> 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/zh/chan-pin/rome-sdk.md).

# Rome SDK

用于从 EVM 合约调用 Solana 程序的类型化 Solidity 接口，以及 Rome 链下服务背后的 Rust SDK。

Rome SDK 提供类型化的 Solidity 接口，使 EVM 智能合约能够与 Solana 程序交互。它是用于在 Rome 上构建跨运行时应用的开发者工具包。

## SDK

Rome 为三类用户提供 SDK——应用构建者（TypeScript）、合约开发者（Solidity），以及在 Rome 上运行自有服务的团队（Rust）。

### TypeScript SDK（`@rome-protocol/sdk`)

**面向 dApp 和前端开发者** ——大多数应用构建者首先使用的 SDK。 [`@rome-protocol/sdk`](https://github.com/rome-protocol/rome-sdk-ts) 封装 Rome 写入路径，使 Web 应用能够正确提交 Rome 交易： `submitRomeTx` （正确的写入路径以及 gas/手续费处理）、PDA / ATA 推导、CPI `invoke` / `invoke_signed` 编码器、预编译绑定，以及一个 `/bridge` 子路径。优先通过仓库安装（npm 发布待定）：

```bash
npm install github:rome-protocol/rome-sdk-ts#v0.4.0
```

```typescript
import { submitRomeTx } from '@rome-protocol/sdk';
// 通过正确的写入路径提交任何 Rome EVM 写操作（处理 gas/手续费编码）。
```

公开的 [rome-dex](https://github.com/rome-protocol/rome-dex) 该应用只使用了 SDK 的少量辅助工具（PDA 和代币账户推导、CPI `invoke` 编码器以及 1.3 倍 gas 预留），并且 [cardo](https://github.com/rome-protocol/cardo) 不依赖它。两者都不调用 `submitRomeTx` 或 `submitRomeTxV1`，因此请阅读它们以了解应用如何调用 CPI 预编译，而不是了解 SDK 的写入路径。

**双通道，一个 SDK。** `submitRomeTx` 是 EVM 通道（MetaMask）。对于 **Solana 通道** ——由 Solana 钱包驱动你的 EVM 应用—— `submitRomeTxV1` 其工作方式与之对应：代理为该调用组装一笔 Solana v1 交易，钱包使用同一密钥签名两次（先签一条可读的授权消息，再签交易），Rome 将该调用作为来自用户派生身份的 EVM 交易执行，不需要 EVM 密钥。若某次调用无法放入一笔交易，则代理会使用相同的授权签名进行转发，且 `fundSyntheticGas` 为转发调用所消耗的原生 gas 进行补充。发生回退的转发调用会以 `receipt.status === "0x0"` 而不是抛出异常，因此请检查它； [转发调用和长调用](/zh/kai-fa-zhe-zhi-nan/call-evm-from-solana.md#relayed-calls-and-long-calls) 部分包含 gas 规则和限制。价值通过以下方式进出： `buildFundLeg` / `buildSweepLeg` 作为 ERC-20 包装器（例如 `wUSDC`），而不是原生 `msg.value` ——合成发送方在静态状态下不持有任何资产——首次创建的合成账户会被显式地一次性配置，使用 `buildCreatePdaCall`。较早的 `submitRomeTxSolanaLane`，它在客户端构建传统 Solana 交易，仍然保留在 SDK 中。请参见 [构建双通道应用](/zh/kai-fa-zhe-zhi-nan/dual-lane-app.md) 和 [从 Solana 调用 EVM](/zh/kai-fa-zhe-zhi-nan/call-evm-from-solana.md).

### Solidity SDK（`@rome-protocol/rome-solidity`)

**面向 Solidity 开发者。** 提供预编译接口、ERC-20/SPL 包装器、PDA 推导以及 CPI 工具。npm 发布待定；目前你可以从公开的 [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) 仓库（git 依赖或复制文件）中使用这些内容。

```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";
```

### Rust SDK（`rome-sdk`)

**面向在 Rome 上运行自有服务的团队。** 一个 Rust 工作区，负责交易组装、Solana 交互、gas 定价和区块索引。Proxy 和 Hercules 均构建于此。源代码位于 [`rome-protocol/rome-sdk`](https://github.com/rome-protocol/rome-sdk)。它发送 Solana v1 交易（4 KB，最多 64 个账户）。

**构建它。** 该工作区要求以下仓库 [`rome-sdk`](https://github.com/rome-protocol/rome-sdk), [`rome-evm`](https://github.com/rome-protocol/rome-evm) 和 [`mollusk`](https://github.com/rome-protocol/mollusk) 并排克隆，因为它通过相对路径依赖另外两个仓库。这也就是为什么从其他项目中使用它的受支持方式是路径依赖，而不是普通的 git 依赖。首次构建需要 Rust 1.85 或更高版本以及网络访问。 `rome-evm` 没有默认的网络功能，因此任何会编译它的构建都需要且仅需要以下之一： `ci`, `testnet` 或 `mainnet`； `ci` 用于本地工作，例如 `cargo test -p rome-sdk --features ci`。仓库 README 中包含完整步骤和功能表。

**许可证。** Rust SDK 为源码可见，而非开源：其版权全部保留，仅可用于个人非商业用途。商业用途需要获得 Rome Protocol 的书面许可；仓库中的 `LICENSE` 说明了如何申请。

## Solidity SDK：包含内容

### 预编译接口

将接口绑定到其预编译地址：

```solidity
ISystemProgram          constant System   = ISystemProgram(0xFF00000000000000000000000000000000000007);
ICrossProgramInvocation constant Cpi      = ICrossProgramInvocation(0xFF00000000000000000000000000000000000008);
IHelperProgram          constant Helper   = IHelperProgram(0xFF00000000000000000000000000000000000009);
IWithdraw               constant Withdraw = IWithdraw(0x4200000000000000000000000000000000000016);
// Cached track: ISplCached 0xff…05, IAssociatedSplCached 0xff…06, ISystemCached 0xff…04, IWithdrawCached 0xff…0b
```

### SPL 代币操作

使用 `IHelperProgram` (`0xff…09`）用于由用户 PDA 签名的 SPL 原语：

```solidity
// 为某个铸币创建调用者的 ATA
Helper.create_ata(user, mint);

// 从调用者的 PDA 转移 SPL
Helper.transfer_spl(to, tokens, mint);
```

在缓存路径上，对应操作位于 `ISplCached` (`0xff…05`）以及 `IAssociatedSplCached` (`0xff…06`）。请参见 `interface.sol` 以了解所有重载；合约应始终一致地使用同一路径。

### PDA 推导

```solidity
// 推导用户的 Solana PDA
bytes32 userPda = RomeEVMAccount.pda(msg.sender);

// 使用盐值推导 PDA（用于为每个用户创建多个 PDA）
bytes32 pda = RomeEVMAccount.pda_with_salt(msg.sender, salt);

// 查找任意 PDA
(bytes32 pda, uint8 bump) = SystemProgram.find_program_address(programId, seeds);
```

### 跨程序调用

```solidity
// 调用任意 Solana 程序
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);

// 使用 PDA 签名调用
CpiProgram.invoke_signed(programId, accounts, data, seeds);

// 读取账户数据
(uint64 lamports, bytes32 owner, bool isSigner, bool isWritable, bool executable, bytes memory data)
    = CpiProgram.account_info(pubkey);
```

### 基于 SPL 代币的 ERC-20

```solidity
// 为任意 SPL 铸币部署包装器
ERC20SPLFactory factory = ERC20SPLFactory(FACTORY_ADDRESS);
address wrapper = factory.add_spl_token_with_metadata(splMint);

// 将包装器作为标准 ERC-20 使用
SPL_ERC20 token = SPL_ERC20(wrapper);
token.transfer(recipient, amount);
uint256 balance = token.balanceOf(user);
```

### Borsh 反序列化

```solidity
import {Convert} from "@rome-protocol/rome-solidity/contracts/convert.sol";

// 解析 Solana 账户数据（小端 Borsh 格式）
(uint64 value, uint256 newOffset) = Convert.read_u64le(data, offset);
(bytes32 pubkey, uint256 newOffset2) = Convert.read_bytes32(data, offset);
```

### Metaplex 元数据

```solidity
import {MplTokenMetadataLib} from "@rome-protocol/rome-solidity/contracts/mpl_token_metadata/lib.sol";

// 从 Metaplex 加载代币元数据
MplTokenMetadataLib.Metadata memory meta = MplTokenMetadataLib.load_metadata(
    mintPubkey, mplProgramId, cpiAddress
);
string memory name = meta.name;
string memory symbol = meta.symbol;
```

## Rust SDK：架构

Rust SDK 是一个 Cargo 工作区。其核心 crate 包括：

| crate               | 用途                                                                   |
| ------------------- | -------------------------------------------------------------------- |
| `rome-sdk`          | 核心 API： `Rome` 结构体、配置、交易类型（RheaTx、RemusTx、RomulusTx）                 |
| `rome-evm-client`   | EVM rollup 客户端、TxBuilder、ResourceFactory、模拟器集成                       |
| `rome-solana`       | Solana tower、RPC 客户端、交易批处理与跟踪                                        |
| `rome-utils`        | RLP、十六进制、JSON-RPC、认证工具                                               |
| `rome-obs`          | OpenTelemetry 可观测性（链路追踪、指标、日志）                                       |
| `rome-meteora`      | 用于 gas 定价的 Meteora DAMM v1 和 v2 池读取器                                 |
| `rome-meta-hook`    | Meta-Hook Router 程序客户端：Token-2022 transfer-hook 配置、额外账户解析、带计算预算估算的转账 |
| `rome-jito-bundler` | 用于原子性多交易提交的 Jito bundle 构建器                                          |

### 交易类型

```rust
// 单笔 rollup 交易
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?;

// 跨 rollup 原子交易
let remus = RemusTx::new(vec![tx1, tx2]);
let mut tx = rome.compose_cross_rollup_tx(remus).await?;

// 跨链原子交易（EVM + Solana）
let romulus = RomulusTx::new(eth_txs, sol_ixs);
let mut tx = rome.compose_cross_chain_tx(romulus, signers).await?;
```

### 资源池化

该 SDK 会池化 Solana 密钥对（payer）和 holder 账户索引，以便并行提交交易：

```rust
let resource = resource_factory.get().await?;
let payer = resource.payer();       // Solana keypair
let holder = resource.holder();     // Holder account index
// 在 Drop 时自动将资源归还到池中
```

## SDK 路线图

### 已构建并可用

* SPL 代币包装器和预编译接口
* 通过 CPI 的 Meteora DAMM v1 交换
* Oracle Gateway V1 + V2（Pyth Pull、Switchboard V3）
* System Program 辅助工具、Borsh 反序列化
* ERC20SPL 工厂 + 桥接合约

## 接下来

* [部署 Solidity](/zh/kai-fa-zhe-zhi-nan/deploy-solidity.md) ——使用该 SDK 部署你的第一个合约
* [从 EVM 调用 Solana](/zh/kai-fa-zhe-zhi-nan/call-solana-from-evm.md) ——使用 CPI 与 Solana 程序交互
* [合约地址](/zh/can-kao/contract-addresses.md) ——已部署的 SDK 合约地址


---

# 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/zh/chan-pin/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.