> 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/he-xin-gai-nian/token-interop.md).

# 代币互操作

ERC-20 和 SPL 代币如何在 Rome 上对应同一个底层账户。

Rome 将 ERC-20 代币及其底层 SPL 代币表示为一个共享账户。本页介绍代币如何在 EVM 和 Solana 之间运作。

## 共享状态模型

对于普通钱包，Rome 上的 ERC-20 代币是 Solana 上 SPL 代币账户的 **透明封装** 。钱包的 ERC-20 余额就是其 SPL 余额。与 EVM 地址对应的程序派生地址（PDA）拥有该代币账户。这就是 **外部权限 PDA**.

<figure><img src="https://4058553919-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-552c639322c2d0e90b312def5db39d06c1871d18%2Ftoken-interop.svg?alt=media" alt="An EVM address and its Solana token account, owned by its external-authority PDA. Multiple wrappers read the same token account. The wrapper escrow account and Solana pool vaults hold tokens of the same Solana mint."><figcaption></figcaption></figure>

* 无同步延迟：钱包的 ERC-20 余额就是其 SPL 余额。
* 普通钱包（包括 MetaMask 钱包和合成地址）不存在流动性碎片化。针对同一铸币账户的所有封装合约都会显示相同的钱包余额。balanceOf `balanceOf` 方法会从钱包的代币账户读取该余额。存放在 EVM 合约中的代币按封装合约分别持有（参见 [封装合约](#the-wrapper-contract)).
* 对于钱包持有的代币，不会出现一边锁定、另一边铸造的情况。合约持有的代币存放在 Solana 上封装合约自己的托管代币账户中。每个封装合约分别跟踪这些代币。

**为什么第二个封装合约不会拆分余额**

针对同一铸币账户的两个封装合约会显示相同的钱包余额。封装合约从 Solana 铸币账户读取 `totalSupply` 。在 Hadrian（测试网）上，三个 wUSDC 封装合约返回了相同的钱包余额。三个 wUSDC 封装合约（9.0.0、8.0.0 和 2026 年 5 月版）均返回了 Solana 铸币账户的供应量。

每个工厂对每个铸币账户仅允许部署一个封装合约。新的工厂版本可以为该铸币账户再部署一个封装合约。注册表会为每条链指定规范封装合约。

直接持有 USDC 的 Solana 钱包和 EVM 地址持有的是同一铸币账户下的代币。Solana 流动性池对两者使用相同的金库和储备。

中的持有人表 [Via 浏览器](https://docs.rome.builders/zh/rome-shang-de-ying-yong/via.md) 根据每个封装合约的 `Transfer` 事件生成。由于直接 SPL 转账、 `ActivateAta`以及通过其他封装合约进行的转账不会记录在该封装合约的事件中，因此表中的数据可能与代币账户余额不同。

> 以下导入路径使用 `@rome-protocol/rome-solidity`。该软件包未发布到 npm；请从公开的 [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) 代码库安装： `npm install github:rome-protocol/rome-solidity`，或者使用 `forge install rome-protocol/rome-solidity` 并配置重映射；在 Foundry 中，封装合约和工厂合约还需要 OpenZeppelin（参见 [部署 Solidity 合约](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/deploy-solidity.md#using-the-rome-solidity-sdk)）。预编译接口位于 [`contracts/interface.sol`](https://github.com/rome-protocol/rome-solidity/blob/master/contracts/interface.sol).

## 封装合约

`SPL_ERC20` （及其缓存跟踪变体 `SPL_ERC20_cached`；工厂会为除启用了转账钩子的铸币账户以外的所有铸币账户部署此变体；参见 [Token-2022 铸币账户](#token-2022-mints)）在 SPL 铸币账户之上提供完整的 ERC-20 接口：

* `balanceOf()` — 从 Solana 读取用户的 ATA 余额（对于合约地址，则读取封装合约自己的账本，见下文）
* `transfer()` / `transferFrom()` — 在 Solana 上转移代币
* `approve()` / `allowance()` — 每个支出方的 ERC-20 授权额度存储在 EVM 中（SPL 代币账户没有 EVM 风格的授权额度）。这些额度与下方的一次性授权相互独立：要转移用户的任何代币，包装器都必须作为该用户的 SPL 代理，而用户只需为每个钱包授予一次此权限
* `totalSupply()` — 读取 SPL 铸币账户的供应量

合约无法发出一次性授权，因此合约持有的代币会存放在包装器自己的代币账户中，并记录在包装器的账本里。 `balanceOf(contract)` 读取该账本。

## 工厂合约

`ERC20SPLFactory` 可为任意 SPL 铸币账户部署包装器：

```solidity
import {ERC20SPLFactory} from "@rome-protocol/rome-solidity/contracts/erc20spl/erc20spl_factory.sol";

// 部署包装器，从铸币账户的 Token-2022 元数据或 Metaplex 加载名称/符号
address wrapper = factory.add_spl_token_with_metadata(splMint);

// 或手动指定名称/符号
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

实时工厂地址，来自注册表的 `live` 条目（v0.2.0）：Hadrian `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`。较早的工厂仍部署在链上，但标记为 `deprecated` 或 `retired` ，位于 [注册表](https://github.com/rome-protocol/rome-registry/tree/main/chains)中；请勿使用。注册表是权威信息来源，因此应从中读取实时地址（参见 [读取合约列表](https://docs.rome.builders/zh/can-kao/contract-addresses.md#reading-the-contracts-list)），不要将地址复制到代码中。

## 规范铸币账户

链上没有代币注册表合约。规范包装器以及 Gas/桥接代币由链下的 [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry)维护；通过 `add_spl_token_no_metadata` 创建的无许可包装器则通过链上的 `TokenCreated` 事件发现。注册表列出了每条链上每个铸币账户对应的规范包装器。钱包余额在不同包装器间共享。每个包装器会单独跟踪由 EVM 合约持有的余额。

## 在 Solidity 中执行 SPL 操作

对于由用户 PDA 签名的 SPL 基础操作，请使用 **HelperProgram** 预编译合约（`0xFF…09`）——用于创建 ATA、执行 SPL 转账以及转换 Gas 与 lamports：

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

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // 为用户创建该铸币账户对应的 ATA
helper.transfer_spl(to, tokens, mint);      // 从调用方的 PDA 转出 SPL 代币
```

`transfer_spl` 有多个重载版本（包括用于 `transferFrom` 流程的代理版本）；参见 `interface.sol` 用于精确签名。在缓存轨道上，对应的操作位于 `ISplCached` (`0xFF…05`) 和 `IAssociatedSplCached` (`0xFF…06`)。合约会始终使用同一轨道。

## 每个钱包一次性授权

包装合约会将用户的代币作为 **SPL 委托方** 该用户代币账户的。因此，钱包必须在每个包装器上授予它这项权限一次，之后包装器才能代用户转移任何资产。授权只需调用一次 Helper 预编译（`0xff00000000000000000000000000000000000009`):

```solidity
helper.approve_spl(wrapper, type(uint64).max, mint);   // approve_spl(wrapper, 2^64-1, mint)
```

`approve_spl` 由用户自己的账户签名，因此发送该调用的是用户，而不是包装器或你的合约。铸币地址为 `mint_id()` （在包装器上）。

* **哪些主体需要授权。** 每个 EVM 钱包，以及每个 Solana 用户的合成地址，都需要为其希望转移代币的每个包装器授予授权。使用以下方式拉取代币的合约 `transferFrom` 仅适用于已授权该包装器的用户。
* **检查方法。** 调用 `isEnabled(user)` （在包装器上）。它会返回 `true` 授权完成后。
* **未获得授权时的表现。** 转账会因 SPL 错误而回滚 `0x4` （所有者不匹配）。
* **每个代币账户只能有一个委托方。** SPL 代币账户只能有一个委托方。在同一个代币账户上授权另一个程序（例如桥接程序或路由器），会取代授予包装器的权限，导致该用户无法再使用包装器，除非重新授权。请检查 `isEnabled` 再进行转账，不要假设之前授予的权限仍然有效。

新工厂版本替换包装器后，每个钱包都需要使用 `approve_spl`向新包装器授予权限。只要旧包装器仍是该钱包代币账户的委托方，它就可以转移该钱包的代币。授权新包装器会取代原有委托方。

该 [双通道应用指南](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/dual-lane-app.md#one-time-grant-the-wrapper) 包含两个通道的完整代码。

## 存入和提取

* **转入 EVM** — SPL 侧会将资金记入用户 PDA 所有的 ATA；ERC-20 封装代币会立即反映余额。来自其他链的转入会通过桥接上的用户签名授权在链上完成结算。
* **将 Gas 封装为 Gas 代币** — 调用 `Withdraw` 预编译合约（`0x42…16`). `withdraw_to_ata(wei)` 销毁原生 Gas，并按 Gas 代币自身的小数位数，将等值金额计入调用者的代币账户；Gas 代币的包装代币（例如 wUSDC）随后会显示为余额。 `withdraw_to_pda(wei)` 向调用者的 PDA 支付 lamport；仅适用于以 SOL 作为 Gas 的链。Hadrian 和 Rubicon 使用 USDC 作为 Gas，因此此调用会回滚，应改用 `withdraw_to_ata` 。金额以 18 位小数的 Gas 单位表示，且必须是整数个 Gas 代币单位：在以 USDC 作为 Gas 的链上，金额必须是 10^12 的倍数（即一个 6 位小数单位），否则调用会回滚。 `HelperProgram.deposit_from_ata(wei)` 功能相反：将调用者代币账户中的 Gas 代币转换回原生 Gas，并遵循相同的倍数规则。这些是 Gas 代币转换方法，并不能用于提取其他代币。
* **转出到 Solana 的其他代币** ——包装代币自身的余额已经是 SPL 余额，因此将其转出就是一次 SPL 转账：
  * `HelperProgram.transfer_spl_to_signer(amount, mint)` 将调用者的代币发送到为该交易签名的 Solana 钱包所对应的代币账户。只有在由钱包签名的 Solana 通道中，这种返还方式才会将代币发送到用户自己的钱包。如果通过 MetaMask 或中继器调用，签名者是 Rome 的代理付款方，因此调用会失败，或者代币会被发送给 Rome。请改用 `transfer_spl` 或 `RomeBridgeWithdraw.bridgeOutToSolana` 。
  * `RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint)` 会将代币发送到任意 Solana 钱包。此操作需要用户向桥接合约授权（`approve_spl(bridge, …)`，参见上文关于单一委托方的说明），且收款方的代币账户必须已存在； `ensureRecipientAta(solanaRecipient, mint)` 可创建该账户。
  * `RomeBridgeWithdraw` 还可以通过 CCTP 将 USDC 销毁并转移到另一条链（`burnUSDC`），并通过 Wormhole 发送其他资产（`burnETH`, `burnToWormhole`).

从注册表中获取最新的 `RomeBridgeWithdraw` 地址。

要在 Solana 与 Ethereum 或 AggLayer 链之间转移其他代币，请参阅 [Solgate](https://docs.rome.builders/zh/rome-shang-de-ying-yong/solgate.md) 和 [13. 在 Solgate 上构建](https://docs.rome.builders/zh/rome-xue-yuan/13-build-on-solgate.md).

## Gas 代币

每条链都有自己的 Gas 代币：SOL 或 SPL 代币。Rome Proxy 的价格来源可以是 Hermes API 报价源、Meteora DAMM v1 池、Meteora DAMM v2 池或固定价格。Hadrian（测试网）和 Rubicon（主网）使用 USDC。Hadrian 使用测试 USDC，Rubicon 使用真实 USDC。不存在通用的默认 Gas 代币。

## Token-2022 铸币

工厂也会包装 Token-2022 铸币。它会通过以下方式查询 Helper 预编译合约，以确定铸币类型： `mint_info(mint)` （选择器 `0xe24bf5d4`），并根据返回结果选择包装代币。 `mint_info` 会返回五个值：

| 值              | 含义                                            |
| -------------- | --------------------------------------------- |
| `tokenProgram` | 拥有该铸币的代币程序（经典 SPL Token 程序或 Token-2022）       |
| `decimals`     | 该 mint 的小数位数                                  |
| `hookProgram`  | 转账钩子程序；如果没有钩子，或钩子存在但未启用，则为零地址                 |
| `feeBps`       | 以基点表示的转账手续费；如果没有手续费或手续费设为零，则为零                |
| `extensions`   | 一个位图，表示该 mint 包含的 Token-2022 扩展；第 N 位对应扩展类型 N |

Mint 对应的包装器：

| Mint                                          | 包装器                                                                    | `wrapper_kind_by_mint` |
| --------------------------------------------- | ---------------------------------------------------------------------- | ---------------------- |
| 普通 mint、没有钩子的 Token-2022 mint，或钩子存在但未启用的 mint | 缓存型包装器（`SPL_ERC20_cached`)                                             | `1`                    |
| 启用了转账钩子的 Token-2022 mint                      | 带钩子的包装器（`SPL_ERC20_Token2022Hooked`），通过工厂的 `hooked_wrapper_deployer()` | `2`                    |

带转账手续费的 mint 会获得缓存型包装器，其 `Transfer` 事件报告的是扣除手续费后实际到账的金额，而不是发送金额。可以通过工厂的 `wrapper_kind_by_mint(mint)`读取 mint 获得的包装器类型；在 Hadrian 线上工厂中，USDC、ETH 和 SOL 包装器均返回 `1`.

哪些情况会被拒绝：

* 启用了转账钩子的 mint 不能使用普通包装器。直接在其上部署 `SPL_ERC20` 或 `SPL_ERC20_cached` 会回滚，并报错 `ArmedTransferHookUnsupported(mint, hookProgram)`。通过工厂处理时，这种情况会改用带钩子的包装器。
* 非 SPL mint 的地址会使 `mint_info` 回滚，并报错 `Invalid SPL mint account: <address>`.
* 已拥有包装器的 mint 会回滚，并报错 `Token exists`；已被使用的符号也会导致回滚，并报错 `Token with symbol exists`.
* `add_spl_token_with_metadata` 会优先从 mint 自身的 Token-2022 元数据中读取名称和符号，其次从 Metaplex 读取。如果 mint 两者都没有，则会回滚，并报错 `Mint asserts no name: use add_spl_token_no_metadata`.

带钩子的包装器的行为：

* Token-2022 会在每次转账时运行钩子，而钩子需要的账户取决于具体转账。包装器无法自行确定这些账户，因此调用方要根据 mint 的 extra-account-metas 列表解析出完整账户列表并传入。包装器会检查该列表中固定的部分（钩子程序及其验证账户），并原样转发其余内容。
* 普通 `transfer`, `transferFrom` 以及 `bridgeOutToSolana` 回滚并返回 `HookAccountPlanRequired`。使用 `transferWithHookAccounts`, `transferFromWithHookAccounts` 以及 `bridgeOutToSolanaWithHookAccounts`，这些函数会将账户列表作为额外参数。
* 如果在部署包装器后，铸币账户的钩子程序发生变化，转账会回滚并返回 `HookConfigurationChanged`.
* 它通过直接跨程序调用（旧路径）转移代币，不使用缓存路径。合约会始终使用同一路径，而旧路径上的调用只能在原子执行中运行，因此，使用带钩子的包装器进行的调用必须能在单笔原子交易中完成。
* 它不会为合约余额维护账本。发送给合约的代币会进入合约自己的代币账户；只有在合约向包装器授予 `approve_spl` 权限后，才能继续转出这些代币。
* 它需要与其他包装器相同的 [一次性授权](#one-time-grant-per-wallet) 。

## 限制

* SPL 代币数量为 `uint64` （最大值为 18,446,744,073,709,551,615）
* ERC-20 授权额度（`approve` / `allowance`）存储在 EVM 中。包装器以用户的 SPL 代理身份转移代币；用户需要为每个包装器授权一次（参见 [每个钱包的一次性授权](#one-time-grant-per-wallet))
* ERC-20 包装器的符号在每个工厂中必须唯一

## 接下来

* [合约地址](https://docs.rome.builders/zh/can-kao/contract-addresses.md) — 预编译合约及各链地址
* [从 EVM 调用 Solana](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/call-solana-from-evm.md) — 从 Solidity 执行 CPI 和 SPL 操作
* [Solana 与 EVM 如何在 Rome 上交互](https://docs.rome.builders/zh/he-xin-gai-nian/how-solana-and-evm-meet.md)
* [集成 Solana 程序](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/integrate-solana-program.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/he-xin-gai-nian/token-interop.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.
