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

# Construyendo sobre Bloom

Esta guía responde a una pregunta: **¿cómo hace un desarrollador esto por sí mismo?** Toma un contrato de activo del mundo real en Solidity, ponlo en una cadena Rome como un token con permisos, ábrelo también a carteras de Solana además de carteras EVM sin un segundo token, e integra tu propia decisión de KYC/cumplimiento.

La audiencia es un desarrollador que evalúa o adopta el enfoque. Bloom es el ejemplo trabajado a lo largo de todo el texto — su activo en vivo **ARCV ("Mineral Vault I")** en Hadrian (`200010`) es una instancia real de cada paso que aparece abajo, y su recibo de despliegue (`deployments/200010.tokens/ARCV.json`) registra exactamente los tres contratos y las ocho transacciones que produce este método.

Nada aquí modifica los contratos del activo. Bloom ejecuta el framework Arc de Plume **sin modificaciones** (el árbol incluido en `contracts/`, idéntico byte a byte a `plumenetwork/contracts` en el pin de `NOTICE`); el único contrato del lado de Rome es `ArcTokenFactoryV2`, que añade una función. El trabajo está en *cómo* tú despliegas y *cómo* tú conduces los contratos — no en cambiarlos.

> **El método, de un vistazo.** Un token con permisos es **tres** contratos desplegados. Se despliega **por partes** — un contrato por transacción — porque una llamada de fábrica en una sola transacción supera el límite de cuentas por transacción de Rome. Sus proxies deben provenir de **artefactos bloqueados por procedencia** o el registro en cadena falla en cerrado. El cumplimiento es un **booleano por dirección**, escrito por quienquiera que tu proceso de KYC autorice. Y el mismo despliegue es accesible desde una cartera de Solana mediante un **emisor sintético** derivado en cadena — sin segundo token, sin segunda lista de अनुमति.

## Requisitos previos

> **Antes de empezar.** La herramienta para emisores que usa esta guía todavía no se ha publicado. Eso incluye los scripts (`deploy-infra.ts`, `create-token.ts` y el resto), los árboles `contracts/` y `rome-contracts/` y los recibos de despliegue que nombra. Los emisores obtienen esta herramienta al incorporarse con Rome. Hasta entonces, lee la guía como una descripción del método y de lo que hace cada script.

La herramienta de referencia vive en un directorio `scripts/` (proporcionado durante la incorporación; instala sus dependencias con `npm install`). Cada comando resuelve los datos de la cadena desde el registro en lugar de codificarlos, así que redirigirlo a otra cadena Rome es un cambio de entorno, no un cambio de código:

```bash
export PRIVATE_KEY=…       # clave financiada del desplegador/emisor en la cadena objetivo
export CHAIN_ID=200010     # selecciona la cadena
export REGISTRY_ROOT=…     # un checkout del registro de cadenas de Rome
# Los flujos de la vía de Solana también necesitan:
export SOLANA_KEYPAIR=…    # ruta a un JSON de keypair de Solana financiado (el pagador de comisiones)
```

El gas en las cadenas Rome se denomina en USDC; la secuencia completa de despliegue cuesta del orden de 10–15 unidades nativas en devnet. Las claves vienen solo del entorno — nunca del repositorio. Compila los contratos una vez antes de desplegar, porque los artefactos **deben** provenir de `rome-contracts/out` (ver paso 3):

```bash
cd contracts       && forge build --via-ir     # la suite Arc incluida
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + el proxy canónico
```

***

## Paso 1 — Entiende qué es un token con permisos *es* aquí

Un token Bloom con permisos no es un contrato. Son **tres contratos desplegados**, más cuatro contratos compartidos que ops despliega una vez por cadena y que cada emisor reutiliza.

**Los tres contratos por token** — un activo posee exactamente estos:

| Contrato                     | Fuente                                                      | Qué es                                                                                                                                  |
| ---------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | El token en sí — un proxy UUPS que apunta a la implementación compartida `ArcToken` . Los saldos, los titulares y los roles viven aquí. |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | El módulo de lista blanca. Un booleano por dirección; se aplica en cada transferencia mientras el activo esté restringido.              |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | El módulo de rendimiento. Excluye direcciones de las distribuciones de rendimiento sin tocar su saldo.                                  |

**Los cuatro contratos compartidos, uno por cadena** (desplegados por `deploy-infra.ts`):

| Contrato                    | Rol                                                                               |
| --------------------------- | --------------------------------------------------------------------------------- |
| `RestrictionsRouter`        | Registro de tipos de módulo — cableado de la cadena, configurado una vez por ops. |
| `ArcTokenFactoryV2`         | Registro + el codehash canónico del proxy (pasos 2–3).                            |
| `ArcToken` (implementación) | La lógica de activo compartida y reutilizable a la que apunta cada token.         |
| `ArcTokenPurchase`          | Un único escaparate, compartido por cada token y emisor (paso 4).                 |
| wUSDC                       | La pata de efectivo — moneda de rendimiento y moneda de compra/venta.             |

La restricción de transferencias y la restricción de rendimiento son **módulos deliberadamente separados**: un titular puede ser excluido del ingreso mientras conserva el activo, que es como funcionan realmente las sanciones y las órdenes judiciales.

Este hecho de "tres contratos" es clave para la verificación. `verify-deployments.ts` y `register-asset.ts` ambos esperan que un token se resuelva en tres contratos desplegados — verificar un token a mano una vez dejó pasar siete en una cadena (cada módulo de rendimiento y tres módulos de lista blanca).

El ciclo de vida tiene tres fases y una puerta de un solo sentido:

```
borrador     proxy activo, sin módulo enlazado — nada bloquea una transferencia
  ↓
sin restricción   módulo enlazado, transfersAllowed = true   (WhitelistRestrictions.initialize establece esto)
  ↓  acuñar suministro, construir la lista blanca               [reversible]
restringido     setTransfersAllowed(false)                [PUERTA DE UN SOLO SENTIDO — el suministro se vuelve definitivo]
```

La restricción es de un solo sentido para el suministro porque acuñar y quemar pasan `address(0)` como contraparte, y `address(0)` nunca puede entrar en la lista blanca — así que, una vez restringido, nunca podrá acuñarse nuevo suministro. Esa es la garantía que un activo con permisos ofrece a sus titulares.

***

## Paso 2 — Desplégalo por partes, nunca como una sola transacción

Arc incluye un `createToken` de una sola vez que despliega el proxy y ambos módulos y los conecta en una sola llamada. **En Rome no puedes usarlo.** Esa transacción necesita **77 bloqueos de cuentas de Solana**, y el límite por transacción de Rome es **62 bloqueos**. Nunca cabe — ni con ajustes ni con una pasada del optimizador.

Así que el despliegue es **por partes**: cada contrato en su propia transacción, y el token obtiene un estatus equivalente al de la fábrica mediante `ArcTokenFactoryV2.registerToken` en lugar del monolítico `createToken`. Este es el asistente de creación, y es lo que hace la consola del emisor paso a paso:

![el asistente de creación](https://1082203750-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)

La implementación de referencia es `arc/plan/create.ts` (`createSequence()`), que la app muestra como seis tarjetas (`bloom/lib/createCards.ts`) sobre **ocho transacciones**, en el orden exacto que imponen los contratos:

| # | Transacción                                | Llamada al contrato                                                             |
| - | ------------------------------------------ | ------------------------------------------------------------------------------- |
| 1 | Desplegar el activo                        | `new ArcTokenProxy(impl, initData)` donde `initData = ArcToken.initialize(...)` |
| 2 | Desplegar el módulo de lista de permitidos | `new WhitelistRestrictions()`                                                   |
| 3 | Asignarte como su administrador            | `whitelist.initialize(issuer)`                                                  |
| 4 | Imponerlo en las transferencias            | `token.setRestrictionModule(TRANSFER, whitelist)`                               |
| 5 | Desplegar el módulo de rendimiento         | `new YieldBlacklistRestrictions()`                                              |
| 6 | Asignarte como su administrador            | `yieldBlacklist.initialize(issuer)`                                             |
| 7 | Imponerlo en el rendimiento                | `token.setRestrictionModule(YIELD, yieldBlacklist)`                             |
| 8 | Registrar con la fábrica                   | `factoryV2.registerToken(token, impl)`                                          |

La forma en script es un solo comando:

```bash
# una vez por cadena (ops, no por token) — despliega los cuatro contratos compartidos
npx tsx deploy-infra.ts

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

El emisor (`PRIVATE_KEY`) firma cada transacción y termina controlando los roles del token (`ArcToken.initialize` concede a `msg.sender` — ver paso 7). El registro (tx 8) es lo que desbloquea la `enableToken` del escaparate y cualquier actualización mediada por la fábrica.

> **No "optimices" esto de nuevo hasta convertirlo en un monolito.** Agrupar estas llamadas en una sola transacción para ahorrar idas y vueltas reintroduce exactamente el desbordamiento de 62 bloqueos que la ruta por partes existe para evitar. Ese mismo límite es la razón por la que la distribución de rendimiento recorre un titular por transacción (paso 8). Si una llamada falla con `Demasiadas cuentas: N > 62`, una transacción está tocando demasiadas cuentas — divídela, no la ajustes.

***

## Paso 3 — Despliega proxies solo desde los artefactos bloqueados por procedencia

`registerToken` es la frontera de seguridad que permite que los despliegues por partes sean seguros. Solo aceptará un token cuyo **codehash de tiempo de ejecución coincida con el canónico `ArcTokenProxy`** incorporado en la fábrica en el momento del despliegue:

```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();
    // …la implementación debe estar en la lista blanca de la fábrica, y msg.sender debe poseer el
    //    ADMIN_ROLE del token, y el token no debe estar ya registrado.
}
```

Como ese codehash es un **inmutable**, un proxy construido a partir de cualquier otro artefacto falla en cerrado con `ProxyCodehashUnknown`. De ello se siguen dos reglas, y ambas están aplicadas por CI y por las reglas duras de `CLAUDE.md`:

1. **Los proxies de token DEBEN desplegarse desde `rome-contracts/out`** — nunca desde `contracts/out`, nunca desde una compilación distinta. Esa es la compilación cuya huella canónica fija la fábrica.
2. **`bytecode_hash = "none"` y `cbor_metadata = false`** en `rome-contracts/foundry.toml` son clave. Con los metadatos activados, el `ArcTokenProxy` runtime *incrustado* en la fábrica (`type().runtimeCode`) lleva una cola CBOR/IPFS distinta de la del `out/` artefacto independiente desde el que el asistente despliega — así que en cadena `registerToken` revierte mientras **cada prueba de Foundry en el código fuente pasa** (Foundry incrusta ambas copias, así que no puede ver la discrepancia). `rome-contracts/test/ArtifactProvenance.t.sol` fija esta propiedad; la ejecución financiada fue la que la detectó originalmente.

> **Una suite en código fuente en verde no prueba la procedencia.** Antes de publicar una imagen, y después de CUALQUIER cambio en la configuración del compilador, demuestra la propiedad contra la *fábrica* desplegada
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> Hashea tu `ArcTokenProxy` artefacto local y afirma que ese hash aparece literalmente dentro del bytecode de la fábrica desplegada.

Si deben cambiar las configuraciones del compilador, **rota la fábrica** — despliega una nueva cuya inmutable fije el nuevo codehash, y vuelve a conectar — en lugar de parchear la comprobación a mano:

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

La rotación conserva la dirección anterior en el recibo; los tokens registrados contra la fábrica antigua deben volver a registrarse contra la nueva.

***

## Paso 4 — Abre una venta a través del escaparate compartido

Vender es un acto separado de crear, y corre sobre el único `ArcTokenPurchase` escaparate compartido. Deben cumplirse tres cosas antes de abrir una venta, y `ArcTokenPurchase.enableToken` comprueba cada una en cadena:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) posees el ADMIN_ROLE del token
{
    // (b) el token debe ser conocido por la fábrica — esto es lo que compró registerToken (paso 2):
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) el escaparate ya debe poseer el inventario de venta:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …el precio y la cantidad deben ser positivos.
}
```

Hay un cuarto requisito implícito que impone un activo restringido: porque **cada transferencia pasa por la puerta de la lista blanca**, mover inventario al escaparate solo tiene éxito si la dirección del escaparate está a su vez en la lista blanca de tu token. Así que la secuencia completa para abrir una venta es:

1. **Pon el escaparate en la lista blanca** en el módulo de lista blanca de tu token (`batchAddToWhitelist([storefront])` — ver paso 5). Sin esto, la transferencia de inventario en (2) revierte `TransferRestricted()` una vez restringido.
2. **Transfiere el inventario** a la dirección del escaparate (desde `arcTokenPurchase`).
3. **`del recibo de infraestructura`** enableToken(token, amount, price)

— ahora los compradores pagan wUSDC y reciben el RWA. *La división de la retirada merece conocerse en un* escaparate compartido`, y no es simétrica (` arc/roles.ts

| Acción                                                     | Autoridad                          | La posee                                 |
| ---------------------------------------------------------- | ---------------------------------- | ---------------------------------------- |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | el `ADMIN_ROLE` (`onlyTokenAdmin`) | tú, el emisor                            |
| `withdrawPurchaseTokens` (los ingresos en wUSDC)           | el `DEFAULT_ADMIN_ROLE`            | quienquiera que desplegara el escaparate |

En una cadena autoalojada eres ambas cosas. En un escaparate compartido el fondo de ingresos es lo recaudado por cada emisor, así que su retirada es a nivel de plataforma — diseña tu liquidación alrededor de eso en lugar de asumir control unilateral.

***

## Paso 5 — Integra tu propio KYC / cumplimiento

Esta es la sección que un cliente lee antes de decir que sí, así que es código, no prosa. **El cumplimiento lo impone el propio contrato del token** — no una pantalla fuera de cadena, ni un filtro del secuenciador, ni una política del lugar. Las reglas viajan con el token a cualquier ruta de ejecución, en ambas vías de cartera. Lo que la cadena registra es la **resultado** de tu decisión de KYC, como un único booleano:

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — el estado en cadena, completo
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← un booleano por dirección. Nunca PII.
    bool transfersAllowed;                    // false = restringido; solo las direcciones en lista blanca transfieren
    EnumerableSet.AddressSet whitelistedAddresses;
}
```

### La interfaz a la que escribe tu proceso

La decisión de aprobar/denegar de tu proveedor de KYC se convierte exactamente en una de estas llamadas:

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

### Quién puede escribir

> **La autoridad que necesita una aprobación está `MANAGER_ROLE` en el&#x20;*****módulo*****&#x20;— no `ADMIN_ROLE` en el token.** `addToWhitelist` / `batchAddToWhitelist` / `removeFromWhitelist` son todos `onlyRole(MANAGER_ROLE)`, y ese rol vive en la `WhitelistRestrictions` instancia. Autenticarse `ADMIN_ROLE` en el token y luego escribir en el módulo es un defecto real por el que esta base de código ya ha pagado. No lo ofrezcas como solución para una denegación — se concede en initialize y `WHITELIST_ADMIN_ROLE` no se comprueba en ninguna parte de la suite **(la aserción indica que es el único rol que no bloquea nada).** (`, y no es simétrica (` WhitelistRestrictions.initialize(issuer)

`(tx 3 del asistente) concede al emisor` en ese módulo. Así que el emisor posee `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`, y `UPGRADER_ROLE` de fábrica y también puede delegarlo: como el emisor posee `MANAGER_ROLE` grantRole(MANAGER\_ROLE, serviceAccount) `DEFAULT_ADMIN_ROLE`, una `entrega la escritura a un firmante de backend.` Una decisión convertida en una escritura en cadena

### Apunta el webhook de tu proveedor a un firmante que tenga

, y al aprobar, agrupa las direcciones: `MANAGER_ROLE`, y en una aprobación, agrupa las direcciones:

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

// `signer` debe poseer MANAGER_ROLE en el módulo de lista blanca DE ESTE token.
const wallet = createWalletClient({ account, transport: http(chain.rpcUrl) });

// el proveedor dijo "aprobado" para estas direcciones:
await wallet.writeContract({
  address: whitelistModule,                 // resuelto DESDE el token mediante getRestrictionModule
  abi: whitelistAbi,
  functionName: 'batchAddToWhitelist',
  args: [approvedAddresses],
});
```

Resolver `whitelistModule` desde el propio token (`ArcToken.getRestrictionModule(TRANSFER_RESTRICTION_TYPE)`), nunca desde una proyección en caché — apuntar una escritura al módulo equivocado es cómo «approve on any asset» terminó escribiendo en la lista de permitidos de un token.

### La variante firmada por la wallet (demo de autoservicio)

Para una implementación de prueba sin permisos en la que los visitantes se admiten a sí mismos, concede `MANAGER_ROLE` a un `TestApprover` (`rome-contracts/src/TestApprover.sol`) cuyo `módulo` es **inmutable**. Luego `approve(address)` puede ser llamada por cualquiera, desde su propia wallet, pagando su propio gas — llama a `addToWhitelist` solo si la dirección no está ya incluida en la lista:

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

Esta es la «puerta de acceso» — muestra a un visitante el mecanismo real (una aprobación que se convierte en una entrada de lista de permitidos en la cadena que luego el token hace cumplir) sin custodiar nada. **Nunca concedas `MANAGER_ROLE` a un `TestApprover` en un token de producción** — convierte la lista de permitidos de ese token en algo sin permisos.

### Cuando la puerta muerde, y cambiar de proveedor

La puerta solo restringe una vez que el activo está **con control de acceso** (`setTransfersAllowed(false)`, `ADMIN_ROLE` en el módulo). Mientras no esté con puerta, las transferencias están abiertas — primero construye tu lista de permitidos y luego activa la puerta. Una vez activada, una transferencia en la que cualquiera de las dos partes esté fuera de la lista revierte con el error tipado `TransferRestricted()` (`0xe827105e`).

> **Cambiar de proveedor de KYC más adelante no requiere ningún cambio en cadena.** El módulo de lista de permitidos, su interfaz y el booleano que almacena son agnósticos al proveedor. Para cambiar de vendedor, apunta una fuente de decisión distinta al mismo `MANAGER_ROLE` firmante — sin redeploy, sin migración, sin cambio de estado. La cadena nunca supo qué vendedor hizo la llamada, solo el resultado.

***

## Paso 6 — Abre el mismo activo a wallets de Solana

Los mismos tres contratos son accesibles desde una wallet de Solana **sin un segundo token**. Un usuario nativo de Solana no tiene ninguna clave EVM en ningún sitio; en su lugar, su identidad EVM es *sintética*, derivada en cadena a partir del firmante real de Solana de la transacción:

```
dirección EVM sintética = keccak256(solana_pubkey)[12..32]
```

El programa EVM de Rome lo deriva desde el propio firmante (`do_tx_unsigned::derive_sender`), así que no puede falsificarse y no existe una clave privada secp256k1 para ello — **la firma de Solana es la única cosa que puede impulsar esta dirección**. La derivación de referencia está en `arc/materialise/solana/identity.ts` (`syntheticAddress`), compatible a nivel de bytes con la regla en cadena:

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

**Lo que hace un constructor para soportar el carril** — fíjate en que *nada de esto es un cambio de contrato*:

1. **Pon al usuario de Solana en la lista de permitidos por su dirección sintética.** Para la capa de cumplimiento, una dirección sintética es una dirección ordinaria: pega la clave pública de Solana del usuario, deriva la sintética y `batchAddToWhitelist([synthetic])`. Una sola lista de permitidos abarca ambos mundos de wallets.
2. **Provisióna una vez el PDA de firma, antes de su primera llamada que mueva valor.** El PDA de autoridad externa que firma para una sintética debe existir primero, y crearlo es una `create_pda` llamada. Cualquiera de las dos partes puede enviarla: la propia wallet de Solana del usuario a través del carril (el `buildCreatePdaCall`, después de `isSyntheticProvisioned` devuelve false), o el emisor desde una clave EVM. Las herramientas de emisor de Bloom lo envían hoy como parte del alta de un titular; la app todavía no lo hace en la primera acción del usuario, así que provísionalo antes de la primera compra del titular. Cómo hacerlo con las llamadas del SDK está en [App de doble carril](https://docs.rome.builders/es/guias-para-desarrolladores/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **Envía a través de la biblioteca del carril, no a mano.** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`) le pide al proxy de la cadena que componga la transacción, y maneja lo que una construida a mano hace mal. Toda llamada a contrato en el carril es una **transacción Solana v1 compuesta por el proxy** (`rome_composeUnsignedAtomicV1`) sin tabla de búsqueda de direcciones, y la biblioteca del carril falla de forma cerrada en lugar de retroceder a un formato más antiguo. El movimiento de entrada de efectivo del paso 5 es una transacción de Solana separada que la app construye por sí misma, no una llamada de contrato compuesta.
   * **El descubrimiento de cuentas y el presupuesto de cómputo son tarea del proxy.** Emula la llamada, decide la capacidad de escritura de cada cuenta (la llamada `valor` forma parte de lo que emula, así que pásala), y establece el presupuesto de cómputo y de heap en la transacción que devuelve. Nada en tu código construye instrucciones de presupuesto de cómputo ni añade la cuenta del fondo de comisiones.
   * **Dos firmas por llamada, ambas desde la clave de Solana.** Primero, la wallet firma un mensaje de autorización legible (*autorización Rome* más el hash del payload EIP-1559 sin firmar; Wallet Standard `solana:signMessage`), que el proxy verifica antes de componer la llamada. Luego firma la transacción v1 que devuelve el proxy (`solana:signTransaction` sobre el wire bruto). La biblioteca del carril toma esto como `signAuthHash` y `signV1Wire`, nunca como un método unificado. Comprueba que tu wallet firma transacciones v1 antes de construir sobre ella: Solflare lo hace hoy en devnet y Phantom todavía no.
   * **La app envía la transacción firmada a un RPC de Solana por sí misma.** El proxy compone; no difunde una llamada atómica.
   * **Valida antes de pedir una firma.** La biblioteca del carril analiza el mensaje compuesto y rechaza uno malformado antes del aviso de la transacción.
4. **Pon la concesión única del wrapper antes del primer gasto de wUSDC.** wUSDC mueve los tokens de un usuario como delegado SPL de ese usuario, así que una dirección sintética que nunca ha recibido una concesión obtiene un error SPL en su primera transferencia de wUSDC. `0x4` en `isEnabled(user)` en el wrapper y, cuando sea falso, anteponer `approve_spl(wrapper, 2^64-1, mint)` en el precompilado Helper como la primera etapa de la ejecución. Es una llamada ordinaria en cualquiera de los dos carriles, una vez por wallet. Véase [Concesión única por billetera](https://docs.rome.builders/es/conceptos-basicos/token-interop.md#one-time-grant-per-wallet).
5. **Mueve efectivo antes de una llamada que lo gasta.** La sintética no tiene nada en reposo. Cuando tiene menos wUSDC del que gasta la llamada, mueve primero la diferencia desde la propia cuenta de tokens USDC de la wallet (una creación idempotente de la cuenta de tokens de la sintética, luego la instrucción activate-token-account del programa Rome, que mueve los tokens sin ejecutar la EVM). Es una sola transacción de Solana firmada con un solo prompt, y se omite cuando la sintética ya tiene suficiente.
6. **Reenvía solo lo que el compositor atómico rechaza.** Una llamada que no cabe en una sola transacción de Solana (aprox. 1,4 M de unidades de cómputo, 64 cuentas, 4 KB) es rechazada por el compositor con *el plan atómico externo requiere composición iterativa*. Justo ante ese rechazo, y nunca antes, llama a `rome_relayUnsignedV1` con la misma firma de autorización: el proxy lo compone y lo envía, paga las comisiones de Solana y responde con un hash de transacción EVM (no una firma de Solana). La sintética paga el gas nativo de la cadena en wei, así que cuando su saldo es inferior a `gasLimit x maxFeePerGas`, súbelo primero con `rome_composeExternalDepositV1` (una transacción v1 firmada por la wallet; la cantidad debe ser un múltiplo de 10^12 wei), en la práctica una vez por wallet. Cualquier otro error, como un revert, un fallo de red o una firma rechazada, se vuelve a lanzar, no se reenvía. Los detalles están en [Llamadas retransmitidas y llamadas largas](https://docs.rome.builders/es/guias-para-desarrolladores/call-evm-from-solana.md#relayed-calls-and-long-calls).

El usuario es el **pagador de comisiones** y paga lamports (SOL) desde su wallet de Solana para una llamada directa; la sintética que controla tiene los activos y nunca tiene SOL. Después de cada envío por el carril, consulta el nonce de la EVM antes del siguiente — el indexador se retrasa un poco respecto a la confirmación de Solana, y de lo contrario la siguiente llamada se construiría sobre un nonce que la cadena ya ha gastado.

> **Primero atómico, reenvía ante el rechazo.** El valor predeterminado para cada llamada es una transacción EVM ejecutada dentro de una transacción de Solana, firmada por la wallet del usuario. El reenvío es la excepción para una llamada que no cabe, no una segunda ruta a elegir por preferencia: una llamada directa son dos prompts, una llamada reenviada es uno, y la llamada reenviada se paga en gas Rome en lugar de lamports. Un viaje de varios pasos (aprobar, luego comprar) son varias llamadas completas, cada una su propia transacción, no una ejecución dividida entre transacciones.

**Por qué el RWA no puede filtrarse fuera del perímetro.** El activo reside en el estado de la EVM — sus saldos son almacenamiento dentro de las cuentas del programa Rome EVM. No hay **ningún mint SPL** de él y nada nativo de Solana que mover; los primitivos de movimiento de activos del carril operan sobre cuentas de tokens SPL, que un saldo de almacenamiento EVM no tiene. Todo movimiento que la firma de Solana puede expresar es una llamada al contrato del token, que ejecuta la puerta de lista de permitidos — la suite financiada afirma que una transferencia a una dirección no incluida en la lista revierte de forma idéntica tanto si la firma una clave EVM como una clave de Solana. La pata de efectivo (wUSDC) es la excepción deliberada: está respaldada por SPL y *no* se transfiere a la propia cuenta de tokens del usuario.

***

## Paso 7 — Saber quién tiene la autoridad tras el despliegue

`ArcToken.initialize` se ejecuta desde el constructor del proxy (tx 1) y concede roles a `msg.sender` — el conductor del asistente, es decir, el emisor. Concede **cinco** roles explícitamente:

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

Dos consecuencias que un constructor no debe pasar por alto:

* **`MINTER_ROLE`, `BURNER_ROLE`, y `UPGRADER_ROLE` NO se conceden en initialize.** La oferta inicial se acuña dentro de `inicializar` (un `_mint`interno, no necesita rol), pero un *burn* `mint` ni `posterior` requiere que el emisor primero se conceda a sí mismo el rol. Puede hacerlo, porque posee `DEFAULT_ADMIN_ROLE` (el administrador de cada rol — nada llama a `_setRoleAdmin`, así que `DEFAULT_ADMIN_ROLE` administra todos ellos). Pero es un paso extra deliberado, no un poder omnipresente.
* **`UPGRADER_ROLE` nunca se concede a la fábrica.** Las actualizaciones mediadas por la fábrica (`ArcTokenFactoryV2.upgradeToken`) requieren que **la propia fábrica** tenga `UPGRADER_ROLE` en el token — concedértelo a ti mismo no hace nada. Esa concesión es una puerta de un solo sentido que la fábrica no puede revertir, así que es opcional: si quieres actualizaciones mediadas por la fábrica, `grantRole(UPGRADER_ROLE, factory)` de forma explícita; de lo contrario el emisor actualiza el token directamente.

El modelo completo de 21 autoridades (11 nombres de rol repartidos en seis contratos — el mismo nombre es una autoridad distinta en cada contrato) está codificado en `, y no es simétrica (`. Consulta `rolesRequiredFor(contract, functionName)` en lugar de leer el contrato propio de un rol, porque cuatro funciones de storefront y ambas funciones de fábrica están protegidas por una autoridad que vive en un *distinto* .

***

## Paso 8 — Distribuir rendimiento

El token paga rendimiento en wUSDC (fijo en `inicializar`, modificable mediante `setYieldToken` menos de `YIELD_MANAGER_ROLE`). La distribución recorre el conjunto de titulares:

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

Los mecanismos que importan para ejecutarlo correctamente:

* **El `totalAmount` completo se extrae del llamador solo en la `startIndex == 0` ventana** (`safeTransferFrom(msg.sender, this, totalAmount)`). Aprueba ese total al token antes de la primera ventana; las ventanas posteriores pagan con el saldo ya mantenido.
* **`nextIndex` se reinicia a `0` cuando termina el recorrido.** Bucle `distributeYieldWithLimit(total, nextIndex, …)` hasta `nextIndex` vuelve `0`.
* **Las participaciones de los titulares restringidos por rendimiento permanecen en el contrato del token** — se omiten, no se redistribuyen.

> **En Rome, el límite práctico es `maxHolders = 1` por transacción** — el mismo tope de 62 cuentas del paso 2 —, así que el rendimiento se recorre un titular por transacción (medido \~318 K gas por titular). Cada titular en lista de permitidos, sea EVM o nativo de Solana, recibe prorrateado; el script de referencia es `measure-yield-batch.ts` y el paso de rendimiento del smoke financiado lo afirma de extremo a extremo.

```bash
# Formato de referencia de USAGE.md: recorre un titular por tx hasta que nextIndex vuelva a 0
distributeYieldWithLimit(total, offset, 1)
```

***

## Paso 9 — Verifica lo que desplegaste

Nada envía fuentes automáticamente a ningún sitio en Rome, así que la verificación es un paso que ejecutas tú. Después de cualquier despliegue — de infraestructura o de un token nuevo — ejecuta el verificador de solo lectura, sin claves e idempotente (los contratos ya verificados se omiten, así que volver a ejecutarlo tras emitir un token verifica solo los nuevos):

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

Espera los **tres** contratos por token (proxy + ambos módulos) más la infraestructura, e informa de lo que no pudo verificar en lugar de hacer fallar un despliegue. Hacer esto a mano una vez se dejó siete contratos sin verificar.

Registrar el activo en el registro de Rome trata la verificación como una **puerta**, no como adorno (`register-asset.ts`): un token obtiene su registro `apps/arc/<chain>.json` — que contiene `standard: arc-permissioned-erc20` y un `transferRestriction` que nombra su puerta de lista de permitidos — solo cuando sus tres contratos están verificados en Sourcify. Ese registro lee la cadena para obtener sus datos (un token desplegado por el asistente no tiene un recibo comprometido) y solo escribe un checkout local del registro; cerrar el PR es tarea de una persona.

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # verificar + preparar el registro de cumplimiento
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # vista previa solo lectura
```

Para una prueba de extremo a extremo de todo el flujo — crear, poner en lista de permitidos, activar la puerta, vender en ambos carriles, distribuir rendimiento — ejecuta el smoke financiado contra cualquier cadena:

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

***

## Paso 10 — Saber qué queda fuera de la cadena

El modelo de confianza es deliberadamente honesto, y un constructor debería representarlo del mismo modo a sus propios usuarios:

* **La bandera de lista de permitidos es tu decisión fuera de la cadena.** KYC/AML ocurre en tu proceso — tus proveedores, tus reglas. La cadena registra y hace cumplir solo el *resultado*, `isWhitelisted(addr)`.
* **El único estado en cadena es un booleano por dirección.** Nada de PII, nada de documentos, nada de reclamaciones de identidad, nada de atestaciones en cadena, nada de prueba criptográfica de a quién pertenece una dirección. Este es el modelo de Arc tal como se usa en Plume; intercambia las transferencias más pesadas de un estándar de identidad en cadena (p. ej. ERC-3643) por mecánicas más ligeras y confianza mantenida por el emisor.
* **La recuperación es un poder del emisor, no una salida de emergencia.** Una wallet perdida — EVM o Solana — se recupera poniendo en lista de permitidos una dirección de reemplazo y, si hace falta, usando mint/burn/upgrade bajo tu propio proceso legal (Arc no tiene un primitivo integrado de transferencia forzada). La custodia de la clave del emisor es, por tanto, parte de la postura de cumplimiento.
* **Sin relayer propio de Bloom, sin superficie de custodia.** Los usuarios mantienen su propio gas en ambos carriles. Un servicio de pagador de comisiones operado por la app significaría mantener claves — una superficie que un producto RWA no debería añadir. El único reenvío en el carril de Solana es el del proxy de la cadena, para una llamada demasiado grande para una sola transacción, y el usuario aun así la autoriza con su propia firma y la paga con su propio gas Rome.

***

## Referencia: la herramienta

Cada script se ejecuta desde el directorio de la herramienta, con `scripts/` exportados. `PRIVATE_KEY`, `CHAIN_ID`, y `REGISTRY_ROOT` exportados.

| Script                          | Qué hace                                                                                  |
| ------------------------------- | ----------------------------------------------------------------------------------------- |
| `deploy-infra.ts`               | Una vez por cadena: los cuatro contratos compartidos, configurados para wUSDC.            |
| `create-token.ts`               | El asistente por etapas — ocho transacciones, un token.                                   |
| `rotate-factory.ts`             | Despliega una fábrica nueva tras un cambio de compilador/artefacto; reconfigura.          |
| `verify-artifact-provenance.ts` | Demuestra que tu artefacto de proxy es aceptado por la fábrica desplegada (solo lectura). |
| `verify-deployments.ts`         | Verifica los tres contratos por token + la infraestructura en Sourcify (solo lectura).    |
| `register-asset.ts`             | Verifica la puerta y luego prepara el registro de cumplimiento.                           |
| `measure-yield-batch.ts`        | Vuelve a medir el techo de rendimiento por tx en una cadena.                              |
| `smoke.ts`                      | La suite financiada de extremo a extremo en ambos carriles.                               |
| `sweep-synthetic-native.ts`     | Recupera gas nativo de una cuenta sintética (higiene de pruebas).                         |

Hay un contexto más profundo junto a esta guía: `docs/ARCHITECTURE.md` (el modelo de aplicación por capas), `docs/LANES.md` (los dos carriles y la custodia), `docs/COMPLIANCE.md` (el modelo de confianza), y `docs/USAGE.md` (el manual del 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/es/apps-en-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.
