@solana/web3-compat

@solana/web3-compat는 오래 사용된 @solana/web3.js 앱과 새로운 Kit 런타임 사이의 브리지입니다. import를 교체하고, 앱이 이미 알고 있는 인터페이스를 유지하며, 모든 헬퍼나 인스트럭션을 다시 작성하지 않고도 Kit 기능을 점진적으로 도입할 수 있습니다.

Kit 피어와 함께 설치

$ 
npm install @solana/web3-compat @solana/kit @solana/clientCopy

호환성 레이어는 클래식 Web3 타입(Connection, PublicKey, Transaction 등)을 재내보내며 내부적으로 Kit 네트워킹과 코덱에 위임합니다. 기존 RPC 엔드포인트를 유지하면서도 Kit의 더욱 예측 가능한 블록해시 처리 및 지갑 추상화의 이점을 누릴 수 있습니다.

import 교체 (다른 코드 변경 없음)

대부분의 프로젝트는 import 소스를 전환하여 파일별로 마이그레이션할 수 있습니다. 명명된 import와 네임스페이스 import 모두 기존 패키지를 미러링합니다.

import { Connection, PublicKey } from "@solana/web3.js";

import { Connection, PublicKey } from "@solana/web3-compat";

CommonJS도 작동합니다:

const solanaWeb3 = require("@solana/web3-compat");
const connection = new solanaWeb3.Connection("https://api.devnet.solana.com");

내부적으로 Connection는 읽기와 쓰기를 @solana/client를 통해 전달하므로, sendAndConfirmTransaction, simulateTransaction, getProgramAccounts와 같은 헬퍼가 비즈니스 로직을 건드리지 않고도 새로운 런타임의 이점을 누릴 수 있습니다.

Kit 타입이 필요할 때 브리지 헬퍼 사용

Kit을 직접 도입할 때(@solana/client 또는 @solana/react-hooks를 사용하는 새 컴포넌트에서), compat 패키지에 포함된 브리지 헬퍼를 사용하여 두 생태계 간에 변환할 수 있습니다:

import {
  PublicKey,
  toAddress,
  toPublicKey,
  toWeb3Instruction,
  toKitSigner
} from "@solana/web3-compat";

const legacyKey = new PublicKey("11111111111111111111111111111111");
const kitAddress = toAddress(legacyKey);
const backToWeb3 = toPublicKey(kitAddress);

런타임 혼합이 안전해집니다: 새로운 훅이 Kit 인스트럭션을 생성하면, toWeb3Instruction가 전체 프로젝트가 이전될 때까지 레거시 플로우를 위해 래핑합니다.

점진적 마이그레이션 패턴

• 점진적 롤아웃: 한 번에 하나의 기능 폴더를 업데이트합니다. 모듈이 더 이상 compat가 필요하지 않으면 트리의 나머지 부분을 건드리지 않고 @solana/client/@solana/react-hooks를 직접 가리키도록 합니다.
• 공유 RPC 튜닝: compat는 Kit 연결에 의존하므로 커밋먼트 레벨, 우선순위 수수료 또는 RPC URL 조정이 단일 구성 객체를 통해 흐릅니다.
• SPL + 트랜잭션 헬퍼: 레거시 트랜잭션 빌더를 당분간 유지하되, 준비가 되면 client.helpers.transaction.prepare를 사용하세요. Compat는 여전히 동일한 서명된 페이로드를 제출할 수 있습니다.
• 테스트: 공개 인터페이스가 동일하게 유지되므로 기존 Web3 모의 객체를 재사용하되, 테스트 중에는 더 풍부한 시뮬레이션을 위해 Kit 클라이언트를 스텁할 수 있습니다.

Phase 0에 포함된 내용

• getLatestBlockhash, getBalance, getAccountInfo, getProgramAccounts, getSignatureStatuses, sendRawTransaction, confirmTransaction, simulateTransaction가 포함된 Connection.
• LAMPORTS_PER_SOL, sendAndConfirmTransaction, compileFromCompat와 같은 유틸리티.
• SystemProgram.transfer 및 모든 핵심 Web3 프리미티브 (Keypair, Transaction, VersionedTransaction, TransactionInstruction).

동일한 Kit 런타임 위에 새로운 UI를 구축할 준비가 되면 이 가이드를 @solana/client 개요 및 @solana/react-hooks 가이드와 함께 참조하세요.