> For the complete documentation index, see [llms.txt](https://docs.rome.builders/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rome.builders/vi/san-pham/rome-sdk.md). # Rome SDK Các giao diện Solidity được đánh kiểu để gọi chương trình Solana từ các hợp đồng EVM, cùng với SDK Rust đứng sau các dịch vụ ngoài chuỗi của Rome. Bộ SDK Rome cung cấp các giao diện Solidity được đánh kiểu để tương tác với các chương trình Solana từ các hợp đồng thông minh EVM. Đây là bộ công cụ dành cho nhà phát triển để xây dựng ứng dụng chạy đa runtime trên Rome. ## Các SDK Rome có các SDK cho ba nhóm đối tượng — người xây dựng ứng dụng (TypeScript), nhà phát triển hợp đồng (Solidity), và các đội ngũ vận hành dịch vụ riêng của họ trên Rome (Rust). ### SDK TypeScript (`@rome-protocol/sdk`) **Dành cho nhà phát triển dapp và frontend** — SDK mà hầu hết người xây dựng ứng dụng bắt đầu với. [`@rome-protocol/sdk`](https://github.com/rome-protocol/rome-sdk-ts) bao bọc đường ghi của Rome để một ứng dụng web gửi giao dịch Rome đúng cách: `submitRomeTx` (đường ghi đúng cùng với xử lý gas/phí), suy diễn PDA / ATA, CPI `invoke` / `invoke_signed` bộ mã hóa, liên kết precompile, và một `/bridge` đường con. Cài đặt từ repo là chính (chưa xuất bản npm): ```bash npm install github:rome-protocol/rome-sdk-ts#v0.4.0 ``` ```typescript import { submitRomeTx } from '@rome-protocol/sdk'; // Gửi bất kỳ lệnh ghi EVM nào của Rome qua đúng đường ghi (xử lý mã hóa gas/phí). ``` Bản công khai [rome-dex](https://github.com/rome-protocol/rome-dex) ứng dụng chỉ dùng một vài trợ giúp của SDK (suy diễn PDA và tài khoản token, bộ mã hóa CPI `invoke` và phần đệm gas 1.3x), và [cardo](https://github.com/rome-protocol/cardo) không phụ thuộc vào nó. Cả hai cũng không gọi `submitRomeTx` hoặc `submitRomeTxV1`, vì vậy hãy đọc chúng để biết cách một ứng dụng gọi precompile CPI, chứ không phải đường ghi của SDK. **Cả hai luồng, một SDK.** `submitRomeTx` là luồng EVM (MetaMask). Với luồng **Solana** — một ví Solana điều khiển ứng dụng EVM của bạn — `submitRomeTxV1` phản chiếu nó: proxy ghép thành một giao dịch Solana v1 cho lời gọi, ví ký hai lần bằng cùng một khóa (một thông điệp ủy quyền dễ đọc, rồi giao dịch), và Rome chạy lời gọi như một giao dịch EVM từ danh tính được suy ra của người dùng, không cần khóa EVM. Một lời gọi không khớp trong một giao dịch sẽ được proxy chuyển tiếp với cùng chữ ký ủy quyền, và `fundSyntheticGas` nạp thêm native gas mà một lời gọi được chuyển tiếp tiêu thụ. Một lời gọi được chuyển tiếp bị hoàn nguyên sẽ trả về với `receipt.status === "0x0"` thay vì ném lỗi, vì vậy hãy kiểm tra nó; [các lời gọi được chuyển tiếp và các lời gọi dài](/vi/huong-dan-cho-nha-phat-trien/call-evm-from-solana.md#relayed-calls-and-long-calls) phần này có quy tắc gas và các giới hạn. Giá trị ra vào thông qua `buildFundLeg` / `buildSweepLeg` như một lớp bọc ERC-20 (ví dụ `wUSDC`), chứ không phải native `msg.value` — bộ gửi tổng hợp không giữ gì cả khi ở trạng thái nghỉ — và một synthetic lần đầu được cấp phát một lần, một cách rõ ràng, với `buildCreatePdaCall`. Cách trước đó `submitRomeTxSolanaLane`, vốn tạo một giao dịch Solana kiểu cũ trong client, vẫn còn trong SDK. Xem [Xây dựng một ứng dụng hai làn](/vi/huong-dan-cho-nha-phat-trien/dual-lane-app.md) và [Gọi EVM từ Solana](/vi/huong-dan-cho-nha-phat-trien/call-evm-from-solana.md). ### SDK Solidity (`@rome-protocol/rome-solidity`) **Dành cho nhà phát triển Solidity.** Cung cấp các giao diện precompile, bộ bọc ERC-20/SPL, suy diễn PDA, và các tiện ích CPI. Việc xuất bản npm đang chờ; hiện tại bạn sử dụng chúng từ [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) kho lưu trữ công khai (phụ thuộc git hoặc các tệp sao chép). ```solidity import {ISystemProgram, ICrossProgramInvocation, IHelperProgram, IWithdraw} from "@rome-protocol/rome-solidity/contracts/interface.sol"; import {SPL_ERC20} from "@rome-protocol/rome-solidity/contracts/erc20spl/erc20spl.sol"; import {RomeEVMAccount} from "@rome-protocol/rome-solidity/contracts/rome_evm_account.sol"; ``` ### SDK Rust (`rome-sdk`) **Dành cho các đội ngũ vận hành dịch vụ riêng của họ trên Rome.** Một workspace Rust xử lý việc ghép giao dịch, tương tác với Solana, định giá gas, và lập chỉ mục khối. Proxy và Hercules được xây dựng trên nó. Mã nguồn nằm trong [`rome-protocol/rome-sdk`](https://github.com/rome-protocol/rome-sdk). Nó gửi các giao dịch Solana v1 (4 KB, tối đa 64 tài khoản). **Đang xây dựng nó.** Workspace này yêu cầu các kho lưu trữ [`rome-sdk`](https://github.com/rome-protocol/rome-sdk), [`rome-evm`](https://github.com/rome-protocol/rome-evm) và [`mollusk`](https://github.com/rome-protocol/mollusk) được clone cạnh nhau, vì nó phụ thuộc vào hai kho còn lại theo đường dẫn tương đối. Đó cũng là lý do cách được hỗ trợ để dùng nó từ một dự án khác là phụ thuộc đường dẫn, không phải phụ thuộc git thuần túy. Bạn cần Rust 1.85 trở lên và có quyền truy cập mạng cho lần build đầu tiên. `rome-evm` không có tính năng mạng mặc định, vì vậy bất kỳ bản build nào biên dịch nó đều cần chính xác một trong `ci`, `testnet` hoặc `mainnet`; dùng `ci` cho công việc cục bộ, ví dụ `cargo test -p rome-sdk --features ci`. README của kho chứa có đầy đủ các bước và bảng tính năng. **Giấy phép.** SDK Rust là source-available, không phải mã nguồn mở: mọi quyền được bảo lưu và chỉ được phép dùng cho mục đích cá nhân, phi thương mại. Việc sử dụng thương mại cần có sự cho phép bằng văn bản từ Rome Protocol; kho lưu trữ's `LICENSE` nói cách yêu cầu. ## SDK Solidity: Những gì được bao gồm ### Giao diện Precompile Gắn một interface vào địa chỉ precompile của nó: ```solidity ISystemProgram constant System = ISystemProgram(0xFF00000000000000000000000000000000000007); ICrossProgramInvocation constant Cpi = ICrossProgramInvocation(0xFF00000000000000000000000000000000000008); IHelperProgram constant Helper = IHelperProgram(0xFF00000000000000000000000000000000000009); IWithdraw constant Withdraw = IWithdraw(0x4200000000000000000000000000000000000016); // Track đã cache: ISplCached 0xff…05, IAssociatedSplCached 0xff…06, ISystemCached 0xff…04, IWithdrawCached 0xff…0b ``` ### Thao tác Token SPL Sử dụng `IHelperProgram` (`0xff…09`) cho các primitive SPL ký bằng user-PDA: ```solidity // Tạo ATA của người gọi cho một mint Helper.create_ata(user, mint); // Chuyển SPL từ PDA của người gọi Helper.transfer_spl(to, tokens, mint); ``` Trên track đã cache, các thao tác tương đương nằm trên `ISplCached` (`0xff…05`) và `IAssociatedSplCached` (`0xff…06`). Xem `interface.sol` cho tất cả các overload; một hợp đồng sử dụng nhất quán một track. ### Suy diễn PDA ```solidity // Suy diễn PDA Solana của một người dùng bytes32 userPda = RomeEVMAccount.pda(msg.sender); // Suy diễn PDA với salt (để tạo nhiều PDA cho mỗi người dùng) bytes32 pda = RomeEVMAccount.pda_with_salt(msg.sender, salt); // Tìm PDA tùy ý (bytes32 pda, uint8 bump) = SystemProgram.find_program_address(programId, seeds); ``` ### Lời gọi liên chương trình ```solidity // Gọi bất kỳ chương trình Solana nào ICrossProgramInvocation.AccountMeta[] memory accounts = new ICrossProgramInvocation.AccountMeta[](2); accounts[0] = ICrossProgramInvocation.AccountMeta(signerPda, true, true); accounts[1] = ICrossProgramInvocation.AccountMeta(targetAccount, false, true); CpiProgram.invoke(programId, accounts, instructionData); // Gọi với ký bằng PDA CpiProgram.invoke_signed(programId, accounts, data, seeds); // Đọc dữ liệu tài khoản (uint64 lamports, bytes32 owner, bool isSigner, bool isWritable, bool executable, bytes memory data) = CpiProgram.account_info(pubkey); ``` ### ERC-20 trên nền SPL Token ```solidity // Triển khai wrapper cho bất kỳ mint SPL nào ERC20SPLFactory factory = ERC20SPLFactory(FACTORY_ADDRESS); address wrapper = factory.add_spl_token_with_metadata(splMint); // Dùng wrapper như ERC-20 tiêu chuẩn SPL_ERC20 token = SPL_ERC20(wrapper); token.transfer(recipient, amount); uint256 balance = token.balanceOf(user); ``` ### Giải mã Borsh ```solidity import {Convert} from "@rome-protocol/rome-solidity/contracts/convert.sol"; // Phân tích dữ liệu tài khoản Solana (định dạng Borsh little-endian) (uint64 value, uint256 newOffset) = Convert.read_u64le(data, offset); (bytes32 pubkey, uint256 newOffset2) = Convert.read_bytes32(data, offset); ``` ### Metadata Metaplex ```solidity import {MplTokenMetadataLib} from "@rome-protocol/rome-solidity/contracts/mpl_token_metadata/lib.sol"; // Tải metadata token từ Metaplex MplTokenMetadataLib.Metadata memory meta = MplTokenMetadataLib.load_metadata( mintPubkey, mplProgramId, cpiAddress ); string memory name = meta.name; string memory symbol = meta.symbol; ``` ## SDK Rust: Kiến trúc SDK Rust là một workspace Cargo. Các crate cốt lõi của nó: | Crate | Mục đích | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `rome-sdk` | API cốt lõi: `Rome` struct, config, các kiểu giao dịch (RheaTx, RemusTx, RomulusTx) | | `rome-evm-client` | client rollup EVM, TxBuilder, ResourceFactory, tích hợp emulator | | `rome-solana` | Solana tower, RPC client, ghép lô giao dịch và theo dõi | | `rome-utils` | RLP, hex, JSON-RPC, tiện ích xác thực | | `rome-obs` | quan sát OpenTelemetry (trace, metrics, logs) | | `rome-meteora` | bộ đọc pool Meteora DAMM v1 và v2 cho định giá gas | | `rome-meta-hook` | Client cho chương trình Meta-Hook Router: cấu hình transfer-hook Token-2022, phân giải tài khoản bổ sung, chuyển khoản với ước tính compute-budget | | `rome-jito-bundler` | trình tạo bundle Jito cho việc gửi nhiều giao dịch nguyên tử | ### Các kiểu giao dịch ```rust // Một giao dịch rollup đơn let rhea = RheaTx::new(signed_eth_tx); let mut tx = rome.compose_rollup_tx(rhea).await?; let sig = rome.send_and_confirm(&mut *tx).await?; // Giao dịch nguyên tử xuyên rollup let remus = RemusTx::new(vec![tx1, tx2]); let mut tx = rome.compose_cross_rollup_tx(remus).await?; // Giao dịch nguyên tử xuyên chuỗi (EVM + Solana) let romulus = RomulusTx::new(eth_txs, sol_ixs); let mut tx = rome.compose_cross_chain_tx(romulus, signers).await?; ``` ### Gộp tài nguyên SDK gộp các keypair Solana (payer) và chỉ mục tài khoản holder cho việc gửi giao dịch song song: ```rust let resource = resource_factory.get().await?; let payer = resource.payer(); // Solana keypair let holder = resource.holder(); // Holder account index // Tài nguyên được tự động trả lại pool khi Drop ``` ## Lộ trình SDK ### Đã xây dựng và hoạt động * wrapper token SPL và giao diện precompile * Hoán đổi Meteora DAMM v1 qua CPI * Oracle Gateway V1 + V2 (Pyth Pull, Switchboard V3) * Trợ giúp System Program, giải mã Borsh * ERC20SPL Factory + các hợp đồng bridge ## Tiếp theo là gì * [Triển khai Solidity](/vi/huong-dan-cho-nha-phat-trien/deploy-solidity.md) — triển khai hợp đồng đầu tiên của bạn bằng SDK * [Gọi Solana từ EVM](/vi/huong-dan-cho-nha-phat-trien/call-solana-from-evm.md) — dùng CPI để tương tác với các chương trình Solana * [Địa chỉ Hợp đồng](/vi/tai-lieu-tham-khao/contract-addresses.md) — địa chỉ hợp đồng SDK đã triển khai --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.rome.builders/vi/san-pham/rome-sdk.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.