> 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/chan-pin/oracle-gateway.md).

# Oracle Gateway

Chainlink 的 AggregatorV3Interface 背后的 Pyth 和 Switchboard 价格数据源。

Oracle Gateway 通过 Chainlink 的接口暴露 Solana 原生价格源（Pyth、Switchboard V3） `AggregatorV3Interface`，因此迁移到 Rome 的以太坊协议可以继续使用现有的预言机集成代码。 **Oracle Gateway V2 已部署在 Hadrian 和 Rubicon 上**，不过注册表仅列出 Hadrian 的 feed 地址，注册由客户门户处理。由 Rome 运行的 keeper 会刷新缓存和 book feed，但并非每个 feed 在每一时刻都保持最新—— [当前哪些 feed 会响应](#which-feeds-answer-today) 如下所述。适配器、工厂和 keeper 模型在 [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) 代码仓库中介绍。

> **预览。** Oracle Gateway 尚未经过审计。门户也明确提示：请勿将其用于生产环境中的价值流转。

## 问题

以太坊 DeFi 期望使用 Chainlink 的 `AggregatorV3Interface`:

```solidity
(, int256 price,,,) = priceFeed.latestRoundData();
```

Solana 的预言机提供方（Pyth、Switchboard）使用不同的数据格式。若不做适配，每个移植的协议都需要定制预言机代码。

## 解决方案

Oracle Gateway V2 部署了轻量级适配器合约，用于：

1. 直接从 Solana 上的 Pyth 或 Switchboard 账户读取价格数据（跨状态读取，而非 CPI 调用）
2. 解析链上数据
3. 将价格标准化为 8 位小数
4. 暴露标准的 Chainlink `AggregatorV3Interface`

```solidity
import {IAggregatorV3Interface} from "@rome-protocol/rome-solidity/contracts/oracle/IAggregatorV3Interface.sol";

// 与以太坊上的 Chainlink 使用相同的接口
(, int256 price,,,) = IAggregatorV3Interface(ADAPTER).latestRoundData();
// price = SOL/USD，8 位小数（例如 15000000000 = 150.00 美元）
```

## 分三步消费一个 feed

1. **从注册表中解析适配器地址** ——切勿将其硬编码：

```ts
import { getOracle } from "@rome-protocol/registry";
const solUsd = getOracle(200010).feeds["SOL/USD"].address;
// Hadrian，注册表 v0.2.0：0x567384ee000ca0418c386A73eC2b7466f9f99D6b
```

注册表从 GitHub 安装（`npm install github:rome-protocol/rome-registry#v0.2.0`）。feed 键名带有后缀，用来标明其背后的适配器类型；请参见 [注册表中的 feed 键](#feed-keys-in-the-registry) 再进行选择。

2. **阅读** 并使用你的协议已经在用的接口—— `IAggregatorV3Interface(solUsd).latestRoundData()`。过期或未初始化的 feed **回退** 而不是提供一个冻结的价格。
3. **同时处理多个 feed？** `BatchReader.getLatestPrices(adapters[])` （Hadrian，注册表 v0.2.0： `0x2869f0a96572e7fb15036656e9a32fd17346499b`）——以及 `getFeedHealth(adapters[])` 在依赖它们之前先检查。缓存型适配器使每个消费者读取一个普通的 `SLOAD`，因此多 feed 交易（多抵押借款、组合视图）依然保持低成本。

[cardo](https://github.com/rome-protocol/cardo) 在 Hadrian 上读取这些 feed。由于其表面接口完全与 `AggregatorV3Interface`一致，Compound 和 Aave 级别的协议无需更改预言机代码即可接入这些 feed——只需将其价格源配置指向适配器地址。

## 适配器类型

* **PythPullAdapter** ——读取 Pyth 价格账户（价格、置信度、EMA、发布时间）。
* **SwitchboardV3Adapter** ——读取 Switchboard 聚合器账户（价格、时间戳；不含 EMA）。
* **CachedPyth / CachedFeed 适配器** ——用于节省 CU 的缓存跟踪变体。
* **BookFeedAdapter** ——对某个 `PriceBook` 合约。该价格簿保存其所有已注册 feed 的价格，并以批量方式刷新（刷新是无权限的）；每个 feed 的适配器本身不保留缓存。暂停的条目会立即以 `AdapterPaused`回退，而不是等到过期。

适配器以 EIP-1167 最小代理克隆的形式部署： `OracleAdapterFactory` 该工厂克隆 Pyth、Switchboard 和缓存适配器，并且每个 `PriceBook` 都会克隆其自身的 `BookFeedAdapter` ，在注册 feed 时完成。它们还会在 `AggregatorV3Interface` (`latestPriceData`, `maxStaleness`, `oracleType`，以及一个 `metadata()` 用于健康检查的表面接口）。

## 注册表中的 feed 键

`getOracle(chainId).feeds` 每个资产有多个键。键名后缀标明适配器类型：

| 键                    | 适配器类型                               | 读取方式                                       |
| -------------------- | ----------------------------------- | ------------------------------------------ |
| `SOL/USD`            | 直接 Pyth（`PythPullAdapter`)          | 每次调用都会解析 Pyth 账户。                          |
| `SOL/USD-BOOK`       | `BookFeedAdapter`                   | 读取一个 `PriceBook` 由 keeper 刷新的条目。           |
| `SOL/USD-CACHED`     | 缓存型（包装另一个 feed）                     | 读取由 keeper 刷新的已存储价格。                       |
| `SOL/USD-CACHEDPYTH` | 缓存 Pyth（`CachedPythAdapter`)        | 读取由 keeper 刷新的已存储价格。                       |
| `SOL/USD-SB`         | Switchboard（`SwitchboardV3Adapter`) | 每次调用都会解析 Switchboard 账户。注册表将这些条目标记为 `已退役`. |

具体消费哪一个取决于链。请先查看下一节。

### 当前哪些 feed 会响应

以下结果来自只读 `latestRoundData()` 调用，针对本页编写时注册表 v0.2.0 中列出的 feed。Devnet 上的 feed 新鲜度会随分钟变化，因此请将其视为一个快照，并在你计划使用的 feed 上执行相同调用。

* **Hadrian。** 直接 feed 往往已过期：在重复检查中，它们中的大多数（BONK、BTC、ETH、JITOSOL、JTO、JUP、MSOL、USDC、USDT）都回退并报 `StalePriceFeed` 错，每次都会如此，而 `SOL/USD` 有些调用会返回结果，有些则不会。 `-BOOK` feed 最可靠，除 JTO 外，所有资产在每次调用中都能返回结果，而 JTO 的 `-BOOK` feed 都因过期而回退。每个 `-CACHED` 和 `-CACHEDPYTH` feed 都以 `UninitializedPriceFeed` （没有任何内容刷新过它们），并且 `SOL/USD-SB` 回退并报错 `StalePriceFeed`。在 Hadrian 上，优先使用 `-BOOK` feed，并运行 `latestRoundData()` 在你依赖它之前，先在你选择的 feed 上执行。
* **Rubicon。** 注册表未列出 Rubicon 的预言机 feed，因此本页不予覆盖。工厂已部署在那里（见 [已部署地址](#deployed-addresses)），其首批适配器已可响应，但 feed 地址应从工厂中查询（`adapterCount()` 和 `allAdapters(i)`），而不是从注册表中查询。

这里的回退是预期行为：过期或未初始化的 feed 会明确失败，而不是返回旧价格。请在你的合约中处理它。

## 新鲜度——预言机 keeper

适配器强制执行一个 `maxStaleness` 窗口：如果 `block.timestamp - publishTime > maxStaleness`，读取会回退。在 Solana 主网，Pyth 运行生产 keepers。在 Solana devnet（Hadrian 所在环境）上，Pyth 的推送器是尽力而为的，因此 Rome 运行自己的 **预言机 keeper** sidecar，以保持底层 Pyth 账户新鲜，并刷新缓存和 book feed。该 keeper 不会在每一时刻覆盖每条链上的每个 feed（见 [当前哪些 feed 会响应](#which-feeds-answer-today)).

使用以下方式检查 feed 健康状况： `BatchReader.getFeedHealth` （它会读取每个适配器的 `metadata()`） `latestRoundData` ——feed 可能可访问，但已过期。

## 客户门户

通过以下方式按链注册 feed 并配置消费者： [Oracle Gateway 门户](https://oracle.testnet.romeprotocol.xyz/)。请参见 [门户页面](https://docs.rome.builders/zh/rome-shang-de-ying-yong/oracle-gateway.md) 了解其覆盖范围。

## 已部署地址

按链的规范地址（工厂、适配器实现以及线上 feed）存放在 [注册表](https://github.com/rome-protocol/rome-registry/tree/main/chains)。主要工厂地址，来自 `生效` 注册表 v0.2.0 的条目（Hadrian 上为 5.0.0 版本；Rubicon 地址使用 [合约地址](https://docs.rome.builders/zh/can-kao/contract-addresses.md) 页面上的地址）；请参见 [读取合约列表](https://docs.rome.builders/zh/can-kao/contract-addresses.md#reading-the-contracts-list):

| 合约                   | Hadrian                                      | Rubicon                                      |
| -------------------- | -------------------------------------------- | -------------------------------------------- |
| OracleAdapterFactory | `0x52b008771fc95b4674a4f3533570b3d223f27f68` | `0x6a1340dd86c3951b6f13d9001b3951d56a2fe581` |
| BatchReader          | `0x2869f0a96572e7fb15036656e9a32fd17346499b` | `0x580dc0ecb226530ee8a90b57e0f0cd2555fb4f0f` |

## 约束

* **没有历史轮次数据** —— `getRoundData(roundId)` 会回退；仅 `latestRoundData()` 受支持。
* **不支持 Switchboard EMA** ——EMA 数据仅适用于 Pyth。
* **按链的过期阈值** —— `maxStaleness` 在启动时按环境设置：直接（读取 Pyth）适配器默认约 60 秒；缓存适配器默认 3600 秒（当 keeper 刷新它们时，频率远高于此）。
* **解析器偏移量** 会针对当前的 Pyth/Switchboard 布局进行验证；布局变更需要重新验证。

## 下一步

* [Oracle Gateway 门户](https://docs.rome.builders/zh/rome-shang-de-ying-yong/oracle-gateway.md) ——注册 feed，配置消费者
* [合约地址](https://docs.rome.builders/zh/can-kao/contract-addresses.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/chan-pin/oracle-gateway.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.
