> 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/13-build-on-solgate.md).

# 13. Build on Solgate

Build on Solgate, the bridge and message route between Solana and Ethereum and AggLayer chains, with what crosses, how messages flow, what they cost and how to move from Hadrian to Rubicon.

Rome makes EVM and Solana one market. Solgate is the bridge and message route between them. It carries Solana tokens out to Ethereum and AggLayer chains and EVM tokens into Solana. It also carries contract-to-contract messages, and the Rome contract that receives one can call a Solana program in the same transaction. This lesson shows what crosses, how a message flows, what to check in a receiver, and how to build on Hadrian now and ship on Rubicon. [Lesson 10](https://docs.rome.builders/rome-academy/10-from-other-chains.md) covers the Rome Bridge, which brings USDC in. Solgate is the route for other tokens and for messages.

## What you'll learn

* Which tokens cross in each direction, and how a token with no Solana mint yet becomes bridgeable.
* What Verified and Unverified mean, and how users add a token to their wallet.
* How a message flows from Ethereum to Rome and on to a Solana program, and back.
* The times and costs measured on Hadrian and Sepolia.
* The rules a receiver contract must follow, and what messages are not a fit for.
* Why Solgate and what you rely on in each direction.
* How to start on Hadrian and what changes on Rubicon.

## Before you start

* Finish [10. Bring users and funds from other chains](https://docs.rome.builders/rome-academy/10-from-other-chains.md). You need the idea of a bridge claim.
* Read [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). A receiver that calls Solana uses the CPI precompile, and a Solana token on Rome is the mint itself.
* Have a funded Hadrian wallet, an EVM wallet with Sepolia ETH, and a Solana wallet with devnet SOL. Step 7 lists the faucets.

## The lesson

### Step 1. Know what crosses

Solgate carries one form of each token per chain, the one recorded on chain. Pick the direction first.

**Solana to Ethereum and AggLayer chains**

| Token                                                                                                                    | Crosses?                                                         |
| ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| SOL                                                                                                                      | Yes, as "Wrapped SOL (Rome)"                                     |
| Classic SPL tokens, meme coins included                                                                                  | Yes. On testnet, pick or paste the mint; its first send lists it |
| Token-2022 whose only extra power is freeze                                                                              | On testnet. Not yet on mainnet                                   |
| Token-2022 with a transfer fee                                                                                           | Not carried                                                      |
| Other Token-2022 (transfer hooks, permanent delegate)                                                                    | Stays on Solana and Rome, where Rome's EVM still uses it         |
| Non-transferable mints, NFTs                                                                                             | No                                                               |
| Tokens another bridge brought to Solana, when the AggLayer reaches their home chain (for example a Wormhole-bridged ETH) | Not bridged twice. Bridge the original from its home chain       |
| USDC                                                                                                                     | Moves by Circle's CCTP, not Solgate                              |

**Ethereum and AggLayer chains to Solana**

| Token                                                                         | Crosses?                                                                       |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| ETH                                                                           | Yes, as "Ether (Rome)", 9 decimals on Solana                                   |
| Standard ERC-20                                                               | Yes, as "\<name> (Rome)", a classic SPL mint. On testnet, permissionless setup |
| Fee-on-transfer ERC-20                                                        | Yes. The bridge books what it received                                         |
| Tokens whose issuer runs its own route to Solana (Circle's CCTP and the like) | Use the issuer's route                                                         |
| Permissioned tokens (ERC-3643 and similar)                                    | The issuer's own route only                                                    |
| Rebasing tokens                                                               | No. Bridge the non-rebasing wrapper                                            |
| Copies another bridge made, when the AggLayer reaches their home chain        | Not bridged twice                                                              |

Rules every token follows:

* Solgate carries one form of each token per chain. Forms made by other bridges stay separate and are never merged.
* Every token Rome creates is named "\<origin name> (Rome)" and keeps the origin's symbol.
* Solana keeps supply in 64 bits, so a token with more than 9 decimals has 9 on Solana. Amounts move in whole Solana units. Dust below one unit stays with the bridge as backing.
* The Solana mint Rome creates has no freeze authority. Its only mint authority is the token's contract on Rome.
* On Rome, a Solana token is the mint. A wallet's Rome balance is its own Solana token account, with no second wrapped copy.
* Tokens born on a Rome chain are not carried by Solgate at this time.

A token with no Solana mint yet becomes bridgeable in a few signed steps. On testnet anyone can do it, from an EVM wallet or a Solana wallet. On mainnet Rome lists the tokens.

1. **EVM-born token.** Send it to Hadrian first. Its first claim there creates its Rome copy. Then open **Add a token** and paste any form: a word, the home-chain address, the Rome address or a Solana mint.
2. **Sign the numbered steps.** They are setup, an optional logo, and finish. A Solana wallet pays in SOL only and never needs Rome gas, because Rome's relay sends the finish for it. The card shows the full cost before you sign. Hadrian's setup fee is 1 USDC or 0.06 SOL, plus network fees.
3. **Solana-born token.** Pick or paste the mint on the Bridge. Its first send adds it to the bridge and lists it, as one-time steps.

The logo is optional, free and one more signature. Keep the file under 256 KB and use PNG, because Solana wallets may not render SVG. You can add it later from My tokens.

### Step 2. Tell users what is Verified, and let them add the token

Verified tokens are on Rome's verified list. Anything else set up through the open path shows **Unverified**. The **Tokens** tab lists every token. Users search by name, symbol or any address. Each row shows logo, tag and route, and expands to per-chain addresses with copy and explorer links, **Add to wallet** and **Bridge**. "Verified only" is on by default.

The criteria for Verified: a real contract on its home chain, shown by a CoinGecko or CoinMarketCap listing or the issuer's site; a logo; and no impersonation of a verified token.

Wallets and explorers run their own checks. On Solana mainnet the usual order is a CoinGecko or CoinMarketCap listing, then Solscan's reputation update and Jupiter verification. Solflare sets its own tag automatically.

EVM wallets get a one-click **Add to wallet** (EIP-747) on Tokens rows, in My tokens and on the arrival screen. Solana wallets read the token's name, symbol and logo from its on-chain metadata.

### Step 3. Follow a message

Any contract on Ethereum or an AggLayer chain can send a message to a contract on Rome, and back. Rome's state lives on Solana, so the receiving Rome contract can call any Solana program in the same transaction, signed by its own PDA, a Solana account only that contract can sign for. A Solana program can send a message out through Rome the same way.

You need messaging when the actor is a contract (a DAO, a governance executor, a vault, an escrow, a Safe) or when Solana has to act on an EVM chain. A person with an EVM wallet does not need it, because the same address works on Rome directly.

```
Ethereum / AggLayer chain               Rome (EVM, state on Solana)                  Solana
sender ─ bridgeMessage(rome, rcvr, …, data) ─► Rome's committee posts the exit root
                                          anyone: claimMessage(proof, data)
                                          └► rcvr.onMessageReceived(origin, net, data)
                                               └► optional CPI via 0xFF..08,
                                                  signed by the receiver's PDA ──────► any program

Solana program ─ CPI into Rome's EVM program, signed by its PDA ─► bridgeMessage(dest, rcvr, data)
                                          Rome's certificate settles on Ethereum ─► anyone claims on the destination
```

Inbound, the sender calls `bridgeMessage`. Rome's committee posts Ethereum's exit root to Rome. Anyone can then call `claimMessage` with the proof, and the bridge calls `onMessageReceived` on your receiver. Outbound, a Solana program calls into Rome's EVM program, which calls `bridgeMessage`. Rome's certificate settles on Ethereum, and anyone claims on the destination.

### Step 4. Read the measured times

These legs ran on Hadrian and Sepolia.

| Leg                                                      | Result                                                                       | Time to claimable           | Cost on Hadrian                               |
| -------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------- | --------------------------------------------- |
| Sepolia contract → Rome contract                         | Delivered                                                                    | 133–158 s                   | $0.096 into a new receiver, $0.0007 after     |
| Sepolia → Rome contract → Solana Memo program, one claim | Memo ran, the receiver's PDA signed                                          | 158 s                       | $0.096 into a new receiver                    |
| ETH value with a message into Rome                       | Arrives as an ordinary wrapped-ETH balance                                   | 396 s (during a test burst) | $0.19                                         |
| Token and message in one Sepolia transaction             | 5 of 5 delivered, token claimed first                                        | Not recorded                | $0.175 + $0.119                               |
| Receiver refuses, then accepts                           | The API's simulation refused the claim, so nothing was sent; it landed later | 412 s                       | $0.0007 for the accepted claim                |
| Rome contract → Sepolia contract                         | Delivered and claimed                                                        | 317 s                       | $0.0007 send; 446,636 gas to claim on Sepolia |
| Solana program → Rome → out                              | Sent from one Solana transaction; not yet claimed on Sepolia                 | n/a                         | 5,000 lamports + a Rome charge (not recorded) |

A Sepolia `bridgeMessage` with a forced exit-root update used 395K to 400K gas. Source-chain gas is extra to the Hadrian costs above.

Not run yet: mainnet, AggLayer L2 messages, a Solana wallet as the sender, value sent out of Rome, value plus a Solana call, a realistic governance receiver, and an iterative claim.

### Step 5. Write a safe receiver

* **Check the caller and the origin.** `msg.sender` must be the bridge. `(originNetwork, originAddress)` must be the sender you trust.
* **Exactly once is yours.** A reverted claim stays claimable and can be retried, and the bridge's exit-root remover role can unset a claim. Keep your own nonce.
* **Nobody claims automatically.** Your app runs a claimer, or the user claims. The claimer pays the receiver's gas.
* **Value in** arrives as wrapped ETH on Rome. **Value out** goes only as wrapped ETH (`bridgeMessageWETH`, in multiples of 1e9 wei), and this path has not been run yet. Rome's gas USDC moves by CCTP, never through the AggLayer.
* **A receiver that calls Solana takes zero-value messages.** Send value as a separate token in the same source transaction, and check in the receiver that it arrived.
* **Measure your compute.** A Solana transaction allows about 1.35M CU and the gas estimate refuses above about 1.25M. The Memo-CPI claim used 813,199 CU, leaving about 0.44 to 0.54M CU for more Solana work. Larger instructions and account counts are not measured yet. For heavier work, such as a DEX swap or a borrow, park the message, then run it in a second transaction.
* **Keep messages small.** A claim of a 16-byte message is already about 2.4 KB of calldata.
* **Cap what one message from Rome can unlock** on the destination, with a limit or a delay. Outbound messages rest on Rome's signers alone.

Messages are not a fit for intents, fast fills, liquidations and price feeds. Sepolia to Rome took 133 to 412 s, and an AggLayer L2 route adds that chain's own settlement. They are also not a fit for heavy Solana work inside a single claim, or for buying Solana tokens through messages.

### Step 6. Know why Solgate, and what you rely on

* **It settles through Polygon's AggLayer on Ethereum.** Rome runs Polygon's AggLayer bridge contracts unmodified. Rome's outbound certificates settle on Ethereum with the AggLayer's pessimistic proof.
* **It has no separate bridge validator network.** The parties are Ethereum, the AggLayer and Rome's own keys: a 2-of-3 committee inbound, Rome's AggLayer signers outbound.
* **It is one market.** On Rome a Solana token is the same mint, not a wrapper of it. A Solana wallet's Rome balance is its own token account, and Rome contracts move the same SPL tokens.
* **It is programmable on both sides.** An EVM message can drive a Solana program in the transaction it lands in. A Solana program can send a message out through Rome.
* **On testnet, setup is permissionless from either wallet.** A Solana wallet pays only SOL. An EVM token becomes a classic SPL mint with no freeze authority, minted only by its contract on Rome.
* **There is one form per chain, no wrap of a wrap.** Rome marks what it makes "(Rome)", leaves tokens with an issuer route to that route and never re-bridges another bridge's copy.
* **It is one connection to the AggLayer.** The same unified bridge reaches Ethereum and every AggLayer chain the app lists.
* **Compare trust models.** Wormhole, LayerZero, CCIP and others also connect Solana and EVM chains, each with its own trust model. Compare the table below with theirs for your use.

| Direction                            | What you rely on                                                                                                                                                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Ethereum → Rome                      | Ethereum, plus a 2-of-3 committee that posts Ethereum's exit root to Rome. Rome's Safe owns it, behind a timelock                                                                                                  |
| AggLayer chain → Rome                | The above, plus that chain's certificate settled on Ethereum                                                                                                                                                       |
| Rome → Ethereum or an AggLayer chain | Rome's AggLayer signers. The pessimistic proof caps each token that came from another chain at what came in. Messages, and tokens whose AggLayer origin is Rome (SOL and other Solana tokens), rest on the signers |

### Step 7. Start on Hadrian

The app is [solgate.testnet.romeprotocol.xyz](https://solgate.testnet.romeprotocol.xyz). It has Bridge, Add a token, Tokens, Claim, Activity and How it works. The live chain list is `GET /v1/chains`.

| Chain            | AggLayer network | Chain ID | Notes                                                                                                                    |
| ---------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| Rome Hadrian     | 74               | 200010   | RPC `https://hadrian.testnet.romeprotocol.xyz/`, explorer `via-hadrian.testnet.romeprotocol.xyz`; state on Solana devnet |
| Ethereum Sepolia | 0                | 11155111 | You claim for yourself                                                                                                   |
| Katana Bokuto    | 37               | 737373   | You claim for yourself                                                                                                   |
| Billions Testnet | 32               | 6913     | You claim for yourself                                                                                                   |

Test tokens:

* **Solana devnet SOL.** faucet.solana.com. A Solana wallet needs nothing else in Solgate.
* **Hadrian gas (USDC).** Testnet USDC from Circle's faucet (faucet.circle.com), brought to your EVM address as Hadrian gas with the Rome Bridge testnet (bridge-api.devnet.romeprotocol.xyz). Pick a source testnet the Rome Bridge lists.
* **Sepolia ETH.** Any public Sepolia faucet.
* **Sepolia ERC-20s already verified on Hadrian.** Aave's Sepolia faucet tokens (DAI, USDT, WBTC, AAVE, EURS). Or deploy your own and set it up.

Contracts and code to read:

* Rome Hadrian bridge: `0x5366e5864cb9dba587a706d8dd48cfdc40b961af` (network 74). Sepolia bridge: `0x528e26b25a34a4A5d0dbDa1d57D318153d2ED582` (network 0).
* Polygon's bridge: `github.com/agglayer/agglayer-contracts`. Read `AgglayerBridge.sol` and `AgglayerBridgeL2.sol` (`bridgeMessage`, `bridgeMessageWETH`, `claimMessage`) and the `IBridgeMessageReceiver` interface (`onMessageReceived`).
* Rome's Solana precompiles: `github.com/rome-protocol/rome-solidity`, `contracts/interface.sol`. CPI to any program is at `0xFF00…0008`, and the SPL token precompile is at `0xff00…0005`.
* Token addresses per chain: `GET /v1/tokens`. Chains: `GET /v1/chains`. Live switches: `GET /v1/switches`.

The message API is live on Hadrian.

| Call                                         | Use                                                                                                                                                                        |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/transfers` `{ networkId, txHash }` | Record a send you mined. `networkId` is the network it left                                                                                                                |
| `GET /v1/transfers?wallet=<address>`         | Your rows                                                                                                                                                                  |
| `GET /v1/transfers?tx=<hash>`                | The rows of one send, a token first                                                                                                                                        |
| `GET /v1/transfers/:id`                      | One row, with its stage: sent → certified → settled → ready\_to\_claim → claimed → received                                                                                |
| `GET /v1/transfers/:id/claim`                | The claim transaction, simulated first. A receiver that would revert comes back as `message_would_fail`. The simulation does not catch a claim over Solana's compute limit |

### Step 8. Move from Hadrian to Rubicon

Rubicon is Rome's mainnet chain, with state on Solana mainnet, settled on the AggLayer on Ethereum mainnet. Solgate is live on Rubicon at [solgate.romeprotocol.xyz](https://solgate.romeprotocol.xyz), with Ethereum, X Layer and Katana, and Rome lists the tokens there. What you build on Hadrian moves over with chain IDs and addresses changed. Measure times and costs again on mainnet, because Hadrian's are testnet figures. The general move is in [11. Ship to Rubicon](https://docs.rome.builders/rome-academy/11-ship-to-rubicon.md).

On mainnet: sends both ways and Claim on Solana, for SOL, ETH, USDT, WBTC and OKB, auto-claim of ETH deposits from Ethereum to an EVM wallet on Rubicon, the Tokens tab, Activity filters, and the Arrived card. Message tracking, permissionless token setup from either wallet and a listing path for Solana-born tokens run on testnet and are not yet available on mainnet. See [Using Solgate](https://docs.rome.builders/apps-on-rome/solgate/using.md).

What changes on mainnet:

* Real gas: USDC on Rubicon (bring it in with the Rome Bridge) and ETH on Ethereum.
* Arrival times follow mainnet settlement: Ethereum to Solana about 120 seconds, Solana to Ethereum about 6 minutes, X Layer from Solana about 18 minutes, Katana from Solana about 4 minutes and Katana to Solana about 65 minutes. [Using Solgate](https://docs.rome.builders/apps-on-rome/solgate/using.md#times) lists them.
* Phantom and Solflare on mainnet add their own instructions to transactions.
* Wallets and explorers run their own token checks (step 2).
* The trust model is the same, with Rome's mainnet committee and signer set.

Build on Hadrian now. Ship on Rubicon when you are ready.

## Check yourself

Run a small round trip on Hadrian.

1. Deploy a test ERC-20 on Sepolia, bridge some to Hadrian, then run **Add a token** with an EVM wallet. Read the card's total before you sign.
2. Create an SPL mint on Solana devnet, pick it on the Bridge with a Solana wallet, send to Ethereum Sepolia and claim there.
3. Write a receiver with the two checks and a nonce. Send one message to it from a Sepolia contract, and claim it with `GET /v1/transfers/:id/claim`.

Then answer:

* Which two values does a receiver check before it trusts a message?
* A receiver calls Solana and must also receive value. How do you send it?
* Why are messages not a fit for a liquidation?

<details>

<summary>Answers</summary>

* `msg.sender`, which must be the bridge, and `(originNetwork, originAddress)`, which must be the sender you trust.
* Send the message with zero value. Send the value as a separate token in the same source transaction, and check in the receiver that it arrived.
* Sepolia to Rome took 133 to 412 s, and an AggLayer L2 route adds that chain's own settlement. A liquidation cannot wait that long.

</details>

## Next

Ideas to build, with where each one starts, are in [Solgate ideas](https://docs.rome.builders/apps-on-rome/solgate/ideas.md). The reference pages are [Building on Solgate](https://docs.rome.builders/apps-on-rome/solgate/builders.md) for tokens and [Messaging on Solgate](https://docs.rome.builders/apps-on-rome/solgate/messaging.md) for messages.

[Back to the course map](https://docs.rome.builders/rome-academy/academy.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/13-build-on-solgate.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.
