> 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/fee 处理）、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/fee 编码）。
```

公开的 [rome-dex](https://github.com/rome-protocol/rome-dex) app 仅使用了 SDK 的少量辅助功能（PDA 和 token 账户推导、CPI `invoke` 编码器以及 1.3x 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"` 而不是抛出异常来结束，因此请检查它； [转发调用与长调用](https://docs.rome.builders/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 中。请参阅 [构建双通道应用](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/dual-lane-app.md) 和 [从 Solana 调用 EVM](https://docs.rome.builders/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 workspace，负责交易组装、Solana 交互、gas 定价和区块索引。Proxy 和 Hercules 都建立在它之上。源代码位于 [`rome-protocol/rome-sdk`](https://github.com/rome-protocol/rome-sdk)。它发送 Solana v1 交易（4 KB，最多 64 个账户）。

**构建它。** 该 workspace 期望这些仓库 [`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) 并排克隆，因为它通过相对路径依赖另外两个仓库。这也是为什么从其他项目中使用它的推荐方式是 path 依赖，而不是普通 git 依赖。首次构建需要 Rust 1.85 或更高版本，以及网络访问。 `rome-evm` 没有默认的网络功能，因此任何编译它的构建都需要以下选项之一： `ci`, `测试网` 或 `主网`；请使用 `ci` 用于本地工作，例如 `cargo test -p rome-sdk --features ci`。仓库 README 中有完整步骤和功能表。

**许可证。** Rust SDK 采用源代码可用（source-available）而非开源：保留所有权利，仅可用于个人、非商业用途。商业用途需要 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);
// 缓存通道：ISplCached 0xff…05，IAssociatedSplCached 0xff…06，ISystemCached 0xff…04，IWithdrawCached 0xff…0b
```

### SPL 代币操作

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

```solidity
// 为某个 mint 创建调用者的 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);

// 使用 salt 推导 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 mint 部署封装器
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 workspace。其核心 crate：

| Crate               | 用途                                                                   |
| ------------------- | -------------------------------------------------------------------- |
| `rome-sdk`          | 核心 API： `Rome` 结构体、配置，以及三种交易类型（`RheaTx`, `RemusTx`, `RomulusTx`)     |
| `rome-evm-client`   | 适用于 Rome 链的 EVM 客户端、TxBuilder、ResourceFactory、模拟器集成                  |
| `rome-solana`       | Solana tower、RPC 客户端、交易批处理与跟踪                                        |
| `rome-utils`        | RLP、hex、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
// 在一条 Rome 链上的一笔 EVM 交易
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?;

// 在不同 Rome 链上的多笔 EVM 交易，以一笔 Solana 交易实现原子性
let remus = RemusTx::new(vec![tx1, tx2]);
let mut tx = rome.compose_cross_rollup_tx(remus).await?;

// EVM 交易加原生 Solana 指令，以一笔 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 密钥对
let holder = resource.holder();     // Holder 账户索引
// 资源会在 Drop 时自动归还到池中
```

## SDK 路线图

### 已构建并可用

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

## 下一步

* [部署 Solidity](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/deploy-solidity.md) — 使用该 SDK 部署你的第一个合约
* [从 EVM 调用 Solana](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/call-solana-from-evm.md) — 使用 CPI 与 Solana 程序交互
* [合约地址](https://docs.rome.builders/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.
