生态系统与仓库

每个公开的 Rome 仓库，它是什么，以及它们如何组合——用于导航整体架构的地图。

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

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

• 架构 解释 协议 —— EVM 如何在 Solana 程序中运行。

• 每个仓库都附带一个 AGENTS.md （例如 rome-sdk-ts/AGENTS.md），它会依据 你的起点 （一个 Solidity 合约、一个 Solana 程序、全新起步、从家链发起）路由到最接近你场景的示例。

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

表面概览

基础——以此为基础构建

仓库	它是什么	在以下情况下使用
rome-registry	@rome-protocol/registry —— 只读、生成的链上实时事实投影（ID、RPC、地址、代币铸币地址、程序 ID、预言机数据源、ALT）。	你需要真实的链上事实——绝不要硬编码。
rome-sdk-ts	@rome-protocol/sdk —— TypeScript 写入路径： submitRomeTx 加上费用估算、双通道、PDA/ATA + CPI 编码器、预编译绑定，以及一个 /bridge 客户端。	你正在编写应用或前端代码。
rome-solidity	Solidity 预编译接口、SPL/ERC-20 包装器，以及预言机适配器——合约侧工具包。	你正在编写合约。

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

仓库	它是什么	在以下情况下使用
rome-dex	双通道 AMM——一个原生 Solana 池，配一个轻量 EVM 路由器。	打开另一条通道；一个 native-core 原生核心示例。
aerarium	双通道借贷——Solana 用户通过合成发送者访问的 Solidity Comet 核心。	打开另一条通道；一个 Solidity 核心 原生核心示例。
cardo	EVM 用户通过 CPI 驱动 Solana dApp（兑换/质押/借贷/永续）。	一个值得研读的、从 CPI 到 Solana 的实作应用。
appia	以仓位为先的跨 VM DeFi；用户从自己的主链访问它。	一个 从家链 应用。
rome-aave-v3-demo	Aave v3 存入/借出/偿还，按原样部署。	一个按原样运行的完整 EVM 应用。

合约分叉——已知协议，部署在 Rome 上

仓库	它是什么	在以下情况下使用
compound-on-rome-comet	Compound III（Comet）货币市场。	分叉一个已知的 EVM 协议。
rome-aave-v3	Aave v3 合约分叉。	分叉一个已知的 EVM 协议。

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

仓库	它是什么	在以下情况下使用
rome-bridge-api	链下编排器 + 链上桥的费用赞助方。不持有任何密钥。	为钱包充值，或从家链发起的流程。
rome-oracle-gateway	通过 Chainlink 暴露给 EVM 的 Solana 价格源（Pyth、Switchboard） AggregatorV3Interface.	你需要价格源。

脚手架——从这里开始

仓库	它是什么	在以下情况下使用
create-rome-app	npx github:rome-protocol/create-rome-app —— 生成一个双通道应用，预先接入 registry + SDK，并附带已充值的双通道检查。	启动一个新应用。

它们如何组合

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

• rome-registry 是实时事实的唯一来源。 rome-sdk-ts 是写入路径——以及其 /bridge 子路径是你的应用用来与……通信的客户端 rome-bridge-api. rome-solidity 是你的合约（以及各分叉）导入的内容；预言机适配器也在这里 rome-oracle-gateway 部署也在此处。这三者彼此独立——按你的应用需要选择。

• create-rome-app 为新应用将前两个连接起来，因此新项目一开始就已能读取 registry 并通过 SDK 写入。

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

按需导航

• 一个实时链上事实 （ID、地址、铸币地址、程序 ID）→ rome-registry。绝不要硬编码。

• 编写应用代码 （一次写入、一次 CPI 调用、一次桥接）→ rome-sdk-ts；参考 Rome SDK.

• 编写合约 → rome-solidity；见 部署 Solidity 合约.

• 从 Solidity 合约调用 Solana 程序 → 见 rome-solidity (interface.sol); cardo 中的 CPI 预编译示例。

• 一个可运行示例 一个 AMM、借贷、CPI 或从家链应用的示例 → 见上方参考应用；每个仓库的 AGENTS.md 都会按起点进行路由。

• 为新应用搭建脚手架 → create-rome-app.

• 一个价格源 → rome-oracle-gateway （见 Oracle Gateway 门户).

• 另一条链上的用户 → 从家链 + rome-bridge-api.

• 决定哪一侧承载你的逻辑 → 选择你的核心.

基础层，近距离查看

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 所做的。）

你的应用不直接实时读取的事实也会出现在 合约地址 参考资料中。

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，以及指南 从 EVM 调用 Solana, 从 Solana 调用 EVM，以及 构建双通道应用.

rome-solidity——合约侧工具包

你的合约导入以下内容：

• contracts/interface.sol —— 绑定到其地址的预编译接口： CPI ICrossProgramInvocation (0xFF…08), 辅助 IHelperProgram (0xFF…09、ATA/PDA 创建、SPL 转账、gas↔lamports）， 提现 IWithdraw (0x42…16），以及 系统 (0xFF…07）。一个经 gas 优化的 缓存 系列也在这里；合约会始终使用同一条路径。完整地址表： 合约地址.

• 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 展示了代码中的导入模式和预编译绑定。

下一步

• 选择你的核心 ——哪一侧承载你的逻辑。

• 快速开始 ——部署你的第一个合约。

• create-rome-app ——搭建一个双通道应用。

• 每个仓库的 AGENTS.md ——按起点路由到最接近示例。