> 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/getting-started/ecosystem.md).

# Ecosystem & repos

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](/getting-started/architecture.md) explains the **protocol** — how the EVM runs inside a Solana program.
* Each repo ships an **`AGENTS.md`** (e.g. [rome-sdk-ts/AGENTS.md](https://github.com/rome-protocol/rome-sdk-ts/blob/main/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](https://github.com/rome-protocol/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](https://github.com/rome-protocol/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](https://github.com/rome-protocol/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](https://github.com/rome-protocol/rome-dex)                   | Dual-lane AMM — a native Solana pool with a thin EVM router.                              | Opening the other lane; a **native-core** example.   |
| [aerarium](https://github.com/rome-protocol/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](https://github.com/rome-protocol/cardo)                         | EVM users driving Solana dApps (swap/stake/lend/perps) via CPI.                           | A worked CPI-to-Solana app to study.                 |
| [appia](https://github.com/rome-protocol/appia)                         | Positions-first cross-VM DeFi; users reach it from their home chain.                      | A **from-home** app.                                 |
| [rome-aave-v3-demo](https://github.com/rome-protocol/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](https://github.com/rome-protocol/compound-on-rome-comet) | Compound III (Comet) money market. | Forking a known EVM protocol. |
| [rome-aave-v3](https://github.com/rome-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](https://github.com/rome-protocol/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](https://github.com/rome-protocol/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](https://github.com/rome-protocol/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

```mermaid
flowchart TD
    REG["rome-registry — live chain facts"]
    SDK["rome-sdk-ts — writes, CPI, bridge client"]
    SOL["rome-solidity — precompile interfaces, SPL wrappers, oracle adapters"]
    CRA["create-rome-app — scaffolder"]
    APP["your app — frontend + contracts"]
    BAPI["rome-bridge-api — off-chain orchestrator, holds no keys"]
    OG["rome-oracle-gateway — Solana price feeds"]

    CRA -->|scaffolds, pre-wired| APP
    REG -->|facts, never hardcoded| APP
    SDK -->|write path & CPI| APP
    SOL -->|imported by your contracts| APP
    APP -->|SDK /bridge client| BAPI
    APP -->|reads via AggregatorV3Interface| OG
    OG -.->|adapters live in| SOL
    CRA -.->|wires| REG
    CRA -.->|wires| SDK
```

The spine is three foundations and a scaffolder:

* [**rome-registry**](https://github.com/rome-protocol/rome-registry) is the single source of live facts. [**rome-sdk-ts**](https://github.com/rome-protocol/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**](https://github.com/rome-protocol/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**](https://github.com/rome-protocol/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](https://github.com/rome-protocol/rome-registry). Never hardcode.
* **Writing app code** (a write, a CPI call, a bridge) → [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts); reference at [Rome SDK](/products/rome-sdk.md).
* **Writing contracts** → [rome-solidity](https://github.com/rome-protocol/rome-solidity); see [Deploy Solidity Contracts](/developer-guides/deploy-solidity.md).
* **Calling a Solana program from a Solidity contract** → the CPI precompile in [rome-solidity](https://github.com/rome-protocol/rome-solidity) (`interface.sol`); [cardo](https://github.com/rome-protocol/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](https://github.com/rome-protocol/create-rome-app).
* **A price feed** → [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) (see the [Oracle Gateway portal](/apps-on-rome/oracle-gateway.md)).
* **Users on another chain** → [From home](/developer-guides/from-home.md) + [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api).
* **Deciding which side holds your logic** → [Choose your core](/core-concepts/choose-your-core.md).

## 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/contract-addresses.md) 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](/products/rome-sdk.md), and the guides [Call Solana from EVM](/developer-guides/call-solana-from-evm.md), [Call EVM from Solana](/developer-guides/call-evm-from-solana.md), and [Build a dual-lane app](/developer-guides/dual-lane-app.md).

### 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](/reference/contract-addresses.md).
* **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](/products/rome-sdk.md) shows the import patterns and the precompile bindings in code.

## What's next

* [Choose your core](/core-concepts/choose-your-core.md) — which side holds your logic.
* [Quickstart](/getting-started/quickstart.md) — deploy your first contract.
* [create-rome-app](https://github.com/rome-protocol/create-rome-app) — scaffold a dual-lane app.
* Each repo's `AGENTS.md` — the by-starting-point route to the closest example.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rome.builders/getting-started/ecosystem.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.