> 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ço nativos da Solana (Pyth, Switchboard V3) por meio do Chainlink `AggregatorV3Interface`, então os protocolos Ethereum portados para Rome mantêm seu código de integração de oráculos 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 cuide do registro. Um keeper operado pela Rome atualiza os feeds em cache e book, mas nem todo feed está fresco em todo momento — [quais feeds respondem hoje](#which-feeds-answer-today) está detalhado abaixo. Os adaptadores, 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 de produção. ## O problema O DeFi em Ethereum espera o `AggregatorV3Interface`: ```solidity (, int256 price,,,) = priceFeed.latestRoundData(); ``` Os provedores de oráculos 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. Ler dados de preço diretamente das contas Pyth ou Switchboard na Solana (leituras entre estados, não CPI) 2. Analisar os dados on-chain 3. Normalizar 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(); // price = SOL/USD com 8 casas decimais (ex.: 15000000000 = US$ 150,00) ``` ## Consumir um feed em três etapas 1. **Resolver o endereço do adaptador a partir do registro** — nunca o codifique fixamente: ```ts import { getOracle } from "@rome-protocol/registry"; const solUsd = getOracle(200010).feeds["SOL/USD"].address; // Hadrian, registry v0.2.0: 0x567384ee000ca0418c386A73eC2b7466f9f99D6b ``` O registro é instalado do GitHub (`npm install github:rome-protocol/rome-registry#v0.2.0`). Os nomes dos feeds carregam um sufixo que indica qual tipo de adaptador está por trás deles; veja [Nomes dos feeds no registro](#feed-keys-in-the-registry) antes de escolher um. 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, registry v0.2.0: `0x2869f0a96572e7fb15036656e9a32fd17346499b`) — e `getFeedHealth(adapters[])` antes de depender deles. Adaptadores em cache fazem cada consumidor ler um simples `SLOAD`, então transações com vários feeds (um empréstimo com vários colaterais, uma visão de portfólio) continuam baratas. [cardo](https://github.com/rome-protocol/cardo) lê esses feeds em Hadrian. Como a interface é exatamente `AggregatorV3Interface`, protocolos das classes Compound e Aave podem usar esses feeds sem alterações no código do oráculo — aponte a configuração do feed de preço para os endereços dos adaptadores. ## Tipos de adaptador * **PythPullAdapter** — lê contas de preço da Pyth (preço, confiança, EMA, horário de publicação). * **SwitchboardV3Adapter** — lê contas agregadoras do Switchboard (preço, timestamp; sem EMA). * **Adaptadores CachedPyth / CachedFeed** — variantes com rastreamento em cache para leituras eficientes em CU. * **BookFeedAdapter** — uma visualização somente leitura compatível com Chainlink sobre uma entrada de um `PriceBook` contrato. O book mantém os preços de todos os feeds registrados e é atualizado em lotes (a atualização não exige permissão); o adaptador de cada feed não mantém cache próprio. Uma entrada pausada reverte imediatamente com `AdapterPaused`, em vez de esperar ficar desatualizada. Os adaptadores são implantados como clones de proxy mínimo EIP-1167: o `OracleAdapterFactory` clona os adaptadores Pyth, Switchboard e em cache, e cada `PriceBook` clona o 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). ## Nomes dos feeds no registro `getOracle(chainId).feeds` tem várias chaves por ativo. O sufixo no nome da chave indica o tipo de adaptador: | Chave | Tipo de adaptador | Como lê | | -------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------ | | `SOL/USD` | Pyth direto (`PythPullAdapter`) | Analisa a 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`) | Analisa a conta Switchboard a cada chamada. O registro marca essas entradas `aposentadas`. | Qual deles consumir depende da chain. Verifique a próxima seção primeiro. ### Quais feeds respondem hoje Estes são resultados de `latestRoundData()` chamadas somente leitura nos feeds listados no registry v0.2.0, feitas enquanto esta página estava sendo escrita. A frescura dos feeds muda de minuto a 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. Todo feed `-CACHED` e `-CACHEDPYTH` reverteu com `UninitializedPriceFeed` (nada os atualizou), e `SOL/USD-SB` reverteu com `StalePriceFeed`. `-BOOK` Em Hadrian, prefira o `latestRoundData()` feed, e execute * **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 adaptadores respondem, mas consulte os endereços dos feeds na factory (`adapterCount()` e `allAdapters(i)`) em vez de no registro. Um revert aqui é o comportamento previsto: 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. ## Atualidade — o oracle-keeper Os adaptadores impõem uma `maxStaleness` janela: se `block.timestamp - publishTime > maxStaleness`, as leituras revertem. Na mainnet da Solana, a Pyth executa keepers de produção. Na devnet da Solana (onde Hadrian vive), os pushers da 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 todos os feeds em todas as chains em 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 adaptador), e 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 Oracle Gateway](https://oracle.testnet.romeprotocol.xyz/). Veja a [página do portal](/pt-br/apps-na-rome/oracle-gateway.md) para saber o que ele cobre. ## Endereços implantados Endereços canônicos por chain (factories, implementações de adaptadores e os feeds ativos) vivem no [registro](https://github.com/rome-protocol/rome-registry/tree/main/chains). As factories principais, a partir das `live` entradas do registry v0.2.0 (versão 5.0.0 em Hadrian; os endereços de Rubicon são os da [referência de Endereços de Contrato](/pt-br/referencia/contract-addresses.md) página); veja [Lendo a lista de contratos](/pt-br/referencia/contract-addresses.md#reading-the-contracts-list): | Contrato | Hadrian | Rubicon | | -------------------- | -------------------------------------------- | -------------------------------------------- | | OracleAdapterFactory | `0x52b008771fc95b4674a4f3533570b3d223f27f68` | `0x6a1340dd86c3951b6f13d9001b3951d56a2fe581` | | BatchReader | `0x2869f0a96572e7fb15036656e9a32fd17346499b` | `0x580dc0ecb226530ee8a90b57e0f0cd2555fb4f0f` | ## Restrições * **Não há dados históricos de rounds** — `getRoundData(roundId)` reverte; somente `latestRoundData()` é suportado. * **EMA do Switchboard não suportada** — dados de EMA são exclusivos da Pyth. * **Desatualização por chain** — `maxStaleness` é definida por ambiente na inicialização: adaptadores diretos (que leem Pyth) usam padrão de \~60 segundos; adaptadores em cache usam padrão de 3600 segundos (quando o keeper os atualiza, ele o faz com muito mais frequência do que isso). * **Offsets do parser** são validados em relação aos layouts atuais da Pyth/Switchboard; mudanças de layout exigem nova validação. ## O que Vem a Seguir * [portal Oracle Gateway](/pt-br/apps-na-rome/oracle-gateway.md) — registre feeds, configure consumidores * [referência de Endereços de Contrato](/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=&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.