> 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/ja/romenoapuri/bloom/building.md).

# Bloom 上での構築

このガイドが答えるのは1つの疑問です: **ビルダーはこれを自分でどう実現するのか？** Solidityの実世界資産コントラクトを取り上げ、Romeチェーン上に権限制御付きトークンとして立ち上げ、2つ目のトークンなしでSolanaウォレットにもEVMウォレットにも開放し、独自のKYC/コンプライアンス判定を組み込む。

対象読者は、この手法を評価する、または採用する開発者です。全体を通しての実例はBloomで、その稼働中資産 **ARCV（「Mineral Vault I」）** Hadrian上の（`200010`）は、以下の各手順の実例であり、そのデプロイ受領書（`deployments/200010.tokens/ARCV.json`）には、この方式が生成する正確な3つのコントラクトと8つのトランザクションが記録されています。

ここでは資産コントラクトは変更しません。BloomはPlumeのArcフレームワークを実行し **未変更のまま** （vendor提供のツリーは `contracts/`にあり、 `plumenetwork/contracts` の `NOTICE`にあるピン留め箇所とバイト単位で同一です）；Rome側の唯一のコントラクトは `ArcTokenFactoryV2`で、1つの関数だけを追加します。作業の中心は *どう* あなたがデプロイし、 *どう* あなたがコントラクトを動かすことであり、変更することではありません。

> **この手法をひと目で。** 権限制御付きトークンは **3つの** デプロイ済みコントラクトです。デプロイは **分割して** — 1トランザクションにつき1コントラクト — 行われます。1回のファクトリ呼び出しではRomeのトランザクションごとのアカウント上限を超えるためです。プロキシは **由来が固定されたアーティファクト** から作成しないと、オンチェーン登録はフェイルクローズします。コンプライアンスは各アドレスごとに1つの **真偽値**で、KYCプロセスが許可した人が書き込みます。そして同じデプロイは、Solanaウォレットから **合成送信者** をオンチェーンで導出して到達できます — 2つ目のトークンも、2つ目の許可リストも不要です。

## 前提条件

> **始める前に。** このガイドで使う発行者向けツールは、まだ公開されていません。対象はスクリプト（`deploy-infra.ts`, `create-token.ts` など）と、 `contracts/` および `rome-contracts/` のツリー、およびそれが参照するデプロイ受領書です。発行者はRomeへのオンボーディング時にこのツール群を受け取ります。それまでは、このガイドは手法と各スクリプトの役割を説明するものとして読んでください。

参照用ツールは `scripts/` ディレクトリにあります（オンボーディング時に提供されます。依存関係は `npm install`でインストールしてください）。各コマンドは、ハードコードせずレジストリからチェーン情報を解決するため、別のRomeチェーンへの切り替えはコード変更ではなく環境変更です:

```bash
export PRIVATE_KEY=…       # 対象チェーン上の資金付きデプロイ／発行者キー
export CHAIN_ID=200010     # チェーンを指定
export REGISTRY_ROOT=…     # Romeチェーンレジストリのチェックアウト先
# Solana系フローにはこれも必要です:
export SOLANA_KEYPAIR=…    # 資金付きSolanaキーペアJSONへのパス（手数料支払者）
```

Romeチェーン上のガスはUSDC建てです。デプロイ全体のコストはdevnetでおおむね10〜15ネイティブ単位です。鍵は環境変数からのみ受け取り、リポジトリには置きません。デプロイ前にまずコントラクトをビルドしてください。アーティファクトは **必ず** から `rome-contracts/out` （手順3を参照）:

```bash
cd contracts       && forge build --via-ir     # vendor提供のArcスイート
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + 正式なプロキシ
```

***

## 手順1 — 権限制御付きトークンであるとは *が* ここで

権限制御付きのBloomトークンは1つのコントラクトではありません。 **デプロイ済みの3つのコントラクト**に加え、運用チームがチェーンごとに1回だけデプロイし、各発行者が再利用する4つの共有コントラクトがあります。

**トークンごとの3つのコントラクト** — 1つの資産はちょうど次の3つを持ちます:

| コントラクト                       | ソース                                                         | 何か                                                          |
| ---------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | トークン本体 — 共有の `ArcToken` 実装を指すUUPSプロキシです。残高、保有者、ロールはここにあります。 |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | 許可リストモジュールです。アドレスごとに1つの真偽値を持ち、資産がゲートされている間はすべての送信で強制されます。   |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | 利回りモジュールです。保有には触れずに、利回り分配からアドレスを除外します。                      |

**チェーンごとに1回共有される4つのコントラクト** （によってデプロイされる `deploy-infra.ts`):

| コントラクト               | ロール                                       |
| -------------------- | ----------------------------------------- |
| `RestrictionsRouter` | モジュール種別レジストリ — チェーン接続情報で、運用チームが一度だけ設定します。 |
| `ArcTokenFactoryV2`  | 登録 + 正式なプロキシコードハッシュ（手順2〜3）。               |
| `ArcToken` （実装）      | すべてのトークンがプロキシする共有・再利用可能な資産ロジック。           |
| `ArcTokenPurchase`   | 全トークン・全発行者で共有される単一の販売窓口（手順4）。             |
| wUSDC                | 現金側のレッグ — 利回り通貨および売買通貨。                   |

送信制限と利回り制限は **意図的に別モジュール**です：保有者は資産を保持したまま収益だけを止められます。これは制裁や裁判所命令が実際に機能する仕組みです。

この「3つのコントラクト」という事実は、検証の要です。 `verify-deployments.ts` および `register-asset.ts` のどちらも、トークンがデプロイ済みの3つのコントラクトに解決されることを期待しています。1度だけ手動でトークンを検証した際、チェーン全体で7件を見落としました（すべての利回りモジュールと3つのホワイトリストモジュール）。

ライフサイクルは3段階と、1つの一方通行の扉があります:

```
ドラフト     プロキシは稼働中、モジュール未接続 — 何も送信をゲートしない
  ↓
非ゲート   モジュール接続済み、transfersAllowed = true   （WhitelistRestrictions.initialize がこれを設定）
  ↓  供給量をミントし、許可リストを構築               [可逆]
ゲート済み     setTransfersAllowed(false)                [一方通行の扉 — 供給量は確定する]
```

ミントとバーンは `address(0)` を相手側として通るため、供給量のゲートは一方通行です。 `address(0)` は許可リストに入れられないので、一度ゲートされると新規供給は二度とミントできません。これが権限制御付き資産が保有者に対して与える保証です。

***

## 手順2 — 1回のトランザクションとしてではなく、分割してデプロイする

Arcには、プロキシと両モジュールをデプロイし、1回の呼び出しで配線するワンショット版の `createToken` があります。 **Romeではこれを使えません。** そのトランザクションには **77のSolanaアカウントロック**が必要で、Romeの1トランザクションあたりの上限は **62ロック**です。調整しても、最適化パスを通しても、決して収まりません。

そのためデプロイは **分割して**：各コントラクトを個別のトランザクションで行い、トークンは `ArcTokenFactoryV2.registerToken` モノリシックな `createToken`の代わりに。これは作成ウィザードであり、発行者コンソールが手順ごとに行うものです:

![作成ウィザード](https://3990464069-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()`）で、アプリはこれを6枚のカード（`bloom/lib/createCards.ts`）として、 **8つのトランザクション**にわたり、コントラクトが強制するまさにその順序でレンダリングします:

| # | トランザクション        | コントラクト呼び出し                                                                    |
| - | --------------- | ----------------------------------------------------------------------------- |
| 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)`                                        |

スクリプト形式では1コマンドです:

```bash
# チェーンごとに1回（運用チームが実施、トークンごとではない）— 4つの共有コントラクトをデプロイ
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` と、ファクトリ経由のアップグレードが有効になります。

> **これを「最適化」してモノリスに戻さないでください。** 往復を節約するためにこれらの呼び出しを1つのトランザクションにまとめると、分割経路が避けるために存在するまさにその62ロック超過が再び起きます。同じ上限が、利回り分配が保有者を1人ずつトランザクションで処理する理由でもあります（手順8）。もし呼び出しが `アカウントが多すぎます: N > 62`で失敗したら、1つのトランザクションが多すぎるアカウントに触れています — 調整ではなく分割してください。

***

## 手順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`でフェイルクローズします。ここから2つの規則が導かれ、どちらも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` revertsしますが **ソース内の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` 販売窓口で動作します。販売を開始する前に満たすべき条件は3つあり、 `ArcTokenPurchase.enableToken` がそれぞれをオンチェーンでチェックします:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) あなたがトークンのADMIN_ROLEを保持している
{
    // (b) トークンはファクトリに認識されている必要があります — これが手順2のregisterTokenで得たものです:
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) 販売窓口はすでに販売在庫を保持している必要があります:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …価格と数量は正でなければなりません。
}
```

ゲートされた資産が強制する第4の暗黙要件があります。なぜなら **すべての送信が許可リストのゲートを通る**ので、在庫を販売窓口へ移すには、その販売窓口アドレス自体があなたのトークンで許可済みである必要があります。したがって、販売開始の完全な手順は次のとおりです:

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;   // ← アドレスごとに1つの真偽値。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` を提案しないでください。これはinitialize時に付与され、 **スイートのどこでもチェックされません** (`が権限の所在です）:` （これは何もゲートしない唯一のロールだとアサートします）。

`WhitelistRestrictions.initialize(issuer)` （ウィザードのtx 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)`）、決してキャッシュされた投影からではありません。書き込み先を間違ったモジュールに向けると、「あらゆる資産で承認」がかつて1つのトークンの許可リストに書き込んでしまった、という事態になります。

### ウォレット署名版（セルフサービスのデモ）

許可不要のテスト展開で、訪問者が自分で入場するなら、 `MANAGER_ROLE` に `TestApprover` (`rome-contracts/src/TestApprover.sol`）の `モジュール` が **不変**。その後 `approve(address)` は誰でも、自分のウォレットから、自分のガス代で呼び出せます。— それは `addToWhitelist` アドレスがまだ登録されていない場合にのみ:

```solidity
function approve(address account) external {
    IWhitelistRestrictions target = IWhitelistRestrictions(module);   // 不変 — 1つのモジュール、永遠に
    if (!target.isWhitelisted(account)) target.addToWhitelist(account);
    emit Approved(account, msg.sender);
}
```

これが「サインインゲート」です。何も保管せずに、訪問者に実際の仕組み（承認がオンチェーンの許可リスト項目になり、その後トークンがそれを強制する）を示します。 **絶対に付与しないでください `MANAGER_ROLE` に `TestApprover` 本番トークンに** — そのトークンの許可リストを許可不要にしてしまいます。

### ゲートが効くとき、そしてプロバイダを切り替えるとき

ゲートが制限をかけるのは、資産が **ゲート化された** (`setTransfersAllowed(false)`, `ADMIN_ROLE` モジュール上で）。ゲートされていない間は送金は開放されています。先に許可リストを作成し、その後ゲートしてください。ゲート後は、どちらか一方がリスト外の送金は型付きエラーでrevertします `TransferRestricted()` (`0xe827105e`).

> **後でKYCプロバイダを切り替えても、オンチェーン変更は不要です。** 許可リストモジュール、そのインターフェース、そして保持する真偽値はプロバイダ非依存です。ベンダーを切り替えるには、別の判定ソースを同じ `MANAGER_ROLE` 署名者に向けるだけです。再デプロイも、移行も、状態変更も不要です。チェーンはどのベンダーが呼び出したかは知らず、結果だけを知ります。

***

## 手順6 — 同じ資産をSolanaウォレットにも開放する

同じ3つのコントラクトにSolanaウォレットからアクセスできます **追加のトークンなしで**。SolanaネイティブのユーザーはEVMキーをどこにも持ちません。代わりに、そのEVM上のIDは *合成*で、トランザクションの実際の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])`。1つの許可リストが両方のウォレット世界をまたぎます。
2. **価値を動かす最初の呼び出しの前に、署名用PDAを一度だけ用意します。** 合成アドレスに代わって署名する外部権限PDAは先に存在している必要があり、その作成は1回の `create_pda` 呼び出しです。どちら側からでも送れます。ユーザー自身のSolanaウォレットからレーン経由で（SDKの `buildCreatePdaCall`、〜の後で `isSyntheticProvisioned` がfalseを返した後）、またはEVMキーから発行者が送ります。Bloomの発行者ツールは、現在は保有者のオンボーディングの一部としてこれを送信しています。アプリはまだユーザーの最初のアクションでこれを行わないため、保有者の最初の買い注文の前に用意してください。SDK呼び出しを使った方法は [デュアルレーンアプリ](https://docs.rome.builders/ja/gaido/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **手作業ではなく、レーンライブラリ経由で送信してください。** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`）は、チェーンのプロキシにトランザクションの組み立てを依頼し、手組みでは間違えがちな点を処理します。レーン上のすべてのコントラクト呼び出しは **プロキシが組み立てたSolana v1トランザクション** (`rome_composeUnsignedAtomicV1`）で、アドレスルックアップテーブルはありません。レーンライブラリは、古い形式にフォールバックするのではなく、閉じた状態で失敗します。手順5の現金化の動きは、コントラクト呼び出しではなく、アプリ自身が組み立てる別のSolanaトランザクションです。
   * **アカウント探索とcompute budgetはプロキシの役目です。** それは呼び出しをエミュレートし、各アカウントの書き込み可否を決定し（呼び出しの `value` はエミュレーション対象の一部なので渡してください）、返すトランザクションにcomputeとheapの予算を設定します。あなたのコードがcompute-budget命令を組み立てたり、fee-poolアカウントを追加したりすることはありません。
   * **1回の呼び出しにつき2回の署名、どちらもSolana鍵からです。** ウォレットはまず、人が読める認可メッセージに署名します（*Rome認可* と未署名のEIP-1559ペイロードのハッシュ。Wallet Standard `solana:signMessage`）を、プロキシが呼び出しを組み立てる前に検証します。次に、プロキシが返すv1トランザクションに署名します（`solana:signTransaction` 生のワイヤ上で）。レーンライブラリはこれらを `signAuthHash` および `signV1Wire`として扱い、1つにまとめたメソッドにはしません。これを基盤にする前に、ウォレットがv1トランザクションに署名できることを確認してください。現時点ではSolflareはdevnetで対応しており、Phantomはまだです。
   * **アプリが署名済みトランザクションをSolana RPCへ自分で送信します。** プロキシは組み立てるだけで、アトミックな呼び出しをブロードキャストしません。
   * **署名を求める前に検証してください。** レーンライブラリは組み立て済みメッセージを解析し、トランザクションのプロンプト前に不正なものを拒否します。
4. **一度だけのラッパー付与は、最初のwUSDC支出の前に行ってください。** wUSDCはユーザーのSPLデリゲートとしてユーザーのトークンを動かすため、一度も付与されていない合成アドレスはSPLエラーを受けます `0x4` 最初のwUSDC送金時に。読み取る `isEnabled(user)` ラッパー上で、falseのときは先頭に `なら、ユーザーに再度` Helperプリコンパイルへの呼び出しを実行の最初の区間として追加してください。どちらのレーンでも通常の呼び出しで、ウォレットごとに1回です。参照: [各ユーザーがこれを行っている必要があります。参照](https://docs.rome.builders/ja/ji-ben-gai-nian/token-interop.md#one-time-grant-per-wallet).
5. **それを使う呼び出しの前に現金を移してください。** 合成アドレスは静止時には何も保持しません。呼び出しが使う量よりwUSDCが少ない場合は、まずウォレット自身のUSDCトークン口座から不足分を移します（合成のトークン口座を冪等に作成し、次にRomeプログラムのactivate-token-account命令を実行して、EVMを動かさずにトークンを移動します）。これは1回のプロンプトで署名される1つのSolanaトランザクションであり、合成アドレスがすでに十分持っている場合はスキップされます。
6. **アトミックコンポーザーが拒否したものだけをリレーしてください。** 1つのSolanaトランザクションに収まらない呼び出し（約140万compute units、64アカウント、4KB）は、コンポーザーによって次のエラーで拒否されます *external atomic plan requires iterative composition*。その拒否があった場合にのみ、決してそれ以前ではなく、呼び出してください `rome_relayUnsignedV1` 同じ認可署名を使って。プロキシがこれを組み立てて送信し、Solana手数料を支払い、EVMトランザクションハッシュ（Solana署名ではありません）を返します。合成アドレスはチェーンのネイティブガスをweiで支払うため、残高が `gasLimit x maxFeePerGas`の場合は、まず `rome_composeExternalDepositV1` （ウォレット署名のv1トランザクション。金額は10^12 weiの倍数である必要があります）。実際にはウォレットごとに1回です。revert、ネットワーク障害、署名拒否などの他のエラーは再スローされ、リレーされません。詳細は [中継呼び出しと長い呼び出し](https://docs.rome.builders/ja/gaido/call-evm-from-solana.md#relayed-calls-and-long-calls).

ユーザーが **fee payer** であり、直接呼び出しではSolanaウォレットからlamports（SOL）を支払います。彼らが管理する合成アドレスは資産を保持し、SOLは保持しません。各レーン送信の後は、次の送信前にEVM nonceをポーリングしてください。インデクサーはSolanaの確定にわずかに遅れるため、そうしないと次の呼び出しが、チェーンがすでに使ったnonceを元に組み立てられてしまいます。

> **まずアトミック、拒否されたらリレー。** すべての呼び出しのデフォルトは、ユーザーのウォレットで署名された、1つのSolanaトランザクション内で実行される1つのEVMトランザクションです。リレーは、収まらない呼び出しのための例外であり、好みに応じて選ぶ別ルートではありません。直接呼び出しは2回のプロンプト、リレー呼び出しは1回で、リレー呼び出しはlamportsではなくRome gasで支払われます。複数段階の流れ（承認してから購入）は、複数の完全な呼び出しであり、それぞれが独自のトランザクションで、1つの実行を複数トランザクションに分割したものではありません。

**なぜRWAが境界の外へ漏れ出せないのか。** 資産はEVM状態内に存在し、その残高はRome EVMプログラムのアカウント内のストレージです。そこには **SPLミントはありません** それを動かすSolanaネイティブなものもありません。レーンの資産移動プリミティブはSPLトークン口座に対して動作しますが、EVMストレージ残高にはそれがありません。Solana署名で表現できるあらゆる移動はトークンコントラクトへの呼び出しであり、そのコントラクトが許可リストゲートを実行します。資金付きのスイートは、EVM鍵で署名してもSolana鍵で署名しても、非ホワイトリストアドレスへの送金が同一にrevertすることを確認します。現金部分（wUSDC）は意図的な例外で、SPLに裏付けられており *は* ユーザー自身のトークン口座へ掃き出されます。

***

## 手順7 — デプロイ後に誰が権限を持つかを知る

`ArcToken.initialize` プロキシのコンストラクタ（tx 1）から実行され、役割を `msg.sender` — ウィザードの実行者、つまり発行者に付与します。以下を付与します **5つの** 役割を明示的に:

```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);
```

ビルダーが見落としてはならない2つの結果:

* **`MINTER_ROLE`, `BURNER_ROLE`、および `UPGRADER_ROLE` initialize時には付与されません。** 初期供給は内部でミントされます `初期化` （内部の `_mint`、役割は不要）ですが、後からの *後の* `mint` または `burn` では、発行者がまず自分自身にその役割を付与する必要があります。可能なのは、彼らが `DEFAULT_ADMIN_ROLE` （すべての役割の管理者です。\_setRoleAdmin を呼ぶものは何もないので、 `_setRoleAdmin`、そのため `DEFAULT_ADMIN_ROLE` 彼らがそれらすべてを管理するからです）。ただし、これは意図的な追加手順であり、常時有効な権限ではありません。
* **`UPGRADER_ROLE` factoryには決して付与されません。** factory仲介のアップグレード（`ArcTokenFactoryV2.upgradeToken`）には **factory自体が** 保有していることが必要です `UPGRADER_ROLE` トークン上での権限を。自分自身に付与しても何の意味もありません。その付与はfactoryが元に戻せない一方通行の扉なので、オプトインです。factory仲介のアップグレードを望むなら、 `grantRole(UPGRADER_ROLE, factory)` を明示的に行ってください。そうしない場合、発行者がトークンを直接アップグレードします。

21の権限からなる完全なモデル（6つのコントラクトにまたがる11の役割名。 同じ名前でもコントラクトごとに別の権限です）は、以下にコード化されています `が権限の所在です）:`。問い合わせます `rolesRequiredFor(contract, functionName)` 役割自身のコントラクトを読むのではなく、4つのストアフロント関数と両方のfactory関数が、次の場所にある権限によってゲートされているためです *異なる* コントラクトを通じて支払います。

***

## 手順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` 1トランザクションあたり** — 手順2と同じ62アカウント上限のため — 利回りは1トランザクションにつき1保有者ずつ巡回します（保有者1人あたり約318K gasを計測）。ホワイトリスト入りのすべての保有者、EVMでもSolanaネイティブでも、按分で受け取ります。参照スクリプトは `measure-yield-batch.ts` で、資金付きスモークの利回り手順がエンドツーエンドでそれを検証します。

```bash
# USAGE.mdの参照形式: nextIndexが0に折り返すまで、1トランザクションにつき1保有者を巡回
distributeYieldWithLimit(total, offset, 1)
```

***

## 手順9 — デプロイしたものを検証する

Romeではソースが自動送信されることはないので、検証は自分で実行する手順です。インフラでも新しいトークンでも、何かをデプロイした後は、読み取り専用・鍵不要・冪等な検証ツールを実行してください（すでに検証済みのコントラクトはスキップされるため、トークン発行後に再実行すると新しいものだけが検証されます）:

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

期待しているのは **3つの** トークンごとのコントラクト（proxy + 両方のモジュール）とインフラで、デプロイを失敗させる代わりに検証できなかったものを報告します。これを手作業で1回やったとき、7つのコントラクトを見落としました。

資産をRomeレジストリに登録すると、検証は **ゲート**であり、飾りではありません（`register-asset.ts`）: トークンが獲得するのは `apps/arc/<chain>.json` レコードです。含まれるのは `standard: arc-permissioned-erc20` と `transferRestriction` で、その許可リストゲートを名付けます。Sourcifyで3つのコントラクトすべてが検証された場合にのみです。そのレコードは事実をチェーンから読み取ります（ウィザードでデプロイされたトークンにはコミット済みレシートがありません）し、ローカルのレジストリのチェックアウトにのみ書き込みます。PRをマージするのは人の仕事です。

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # 検証 + レジストリレコードの準備
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # 読み取り専用プレビュー
```

ループ全体のエンドツーエンド証明 — 作成、ホワイトリスト登録、ゲート、両レーンでの販売、利回り分配 — を行うには、任意のチェーンに対して資金付きスモークを実行します:

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

***

## 手順10 — オフチェーンに残るものを知る

信頼モデルは意図的に率直であり、ビルダーも自分のユーザーに同じように示すべきです:

* **許可リストフラグは、オフチェーンでの判断です。** KYC/AMLはあなたのプロセス内で行われます。あなたのベンダー、あなたのルールです。チェーンが記録し強制するのは〜だけです *結果*, `isWhitelisted(addr)`.
* **オンチェーン状態は、アドレスごとの1つのブール値だけです。** 個人識別情報も、書類も、ID主張も、オンチェーン証明も、アドレスの所有者に関する暗号学的証明もありません。これはPlumeで使われるArcのモデルで、オンチェーンID標準（例: ERC-3643）の重い移転を、より軽い仕組みと発行者が保持する信頼と引き換えにしています。
* **復旧は発行者の権限であり、抜け道ではありません。** 失われたウォレット—EVMでもSolanaでも—は、代替アドレスをホワイトリストに追加し、必要なら自社の法的手続きの下でmint/burn/upgradeを使って復旧します（Arcには強制送金の組み込みプリミティブはありません）。したがって、発行者の鍵管理はコンプライアンス姿勢の一部です。
* **Bloom独自のリレーサービスはなく、カストディ面もありません。** ユーザーは両レーンで自分のガスを自分で保持します。アプリが運営するfee-payerサービスは鍵を保持することを意味し、RWA製品が追加すべきでない領域です。Solanaレーンの唯一のリレーはチェーンプロキシのもので、1回のトランザクションには大きすぎる呼び出し向けです。それでもユーザーは自分の署名で承認し、自分のRome gasで支払います。

***

## 参照: ツール群

すべてのスクリプトはツール群の `scripts/` ディレクトリから実行され、 `PRIVATE_KEY`, `CHAIN_ID`、および `REGISTRY_ROOT` がエクスポートされています。

| スクリプト                           | 何をするか                                              |
| ------------------------------- | -------------------------------------------------- |
| `deploy-infra.ts`               | チェーンごとに1回: wUSDC用に接続された4つの共有コントラクト。                |
| `create-token.ts`               | 段階的なウィザード — 8回のトランザクション、1つのトークン。                   |
| `rotate-factory.ts`             | コンパイラ/成果物の変更後に新しいfactoryをデプロイし、再接続します。             |
| `verify-artifact-provenance.ts` | デプロイ済みfactoryがあなたのproxy成果物を受け入れることを証明します（読み取り専用）。  |
| `verify-deployments.ts`         | Sourcifyでトークンごとの3つのコントラクト + インフラをすべて検証します（読み取り専用）。 |
| `register-asset.ts`             | 検証ゲートを通し、その後レジストリのコンプライアンス記録を準備します。                |
| `measure-yield-batch.ts`        | チェーン上でトランザクションごとの利回り上限を再測定します。                     |
| `smoke.ts`                      | 両レーンにまたがる資金付きエンドツーエンドスイート。                         |
| `sweep-synthetic-native.ts`     | 合成アカウントからネイティブガスを回収します（テスト整備）。                     |

より詳しい背景はこのガイドと併記されています: `docs/ARCHITECTURE.md` （レイヤー化されたアプリモデル）、 `docs/LANES.md` （2つのレーンとカストディ）、 `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/ja/romenoapuri/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.
