> 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-kai-shi/ecosystem.md).

# 生态与仓库

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

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

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

* [架构](/zh/kuai-su-kai-shi/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 编码器、precompile 绑定、一个 `/bridge` 客户端。 | 你正在编写应用或前端代码。       |
| [rome-solidity](https://github.com/rome-protocol/rome-solidity) | Solidity precompile 接口、SPL/ERC-20 包装器以及预言机适配器——合约侧工具箱。                                                                   | 你正在编写合约。            |

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

### Rome ZK EVM rollups

| 仓库                                                              | 它是什么                       | 在以下情况下使用它                   |
| --------------------------------------------------------------- | -------------------------- | --------------------------- |
| [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，并请求其验证密钥。     |

### Canton ZK EVM

| 仓库                                                                                                                      | 它是什么                                                          | 在以下情况下使用它                                                                     |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [canton-zk-evm](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/README.md) | Ostia，一个 Canton zkEVM 的早期版本，它会在一笔交易中结算已证明的 EVM 区块和 Canton 操作。 | 你正在运行本地演示，或研究其网关和证明校验。参见 [Canton ZK EVM](/zh/canton-zk-evm/canton-zk-evm.md). |

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

| 仓库                                                                      | 它是什么                                               | 在以下情况下使用它                      |
| ----------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------ |
| [rome-dex](https://github.com/rome-protocol/rome-dex)                   | 双通道 AMM——带有一个轻量 EVM 路由器的原生 Solana 池。               | 打开另一条通道；一个 **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、bridge 客户端"]
    SOL["rome-solidity — precompile 接口、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 调用、一次 bridge）→ [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts)；参考 [Rome SDK](/zh/chan-pin/rome-sdk.md).
* **编写合约** → [rome-solidity](https://github.com/rome-protocol/rome-solidity)；参见 [部署 Solidity 合约](/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 门户](/zh/rome-shang-de-ying-yong/oracle-gateway.md)).
* **另一条链上的用户** → [从家出发](/zh/kai-fa-zhe-zhi-nan/from-home.md) + [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api).
* **决定你的逻辑放在哪一侧** → [选择你的核心](/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 安装，固定到某个 release tag： `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 所做的。）

合约地址会以每个合约的一组版本形式返回；请选择其 `状态` 是 `生效`. [读取合约列表](/zh/can-kao/contract-addresses.md#reading-the-contracts-list) 会展示其方式。不由应用实时读取的事实也会出现在 [合约地址](/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 指令（注资段、在清扫前创建钱包代币账户）则通过 `submitSolanaInstructionsV1` 作为 v1 交易处理。 `submitRomeTxSolanaLane` 是较早的路径，它在客户端构建一个传统 Solana 交易，并在首次使用时自动预配一个新的合成（`create_pda`）。
* **PDA/ATA 派生、CPI `invoke`/`invoke_signed` 编码器、precompile 绑定**，以及一个 **`/bridge`** 子路径（`@rome-protocol/sdk/bridge`）——报价优先的 bridge 客户端。

完整 API + 示例： [Rome SDK](/zh/chan-pin/rome-sdk.md)，以及指南 [从 EVM 调用 Solana](/zh/kai-fa-zhe-zhi-nan/call-solana-from-evm.md), [从 Solana 调用 EVM](/zh/kai-fa-zhe-zhi-nan/call-evm-from-solana.md)，以及 [构建双通道应用](/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）， **提取** `IWithdraw` (`0x42…16`），以及 **系统** (`0xFF…07`）。一个经过 gas 优化的 **缓存** 家族也在这里；合约始终使用同一条轨道。完整地址表： [合约地址](/zh/can-kao/contract-addresses.md).
* **SPL/ERC-20 包装器** — `SPL_ERC20` （基于 CPI）和 `SPL_ERC20_cached` （缓存轨道，用于 devnet）；任何 SPL 铸币在这里都已作为 ERC-20。
* **预言机适配器** (`contracts/oracle/`）——Pyth/Switchboard 适配器 `rome-oracle-gateway` 部署后，通过 `IAggregatorV3Interface`.
* 实作示例位于 `contracts/examples/`.

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

## 下一步

* [选择你的核心](/zh/he-xin-gai-nian/choose-your-core.md) ——你的逻辑放在哪一侧。
* [快速开始](/zh/kuai-su-kai-shi/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-kai-shi/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.