> 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/rome-xue-yuan/06-tokens-on-both-sides.md).

# 6. 双边代币

一个 SPL 代币如何对 EVM 钱包表现为 ERC-20 包装代币，对 Solana 钱包表现为代币账户，以及允许合约转移它的一次性授权。

代币是以下每种用例的基础： [2. 可以构建什么](https://docs.rome.builders/zh/rome-xue-yuan/02-what-you-can-build.md)：无论是资金池、金库还是借贷市场，转移的都是 Solana 钱包持有的同一种资产。SPL 封装器通过 ERC-20 接口公开 SPL mint。对于钱包持有的代币，封装器会读取钱包中由 Rome 派生的代币账户余额，因此 Solana 和 Solidity 看到的是同一余额。本课将说明其工作原理，以及每位用户必须先授予的一项权限，否则你的合约无法转移其代币。

## 你将学到什么

* SPL 封装器如何通过 ERC-20 方法公开钱包的 Solana 代币余额。
* 工厂和封装器的作用，以及应使用哪种封装器。
* 合约持有的代币与钱包持有的代币有何不同。
* 一次性 `approve_spl` 授权、如何检查授权，以及授权失效的情形。

## 开始之前

* 完成 [5. 从 Solidity 调用 Solana](https://docs.rome.builders/zh/rome-xue-yuan/05-call-solana-from-solidity.md)。你需要了解外部权限 PDA 和 Helper 预编译合约的概念。
* 准备一个已注资的 Hadrian 钱包和一个已部署的合约。规范封装器地址位于链的 `tokens.json` 注册表文件中：找到带有 `kind: "spl_wrapper"` 且符号为 `wUSDC`. [Hadrian](https://docs.rome.builders/zh/wang-luo/hadrian.md) 链接指向该链的注册表文件夹。
* 你在第 5 课中通过 `createMyAta` 创建的 USDC 代币账户。授权要求该账户已存在。

## 一个余额，两种视图

每个 EVM 地址在 Solana 上都有一个外部权限 PDA，该 PDA 拥有此地址的代币账户。ERC-20 封装器的 `balanceOf` 会直接读取钱包的代币账户。 `totalSupply` 会读取 mint。

在 Rome 中，钱包的 SPL 代币与其 ERC-20 封装器读取的是同一个代币账户。持有 USDC 的 Solana 钱包和持有 USDC 的 EVM 地址，都持有同一个 mint，并且都通过同一组池账户进行交易。这就是流动性能够在 Rome 上集中于一处的原因。相关图示和详情请参阅 [代币互操作](https://docs.rome.builders/zh/he-xin-gai-nian/token-interop.md#the-shared-state-model).

## 钱包和合约持有代币的方式不同

这种共享余额的机制适用于钱包，合约则有所不同。合约无法代用户授予下文所述的一次性授权，因此，普通封装器会将合约的代币存放在托管代币账户中，并记录每个合约所拥有的代币数量。带钩子的 Token-2022 封装器不维护账本，而是使用合约自己的代币账户。

由此可知：

* 基于同一 mint 的两个封装器会显示相同的钱包余额。但它们显示的合约余额可能不同，因为各自维护独立的账本。
* 对于池、金库和借贷市场，请使用每条链的注册表中为各个 mint 指定的规范封装器。不要只凭名称选择。

通过封装器向合约转账，会增加该合约在账本中记录的余额，但不会为合约提供一个可供其支出代币的代币账户。需要合约在 Solana 上执行操作的流程，请参阅 [集成 Solana 程序](https://docs.rome.builders/pages/6d3e31686e4cb73ec09bc01c61a81b4e07583fbf#id-3.-tokens-in-tokens-out).

## 工厂和封装器

`ERC20SPLFactory` 会为 SPL mint 部署一个封装器。每个工厂对每个 mint 只能部署一个封装器。该封装器提供完整的 ERC-20 接口：

* `balanceOf` 和 `totalSupply` 读取 Solana 状态。
* `transfer` 和 `transferFrom` 在 Solana 上转移代币。
* `approve` 和 `allowance` 将普通 ERC-20 授权额度保留在 EVM 存储中，因为代币账户没有这类机制。

你很少需要部署包装合约。Rome 和注册表已经提供了 USDC、ETH 和 SOL 的规范版本。只有在引入新的 mint 时才需要部署。两个工厂调用都在 [工厂](https://docs.rome.builders/zh/he-xin-gai-nian/token-interop.md#the-factory)中。工厂也支持 Token-2022 mint，但其扩展会改变集成方式：带钩子的包装合约会使普通的 `transfer` 和 `transferFrom`调用回退，而带转账手续费的 mint 实际到账可能少于发送金额。在将其用于金库之前，请先阅读 [Token-2022 mint](https://docs.rome.builders/zh/he-xin-gai-nian/token-interop.md#token-2022-mints) 。

金额必须能用 `uint64`表示，因为 SPL 金额采用该类型，包装合约也会拒绝任何更大的值。Gas 代币有自己的小数位数，而原生 gas 余额使用 18 位小数。两者之间的转换必须精确。Hadrian 和 Rubicon 上的 gas 代币是 USDC。

## 一次性授权

包装合约会以 SPL 委托人的身份，转移用户代币账户中的代币。用户必须先在代币账户中指定该委托人，包装合约才能转移代币。用户只需对每个包装合约调用一次，并授权最大金额：

`approve_spl(wrapper, type(uint64).max, mint)` 调用 Helper 预编译合约。

实际使用时，有四点需要注意：

* **由用户发起。** 该授权由用户自己的账户签名，并直接发送给 Helper 预编译合约。你的合约无法代替用户发送。请在前端加入“启用”步骤。
* **所有用户都需要授权。** MetaMask 钱包和 Solana 钱包的合成地址都需要为其想要转移代币的每个包装合约进行授权。
* **先检查授权状态。** 包装合约的 `isEnabled(user)` 在授权完成后会返回 `true` 。转账前应读取该值，不要想当然。
* **授权最大额度。** `isEnabled` 会在受限额度尚有剩余时一直保持 `true` 。额度有限的授权在余额所剩不多时会导致普通转账失败，而且你的应用也不会知道需要再次请求授权。

要传入的 mint 是包装合约上的 `mint_id()` 。有关两种钱包类型的前端实现示例，请参阅 [一次性操作：授权包装合约](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/dual-lane-app.md#one-time-grant-the-wrapper).

### 失效原因

一个代币账户只能有一个委托人。如果用户授权了桥接合约或路由器，该授权会取代对包装合约的授权，导致包装合约无法再为该用户工作。此时会出现回退，并返回 SPL 错误 `0x4`，表示所有者不匹配。解决方法是重新授权包装合约。因此，在依赖包装合约的操作流程开始前，应检查 `isEnabled` ，而不是只在注册时检查一次。

新版本的工厂会带来新的包装合约，每个钱包都需按相同方式为新合约授权。

## 转出代币

由于包装合约余额本身就是 SPL 余额，将代币转出到 Solana 只需执行 SPL 转账。

* 从 EVM 钱包转给另一个 Solana 钱包： `transfer_spl` 直接从钱包发送到 Helper 预编译，或者 `RomeBridgeWithdraw.bridgeOutToSolana`，此操作也需要为桥接合约授予权限。两种方式都要求收款方的代币账户已存在。
* 发送到签署交易的钱包： `transfer_spl_to_signer`。只有通过钱包签名的 Solana 通道，代币才会到达用户自己的钱包。从 MetaMask 发起时，签名者是 Rome 的代理付款方，因此请使用另外两种方式。
* 对于 Gas 代币， `withdraw_to_ata` 和 `deposit_from_ata` 用于在原生 Gas 代币与代币账户中的代币之间进行兑换。

Solgate 可在主网和测试网上双向连接 Solana 资产与 AggLayer EVM 链。在测试网上，SPL 代币注册无需许可。USDC 使用 CCTP。 [第 10 课](https://docs.rome.builders/zh/rome-xue-yuan/10-from-other-chains.md) 将回到入站流程和桥接。方法列表请参见 [存款与取款](https://docs.rome.builders/zh/he-xin-gai-nian/token-interop.md#deposit-and-withdraw).

## 自测

在 Hadrian 上，使用你已充值的那个钱包：

1. 读取 `isEnabled` 查询注册表中 canonical wUSDC 包装合约对你地址的启用状态。
2. 确保你的 USDC 代币账户已存在。第 5 课中的 `createMyAta` 调用已创建该账户。如果你跳过了这一步，可使用 `withdraw_to_ata`将少量 Gas 代币包装为 wUSDC，参见 [在 MetaMask 中使用同一个应用](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/dual-lane-app.md#the-same-app-from-metamask).
3. 如果 `isEnabled` 为 `false`，请向 Helper 预编译发送 `approve_spl` 授权。请使用上方双通道指南中的代码。
4. 再次读取 `isEnabled` 。现在它应为 `true`.
5. 在以下位置查找你的授权交易： [通过区块浏览器](https://docs.rome.builders/zh/rome-shang-de-ying-yong/via.md)。查找 SPL Token `ApproveChecked` 指令。

<details>

<summary>1. 为什么同一 mint 上的两个包装合约显示相同的钱包余额？</summary>

它们都读取 Solana 上的钱包代币账户。包装合约只是 SPL 代币的一种视图，并非单独的账本。只有由合约持有的余额才会按包装合约分别跟踪。

</details>

<details>

<summary>2. 用户向你的金库存入资产，随后使用某个路由器，而该路由器要求用户为其自身 <code>approve_spl</code>授权。接下来，你调用 <code>transferFrom</code> 时却因 SPL 错误 0x4 而回退。为什么？</summary>

一个代币账户只能有一个委托人。路由器的授权取代了包装合约的授权。用户必须重新授权包装合约，而你的应用应检查 `isEnabled` 转账之前。

</details>

<details>

<summary>3. 新建流动性池时应使用哪个池包装器？</summary>

注册表为该链上的该铸币指定的规范包装器。不同包装器持有的合约余额各不相同。

</details>

## 下一步

[7. 将 EVM 应用接入 Solana 钱包](https://docs.rome.builders/zh/rome-xue-yuan/07-open-to-solana-wallets.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/rome-xue-yuan/06-tokens-on-both-sides.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.
