> 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/pt-br/produtos/oracle-gateway.md).

# Oracle Gateway

Feeds de preço da Pyth e da Switchboard por trás da Chainlink AggregatorV3Interface.

O Oracle Gateway expõe feeds de preços nativos de Solana (Pyth, Switchboard V3) por meio da interface da Chainlink `AggregatorV3Interface`, então protocolos Ethereum portados para a Rome mantêm seu código de integração de oráculo existente. **O Oracle Gateway V2 está implantado em Hadrian e Rubicon**, embora o registro liste endereços de feeds apenas para Hadrian, e um portal do cliente faça o registro. Um keeper executado pela Rome atualiza os feeds em cache e book, mas nem todo feed está atualizado a todo momento — [quais feeds respondem hoje](#which-feeds-answer-today) é detalhado abaixo. Os adapters, a factory e o modelo de keeper são abordados no [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) repositório.

> **Prévia.** O Oracle Gateway não foi auditado. O portal diz o mesmo: não o use em fluxos de valor em produção.

## O problema

O DeFi do Ethereum espera a interface da Chainlink `AggregatorV3Interface`:

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

Os provedores de oráculo da Solana (Pyth, Switchboard) têm formatos de dados diferentes. Sem adaptação, cada protocolo portado precisaria de código de oráculo personalizado.

## A solução

O Oracle Gateway V2 implanta contratos adaptadores leves que:

1. Lêem dados de preço diretamente de contas Pyth ou Switchboard na Solana (leituras entre estados, não CPI)
2. Fazem o parse dos dados on-chain
3. Normalizam os preços para 8 casas decimais
4. Expor a interface padrão da Chainlink `AggregatorV3Interface`

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

// Mesma interface da Chainlink no Ethereum
(, int256 price,,,) = IAggregatorV3Interface(ADAPTER).latestRoundData();
// preço = SOL/USD com 8 casas decimais (por ex., 15000000000 = US$ 150,00)
```

## Consuma um feed em três etapas

1. **Resolva o endereço do adapter no registro** — nunca o codifique fixamente:

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

O registro é instalado a partir do GitHub (`npm install github:rome-protocol/rome-registry#v0.2.0`). As chaves dos feeds carregam um sufixo que informa qual tipo de adapter está por trás delas; veja [Chaves de feed no registro](#feed-keys-in-the-registry) antes de escolher uma.

2. **Leia-o** com a interface que seu protocolo já usa — `IAggregatorV3Interface(solUsd).latestRoundData()`. Um feed desatualizado ou não inicializado **reverte** em vez de servir um preço congelado.
3. **Vários feeds ao mesmo tempo?** `BatchReader.getLatestPrices(adapters[])` (Hadrian, registro v0.2.0: `0x2869f0a96572e7fb15036656e9a32fd17346499b`) — e `getFeedHealth(adapters[])` antes de depender deles. Adapters em cache fazem com que cada consumidor leia um simples `SLOAD`, então transações com vários feeds (um empréstimo com múltiplas garantias, uma visão de portfólio) continuam baratas.

[cardo](https://github.com/rome-protocol/cardo) lê esses feeds em Hadrian. Como a superfície é exatamente `AggregatorV3Interface`, protocolos da classe Compound e Aave podem usar esses feeds sem mudanças no código de oráculo — aponte a configuração de price-feed deles para os endereços dos adapters.

## Tipos de adapter

* **PythPullAdapter** — lê contas de preço Pyth (preço, confiança, EMA, horário de publicação).
* **SwitchboardV3Adapter** — lê contas agregadoras do Switchboard (preço, timestamp; sem EMA).
* **Adapters CachedPyth / CachedFeed** — variantes em cache para leituras eficientes em CU.
* **BookFeedAdapter** — uma visão compatível com Chainlink, somente leitura, sobre uma entrada de um `PriceBook` contrato. O book mantém os preços de todos os seus feeds registrados e é atualizado em lotes (a atualização é sem permissão); o adapter de cada feed não mantém cache próprio. Uma entrada pausada reverte imediatamente com `AdapterPaused`, em vez de esperar ficar desatualizada.

Os adapters são implantados como clones de minimal proxy EIP-1167: o `OracleAdapterFactory` clona os adapters Pyth, Switchboard e em cache, e cada `PriceBook` clona o seu próprio `BookFeedAdapter` quando um feed é registrado. Eles expõem uma interface estendida junto com `AggregatorV3Interface` (`latestPriceData`, `maxStaleness`, `oracleType`, e um `metadata()` superfície usada para verificações de saúde).

## Chaves de feed no registro

`getOracle(chainId).feeds` tem várias chaves por ativo. O sufixo na chave nomeia o tipo de adapter:

| Chave                | Tipo de adapter                      | Como lê                                                                                         |
| -------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `SOL/USD`            | Pyth direto (`PythPullAdapter`)      | Faz o parse da conta Pyth a cada chamada.                                                       |
| `SOL/USD-BOOK`       | `BookFeedAdapter`                    | Lê uma `PriceBook` entrada que o keeper atualiza.                                               |
| `SOL/USD-CACHED`     | Em cache (envolve outro feed)        | Lê um preço armazenado que o keeper atualiza.                                                   |
| `SOL/USD-CACHEDPYTH` | Pyth em cache (`CachedPythAdapter`)  | Lê um preço armazenado que o keeper atualiza.                                                   |
| `SOL/USD-SB`         | Switchboard (`SwitchboardV3Adapter`) | Faz o parse da conta Switchboard a cada chamada. O registro marca essas entradas `desativadas`. |

Qual consumir depende da chain. Consulte primeiro a próxima seção.

### Quais feeds respondem hoje

Estes são resultados de `latestRoundData()` chamadas somente leitura nos feeds listados no registro v0.2.0, feitas enquanto esta página era escrita. A atualização dos feeds muda de minuto em minuto no devnet, então trate isso como um instantâneo e execute a mesma chamada no feed que você pretende usar.

* **Hadrian.** Os feeds diretos costumam estar desatualizados: em verificações repetidas, a maioria deles (BONK, BTC, ETH, JITOSOL, JTO, JUP, MSOL, USDC, USDT) reverteu com `StalePriceFeed` todas as vezes, e `SOL/USD` respondeu em algumas chamadas e não em outras. Os feeds `-BOOK` foram os mais confiáveis e responderam em todas as chamadas para todos os ativos, exceto JTO, cujo `-BOOK` feed reverteu por estar desatualizado. Cada `-CACHED` e `-CACHEDPYTH` feed reverteu com `UninitializedPriceFeed` (nada os atualizou), e `SOL/USD-SB` reverteu com `StalePriceFeed`. Em Hadrian, prefira o `-BOOK` feed, e execute `latestRoundData()` no feed que você escolher antes de depender dele.
* **Rubicon.** O registro não lista feeds de oráculo para Rubicon, então esta página não os cobre. A factory está implantada lá (veja [Endereços implantados](#deployed-addresses)) e seus primeiros adapters respondem, mas busque os endereços dos feeds na factory (`adapterCount()` e `allAdapters(i)`) em vez de no registro.

Uma reversão aqui é o comportamento planejado: um feed desatualizado ou não inicializado falha de forma explícita em vez de retornar um preço antigo. Trate isso no seu contrato.

## Atualização — o oracle-keeper

Os adapters impõem uma `maxStaleness` janela: se `block.timestamp - publishTime > maxStaleness`, as leituras revertem. Na mainnet da Solana, o Pyth executa keepers de produção. Na devnet da Solana (onde Hadrian fica), os pushers do Pyth são best-effort, então a Rome executa seu próprio **oracle-keeper** sidecar para manter as contas Pyth subjacentes atualizadas e para atualizar os feeds em cache e book. O keeper não cobre todo feed em toda chain a todo momento (veja [quais feeds respondem hoje](#which-feeds-answer-today)).

Verifique a saúde do feed com `BatchReader.getFeedHealth` (que lê o `metadata()`de cada adapter, não apenas `latestRoundData` — um feed pode estar acessível, mas desatualizado.

## Portal do cliente

Registre feeds e configure consumidores por chain por meio do [portal do Oracle Gateway](https://oracle.testnet.romeprotocol.xyz/). Veja a [página do portal](https://docs.rome.builders/pt-br/apps-na-rome/oracle-gateway.md) para ver o que ela cobre.

## Endereços implantados

Os endereços canônicos por chain (factories, implementações de adapters e os feeds ativos) estão no [é o wrapper em cache que esta seção descreve.](https://github.com/rome-protocol/rome-registry/tree/main/chains). As factories principais, a partir das `ativa` entradas do registro v0.2.0 (versão 5.0.0 em Hadrian; os endereços de Rubicon são os da [Contract Addresses](https://docs.rome.builders/pt-br/referencia/contract-addresses.md) página); veja [Lendo a lista de contratos](https://docs.rome.builders/pt-br/referencia/contract-addresses.md#reading-the-contracts-list):

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

## Restrições

* **Sem dados históricos de rodadas** — `getRoundData(roundId)` reverte; somente `latestRoundData()` é suportado.
* **EMA do Switchboard não suportado** — dados de EMA são exclusivos do Pyth.
* **Desatualização por chain** — `maxStaleness` é definida por ambiente na inicialização: adapters diretos (leitura Pyth) usam por padrão \~60 segundos; adapters em cache usam por padrão 3600 segundos (quando o keeper os atualiza, ele faz isso com muito mais frequência do que isso).
* **Deslocamentos do parser** são validados contra os layouts atuais de Pyth/Switchboard; mudanças de layout exigem nova validação.

## O que vem a seguir

* [portal do Oracle Gateway](https://docs.rome.builders/pt-br/apps-na-rome/oracle-gateway.md) — registre feeds, configure consumidores
* [Contract Addresses](https://docs.rome.builders/pt-br/referencia/contract-addresses.md) — precompiles e endereços por cadeia


---

# 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/pt-br/produtos/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.
