> 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/kai-fa-zhe-zhi-nan/integrate-solana-program.md).

# 集成一个 Solana 程序

将 Solana 程序与 Rome EVM 集成——Solana 签名者是谁、价值如何传入你的程序并返回、单轨规则、原子式与迭代式，以及账户配置。

本指南面向希望让 Rome EVM 用户使用其程序的 Solana 程序团队——即一个应为 EVM 账户持有价值的隐私、借贷或金库程序。本指南建立在 [从 EVM 调用 Solana](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/call-solana-from-evm.md) （预编译机制）之上，并回答当另一侧接入真实程序后会出现的问题： *谁* 签名， *如何* 代币进出，以及 *哪些* 限制会塑造设计。

全文采用的流程是：EVM 账户将 USDC 转入你的程序（“shield” 或 “deposit”），你的程序为该用户持有这些资金，之后再将其释放回去（“unshield” 或 “withdraw”）。你可以用自己的术语替换这些动词。

## 1. 每个 EVM 地址都有一个 Solana 身份

Rome 会为每个 EVM 地址——无论用户还是合约——派生一个 Solana 账户，称为其 **外部授权**:

```
external_auth(addr) = find_program_address(["EXTERNAL_AUTHORITY", addr_h160], rome_evm_program_id)
```

它拥有该地址的关联代币账户（也就是 `wUSDC.balanceOf(addr)` 读取的来源），并且它是代表该地址签署 CPI 的密钥。你的程序看到的是一个 32 字节的 Solana 公钥；它从不会看到 H160。

**谁来签名，取决于谁调用了预编译：**

| 预编译由                        | Solana 签名者                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 一个 **合约**调用，带有一个普通的 `CALL`  | 这些 **合约自身的** 外部授权（`external_auth(contract)`），以及它请求的任何带盐子 PDA                                                                                                                                                                                                                                                                                                             |
| 一个 **用户**，在一笔直接发送到预编译地址的交易中 | 这些 **用户自身的** 外部授权                                                                                                                                                                                                                                                                                                                                                        |
| 合约通过 `DELEGATECALL`         | 裸授权会被拒绝（`DelegatecallOwnerAuthority`). `invoke` 没有签名者，并且 `invoke_signed` 带盐的子 PDA 仍然可运行——但这些子 PDA 以当前运行合约的地址为命名空间（`["EXTERNAL_AUTHORITY", caller, running_contract, salt]`），因此 `pda_with_salt` 不会派生它们。HelperProgram 中只有创建和注资选择器会通过（`create_ata*`, `create_pda*`, `swap_gas_to_lamports`, `init_spl_mint`, `create_and_init_mint`）；它们之所以豁免，是因为其目标绑定到调用者或由操作员注资，而不是因为它们不签名 |

结果就是你已经熟悉的 ERC-20 规则： **合约不能自行移动用户资产。** 它作为自身身份运作，用户先授予它权限。对于必须在 Solana 侧移动的代币，这种授权是用户代币账户上的 SPL 委托；包装器的 ERC-20 `approve` 只不过是 EVM 侧的额度，包装器自身的转账会遵守它。这就是 Rome 自己的代币包装器的工作方式，也是你的适配器的工作方式（第 3 节）。

带盐子 PDA： `invoke_signed` 接收一个 `bytes32` 盐列表，Rome 会使用 `["EXTERNAL_AUTHORITY", caller_h160, salt]` 为每个盐签名（会附加 bump；在直接调用时，caller 是该合约）。 `HelperProgram.pda_with_salt(addr, salt)` 会从 Solidity 返回该地址。当你的程序希望每个仓位都有一个不同的所有者账户时，每个用户使用一个盐（例如用户地址）。

注资：外部授权 PDA 不一定必须存在才能拥有一个 ATA（`create_ata` 是幂等的，而交易的 Solana 费用支付者会承担租金）。只有在为你的指令创建的账户注资时，它才必须存在并持有 lamports。 `HelperProgram.create_pda(addr)` 会将其作为一个普通的 System `CreateAccount`创建，所以只需调用一次；它不是幂等的。 `swap_gas_to_lamports(n)` 会用交易的 Solana 费用支付者的 lamports 为该地址的 PDA 充值， `n` 而调用方则以 Rome gas 的形式为这些费用买单：每个传统路径 CPI 对费用支付者余额的影响都会被计入交易费，并按 gas 价格向用户收费，CPI 创建账户的租金也是同样处理。Solana 通道的准备步骤见 [从 Solana 调用 EVM](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/call-evm-from-solana.md)；合约会在构造函数中或首次调用时为自己的 PDA 做准备。

## 2. 持有用户仓位的三种方式

**A. 适配器合约（适用于可复用适配器的推荐方案）。** 一个 Solidity 合约作为你程序的前端。用户向适配器的授权在其代币账户上授予 SPL 委托；适配器把代币拉入它自己拥有的代币账户，以自身身份调用你的程序，并通过按用户划分的子 PDA 或它在指令数据中传入的标识符来为你的程序中的用户仓位建键。返回时，它会让你的程序将资金释放到用户自己的代币账户。适配器是你的程序唯一需要识别的 Solana 身份。该授权是 SPL 委托，而不是 ERC-20 `approve`；第 3 节会解释原因以及这会给用户带来什么成本。

**B. 用户作为 Solana 签名者。** 前端从用户的 EVM 账户发送一笔交易 **直接到 CpiProgram 预编译** (`to = 0xff…08`，calldata = ABI 编码后的 `invoke` 或 `invoke_signed`），因此用户自身的外部授权会签名，你的程序据此为该仓位建键。没有适配器合约，也没有委托，但每个动作在钱包里都是一笔不透明的 calldata 交易，而流程所需的任何额外内容（ATA、前置转账）都需要单独交易。它适用于一次性授权（用户对包装器的 `approve_spl` ）以及简单程序，不适合多步骤流程。 [Cardo](https://github.com/rome-protocol/cardo) 采用了这种形态：其前端会从用户钱包直接发送 `invoke` 到预编译。

**C. 无托管路由器。** 一种从不持有用户代币的合约。用户向路由器的授权在自己的代币账户上授予 SPL 委托；路由器以该授权作为转账授权调用你的程序，因此代币会从用户的代币账户移动到你程序的账户（或返回用户账户），而路由器在两次调用之间什么也不持有。路由器会从 `msg.sender`派生每个用户侧账户，因此一个用户的授权不能被指向另一个用户的账户；它调用的是一个固定程序，并使用固定的指令形状，而不是充当通用 `invoke` 透传器。该 `RomeDexRouter` 在 [rome-dex](https://github.com/rome-protocol/rome-dex) 就是这样写的；rome-dex 的 EVM 通道也提供原始的 `invoke` 这种形态的直连方式。它需要与 A 相同的授权，以及同样的单一委托成本（第 3 节），并且不需要拉取步骤。

本指南其余部分都以 A 为例；C 使用相同的授权和相同的签名规则。

## 3. 代币进入，代币流出

Rome 上的 USDC 是同一个 SPL mint，从两个侧面观察：EVM 侧的 `wUSDC` ERC-20 包装器，以及 Solana 侧外部授权的 ATA。对用户自己的地址而言，这两者是同一余额： `wUSDC.balanceOf(user)` 读取的是用户的 ATA。两种视图之间不会有任何转移或同步。

**合约的包装器余额并不是合约控制的代币账户。** 工厂会 `SPL_ERC20_cached` 为普通 mint 部署包装器，而 Hadrian 的 `wUSDC` 就是其中之一。该包装器不能代表合约签名，因此当 `wUSDC.transferFrom(user, adapter, amount)` 或 `transfer` 把代币发送给合约时，SPL 代币会进入 **包装器自身的托管代币账户** (`escrow_ata()`），而包装器会在其存储中按合约记录该金额。 `wUSDC.balanceOf(adapter)` 返回的是那条记录，即一条托管台账，而不是 `external_auth(adapter)`拥有的代币账户余额。你的适配器不能通过 CPI 将这些代币交给你的程序；它们只能再次通过包装器流出。因此，一个用 `transferFrom` 为自己注资的适配器，在 Solana 侧没有任何可支出的资金。

可行的路径是 SPL 委托：

* **授权。** 用户发送 `approve_spl(adapter, amount, mint)` 作为一笔交易 **直接到 HelperProgram** (`to = 0xff…09`，其中 `mint` 是包装器的 `mint_id()`。用户自身的授权会签名，而它在用户代币账户上设置的委托就是适配器的外部授权。
* **进入。** 适配器的 `deposit(amount)` 使用委托重载进行拉取 `HelperProgram.transfer_spl(srcAta, dstAta, amount, mint)`，其中用户的 ATA 作为来源，适配器自己的 ATA（`HelperProgram.ata(address(this), mint)`，只需创建一次，使用 `create_ata`）作为目标。适配器的授权以委托身份签名。现在这些代币位于由 `external_auth(adapter)`拥有的代币账户中，也就是你的 CPI 所命名的账户；签名者和来源都是适配器自身，因此不需要进一步授权。它们不会出现在 `wUSDC.balanceOf(adapter)`.
* **流出。** 你的程序的 withdraw 指令会转账到 **用户的** ATA， `HelperProgram.ata(user, mint)`。接收不需要用户签名，余额会立即显示为 `wUSDC.balanceOf(user)`。如果该 ATA 可能尚未存在，先用 `HelperProgram.create_ata(user, mint)` 创建它（幂等）。

**一个代币账户只有一个委托者。** 上面的授权会替换该账户上包装器自身的授权。在用户再次授予包装器之前，每次从其地址 `wUSDC` `transfer` 或 `transferFrom` 转出都会因 SPL 错误 `0x4`而回滚。在使用该授权的任何流程之后，调用 `wUSDC.isEnabled(user)`；当它返回 `false`时，要求用户再次发送 `approve_spl(wrapper, 2^64-1, mint)` 到 HelperProgram，这也是包装器所围绕建立的最大授权（见 [一次性：授予包装器](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/dual-lane-app.md#one-time-grant-the-wrapper)）。如果授权有上限，那么用户的普通 `wUSDC` 转账在额度耗尽后会再次失效，而且 `isEnabled` 会保持 `true` 只要其中仍有任意余额存在，应用就不会知道需要再次提示用户。

要检查某个 mint 对应的是哪种包装器，请读取工厂的 `wrapper_kind_by_mint(mint)` （工厂地址位于链的 `contracts.json` 在 [注册表](https://github.com/rome-protocol/rome-registry)). `1` 中的是本节所述的 cached 包装器。 `2` 是工厂为带有已启用转账钩子的 Token-2022 mint 部署的直接 CPI 包装器；本指南不予讨论。注册表中的 `tokens.json` 只列出包装器地址和 mint，不会标明其类型。

## 4. 每个合约、每笔交易只走一条轨道

Rome 有两类会更改 Solana 状态的预编译，且 **一笔交易只会使用其中一种** —— 即使跨合约，运行时也会拒绝在同一交易中混用两者的变更性调用。

| 轨道         | 预编译合约                                                                                               | 生效位置                                  | 是否可在迭代执行中运行                                                      |
| ---------- | --------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------- |
| **Legacy** | `CpiProgram` `0xff…08` (`invoke`, `invoke_signed`), `HelperProgram` `0xff…09`, `Withdraw` `0x42…16` | 立即生效，作为 EVM 步骤中的真实 CPI                | **否** —— 在迭代交易中的 legacy CPI 会失败，报错为 `CpiProhibitedInIterativeTx` |
| **Cached** | `SplCached` `0xff…05`, `ASplCached` `0xff…06`, `SystemCached` `0xff…04`, `WithdrawCached` `0xff…0b` | 先在叠加层中暂存，并在交易结束时作为 CPI 提交；EVM 回滚会将其丢弃 | 是                                                                |

这对程序集成意味着什么：

* **调用你自己程序的指令仅限 legacy 路径。** cached 路径没有通用的 `invoke`；它覆盖 SPL 转账、ATA 创建、System Program 操作和 gas 提取。
* 因此，如果为适配器注资的步骤与 CPI 在同一交易中执行，那么该步骤也必须走 legacy 路径。cached 包装器的 `transferFrom` 是 cached 路径调用，因此不能与你的 CPI 共用一笔交易（而且如第 3 节所示，它只会记入托管台账）。请改用 `HelperProgram.transfer_spl(userAta, adapterAta, amount, mint)` ，前提是用户已经让适配器成为 SPL 委托（`approve_spl`，由用户直接发送给 HelperProgram）。拉取和 CPI 都是 legacy 路径，因此它们可以在一笔交易中执行。
* **让该交易避开包装器。** 不要在与 legacy CPI 相同的交易中，从适配器调用包装器的变更函数（`wUSDC.transfer`, `transferFrom`）。 `isEnabled(user)` 和余额时，用前端来检查 `eth_call`.
* **而且 CPI 交易必须是原子的。** 这就是该设计所受的上限。

读取不受此规则限制： `account_info`, `account_data_at`, `account_u64_at`, `account_lamports`, `pdas_batch_derive` 和 `HelperProgram.user_balance` / `allowance_of` 是对预加载账户的读取（没有 CPI），可在任一轨道和两种执行模式下使用。把你的预检查放在这些读取上。一个顺序规则：一旦交易中触发了某个 cached 变更，剩余部分就会阻止 legacy 路径读取——先读，再变更。

## 5. 原子性就是预算

一个原子的 Rome 交易就是一笔 Solana 交易：大约 **140 万计算单元**、一个 **64 地址** 的账户列表，以及一个 **4 KB** 的线上大小（Solana v1 交易）。Rome 程序和你的 CPI 共享这部分预算。Hadrian 上的一次包装器转账大约消耗 170K CU，你的指令还会增加自身开销；请使用 Solana 收据中的 `computeUnitsConsumed`，而不是 EVM `gasUsed`.

当模拟判定某笔交易装不下时，Rome 会将其 **迭代执行** 为多笔 Solana 交易，而其中的 legacy CPI 随后会失败。将 deposit 和 withdraw 都控制为一次代币移动加一次进入你程序的 CPI，并把周围的 Solidity 代码保持精简。更大的操作应拆分为两笔用户交易。

CPI 深度：Solana 允许 4 层，而 Rome 使用了 1 层，因此你的指令运行在第 2 层，其下还有两层（你的程序 → SPL Token 还剩 1 层）。

## 6. 账户准备

你的程序在运行时不会从 Solidity 接收其账户。代理 **会模拟** 每笔交易，然后再发送，记录 CPI 触及的每一个 Solana 账户，并将它们放入 Solana 交易中。你的适配器在 `invoke_signed` 账户列表

* 中命名这些账户；模拟会证明它们可以解析成功。由此有三点： `你的指令触及的每一个账户都必须能够从适配器已拥有的输入中推导出来（它自身的 PDA 和子 PDA、你的程序 ID、mint、用户地址）。` 和 `SystemProgram.find_program_address` 在 Solidity 中完成这些派生。
* 尚不存在的账户（一个新仓位、一个新 ATA）也必须出现在账户列表中；其地址就是进入 Solana 交易的地址。
* 交易触及的一切——包括 Rome 为用户、适配器和包装器准备的账户——都必须控制在 64 个地址以内。一次调用触及十个市场的设计将无法装入。

对于 Solana 钱包通道， `rome_emulateCallAccounts` 会向客户端暴露相同的发现机制；SDK 会使用它。

CPI 绝不能命名的两个账户：提交交易的 Solana 费用支付者（除非是在普通 System 转账指令内部）以及 Rome 程序自身。指向 Rome 程序的 CPI 会被拒绝。

## 7. Solidity 中的存入与提取

一个在 legacy 路径上的适配器的最小示意。用户已经向 `approve_spl(adapter, amount, mint)` 发送给 HelperProgram（第 3 节）。 `PRIVACY_PROGRAM` 是你的程序 ID； `encodeDeposit` / `encodeWithdraw` 构造你的指令数据（Borsh、小端序）；账户元数据遵循你的指令布局。

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

contract PrivacyAdapter {
    ICrossProgramInvocation constant Cpi    = ICrossProgramInvocation(0xFF00000000000000000000000000000000000008);
    IHelperProgram          constant Helper = IHelperProgram(0xFF00000000000000000000000000000000000009);
    bytes32 constant SPL_TOKEN = 0x06ddf6e1d765a193d9cbe146ceeb79ac1cb485ed5f5b37913a8cf5857eff00a9; // TokenkegQ...

    bytes32 immutable PRIVACY_PROGRAM;
    bytes32 immutable USDC_MINT;

    constructor(bytes32 program, bytes32 mint) {
        PRIVACY_PROGRAM = program; USDC_MINT = mint;
        Helper.create_pda(address(this));                 // 适配器自身的 Solana 身份
        Helper.create_ata(address(this), USDC_MINT);      // 以及它拥有的一个 USDC 账户
    }

    function _salt(address user) internal pure returns (bytes32) { return bytes32(uint256(uint160(user))); }

    function deposit(uint64 amount) external {
        bytes32 self       = Helper.pda(address(this));                   // signer: the adapter's authority
        bytes32 adapterAta = Helper.ata(address(this), USDC_MINT);
        bytes32 position   = Helper.pda_with_salt(address(this), _salt(msg.sender)); // per-user sub-PDA, also signs

        // 从用户的代币账户拉取。适配器的授权以用户授予的 SPL 委托身份签名；这是一条 legacy 路径调用，和下面的 CPI 一样。
        // delegate the user granted; this is a legacy-track call, like the CPI below.
        Helper.transfer_spl(Helper.ata(msg.sender, USDC_MINT), adapterAta, amount, USDC_MINT);

        ICrossProgramInvocation.AccountMeta[] memory accs = new ICrossProgramInvocation.AccountMeta[](5);
        accs[0] = ICrossProgramInvocation.AccountMeta(self,       true,  true);
        accs[1] = ICrossProgramInvocation.AccountMeta(position,   true,  true);
        accs[2] = ICrossProgramInvocation.AccountMeta(adapterAta, false, true);                          // 来源：由适配器的授权拥有
        accs[3] = ICrossProgramInvocation.AccountMeta(_vaultFor(position), false, true);                 // 你程序的金库
        accs[4] = ICrossProgramInvocation.AccountMeta(SPL_TOKEN, false, false);

        bytes32[] memory salts = new bytes32[](1);
        salts[0] = _salt(msg.sender);
        Cpi.invoke_signed(PRIVACY_PROGRAM, accs, encodeDeposit(amount), salts);
    }

    function withdraw(uint64 amount) external {
        bytes32 position = Helper.pda_with_salt(address(this), _salt(msg.sender));
        bytes32 userAta  = Helper.ata(msg.sender, USDC_MINT);            // 目标：用户自己的账户
        // ... 形状相同：你的程序把 `amount` 从金库转到 userAta，由 `position` 签名
        Cpi.invoke_signed(PRIVACY_PROGRAM, accs, encodeWithdraw(amount), salts);
    }
}
```

适配器从不调用 `wUSDC` 该合约。拉取是对 HelperProgram 的一次调用，它会花费用户的委托，而代币存放在由 `external_auth(adapter)` 拥有的代币账户中，因此 CPI 才能使用这些代币。

关于签名者的说明。Rome 仅为两类账户签名：调用合约自身的裸授权（`Helper.pda(address(this))`），它无需出现在 `salts`中就可签名；以及每个 `salts`中的条目对应一个带盐的子 PDA。你列出的每个盐都必须作为签名者出现在账户列表中，否则调用会以 `根据提供的种子计算出的签名者账户未找到`而失败。任何其他被标记为签名者的账户，包括用户自身的授权，都不会从 Rome 获得种子，而 Solana 运行时会拒绝该 CPI。用户对其代币的权利来自委托，而不是来自适配器以用户身份签名。

无需拉取的委托：如果你的程序应该直接从用户的代币账户支出，用户应发送 `HelperProgram.approve_spl_raw_delegate(userAta, yourProgramPda, amount, mint, decimals)` 直接到 HelperProgram，并将你程序的 PDA 指定为 SPL 委托。Rome bridge 在 Wormhole 中就是这样使用它的。第 3 节的单一委托规则在此同样适用：该授权会取代包装器的授权。

## 8. 测试

* 请先部署到 **Hadrian** （testnet，链 200010）；地址和 RPC 位于 [合约地址](https://docs.rome.builders/zh/can-kao/contract-addresses.md) 以及 [注册表](https://github.com/rome-protocol/rome-registry).
* `eth_call` 和 `eth_estimateGas` 会运行与代理发送时相同的模拟，因此在那里失败的 CPI 会以相同原因在链上失败，而回滚数据会携带底层的 Solana 错误（`non-evm call error: …` ，位于 Solana 程序日志中）。
* 使用 `rome_solanaTxForEvmTx(hash)`读取一笔已落地的 EVM 交易在 Solana 侧的内容；Solana 收据中保存着 CU 和你程序的日志。
* 一个在 `eth_call` 中可用但发送时被拒绝的 CPI，通常触发了模拟报告的某个限制：64 地址上限、原子 CU 预算（交易变成了迭代执行），或者轨道规则。

## 9. 参考

* [预编译参考](https://docs.rome.builders/zh/can-kao/precompiles.md) —— 每个预编译上的每个 selector，连同其分发类别和 delegatecall 规则。
* [约束](https://docs.rome.builders/zh/he-xin-gai-nian/constraints.md) —— 将上述限制汇总成一张表。
* [代币互操作](https://docs.rome.builders/zh/he-xin-gai-nian/token-interop.md) —— 包装器、规范 mint、存入与提取。
* 公开仓库中的参考应用： [cardo](https://github.com/rome-protocol/cardo) （用户直接调用 CPI 预编译，形态 B）， [rome-dex](https://github.com/rome-protocol/rome-dex) （直接 `invoke` 再加一个无托管路由器，形态 C），以及 [aerarium](https://github.com/rome-protocol/aerarium) （一个基于共享市场的 Compound III 借贷应用；它不会从 Solidity 调用 Solana 程序（没有 CPI），因此不是适配器示例）。


---

# 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/kai-fa-zhe-zhi-nan/integrate-solana-program.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.
