> 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/conceitos-principais/token-interop.md).

# Interoperabilidade de tokens

Como tokens ERC-20 e SPL são a mesma conta subjacente na Rome.

A Rome representa um token ERC-20 e seu token SPL subjacente como uma única conta compartilhada. Esta página explica como os tokens funcionam entre EVM e Solana.

## O modelo de estado compartilhado

Para uma carteira comum, um token ERC-20 na Rome é um **wrapper transparente** sobre uma conta de token SPL na Solana. O saldo ERC-20 da carteira é o saldo SPL dela. Um endereço derivado de programa para o endereço EVM é o proprietário da conta de token. Este é o **PDA de autoridade externa**.

<figure><img src="https://735130481-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>

* Sem atraso de sincronização: o saldo ERC-20 da carteira é o saldo SPL dela.
* Carteiras comuns, incluindo carteiras MetaMask e endereços sintéticos, não têm fragmentação de liquidez. Todo wrapper sobre uma mint mostra o mesmo saldo da carteira. O método `balanceOf` lê esse saldo na conta de token da carteira. Os tokens mantidos em contratos EVM são mantidos por wrapper (veja [O contrato wrapper](#the-wrapper-contract)).
* No caso dos tokens de uma carteira, nada fica bloqueado de um lado e é emitido do outro. Os tokens mantidos em contratos ficam na própria conta de token de escrow do wrapper na Solana. Cada wrapper rastreia esses tokens separadamente.

**Por que um segundo wrapper não divide o saldo**

Dois wrappers sobre a mesma mint mostram o mesmo saldo da carteira. Os wrappers leem o `totalSupply` da mint Solana. Na Hadrian (testnet), três wrappers wUSDC retornaram saldos correspondentes da carteira. Os três wrappers wUSDC (9.0.0, 8.0.0 e May 2026) retornaram o fornecimento da mint Solana.

Cada factory permite um wrapper por mint. Uma nova versão da factory pode implantar outro wrapper para essa mint. O registro identifica o wrapper canônico por cadeia.

Uma carteira Solana que mantém USDC diretamente e um endereço EVM mantêm tokens da mesma mint. Os pools Solana usam os mesmos cofres e reservas para ambos.

A tabela de detentores no [explorador Via](https://docs.rome.builders/pt-br/apps-na-rome/via.md) é construída a partir dos eventos `Transfer` de cada wrapper. Ela pode diferir do saldo da conta de token porque transferências SPL diretas, `ActivateAta`, e transferências por outro wrapper não aparecem nos eventos desse wrapper.

> Os caminhos de importação abaixo usam `@rome-protocol/rome-solidity`. O pacote não está no npm; instale-o pelo repositório público [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) com `npm install github:rome-protocol/rome-solidity`, ou com `forge install rome-protocol/rome-solidity` e um remapping; os contratos wrapper e factory também precisam do OpenZeppelin no Foundry (veja [Implantar contratos Solidity](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/deploy-solidity.md#using-the-rome-solidity-sdk)). As interfaces de precompilação ficam em [`contracts/interface.sol`](https://github.com/rome-protocol/rome-solidity/blob/master/contracts/interface.sol).

## O contrato wrapper

`SPL_ERC20` (e sua variante com rastreamento em cache `SPL_ERC20_cached`, que a factory implanta para todas as mints, exceto uma que tenha um gancho de transferência ativado; veja [Mints Token-2022](#token-2022-mints)) fornece uma interface ERC-20 completa sobre uma mint SPL:

* `balanceOf()` — lê o saldo da ATA do usuário na Solana (para um endereço de contrato, lê o próprio registro do wrapper; veja abaixo)
* `transfer()` / `transferFrom()` — movimentam tokens na Solana
* `approve()` / `allowance()` — permissões ERC-20 por usuário autorizado armazenadas no EVM (uma conta de token SPL não tem permissões no estilo EVM). Elas são independentes da concessão única descrita abaixo: para movimentar os tokens de um usuário, o wrapper atua como delegado SPL desse usuário, e o usuário concede esse direito uma vez por carteira
* `totalSupply()` — lê o fornecimento do mint SPL

Um contrato não pode conceder a permissão única; por isso, os tokens de um contrato ficam na conta de token do próprio wrapper e são contabilizados no livro-razão do wrapper. `balanceOf(contract)` lê esse livro-razão.

## A fábrica

`ERC20SPLFactory` implanta um wrapper para qualquer mint SPL:

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

// Implanta um wrapper, carregando o nome/símbolo dos metadados Token-2022 ou Metaplex do mint
address wrapper = factory.add_spl_token_with_metadata(splMint);

// Ou especifique o nome/símbolo manualmente
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

Endereço da fábrica ativa, conforme as entradas `live` do registro (v0.2.0): Hadrian `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`. Fábricas anteriores ainda estão na blockchain, mas estão marcadas como `deprecated` ou `retired` no [registro](https://github.com/rome-protocol/rome-registry/tree/main/chains); não as use. O registro é a fonte oficial, então leia nele o endereço ativo (consulte [Como ler a lista de contratos](https://docs.rome.builders/pt-br/referencia/contract-addresses.md#reading-the-contracts-list)) em vez de copiar um endereço para o seu código.

## Mints canônicos

Não há um contrato de registro de tokens na blockchain. Os wrappers canônicos e os tokens de gás/bridge são selecionados e mantidos no repositório externo [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry); wrappers sem permissão criados por meio de `add_spl_token_no_metadata` são descobertos pelo evento `TokenCreated` na blockchain. O registro identifica o wrapper canônico de cada mint em cada cadeia. Os saldos das carteiras são compartilhados entre os wrappers. Cada wrapper contabiliza separadamente os saldos mantidos por contratos EVM.

## Operações SPL a partir do Solidity

Para primitivas SPL assinadas pelo PDA do usuário, use a precompilação **HelperProgram** (`0xFF…09`) — criação de ATA, transferências SPL e conversão entre gás e lamports:

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

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // cria a ATA do usuário para um mint
helper.transfer_spl(to, tokens, mint);      // transfere SPL do PDA do chamador
```

`transfer_spl` tem várias sobrecargas (incluindo uma variante com delegado para fluxos de `transferFrom` ); consulte `interface.sol` para assinaturas exatas. Na faixa em cache, as operações equivalentes ficam em `ISplCached` (`0xFF…05`) e `IAssociatedSplCached` (`0xFF…06`). Um contrato usa uma única faixa de forma consistente.

## Concessão única por carteira

O wrapper movimenta os tokens de um usuário como **delegado SPL** da conta de tokens desse usuário. Portanto, a carteira precisa conceder esse direito uma vez por wrapper, antes que ele possa movimentar qualquer token em seu nome. A concessão é feita em uma chamada ao precompile Helper (`0xff00000000000000000000000000000000000009`):

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

`approve_spl` é assinado pela própria conta do usuário, portanto, é o usuário que o envia, não o wrapper nem o seu contrato. O mint é `mint_id()` no wrapper.

* **Quem precisa disso.** Todas as carteiras EVM e todos os endereços sintéticos dos usuários Solana, para cada wrapper cujos tokens desejam movimentar. Um contrato que transfere tokens usando `transferFrom` funciona apenas para usuários que concederam permissão ao wrapper.
* **Como verificar.** Chame `isEnabled(user)` no wrapper. Ele retorna `true` assim que a concessão estiver ativa.
* **O que acontece quando a concessão está ausente.** A transferência falha com o erro SPL `0x4` (incompatibilidade do proprietário).
* **Um delegado por conta de tokens.** Uma conta de tokens SPL tem um único delegado. Conceder permissão a outro programa na mesma conta de tokens, como uma ponte ou um roteador, substitui a concessão do wrapper, que deixa de funcionar para esse usuário até que ele conceda a permissão novamente. Verifique `isEnabled` antes de uma transferência, em vez de presumir que uma concessão anterior ainda está ativa.

Quando uma nova versão da factory substitui um wrapper, cada carteira concede permissão ao novo wrapper com `approve_spl`. O wrapper antigo só pode movimentar os tokens dessa carteira enquanto continuar sendo o delegado da conta de tokens. A concessão ao novo wrapper substitui esse delegado.

O [guia de aplicativos com duas faixas](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/dual-lane-app.md#one-time-grant-the-wrapper) contém o código completo para ambas as faixas.

## Depositar e sacar

* **Para EVM** — o lado SPL credita a ATA pertencente à PDA do usuário; o wrapper ERC-20 reflete imediatamente o saldo. As transferências recebidas de outras blockchains são liquidadas on-chain por meio de uma autorização assinada pelo usuário na ponte.
* **Converter gás no token de gás** — chame o `Withdraw` precompile (`0x42…16`). `withdraw_to_ata(wei)` queima gás nativo e credita o valor equivalente, considerando as casas decimais do próprio token de gás, na conta de token do chamador. O wrapper do token de gás (por exemplo, wUSDC) então exibe esse valor como saldo. `withdraw_to_pda(wei)` paga lamports à PDA do chamador e se aplica somente a uma chain cujo gás é SOL; a chamada é revertida em Hadrian e Rubicon, que usam USDC como gás. Portanto, use `withdraw_to_ata` nesses casos. O valor é expresso em unidades de gás com 18 casas decimais e deve corresponder a um número inteiro de unidades do token de gás: em uma chain que usa USDC como gás, o valor deve ser múltiplo de 10^12 (uma unidade com 6 casas decimais); caso contrário, a chamada é revertida. `HelperProgram.deposit_from_ata(wei)` faz o caminho inverso e converte o token de gás da conta de token do chamador novamente em gás nativo, seguindo a mesma regra dos múltiplos. Essas conversões são de tokens de gás, não uma forma de retirar outros tokens.
* **Envio para Solana de outros tokens** — o saldo do próprio wrapper já é o saldo SPL, então basta transferi-lo para fora como uma transferência SPL:
  * `HelperProgram.transfer_spl_to_signer(amount, mint)` envia os tokens do chamador para a conta de token da carteira Solana que assinou a transação. Esse caminho de retorno chega à carteira do próprio usuário somente quando a transação em Solana é assinada pela carteira. Se a chamada for feita pelo MetaMask ou pelo relay, o signatário será o payer proxy da Rome, então a chamada falhará ou os tokens serão enviados para a Rome. Em vez disso, use `transfer_spl` ou `RomeBridgeWithdraw.bridgeOutToSolana` nesses casos.
  * `RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint)` envia os tokens para qualquer carteira Solana. É necessária a autorização do usuário para o contrato da bridge (`approve_spl(bridge, …)`, consulte a observação acima sobre um único delegate), e a conta de token do destinatário precisa existir; `ensureRecipientAta(solanaRecipient, mint)` cria essa conta.
  * `RomeBridgeWithdraw` também queima USDC para enviá-lo a outra chain via CCTP (`burnUSDC`) e envia outros ativos via Wormhole (`burnETH`, `burnToWormhole`).

Consulte o endereço atualizado de `RomeBridgeWithdraw` no registro.

Para transferir outros tokens entre Solana e Ethereum ou chains da AggLayer, consulte [Solgate](https://docs.rome.builders/pt-br/apps-na-rome/solgate.md) e [13. Desenvolver com Solgate](https://docs.rome.builders/pt-br/rome-academy/13-build-on-solgate.md).

## Token de gás

Cada chain tem seu próprio token de gás: SOL ou um token SPL. A fonte de preços do Rome Proxy pode ser um feed da API Hermes, um pool Meteora DAMM v1, um pool Meteora DAMM v2 ou um preço fixo. Hadrian (testnet) e Rubicon (mainnet) usam USDC. Hadrian usa USDC de teste. Rubicon usa USDC real. Não há um token de gás padrão universal.

## Mints do Token-2022

A factory também cria wrappers para mints do Token-2022. Ela consulta o precompile Helper para identificar o mint usando `mint_info(mint)` (seletor `0xe24bf5d4`) e escolhe o wrapper com base na resposta. `mint_info` retorna cinco valores:

| Valor          | Significado                                                                                                     |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| `tokenProgram` | o programa de token proprietário do mint (o programa clássico SPL Token ou o Token-2022)                        |
| `decimals`     | as casas decimais do mint                                                                                       |
| `hookProgram`  | o programa de transferência com hook, ou zero quando não há hook ou quando o hook está presente, mas não armado |
| `feeBps`       | a taxa de transferência em pontos-base, ou zero quando não há taxa ou quando ela está definida como zero        |
| `extensions`   | um bitmap das extensões do Token-2022 que o mint possui, com o bit N para o tipo de extensão N                  |

O que um mint recebe:

| Mint                                                                                        | Wrapper                                                                                              | `wrapper_kind_by_mint` |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------- |
| Um mint comum, um mint do Token-2022 sem hook ou um cujo hook está presente, mas não armado | o wrapper em cache (`SPL_ERC20_cached`)                                                              | `1`                    |
| Um mint do Token-2022 com um hook de transferência armado                                   | o wrapper com hook (`SPL_ERC20_Token2022Hooked`), implantado por meio de `hooked_wrapper_deployer()` | `2`                    |

Um mint com taxa de transferência recebe o wrapper em cache, e seu `Transfer` evento informa o valor recebido após a cobrança da taxa, não o valor enviado. Você pode consultar o tipo recebido pelo mint na factory com `wrapper_kind_by_mint(mint)`; na factory ativa da Hadrian, os wrappers de USDC, ETH e SOL retornam todos `1`.

O que é recusado:

* Um mint com um hook de transferência armado não pode receber um dos wrappers comuns. Implantar `SPL_ERC20` ou `SPL_ERC20_cached` diretamente nele causa uma reversão com `ArmedTransferHookUnsupported(mint, hookProgram)`. Por meio da factory, esse caso é encaminhado para o wrapper com hook.
* Um endereço que não seja um mint SPL faz com que `mint_info` reverta com `Invalid SPL mint account: <address>`.
* Um mint que já tenha um wrapper reverte com `Token exists`, e um símbolo que já esteja em uso reverte com `Token with symbol exists`.
* `add_spl_token_with_metadata` lê primeiro o nome e o símbolo dos metadados do próprio mint no Token-2022 e, em seguida, do Metaplex. Se o mint não tiver nenhum dos dois, a chamada reverte com `Mint asserts no name: use add_spl_token_no_metadata`.

Como o wrapper com hook funciona:

* O Token-2022 executa o hook em cada transferência, e o hook precisa de contas que dependem da transferência. O wrapper não consegue determinar essas contas, então o chamador resolve a lista completa de contas a partir da lista extra-account-metas do mint e a repassa. O wrapper verifica a parte fixa dessa lista (o programa do hook e sua conta de validação) e a encaminha sem alterações.
* O método simples `transfer`, `transferFrom` e `bridgeOutToSolana` reverter com `HookAccountPlanRequired`. Use `transferWithHookAccounts`, `transferFromWithHookAccounts` e `bridgeOutToSolanaWithHookAccounts`, que recebem a lista de contas como argumento adicional.
* Se o programa de hook do mint mudar depois que o wrapper for implantado, as transferências serão revertidas com `HookConfigurationChanged`.
* Ele movimenta tokens por meio de uma chamada direta entre programas, a rota legada, e não usa a rota em cache. Um contrato usa uma única rota de forma consistente, e as chamadas pela rota legada só são executadas em uma execução atômica; portanto, uma chamada que usa o wrapper com hook precisa caber em uma única transação atômica.
* Ele não mantém um registro dos saldos do contrato. Os tokens enviados a um contrato são depositados na própria conta de tokens do contrato, e o contrato só pode encaminhá-los depois de conceder a `approve_spl` ao próprio wrapper.
* Ele precisa da mesma [concessão única](#one-time-grant-per-wallet) que qualquer outro wrapper.

## Restrições

* As quantias de tokens SPL são do tipo `uint64` (máximo de 18.446.744.073.709.551.615)
* As permissões de ERC-20 (`approve` / `allowance`) ficam armazenadas na EVM. O wrapper movimenta tokens como delegado SPL do usuário, que concede essa permissão uma vez para cada wrapper (consulte [Concessão única por carteira](#one-time-grant-per-wallet))
* Os símbolos de wrappers ERC-20 devem ser exclusivos por fábrica

## Próximos passos

* [Endereços dos contratos](https://docs.rome.builders/pt-br/referencia/contract-addresses.md) — pré-compilados e endereços por cadeia
* [Chamar Solana a partir da EVM](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-solana-from-evm.md) — CPI e operações SPL a partir de Solidity
* [Como Solana e a EVM se conectam na Rome](https://docs.rome.builders/pt-br/conceitos-principais/how-solana-and-evm-meet.md)
* [Integrar um programa Solana](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/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/pt-br/conceitos-principais/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.
