> 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/kuai-su-ru-men/architecture.md).

# 架构

Rome 的各个组件如何协同工作——在 Solana 程序内部执行 EVM。

Rome 将 EVM 字节码解释器嵌入到一个 Solana 链上程序中。在 EVM 密钥通道中，用户通过标准的 Ethereum JSON-RPC 将已签名的 EVM 交易发送到 Rome Proxy。代理将其提交到 Solana 上的 Rome EVM 程序。一次 EVM 交易可能需要多笔 Solana 交易，才能将分片写入 holder 账户或执行迭代式执行。在 v1 Solana 密钥通道中，代理会组装该交易。Solana 钱包对其签名，并直接发送到 Solana RPC。不存在需要同步的独立执行层——EVM 状态 *为* Solana 状态。

## 系统概览

<figure><img src="https://4058553919-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-4d7d386c95b500079204f3dea2103d9759c5de8f%2Farchitecture.svg?alt=media" alt="EVM wallet and Solana wallet connected to Rome Proxy with its emulator. The Solana cluster holds the Rome EVM program, per-chain state, external-authority PDA, token accounts, Solana programs and holder accounts. Hercules feeds blocks, receipts and logs back to the proxy."><figcaption></figcaption></figure>

## 组件

### Rome EVM 程序（链上）

Rome 的核心——一个 Solana BPF 程序，包含完整的 EVM 字节码解释器（源自 SputnikVM 的分支）。它：

* 将已签名的 EVM 交易和未签名的 EIP-1559 交易体作为 Solana 指令接收。Solana 密钥可通过 Solana 费用支付者的签名或 Ed25519 验证器指令来授权未签名的交易体
* 在 Solana 运行时中执行 Solidity 字节码
* 将每个 Ethereum 地址（H160）映射到按链划分的余额 PDA，其中包含其 nonce、原生余额和代码。单独的存储 PDA 与该余额 PDA 关联。每个地址还拥有一个用于控制 Solana 调用权限的程序派生地址，称为其 **外部权限 PDA**。该 PDA 被程序中的每条链共享。它拥有该地址的 SPL 代币账户，并对其跨程序调用（CPI）进行签名
* 提供用于调用 Solana 的预编译合约（CPI、System、Helper、Withdraw），同时也提供 Ethereum 预编译合约。缓存家族新增 SystemCached（`0xff…04`）、SplCached（`0xff…05`）、ASplCached（`0xff…06`）和 WithdrawCached（`0xff…0b`）。工厂会在这条缓存路径上部署封装器
* 将 EVM 状态（余额、nonce、代码、存储）存储为 Solana 账户数据
* 一个 Rome EVM 程序可承载多个 chain ID。chain ID 是余额和存储 PDA 地址的一部分，而不是外部权限 PDA 的一部分

### Rome Proxy（JSON-RPC 服务器）

Rome Proxy 是一个标准的 Ethereum JSON-RPC 服务器。用户连接到 `https://hadrian.testnet.romeprotocol.xyz/` 用于 Hadrian（测试网）和 `https://rubicon.mainnet.romeprotocol.xyz/` 用于 Rubicon（主网）。它将 Ethereum API 调用转换为 Solana 活动：

* `eth_sendRawTransaction` → 提交一笔或多笔 Solana v1 交易：原子 `DoTx`，holder 分片（`TransmitTx`）以及 `DoTxHolder`，或者迭代式分段。由共享付款方签名并支付 SOL。共享费用接收方收取用户的 gas 费用
* `eth_call` → 在通过 RPC 读取的实时 Solana 账户上，原生运行 EVM 解释器。Mollusk 会运行通过 CPI 可达的 Solana 程序。代理测量计算单元时，它也会运行 Rome EVM 程序
* `eth_estimateGas` → 用于 gas 估算的模拟。一个 gas 单位等于一个 lamport 的 Solana 成本。估算值不会低于 21,000
* `eth_getBalance`, `eth_getCode`, `eth_getTransactionCount`, `eth_getStorageAt` → 通过模拟器读取实时 Solana 账户。 `eth_getBlockByNumber`，回执和日志来自 Hercules

它还公开 Rome 扩展： `rome_emulateTx`, `rome_emulateRegRollup`, `rome_mintId`, `rome_buildInfo` 和 `rome_getResources`。Solana 钱包方法包括 `rome_emulateCallAccounts`, `rome_composeUnsignedAtomicV1`, `rome_composeUnsignedIterativeV1`, `rome_submitSignedV1Plan`, `rome_relayUnsignedV1`, `rome_composeExternalDepositV1` 和 `rome_sendUnsignedTransaction`。代理还公开 `rome_solanaTxForEvmTx`.

### Hercules（索引器）

Hercules 监视 Solana 上的 Rome EVM 程序，并在 PostgreSQL 中重建兼容 Ethereum 的区块。这些区块包含交易、回执、日志和状态变更。在公有链上，它以 slot 对齐模式运行，因此区块号映射到 Solana slot，同一 slot 在任何索引器上都会得到相同的区块。代理将这些区块提供给钱包和浏览器。

Hercules 对已确认区块进行索引。它会在最终确认时重新检查每个区块，如果 blockhash 发生变化则重新加载。该 [Via explorer](https://docs.rome.builders/zh/rome-shang-de-ying-yong/via.md) 读取 Hercules 数据。

### 预编译合约

Rome 以 Ethereum 语义实现了 ecrecover、SHA-256、RIPEMD-160、identity、BN254 曲线操作和 blake2f，但 BN254 和 blake2f 的失败数据除外。对 BN254 或 blake2f 的调用若失败，会返回 Rome 的 `Error(string)` 回退数据，而不是空缓冲区。Modexp（`0x05`）已禁用，并会回退并返回 `"big_mod_exp 调用已禁用"`。blake2f 拒绝超过 1,000,000 轮的调用，而 Ethereum 允许这种调用。

非 EVM 预编译合约可访问 Solana： **CpiProgram** (`0xFF…08`，任意 CPI）， **System** (`0xFF…07`），PDA 派生和 base58 辅助函数）， **HelperProgram** (`0xFF…09`，ATA/PDA 创建、SPL 转账、gas↔lamports），以及 **Withdraw** (`0x42…16`）。缓存家族是 **SystemCached** (`0xff…04`), **SplCached** (`0xff…05`), **ASplCached** (`0xff…06`）以及 **WithdrawCached** (`0xff…0b`）。旧版 CPI 会立即运行，并且只会在原子交易中运行。缓存 CPI 会在执行期间记录，并在提交时发送。它们会随 EVM 一起回退。它们可以在迭代式交易中运行。请参见 [合约地址](https://docs.rome.builders/zh/can-kao/contract-addresses.md) 参考文档中的完整表格。

## 执行模式

Rome 以两种方式执行 EVM 交易：

### 原子式（VmAt）

单笔 Solana 交易。整个 EVM 交易在一笔 Solana 交易的计算预算内执行（约 140 万计算单元）。适用于大多数操作——转账、普通合约调用、兑换。

### 迭代式（VmIt）

对于超出单笔交易预算的工作。执行会拆分为多笔 Solana 交易：

1. 每一步（一笔 Solana 交易）会在其计算预算内运行尽可能多的 EVM 操作码——步长是自适应的，而非固定的
2. VM 状态以 Borsh 序列化到一个 `StateHolder` 步骤之间的账户中
3. 在执行期间，账户会被 TTL 锁定几秒钟

当计算单元、堆或指令数量无法容纳在一笔 Solana 交易中时，代理会回退到迭代式执行。一次会话最多限制为 160 次迭代。由于无法跨分段拆分，迭代式交易会拒绝 legacy 路径的 CPI。cached 路径的 CPI 则允许。

## 账户映射

在 Rome EVM 程序下，每个 Ethereum 地址都会根据 chain ID 和该地址，确定性地映射到一个 Solana 余额 PDA。其原生 gas 余额是该 PDA 中的一个字段，此外还有 nonce 和合约代码。存储槽位位于独立的存储 PDA 中。SPL 余额位于由单独的外部权限 PDA 拥有的代币账户中。该权限在同一程序上的每条链之间共享。

## 两种接入方式

* **EVM 密钥通道：** 钱包将一笔经 secp256k1 签名的 EVM 交易发送到 Rome Proxy。代理提交这些 Solana 交易。
* **Solana 密钥通道：** 钱包使用其 Solana 密钥对未签名的 EIP-1559 交易体进行授权。对于直接的 v1 路径，代理会组装 Solana 交易。钱包对其签名，并直接提交到 Solana RPC。中继路径则改为使用代理提交。较旧的 legacy 路径要求钱包构建、签名并支付一笔 `DoTxUnsigned` Solana 交易，程序则从 Solana 签名者推导出发送方。

Solana 公钥映射到合成地址 `keccak256(pubkey)[12:]`，即哈希的最后 20 个字节。参见 [Solana 与 EVM 如何在 Rome 上交汇](https://docs.rome.builders/zh/he-xin-gai-nian/how-solana-and-evm-meet.md).

## 谁为对 Solana 的调用签名

Rome EVM 程序使用预编译合约的直接调用者的外部权限 PDA 对 CPI 进行签名。合约以自身身份签名。要花费用户的 SPL 代币，合约需要该用户提供 SPL 授权。用户可通过以下方式授予： `HelperProgram.approve_spl(spender, amount, mint)`。从用户的 EVM 地址或合成地址直接调用预编译合约时，会使用用户的外部权限 PDA。

## Holder 账户

Solana（v1）交易的上限为 4 KB，但 EVM 交易（尤其是合约部署）可能大得多。Rome 会将大型交易拆分为 3,600 字节的分片，并按顺序写入 **holder 账户** （最高可达 80 KB）。然后它会组装每笔交易并在链上执行。Rome SDK 会透明地管理这一过程。每个分片的签名费用都会计入发送方的 gas。

## Gas 与定价

每条链都有自己的 gas 代币：SOL 或某种 SPL 代币。价格来源可以是 Hermes API、Meteora DAMM v1 池、Meteora DAMM v2 池或固定价格。它提供底层 Solana 交易费用所需的 gas 代币与 SOL 之间的换算。

* 一个 gas 单位等于一个 lamport 的 Solana 成本
* `eth_gasPrice` 是每个 lamport 对应的 gas 代币 wei
* 发送方从其原生 gas 余额向费用接收方支付费用。代理付款方支付 SOL
* 在没有费用接收方时，如 Solana 钱包原子通道，不会收取 EVM gas。钱包直接支付 SOL
* 本地余额有 18 位小数。它由按链保存的程序钱包中持有的 gas-token SPL 提供支持

## 最终性

Rome 使用 Solana 的最终性。SDK 会等待 `已确认`。Hercules 会在 `finalized` blockhash 发生变化时重新检查并重新加载每个已索引区块。

## 下一步

* [网络](https://docs.rome.builders/zh/wang-luo/networks.md) — 连接到 Hadrian（测试网）和 Rubicon（主网）
* [快速开始](https://docs.rome.builders/zh/kuai-su-ru-men/quickstart.md) — 部署你的第一个合约
* [执行模型](https://docs.rome.builders/zh/he-xin-gai-nian/execution-model.md) — 原子执行与迭代执行的深入说明
* [代币互操作](https://docs.rome.builders/zh/he-xin-gai-nian/token-interop.md)
* [约束](https://docs.rome.builders/zh/he-xin-gai-nian/constraints.md)
* [从 EVM 调用 Solana](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/call-solana-from-evm.md)
* [从 Solana 调用 EVM](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/call-evm-from-solana.md)
* [预编译参考](https://docs.rome.builders/zh/can-kao/precompiles.md)
* [Solana 与 EVM 如何在 Rome 上交汇](https://docs.rome.builders/zh/he-xin-gai-nian/how-solana-and-evm-meet.md)


---

# 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/kuai-su-ru-men/architecture.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.
