> 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.

Rome SDK cung cấp các giao diện Solidity có kiểu cho việc tương tác với các chương trình Solana từ các smart contract EVM. Đây là bộ công cụ dành cho nhà phát triển để xây dựng ứng dụng chạy xuyên nhiều runtime trên Rome.

## SDK

Rome có các SDK cho ba nhóm đối tượng — nhà 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 nhà xây dựng ứng dụng bắt đầu với. [`@rome-protocol/sdk`](https://github.com/rome-protocol/rome-sdk-ts) bọc đường dẫn ghi của Rome để một ứng dụng web gửi giao dịch Rome đúng cách: `submitRomeTx` (đường dẫn 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 theo repo là chính (chưa phát hành 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 dẫn ghi (xử lý mã hóa gas/phí).
```

Ứng dụng công khai [rome-dex](https://github.com/rome-protocol/rome-dex) chỉ dùng một vài helper của SDK (suy diễn PDA và tài khoản token, trình mã hóa CPI `invoke` và mức đệm gas 1.3x), và [cardo](https://github.com/rome-protocol/cardo) không phụ thuộc vào nó. Cả hai đều 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 cho đường dẫn 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` nó phản chiếu lại: proxy tạo một giao dịch Solana v1 cho lệnh 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 đến giao dịch), và Rome chạy lệnh gọi như một giao dịch EVM từ danh tính suy diễn của người dùng, không cần khóa EVM. Một lệnh gọi không vừa trong một giao dịch sẽ được proxy chuyển tiếp với cùng chữ ký ủy quyền, và `fundSyntheticGas` bù thêm lượng gas gốc mà một lệnh gọi được chuyển tiếp tiêu tốn. Một lệnh gọi được chuyển tiếp bị revert sẽ trả về `receipt.status === "0x0"` thay vì ném lỗi, vì vậy hãy kiểm tra nó; phần [các lệnh gọi được chuyển tiếp và các lệnh gọi dài](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-evm-from-solana.md#relayed-calls-and-long-calls) 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 bọc ERC-20 (ví dụ `wUSDC`), chứ không phải native `msg.value` — tài khoản gửi tổng hợp không giữ gì khi ở trạng thái nghỉ — và một tài khoản tổng hợp lần đầu sẽ được cấp phát một lần, rõ ràng, với `buildCreatePdaCall`. Phần `submitRomeTxSolanaLane`trước đây, vốn xây dựng một giao dịch Solana kiểu cũ ở phía client, vẫn còn trong SDK. Xem [Xây dựng một ứng dụng hai làn](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/dual-lane-app.md) và [Gọi EVM từ Solana](https://docs.rome.builders/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, các bọc ERC-20/SPL, suy diễn PDA, và các tiện ích CPI. Việc phát hành npm đang chờ; hiện tại bạn dùng chúng từ [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) repo công khai (phụ thuộc git hoặc các file được 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 Solana, định giá gas, và lập chỉ mục block. Proxy và Hercules được xây dựng trê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 yêu cầu các repository [`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 song song, vì nó phụ thuộc vào hai repo còn lại qua đường dẫn tương đối. Đó cũng là lý do cách được hỗ trợ để dùng nó từ một project khác là dependency theo đường dẫn, không phải dependency git thuần túy. Bạn cần Rust 1.85 trở lên và có kết nối mạng cho lần build đầu tiên. `rome-evm` không có feature mạng mặc định, nên 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 repository có đầy đủ các bước và bảng tính năng.

**Giấy phép.** SDK Rust là có sẵn mã nguồn, không phải mã nguồn mở: mọi quyền được bảo lưu và có thể được 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; file `LICENSE` của repository nêu cách yêu cầu.

## SDK Solidity: Bao gồm những gì

### Giao diện Precompile

Ràng buộc một interface với đị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 được cache: ISplCached 0xff…05, IAssociatedSplCached 0xff…06, ISystemCached 0xff…04, IWithdrawCached 0xff…0b
```

### Các thao tác SPL Token

Dùng `IHelperProgram` (`0xff…09`) cho các primitive SPL được ký bởi 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 được cache, các thao tác tương đương nằm trên `ISplCached` (`0xff…05`và `IAssociatedSplCached` (`0xff…06`). Xem `interface.sol` để biết tất cả các overload; một contract 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);
```

### 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 các token SPL

```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, ba loại giao dịch (`RheaTx`, `RemusTx`, `RomulusTx`)                                                            |
| `rome-evm-client`   | Client EVM cho các chain Rome, TxBuilder, ResourceFactory, tích hợp emulator                                                                        |
| `rome-solana`       | Solana tower, client RPC, gom và theo dõi giao dịch                                                                                                 |
| `rome-utils`        | RLP, hex, JSON-RPC, các tiện ích xác thực                                                                                                           |
| `rome-obs`          | khả năng quan sát OpenTelemetry (trace, metrics, log)                                                                                               |
| `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 lượng compute-budget |
| `rome-jito-bundler` | trình tạo bundle Jito cho việc gửi nguyên tử nhiều giao dịch                                                                                        |

### Các loại giao dịch

```rust
// Một giao dịch EVM trên một chain Rome
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?;

// Nhiều giao dịch EVM trên các chain Rome khác nhau, nguyên tử trong một giao dịch Solana
let remus = RemusTx::new(vec![tx1, tx2]);
let mut tx = rome.compose_cross_rollup_tx(remus).await?;

// Giao dịch EVM cộng với lệnh Solana gốc, nguyên tử trong một giao dịch 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ỉ số 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();       // Keypair Solana
let holder = resource.holder();     // Chỉ số tài khoản holder
// Tài nguyên tự động được trả lại pool khi Drop
```

## Lộ trình SDK

### Đã xây dựng và hoạt động

* Wrapper SPL Token và giao diện precompile
* Hoán đổi Meteora DAMM v1 qua CPI
* Oracle Gateway V1 + V2 (Pyth Pull, Switchboard V3)
* Helper của System Program, giải mã Borsh
* ERC20SPL Factory + các hợp đồng bridge

## Tiếp theo là gì

* [Triển khai Solidity](https://docs.rome.builders/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](https://docs.rome.builders/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](https://docs.rome.builders/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=<question>&goal=<user_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.
