> 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-shang-de-ying-yong/bloom/building.md).

# 基于 Bloom 构建

本指南回答一个问题： **构建者如何自己完成这件事？** 取一个 Solidity 的现实世界资产合约，将其作为许可型代币部署到 Rome 链上，同时让 Solana 钱包和 EVM 钱包都能使用，而且不需要第二个代币，再接入你自己的 KYC/合规决策。

读者是正在评估或采用该方案的开发者。Bloom 始终是贯穿全文的实践示例——其在链上的资产 **ARCV（“Mineral Vault I”）** 在 Hadrian（`200010`）上是下述每一步的真实实例，其部署收据（`deployments/200010.tokens/ARCV.json`）记录了该方法生成的全部三个合约和八笔交易的精确详情。

这里没有任何内容会修改资产合约。Bloom 运行的是 Plume 的 Arc 框架 **未作修改** （在 `contracts/`中的 vendored 代码树，与 `plumenetwork/contracts` 在 `NOTICE`中的固定版本完全字节一致）；Rome 侧唯一的合约是 `ArcTokenFactoryV2`，它新增了一个函数。工作重点在于 *如何* 你如何部署以及 *如何* 你如何驱动这些合约——而不在于修改它们。

> **方法概览。** 许可型代币是 **三个** 已部署的合约。它是分步 **部署的** ——每个交易部署一个合约——因为一次性工厂调用会超出 Rome 的单笔交易账户上限。其代理必须来自 **来源锁定的制品** ，否则链上注册会以失败关闭。合规是一个 **每个地址一个布尔值**，由你的 KYC 流程授权者写入。而同一部署也可以通过 **合成发送方** 从 Solana 钱包触达——不需要第二个代币，也不需要第二份允许名单。

## 前提条件

> **开始之前。** 本指南所使用的发行方工具尚未公开发布。这包括脚本（`deploy-infra.ts`, `create-token.ts` 以及其余部分）、 `contracts/` 和 `rome-contracts/` 代码树，以及其所命名的部署收据。发行方通过与 Rome 完成接入来获得这些工具。在那之前，请将本指南视为对该方法及各脚本作用的说明。

参考工具位于一个 `scripts/` 目录中（接入时提供；使用 `npm install`安装其依赖）。所有命令都从注册表读取链上事实，而不是硬编码，因此切换到另一条 Rome 链只是环境变更，而不是代码变更：

```bash
# 目标链上已注资的部署者/发行方私钥
# 选择链
# Rome 链注册表的检出副本
# Solana 通道流程还需要：
# 已注资的 Solana 密钥对 JSON 文件路径（手续费支付者）
```

Rome 链上的 Gas 以 USDC 计价；完整部署序列在 devnet 上大约消耗 10–15 个原生单位。密钥只来自环境变量——绝不来自仓库。部署前请先构建合约，因为制品 **必须** 来自 `rome-contracts/out` （见步骤 3）：

```bash
cd contracts       && forge build --via-ir     # vendored 的 Arc 套件
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + 标准代理
```

***

## 步骤 1——了解什么是许可型代币 *为* 在这里

许可型 Bloom 代币不是一个合约。它是 **三个已部署的合约**，外加四个共享合约，这些合约由运维团队每条链部署一次，之后每个发行方复用。

**每个代币对应的三个合约** ——一个资产恰好拥有以下这些：

| 合约                           | 源码                                                          | 它是什么                                               |
| ---------------------------- | ----------------------------------------------------------- | -------------------------------------------------- |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | 代币本体——一个指向共享 `ArcToken` 实现的 UUPS 代理。余额、持有人和角色都在这里。 |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | 白名单模块。每个地址一个布尔值；在资产受限时，每次转账都会强制执行。                 |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | 收益模块。将地址排除在收益分配之外，但不会影响其持仓。                        |

**四个共享的、每链一个的合约** （由 `deploy-infra.ts`):

| 合约                   | 角色                       |
| -------------------- | ------------------------ |
| `RestrictionsRouter` | 模块类型注册表——链路配置，由运维一次性设置。  |
| `ArcTokenFactoryV2`  | 注册 + 标准代理代码哈希（步骤 2–3）。   |
| `ArcToken` （实现）      | 所有代币都会代理到的共享、可复用资产逻辑。    |
| `ArcTokenPurchase`   | 一个统一门店，所有代币和发行方共享（步骤 4）。 |
| wUSDC                | 现金部分——收益货币和销售购买货币。       |

转账限制和收益限制是 **刻意分离的模块**：持有人可以被禁止获得收入，但仍保留资产，这正是制裁和法院命令在现实中的运作方式。

这个“三个合约”的事实对验证至关重要。 `verify-deployments.ts` 和 `register-asset.ts` 都要求一个代币解析为三个已部署合约——曾经有一次人工验证某个代币时，遗漏了其中七个合约（每个收益模块和三个白名单模块）。

生命周期分为三个阶段，并有一道单向门：

```
草稿     代理已上线，尚未关联模块——没有任何东西限制转账
  ↓
未受限   模块已关联，transfersAllowed = true   （WhitelistRestrictions.initialize 会设置这一点）
  ↓  铸造供应，构建允许名单               [可逆]
受限     setTransfersAllowed(false)                [单向门——供应量变为最终值]
```

之所以对供应量实行单向门限制，是因为铸造和销毁都以 `address(0)` 作为交易对手，而且 `address(0)` 永远不可能被加入白名单——因此一旦进入受限状态，便再也无法铸造新的供应量。这正是许可型资产对其持有人的保证。

***

## 步骤 2——分步部署，绝不一次性交易完成

Arc 提供了一个一键式 `createToken` ，可在一次调用中部署代理和两个模块并完成连接。 **在 Rome 上你不能使用它。** 该交易需要 **77 个 Solana 账户锁定**，而 Rome 的单笔交易上限是 **62 个锁定**。无论怎么调参、无论怎么做优化，它都不可能装得下。

因此部署必须 **部署的**：每个合约各自一笔交易，而代币通过 `ArcTokenFactoryV2.registerToken` 而不是通过单体式 `createToken`获得与工厂等同的状态。这就是创建向导，也是发行控制台逐步执行的内容：

![创建向导](https://4058553919-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-94683a3a49ac2418aed8cc66dbf47fad940814f7%2Fcreate-wizard.png?alt=media\&token=38b47568-d343-483d-8ce1-f437164bdeae)

参考实现是 `arc/plan/create.ts` (`createSequence()`），应用会将其渲染为六张卡片（`bloom/lib/createCards.ts`）对应的 **八笔交易**，顺序完全遵循合约约束：

| # | 交易       | 合约调用                                                                         |
| - | -------- | ---------------------------------------------------------------------------- |
| 1 | 部署资产     | `new ArcTokenProxy(impl, initData)` 其中 `initData = ArcToken.initialize(...)` |
| 2 | 部署白名单模块  | `new WhitelistRestrictions()`                                                |
| 3 | 将您设为其管理员 | `whitelist.initialize(issuer)`                                               |
| 4 | 在转账中强制执行 | `token.setRestrictionModule(TRANSFER, whitelist)`                            |
| 5 | 部署收益模块   | `new YieldBlacklistRestrictions()`                                           |
| 6 | 将您设为其管理员 | `yieldBlacklist.initialize(issuer)`                                          |
| 7 | 在收益中强制执行 | `token.setRestrictionModule(YIELD, yieldBlacklist)`                          |
| 8 | 在工厂中注册   | `factoryV2.registerToken(token, impl)`                                       |

脚本形式只需一条命令：

```bash
# 每条链一次性（运维执行，不是每个代币都执行）——部署四个共享合约
npx tsx deploy-infra.ts

# 每个代币一次——将向导以脚本形式重放
NAME="Mineral Vault I" SYMBOL=ARCV SUPPLY=1000000 DECIMALS=6 npx tsx create-token.ts
```

发行方（`PRIVATE_KEY`）签署每一笔交易，并最终持有代币的角色权限（`ArcToken.initialize` 授予给 `msg.sender` ——见步骤 7）。注册（tx 8）会解锁门店的 `enableToken` 以及任何经由工厂执行的升级。

> **不要把它“优化”回一个单体流程。** 为了减少往返而把这些调用批处理到一笔交易中，会重新引入分步路径原本就是为了避免的 62 锁溢出。同样的上限也是收益分发要每次只处理一个持有人（步骤 8）的原因。如果某次调用报错 `账户过多：N > 62`，说明一笔交易触及了太多账户——把它拆开，不要调参。

***

## 步骤 3——仅从来源锁定的制品部署代理

`registerToken` 是安全边界，使得分步部署可以安全进行。它只接受其 **运行时代码哈希与工厂在部署时内嵌的标准值匹配 `ArcTokenProxy`** 的代币：

```solidity
// rome-contracts/src/ArcTokenFactoryV2.sol
bytes32 private immutable CANONICAL_PROXY_CODEHASH =
    keccak256(type(ArcTokenProxy).runtimeCode);

function registerToken(address token, address implementation) external {
    if (token.codehash != CANONICAL_PROXY_CODEHASH) revert ProxyCodehashUnknown();
    // ……实现必须已被工厂列入白名单，而且 msg.sender 必须持有
    //    该代币的 ADMIN_ROLE，且该代币尚未注册。
}
```

因为这个代码哈希是 **不可变的**，由任何其他制品构建的代理都会以闭合失败的方式报错 `ProxyCodehashUnknown`。由此导出两条规则，而且这两条都由 CI 和 `CLAUDE.md`:

1. **中的硬性规则强制执行：代币代理必须从 `rome-contracts/out`** 部署——绝不能从 `contracts/out`，也绝不能从其他构建产物部署。工厂的标准代码哈希锁定的就是这次编译。
2. **`bytecode_hash = "none"` 和 `cbor_metadata = false`** 在 `rome-contracts/foundry.toml` 是至关重要的。开启元数据后，工厂中嵌入的 `ArcTokenProxy` 运行时 *内嵌* （`type().runtimeCode`）会携带与向导部署所用的独立 `out/` 制品不同的 CBOR/IPFS 尾部——因此链上 `registerToken` 会回滚，而 **所有源码内 Foundry 测试仍然通过** （Foundry 会同时嵌入两份副本，所以它看不出不匹配）。 `rome-contracts/test/ArtifactProvenance.t.sol` 固定验证了这一属性；最初正是带资金的运行发现了它。

> **源码内测试全部通过，并不能证明来源正确。** 在发布镜像之前，以及在任何编译器设置变更之后，请对 *已部署的* 工厂进行属性验证（只读，不需要密钥）：
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> 它会对你的本地 `ArcTokenProxy` 制品进行哈希，并断言该哈希原样出现在已部署工厂的字节码中。

如果编译器设置必须更改， **就轮换工厂** ——部署一个新的工厂，使其不可变变量固定新的代码哈希，并重新连接——而不是手工修补检查逻辑：

```bash
cd scripts && CHAIN_ID=<id> npx tsx rotate-factory.ts
```

轮换会在收据中保留旧地址；对旧工厂注册的代币必须在新工厂上重新注册。

***

## 步骤 4——通过共享门店开启销售

销售与创建是两回事，并且它运行在那个唯一共享的 `ArcTokenPurchase` 门店上。销售开启前必须满足三项条件，而 `ArcTokenPurchase.enableToken` 会在链上逐项检查：

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) 你持有该代币的 ADMIN_ROLE
{
    // (b) 该代币必须为工厂所知——这正是 registerToken（步骤 2）所获得的：
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) 门店必须已经持有待售库存：
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // ……价格和数量必须为正。
}
```

在一个 **共享**门店上，还有一个第四项、隐含的要求由受限资产强制施加：因为

1. **将门店加入白名单** 到你代币的白名单模块中（`batchAddToWhitelist([storefront])` ——见步骤 5）。没有这一步，（2）中的库存转移在 `TransferRestricted()` 受限后会回滚。
2. **将库存转移** 到门店地址（来自基础设施收据中的 `arcTokenPurchase`).
3. **`enableToken(token, amount, price)`** ——买家现在支付 wUSDC 并获得 RWA。

在一个 *共享* 门店上，提现拆分值得了解，而且它并不对称（`arc/roles.ts` 是权限来源）：

| 操作                                                         | 权限                                   | 持有者     |
| ---------------------------------------------------------- | ------------------------------------ | ------- |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | 该代币的 `ADMIN_ROLE` (`onlyTokenAdmin`) | 你，发行方   |
| `withdrawPurchaseTokens` （wUSDC 收益）                        | 门店的 `DEFAULT_ADMIN_ROLE`             | 谁部署了该门店 |

在自托管链上，你同时拥有这两项权限。在共享门店上，收益池属于所有发行方的销售收入，因此其提现属于平台级操作——设计结算时应围绕这一点，而不要假定你拥有单方面控制权。

***

## 步骤 5——接入你自己的 KYC / 合规

这是客户在同意前会阅读的部分，所以它是代码，而不是说明文字。 **合规由代币合约本身强制执行** ——而不是由链下审查器、排序器过滤器或场馆策略来执行。规则会随代币流转到任意执行路径上，在两个钱包通道中均如此。链上记录的是你 KYC 决策的 **结果** 结果，以单个布尔值表示：

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — 链上状态的完整表示
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← 每个地址一个布尔值。绝不存储 PII。
    bool transfersAllowed;                    // false = 受限；只有白名单地址才能转账
    EnumerableSet.AddressSet whitelistedAddresses;
}
```

### 你的流程写入的接口

你的 KYC 服务商的批准/拒绝决定会精确对应到以下调用之一：

```solidity
interface IWhitelistRestrictions {
    function addToWhitelist(address account) external;                  // 仅限 onlyRole(MANAGER_ROLE)
    function batchAddToWhitelist(address[] calldata accounts) external; // 仅限 onlyRole(MANAGER_ROLE)
    function removeFromWhitelist(address account) external;             // 仅限 onlyRole(MANAGER_ROLE)
    function isWhitelisted(address account) external view returns (bool);
    function setTransfersAllowed(bool allowed) external;                // 仅限 onlyRole(ADMIN_ROLE)
}
```

### 谁可以写入

> **批准所需的权限是 `MANAGER_ROLE` 在&#x20;*****模块*****&#x20;上——而不是 `ADMIN_ROLE` 在代币上。** `addToWhitelist` / `batchAddToWhitelist` / `removeFromWhitelist` 都属于 `onlyRole(MANAGER_ROLE)`，而该角色存在于 `WhitelistRestrictions` 实例上。先在代币上完成认证、再向模块写入，是本代码库已经付出代价的真实缺陷。不要把 `ADMIN_ROLE` 作为拒绝的修复方案——它在初始化时就已授予，且 `WHITELIST_ADMIN_ROLE` 在整个测试套件中从未被检查过 **（而且有断言表明它是那个不会限制任何内容的角色）。** (`arc/roles.ts` 。

`WhitelistRestrictions.initialize(issuer)` （向导的第 3 笔交易）授予发行方 `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`，以及 `UPGRADER_ROLE` 在该模块上的 `MANAGER_ROLE` 。因此发行方开箱即持有 `DEFAULT_ADMIN_ROLE`、一个 `grantRole(MANAGER_ROLE, serviceAccount)` ，并且还可以委托该权限：因为发行方持有

### 批准变成链上写入

将你的服务商 webhook 指向一个持有 `MANAGER_ROLE`的签名者，并在批准时批量处理这些地址：

```typescript
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';

// `signer` 必须在该代币的白名单模块上持有 MANAGER_ROLE。
const wallet = createWalletClient({ account, transport: http(chain.rpcUrl) });

// 服务商对这些地址给出了“已批准”：
await wallet.writeContract({
  address: whitelistModule,                 // 通过 getRestrictionModule 从代币中解析得到
  abi: whitelistAbi,
  functionName: 'batchAddToWhitelist',
  args: [approvedAddresses],
});
```

解析 `whitelistModule` 来自代币本身（`ArcToken.getRestrictionModule(TRANSFER_RESTRICTION_TYPE)`），绝不要来自缓存的投影——把写入发送到错误的模块，正是“对任意资产批准”曾经把某个代币的允许名单写错的原因。

### 钱包签名版本（自助演示）

对于一个无需许可的测试部署，让访客自行登记，请授予 `MANAGER_ROLE` 给一个 `TestApprover` (`rome-contracts/src/TestApprover.sol`），其 `模块` 为 **不可变的**。然后 `approve(address)` 可由任何人从自己的钱包调用，并自行支付 gas——它会调用 `addToWhitelist` ，前提是该地址尚未被列入：

```solidity
function approve(address account) external {
    IWhitelistRestrictions target = IWhitelistRestrictions(module);   // immutable — one module, forever
    if (!target.isWhitelisted(account)) target.addToWhitelist(account);
    emit Approved(account, msg.sender);
}
```

这就是“登录门禁”——它向访客展示真实机制（一个批准变成链上允许名单条目，随后由代币执行）而不托管任何资产。 **切勿在 `MANAGER_ROLE` 给一个 `TestApprover` 生产代币上授予** ——这会使该代币的允许名单变成无需许可。

### 当门禁生效，以及切换供应商

只有在资产 **被门禁保护** (`setTransfersAllowed(false)`, `ADMIN_ROLE` 于模块上）。在未门禁时，转账是开放的——先构建你的允许名单，然后再启用门禁。一旦启用门禁，任一方不在名单上的转账会以类型化错误回滚 `TransferRestricted()` (`0xe827105e`).

> **之后更换 KYC 供应商无需任何链上变更。** 允许名单模块、其接口以及它存储的布尔值都与供应商无关。要切换供应商，只需将另一个决策源指向同一个 `MANAGER_ROLE` 签名者——无需重新部署、无需迁移、无需状态变更。链上永远不知道是哪家供应商做出的调用，只知道结果。

***

## 第 6 步——将同一资产开放给 Solana 钱包

同样的三个合约可从一个 Solana 钱包访问 **，无需第二个代币**。Solana 原生用户在任何地方都没有 EVM 密钥；相反，他们的 EVM 身份是 *合成的*，由链上从交易的真实 Solana 签名者派生：

```
合成 EVM 地址 = keccak256(solana_pubkey)[12..32]
```

Rome EVM 程序直接从签名者本身推导该地址（`do_tx_unsigned::derive_sender`），因此无法伪造，而且不存在对应的 secp256k1 私钥—— **Solana 签名是唯一能够驱动该地址的东西**。参考实现见 `arc/materialise/solana/identity.ts` (`syntheticAddress`），与链上规则字节级兼容：

```typescript
export function syntheticAddress(pubkey: SolanaPubkeyInput): `0x${string}` {
  return `0x${keccak256(pubkeyBytes(pubkey)).slice(-40)}`;
}
```

**构建者为支持该通道所做的工作** ——注意 *其中没有任何一项属于合约变更*:

1. **按该 Solana 用户的合成地址将其加入允许名单。** 对合规层而言，合成地址就是普通地址：粘贴用户的 Solana 公钥，推导出合成地址，然后 `batchAddToWhitelist([synthetic])`。一份允许名单覆盖两个钱包世界。
2. **在他们第一次进行价值转移调用之前，先一次性准备好签名 PDA。** 用于为合成地址签名的外部权限 PDA 必须先存在，而创建它只需一次 `create_pda` 调用。任一方都可以发送它：用户自己的 Solana 钱包通过通道（SDK 的 `buildCreatePdaCall`，在 `isSyntheticProvisioned` 返回 false 之后），或者发行方通过 EVM 密钥。Bloom 的发行方工具今天会在为持有人完成入职时发送该调用；应用目前还不会在用户首次操作时自动执行，因此请在持有人首次购买前先完成配置。如何通过 SDK 调用完成，见 [双通道应用](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **通过通道库提交，不要手动提交。** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`）会让链的代理来组装交易，它会处理手工构造常见的错误。通道上的每次合约调用都是由代理组装的 **Solana v1 交易** (`rome_composeUnsignedAtomicV1`），不使用地址查找表；通道库在出错时会直接失败，而不会回退到旧格式。第 5 步中的现金注入是应用自行构建的单独 Solana 交易，不是组装出来的合约调用。
   * **账户发现和计算预算由代理负责。** 它会模拟该调用，决定每个账户是否可写（调用的 `value` 也属于模拟内容之一，所以要传入），并为它返回的交易设置计算和堆内存预算。你的代码不会构造计算预算指令，也不会添加 fee-pool 账户。
   * **每次调用需要两次签名，且都来自 Solana 密钥。** 钱包首先签署一条可读的授权消息（*Rome 授权* 加上未签名 EIP-1559 负载的哈希；Wallet Standard `solana:signMessage`），代理在组装调用前会先验证它。随后钱包再对代理返回的 v1 交易签名（`solana:signTransaction` ，按原始 wire 格式）。通道库将它们作为 `signAuthHash` 和 `signV1Wire`，而不是合并成一个方法。开始构建前，请确认你的钱包能够签署 v1 交易：Solflare 目前在 devnet 上可以，Phantom 还不行。
   * **应用会自行将已签名的交易发送到 Solana RPC。** 代理负责组装；它不会广播原子调用。
   * **在请求签名之前先验证。** 通道库会解析组装后的消息，并在交易提示之前拒绝格式错误的消息。
4. **在第一次 wUSDC 支出之前，先放置一次性的包装授权。** wUSDC 作为用户的 SPL 代理来移动其代币，因此从未被授予过的合成地址在首次 wUSDC 转账时会触发 SPL 错误 `0x4` 。阅读 `isEnabled(user)` 包装器上的 `approve_spl(wrapper, 2^64-1, mint)` ，当其为 false 时，先加上 [每个钱包一次性授权](https://docs.rome.builders/zh/he-xin-gai-nian/token-interop.md#one-time-grant-per-wallet).
5. **在花费它的调用之前先把现金转入。** 合成地址在静态时不持有任何资产。当其持有的 wUSDC 少于调用所花费的金额时，先从钱包自身的 USDC 代币账户补足差额（先幂等地创建合成地址的代币账户，然后调用 Rome 程序的激活代币账户指令，在不运行 EVM 的情况下转移代币）。这是一次 Solana 交易、一次提示签名；如果合成地址已经持有足够余额，则会跳过。
6. **只中继原子组合器拒绝的内容。** 无法装入单个 Solana 交易的调用（约 140 万计算单元、64 个账户、4 KB）会被组合器以 *外部原子计划需要迭代式组合*拒绝。只有在收到这一拒绝之后，且绝不在此前，才调用 `rome_relayUnsignedV1` ，并使用相同的授权签名：代理会组装并提交它，支付 Solana 费用，并返回一个 EVM 交易哈希（而不是 Solana 签名）。合成地址用 wei 支付链的原生 gas，因此当其余额低于 `gasLimit x maxFeePerGas`时，先用 `rome_composeExternalDepositV1` 补足（一个钱包签名的 v1 交易；金额必须是 10^12 wei 的整数倍），在实践中每个钱包一次即可。任何其他错误，如回滚、网络故障或拒绝签名，都会被重新抛出，而不是被中继。详情见 [转发调用和长调用](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/call-evm-from-solana.md#relayed-calls-and-long-calls).

用户是 **费用支付者** ，并通过自己的 Solana 钱包为直接调用支付 lamports（SOL）；其所控制的合成地址持有资产，但从不持有 SOL。每次通道发送后，在下一次发送前先轮询 EVM nonce——索引器比 Solana 确认略有滞后，否则下一次调用会基于一个链上已经使用过的 nonce 构建。

> **先原子执行，拒绝后再中继。** 每次调用的默认路径都是：在一个 Solana 交易内执行一个 EVM 交易，由用户的钱包签名。中继是针对无法装入的调用的例外，不是可按偏好选择的第二条路线：直接调用需要两次提示，中继调用只需要一次，而中继调用用的是 Rome gas 而不是 lamports。多步骤流程（先批准，再购买）是多个完整调用，每个调用各自构成一个交易，而不是一个执行被拆分到多个交易中。

**为什么 RWA 不会泄漏出边界。** 该资产驻留于 EVM 状态中——其余额是 Rome EVM 程序账户内的存储。它 **没有 SPL 铸币** 版本，也没有任何 Solana 原生可转移对象；通道的资产移动原语作用于 SPL 代币账户，而 EVM 存储余额并不具备这种账户。Solana 签名能够表达的每一种移动，最终都会成为一次对代币合约的调用，而该合约会执行允许名单门禁——已部署的测试套件断言：无论由 EVM 密钥还是 Solana 密钥签名，向未列入白名单地址的转账都会以相同方式回滚。现金侧（wUSDC）是刻意的例外：它有 SPL 支撑，并且 *并不会* 会被清扫回用户自己的代币账户。

***

## 第 7 步——部署后了解谁持有权限

`ArcToken.initialize` 由代理构造函数（交易 1）运行，并将角色授予给 `msg.sender` ——向导驱动者，即发行方。它明确授予 **五个** 角色：

```solidity
_grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
_grantRole(ADMIN_ROLE, msg.sender);
_grantRole(MANAGER_ROLE, msg.sender);
_grantRole(YIELD_MANAGER_ROLE, msg.sender);
_grantRole(YIELD_DISTRIBUTOR_ROLE, msg.sender);
```

构建者绝不能忽略的两个后果：

* **`MINTER_ROLE`, `BURNER_ROLE`，以及 `UPGRADER_ROLE` 并未在 initialize 时授予。** 初始供应是在 `初始化` 中铸造的（一个内部的 `_mint`，无需任何角色），但后续的 *销毁* `mint` 或 `需要发行方先把该角色授予自己。他们可以这么做，因为他们持有` （每个角色的管理员——没有任何地方调用 `DEFAULT_ADMIN_ROLE` \_setRoleAdmin `，所以`负责管理它们全部）。但这是一项有意的额外步骤，而不是一种随时可用的权限。 `DEFAULT_ADMIN_ROLE` 负责管理全部角色
* **`UPGRADER_ROLE` 从不授予给工厂。** 由工厂介导的升级（`ArcTokenFactoryV2.upgradeToken`）要求 **工厂本身** 持有 `UPGRADER_ROLE` 代币上的该角色——把它授予自己并不会产生任何作用。该授予是一扇单向门，工厂无法撤销，因此它是可选的：如果你希望使用工厂介导的升级， `grantRole(UPGRADER_ROLE, factory)` 请显式授予；否则由发行方直接升级代币。

完整的 21 权限模型（六个合约中的 11 个角色名称——相同名称在每个合约上都是不同的权限）已写入 `arc/roles.ts`。查询 `rolesRequiredFor(contract, functionName)` ，而不是读取某个角色自身所属的合约，因为四个 storefront 函数和两个 factory 函数都受制于一个位于 *不同* 合约在 Hadrian 上支付 2 USDC。

***

## 第 8 步——分发收益

代币以 wUSDC 支付收益（固定为 `初始化`，可通过 `setYieldToken` 低于 `YIELD_MANAGER_ROLE`更改）。分发会遍历持有人集合：

```solidity
function distributeYieldWithLimit(uint256 totalAmount, uint256 startIndex, uint256 maxHolders)
    external onlyRole(YIELD_DISTRIBUTOR_ROLE) nonReentrant
    returns (uint256 nextIndex, uint256 totalHolders, uint256 amountDistributed);
```

正确驱动它所需的关键机制：

* **完整的 `totalAmount` 仅在 `startIndex == 0` 窗口** (`safeTransferFrom(msg.sender, this, totalAmount)`时才从调用者那里拉取。先在第一个窗口之前向代币批准该总额；后续窗口从已持有的余额中支付。
* **`nextIndex` 在遍历完成时回绕到 `0` 。** 循环 `distributeYieldWithLimit(total, nextIndex, …)` 直到 `nextIndex` 再次返回 `0`.
* **受收益限制的持有人份额保留在代币合约中** ——它们被跳过，而不是重新分配。

> **在 Rome 上，实际上限是 `maxHolders = 1` 每笔交易** ——与第 2 步的 62 账户上限相同——因此收益按每笔交易一位持有人来遍历（每位持有人约耗 318K gas）。每位已列入白名单的持有人，无论 EVM 还是 Solana 原生，都会按比例获得；参考脚本是 `measure-yield-batch.ts` ，而已部署的 smoke 测试中的收益步骤会端到端断言这一点。

```bash
# USAGE.md 参考形式：每笔交易遍历一位持有人，直到 nextIndex 回绕到 0
distributeYieldWithLimit(total, offset, 1)
```

***

## 第 9 步——验证你部署的内容

Rome 不会自动将源代码提交到任何地方，因此验证是你需要亲自运行的一步。完成任何部署后——无论是基础设施还是新代币——都要运行这个只读、无密钥、幂等的验证器（已验证的合约会被跳过，因此在发行代币后重新运行只会验证新增内容）：

```bash
cd scripts && CHAIN_ID=<id> npx tsx verify-deployments.ts
```

它期望 **三个** 每个代币对应的合约（代理 + 两个模块）以及基础设施，并会报告哪些内容无法验证，而不是让部署失败。曾经手动做这一步时漏掉了七个合约。

将资产注册到 Rome 注册表时，会把验证视为一个 **门禁**，而不是装饰（`register-asset.ts`）：一个代币只有在其全部三个合约都已在 Sourcify 上验证后，才会获得其 `apps/arc/<chain>.json` 记录——其中包含 `standard: arc-permissioned-erc20` 以及一个 `transferRestriction` ，用于命名其允许名单门禁——。该记录会从链上读取事实（由向导部署的代币没有已提交的收据），并且只写入本地注册表检出；最终合并 PR 是人的工作。

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # 验证 + 准备注册表记录
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # 只读预览
```

要获得整个流程的端到端证明——创建、加入白名单、启用门禁、在两个通道上卖出、分发收益——请在任意链上运行已资助的 smoke 测试：

```bash
PRIVATE_KEY=… CHAIN_ID=… SOLANA_KEYPAIR=… npx tsx smoke.ts
```

***

## 第 10 步——了解哪些内容保持链下

信任模型是有意保持诚实的，构建者也应当以同样方式向自己的用户呈现它：

* **允许名单标志是你链下的决定。** KYC/AML 发生在你的流程中——你的供应商、你的规则。链上只记录并执行 *结果*, `isWhitelisted(addr)`.
* **每个地址一个布尔值。** 没有 PII、没有文件、没有身份声明、没有链上证明、也没有关于某地址属于谁的密码学证明。这是 Arc 在 Plume 上使用的模型；它用较轻的机制和由发行方持有的信任，取代了链上身份标准（例如 ERC-3643）中更重的转移机制。
* **恢复权限属于发行方，而不是逃生通道。** 丢失的钱包——无论 EVM 还是 Solana——都可通过将替代地址加入白名单来恢复，如有必要，还可在你自己的法律流程下使用 mint/burn/upgrade（Arc 没有内置强制转移原语）。因此，发行方的密钥托管是合规姿态的一部分。
* **没有 Bloom 自己的中继器，也没有托管面。** 用户在两个通道上都持有自己的 gas。若由应用运行一个 fee-payer 服务，就意味着持有密钥——这是 RWA 产品不应增加的攻击面。Solana 通道上的那一次中继属于链代理，仅用于无法装入单个交易的调用；用户仍然使用自己的签名授权它，并以自己的 Rome gas 支付。

***

## 参考：工具集

每个脚本都从工具集的 `scripts/` 目录运行，并导出了 `PRIVATE_KEY`, `CHAIN_ID`，以及 `REGISTRY_ROOT` 。

| 脚本                              | 功能                                    |
| ------------------------------- | ------------------------------------- |
| `deploy-infra.ts`               | 每条链一次：四个共享合约，按 wUSDC 配置。              |
| `create-token.ts`               | 分步骤向导——八笔交易，一个代币。                     |
| `rotate-factory.ts`             | 在编译器/制品发生变化后部署一个新的工厂；重新连接。            |
| `verify-artifact-provenance.ts` | 证明你的代理制品可被已部署的工厂接受（只读）。               |
| `verify-deployments.ts`         | 在 Sourcify 上验证每个代币的全部三个合约 + 基础设施（只读）。 |
| `register-asset.ts`             | 验证门禁，然后准备注册表合规记录。                     |
| `measure-yield-batch.ts`        | 在某条链上重新测量每笔交易的收益上限。                   |
| `smoke.ts`                      | 覆盖两个通道的已资助端到端套件。                      |
| `sweep-synthetic-native.ts`     | 从合成账户中回收原生 gas（测试卫生）。                 |

更深入的背景资料与本指南并列： `docs/ARCHITECTURE.md` （分层应用模型）， `docs/LANES.md` （两个通道与托管）， `docs/COMPLIANCE.md` （信任模型），以及 `docs/USAGE.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-shang-de-ying-yong/bloom/building.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.
