@solana/web3-compat

@solana/web3-compat là cầu nối giữa các ứng dụng @solana/web3.js tồn tại lâu dài và runtime Kit mới hơn. Thay đổi import, giữ nguyên giao diện mà ứng dụng của bạn đã quen thuộc, và dần dần áp dụng các tính năng Kit mà không cần viết lại mọi helper hoặc instruction cùng một lúc.

Cài đặt với các peer Kit

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

Lớp tương thích re-export các kiểu Web3 cổ điển (Connection, PublicKey, Transaction, v.v.) trong khi nội bộ ủy quyền cho networking Kit và codec. Giữ nguyên các RPC endpoint hiện có của bạn, nhưng hưởng lợi từ xử lý blockhash dự đoán được hơn và các abstraction ví của Kit.

Thay thế import (không cần thay đổi code khác)

Hầu hết các dự án có thể migrate từng file một bằng cách chuyển đổi nguồn import. Cả import có tên và namespace đều phản ánh package cũ.

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

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

CommonJS cũng hoạt động:

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

Đằng sau hậu trường Connection chuyển tiếp các thao tác đọc và ghi thông qua @solana/client, vì vậy các helper như sendAndConfirmTransaction, simulateTransaction, và getProgramAccounts hưởng lợi từ runtime mới hơn mà không cần chạm vào logic nghiệp vụ của bạn.

Bridge helper khi bạn cần các kiểu Kit

Khi bạn áp dụng Kit trực tiếp (có thể trong các component mới sử dụng @solana/client hoặc @solana/react-hooks), hãy sử dụng các bridge helper được cung cấp trong package compat để chuyển đổi giữa hai hệ sinh thái:

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

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

Việc kết hợp các runtime trở nên an toàn: các hook mới hơn có thể phát ra các instruction Kit, sau đó toWeb3Instruction sẽ bọc chúng cho các luồng cũ cho đến khi toàn bộ dự án chuyển đổi hoàn toàn.

Các mẫu migration dần dần

• Triển khai tăng dần: Cập nhật từng thư mục tính năng một. Khi một module không còn cần compat, hãy trỏ nó trực tiếp đến @solana/client/@solana/react-hooks mà không cần chạm vào phần còn lại của cây.
• Điều chỉnh RPC chung: Vì compat dựa vào kết nối Kit, việc điều chỉnh mức cam kết, phí ưu tiên hoặc URL RPC sẽ được thực hiện thông qua một đối tượng cấu hình duy nhất.
• Trợ giúp SPL + giao dịch: Giữ lại các trình xây dựng giao dịch cũ hiện tại, nhưng hãy sử dụng client.helpers.transaction.prepare khi bạn đã sẵn sàng. Compat vẫn có thể gửi các payload đã ký tương tự.
• Kiểm thử: Tái sử dụng các mock Web3 hiện có vì bề mặt công khai vẫn giữ nguyên, tuy nhiên trong quá trình kiểm thử bạn có thể stub client Kit để mô phỏng phong phú hơn.

Những gì được phát hành trong giai đoạn 0

• Connection với getLatestBlockhash, getBalance, getAccountInfo, getProgramAccounts, getSignatureStatuses, sendRawTransaction, confirmTransaction, và simulateTransaction.
• Các tiện ích như LAMPORTS_PER_SOL, sendAndConfirmTransaction, và compileFromCompat.
• SystemProgram.transfer cùng với tất cả các primitive Web3 cốt lõi (Keypair, Transaction, VersionedTransaction, TransactionInstruction).

Kết hợp hướng dẫn này với tổng quan @solana/client và hướng dẫn @solana/react-hooks khi bạn sẵn sàng bắt đầu xây dựng UI mới trên cùng runtime Kit.