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

# 6. Tokens on both sides

How one SPL token appears as an ERC-20 wrapper for EVM wallets and as a token account for Solana wallets, and the one-time grant that lets contracts move it.

Tokens are the base of every use case in [2. What you can build](https://docs.rome.builders/rome-academy/02-what-you-can-build.md): a pool, a vault or a lending market all move the same asset that Solana wallets hold. An SPL wrapper exposes an SPL mint through an ERC-20 interface. For tokens a wallet holds, the wrapper reads the balance in the wallet's Rome-derived token account, so Solana and Solidity see the same balance. This lesson explains how that works and the one grant every user must make before your contract can move their tokens.

## What you'll learn

* How an SPL wrapper exposes a wallet's Solana token balance through ERC-20 methods.
* What the factory and the wrapper do, and which wrapper to use.
* How tokens held by contracts differ from tokens held by wallets.
* The one-time `approve_spl` grant, how to check it and how it breaks.

## Before you start

* Finish [5. Call Solana from Solidity](https://docs.rome.builders/rome-academy/05-call-solana-from-solidity.md). You need the idea of the external-authority PDA and the Helper precompile.
* Have a funded Hadrian wallet and a deployed contract. The canonical wrapper addresses are in the chain's `tokens.json` in the registry: the entry with `kind: "spl_wrapper"` and symbol `wUSDC`. [Hadrian](https://docs.rome.builders/networks/hadrian.md) links to the chain's registry folder.
* The USDC token account you created with `createMyAta` in lesson 5. The grant needs it to exist.

## One balance, two views

Every EVM address has an external-authority PDA on Solana, and that PDA owns the address's token accounts. The ERC-20 wrapper's `balanceOf` reads the wallet's token account directly. `totalSupply` reads the mint.

Inside Rome, a wallet's SPL token and its ERC-20 wrapper read the same token account. A Solana wallet that holds USDC and an EVM address that holds USDC both hold the same mint, and both trade against the same pool accounts. That is how liquidity stays in one place on Rome. The picture and the details are in [Token interop](https://docs.rome.builders/core-concepts/token-interop.md#the-shared-state-model).

## Wallets and contracts hold tokens differently

The shared balance holds for wallets. Contracts differ. A contract cannot send the one-time grant described below on a user's behalf, so the ordinary wrappers hold a contract's tokens in an escrow token account and keep a ledger of what each contract owns. Hooked Token-2022 wrappers keep no ledger and use the contract's own token account.

Two things follow:

* Two wrappers over the same mint show the same wallet balance. They can disagree about a contract's balance, because each keeps its own ledger.
* For pools, vaults and lending markets, use the canonical wrapper that the registry names for each mint on each chain. Do not pick one by name.

A transfer to a contract through the wrapper credits that ledger. It does not give the contract a token account it can spend from. Flows that need the contract to act on Solana use the path in [Integrate a Solana program](https://docs.rome.builders/pages/gpZ5lOamv8YlMrUbFYh1#id-3.-tokens-in-tokens-out).

## The factory and the wrapper

`ERC20SPLFactory` deploys a wrapper for an SPL mint. Each factory allows one wrapper per mint. The wrapper gives a full ERC-20 interface:

* `balanceOf` and `totalSupply` read Solana state.
* `transfer` and `transferFrom` move tokens on Solana.
* `approve` and `allowance` keep ordinary ERC-20 allowances in EVM storage, because a token account has no such thing.

You rarely deploy a wrapper. Rome and the registry already carry the canonical ones for USDC, ETH and SOL. You deploy one only when you bring a new mint. Both factory calls are in [The factory](https://docs.rome.builders/core-concepts/token-interop.md#the-factory). The factory also handles Token-2022 mints, but their extensions change the integration: a hooked wrapper reverts plain `transfer` and `transferFrom`, and a transfer-fee mint can deliver less than you send. Read [Token-2022 mints](https://docs.rome.builders/core-concepts/token-interop.md#token-2022-mints) before using one in your vault.

Amounts must fit in `uint64`, because SPL amounts do, and the wrapper rejects anything larger. The gas token has its own decimals, and native gas balances use 18. Converting between them must be exact. The gas token on Hadrian and Rubicon is USDC.

## The one-time grant

The wrapper moves a user's tokens as the SPL delegate of the user's token account. A token account has to name that delegate before the wrapper can move anything. The user does this once per wrapper with one call, for the maximum amount:

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

Four details matter in practice:

* **The user sends it.** The grant is signed by the user's own account, sent straight to the Helper precompile. Your contract cannot send it for them. Build an "Enable" step into your front end.
* **It applies to everyone.** MetaMask wallets and the synthetic addresses of Solana wallets both need it, for every wrapper whose tokens they want to move.
* **Check it first.** The wrapper's `isEnabled(user)` returns `true` once the grant is in place. Read it before a transfer instead of assuming.
* **Grant the maximum.** `isEnabled` stays `true` while any part of a capped grant remains. A capped grant breaks ordinary transfers once it runs low, and your app will not know to ask again.

The mint to pass is `mint_id()` on the wrapper. A worked front-end version for both wallet types is in [One-time: grant the wrapper](https://docs.rome.builders/developer-guides/dual-lane-app.md#one-time-grant-the-wrapper).

### How it breaks

A token account has one delegate. If the user grants a bridge or a router, that grant replaces the wrapper's, and the wrapper stops working for that user. The symptom is a revert with SPL error `0x4`, an owner mismatch. The fix is to grant the wrapper again. So check `isEnabled` before a flow that depends on the wrapper, not once at sign-up.

A new factory version brings a new wrapper, and each wallet grants the new one in the same way.

## Moving tokens out

Because the wrapper balance is already the SPL balance, moving a token out to Solana is an SPL transfer.

* To another Solana wallet from an EVM wallet: `transfer_spl` sent straight from the wallet to the Helper precompile, or `RomeBridgeWithdraw.bridgeOutToSolana`, which also needs a grant for the bridge contract. Both need the recipient's token account to exist.
* To the wallet that signed the transaction: `transfer_spl_to_signer`. It reaches the user's own wallet only on the wallet-signed Solana lane. From MetaMask the signer is Rome's proxy payer, so use the other two.
* For the gas token, `withdraw_to_ata` and `deposit_from_ata` convert between native gas and the token in a token account.

Solgate connects Solana assets to AggLayer EVM chains in both directions, on mainnet and testnet. On testnet, SPL token registration is permissionless. USDC uses CCTP. [Lesson 10](https://docs.rome.builders/rome-academy/10-from-other-chains.md) returns to inbound flows and the bridge. The method list is in [Deposit and withdraw](https://docs.rome.builders/core-concepts/token-interop.md#deposit-and-withdraw).

## Check yourself

On Hadrian, with the wallet you funded:

1. Read `isEnabled` for your address on the canonical wUSDC wrapper from the registry.
2. Make sure your USDC token account exists. The `createMyAta` call in lesson 5 created it. If you skipped that, wrap a little gas into wUSDC with `withdraw_to_ata`, as in [The same app from MetaMask](https://docs.rome.builders/developer-guides/dual-lane-app.md#the-same-app-from-metamask).
3. If `isEnabled` is `false`, send the `approve_spl` grant to the Helper precompile. Use the code in the dual-lane guide linked above.
4. Read `isEnabled` again. It should now be `true`.
5. Find your grant transaction on the [Via explorer](https://docs.rome.builders/apps-on-rome/via.md). Look for the SPL Token `ApproveChecked` instruction.

<details>

<summary>1. Why do two wrappers over one mint show the same wallet balance?</summary>

Both read the wallet's token account on Solana. A wrapper is a view of the SPL token, not a separate ledger. Only balances held by contracts are tracked per wrapper.

</details>

<details>

<summary>2. A user supplies to your vault, then uses a router that asks for its own <code>approve_spl</code>. Your next <code>transferFrom</code> reverts with SPL error 0x4. Why?</summary>

A token account has one delegate. The router's grant replaced the wrapper's. The user must grant the wrapper again, and your app should check `isEnabled` before the transfer.

</details>

<details>

<summary>3. Which pool wrapper do you use for a new liquidity pool?</summary>

The canonical wrapper the registry names for that mint on that chain. Contract-held balances differ between wrappers.

</details>

## Next

[7. Open your EVM app to Solana wallets](https://docs.rome.builders/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/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.
