> 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/08-open-your-solana-program-to-evm-users.md).

# 8. Open your Solana program to EVM users

Let MetaMask users call a program you already run on Solana, through a thin Solidity contract and the CPI precompile, with no port and no second copy of your state.

You have a Solana program that works. Its users hold Solana wallets. Rome lets a second audience reach it, people who hold an EVM wallet such as MetaMask, without you rewriting the program in Solidity.

## What you'll learn

* Why you would open a Solana program to EVM users, and what you keep.
* How an EVM call reaches your program: a thin Solidity contract and the CPI precompile.
* What your program sees as the signer and the accounts.
* How an EVM user's tokens reach your program and come back.
* The limits to design around: one track, one atomic transaction, the account cap.

## The use case

This lesson serves a use case from [What you can build](https://docs.rome.builders/rome-academy/02-what-you-can-build.md): an existing Solana application that wants more users. A lending market, an AMM, a vault, a prediction market or a privacy program all fit.

The EVM audience is large and already has wallets, tooling and habits. If you port your program to Solidity, you maintain two codebases and split your state. On Rome you keep one program and one state. EVM users reach it through a small Solidity contract, and Solana users keep calling it natively. Both trade against the same accounts and the same liquidity. [Choose your core](https://docs.rome.builders/core-concepts/choose-your-core.md) calls this shape (b), a native Solana core with a thin CPI router.

[rome-dex](https://github.com/rome-protocol/rome-dex) is the reference: a native Solana pool, with an EVM router in front of it.

## Before you start

* Finish [7. Open your EVM app to Solana wallets](https://docs.rome.builders/rome-academy/07-open-to-solana-wallets.md), the same idea from the other side.
* Know [5. Call Solana from Solidity](https://docs.rome.builders/rome-academy/05-call-solana-from-solidity.md) and [6. Tokens on both sides](https://docs.rome.builders/rome-academy/06-tokens-on-both-sides.md). This lesson assembles them.
* Have your program deployed on Solana devnet. Hadrian settles there, so the program must exist on that cluster. See [Hadrian](https://docs.rome.builders/networks/hadrian.md).

## The path in short

### Step 1: put one thin contract in front of your program

The contract is an adapter. It holds no business logic. It checks the caller, builds your instruction and calls the CPI precompile with `invoke_signed`. Everything else stays in your Solana program. The call mechanics are in [Call Solana from EVM](https://docs.rome.builders/developer-guides/call-solana-from-evm.md#calling-custom-solana-programs), and the interface is `contracts/interface.sol` in the public [rome-solidity](https://github.com/rome-protocol/rome-solidity) repo.

Your adapter has three ways to hold a user's position. The guide compares them in [Three ways to hold a user's position](https://docs.rome.builders/pages/gpZ5lOamv8YlMrUbFYh1#id-2.-three-ways-to-hold-a-users-position):

| Shape                     | What it is                                            | Fits                                         |
| ------------------------- | ----------------------------------------------------- | -------------------------------------------- |
| Adapter contract          | Pulls the user's tokens, calls your program as itself | A reusable front for a program with deposits |
| User calls the precompile | The user's own authority signs, no contract           | One-time grants and simple programs          |
| Custody-less router       | Never holds tokens, spends the user's delegation      | Swaps and other one-shot actions             |

Pick the adapter for a vault or lending program, and the router for a swap.

### Step 2: know who your program sees

Every EVM address has a Solana identity, its external-authority PDA, derived under the Rome program. When a contract calls the precompile, Rome signs with that contract's authority. Your program sees a 32-byte public key marked as a signer. It never sees a 20-byte EVM address and never sees the user.

So the user is not the signer. To tell users apart, the adapter passes a per-user value in the instruction data, or asks Rome to also sign with a salted sub-PDA derived from the user's address. Your program then keeps one position per sub-PDA. The signer rules are in [Every EVM address has one Solana identity](https://docs.rome.builders/pages/gpZ5lOamv8YlMrUbFYh1#id-1.-every-evm-address-has-one-solana-identity).

Write your program to act on whichever authority signs. It then serves a Solana wallet and an adapter alike.

### Step 3: move the user's tokens

On Rome a user's USDC is one SPL token seen from two sides, as lesson 6 showed. The user's balance sits in a token account that their authority owns. To let an adapter spend it, the user grants the adapter an SPL delegation before the deposit. The adapter pulls the tokens into a token account it owns, then calls your program. On the way out, your program pays to the user's own token account, and the user sees it as an ERC-20 balance at once.

Two traps matter here:

* An ERC-20 `transferFrom` to a contract only credits the wrapper's escrow ledger. The contract gets no token account to spend from. Use the delegation, not the wrapper.
* A token account has one delegate. Your grant displaces the wrapper's grant, and the user's ordinary token transfers stop until they grant the wrapper again. Check `isEnabled` after your flow.

The full sequence is in [Tokens in, tokens out](https://docs.rome.builders/pages/gpZ5lOamv8YlMrUbFYh1#id-3.-tokens-in-tokens-out).

### Step 4: stay inside the limits

* **One track.** A custom program call is a legacy-track CPI. A transaction may not mix it with cached-track calls, so keep the cached wrapper out of that transaction.
* **Atomic only.** A legacy-track CPI cannot run in an iterative transaction. The whole call must fit one Solana transaction, about 1.4M compute units, 64 addresses and 4 KB. Your program shares that compute budget with the Rome program.
* **Accounts up front.** Rome emulates the call and puts every account it touches in the Solana transaction. Each account must be derivable from inputs the adapter has. A fresh account is still named.
* **Shallow depth.** Your program runs one level below Rome. Every program it calls uses another level.
* **Rent is the user's.** Accounts your instruction creates are paid for through the user's gas.

Keep each action to one token movement and one CPI into your program. Split anything larger into two user transactions. The limits are in one table in [Constraints](https://docs.rome.builders/core-concepts/constraints.md).

## A worked example

Say your program is a vault. A Solana user deposits USDC and later withdraws it. You want MetaMask users to do the same.

1. You deploy an adapter that knows your program ID and the USDC mint. In its constructor it creates its own Solana identity and a token account for it.
2. A MetaMask user sends one transaction that grants the adapter an SPL delegation on their USDC.
3. The user calls `deposit`. The adapter pulls the USDC into its own token account, then calls your program with its own authority and a salted sub-PDA for that user as signers.
4. Your program moves the USDC into its vault and records the position under the sub-PDA.
5. The adapter's grant replaced the wrapper's, so your app reads `isEnabled` on the wrapper for the user. It returns `false`, and the user sends `approve_spl` for the wrapper again. The next deposit needs a new grant to the adapter.
6. The user calls `withdraw`. The adapter has your program pay out of the vault straight to the user's token account. The balance shows in MetaMask as the ERC-20 token.

Your Solana users never touched the adapter. They call the vault directly and see the same totals. The matching Solidity sketch is in [A deposit and a withdraw, in Solidity](https://docs.rome.builders/pages/gpZ5lOamv8YlMrUbFYh1#id-7.-a-deposit-and-a-withdraw-in-solidity).

Test on Hadrian first. `eth_call` and `eth_estimateGas` run the same emulation the proxy uses to send, so a CPI that fails there fails on chain for the same reason, and the revert carries your program's error. After a send, read the Solana side of the transaction with `rome_solanaTxForEvmTx`. See [Testing](https://docs.rome.builders/pages/gpZ5lOamv8YlMrUbFYh1#id-8.-testing).

## Check yourself

Take a small program of your own, or the one in rome-dex, and write down, without code:

1. The signer your program sees when an adapter calls it.
2. The accounts one deposit names.
3. The number of token movements and CPIs in that deposit.

Then deploy your adapter on Hadrian, fund the user's token account, send the SPL grant to the adapter and run the deposit through `eth_estimateGas` with the user's address as `from`. The estimate should succeed. If it fails, the revert data names the Solana error.

<details>

<summary>1. A MetaMask user deposits through your adapter. Who signs for your program?</summary>

The adapter's external-authority PDA, plus any salted sub-PDA the adapter lists. Not the user. The user's rights come from the SPL delegation they granted.

</details>

<details>

<summary>2. Why not pull the user's USDC with the wrapper's <code>transferFrom</code>?</summary>

The tokens would land in the wrapper's escrow account and be recorded in its ledger. The adapter would have no token account of its own to pass to your program.

</details>

<details>

<summary>3. Your deposit grows until it makes ten CPIs and Rome runs it iteratively. What happens?</summary>

It fails. A legacy-track CPI is refused in an iterative transaction. Cut the action to one token movement and one CPI, or split it into two transactions.

</details>

## Next

[9. Build a dual-lane app](https://docs.rome.builders/rome-academy/09-build-a-dual-lane-app.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/08-open-your-solana-program-to-evm-users.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.
