> 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/vi/san-pham/oracle-gateway.md).

# Oracle Gateway

Các nguồn cấp giá Pyth và Switchboard đứng sau Chainlink's AggregatorV3Interface.

Oracle Gateway hiển thị các nguồn giá gốc Solana (Pyth, Switchboard V3) thông qua giao diện của Chainlink `AggregatorV3Interface`nên các giao thức Ethereum chuyển sang Rome giữ nguyên mã tích hợp oracle hiện có. **Oracle Gateway V2 được triển khai trên Hadrian và Rubicon**tuy nhiên registry chỉ liệt kê địa chỉ feed cho Hadrian, còn một cổng khách hàng xử lý việc đăng ký. Một keeper chạy trên Rome làm mới các feed cached và book, nhưng không phải mọi feed đều tươi ở mọi thời điểm — [những feed nào trả lời hôm nay](#which-feeds-answer-today) được trình bày bên dưới. Các adapter, factory và mô hình keeper được đề cập trong [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) repo.

> **Bản xem trước.** Oracle Gateway chưa được kiểm toán. Cổng portal cũng nói như vậy: đừng dùng nó trong các luồng giá trị production.

## Vấn đề

DeFi trên Ethereum kỳ vọng Chainlink `AggregatorV3Interface`:

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

Các nhà cung cấp oracle của Solana (Pyth, Switchboard) có các định dạng dữ liệu khác nhau. Nếu không được điều chỉnh, mọi giao thức được port sang sẽ cần mã oracle tùy chỉnh.

## Giải pháp

Oracle Gateway V2 triển khai các hợp đồng adapter nhẹ mà:

1. Đọc dữ liệu giá trực tiếp từ các tài khoản Pyth hoặc Switchboard trên Solana (đọc cross-state, không phải CPI)
2. Phân tích dữ liệu on-chain
3. Chuẩn hóa giá về 8 chữ số thập phân
4. Hiển thị giao diện Chainlink chuẩn `AggregatorV3Interface`

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

// Cùng giao diện như Chainlink trên Ethereum
(, int256 price,,,) = IAggregatorV3Interface(ADAPTER).latestRoundData();
// price = SOL/USD với 8 chữ số thập phân (ví dụ 15000000000 = $150.00)
```

## Tiêu thụ một feed trong ba bước

1. **Lấy địa chỉ adapter từ registry** — tuyệt đối không hardcode nó:

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

Registry được cài từ GitHub (`npm install github:rome-protocol/rome-registry#v0.2.0`). Các khóa feed có hậu tố cho biết loại adapter đứng sau chúng; xem [Các khóa feed trong registry](#feed-keys-in-the-registry) trước khi bạn chọn một cái.

2. **Đọc nó** với giao diện mà giao thức của bạn vốn đã dùng — `IAggregatorV3Interface(solUsd).latestRoundData()`. Một feed lỗi thời hoặc chưa khởi tạo **revert** thay vì phục vụ một mức giá bị đóng băng.
3. **Nhiều feed cùng lúc?** `BatchReader.getLatestPrices(adapters[])` (Hadrian, registry v0.2.0: `0x2869f0a96572e7fb15036656e9a32fd17346499b`) — và `getFeedHealth(adapters[])` trước khi bạn phụ thuộc vào chúng. Các adapter được cache khiến mỗi consumer đọc một `SLOAD`thuần, nên các giao dịch nhiều feed (vay đa tài sản thế chấp, xem danh mục) vẫn rẻ.

[cardo](https://github.com/rome-protocol/cardo) đọc các feed này trên Hadrian. Vì bề mặt hoàn toàn giống `AggregatorV3Interface`, các giao thức kiểu Compound và Aave có thể dùng các feed này mà không cần thay đổi mã oracle — chỉ cần trỏ cấu hình price-feed của họ tới các địa chỉ adapter.

## Các loại adapter

* **PythPullAdapter** — đọc các tài khoản giá Pyth (giá, độ tin cậy, EMA, thời gian công bố).
* **SwitchboardV3Adapter** — đọc các tài khoản aggregator của Switchboard (giá, dấu thời gian; không có EMA).
* **CachedPyth / CachedFeed adapters** — các biến thể được cache-tracking để đọc tiết kiệm CU.
* **BookFeedAdapter** — một khung nhìn tương thích Chainlink chỉ-đọc trên một mục của hợp đồng `PriceBook` . Sổ này giữ giá cho tất cả các feed đã đăng ký của nó và được làm mới theo lô (việc làm mới là không cần quyền); adapter của mỗi feed không tự giữ cache riêng. Một mục bị tạm dừng sẽ lỗi ngay với `AdapterPaused`, thay vì chờ đến khi trở nên lỗi thời.

Các adapter được triển khai dưới dạng các clone proxy tối thiểu EIP-1167: `OracleAdapterFactory` clone các adapter Pyth, Switchboard và cached, và mỗi `PriceBook` clone riêng của nó `BookFeedAdapter` khi một feed được đăng ký. Chúng hiển thị một giao diện mở rộng bên cạnh `AggregatorV3Interface` (`latestPriceData`, `maxStaleness`, `oracleType`, và một `metadata()` bề mặt được dùng cho kiểm tra tình trạng).

## Các khóa feed trong registry

`getOracle(chainId).feeds` có nhiều khóa cho mỗi tài sản. Hậu tố trên tên khóa cho biết loại adapter:

| Khóa                 | Loại adapter                          | Cách nó đọc                                                                                |
| -------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `SOL/USD`            | Pyth trực tiếp (`PythPullAdapter`)    | Phân tích tài khoản Pyth ở mỗi lần gọi.                                                    |
| `SOL/USD-BOOK`       | `BookFeedAdapter`                     | Đọc một `PriceBook` mục mà keeper làm mới.                                                 |
| `SOL/USD-CACHED`     | Được cache (bọc một feed khác)        | Đọc một mức giá đã lưu mà keeper làm mới.                                                  |
| `SOL/USD-CACHEDPYTH` | Pyth được cache (`CachedPythAdapter`) | Đọc một mức giá đã lưu mà keeper làm mới.                                                  |
| `SOL/USD-SB`         | Switchboard (`SwitchboardV3Adapter`)  | Phân tích tài khoản Switchboard ở mỗi lần gọi. Registry đánh dấu các mục này `ngừng dùng`. |

Bạn tiêu thụ cái nào sẽ phụ thuộc vào chain. Hãy kiểm tra phần tiếp theo trước.

### Những feed nào trả lời hôm nay

Đây là kết quả của các `latestRoundData()` lệnh gọi chỉ-đọc trên các feed được liệt kê trong registry v0.2.0, được thực hiện בזמן khi trang này được viết. Độ tươi của feed thay đổi theo từng phút trên devnet, vì vậy hãy coi đây là một ảnh chụp nhanh và chạy cùng lệnh gọi đó trên feed bạn định dùng.

* **Hadrian.** Các feed trực tiếp thường bị lỗi thời: trong các lần kiểm tra lặp lại, phần lớn chúng (BONK, BTC, ETH, JITOSOL, JTO, JUP, MSOL, USDC, USDT) đều trả về `StalePriceFeed` mỗi lần, và `SOL/USD` trả lời ở một số lần gọi chứ không phải tất cả. Các `-BOOK` feed là đáng tin cậy nhất và trả lời ở mọi lần gọi cho mọi tài sản trừ JTO, mà `-BOOK` feed của nó trả về lỗi vì lỗi thời. Mọi `-CACHED` và `-CACHEDPYTH` feed đều trả về lỗi với `UninitializedPriceFeed` (chưa có gì làm mới chúng), và `SOL/USD-SB` trả về lỗi với `StalePriceFeed`. Trên Hadrian, hãy ưu tiên `-BOOK` feed, và chạy `latestRoundData()` trên feed bạn chọn trước khi phụ thuộc vào nó.
* **Rubicon.** Registry không liệt kê các feed oracle cho Rubicon, nên trang này không đề cập đến chúng. Factory được triển khai ở đó (xem [Các địa chỉ đã triển khai](#deployed-addresses)) và các adapter đầu tiên của nó trả lời, nhưng hãy tra địa chỉ feed từ factory (`adapterCount()` và `allAdapters(i)`) thay vì từ registry.

Việc trả về lỗi ở đây là hành vi được thiết kế: một feed lỗi thời hoặc chưa khởi tạo sẽ báo lỗi rõ ràng thay vì trả về giá cũ. Hãy xử lý nó trong hợp đồng của bạn.

## Độ tươi — keeper oracle

Các adapter áp dụng một `maxStaleness` cửa sổ: nếu `block.timestamp - publishTime > maxStaleness`, các lần đọc sẽ trả về lỗi. Trên Solana mainnet, Pyth chạy các keeper production. Trên Solana devnet (nơi Hadrian đang chạy), các pusher của Pyth chỉ nỗ lực tối đa, nên Rome tự chạy một sidecar **oracle-keeper** để giữ cho các tài khoản Pyth nền tảng luôn mới và làm mới các feed cached và book. Keeper không bao phủ mọi feed trên mọi chain ở mọi thời điểm (xem [những feed nào trả lời hôm nay](#which-feeds-answer-today)).

Kiểm tra tình trạng feed bằng `BatchReader.getFeedHealth` (đọc `metadata()`của mỗi adapter, `không chỉ` latestRoundData

## Cổng khách hàng

Đăng ký feed và cấu hình các consumer theo từng chain thông qua [cổng Oracle Gateway](https://oracle.testnet.romeprotocol.xyz/). Xem [trang portal](https://docs.rome.builders/vi/ung-dung-tren-rome/oracle-gateway.md) để biết những gì nó bao phủ.

## Các địa chỉ đã triển khai

Các địa chỉ canonical theo từng chain (factory, các implementation adapter, và các feed đang chạy) nằm trong [registry](https://github.com/rome-protocol/rome-registry/tree/main/chains). Các factory chính, từ `đang hoạt động` các mục của registry v0.2.0 (phiên bản 5.0.0 trên Hadrian; các địa chỉ Rubicon là những địa chỉ trên [Địa chỉ hợp đồng](https://docs.rome.builders/vi/tai-lieu-tham-khao/contract-addresses.md) trang); xem [Đọc danh sách hợp đồng](https://docs.rome.builders/vi/tai-lieu-tham-khao/contract-addresses.md#reading-the-contracts-list):

| Hợp đồng             | Hadrian                                      | Rubicon                                      |
| -------------------- | -------------------------------------------- | -------------------------------------------- |
| OracleAdapterFactory | `0x52b008771fc95b4674a4f3533570b3d223f27f68` | `0x6a1340dd86c3951b6f13d9001b3951d56a2fe581` |
| BatchReader          | `0x2869f0a96572e7fb15036656e9a32fd17346499b` | `0x580dc0ecb226530ee8a90b57e0f0cd2555fb4f0f` |

## Ràng buộc

* **Không có dữ liệu round lịch sử** — `getRoundData(roundId)` trả về lỗi; chỉ `latestRoundData()` được hỗ trợ.
* **Switchboard EMA không được hỗ trợ** — dữ liệu EMA chỉ có ở Pyth.
* **Ngưỡng lỗi thời theo từng chain** — `maxStaleness` được đặt theo từng môi trường lúc khởi chạy: các adapter trực tiếp (đọc Pyth) mặc định khoảng 60 giây; các adapter cached mặc định 3600 giây (khi keeper làm mới chúng, nó làm như vậy thường xuyên hơn nhiều so với con số đó).
* **Độ lệch parser** được xác thực theo bố cục Pyth/Switchboard hiện tại; thay đổi bố cục yêu cầu xác thực lại.

## Tiếp theo là gì

* [cổng Oracle Gateway](https://docs.rome.builders/vi/ung-dung-tren-rome/oracle-gateway.md) — đăng ký feed, cấu hình consumer
* [Địa chỉ hợp đồng](https://docs.rome.builders/vi/tai-lieu-tham-khao/contract-addresses.md) — precompile và địa chỉ theo từng chain


---

# 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/vi/san-pham/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.
