> 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/conceptos-basicos/token-interop.md).

# Interop de tokens

Cómo los tokens ERC-20 y SPL son la misma cuenta subyacente en Rome.

Rome representa un token ERC-20 y su token SPL subyacente como una única cuenta compartida. Esta página explica cómo funcionan los tokens entre EVM y Solana.

## El modelo de estado compartido

Para una billetera común, un token ERC-20 en Rome es un **envoltorio transparente** de una cuenta de token SPL en Solana. El saldo ERC-20 de la billetera es su saldo SPL. Una dirección derivada de un programa para la dirección EVM es propietaria de la cuenta de token. Esta es su **PDA con autoridad externa**.

<figure><img src="https://1082203750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-552c639322c2d0e90b312def5db39d06c1871d18%2Ftoken-interop.svg?alt=media" alt="An EVM address and its Solana token account, owned by its external-authority PDA. Multiple wrappers read the same token account. The wrapper escrow account and Solana pool vaults hold tokens of the same Solana mint."><figcaption></figcaption></figure>

* Sin demora de sincronización: el saldo ERC-20 de la billetera es su saldo SPL.
* Las billeteras comunes, incluidas las de MetaMask y las direcciones sintéticas, no sufren fragmentación de liquidez. Todos los envoltorios de una misma acuñación muestran el mismo saldo de la billetera. El método `balanceOf` lee ese saldo de la cuenta de token de la billetera. Los tokens que se mantienen dentro de contratos EVM se guardan por envoltorio (consulta [El contrato de envoltorio](#the-wrapper-contract)).
* En el caso de los tokens de una billetera, no se bloquea nada en un lado mientras se acuñan tokens en el otro. Los tokens mantenidos por un contrato están en la propia cuenta de depósito en garantía del envoltorio en Solana. Cada envoltorio lleva un registro separado de esos tokens.

**Por qué un segundo envoltorio no divide el saldo**

Dos envoltorios de la misma acuñación muestran el mismo saldo de la billetera. Los envoltorios leen `totalSupply` de la acuñación de Solana. En Hadrian (testnet), tres envoltorios de wUSDC devolvieron saldos de billetera coincidentes. Los tres envoltorios de wUSDC (9.0.0, 8.0.0 y mayo de 2026) devolvieron la oferta de la acuñación de Solana.

Cada fábrica permite un envoltorio por acuñación. Una nueva versión de la fábrica puede desplegar otro envoltorio para esa acuñación. El registro indica el envoltorio canónico por cadena.

Una billetera de Solana que tiene USDC directamente y una dirección EVM poseen tokens de la misma acuñación. Los pools de Solana usan las mismas bóvedas y reservas para ambos.

La tabla de titulares en el [explorador Via](https://docs.rome.builders/es/apps-en-rome/via.md) se genera a partir de los eventos `Transfer` de cada envoltorio. Puede diferir del saldo de la cuenta de token porque las transferencias SPL directas, `ActivateAta`, y las transferencias a través de otro envoltorio no aparecen en los eventos de ese envoltorio.

> Las rutas de importación siguientes usan `@rome-protocol/rome-solidity`. El paquete no está en npm; instálalo desde el repositorio público [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) con `npm install github:rome-protocol/rome-solidity`, o `forge install rome-protocol/rome-solidity` con una reasignación de rutas; los contratos de envoltorio y fábrica también necesitan OpenZeppelin en Foundry (consulta [Desplegar contratos Solidity](https://docs.rome.builders/es/guias-para-desarrolladores/deploy-solidity.md#using-the-rome-solidity-sdk)). Las interfaces de precompilación están en [`contracts/interface.sol`](https://github.com/rome-protocol/rome-solidity/blob/master/contracts/interface.sol).

## El contrato de envoltorio

`SPL_ERC20` (y su variante con seguimiento en caché, `SPL_ERC20_cached`, que la fábrica despliega para todas las acuñaciones salvo una con un hook de transferencia activado; consulta [Acuñaciones Token-2022](#token-2022-mints)) proporcionan una interfaz ERC-20 completa sobre una acuñación SPL:

* `balanceOf()` — lee el saldo de la ATA del usuario desde Solana (para una dirección de contrato, lee el registro propio del envoltorio; consulta más abajo)
* `transfer()` / `transferFrom()` — transfieren tokens en Solana
* `approve()` / `allowance()` — las autorizaciones ERC-20 por gastador se almacenan en el almacenamiento de la EVM (una cuenta de token SPL no tiene autorizaciones al estilo de la EVM). Son independientes de la autorización única que se concede a continuación: para poder mover los tokens de un usuario, el wrapper actúa como delegado SPL de ese usuario, quien le concede ese derecho una vez por cartera
* `totalSupply()` — lee la oferta del mint SPL

Un contrato no puede conceder la autorización única, por lo que sus tokens se mantienen en la propia cuenta de tokens del wrapper y se registran en el libro mayor del wrapper. `balanceOf(contract)` lee ese libro mayor.

## La factoría

`ERC20SPLFactory` despliega un wrapper para cualquier mint SPL:

```solidity
import {ERC20SPLFactory} from "@rome-protocol/rome-solidity/contracts/erc20spl/erc20spl_factory.sol";

// Deploy a wrapper, loading name/symbol from the mint's Token-2022 metadata or Metaplex
address wrapper = factory.add_spl_token_with_metadata(splMint);

// Or specify name/symbol manually
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

Dirección de la factoría activa, según las entradas `live` del registro (v0.2.0): Hadrian `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`. Las factorías anteriores siguen en la cadena, pero están marcadas como `deprecated` o `retired` en el [registro](https://github.com/rome-protocol/rome-registry/tree/main/chains); no las uses. El registro es la fuente de verdad, así que lee de él la dirección activa (consulta [Consultar la lista de contratos](https://docs.rome.builders/es/referencia/contract-addresses.md#reading-the-contracts-list)) en lugar de copiarla en tu código.

## Mints canónicos

No existe un contrato de registro de tokens en la cadena. Los wrappers canónicos y los tokens de gas/puente se seleccionan en el registro externo [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry); los wrappers sin permisos creados mediante `add_spl_token_no_metadata` se detectan a partir del evento en la cadena `TokenCreated` . El registro indica el wrapper canónico de cada mint en cada cadena. Los saldos de las carteras se comparten entre wrappers. Cada wrapper registra por separado los saldos que mantienen los contratos de la EVM.

## Operaciones SPL desde Solidity

Para las operaciones primitivas SPL firmadas por el PDA del usuario, usa el precompilado **HelperProgram** (`0xFF…09`) — creación de ATA, transferencias SPL y conversión entre gas y lamports:

```solidity
import {IHelperProgram} from "@rome-protocol/rome-solidity/contracts/interface.sol";

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // create the user's ATA for a mint
helper.transfer_spl(to, tokens, mint);      // transfer SPL from the caller's PDA
```

`transfer_spl` tiene varias sobrecargas (incluida una variante con delegado para los flujos de `transferFrom` ); consulta `interface.sol` para firmas exactas. En la vía con caché, las operaciones equivalentes se encuentran en `ISplCached` (`0xFF…05`) y `IAssociatedSplCached` (`0xFF…06`). Un contrato usa una sola vía de forma coherente.

## Autorización única por cartera

El wrapper mueve los tokens de un usuario como **delegado de SPL** de la cuenta de tokens de ese usuario. Por lo tanto, una cartera debe concederle ese permiso una vez por wrapper, antes de que el wrapper pueda mover nada en su nombre. La autorización se concede mediante una llamada al precompilado Helper (`0xff00000000000000000000000000000000000009`):

```solidity
helper.approve_spl(wrapper, type(uint64).max, mint);   // approve_spl(wrapper, 2^64-1, mint)
```

`approve_spl` está firmada por la propia cuenta del usuario, así que la envía el usuario, no el wrapper ni tu contrato. El mint es `mint_id()` en el wrapper.

* **Quién lo necesita.** Todas las carteras EVM y todas las direcciones sintéticas de usuarios de Solana, por cada wrapper cuyos tokens quieran mover. Un contrato que transfiere tokens mediante `transferFrom` solo funciona para usuarios que hayan autorizado al wrapper.
* **Cómo comprobarlo.** Llama a `isEnabled(user)` en el wrapper. Devuelve `true` cuando la autorización ya está concedida.
* **Qué ocurre si falta la autorización.** La transferencia se revierte con el error de SPL `0x4` (el propietario no coincide).
* **Un delegado por cuenta de tokens.** Una cuenta de tokens SPL tiene un único delegado. Conceder permiso a otro programa para la misma cuenta de tokens, como un puente o un enrutador, reemplaza la autorización del wrapper, que deja de funcionar para ese usuario hasta que vuelva a concederla. Comprueba `isEnabled` antes de una transferencia, en lugar de dar por sentado que la autorización anterior sigue vigente.

Cuando una nueva versión de la fábrica reemplaza un wrapper, cada cartera autoriza al nuevo wrapper con `approve_spl`. El wrapper anterior solo puede mover los tokens de esa cartera mientras siga siendo el delegado de la cuenta de tokens. Autorizar al nuevo wrapper reemplaza ese delegado.

La [guía de aplicaciones de doble vía](https://docs.rome.builders/es/guias-para-desarrolladores/dual-lane-app.md#one-time-grant-the-wrapper) incluye el código completo para ambas vías.

## Depositar y retirar

* **A EVM** — el lado SPL acredita el ATA propiedad del PDA del usuario; el wrapper ERC-20 refleja el saldo de inmediato. Las transferencias entrantes desde otras cadenas se liquidan en la cadena mediante una autorización firmada por el usuario en el puente.
* **Convertir gas al token de gas** — llama al precompilado `Withdraw` (`0x42…16`). `withdraw_to_ata(wei)` quema gas nativo y abona la cantidad equivalente, expresada con los decimales propios del token de gas, en la cuenta de tokens de quien realiza la llamada; el wrapper del token de gas (por ejemplo, wUSDC) la muestra entonces como saldo. `withdraw_to_pda(wei)` envía lamports a la PDA de quien realiza la llamada y solo se aplica a una cadena cuyo gas sea SOL; revierte en Hadrian y Rubicon, que usan USDC como gas, así que usa `withdraw_to_ata` en su lugar. La cantidad se expresa en unidades de gas con 18 decimales y debe ser un número entero de unidades del token de gas: en una cadena cuyo gas sea USDC, debe ser múltiplo de 10^12 (una unidad con 6 decimales); de lo contrario, la llamada revierte. `HelperProgram.deposit_from_ata(wei)` hace lo contrario y convierte el token de gas de la cuenta de tokens de quien realiza la llamada de nuevo en gas nativo, con la misma regla de múltiplos. Estas son conversiones de tokens de gas, no una vía de salida para otros tokens.
* **Enviar a Solana cualquier otro token** — el saldo propio del wrapper ya es el saldo SPL, así que para transferirlo basta con una transferencia SPL:
  * `HelperProgram.transfer_spl_to_signer(amount, mint)` envía los tokens de quien realiza la llamada a la cuenta de tokens de la billetera de Solana que firmó la transacción. Esta vía de retorno llega a la billetera del usuario solo si la transacción en Solana está firmada por la billetera. Si se llama desde MetaMask o mediante el relé, quien firma es el pagador proxy de Rome, por lo que la llamada falla o los tokens van a Rome. Usa `transfer_spl` o `RomeBridgeWithdraw.bridgeOutToSolana` en su lugar.
  * `RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint)` envía los tokens a cualquier billetera de Solana. Requiere que el usuario haya concedido autorización al contrato del puente (`approve_spl(bridge, …)`, consulta la nota anterior sobre el único delegado), y que exista la cuenta de tokens del destinatario; `ensureRecipientAta(solanaRecipient, mint)` la crea.
  * `RomeBridgeWithdraw` también quema USDC para enviarlo a otra cadena mediante CCTP (`burnUSDC`) y envía otros activos mediante Wormhole (`burnETH`, `burnToWormhole`).

Obtén la dirección vigente de `RomeBridgeWithdraw` del registro.

Para transferir otros tokens entre Solana y Ethereum o las cadenas de AggLayer, consulta [Solgate](https://docs.rome.builders/es/apps-en-rome/solgate.md) y [13. Desarrollar en Solgate](https://docs.rome.builders/es/rome-academy/13-build-on-solgate.md).

## Token de gas

Cada cadena tiene su propio token de gas: SOL o un token SPL. La fuente de precios del Rome Proxy puede ser un feed de la API de Hermes, un pool Meteora DAMM v1, un pool Meteora DAMM v2 o un precio fijo. Hadrian (red de pruebas) y Rubicon (red principal) usan USDC. Hadrian usa USDC de prueba. Rubicon usa USDC real. No hay un token de gas predeterminado universal.

## Mints de Token-2022

La fábrica también envuelve mints de Token-2022. Consulta al precompilado Helper qué tipo de mint es mediante `mint_info(mint)` (selector `0xe24bf5d4`) y elige el wrapper según la respuesta. `mint_info` devuelve cinco valores:

| Valor          | Significado                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| `tokenProgram` | el programa de tokens propietario del mint (el programa clásico de tokens SPL o Token-2022)                  |
| `decimals`     | los decimales de la mint                                                                                     |
| `hookProgram`  | el programa de transfer-hook, o cero cuando no hay hook o cuando el hook está presente pero no está activado |
| `feeBps`       | la comisión de transferencia en puntos básicos, o cero cuando no hay ninguna o está establecida en cero      |
| `extensions`   | un mapa de bits de las extensiones Token-2022 que tiene la mint, con el bit N para el tipo de extensión N    |

Qué wrapper obtiene una mint:

| Mint                                                                                                 | Wrapper                                                                                              | `wrapper_kind_by_mint` |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------- |
| Una mint normal, una mint de Token-2022 sin hook o una cuyo hook está presente pero no está activado | el wrapper en caché (`SPL_ERC20_cached`)                                                             | `1`                    |
| Una mint de Token-2022 con un transfer hook activado                                                 | el wrapper con hook (`SPL_ERC20_Token2022Hooked`), implementado mediante `hooked_wrapper_deployer()` | `2`                    |

Una mint con una comisión de transferencia obtiene el wrapper en caché, y su evento `Transfer` indica la cantidad recibida después de la comisión, no la cantidad enviada. Puedes consultar el tipo asignado a una mint en la fábrica mediante `wrapper_kind_by_mint(mint)`; en la fábrica activa de Hadrian, los wrappers de USDC, ETH y SOL devuelven `1`.

Qué se rechaza:

* Una mint con un transfer hook activado no puede obtener uno de los wrappers normales. Implementar `SPL_ERC20` o `SPL_ERC20_cached` directamente en ella revierte con `ArmedTransferHookUnsupported(mint, hookProgram)`. A través de la fábrica, este caso se asigna al wrapper con hook.
* Si una dirección no es una mint SPL, `mint_info` revierte con `Invalid SPL mint account: <address>`.
* Si una mint ya tiene un wrapper, la operación revierte con `Token exists`, y si un símbolo ya está en uso, revierte con `Token with symbol exists`.
* `add_spl_token_with_metadata` primero obtiene el nombre y el símbolo de los metadatos propios de Token-2022 de la mint y, en segundo lugar, de Metaplex. Si la mint no tiene ninguno de los dos, revierte con `Mint asserts no name: use add_spl_token_no_metadata`.

Cómo funciona el wrapper con hook:

* Token-2022 ejecuta el hook en cada transferencia, y el hook necesita cuentas que dependen de la transferencia. El wrapper no puede determinarlas, así que quien realiza la llamada resuelve la lista completa de cuentas a partir de la lista de extra-account-metas de la mint y la proporciona. El wrapper comprueba la parte fija de esa lista (el programa del hook y su cuenta de validación) y la reenvía sin modificaciones.
* La función sencilla `transfer`, `transferFrom` y `bridgeOutToSolana` revierten con `HookAccountPlanRequired`. Usa `transferWithHookAccounts`, `transferFromWithHookAccounts` y `bridgeOutToSolanaWithHookAccounts`, que reciben la lista de cuentas como argumento adicional.
* Si el programa hook de la acuñación cambia después de desplegar el wrapper, las transferencias revierten con `HookConfigurationChanged`.
* Mueve tokens mediante una llamada directa entre programas, la vía heredada, y no usa la vía en caché. Un contrato usa una sola vía de forma consistente, y las llamadas por la vía heredada solo se ejecutan en una ejecución atómica, por lo que una llamada que usa el wrapper con hooks debe caber en una única transacción atómica.
* No lleva un registro de los saldos del contrato. Los tokens enviados a un contrato llegan a su propia cuenta de tokens, y el contrato solo puede reenviarlos después de haber concedido la `approve_spl` al propio wrapper.
* Necesita la misma [concesión única](#one-time-grant-per-wallet) que cualquier otro wrapper.

## Limitaciones

* Las cantidades de tokens SPL son de tipo `uint64` (máximo: 18,446,744,073,709,551,615)
* Las allowances de ERC-20 (`approve` / `allowance`) se almacenan en el EVM. El wrapper mueve tokens como delegado SPL del usuario, autorización que este concede una vez por wrapper (consulta [Concesión única por billetera](#one-time-grant-per-wallet))
* Los símbolos de los wrappers ERC-20 deben ser únicos en cada factory

## Qué hacer a continuación

* [Direcciones de contratos](https://docs.rome.builders/es/referencia/contract-addresses.md) — precompilaciones y direcciones por cadena
* [Llamar a Solana desde el EVM](https://docs.rome.builders/es/guias-para-desarrolladores/call-solana-from-evm.md) — operaciones CPI y SPL desde Solidity
* [Cómo se conectan Solana y el EVM en Rome](https://docs.rome.builders/es/conceptos-basicos/how-solana-and-evm-meet.md)
* [Integra un programa de Solana](https://docs.rome.builders/es/guias-para-desarrolladores/integrate-solana-program.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rome.builders/es/conceptos-basicos/token-interop.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.
