> 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/rome-academy/06-tokens-on-both-sides.md).

# 6. Tokens em ambos os lados

Como um token SPL aparece como um wrapper ERC-20 para carteiras EVM e como uma conta de token para carteiras Solana, e a concessão única que permite aos contratos movê-lo.

Tokens são a base de todos os casos de uso em [2. O que você pode criar](https://docs.rome.builders/pt-br/rome-academy/02-what-you-can-build.md): um pool, um vault ou um mercado de empréstimos movimentam o mesmo ativo mantido pelas carteiras Solana. Um wrapper SPL expõe um mint SPL por meio de uma interface ERC-20. Para tokens mantidos por uma carteira, o wrapper consulta o saldo na conta de token derivada de Rome da carteira, para que Solana e Solidity vejam o mesmo saldo. Esta lição explica como isso funciona e a única concessão que cada usuário precisa fazer antes que seu contrato possa movimentar os tokens dele.

## O que você vai aprender

* Como um wrapper SPL expõe o saldo de tokens Solana de uma carteira por meio de métodos ERC-20.
* O que a factory e o wrapper fazem e qual wrapper usar.
* Como os tokens mantidos por contratos diferem dos mantidos por carteiras.
* A `approve_spl` concessão única, como verificá-la e como ela pode deixar de funcionar.

## Antes de começar

* Concluir [5. Chamar Solana a partir de Solidity](https://docs.rome.builders/pt-br/rome-academy/05-call-solana-from-solidity.md). Você precisa conhecer o conceito de PDA de autoridade externa e o precompile Helper.
* Tenha uma carteira Hadrian com saldo e um contrato implantado. Os endereços canônicos dos wrappers estão em `tokens.json` no registro: a entrada com `kind: "spl_wrapper"` e símbolo `wUSDC`. [Hadrian](https://docs.rome.builders/pt-br/redes/hadrian.md) links para a pasta do registro da rede.
* A conta de tokens USDC que você criou com `createMyAta` na lição 5. A concessão exige que ela exista.

## Um saldo, duas visões

Todo endereço EVM tem uma PDA de autoridade externa na Solana, e essa PDA é proprietária das contas de tokens do endereço. O método `balanceOf` do wrapper ERC-20 consulta diretamente a conta de tokens da carteira. `totalSupply` consulta o mint.

Dentro de Rome, o token SPL de uma carteira e seu wrapper ERC-20 consultam a mesma conta de tokens. Uma carteira Solana que mantém USDC e um endereço EVM que mantém USDC possuem o mesmo mint, e ambos negociam com as mesmas contas do pool. É assim que a liquidez permanece em um só lugar em Rome. A ilustração e os detalhes estão em [Interoperabilidade de tokens](https://docs.rome.builders/pt-br/conceitos-principais/token-interop.md#the-shared-state-model).

## Carteiras e contratos mantêm tokens de maneiras diferentes

O saldo compartilhado vale para carteiras. Os contratos são diferentes. Um contrato não pode conceder, em nome de um usuário, a permissão única descrita abaixo; por isso, os wrappers comuns mantêm os tokens de um contrato em uma conta de tokens de custódia e registram o que pertence a cada contrato. Os wrappers Token-2022 com hooks não mantêm um registro e usam a própria conta de tokens do contrato.

Duas consequências:

* Dois wrappers sobre o mesmo mint mostram o mesmo saldo da carteira. Eles podem divergir quanto ao saldo de um contrato, pois cada um mantém seu próprio registro.
* Para pools, vaults e mercados de empréstimos, use o wrapper canônico indicado no registro para cada mint em cada rede. Não escolha um pelo nome.

Uma transferência para um contrato por meio do wrapper credita esse registro. Ela não dá ao contrato uma conta de tokens da qual ele possa gastar. Para fluxos que precisam que o contrato atue na Solana, use o caminho descrito em [Integrar um programa Solana](https://docs.rome.builders/pages/710652f2600ba20ebe907343732b80a7d5c1c611#id-3.-tokens-in-tokens-out).

## A factory e o wrapper

`ERC20SPLFactory` implanta um wrapper para um mint SPL. Cada factory permite um wrapper por mint. O wrapper oferece uma interface ERC-20 completa:

* `balanceOf` e `totalSupply` leem o estado da Solana.
* `transfer` e `transferFrom` movem tokens na Solana.
* `approve` e `allowance` mantenha as permissões comuns de ERC-20 no armazenamento da EVM, pois uma conta de token não tem esse recurso.

Raramente é necessário implantar um wrapper. A Rome e o registro já fornecem os wrappers canônicos para USDC, ETH e SOL. Você só implanta um quando adiciona uma nova mint. As duas chamadas da factory estão em [A factory](https://docs.rome.builders/pt-br/conceitos-principais/token-interop.md#the-factory). A factory também dá suporte a mints Token-2022, mas as extensões delas alteram a integração: um wrapper com hook reverte chamadas simples de `transfer` e `transferFrom`, e uma mint com taxa de transferência pode entregar menos do que você envia. Leia [Mints Token-2022](https://docs.rome.builders/pt-br/conceitos-principais/token-interop.md#token-2022-mints) antes de usar uma no seu vault.

Os valores precisam caber em `uint64`, pois os valores SPL usam esse tipo, e o wrapper rejeita qualquer valor maior. O token de gas tem suas próprias casas decimais, e os saldos de gas nativo usam 18. A conversão entre eles precisa ser exata. O token de gas na Hadrian e na Rubicon é USDC.

## A autorização única

O wrapper movimenta os tokens de um usuário como delegado SPL da conta de token desse usuário. Antes que o wrapper possa movimentar qualquer coisa, a conta de token precisa designá-lo como delegado. O usuário faz isso uma vez para cada wrapper, com uma única chamada, para o valor máximo:

`approve_spl(wrapper, type(uint64).max, mint)` no precompile Helper.

Na prática, quatro detalhes são importantes:

* **O usuário envia a chamada.** A autorização é assinada pela própria conta do usuário e enviada diretamente ao precompile Helper. Seu contrato não pode enviá-la em nome dele. Inclua uma etapa "Ativar" na sua interface.
* **Ela se aplica a todos.** Tanto as carteiras MetaMask quanto os endereços sintéticos das carteiras Solana precisam dessa autorização para cada wrapper cujos tokens desejam movimentar.
* **Verifique antes.** O método `isEnabled(user)` do wrapper retorna `true` quando a autorização está ativa. Leia esse valor antes de uma transferência, em vez de presumir que ela está ativa.
* **Conceda o valor máximo.** `isEnabled` permanece `true` enquanto restar qualquer parte de uma autorização com limite. Uma autorização limitada faz as transferências comuns falharem quando o saldo autorizado fica baixo, e seu app não saberá que deve pedir uma nova autorização.

O valor de mint a passar é `mint_id()` no wrapper. Veja em [Única: conceder autorização ao wrapper](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/dual-lane-app.md#one-time-grant-the-wrapper).

### Como isso falha

Uma conta de token tem apenas um delegado. Se o usuário autorizar uma bridge ou um router, essa autorização substitui a do wrapper, que deixa de funcionar para esse usuário. O sintoma é uma reversão com o erro SPL `0x4`, indicando incompatibilidade de proprietário. A solução é autorizar o wrapper novamente. Portanto, verifique `isEnabled` antes de um fluxo que dependa do wrapper, e não apenas no cadastro.

Uma nova versão da factory traz um novo wrapper, e cada carteira autoriza o novo wrapper da mesma forma.

## Movimentar tokens para fora

Como o saldo do wrapper já é o saldo SPL, para movimentar um token para fora, em direção à Solana, basta fazer uma transferência SPL.

* Para outra carteira Solana, a partir de uma carteira EVM: `transfer_spl` enviado diretamente da carteira para o precompile Helper, ou `RomeBridgeWithdraw.bridgeOutToSolana`, que também precisa de uma autorização para o contrato da bridge. Em ambos os casos, a conta de token do destinatário precisa existir.
* Para a carteira que assinou a transação: `transfer_spl_to_signer`. O token só chega à carteira do próprio usuário na rota Solana assinada pela carteira. No MetaMask, quem assina é o pagador proxy da Rome; portanto, use uma das outras duas opções.
* Para o token de gas, `withdraw_to_ata` e `deposit_from_ata` convertem entre o gas nativo e o token em uma conta de token.

O Solgate conecta ativos da Solana a redes EVM do AggLayer nos dois sentidos, tanto na mainnet quanto na testnet. Na testnet, o registro de tokens SPL não exige permissão. O USDC usa CCTP. [Lição 10](https://docs.rome.builders/pt-br/rome-academy/10-from-other-chains.md) retoma os fluxos de entrada e a bridge. A lista de métodos está em [Depósito e saque](https://docs.rome.builders/pt-br/conceitos-principais/token-interop.md#deposit-and-withdraw).

## Teste seus conhecimentos

No Hadrian, usando a carteira que você financiou:

1. Leia `isEnabled` para o seu endereço no wrapper canônico de wUSDC do registro.
2. Verifique se sua conta de token USDC existe. A chamada `createMyAta` da lição 5 a criou. Se você pulou essa etapa, converta uma pequena quantidade de gas em wUSDC com `withdraw_to_ata`, como em [O mesmo app com MetaMask](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/dual-lane-app.md#the-same-app-from-metamask).
3. Se `isEnabled` for `false`, envie a autorização `approve_spl` para o precompile Helper. Use o código do guia de rota dupla indicado acima.
4. Leia `isEnabled` novamente. Agora, o valor deve ser `true`.
5. Encontre a transação da sua autorização no [Via explorador](https://docs.rome.builders/pt-br/apps-na-rome/via.md). Procure a instrução SPL Token `ApproveChecked` .

<details>

<summary>1. Por que dois wrappers sobre um mesmo mint mostram o mesmo saldo da carteira?</summary>

Ambos leem a conta de token da carteira na Solana. Um wrapper é uma visualização do token SPL, não um registro separado. Apenas os saldos mantidos por contratos são contabilizados por wrapper.

</details>

<details>

<summary>2. Um usuário deposita ativos no seu cofre e, em seguida, usa um roteador que solicita sua própria autorização <code>approve_spl</code>. Sua chamada seguinte a <code>transferFrom</code> falha com o erro SPL 0x4. Por quê?</summary>

Uma conta de token tem um único delegado. A autorização concedida ao roteador substituiu a do wrapper. O usuário precisa conceder a autorização ao wrapper novamente, e seu app deve verificar `isEnabled` antes da transferência.

</details>

<details>

<summary>3. Qual wrapper de pool você usa para um novo pool de liquidez?</summary>

O wrapper canônico que o registro indica para essa emissão naquela rede. Os saldos mantidos em contratos diferem entre os wrappers.

</details>

## Avançar

[7. Abra seu app EVM para carteiras Solana](https://docs.rome.builders/pt-br/rome-academy/07-open-to-solana-wallets.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/rome-academy/06-tokens-on-both-sides.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.
