Ecosystem & repos

Every public Rome repo, what it is, and how they compose — the map for navigating the surface.

Rome's public surface is a set of repositories: a few foundation packages you build on, a scaffolder, reference apps to learn from, and two services your app calls. This page is the map — what each repo is and how they fit together.

Two neighbours answer different questions, and this page links to both rather than repeating them:

• Architecture explains the protocol — how the EVM runs inside a Solana program.

• Each repo ships an AGENTS.md (e.g. rome-sdk-ts/AGENTS.md) that routes by what you're starting from (a Solidity contract, a Solana program, greenfield, from-home) to the one example closest to your case.

This page is the level in between: the whole surface and how the pieces connect.

The surface at a glance

Foundation — build on these

Repo	What it is	Reach for it when
rome-registry	@rome-protocol/registry — read-only, generated projection of live chain facts (ids, RPC, addresses, token mints, program ids, oracle feeds, ALTs).	You need a real chain fact — never hardcode one.
rome-sdk-ts	@rome-protocol/sdk — the TypeScript write path: submitRomeTx + fee sizing, both lanes, PDA/ATA + CPI encoders, precompile bindings, a /bridge client.	You're writing app or frontend code.
rome-solidity	Solidity precompile interfaces, SPL/ERC-20 wrappers, and the oracle adapters — the contract-side toolkit.	You're writing contracts.

Reference apps — learn by example

Repo	What it is	Reach for it when
rome-dex	Dual-lane AMM — a native Solana pool with a thin EVM router.	Opening the other lane; a native-core example.
aerarium	Dual-lane lending — a Solidity Comet core that Solana users reach via a synthetic sender.	Opening the other lane; a Solidity-core example.
cardo	EVM users driving Solana dApps (swap/stake/lend/perps) via CPI.	A worked CPI-to-Solana app to study.
appia	Positions-first cross-VM DeFi; users reach it from their home chain.	A from-home app.
rome-aave-v3-demo	Aave v3 supply/borrow/repay, deployed unchanged.	A full EVM app running as-is.

Contract forks — known protocols, deployed on Rome

Repo	What it is	Reach for it when
compound-on-rome-comet	Compound III (Comet) money market.	Forking a known EVM protocol.
rome-aave-v3	Aave v3 contracts fork.	Forking a known EVM protocol.

Services — your app calls these

Repo	What it is	Reach for it when
rome-bridge-api	Off-chain orchestrator + fee-sponsor for the on-chain bridge. Holds no keys.	Funding a wallet, or a from-home flow.
rome-oracle-gateway	Solana price feeds (Pyth, Switchboard) exposed to EVM via the Chainlink AggregatorV3Interface.	You need a price feed.

Scaffold — start here

Repo	What it is	Reach for it when
create-rome-app	npx github:rome-protocol/create-rome-app — scaffolds a dual-lane app pre-wired to the registry + SDK, with a funded both-lane check.	Starting a new app.

How they compose

The spine is three foundations and a scaffolder:

• rome-registry is the single source of live facts. rome-sdk-ts is the write path — and its /bridge subpath is the client your app uses to talk to rome-bridge-api. rome-solidity is what your contracts (and the forks) import; the oracle adapters that rome-oracle-gateway deploys live there too. The three are independent of each other — pick the ones your app needs.

• create-rome-app ties the first two together for a new app, so a fresh project starts already reading the registry and writing through the SDK.

The reference apps are the exception worth knowing: they predate the extracted packages. cardo consumes the registry package; appia projects the registry to static JSON at build time; and both vendor their write path rather than importing the SDK. Read them to learn the patterns — but a new app should start from create-rome-app + the packages, not by cloning an app.

Navigate by what you need

• A live chain fact (id, address, mint, program id) → rome-registry. Never hardcode.

• Writing app code (a write, a CPI call, a bridge) → rome-sdk-ts; reference at Rome SDK.

• Writing contracts → rome-solidity; see Deploy Solidity Contracts.

• Calling a Solana program from a Solidity contract → the CPI precompile in rome-solidity (interface.sol); cardo is a worked example.

• A working example of an AMM, lending, CPI, or from-home app → the reference apps above; each repo's AGENTS.md routes by starting point.

• Scaffolding a new app → create-rome-app.

• A price feed → rome-oracle-gateway (see the Oracle Gateway portal).

• Users on another chain → From home + rome-bridge-api.

• Deciding which side holds your logic → Choose your core.

The foundation layer, up close

rome-registry — live facts, public by construction

The registry is generated from Rome's internal source: an allowlist emits only what's meant to be public, substitutes internal endpoints for their public equivalents, and default-denies everything else — so it's public-safe by construction. It publishes, per chain, chain.json / tokens.json / contracts.json / oracle.json / bridge.json / alts.json, plus Solana programs and per-protocol app deployments.

You read it through getters — getChain, getTokens, getContracts, getOracle, getBridge, getAlts, and getPrograms(network) (program ids are keyed by network, not chain id). The package is plain ESM (no bundled TypeScript types today).

Two things to know before you wire it in:

• getTokens() doesn't return assetRef. To find a token's wrapper, match on its mint (mintId) — e.g. the gas token's wrapper is the entry that shares its mint.

• It reads JSON from disk (node:fs) — it is not browser-safe. In a web app, project the values you need to a static JSON file at build time and import that in the client. (This is exactly what create-rome-app and appia do.)

Facts your app doesn't read live also appear in the Contract Addresses reference.

rome-sdk-ts — the write path, both lanes

@rome-protocol/sdk (v0.2.1) wraps everything a Rome write needs so you don't hand-roll calldata or fees:

• submitRomeTx — the EVM-lane write path: sizes gas off eth_estimateGas (padded, with a fallback ceiling when estimation reverts) and supplies EIP-1559 fees.

• submitRomeTxSolanaLane — the same, for a Phantom/Solana wallet driving your EVM app. The synthetic sender holds nothing at rest; buildFundLeg/buildSweepLeg move value in and out as an ERC-20 (wUSDC), not native msg.value, and a fresh synthetic is auto-provisioned (create_pda) on first use.

• PDA/ATA derivation, CPI invoke/invoke_signed encoders, precompile bindings, and a /bridge subpath (@rome-protocol/sdk/bridge) — quote-first bridge client.

Full API + examples: Rome SDK, and the guides Call Solana from EVM, Call EVM from Solana, and Build a dual-lane app.

rome-solidity — the contract-side toolkit

What your contracts import:

• contracts/interface.sol — the precompile interfaces bound to their addresses: CPI ICrossProgramInvocation (0xFF…08), Helper IHelperProgram (0xFF…09, ATA/PDA creation, SPL transfers, gas↔lamports), Withdraw IWithdraw (0x42…16), and System (0xFF…07). A gas-optimised cached family also lives here; a contract uses one track consistently. Full address table: Contract Addresses.

• SPL/ERC-20 wrappers — SPL_ERC20 (CPI-based) and SPL_ERC20_cached (the cached track, used on devnet); any SPL mint is already an ERC-20 through these.

• Oracle adapters (contracts/oracle/) — the Pyth/Switchboard adapters rome-oracle-gateway deploys, read via IAggregatorV3Interface.

• Worked examples in contracts/examples/.

The Solidity SDK section of Rome SDK shows the import patterns and the precompile bindings in code.

What's next

• Choose your core — which side holds your logic.

• Quickstart — deploy your first contract.

• create-rome-app — scaffold a dual-lane app.

• Each repo's AGENTS.md — the by-starting-point route to the closest example.