> 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

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

## SDK

Rome 为三类受众提供 SDK——应用构建者（TypeScript）、合约开发者（Solidity）以及基础设施运维者（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 publish 待定）：

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

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

公开参考应用—— [rome-dex](https://github.com/rome-protocol/rome-dex) 和 [cardo](https://github.com/rome-protocol/cardo) ——都在使用这个 SDK。

**两条通道，一个 SDK。** `submitRomeTx` 是 EVM 通道（MetaMask）。对于 **Solana 通道** ——由 Phantom/Solana 钱包驱动你的 EVM 应用—— `submitRomeTxSolanaLane` 则与之对应：用户签名一笔 Solana 交易，Rome 会将其作为来自其派生身份的 EVM 交易来执行，不需要 EVM 密钥。价值通过 `buildFundLeg` / `buildSweepLeg` 作为 ERC-20 包装器（例如 `wUSDC`），而不是原生 `msg.value` ——合成发送方在静态状态下不持有任何资产——并且首次使用时会自动创建首个合成账户。参见 [构建双通道应用](/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`)

**面向基础设施运维者。** 一个 Rust 工作区，负责交易组装、Solana 交互、gas 定价和区块索引。由 Proxy 和 Hercules 使用。

## 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 工作区。其核心 crate：

| Crate               | 用途                                                      |
| ------------------- | ------------------------------------------------------- |
| `rome-sdk`          | 核心 API： `Rome` struct、配置、交易类型（RheaTx、RemusTx、RomulusTx） |
| `rome-evm-client`   | EVM rollup 客户端、TxBuilder、ResourceFactory、模拟器集成          |
| `rome-solana`       | Solana tower、RPC 客户端、交易批处理与跟踪                           |
| `rome-utils`        | RLP、hex、JSON-RPC、认证工具                                   |
| `rome-obs`          | OpenTelemetry 可观测性（追踪、指标、日志）                            |
| `rome-meteora`      | 用于 gas 定价的 Meteora DEX AMM 池适配器                         |
| `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）和持有者账户索引：

```rust
let resource = resource_factory.get().await?;
let payer = resource.payer();       // Solana 密钥对
let holder = resource.holder();     // 持有者账户索引
// 资源在 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-wen-dang/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rome.builders/zh/chan-pin/rome-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.