> 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/can-kao/json-rpc.md).

# JSON-RPC 支持

Rome EVM 端点支持的以太坊 JSON-RPC 方法，以及 Rome 特有的行为——适用于 Foundry、Hardhat、ethers、viem 和 MetaMask。

Rome 的 EVM 端点使用标准的 Ethereum JSON-RPC。Foundry、Hardhat、ethers、viem 和 MetaMask 在 Rome 上的使用方式与在任何 EVM 链上一样。此页面列出了受支持的内容，以及少数值得了解的 Rome 特有行为。

## 支持的方法

**核心（状态与执行）：** `eth_chainId`, `eth_blockNumber`, `eth_getBalance`, `eth_getCode`, `eth_getStorageAt`, `eth_getTransactionCount`, `eth_call`, `eth_estimateGas`, `eth_gasPrice`, `eth_maxPriorityFeePerGas`, `eth_feeHistory`.

**区块与交易：** `eth_getBlockByNumber`, `eth_getBlockByHash`, `eth_getBlockReceipts`, `eth_getTransactionByHash`, `eth_getTransactionReceipt`, `eth_sendRawTransaction`，按区块索引/计数的变体。

**日志与过滤器：** `eth_getLogs`, `eth_newFilter`, `eth_newBlockFilter`, `eth_getFilterChanges`, `eth_getFilterLogs`, `eth_uninstallFilter`.

**WebSocket 订阅：** `eth_subscribe` / `eth_unsubscribe` (`newHeads`, `logs`）。请参阅 [WebSocket 订阅](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/websocket-subscriptions.md).

**网络 / web3：** `net_version`, `net_listening`, `net_peerCount`, `web3_clientVersion`.

**简单的自省方法：** `rpc_modules` （列出 `debug`, `eth`, `net`, `rome`, `rpc`, `txpool`, `web3`), `eth_syncing` （始终 `false`), `eth_accounts` （始终为空列表）， `eth_getUncleCountByBlockNumber`, `eth_getUncleCountByBlockHash`, `eth_getUncleByBlockNumberAndIndex` 和 `eth_getUncleByBlockHashAndIndex` （没有叔块，因此计数为 `0x0` 并且查询返回 `null`), `eth_newPendingTransactionFilter` （已接受，但由于没有公共 mempool，因此它永远不会返回哈希），以及 `txpool_status`，它始终返回 `{\"pending\":\"0x0\",\"queued\":\"0x0\"}` ，因为没有公共 mempool。

**追踪：** `debug_traceRomeTransaction` 接收一个交易哈希，并返回将多个调用打包为一个批次的交易的逐子调用和逐 CPI 分解。普通交易返回 `null`，未知或尚未建立索引的哈希也是如此。

### 不支持

`debug_traceTransaction` / `trace_*` （以太坊风格的交易追踪；它们返回 `-32601`), `eth_getProof`, `eth_createAccessList`, `eth_blobBaseFee` （没有 blob 交易），以及 `txpool_*` 方法，除了 `txpool_status` （没有公共 mempool）。 `newPendingTransactions` 订阅会被接受，但永远不会发出事件。

## Rome 扩展方法

除标准 Ethereum RPC 外，代理还提供 `rome_*` 方法：

| 方法                                | 用途                                                                                                |
| --------------------------------- | ------------------------------------------------------------------------------------------------- |
| `rome_emulateTx`                  | 在链下模拟一笔交易（返回 Solana 执行结果）                                                                         |
| `rome_emulateTxWithPayer`         | 针对指定 payer 进行模拟                                                                                   |
| `rome_emulateCallAccounts`        | 模拟并返回某次调用所触及的 Solana 账户                                                                           |
| `rome_emulateRegRollup`           | 模拟一次 rollup 注册                                                                                    |
| `rome_getResources`               | 报告代理资源池状态（payer、holder）                                                                           |
| `rome_mintId`                     | 解析 ERC-20 包装器背后的 SPL mint                                                                         |
| `rome_buildInfo`                  | 代理构建信息 + 链上程序信息                                                                                   |
| `rome_isCompatible`               | 检查代理/程序兼容性                                                                                        |
| `rome_solanaTxForEvmTx`           | 获取某个 EVM 交易哈希对应的 Solana 交易                                                                        |
| `rome_sendUnsignedTransaction`    | 提交一笔未签名交易（合成发送者流程）                                                                                |
| `rome_composeUnsignedAtomicV1`    | 为一个未签名的 EIP-1559 主体，使用 Solana 钱包的 Ed25519 签名组装一笔 Solana v1 交易；钱包完成签名，应用负责广播。如果该调用无法装入一笔原子交易，则会拒绝。 |
| `rome_composeUnsignedIterativeV1` | 相同，但返回每一段（如果能装入则为原子交易，否则返回迭代分段）；钱包对每一段签名并随之提交。 `rome_submitSignedV1Plan`                          |
| `rome_submitSignedV1Plan`         | 广播一个已签名的计划（最多 64 段）；代理仅负责传输，钱包仍作为费用支付方。                                                           |
| `rome_relayUnsignedV1`            | 一次钱包签名，代理的 payer 驱动各段执行；合成账户支付 Rome gas（请先用 `rome_composeExternalDepositV1`）。返回 EVM 交易哈希          |
| `rome_composeExternalDepositV1`   | 一笔由钱包签名的交易，将钱包中的代币记入合成账户的原生 gas 余额                                                                |

## Rome 特有行为

### Gas 源自 Solana —— 请估算，不要硬编码

Rome 以 Solana compute unit 计量执行，并将其呈现为 EVM gas。一次写操作的大部分成本来自创建 Solana 账户：从未使用过的接收方、新的代币账户、已部署的合约。这些账户都会计入估算。实际影响如下：

* **使用 `eth_estimateGas`，并且永远不要硬编码 `21000`.** 标准工具（`forge create`, `cast`、Hardhat、ethers、viem、MetaMask）已经会调用它并得到可用值。对于会触及 Solana 程序的调用，请添加余量（SDK 的 `submitRomeTx` 会按 1.3 倍加垫），并在估算本身回退时设置 gas 上限。硬编码的 `21000` 上限会在写操作需要创建账户时失效，例如向一个从未使用过的地址转账。
* **Rome 仅按实际使用的 gas 计费。** 在以下测量中，实际使用的 gas 从未超过估算值，因此估算高于实际工作量时，不会向你收取差额。
* **保留工具添加的余量。** 状态可能在估算与交易落地之间发生变化，而会产生 Solana CPI 的调用，其估算值可能偏低。SDK 的 `submitRomeTx` 会将估算值按 1.3 倍作为余量加垫。

在 Hadrian 上测得，当时 gas 价格约为 10.4 gwei：

| 写入                                   | `eth_estimateGas` | 使用的 gas   |
| ------------------------------------ | ----------------- | --------- |
| 向从未使用过的地址进行原生代币转账                    | 1,086,961         | 1,086,961 |
| 向已存在的地址进行原生代币转账                      | 21,000            | 10,001    |
| 向从未使用过的地址转移 wUSDC                    | 2,544,921         | 2,544,921 |
| 将 gas 包装为 wUSDC（`withdraw_to_ata`)   | 21,000            | 10,001    |
| 包装器授权（`approve_spl` 在 Helper 预编译合约上） | 21,000            | 10,001    |
| 部署一个 10 字节合约                         | 1,147,921         | 1,147,921 |

这些只是单条链上的单次测量，不是上限。数值取决于某次调用需要创建哪些账户，因此请为每次写操作单独估算，而不要照搬这些数字。

### `forge script --broadcast` 需要 `--skip-simulation`

`forge script` 会根据 **本地** 模拟设置其广播 gas 上限，这对 Rome 的 gas 模型来说会配额不足。请添加 `--skip-simulation` ，这样 Foundry 会改用链上的 `eth_estimateGas` 而是：

```bash
forge script script/Deploy.s.sol:Deploy \\
  --rpc-url <RPC> --private-key $PRIVATE_KEY --broadcast --skip-simulation
```

`forge create`, `cast send`和 Hardhat 不受影响——它们本来就会在链上估算。

### `eth_getLogs` 查询范围有上限（约 12,000 个区块）

与 Infura、Alchemy 及其他生产级 RPC 一样， `eth_getLogs` 会拒绝过宽的区块范围（错误 `-32005`）。请限制你的查询范围：

```javascript
const latest = await provider.getBlockNumber();
const logs = await contract.queryFilter(filter, latest - 5000, latest);
```

一个 `queryFilter` 在没有范围参数时会扫描全部历史记录，并会超出上限——请显式传入 `fromBlock`/`toBlock`。基于收据的事件断言（例如等待交易并读取其日志）不受影响。

### 费用

`eth_gasPrice` 返回真实的、由预言机导出的价格；钱包（包括 MetaMask）会使用它并显示正确的费用。提交的 fee 字段会被宽松接受——无论是 legacy 还是 EIP-1559 交易，使用标准工具的默认值都能正常落地。


---

# 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/can-kao/json-rpc.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.
