> 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/apps-on-rome/bloom/building.md).

# Building on Bloom

This guide answers one question: **how does a builder do this themselves?** Take a Solidity real-world-asset contract, stand it up on a Rome chain as a permissioned token, open it to Solana wallets as well as EVM wallets with no second token, and plug in your own KYC/compliance decision.

The audience is a developer evaluating or adopting the approach. Bloom is the worked example throughout — its live asset **ARCV ("Mineral Vault I")** on Hadrian (`200010`) is a real instance of every step below, and its deploy receipt (`deployments/200010.tokens/ARCV.json`) records the exact three contracts and eight transactions this method produces.

Nothing here modifies the asset contracts. Bloom runs Plume's Arc framework **unmodified** (the vendored tree in `contracts/`, byte-identical to `plumenetwork/contracts` at the pin in `NOTICE`); the only Rome-side contract is `ArcTokenFactoryV2`, which adds one function. The work is in *how* you deploy and *how* you drive the contracts — not in changing them.

> **The method, at a glance.** A permissioned token is **three** deployed contracts. It is deployed **piecewise** — one contract per transaction — because a one-transaction factory call exceeds Rome's per-transaction account cap. Its proxies must come from **provenance-locked artifacts** or on-chain registration fails closed. Compliance is one **boolean per address**, written by whoever your KYC process authorises. And the same deployment is reachable from a Solana wallet through a **synthetic sender** derived on-chain — no second token, no second allowlist.

## Prerequisites

> **Before you start.** The issuer tooling this guide uses is not published yet. That covers the scripts (`deploy-infra.ts`, `create-token.ts` and the rest), the `contracts/` and `rome-contracts/` trees, and the deploy receipts it names. Issuers get this tooling by onboarding with Rome. Until then, read the guide as a description of the method and of what each script does.

The reference tooling lives in a `scripts/` directory (provided at onboarding; install its dependencies with `npm install`). Every command resolves chain facts from the registry rather than hardcoding them, so retargeting another Rome chain is an environment change, not a code change:

```bash
export PRIVATE_KEY=…       # funded deployer/issuer key on the target chain
export CHAIN_ID=200010     # picks the chain
export REGISTRY_ROOT=…     # a checkout of the Rome chain registry
# Solana-lane flows also need:
export SOLANA_KEYPAIR=…    # path to a funded Solana keypair JSON (the fee payer)
```

Gas on Rome chains is USDC-denominated; the full deploy sequence costs on the order of 10–15 native units on devnet. Keys come from the environment only — never the repo. Build the contracts once before deploying, because artifacts **must** come from `rome-contracts/out` (see step 3):

```bash
cd contracts       && forge build --via-ir     # the vendored Arc suite
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + the canonical proxy
```

***

## Step 1 — Know what a permissioned token *is* here

A permissioned Bloom token is not one contract. It is **three deployed contracts**, plus four shared contracts that ops deploys once per chain and every issuer reuses.

**The three per-token contracts** — one asset owns exactly these:

| Contract                     | Source                                                      | What it is                                                                                                                |
| ---------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | The token itself — a UUPS proxy pointing at the shared `ArcToken` implementation. Balances, holders, and roles live here. |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | The allowlist module. One boolean per address; enforced on every transfer while the asset is gated.                       |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | The yield module. Excludes addresses from yield distributions without touching their holding.                             |

**The four shared, one-per-chain contracts** (deployed by `deploy-infra.ts`):

| Contract                    | Role                                                       |
| --------------------------- | ---------------------------------------------------------- |
| `RestrictionsRouter`        | Module-type registry — chain wiring, set once by ops.      |
| `ArcTokenFactoryV2`         | Registration + the canonical proxy codehash (steps 2–3).   |
| `ArcToken` (implementation) | The shared, reusable asset logic every token proxies to.   |
| `ArcTokenPurchase`          | One storefront, shared by every token and issuer (step 4). |
| wUSDC                       | The cash leg — yield currency and sale-purchase currency.  |

Transfer restriction and yield restriction are **deliberately separate modules**: a holder can be barred from income while keeping the asset, which is how sanctions and court orders actually work.

This "three contracts" fact is load-bearing for verification. `verify-deployments.ts` and `register-asset.ts` both expect a token to resolve to three deployed contracts — verifying a token by hand once missed seven of them across a chain (every yield module and three whitelist modules).

The lifecycle has three phases and a one-way door:

```
draft     proxy live, no module linked — nothing gates a transfer
  ↓
ungated   module linked, transfersAllowed = true   (WhitelistRestrictions.initialize sets this)
  ↓  mint supply, build the allowlist               [reversible]
gated     setTransfersAllowed(false)                [ONE-WAY DOOR — supply becomes final]
```

Gating is one-way for supply because mint and burn pass `address(0)` as the counterparty, and `address(0)` can never be allowlisted — so once gated, no new supply can ever be minted. That is the guarantee a permissioned asset makes to its holders.

***

## Step 2 — Deploy it piecewise, never as one transaction

Arc ships a one-shot `createToken` that deploys the proxy and both modules and wires them in a single call. **On Rome you cannot use it.** That transaction needs **77 Solana account locks**, and Rome's per-transaction cap is **62 locks**. It can never fit — not with tuning, not with an optimizer pass.

So the deploy is **piecewise**: each contract in its own transaction, and the token gains factory-equivalent status through `ArcTokenFactoryV2.registerToken` instead of the monolithic `createToken`. This is the create wizard, and it is what the issuer console does step by step:

![the create wizard](https://2654533989-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)

The reference implementation is `arc/plan/create.ts` (`createSequence()`), which the app renders as six cards (`bloom/lib/createCards.ts`) over **eight transactions**, in the exact order the contracts force:

| # | Transaction                  | Contract call                                                                   |
| - | ---------------------------- | ------------------------------------------------------------------------------- |
| 1 | Deploy the asset             | `new ArcTokenProxy(impl, initData)` where `initData = ArcToken.initialize(...)` |
| 2 | Deploy the allowlist module  | `new WhitelistRestrictions()`                                                   |
| 3 | Set you as its administrator | `whitelist.initialize(issuer)`                                                  |
| 4 | Enforce it on transfers      | `token.setRestrictionModule(TRANSFER, whitelist)`                               |
| 5 | Deploy the yield module      | `new YieldBlacklistRestrictions()`                                              |
| 6 | Set you as its administrator | `yieldBlacklist.initialize(issuer)`                                             |
| 7 | Enforce it on yield          | `token.setRestrictionModule(YIELD, yieldBlacklist)`                             |
| 8 | Register with the factory    | `factoryV2.registerToken(token, impl)`                                          |

The script form is one command:

```bash
# one-time per chain (ops, not per token) — deploys the four shared contracts
npx tsx deploy-infra.ts

# per token — the wizard, replayed as a script
NAME="Mineral Vault I" SYMBOL=ARCV SUPPLY=1000000 DECIMALS=6 npx tsx create-token.ts
```

The issuer (`PRIVATE_KEY`) signs every transaction and ends up holding the token's roles (`ArcToken.initialize` grants to `msg.sender` — see step 7). Registration (tx 8) is what unlocks the storefront's `enableToken` and any factory-mediated upgrade.

> **Do not "optimize" this back into a monolith.** Batching these calls into one transaction to save round-trips reintroduces exactly the 62-lock overflow the piecewise path exists to avoid. The same cap is why yield distribution walks one holder per transaction (step 8). If a call fails with `Too many accounts: N > 62`, one transaction is touching too many accounts — split it, don't tune it.

***

## Step 3 — Deploy proxies only from the provenance-locked artifacts

`registerToken` is the security boundary that lets piecewise deploys be safe. It will only accept a token whose **runtime codehash matches the canonical `ArcTokenProxy`** baked into the factory at deploy time:

```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();
    // …implementation must be factory-whitelisted, and msg.sender must hold the
    //    token's ADMIN_ROLE, and the token must not already be registered.
}
```

Because that codehash is an **immutable**, a proxy built from any other artifact fails closed with `ProxyCodehashUnknown`. Two rules follow, and both are enforced by CI and the hard rules in `CLAUDE.md`:

1. **Token proxies MUST be deployed from `rome-contracts/out`** — never from `contracts/out`, never from a different build. That is the compilation the factory's canonical codehash pins.
2. **`bytecode_hash = "none"` and `cbor_metadata = false`** in `rome-contracts/foundry.toml` are load-bearing. With metadata enabled, the `ArcTokenProxy` runtime *embedded* in the factory (`type().runtimeCode`) carries a different CBOR/IPFS tail than the standalone `out/` artifact the wizard deploys from — so on-chain `registerToken` reverts while **every in-source Foundry test passes** (Foundry embeds both copies, so it can't see the mismatch). `rome-contracts/test/ArtifactProvenance.t.sol` pins this property; the funded run is what originally caught it.

> **A green in-source suite does not prove provenance.** Before shipping an image, and after ANY compiler-setting change, prove the property against the *deployed* factory (read-only, no keys):
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> It hashes your local `ArcTokenProxy` artifact and asserts that hash appears verbatim inside the deployed factory's bytecode.

If compiler settings must change, **rotate the factory** — deploy a fresh one whose immutable pins the new codehash, and re-wire — rather than hand-patching the check:

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

Rotation retains the old address in the receipt; tokens registered against the old factory must re-register against the new one.

***

## Step 4 — Open a sale through the shared storefront

Selling is a separate act from creating, and it runs on the one shared `ArcTokenPurchase` storefront. Three things must be true before a sale opens, and `ArcTokenPurchase.enableToken` checks each on-chain:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) you hold the token's ADMIN_ROLE
{
    // (b) the token must be factory-known — this is what registerToken (step 2) bought:
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) the storefront must already hold the sale inventory:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …price and count must be positive.
}
```

There is a fourth, implicit requirement that a gated asset forces: because **every transfer runs the allowlist gate**, moving inventory to the storefront only succeeds if the storefront address is itself whitelisted on your token. So the full open-a-sale sequence is:

1. **Whitelist the storefront** on your token's whitelist module (`batchAddToWhitelist([storefront])` — see step 5). Without this, the inventory transfer in (2) reverts `TransferRestricted()` once gated.
2. **Transfer inventory** to the storefront address (from the infra receipt's `arcTokenPurchase`).
3. **`enableToken(token, amount, price)`** — buyers now pay wUSDC and receive the RWA.

The withdrawal split is worth knowing on a *shared* storefront, and it is not symmetric (`arc/roles.ts` is the authority):

| Action                                                     | Authority                                   | Held by                         |
| ---------------------------------------------------------- | ------------------------------------------- | ------------------------------- |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | the token's `ADMIN_ROLE` (`onlyTokenAdmin`) | you, the issuer                 |
| `withdrawPurchaseTokens` (the wUSDC proceeds)              | the storefront's `DEFAULT_ADMIN_ROLE`       | whoever deployed the storefront |

On a self-hosted chain you are both. On a shared storefront the proceeds pool is every issuer's takings, so its withdrawal is platform-level — design your settlement around that rather than assuming unilateral control.

***

## Step 5 — Plug in your own KYC / compliance

This is the section a customer reads before saying yes, so it is code, not prose. **Compliance is enforced by the token contract itself** — not by an off-chain screen, a sequencer filter, or a venue policy. The rules travel with the token to any execution path, on both wallet lanes. What the chain records is the **outcome** of your KYC decision, as a single boolean:

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — the on-chain state, in full
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← one boolean per address. No PII, ever.
    bool transfersAllowed;                    // false = gated; only whitelisted addresses transfer
    EnumerableSet.AddressSet whitelistedAddresses;
}
```

### The interface your process writes to

Your KYC vendor's approve/deny decision becomes exactly one of these calls:

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

### Who may write

> **The authority an approval needs is `MANAGER_ROLE` on the&#x20;*****module*****&#x20;— not `ADMIN_ROLE` on the token.** `addToWhitelist` / `batchAddToWhitelist` / `removeFromWhitelist` are all `onlyRole(MANAGER_ROLE)`, and that role lives on the `WhitelistRestrictions` instance. Authenticating `ADMIN_ROLE` on the token and then writing to the module is a real defect this codebase has already paid for. Do not offer `WHITELIST_ADMIN_ROLE` as the fix for a refusal — it is granted at initialize and **checked nowhere in the suite** (`arc/roles.ts` asserts it is the one role that gates nothing).

`WhitelistRestrictions.initialize(issuer)` (tx 3 of the wizard) grants the issuer `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`, and `UPGRADER_ROLE` on that module. So the issuer holds `MANAGER_ROLE` out of the box and can also delegate it: because the issuer holds `DEFAULT_ADMIN_ROLE`, a `grantRole(MANAGER_ROLE, serviceAccount)` hands the write to a backend signer.

### A decision becoming an on-chain write

Point your vendor's webhook at a signer that holds `MANAGER_ROLE`, and on an approve, batch the addresses:

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

// `signer` must hold MANAGER_ROLE on THIS token's whitelist module.
const wallet = createWalletClient({ account, transport: http(chain.rpcUrl) });

// vendor said "approved" for these addresses:
await wallet.writeContract({
  address: whitelistModule,                 // resolved FROM the token via getRestrictionModule
  abi: whitelistAbi,
  functionName: 'batchAddToWhitelist',
  args: [approvedAddresses],
});
```

Resolve `whitelistModule` from the token itself (`ArcToken.getRestrictionModule(TRANSFER_RESTRICTION_TYPE)`), never from a cached projection — aiming a write at the wrong module is how "approve on any asset" once wrote to one token's allowlist.

### The wallet-signed variant (self-serve demo)

For a permissionless test deployment where visitors admit themselves, grant `MANAGER_ROLE` to a `TestApprover` (`rome-contracts/src/TestApprover.sol`) whose `module` is **immutable**. Then `approve(address)` is callable by anyone, from their own wallet, paying their own gas — it calls `addToWhitelist` only if the address is not already listed:

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

This is the "sign-in gate" — it shows a visitor the real mechanism (an approval becoming an on-chain allowlist entry the token then enforces) without custodying anything. **Never grant `MANAGER_ROLE` to a `TestApprover` on a production token** — it makes that token's allowlist permissionless.

### When the gate bites, and swapping providers

The gate only restricts once the asset is **gated** (`setTransfersAllowed(false)`, `ADMIN_ROLE` on the module). While ungated, transfers are open — build your allowlist first, then gate. Once gated, a transfer where either side is off the list reverts with the typed error `TransferRestricted()` (`0xe827105e`).

> **Swapping KYC providers later requires no on-chain change.** The allowlist module, its interface, and the boolean it stores are provider-agnostic. To switch vendors, point a different decision source at the same `MANAGER_ROLE` signer — no redeploy, no migration, no state change. The chain never knew which vendor made the call, only the outcome.

***

## Step 6 — Open the same asset to Solana wallets

The same three contracts are reachable from a Solana wallet **with no second token**. A Solana-native user has no EVM key anywhere; instead their EVM identity is *synthetic*, derived on-chain from the transaction's actual Solana signer:

```
synthetic EVM address = keccak256(solana_pubkey)[12..32]
```

The Rome EVM program derives this from the signer itself (`do_tx_unsigned::derive_sender`), so it cannot be spoofed and no secp256k1 private key for it exists — **the Solana signature is the only thing that can ever drive this address**. The reference derivation is `arc/materialise/solana/identity.ts` (`syntheticAddress`), byte-compatible with the on-chain rule:

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

**What a builder does to support the lane** — note that *none of it is a contract change*:

1. **Whitelist the Solana user by their synthetic address.** To the compliance layer a synthetic address is an ordinary address: paste the user's Solana pubkey, derive the synthetic, and `batchAddToWhitelist([synthetic])`. One allowlist spans both wallet worlds.
2. **Provision the signing PDA once, before their first value-moving call.** The external-authority PDA that signs for a synthetic must exist first, and creating it is one `create_pda` call. Either side can send it: the user's own Solana wallet through the lane (the SDK's `buildCreatePdaCall`, after `isSyntheticProvisioned` returns false), or the issuer from an EVM key. Bloom's issuer tooling sends it today as part of onboarding a holder; the app does not yet do it on the user's first action, so provision before the holder's first buy. How, with the SDK calls, is in [Dual-lane app](https://docs.rome.builders/developer-guides/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **Submit through the lane library, not by hand.** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`) asks the chain's proxy to compose the transaction, and it handles what a hand-built one gets wrong. Every contract call on the lane is a **Solana v1 transaction composed by the proxy** (`rome_composeUnsignedAtomicV1`) with no address lookup table, and the lane library fails closed rather than fall back to an older format. The cash-in move in step 5 is a separate Solana transaction the app builds itself, not a composed contract call.
   * **Account discovery and the compute budget are the proxy's job.** It emulates the call, decides each account's writability (the call's `value` is part of what it emulates, so pass it), and sets the compute and heap budget on the transaction it returns. Nothing in your code builds compute-budget instructions or adds the fee-pool account.
   * **Two signatures per call, both from the Solana key.** The wallet first signs a readable authorization message (*Rome authorization* plus the hash of the unsigned EIP-1559 payload; Wallet Standard `solana:signMessage`), which the proxy verifies before it will compose the call. It then signs the v1 transaction the proxy returns (`solana:signTransaction` on the raw wire). The lane library takes these as `signAuthHash` and `signV1Wire`, never one collapsed method. Check that your wallet signs v1 transactions before you build on it: Solflare does on devnet today and Phantom does not yet.
   * **The app sends the signed transaction to a Solana RPC itself.** The proxy composes; it does not broadcast an atomic call.
   * **Validate before asking for a signature.** The lane library parses the composed message and refuses a malformed one before the transaction prompt.
4. **Put the one-time wrapper grant ahead of the first wUSDC spend.** wUSDC moves a user's tokens as that user's SPL delegate, so a synthetic address that has never been granted gets SPL error `0x4` on its first wUSDC transfer. Read `isEnabled(user)` on the wrapper and, when it is false, prepend `approve_spl(wrapper, 2^64-1, mint)` on the Helper precompile as the first leg of the run. It is an ordinary call on either lane, once per wallet. See [One-time grant per wallet](https://docs.rome.builders/core-concepts/token-interop.md#one-time-grant-per-wallet).
5. **Move cash in before a call that spends it.** The synthetic holds nothing at rest. When it holds less wUSDC than the call spends, move the shortfall from the wallet's own USDC token account first (an idempotent create of the synthetic's token account, then the Rome program's activate-token-account instruction, which moves the tokens without running the EVM). It is one Solana transaction signed with one prompt, and it is skipped when the synthetic already holds enough.
6. **Relay only what the atomic composer refuses.** A call that does not fit one Solana transaction (about 1.4M compute units, 64 accounts, 4 KB) is refused by the composer with *external atomic plan requires iterative composition*. On exactly that refusal, and never before, call `rome_relayUnsignedV1` with the same authorization signature: the proxy composes and submits it, pays the Solana fees, and answers with an EVM transaction hash (not a Solana signature). The synthetic pays the chain's native gas in wei, so when its balance is short of `gasLimit x maxFeePerGas`, top it up first with `rome_composeExternalDepositV1` (a wallet-signed v1 transaction; the amount must be a multiple of 10^12 wei), once per wallet in practice. Any other error, such as a revert, a network failure or a declined signature, is rethrown, not relayed. Details are in [Relayed calls and long calls](https://docs.rome.builders/developer-guides/call-evm-from-solana.md#relayed-calls-and-long-calls).

The user is the **fee payer** and pays lamports (SOL) from their Solana wallet for a direct call; the synthetic they control holds the assets and never holds SOL. After each lane send, poll the EVM nonce before the next one — the indexer lags Solana confirmation slightly, and the next call would otherwise be built on a nonce the chain has already spent.

> **Atomic first, relay on refusal.** The default for every call is one EVM transaction executed inside one Solana transaction, signed by the user's wallet. The relay is the exception for a call that cannot fit, not a second route to pick by preference: a direct call is two prompts, a relayed call is one, and the relayed call is paid in Rome gas instead of lamports. A multi-step journey (approve, then buy) is several whole calls, each its own transaction, not one execution split across transactions.

**Why the RWA can't leak out of the perimeter.** The asset is EVM-state-resident — its balances are storage inside the Rome EVM program's accounts. There is **no SPL mint** of it and nothing Solana-native to move; the lane's asset-moving primitives operate on SPL token accounts, which an EVM storage balance does not have. Every movement the Solana signature can express is a call into the token contract, which runs the allowlist gate — the funded suite asserts a transfer to a non-whitelisted address reverts identically whether signed by an EVM key or a Solana key. The cash leg (wUSDC) is the deliberate exception: it is SPL-backed and *does* sweep out to the user's own token account.

***

## Step 7 — Know who holds authority after deploy

`ArcToken.initialize` runs from the proxy constructor (tx 1) and grants roles to `msg.sender` — the wizard driver, i.e. the issuer. It grants **five** roles explicitly:

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

Two consequences a builder must not miss:

* **`MINTER_ROLE`, `BURNER_ROLE`, and `UPGRADER_ROLE` are NOT granted at initialize.** The initial supply is minted inside `initialize` (an internal `_mint`, no role needed), but a *later* `mint` or `burn` requires the issuer to first grant themselves the role. They can, because they hold `DEFAULT_ADMIN_ROLE` (the admin of every role — nothing calls `_setRoleAdmin`, so `DEFAULT_ADMIN_ROLE` administers all of them). But it is a deliberate extra step, not an ambient power.
* **`UPGRADER_ROLE` is never granted to the factory.** Factory-mediated upgrades (`ArcTokenFactoryV2.upgradeToken`) require the **factory itself** to hold `UPGRADER_ROLE` on the token — granting it to yourself does nothing. That grant is a one-way door the factory cannot reverse, so it is opt-in: if you want factory-mediated upgrades, `grantRole(UPGRADER_ROLE, factory)` explicitly; otherwise the issuer upgrades the token directly.

The full 21-authority model (11 role names across six contracts — the same name is a different authority on each contract) is codified in `arc/roles.ts`. Ask `rolesRequiredFor(contract, functionName)` rather than reading a role's own contract, because four storefront functions and both factory functions are gated by an authority that lives on a *different* contract.

***

## Step 8 — Distribute yield

The token pays yield in wUSDC (fixed at `initialize`, changeable via `setYieldToken` under `YIELD_MANAGER_ROLE`). Distribution walks the holder set:

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

The mechanics that matter for driving it correctly:

* **The full `totalAmount` is pulled from the caller only on the `startIndex == 0` window** (`safeTransferFrom(msg.sender, this, totalAmount)`). Approve that total to the token before the first window; later windows pay out of the balance already held.
* **`nextIndex` wraps to `0` when the walk completes.** Loop `distributeYieldWithLimit(total, nextIndex, …)` until `nextIndex` comes back `0`.
* **Yield-restricted holders' shares stay in the token contract** — they are skipped, not redistributed.

> **On Rome the practical ceiling is `maxHolders = 1` per transaction** — the same 62-account cap from step 2 — so yield is walked one holder per transaction (measured \~318 K gas per holder). Every whitelisted holder, EVM or Solana-native, receives pro-rata; the reference script is `measure-yield-batch.ts` and the funded smoke's yield step asserts it end-to-end.

```bash
# USAGE.md reference form: walk one holder per tx until nextIndex wraps to 0
distributeYieldWithLimit(total, offset, 1)
```

***

## Step 9 — Verify what you deployed

Nothing auto-submits sources anywhere in Rome, so verification is a step you run. After any deploy — infrastructure or a new token — run the read-only, key-less, idempotent verifier (already-verified contracts are skipped, so re-running after issuing a token verifies just the new ones):

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

It expects the **three** contracts per token (proxy + both modules) plus the infrastructure, and reports what it could not verify rather than failing a deploy. Doing this by hand once missed seven contracts.

Registering the asset into the Rome registry treats verification as a **gate**, not decoration (`register-asset.ts`): a token earns its `apps/arc/<chain>.json` record — carrying `standard: arc-permissioned-erc20` and a `transferRestriction` naming its allowlist gate — only when all three of its contracts are verified on Sourcify. That record reads the chain for its facts (a wizard-deployed token has no committed receipt) and writes only a local registry checkout; landing the PR is a person's job.

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # verify + prepare the registry record
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # read-only preview
```

For an end-to-end proof of the whole loop — create, whitelist, gate, sell on both lanes, distribute yield — run the funded smoke against any chain:

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

***

## Step 10 — Know what stays off-chain

The trust model is deliberately honest, and a builder should represent it the same way to their own users:

* **The allowlist flag is your off-chain decision.** KYC/AML happens in your process — your vendors, your rules. The chain records and enforces only the *outcome*, `isWhitelisted(addr)`.
* **The only on-chain state is one boolean per address.** No PII, no documents, no identity claims, no on-chain attestations, no cryptographic proof of who an address belongs to. This is Arc's model as used on Plume; it trades the heavier transfers of an on-chain-identity standard (e.g. ERC-3643) for lighter mechanics and issuer-held trust.
* **Recovery is an issuer power, not an escape hatch.** A lost wallet — EVM or Solana — is recovered by whitelisting a replacement address and, if needed, using mint/burn/upgrade under your own legal process (Arc has no built-in forced-transfer primitive). The issuer's key custody is therefore part of the compliance posture.
* **No relayer of Bloom's own, no custody surface.** Users hold their own gas on both lanes. A fee-payer service run by the app would mean holding keys — a surface an RWA product should not add. The one relay on the Solana lane is the chain proxy's, for a call too large for one transaction, and the user still authorizes it with their own signature and pays for it in their own Rome gas.

***

## Reference: the tooling

Every script runs from the tooling's `scripts/` directory, with `PRIVATE_KEY`, `CHAIN_ID`, and `REGISTRY_ROOT` exported.

| Script                          | What it does                                                               |
| ------------------------------- | -------------------------------------------------------------------------- |
| `deploy-infra.ts`               | One-time per chain: the four shared contracts, wired for wUSDC.            |
| `create-token.ts`               | The piecewise wizard — eight transactions, one token.                      |
| `rotate-factory.ts`             | Deploy a fresh factory after a compiler/artifact change; re-wire.          |
| `verify-artifact-provenance.ts` | Prove your proxy artifact is accepted by the deployed factory (read-only). |
| `verify-deployments.ts`         | Verify all three contracts per token + infra on Sourcify (read-only).      |
| `register-asset.ts`             | Verify-gate, then prepare the registry compliance record.                  |
| `measure-yield-batch.ts`        | Re-measure the per-tx yield ceiling on a chain.                            |
| `smoke.ts`                      | The funded end-to-end suite across both lanes.                             |
| `sweep-synthetic-native.ts`     | Reclaim native gas from a synthetic account (test hygiene).                |

Deeper background lives alongside this guide: `docs/ARCHITECTURE.md` (the layered app model), `docs/LANES.md` (the two lanes and custody), `docs/COMPLIANCE.md` (the trust model), and `docs/USAGE.md` (the operator runbook).


---

# 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/apps-on-rome/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.
