> 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 的公开表面由一组仓库组成：若干 **基础** 可基于其构建的包、一个脚手架、用于学习的参考应用，以及你的应用调用的两个服务。本页就是这张地图——每个仓库是什么，以及它们如何协同。

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

* [架构](/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-dex](https://github.com/rome-protocol/rome-dex)                   | 双通道 AMM——一个原生 Solana 池，配一个轻量 EVM 路由器。         | 打开另一条通道；一个 **native-core** 原生核心示例。 |
| [aerarium](https://github.com/rome-protocol/aerarium)                   | 双通道借贷——Solana 用户通过合成发送者访问的 Solidity Comet 核心。 | 打开另一条通道；一个 **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 — 预编译接口、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、地址、铸币地址、程序 ID）→ [rome-registry](https://github.com/rome-protocol/rome-registry)。绝不要硬编码。
* **编写应用代码** （一次写入、一次 CPI 调用、一次桥接）→ [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 程序** → 见 [rome-solidity](https://github.com/rome-protocol/rome-solidity) (`interface.sol`); [cardo](https://github.com/rome-protocol/cardo) 中的 CPI 预编译示例。
* **一个可运行示例** 一个 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 `程序` 以及各协议的应用部署。

你通过 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-wen-dang/contract-addresses.md) 参考资料中。

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

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

* **`submitRomeTx`** —— EVM 通道写入路径：根据 `eth_estimateGas` （填充后；当估算回退时提供一个回退上限）并提供 EIP-1559 费用。
* **`submitRomeTxSolanaLane`** —— 同样的逻辑，适用于由 **Phantom/Solana** 钱包驱动你的 EVM 应用。合成发送者在静态状态下不持有任何资产； `buildFundLeg`/`buildSweepLeg` 将价值以 ERC-20（`wUSDC`), **而非** 原生 `msg.value`），并且首次使用时会自动配置一个新的合成账户（`create_pda`）。
* **PDA/ATA 推导、CPI `invoke`/`invoke_signed` 编码器、预编译绑定**，以及一个 **`/bridge`** 子路径（`@rome-protocol/sdk/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——合约侧工具包

你的合约导入以下内容：

* **`contracts/interface.sol`** —— 绑定到其地址的预编译接口： **CPI** `ICrossProgramInvocation` (`0xFF…08`), **辅助** `IHelperProgram` (`0xFF…09`、ATA/PDA 创建、SPL 转账、gas↔lamports）， **提现** `IWithdraw` (`0x42…16`），以及 **系统** (`0xFF…07`）。一个经 gas 优化的 **缓存** 系列也在这里；合约会始终使用同一条路径。完整地址表： [合约地址](/zh/can-kao-wen-dang/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](/zh/chan-pin/rome-sdk.md) 展示了代码中的导入模式和预编译绑定。

## 下一步

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