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

# Construindo no Bloom

Este guia responde a uma pergunta: **como um construtor faz isso sozinho?** Pegue um contrato Solidity de ativo do mundo real, coloque-o em uma chain Rome como um token permissionado, abra-o também para carteiras Solana e carteiras EVM sem um segundo token, e conecte sua própria decisão de KYC/compliance.

O público é um desenvolvedor avaliando ou adotando a abordagem. Bloom é o exemplo trabalhado ao longo de todo o texto — seu ativo ao vivo **ARCV ("Mineral Vault I")** em Hadrian (`200010`) é uma instância real de cada etapa abaixo, e seu recibo de deploy (`deployments/200010.tokens/ARCV.json`) registra os três contratos exatos e as oito transações que esse método produz.

Nada aqui modifica os contratos do ativo. Bloom executa o framework Arc da Plume **sem modificações** (a árvore vendorizada em `contracts/`, idêntica byte a byte a `plumenetwork/contracts` no pin em `NOTICE`); o único contrato do lado de Rome é `ArcTokenFactoryV2`, que adiciona uma função. O trabalho está em *como* você implanta e *como* você dirige os contratos — não em alterá-los.

> **O método, em resumo.** Um token permissionado é **três** contratos implantados. Ele é implantado **em partes** — um contrato por transação — porque uma chamada de fábrica em uma única transação excede o limite de contas por transação de Rome. Seus proxies devem vir de **artefatos com procedência travada** ou o registro on-chain falha de forma fechada. A compliance é um **booleano por endereço**, escrito por quem seu processo de KYC autorizar. E a mesma implantação é acessível a partir de uma carteira Solana por meio de um **remetente sintético** derivado on-chain — sem segundo token, sem segunda allowlist.

## Pré-requisitos

> **Antes de começar.** As ferramentas de emissão que este guia usa ainda não foram publicadas. Isso cobre os scripts (`deploy-infra.ts`, `create-token.ts` e o restante), as árvores de `contracts/` e `rome-contracts/` e os recibos de deploy que ele nomeia. Os emissores recebem essas ferramentas ao fazer onboarding com a Rome. Até lá, leia o guia como uma descrição do método e do que cada script faz.

A ferramenta de referência fica em um diretório `scripts/`  (fornecido no onboarding; instale suas dependências com `npm install`). Cada comando resolve os fatos da chain a partir do registro em vez de codificá-los no código, então redirecionar para outra chain Rome é uma mudança de ambiente, não uma mudança de código:

```bash
export PRIVATE_KEY=…       # chave funded do deployer/emissor na chain de destino
export CHAIN_ID=200010     # escolhe a chain
export REGISTRY_ROOT=…     # um checkout do registro de chains da Rome
# Os fluxos da faixa Solana também precisam de:
export SOLANA_KEYPAIR=…    # caminho para um JSON de keypair Solana funded (o fee payer)
```

O gas nas chains Rome é cotado em USDC; a sequência completa de deploy custa na faixa de 10–15 unidades nativas no devnet. As chaves vêm somente do ambiente — nunca do repositório. Compile os contratos uma vez antes de implantar, porque os artefatos **devem** vir de `rome-contracts/out` (veja a etapa 3):

```bash
cd contracts       && forge build --via-ir     # o conjunto Arc vendorizado
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + o proxy canônico
```

***

## Etapa 1 — Entenda o que um token permissionado *seja* aqui

Um token Bloom permissionado não é um contrato. São **três contratos implantados**, mais quatro contratos compartilhados que a equipe de operações implanta uma vez por chain e que cada emissor reutiliza.

**Os três contratos por token** — um ativo possui exatamente estes:

| Contrato                     | Fonte                                                       | O que é                                                                                                                     |
| ---------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | O token em si — um proxy UUPS apontando para a `ArcToken` implementação compartilhada. Saldos, holders e papéis vivem aqui. |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | O módulo de allowlist. Um booleano por endereço; aplicado em toda transferência enquanto o ativo estiver restrito.          |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | O módulo de rendimento. Exclui endereços das distribuições de rendimento sem tocar em sua posse.                            |

**Os quatro contratos compartilhados, um por chain** (implantados por `deploy-infra.ts`):

| Contrato                   | Função                                                                                       |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| `RestrictionsRouter`       | Registro do tipo de módulo — ligação da chain, configurada uma vez pela equipe de operações. |
| `ArcTokenFactoryV2`        | Registro + o codehash canônico do proxy (etapas 2–3).                                        |
| `ArcToken` (implementação) | A lógica de ativo compartilhada e reutilizável para a qual todo token aponta via proxy.      |
| `ArcTokenPurchase`         | Uma única vitrine, compartilhada por cada token e emissor (etapa 4).                         |
| wUSDC                      | A perna de caixa — moeda de rendimento e moeda de compra da venda.                           |

A restrição de transferência e a restrição de rendimento são **módulos deliberadamente separados**: um holder pode ser impedido de receber renda enquanto mantém o ativo, que é como sanções e ordens judiciais realmente funcionam.

Esse fato de "três contratos" é fundamental para a verificação. `verify-deployments.ts` e `register-asset.ts` ambos esperam que um token se resolva em três contratos implantados — verificar um token manualmente uma vez deixou passar sete deles em uma chain (todos os módulos de rendimento e três módulos de whitelist).

O ciclo de vida tem três fases e uma porta sem volta:

```
rascunho     proxy ao vivo, nenhum módulo vinculado — nada restringe uma transferência
  ↓
sem restrição   módulo vinculado, transfersAllowed = true   (WhitelistRestrictions.initialize define isso)
  ↓  cunhe a oferta, construa a allowlist               [reversível]
restrito     setTransfersAllowed(false)                [PORTA SEM VOLTA — a oferta se torna final]
```

A restrição é sem volta para a oferta porque mint e burn passam `address(0)` como contraparte, e `address(0)` nunca pode entrar na allowlist — então, uma vez restrita, nenhuma nova oferta pode jamais ser cunhada. Essa é a garantia que um ativo permissionado oferece a seus holders.

***

## Etapa 2 — Implante em partes, nunca em uma única transação

Arc vem com um atalho de uma vez só `createToken` que implanta o proxy e ambos os módulos e conecta tudo em uma única chamada. **Em Rome você não pode usá-lo.** Essa transação precisa de **77 travas de contas Solana**, e o limite por transação de Rome é **62 travas**. Nunca cabe — nem com ajustes, nem com uma passada de otimizador.

Então o deploy é **em partes**: cada contrato em sua própria transação, e o token ganha status equivalente ao da fábrica por meio de `ArcTokenFactoryV2.registerToken` em vez do monolítico `createToken`. Esta é a wizard de criação, e é isso que o console do emissor faz etapa por etapa:

![a wizard de criação](https://735130481-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)

A implementação de referência é `arc/plan/create.ts` (`createSequence()`), que o app renderiza como seis cartões (`bloom/lib/createCards.ts`) em **oito transações**, na ordem exata que os contratos impõem:

| # | Transação                          | Chamada de contrato                                                            |
| - | ---------------------------------- | ------------------------------------------------------------------------------ |
| 1 | Implante o ativo                   | `new ArcTokenProxy(impl, initData)` onde `initData = ArcToken.initialize(...)` |
| 2 | Implante o módulo de allowlist     | `new WhitelistRestrictions()`                                                  |
| 3 | Defina você como seu administrador | `whitelist.initialize(issuer)`                                                 |
| 4 | Imponha-o nas transferências       | `token.setRestrictionModule(TRANSFER, whitelist)`                              |
| 5 | Implante o módulo de rendimento    | `new YieldBlacklistRestrictions()`                                             |
| 6 | Defina você como seu administrador | `yieldBlacklist.initialize(issuer)`                                            |
| 7 | Imponha-o no rendimento            | `token.setRestrictionModule(YIELD, yieldBlacklist)`                            |
| 8 | Registre com a fábrica             | `factoryV2.registerToken(token, impl)`                                         |

O formulário do script é um comando:

```bash
# uma vez por chain (operações, não por token) — implanta os quatro contratos compartilhados
npx tsx deploy-infra.ts

# por token — a wizard, repetida como script
NAME="Mineral Vault I" SYMBOL=ARCV SUPPLY=1000000 DECIMALS=6 npx tsx create-token.ts
```

O emissor (`PRIVATE_KEY`) assina cada transação e acaba detendo os papéis do token (`ArcToken.initialize` concedidos a `msg.sender` — veja a etapa 7). O registro (tx 8) é o que desbloqueia o storefront da `enableToken` e qualquer upgrade mediado pela fábrica.

> **Não "otimize" isso de volta para um monólito.** Agrupar essas chamadas em uma única transação para economizar idas e voltas reintroduz exatamente o estouro de 62 travas que o caminho em partes existe para evitar. O mesmo limite é o motivo de a distribuição de rendimento percorrer um holder por transação (etapa 8). Se uma chamada falhar com `Muitas contas: N > 62`, uma transação está tocando contas demais — divida-a, não a ajuste.

***

## Etapa 3 — Implante proxies somente a partir dos artefatos com procedência travada

`registerToken` é a fronteira de segurança que torna os deploys em partes seguros. Ele só aceitará um token cujo **codehash de runtime corresponde ao canônico `ArcTokenProxy`** embutido na fábrica no momento do deploy:

```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();
    // …a implementação deve estar na allowlist da fábrica, e msg.sender deve deter o
    //    ADMIN_ROLE do token, e o token não deve já estar registrado.
}
```

Como esse codehash é **imutável**, um proxy construído a partir de qualquer outro artefato falha de forma fechada com `ProxyCodehashUnknown`. Duas regras se seguem, e ambas são aplicadas por CI e pelas regras rígidas em `CLAUDE.md`:

1. **Os proxies de token DEVEM ser implantados a partir de `rome-contracts/out`** — nunca de `contracts/out`, nunca de uma build diferente. Essa é a compilação cuja codehash canônica a fábrica fixa.
2. **`bytecode_hash = "none"` e `cbor_metadata = false`** em `rome-contracts/foundry.toml` são fundamentais. Com os metadados habilitados, o `ArcTokenProxy` runtime *embutido* na fábrica (`type().runtimeCode`) carrega uma cauda CBOR/IPFS diferente da do `out/` artefato standalone de onde a wizard implanta — então o on-chain `registerToken` reverte enquanto **cada teste Foundry em código-fonte passa** (Foundry embute as duas cópias, então não enxerga a incompatibilidade). `rome-contracts/test/ArtifactProvenance.t.sol` fixa essa propriedade; a execução financiada foi o que originalmente a detectou.

> **Uma suíte verde em código-fonte não prova procedência.** Antes de publicar uma imagem, e depois de QUALQUER mudança na configuração do compilador, prove a propriedade contra a fábrica *implantada* (somente leitura, sem chaves):
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> Ele calcula o hash do seu artefato local e afirma que esse hash aparece literalmente dentro do bytecode da fábrica implantada. `ArcTokenProxy` do artefato e

Se as configurações do compilador precisarem mudar, **gire a fábrica** — implante uma nova cujo immutable fixe a nova codehash, e reconecte — em vez de remendar a verificação à mão:

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

A rotação preserva o endereço antigo no recibo; tokens registrados na fábrica antiga precisam se registrar novamente na nova.

***

## Etapa 4 — Abra uma venda por meio da vitrine compartilhada

Vender é um ato separado de criar, e isso roda na única `ArcTokenPurchase` vitrine compartilhada. Três coisas precisam ser verdadeiras antes de uma venda abrir, e `ArcTokenPurchase.enableToken` verifica cada uma on-chain:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) você detém o ADMIN_ROLE do token
{
    // (b) o token precisa ser conhecido pela fábrica — foi isso que registerToken (etapa 2) comprou:
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) a vitrine já deve deter o estoque da venda:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …preço e quantidade precisam ser positivos.
}
```

Há um quarto requisito implícito que um ativo restrito impõe: porque **cada transferência passa pela barreira da allowlist**, mover estoque para a vitrine só funciona se o endereço da vitrine também estiver na allowlist do seu token. Então a sequência completa para abrir uma venda é:

1. **Coloque a vitrine na allowlist** no módulo de whitelist do seu token (`batchAddToWhitelist([storefront])` — veja a etapa 5). Sem isso, a transferência de estoque em (2) reverte `TransferRestricted()` uma vez que esteja restrito.
2. **Transfira o estoque** para o endereço da vitrine (a partir do recibo de infraestrutura, a `arcTokenPurchase`).
3. **`enableToken(token, amount, price)`** — os compradores agora pagam wUSDC e recebem o RWA.

A divisão de retirada vale a pena conhecer em uma *vitrine* compartilhada, e ela não é simétrica (`arc/roles.ts` é a autoridade):

| Ação                                                       | Autoridade                        | Detida por                               |
| ---------------------------------------------------------- | --------------------------------- | ---------------------------------------- |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | o `ADMIN_ROLE` (`onlyTokenAdmin`) | você, o emissor                          |
| `withdrawPurchaseTokens` (os recursos em wUSDC)            | da `DEFAULT_ADMIN_ROLE`           | quem quer que tenha implantado a vitrine |

Em uma chain autogerida você é ambos. Em uma vitrine compartilhada, o pool de recursos é a arrecadação de cada emissor, então sua retirada é em nível de plataforma — desenhe sua liquidação em torno disso, em vez de assumir controle unilateral.

***

## Etapa 5 — Conecte seu próprio KYC / compliance

Esta é a seção que um cliente lê antes de dizer sim, então é código, não prosa. **O compliance é imposto pelo próprio contrato do token** — não por uma triagem off-chain, um filtro de sequenciador ou uma política de venue. As regras viajam com o token para qualquer caminho de execução, em ambas as faixas de carteira. O que a chain registra é o **resultado** da sua decisão de KYC, como um único booleano:

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — o estado on-chain, completo
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← um booleano por endereço. Nenhum dado pessoal, jamais.
    bool transfersAllowed;                    // false = restrito; somente endereços na whitelist transferem
    EnumerableSet.AddressSet whitelistedAddresses;
}
```

### A interface para a qual seu processo escreve

A decisão de aprovar/recusar do seu fornecedor de KYC se torna exatamente uma destas chamadas:

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

### Quem pode escrever

> **A autoridade de que uma aprovação precisa é `MANAGER_ROLE` no&#x20;*****módulo*****&#x20;— não `ADMIN_ROLE` no token.** `addToWhitelist` / `batchAddToWhitelist` / `removeFromWhitelist` são todas `onlyRole(MANAGER_ROLE)`, e esse papel vive na `WhitelistRestrictions` instância. Autenticar `ADMIN_ROLE` no token e depois escrever no módulo é um defeito real que esta base de código já pagou para corrigir. Não ofereça `WHITELIST_ADMIN_ROLE` como a correção para uma recusa — ela é concedida em initialize e **não é verificada em nenhum lugar da suíte** (`arc/roles.ts` afirma que é o único papel que não bloqueia nada).

`WhitelistRestrictions.initialize(issuer)` (tx 3 da wizard) concede ao emissor `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`, e `UPGRADER_ROLE` nessa module. Então o emissor detém `MANAGER_ROLE` de fábrica e também pode delegá-lo: como o emissor detém `DEFAULT_ADMIN_ROLE`, uma `grantRole(MANAGER_ROLE, serviceAccount)` passa a escrita para um signer de backend.

### Uma decisão se tornando uma escrita on-chain

Aponte o webhook do seu fornecedor para um signer que detenha `MANAGER_ROLE`, e, em um approve, faça batch dos endereços:

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

// `signer` deve deter MANAGER_ROLE no módulo de whitelist DESTE token.
const wallet = createWalletClient({ account, transport: http(chain.rpcUrl) });

// o fornecedor disse "approved" para estes endereços:
await wallet.writeContract({
  address: whitelistModule,                 // resolved FROM the token via getRestrictionModule
  abi: whitelistAbi,
  functionName: 'batchAddToWhitelist',
  args: [approvedAddresses],
});
```

Resolva `whitelistModule` do próprio token (`ArcToken.getRestrictionModule(TRANSFER_RESTRICTION_TYPE)`), nunca de uma projeção em cache — apontar uma escrita para o módulo errado foi como "approve on any asset" acabou escrevendo na allowlist de um token.

### A variante assinada pela carteira (demo autoatendimento)

Para uma implantação de teste sem permissão em que os visitantes se admitem sozinhos, conceda `MANAGER_ROLE` a um `TestApprover` (`rome-contracts/src/TestApprover.sol`) cuja `módulo` seja **imutável**. Então `approve(address)` pode ser chamado por qualquer pessoa, a partir da própria carteira, pagando o próprio gas — ele chama `addToWhitelist` somente se o endereço ainda não estiver na lista:

```solidity
function approve(address account) external {
    IWhitelistRestrictions target = IWhitelistRestrictions(module);   // imutável — um módulo, para sempre
    if (!target.isWhitelisted(account)) target.addToWhitelist(account);
    emit Approved(account, msg.sender);
}
```

Este é o "portal de entrada" — ele mostra ao visitante o mecanismo real (uma aprovação se tornando uma entrada de allowlist on-chain que o token então aplica) sem custodiar nada. **Nunca conceda `MANAGER_ROLE` a um `TestApprover` em um token de produção** — isso torna a allowlist desse token sem permissão.

### Quando a trava fecha, e a troca de provedores

A trava só restringe quando o ativo está **bloqueado** (`setTransfersAllowed(false)`, `ADMIN_ROLE` no módulo). Enquanto não estiver bloqueado, as transferências ficam abertas — construa primeiro sua allowlist e depois bloqueie. Uma vez bloqueado, uma transferência em que qualquer uma das partes não esteja na lista reverte com o erro tipado `TransferRestricted()` (`0xe827105e`).

> **Trocar de provedor de KYC depois não exige nenhuma mudança on-chain.** O módulo de allowlist, sua interface e o booleano que ele armazena são agnósticos ao provedor. Para trocar de fornecedor, aponte uma fonte de decisão diferente para o mesmo `MANAGER_ROLE` signer — sem redeploy, sem migração, sem alteração de estado. A cadeia nunca soube qual fornecedor fez a chamada, apenas o resultado.

***

## Etapa 6 — Abrir o mesmo ativo para carteiras Solana

Os mesmos três contratos são alcançáveis a partir de uma carteira Solana **sem um segundo token**. Um usuário nativo de Solana não tem uma chave EVM em lugar nenhum; em vez disso, sua identidade EVM é *sintética*, derivada on-chain a partir do signatário Solana real da transação:

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

O programa Rome EVM deriva isso do próprio signatário (`do_tx_unsigned::derive_sender`), então não pode ser falsificado e não existe uma chave privada secp256k1 para ele — **a assinatura Solana é a única coisa que pode acionar esse endereço**. A derivação de referência é `arc/materialise/solana/identity.ts` (`syntheticAddress`), compatível em bytes com a regra on-chain:

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

**O que um builder faz para dar suporte à via** — note que *nada disso é uma mudança de contrato*:

1. **Adicione o usuário Solana à allowlist pelo endereço sintético dele.** Para a camada de compliance, um endereço sintético é um endereço comum: cole a pubkey Solana do usuário, derive o sintético e `batchAddToWhitelist([synthetic])`. Uma única allowlist cobre os dois mundos de carteira.
2. **Provisione o PDA de assinatura uma vez, antes da primeira chamada que move valor.** O PDA de autoridade externa que assina por um sintético deve existir primeiro, e criá-lo é uma `create_pda` chamada. Qualquer lado pode enviá-la: a própria carteira Solana do usuário pela via (o SDK's `buildCreatePdaCall`, após `isSyntheticProvisioned` retorna falso), ou o emissor a partir de uma chave EVM. A ferramenta de emissor da Bloom a envia hoje como parte do onboarding de um detentor; o app ainda não faz isso na primeira ação do usuário, então provisione antes da primeira compra do detentor. Como, com as chamadas do SDK, está em [App de duas vias](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **Envie pela biblioteca da via, não manualmente.** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`) pede ao proxy da cadeia para compor a transação, e ele trata o que uma feita manualmente faz errado. Toda chamada de contrato na via é uma **transação Solana v1 composta pelo proxy** (`rome_composeUnsignedAtomicV1`) sem tabela de consulta de endereços, e a biblioteca da via falha de forma segura em vez de recuar para um formato mais antigo. A movimentação de entrada de caixa na etapa 5 é uma transação Solana separada que o app constrói por conta própria, não uma chamada de contrato composta.
   * **A descoberta de contas e o orçamento de compute são responsabilidade do proxy.** Ele emula a chamada, decide a gravabilidade de cada conta (a `valor` faz parte do que ele emula, então passe isso), e define o orçamento de compute e heap na transação que ele retorna. Nada no seu código constrói instruções de compute-budget ou adiciona a conta do fee-pool.
   * **Duas assinaturas por chamada, ambas a partir da chave Solana.** A carteira primeiro assina uma mensagem de autorização legível (*Rome authorization* mais o hash do payload EIP-1559 sem assinatura; Wallet Standard `solana:signMessage`), que o proxy verifica antes de compor a chamada. Em seguida, ela assina a transação v1 que o proxy retorna (`solana:signTransaction` no wire bruto). A biblioteca da via trata isso como `signAuthHash` e `signV1Wire`, nunca como um método único condensado. Verifique se sua carteira assina transações v1 antes de construir sobre ela: a Solflare faz isso na devnet hoje e a Phantom ainda não.
   * **O app envia a transação assinada para um RPC Solana por conta própria.** O proxy compõe; ele não transmite uma chamada atômica.
   * **Valide antes de pedir uma assinatura.** A biblioteca da via analisa a mensagem composta e rejeita uma malformada antes do prompt de transação.
4. **Coloque a concessão única do wrapper antes do primeiro gasto de wUSDC.** wUSDC move os tokens de um usuário como delegado SPL desse usuário, então um endereço sintético que nunca recebeu concessão obtém erro SPL `0x4` na sua primeira transferência de wUSDC. Leia `isEnabled(user)` no wrapper e, quando ele for falso, adicione antes `approve_spl(wrapper, 2^64-1, mint)` no precompile Helper como a primeira etapa da execução. É uma chamada comum em qualquer uma das vias, uma vez por carteira. Veja [Concessão única por carteira](https://docs.rome.builders/pt-br/conceitos-principais/token-interop.md#one-time-grant-per-wallet).
5. **Mova o caixa antes de uma chamada que o gaste.** O sintético não mantém nada em repouso. Quando ele tem menos wUSDC do que a chamada gasta, mova primeiro a diferença a partir da própria conta de token USDC da carteira (uma criação idempotente da conta de token do sintético, depois a instrução activate-token-account do programa Rome, que move os tokens sem executar a EVM). É uma transação Solana assinada com um único prompt, e ela é ignorada quando o sintético já tem o suficiente.
6. **Encaminhe apenas o que o compositor atômico recusa.** Uma chamada que não cabe em uma única transação Solana (cerca de 1,4M unidades de compute, 64 contas, 4 KB) é recusada pelo compositor com *external atomic plan requires iterative composition*. Exatamente nessa recusa, e nunca antes, chame `rome_relayUnsignedV1` com a mesma assinatura de autorização: o proxy compõe e a submete, paga as taxas Solana e responde com um hash de transação EVM (não uma assinatura Solana). O sintético paga o gas nativo da cadeia em wei, então quando seu saldo for menor que `gasLimit x maxFeePerGas`, recarregue-o primeiro com `rome_composeExternalDepositV1` (uma transação v1 assinada pela carteira; o valor deve ser múltiplo de 10^12 wei), na prática uma vez por carteira. Qualquer outro erro, como um revert, falha de rede ou assinatura recusada, é relançado, não encaminhado. Os detalhes estão em [Chamadas retransmitidas e chamadas longas](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-evm-from-solana.md#relayed-calls-and-long-calls).

O usuário é o **pagador de taxas** e paga lamports (SOL) da própria carteira Solana para uma chamada direta; o sintético que ele controla mantém os ativos e nunca mantém SOL. Após cada envio pela via, consulte o nonce da EVM antes do próximo — o indexador atrasa um pouco a confirmação Solana, e a próxima chamada seria construída com um nonce que a cadeia já gastou.

> **Primeiro atômico, encaminhe em caso de recusa.** O padrão para cada chamada é uma transação EVM executada dentro de uma transação Solana, assinada pela carteira do usuário. O encaminhamento é a exceção para uma chamada que não cabe, não uma segunda rota para escolher por preferência: uma chamada direta tem dois prompts, uma chamada encaminhada tem um, e a chamada encaminhada é paga em gas Rome em vez de lamports. Uma jornada em várias etapas (aprovar, depois comprar) são várias chamadas completas, cada uma sua própria transação, não uma execução dividida entre transações.

**Por que o RWA não pode vazar para fora do perímetro.** O ativo reside no estado da EVM — seus saldos são armazenamento dentro das contas do programa Rome EVM. Não há **nenhum mint SPL** dele e nada nativo de Solana para mover; os primitivos de movimentação de ativos da via operam em contas de token SPL, que um saldo de armazenamento da EVM não possui. Todo movimento que a assinatura Solana pode expressar é uma chamada ao contrato do token, que executa a trava de allowlist — a suíte financiada afirma que uma transferência para um endereço não listado reverte de forma idêntica, seja assinada por uma chave EVM ou por uma chave Solana. A perna de caixa (wUSDC) é a exceção deliberada: ela é lastreada em SPL e *funciona* varrida para a própria conta de token do usuário.

***

## Etapa 7 — Saiba quem detém autoridade após o deploy

`ArcToken.initialize` é executado a partir do construtor do proxy (tx 1) e concede papéis a `msg.sender` — o driver do assistente, ou seja, o emissor. Ele concede **cinco** papéis explicitamente:

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

Duas consequências que um builder não pode deixar passar:

* **`MINTER_ROLE`, `BURNER_ROLE`, e `UPGRADER_ROLE` NÃO são concedidos na inicialização.** A oferta inicial é cunhada dentro de `inicializar` (um `_mint`, nenhum papel necessário), mas uma *posterior* `mint` ou `queima` exige que o emissor primeiro conceda a si mesmo o papel. Ele pode, porque detém `DEFAULT_ADMIN_ROLE` (o administrador de cada papel — nada chama `_setRoleAdmin`, então `DEFAULT_ADMIN_ROLE` administra todos eles). Mas é uma etapa extra deliberada, não um poder implícito.
* **`UPGRADER_ROLE` nunca é concedido à fábrica.** Atualizações mediadas pela fábrica (`ArcTokenFactoryV2.upgradeToken`) exigem que a **própria fábrica** possa ter `UPGRADER_ROLE` no token — concedê-lo a si mesmo não faz nada. Essa concessão é uma via de mão única que a fábrica não pode reverter, então é opcional: se você quiser atualizações mediadas pela fábrica, `grantRole(UPGRADER_ROLE, factory)` explicitamente; caso contrário, o emissor atualiza o token diretamente.

O modelo completo de 21 autoridades (11 nomes de papéis em seis contratos — o mesmo nome é uma autoridade diferente em cada contrato) é codificado em `arc/roles.ts`. Solicite `rolesRequiredFor(contract, functionName)` em vez de ler o próprio contrato do papel, porque quatro funções de storefront e ambas as funções da fábrica são controladas por uma autoridade que vive em um *diferente* .

***

## Etapa 8 — Distribuir yield

O token paga yield em wUSDC (fixado em `inicializar`, alterável via `setYieldToken` abaixo de `YIELD_MANAGER_ROLE`). A distribuição percorre o conjunto de detentores:

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

Os mecanismos que importam para operá-lo corretamente:

* **O valor total `totalAmount` é retirado do chamador apenas na `startIndex == 0` janela** (`safeTransferFrom(msg.sender, this, totalAmount)`). Aprove esse total para o token antes da primeira janela; as janelas posteriores pagam a partir do saldo já mantido.
* **`nextIndex` volta para `0` quando o percurso se completa.** Faça loop `distributeYieldWithLimit(total, nextIndex, …)` até `nextIndex` retorna `0`.
* **As parcelas dos detentores com restrição de yield permanecem no contrato do token** — elas são puladas, não redistribuídas.

> **Em Rome, o limite prático é `maxHolders = 1` por transação** — o mesmo limite de 62 contas da etapa 2 — então o yield é percorrido um detentor por transação (medido em \~318 K de gas por detentor). Todo detentor na allowlist, EVM ou nativo Solana, recebe proporcionalmente; o script de referência é `measure-yield-batch.ts` e a etapa de yield do smoke financiado valida isso de ponta a ponta.

```bash
# Forma de referência do USAGE.md: percorra um detentor por tx até nextIndex voltar para 0
distributeYieldWithLimit(total, offset, 1)
```

***

## Etapa 9 — Verifique o que você implantou

Nada envia fontes automaticamente em Rome, então a verificação é uma etapa que você executa. Após qualquer deploy — infraestrutura ou um novo token — execute o verificador somente leitura, sem chave e idempotente (contratos já verificados são ignorados, então rodar de novo após emitir um token verifica apenas os novos):

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

Ele espera os **três** contratos por token (proxy + ambos os módulos) além da infraestrutura, e relata o que não conseguiu verificar em vez de falhar um deploy. Fazer isso manualmente uma vez deixou passar sete contratos.

Registrar o ativo no registro Rome trata a verificação como um **portal**, não decoração (`register-asset.ts`): um token ganha seu `apps/arc/<chain>.json` registro — contendo `standard: arc-permissioned-erc20` e um `transferRestriction` nomeando sua trava de allowlist — somente quando todos os três contratos estiverem verificados no Sourcify. Esse registro lê a cadeia para obter seus fatos (um token implantado pelo assistente não tem recibo commitado) e escreve apenas um checkout local do registro; aprovar o PR é trabalho de uma pessoa.

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # verificar + preparar o registro do cadastro
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # prévia somente leitura
```

Para uma prova ponta a ponta de todo o ciclo — criar, colocar na allowlist, bloquear, vender nas duas vias, distribuir yield — execute o smoke financiado em qualquer cadeia:

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

***

## Etapa 10 — Saiba o que fica fora da cadeia

O modelo de confiança é deliberadamente transparente, e um builder deve representá-lo da mesma forma para seus próprios usuários:

* **O sinalizador de allowlist é sua decisão off-chain.** KYC/AML acontece no seu processo — seus fornecedores, suas regras. A cadeia registra e aplica apenas o *resultado*, `isWhitelisted(addr)`.
* **O único estado on-chain é um booleano por endereço.** Nenhum dado pessoal, nenhum documento, nenhuma alegação de identidade, nenhuma atestação on-chain, nenhuma prova criptográfica de a quem um endereço pertence. Este é o modelo da Arc como usado na Plume; ele troca as transferências mais pesadas de um padrão de identidade on-chain (por exemplo, ERC-3643) por mecânicas mais leves e confiança mantida pelo emissor.
* **A recuperação é um poder do emissor, não uma escapatória.** Uma carteira perdida — EVM ou Solana — é recuperada colocando um endereço substituto na allowlist e, se necessário, usando mint/burn/upgrade sob seu próprio processo jurídico (Arc não tem primitive de transferência forçada embutido). A custódia da chave do emissor, portanto, faz parte da postura de conformidade.
* **Sem relayer próprio da Bloom, sem superfície de custódia.** Os usuários mantêm seu próprio gas nas duas vias. Um serviço de fee payer operado pelo app significaria segurar chaves — uma superfície que um produto RWA não deve adicionar. O único relay na via Solana é o do proxy da cadeia, para uma chamada grande demais para uma transação, e o usuário ainda assim a autoriza com sua própria assinatura e paga por ela com seu próprio gas Rome.

***

## Referência: as ferramentas

Todo script roda a partir do diretório `scripts/` das ferramentas, com `PRIVATE_KEY`, `CHAIN_ID`, e `REGISTRY_ROOT` exportados.

| Script                          | O que faz                                                                             |
| ------------------------------- | ------------------------------------------------------------------------------------- |
| `deploy-infra.ts`               | Uma vez por cadeia: os quatro contratos compartilhados, configurados para wUSDC.      |
| `create-token.ts`               | O assistente em partes — oito transações, um token.                                   |
| `rotate-factory.ts`             | Implante uma nova factory após uma mudança no compilador/artefato; reconecte.         |
| `verify-artifact-provenance.ts` | Prove que o artefato do seu proxy é aceito pela factory implantada (somente leitura). |
| `verify-deployments.ts`         | Verifique os três contratos por token + infraestrutura no Sourcify (somente leitura). |
| `register-asset.ts`             | Verifique a trava, depois prepare o registro de conformidade.                         |
| `measure-yield-batch.ts`        | Meça novamente o limite de yield por transação em uma cadeia.                         |
| `smoke.ts`                      | A suíte financiada de ponta a ponta nas duas vias.                                    |
| `sweep-synthetic-native.ts`     | Recupere gas nativo de uma conta sintética (higiene de teste).                        |

Contexto mais profundo está junto deste guia: `docs/ARCHITECTURE.md` (o modelo de app em camadas), `docs/LANES.md` (as duas vias e a custódia), `docs/COMPLIANCE.md` (o modelo de confiança), e `docs/USAGE.md` (o runbook do operador).


---

# 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/pt-br/apps-na-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.
