Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Integrate a Solana program

Integrate a Solana program with Rome EVM — who the Solana signer is, how value reaches your program and comes back, the one-track rule, atomic vs iterative, and account provisioning.

This guide is for a Solana program team that wants Rome EVM users to use their program — a privacy, lending or vault program that should hold value for EVM accounts. It builds on Call Solana from EVM (the precompile mechanics) and answers the questions that come up once a real program is on the other side: who signs, how tokens get in and out, and which limits shape the design.

The flow used throughout: an EVM account moves USDC into your program ("shield" or "deposit"), your program holds it for that user, and later releases it back ("unshield" or "withdraw"). Replace the verbs with your own.

1. Every EVM address has one Solana identity

Rome derives a Solana account for every EVM address — users and contracts alike — called its external authority:

external_auth(addr) = find_program_address(["EXTERNAL_AUTHORITY", addr_h160], rome_evm_program_id)

It owns the address's associated token accounts (that is where wUSDC.balanceOf(addr) reads from) and it is the key that signs CPIs made on that address's behalf. Your program sees a 32-byte Solana pubkey; it never sees an H160.

Who signs is decided by who calls the precompile:

The precompile is called by
The Solana signer

A contract, with a normal CALL

The contract's own external authority (external_auth(contract)), plus any salted sub-PDAs of the contract it asks for

A user, in a transaction sent straight to the precompile address

The user's own external authority

A contract via DELEGATECALL

The bare authority is refused (DelegatecallOwnerAuthority). invoke without a signer, and invoke_signed with salted sub-PDAs, still run — but those sub-PDAs are namespaced by the running contract's address (["EXTERNAL_AUTHORITY", caller, running_contract, salt]), so pda_with_salt does not derive them. Of HelperProgram only the creation and funding selectors pass (create_ata*, create_pda*, swap_gas_to_lamports, init_spl_mint, create_and_init_mint); they are exempt because their target is bound to the caller or funded by the operator, not because they sign nothing

The consequence is the ERC-20 rule you already know: a contract cannot move a user's assets by itself. It acts as its own identity, and the user grants it rights first. For tokens that have to move on the Solana side, that grant is an SPL delegation on the user's token account; the wrapper's ERC-20 approve is only an EVM-side allowance that the wrapper's own transfers honour. That is how Rome's own token wrappers work, and it is how your adapter will work (section 3).

Salted sub-PDAs: invoke_signed takes a list of bytes32 salts, and Rome signs with ["EXTERNAL_AUTHORITY", caller_h160, salt] for each (bump appended; the caller is the contract on a direct call). HelperProgram.pda_with_salt(addr, salt) returns the address from Solidity. Use one salt per user (for example the user's address) when your program wants a distinct owner account per position.

Funding: an external authority PDA does not have to exist to own an ATA (create_ata is idempotent and the transaction's Solana fee payer covers the rent). It must exist and hold lamports only when it funds accounts your instruction creates. HelperProgram.create_pda(addr) creates it as a plain System CreateAccount, so call it once; it is not idempotent. swap_gas_to_lamports(n) credits the address's PDA with n lamports from the transaction's Solana fee payer, and the caller pays for them in Rome gas: every legacy-track CPI's effect on the fee payer's balance is added to the transaction fee and charged to the user at the gas price, the same way rent for accounts a CPI creates is charged. The Solana lane's provisioning step is described in Call EVM from Solana; a contract provisions its own PDA in its constructor or first call.

2. Three ways to hold a user's position

A. An adapter contract (recommended for a reusable adapter). One Solidity contract fronts your program. The user grants the adapter's authority an SPL delegation on their token account; the adapter pulls the tokens into a token account it owns, calls your program as itself, and keys the user's position inside your program by a per-user sub-PDA or by an identifier it passes in the instruction data. On the way out it tells your program to release to the user's own token account. The adapter is the only Solana identity your program needs to know. The grant is an SPL delegation, not an ERC-20 approve; section 3 explains why and what it costs the user.

B. The user as the Solana signer. The front end sends a transaction from the user's EVM account directly to the CpiProgram precompile (to = 0xff…08, calldata = the ABI-encoded invoke or invoke_signed), so the user's own external authority signs and your program keys the position by it. No adapter contract and no delegation, but each action is an opaque calldata transaction in the wallet, and anything the flow needs besides the CPI (the ATA, a prior transfer) is a separate transaction. It is a fit for one-time grants (a user's approve_spl to a wrapper) and for simple programs, not for multi-step flows. Cardo uses this shape: its front end sends the invoke straight to the precompile from the user's wallet.

C. A custody-less router. A contract that never holds the user's tokens. The user grants the router's authority an SPL delegation on their own token account; the router CPIs into your program with that authority as the transfer authority, so tokens move from the user's token account to your program's account (or back to the user's), and the router holds nothing between calls. The router derives every user-side account from msg.sender, so one user's grant cannot be pointed at another user's account, and it calls one fixed program with fixed instruction shapes rather than acting as a general invoke passthrough. The RomeDexRouter in rome-dex is written this way; rome-dex's EVM lane also offers the raw direct invoke of shape B. It needs the same grant as A, with the same one-delegate cost (section 3), and no pull step.

The rest of this guide follows A; C uses the same grant and the same signing rule.

3. Tokens in, tokens out

USDC on Rome is one SPL mint seen from two sides: the wUSDC ERC-20 wrapper on the EVM side and the external authority's ATA on the Solana side. For a user's own address the two are the same balance: wUSDC.balanceOf(user) reads the user's ATA. Nothing moves or syncs between the two views.

A contract's wrapper balance is not a token account the contract controls. The factory deploys SPL_ERC20_cached for an ordinary mint, and Hadrian's wUSDC is one. That wrapper cannot sign for a contract, so when wUSDC.transferFrom(user, adapter, amount) or transfer sends tokens to a contract, the SPL tokens move into the wrapper's own escrow token account (escrow_ata()), and the wrapper records the amount per contract in its storage. wUSDC.balanceOf(adapter) returns that record, an escrow ledger, not the balance of a token account owned by external_auth(adapter). Your adapter cannot hand those tokens to your program in a CPI; they can only leave through the wrapper again. So an adapter that funds itself with transferFrom has nothing it can spend on the Solana side.

The path that works is an SPL delegation:

  • Grant. The user sends approve_spl(adapter, amount, mint) as a transaction straight to the HelperProgram (to = 0xff…09), where mint is the wrapper's mint_id(). The user's own authority signs, and the delegate it sets on the user's token account is the adapter's external authority.

  • In. The adapter's deposit(amount) pulls with the delegate overload HelperProgram.transfer_spl(srcAta, dstAta, amount, mint), with the user's ATA as source and the adapter's own ATA (HelperProgram.ata(address(this), mint), created once with create_ata) as destination. The adapter's authority signs as the delegate. The tokens are now in a token account owned by external_auth(adapter), which is the account your CPI names; the signer and the source are the adapter's own, so no further permission is needed. They do not show up in wUSDC.balanceOf(adapter).

  • Out. Your program's withdraw instruction transfers to the user's ATA, HelperProgram.ata(user, mint). Receiving needs no signature from the user, and the balance is immediately visible as wUSDC.balanceOf(user). If the ATA may not exist yet, create it first with HelperProgram.create_ata(user, mint) (idempotent).

A token account has one delegate. The grant above replaces the wrapper's own grant on that account. Until the user grants the wrapper again, every wUSDC transfer or transferFrom out of their address reverts with SPL error 0x4. After any flow that uses this grant, call wUSDC.isEnabled(user); when it returns false, ask the user to send approve_spl(wrapper, 2^64-1, mint) to the HelperProgram again, the same maximum grant the wrapper is built around (see One-time: grant the wrapper). A capped grant would break the user's ordinary wUSDC transfers again once it runs low, and isEnabled stays true while any of it remains, so the app would not know to ask again.

To check which wrapper a mint has, read the factory's wrapper_kind_by_mint(mint) (the factory address is in the chain's contracts.json in the registry). 1 is the cached wrapper this section describes. 2 is the direct-CPI wrapper the factory deploys for a Token-2022 mint with an armed transfer hook; this guide does not cover it. The registry's tokens.json lists the wrapper address and mint but not which kind it is.

4. One track per contract, and per transaction

Rome has two families of precompiles that change Solana state, and a transaction uses exactly one of them — the runtime refuses a transaction that mixes mutating calls from both, even across contracts.

Track
Precompiles
Effects land
Works in iterative execution

Legacy

CpiProgram 0xff…08 (invoke, invoke_signed), HelperProgram 0xff…09, Withdraw 0x42…16

Immediately, as a real CPI inside the EVM step

No — a legacy CPI in an iterative transaction fails with CpiProhibitedInIterativeTx

Cached

SplCached 0xff…05, ASplCached 0xff…06, SystemCached 0xff…04, WithdrawCached 0xff…0b

Staged in an overlay and committed as CPIs at the end of the transaction; an EVM revert discards them

Yes

What this means for a program integration:

  • Calling your own program's instructions is legacy-track only. The cached track has no generic invoke; it covers SPL transfers, ATA creation, system-program operations and gas withdrawal.

  • So the step that funds the adapter must be legacy-track too if it runs in the same transaction as the CPI. The cached wrapper's transferFrom is a cached-track call, so it cannot share a transaction with your CPI (and, as section 3 shows, it would only credit an escrow ledger). Pull with HelperProgram.transfer_spl(userAta, adapterAta, amount, mint) instead, after the user has made the adapter the SPL delegate (approve_spl, sent by the user directly to the HelperProgram). The pull and the CPI are both legacy-track, so they run in one transaction.

  • Keep the wrapper out of that transaction. Do not call the wrapper's mutating functions (wUSDC.transfer, transferFrom) from the adapter in the same transaction as a legacy CPI. Check isEnabled(user) and balances from the front end with eth_call.

  • And the CPI transaction must be atomic. That is the bound the design sits under.

Reads are outside the rule: account_info, account_data_at, account_u64_at, account_lamports, pdas_batch_derive and HelperProgram.user_balance / allowance_of are reads of pre-loaded accounts (no CPI), allowed on either track and in both execution modes. Put your pre-checks on them. One ordering rule: once a cached mutation has fired in a transaction, legacy-track reads are blocked for the rest of it — read first, then mutate.

5. Atomic is the budget

An atomic Rome transaction is one Solana transaction: about 1.4M compute units, a 64-address account list and a 4 KB wire size (Solana v1 transactions). The Rome program and your CPI share that budget. A wrapper transfer runs about 170K CU on Hadrian and your instruction adds its own; measure with the Solana receipt's computeUnitsConsumed, not EVM gasUsed.

When emulation decides a transaction does not fit, Rome runs it iteratively across several Solana transactions, and a legacy CPI inside it then fails. Keep each of deposit and withdraw to one token movement plus one CPI into your program, and keep the Solidity around them small. Split anything larger into two user transactions.

CPI depth: Solana allows 4 levels and Rome uses one, so your instruction runs at level 2 with two levels below it (your program → SPL Token leaves one).

6. Account provisioning

Your program does not receive its accounts from Solidity at run time. The proxy emulates every transaction before sending it, records every Solana account the CPIs touched, and places them in the Solana transaction. Your adapter names the accounts in the invoke_signed account list; emulation proves they resolve. Three things follow:

  • Every account your instruction touches must be derivable from inputs the adapter has (its own PDA and sub-PDAs, your program ID, mints, the user's address). SystemProgram.find_program_address and CpiProgram.pdas_batch_derive do the derivations in Solidity.

  • An account that does not exist yet (a fresh position, a fresh ATA) still has to be named in the account list; its address is what reaches the Solana transaction.

  • Everything the transaction touches — including Rome's own accounts for the user, the adapter and the wrapper — must stay under 64 addresses. A design that touches ten markets in one call will not fit.

For the Solana-wallet lane, rome_emulateCallAccounts exposes the same discovery to a client; the SDK uses it.

Two accounts a CPI may never name: the Solana fee payer that submits the transaction (except inside a plain System transfer instruction) and the Rome program itself. A CPI back into the Rome program is refused.

7. A deposit and a withdraw, in Solidity

A minimal sketch of an adapter on the legacy track. The user has already sent approve_spl(adapter, amount, mint) to the HelperProgram (section 3). PRIVACY_PROGRAM is your program ID; encodeDeposit / encodeWithdraw build your instruction data (Borsh, little-endian); the account metas follow your instruction's layout.

The adapter never calls the wUSDC contract. The pull is a HelperProgram call that spends the user's delegation, and the tokens sit in a token account that external_auth(adapter) owns, which is why the CPI can spend them.

Notes on the signer. Rome signs for exactly two kinds of account: the calling contract's bare authority (Helper.pda(address(this))), which signs without being listed in salts, and one salted sub-PDA per entry in salts. Every salt you list must appear in the account list as a signer, or the call fails with signer account calculated from the provided seed was not found. Any other account marked as a signer, including the user's own authority, gets no seed from Rome, and the Solana runtime refuses the CPI. The user's rights over their tokens come from the delegation, never from the adapter signing as the user.

Delegation without a pull: if your program should spend straight from the user's token account, the user sends HelperProgram.approve_spl_raw_delegate(userAta, yourProgramPda, amount, mint, decimals) directly to the HelperProgram, naming your program's PDA as SPL delegate. The Rome bridge uses this for Wormhole. The one-delegate rule from section 3 applies here too: the grant displaces the wrapper's.

8. Testing

  • Deploy against Hadrian (testnet, chain 200010) first; addresses and RPC are in Contract Addresses and the registry.

  • 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 data carries the underlying Solana error (non-evm call error: … in the Solana program log).

  • Read the Solana side of a landed EVM transaction with rome_solanaTxForEvmTx(hash); the Solana receipt is where CU and your program's logs live.

  • A CPI that works in eth_call but is refused when sent usually tripped a limit the emulation reports: the 64-address cap, the atomic CU budget (the transaction went iterative), or the track rule.

9. Reference

  • Precompile reference — every selector on every precompile, with its dispatch class and the delegatecall rule.

  • Constraints — the limits above in one table.

  • Token Interop — wrappers, canonical mints, deposit and withdraw.

  • Reference apps in the public repos: cardo (the user calls the CPI precompile directly, shape B), rome-dex (direct invoke plus a custody-less router, shape C), and aerarium (a Compound III lending app over one shared market; it does not call Solana programs from Solidity (no CPI), so it is not an example of an adapter).

Last updated

Was this helpful?