> 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/zh/kuai-su-ru-men/ecosystem.md).

# 生态与仓库

每个公开的 Rome 仓库、其用途及其协作方式——用于导航整体架构的地图。

Rome 的公开表面由一组仓库组成：几个 **基础** 你在其上构建的包、一个脚手架、可供学习的参考应用，以及你的应用调用的两个服务。本页就是这张地图——每个仓库是什么，以及它们如何协同。

两个相邻页面回答不同的问题，本页链接到两者，而不是重复说明：

* [架构](https://docs.rome.builders/zh/kuai-su-ru-men/architecture.md) 解释 **协议** ——EVM 如何在 Solana 程序中运行。
* 每个仓库都附带一个 **`AGENTS.md`** （例如 [rome-sdk-ts/AGENTS.md](https://github.com/rome-protocol/rome-sdk-ts/blob/main/AGENTS.md)）它会根据 **你的起点** （一个 Solidity 合约、一个 Solana 程序、从零开始、从主链出发）路由到最接近你场景的示例。

本页处于中间层级： **整个表面** 以及各部分如何连接。

## 整体概览

### 基础——在这些之上构建

| 仓库                                                              | 它是什么                                                                                                          | 在以下情况下使用           |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------ |
| [rome-registry](https://github.com/rome-protocol/rome-registry) | `@rome-protocol/registry` ——对链上实时事实的只读、自动生成投影（ID、RPC、地址、代币铸币地址、程序 ID、预言机喂价、ALT）。                              | 你需要真实的链上事实——切勿硬编码。 |
| [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts)     | `@rome-protocol/sdk` ——TypeScript 写入路径： `submitRomeTx` + 费用估算、双通道、PDA/ATA + CPI 编码器、预编译绑定，以及一个 `/bridge` 客户端。 | 你在编写应用或前端代码。       |
| [rome-solidity](https://github.com/rome-protocol/rome-solidity) | Solidity 预编译接口、SPL/ERC-20 包装器，以及预言机适配器——面向合约侧的工具包。                                                            | 你在编写合约。            |

这些 `@rome-protocol/…` 上面的名称是包名，但这些包没有发布到 npm。请从 GitHub 安装它们（命令在各章节下方的 [基础层详解](#the-foundation-layer-up-close)）；你代码中的导入路径保持不变。

### Rome ZK EVM Rollup

| 仓库                                                              | 它是什么                      | 在以下情况下使用                   |
| --------------------------------------------------------------- | ------------------------- | -------------------------- |
| [solana-zk-evm](https://github.com/rome-protocol/solana-zk-evm) | ZK Rollup 程序、节点、证明器和运营文档。 | 你在运行一条在 Solana 上结算的 EVM 链。 |
| [rome-zk-guest](https://github.com/rome-protocol/rome-zk-guest) | 为每条链的创世状态构建的批处理 guest 源码。 | 你在构建 guest 并请求其验证密钥。       |

### Ostia（Canton 上的 ZK EVM）

| 仓库                                                                                    | 它是什么                                                               | 在以下情况下使用                                                                                                                                                           |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [canton-zk-evm](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md) | Ostia，是部署在 Canton 上的 ZK EVM：每个已证明的 EVM 区块都会与其 Canton 操作一起在一笔交易中提交。 | 你正在 Ostia DevNet 上构建（[浏览器](https://ostia.devnet.romeprotocol.xyz/)）或运行你自己的 Ostia。参见 [Canton ZK EVM](https://docs.rome.builders/zh/canton-zk-evm/canton-zk-evm.md). |

### 参考应用——通过示例学习

| 仓库                                                                      | 它是什么                                            | 在以下情况下使用                       |
| ----------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------ |
| [rome-dex](https://github.com/rome-protocol/rome-dex)                   | 双通道 AMM——一个原生 Solana 池，配有轻量 EVM 路由器。            | 打开另一条通道；一个 **native-core** 示例。 |
| [aerarium](https://github.com/rome-protocol/aerarium)                   | 双通道借贷——一个 Solidity Comet 核心，Solana 用户通过合成发送者访问。 | 打开另一条通道；一个 **Solidity 核心** 示例。 |
| [cardo](https://github.com/rome-protocol/cardo)                         | EVM 用户通过 CPI 驱动 Solana dApp（兑换/质押/借贷/永续）。       | 一个可供研究的 CPI 到 Solana 的完整应用。    |
| [appia](https://github.com/rome-protocol/appia)                         | 以仓位为先的跨 VM DeFi；用户从其主链访问它。                      | 一个 **从主链出发的** 应用。              |
| [rome-aave-v3-demo](https://github.com/rome-protocol/rome-aave-v3-demo) | Aave v3 的存入/借出/还款，未经修改直接部署。                     | 一个按原样运行的完整 EVM 应用。             |

### 合约分叉——在 Rome 上部署的知名协议

| 仓库                                                                                | 它是什么                     | 在以下情况下使用        |
| --------------------------------------------------------------------------------- | ------------------------ | --------------- |
| [compound-on-rome-comet](https://github.com/rome-protocol/compound-on-rome-comet) | Compound III（Comet）货币市场。 | 分叉一个已知的 EVM 协议。 |
| [rome-aave-v3](https://github.com/rome-protocol/rome-aave-v3)                     | Aave v3 合约分叉。            | 分叉一个已知的 EVM 协议。 |

### 服务——你的应用调用这些

| 仓库                                                                          | 它是什么                                                                         | 在以下情况下使用         |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------- |
| [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api)         | 链下编排器 + 链上桥接的费用赞助方。不持有密钥。                                                    | 为钱包注资，或从主链发起的流程。 |
| [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) | 通过 Chainlink 向 EVM 暴露 Solana 价格喂价（Pyth、Switchboard） `AggregatorV3Interface`. | 你需要一个价格喂价。       |

### 脚手架——从这里开始

| 仓库                                                                  | 它是什么                                                                                     | 在以下情况下使用 |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- |
| [create-rome-app](https://github.com/rome-protocol/create-rome-app) | `npx github:rome-protocol/create-rome-app` ——搭建一个双通道应用，预先接好 registry + SDK，并附带已注资的双通道检查。 | 启动一个新应用。 |

## 它们如何组合

```mermaid
flowchart TD
    REG["rome-registry — 链上实时事实"]
    SDK["rome-sdk-ts — 写入、CPI、桥接客户端"]
    SOL["rome-solidity — 预编译接口、SPL 包装器、预言机适配器"]
    CRA["create-rome-app — 脚手架"]
    APP["你的应用 — 前端 + 合约"]
    BAPI["rome-bridge-api — 链下编排器，不持有密钥"]
    OG["rome-oracle-gateway — Solana 价格喂价"]

    CRA -->|搭建，预先接线| APP
    REG -->|事实，绝不硬编码| APP
    SDK -->|写入路径与 CPI| APP
    SOL -->|由你的合约导入| APP
    APP -->|SDK /bridge 客户端| BAPI
    APP -->|通过 AggregatorV3Interface 读取| OG
    OG -.->|适配器位于| SOL
    CRA -.->|连接| REG
    CRA -.->|连接| SDK
```

主干由三个基础和一个脚手架构成：

* [**rome-registry**](https://github.com/rome-protocol/rome-registry) 是实时事实的唯一来源。 [**rome-sdk-ts**](https://github.com/rome-protocol/rome-sdk-ts) 是写入路径——以及它的 `/bridge` 子路径是你的应用用来与之通信的客户端 `rome-bridge-api`. [**rome-solidity**](https://github.com/rome-protocol/rome-solidity) 是你的合约（以及分叉）导入的内容；预言机适配器 `rome-oracle-gateway` 部署也在那里。三者彼此独立——选择你的应用所需的部分。
* [**create-rome-app**](https://github.com/rome-protocol/create-rome-app) 将前两个为新应用连接起来，因此新项目一开始就能读取 registry 并通过 SDK 写入。

参考应用是值得了解的例外： **它们早于这些提取出来的包。** cardo 使用 registry 包；appia 在构建时将 registry 投影为静态 JSON；两者都将写入路径内置在自身仓库中，而不是导入 SDK。阅读它们以学习这些模式——但一个 **新的** 应用应从 `create-rome-app` + 这些包开始，而不是通过克隆某个应用。

## 按你的需求导航

* **一个实时链上事实** （ID、地址、mint、程序 ID）→ [rome-registry](https://github.com/rome-protocol/rome-registry)。切勿硬编码。
* **编写应用代码** （一次写入、一次 CPI 调用、一次桥接）→ [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts)；参考 [Rome SDK](https://docs.rome.builders/zh/chan-pin/rome-sdk.md).
* **编写合约** → [rome-solidity](https://github.com/rome-protocol/rome-solidity)；参见 [部署 Solidity 合约](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/deploy-solidity.md).
* **从 Solidity 合约调用 Solana 程序** → CPI 预编译位于 [rome-solidity](https://github.com/rome-protocol/rome-solidity) (`interface.sol`); [cardo](https://github.com/rome-protocol/cardo) 是一个完整示例。
* **一个可运行示例** 的 AMM、借贷、CPI 或从主链出发的应用 → 以上参考应用；每个仓库的 `AGENTS.md` 按起点路由。
* **为新应用搭建脚手架** → [create-rome-app](https://github.com/rome-protocol/create-rome-app).
* **一个价格喂价** → [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) （参见 [Oracle Gateway 门户](https://docs.rome.builders/zh/rome-shang-de-ying-yong/oracle-gateway.md)).
* **另一条链上的用户** → [从主链](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/from-home.md) + [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api).
* **决定哪一侧承载你的逻辑** → [选择你的核心](https://docs.rome.builders/zh/he-xin-gai-nian/choose-your-core.md).

## 基础层详解

### rome-registry——链上实时事实，天生公开

registry 是 **生成的** 来自 Rome 的内部来源：白名单只输出本应公开的内容， **替换** 内部端点为其公开等价端点，并且 **默认拒绝** 其他一切——因此它天生就适合公开使用。它按链发布： `chain.json` / `tokens.json` / `contracts.json` / `oracle.json` / `bridge.json` / `alts.json`，以及 Solana `程序` 以及按协议划分的应用部署。

从 GitHub 安装，并固定到发布标签： `npm install github:rome-protocol/rome-registry#v0.2.0`。你通过 getter 读取它—— `getChain`, `getTokens`, `getContracts`, `getOracle`, `getBridge`, `getAlts`，以及 `getPrograms(network)` （程序 ID 以 network 为键，而不是 chain id）。该包是纯 ESM（目前不包含打包的 TypeScript 类型）。

在集成之前，有两点需要知道：

* **`getTokens()` 不会返回 `assetRef`.** 要找到某个代币的包装器，请匹配其 **mint** (`mintId`）——例如，gas 代币的包装器就是与其 mint 相同的那一项。
* **它从磁盘读取 JSON（`node:fs`）——它不适用于浏览器。** 在 Web 应用中，请在构建时将所需值投影为静态 JSON 文件，并在客户端导入它。（这正是 `create-rome-app` 和 appia 所做的。）

合约地址会按每个合约返回一个版本列表；请选择其中 `状态` 为 `生效`. [读取合约列表](https://docs.rome.builders/zh/can-kao/contract-addresses.md#reading-the-contracts-list) 展示了如何操作。你的应用不会实时读取的事实也会出现在 [合约地址](https://docs.rome.builders/zh/can-kao/contract-addresses.md) 参考文档中。

### rome-sdk-ts——写入路径，双通道皆可

从 GitHub 安装： `npm install github:rome-protocol/rome-sdk-ts#v0.4.0`.

`@rome-protocol/sdk` （v0.4.0）封装了 Rome 写入所需的一切，因此你无需手工编写 calldata 或费用：

* **`submitRomeTx`** ——EVM 通道写入路径：基于 `eth_estimateGas` 估算 gas（带填充，当估算回退时使用备用上限）并提供 EIP-1559 费用。
* **`submitRomeTxV1`** ——同样的功能，适用于 **Solana 钱包** 来驱动你的 EVM 应用：每次调用一笔 Solana v1 交易，弹出两次钱包提示。合成发送者在静态状态下不持有任何资产； `buildFundLeg`/`buildSweepLeg` 以 ERC-20 形式进出价值（`wUSDC`), **而不是** 原生 `msg.value`；围绕一次调用的普通 Solana 指令（注资段、在 sweep 之前创建钱包代币账户）通过 `submitSolanaInstructionsV1` 作为 v1 交易发送。 `submitRomeTxSolanaLane` 是较早的路径，它在客户端构建一个旧版 Solana 交易，并自动创建一个新的合成`create_pda`）在首次使用时。
* **PDA/ATA 推导，CPI `invoke`/`invoke_signed` 编码器，预编译绑定**，以及一个 **`/bridge`** 子路径（`@rome-protocol/sdk/bridge`）——先获取报价的桥接客户端。

完整 API + 示例： [Rome SDK](https://docs.rome.builders/zh/chan-pin/rome-sdk.md)，以及指南 [从 EVM 调用 Solana](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/call-solana-from-evm.md), [从 Solana 调用 EVM](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/call-evm-from-solana.md)，以及 [构建双通道应用](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/dual-lane-app.md).

### rome-solidity——合约侧工具包

请从 GitHub 安装，而不是 npm。使用 npm 或 Hardhat： `npm install github:rome-protocol/rome-solidity`。使用 Foundry： `forge install rome-protocol/rome-solidity`，然后添加重映射 `@rome-protocol/rome-solidity/=lib/rome-solidity/` 到 `foundry.toml` （在 `[profile.default]`，作为 `remappings = [...]`），以便 `@rome-protocol/rome-solidity/contracts/interface.sol` 能够解析。 `package.json` 为 `@rome-protocol/rome-solidity`，因此同一个导入路径在两种情况下都可用。

你的合约导入内容：

* **`contracts/interface.sol`** ——绑定到其地址的预编译接口： **CPI** `ICrossProgramInvocation` (`0xFF…08`), **Helper** `IHelperProgram` (`0xFF…09`、ATA/PDA 创建、SPL 转账、gas↔lamports）， **Withdraw** `IWithdraw` (`0x42…16`），以及 **System** (`0xFF…07`）。一个经过 gas 优化的 **缓存** 系列也在这里；合约始终一致地使用其中一条路径。完整地址表： [合约地址](https://docs.rome.builders/zh/can-kao/contract-addresses.md).
* **SPL/ERC-20 包装器** —— `SPL_ERC20` （基于 CPI）以及 `SPL_ERC20_cached` （缓存路径，用于 devnet）；任何 SPL mint 都可通过它们视为 ERC-20。
* **预言机适配器** (`contracts/oracle/`）——Pyth/Switchboard 适配器 `rome-oracle-gateway` 部署，通过 `IAggregatorV3Interface`.
* 完整示例位于 `contracts/examples/`.

Solidity SDK 部分中的 [Rome SDK](https://docs.rome.builders/zh/chan-pin/rome-sdk.md) 展示了代码中的导入模式和预编译绑定。

## 下一步

* [选择你的核心](https://docs.rome.builders/zh/he-xin-gai-nian/choose-your-core.md) ——哪一侧承载你的逻辑。
* [快速开始](https://docs.rome.builders/zh/kuai-su-ru-men/quickstart.md) ——部署你的第一个合约。
* [create-rome-app](https://github.com/rome-protocol/create-rome-app) ——搭建一个双通道应用。
* 每个仓库的 `AGENTS.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/zh/kuai-su-ru-men/ecosystem.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.
