Ler um preço

A partir de um contrato

Duas formas existem, e elas guardam as mesmas rodadas. O registro indexa cada leitura por feedId; um adaptador por feed prende um feedId a um endereço, para que um consumidor escrito contra a Chainlink não precise saber nada sobre identificadores de feed.

// The adapter: what an existing Chainlink consumer already calls.
AggregatorV3Interface feed = AggregatorV3Interface(adapter);
(, int256 answer,, uint256 updatedAt,) = feed.latestRoundData();
uint8 decimals = feed.decimals();          // 8 on every feed today - read it anyway

// The registry: one address for all 33 feeds, keyed by the hash of the symbol.
bytes32 feedId = keccak256(bytes("XAU/USD"));
(, int256 gold,, uint256 goldUpdatedAt,) = registry.latestRoundData(feedId);
uint8 state = registry.status(feedId);     // 1 open, 2 closed
uint64 observedAt = registry.latestObservedAt(feedId);

As seis coisas que um consumidor Chainlink deveria saber antes de confiar nisto:

• One adapter per feed, holding no data: it stores the registry address and its own feedId and forwards every call. Rounds live in the registry.
• startedAt equals updatedAt. Every round is a single transmission, as an OCR feed reports it, and answeredInRound equals roundId because no round is ever carried over.
• updatedAt is the block timestamp of the publishing transaction, not the time the price was observed. The observation time is observedAt(feedId, roundId) on the registry, which usually LEADS updatedAt - that is why it is kept off the Chainlink tuple, where startedAt <= updatedAt is assumed.
• The adapter emits no events. A consumer watching AnswerUpdated on it sees nothing; the registry emits FeedUpdated(feedId, ...) instead, and feedId is indexed.
• version() returns 2, which is this layer's version and not a Chainlink aggregator version.
• latestRoundData() on a feed that has never been written reverts with Error("No data present"), bubbled from the registry unchanged. The legacy latestAnswer() does not revert - it reads the ring at index 0 and returns 0, which is exactly the zero a consumer must not treat as a price.

Um consumidor que faz suas próprias verificações quer o registro em vez do adaptador, porque o status e a hora de observação não estão na tupla da Chainlink:

interface IPickleFeeds {
    function latestRoundData(bytes32 feedId)
        external view returns (uint80, int256, uint256, uint256, uint80);
    function status(bytes32 feedId) external view returns (uint8);
    function decimals(bytes32 feedId) external view returns (uint8);
}

uint8 constant STATUS_OPEN = 1;
uint8 constant STATUS_CLOSED = 2;

/// maxAge is YOUR tolerance, in seconds, and it only applies while the market is open.
function priceOf(IPickleFeeds registry, bytes32 feedId, uint256 maxAge)
    internal view returns (int256 answer, uint8 decimals)
{
    uint256 updatedAt;
    // Reverts with Error("No data present") when the feed has never been written.
    (, answer,, updatedAt,) = registry.latestRoundData(feedId);
    require(answer > 0, "feed: non-positive answer");

    uint8 state = registry.status(feedId);
    require(state == STATUS_OPEN || state == STATUS_CLOSED, "feed: status unknown");
    // A closed market's last print is the right price for as long as it is closed.
    if (state == STATUS_OPEN) {
        require(block.timestamp - updatedAt <= maxAge, "feed: stale");
    }
    decimals = registry.decimals(feedId);
}

As leituras do registro

• latestRoundData(bytes32 feedId) returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)
• getRoundData(bytes32 feedId, uint80 roundId) returns (uint80, int256, uint256, uint256, uint80)
• latestAnswer(bytes32 feedId) returns (int256)
• latestTimestamp(bytes32 feedId) returns (uint256)
• latestRound(bytes32 feedId) returns (uint256)
• observedAt(bytes32 feedId, uint80 roundId) returns (uint64)
• latestObservedAt(bytes32 feedId) returns (uint64)
• status(bytes32 feedId) returns (uint8)
• source(bytes32 feedId) returns (uint8)
• decimals(bytes32 feedId) returns (uint8)
• description(bytes32 feedId) returns (string)
• symbol(bytes32 feedId) returns (string)
• feed(bytes32 feedId) returns (FeedView)
• feeds(uint256 offset, uint256 limit) returns (FeedView[])
• feedCount() returns (uint256)
• feedIdAt(uint256 index) returns (bytes32)
• adapterOf(bytes32 feedId) returns (address)
• adapterAddress(bytes32 feedId) returns (address)
• version() returns (uint256)

As leituras do adaptador

• decimals() returns (uint8)
• description() returns (string)
• version() returns (uint256)
• latestRoundData() returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)
• getRoundData(uint80 roundId) returns (uint80, int256, uint256, uint256, uint80)
• latestAnswer() returns (int256)
• latestTimestamp() returns (uint256)
• latestRound() returns (uint256)
• symbol() returns (string)

Nenhum dos dois endereços é impresso neste site. Resolver os endereços é como você os obtém da cadeia.

A resposta e suas casas decimais

Uma resposta é um inteiro de ponto fixo, não um número de ponto flutuante e não wei. Todo feed do conjunto de gênese carrega decimals = 8, então uma resposta de 415012345678 é 4150.12345678. O campo permite de 0 a 18 e é por feed, então leia-o do feed em vez de compilar 8 no seu consumidor.

// answer arrives as a decimal string, because it does not fit a JS number safely.
const { answer, decimals, price } = result;         // "415012345678", 8, "4150.12345678"
const scaled = BigInt(answer);                       // keep it integral
const human = Number(scaled) / 10 ** decimals;       // only for display

// price is the same number pre-formatted with exactly `decimals` digits.
// Never parseFloat(answer) and never compare two feeds without rescaling both.

Por JSON-RPC

Três métodos, todos leituras simples sem chave e sem conta. Eles estão listados com todos os outros métodos na referência JSON-RPC; o que se segue é o que eles respondem para esta camada.

curl -s $RPC_URL -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"pickle_price","params":["AAPL-USD"]}'

# -> {"jsonrpc":"2.0","id":1,"result":{
#      "symbol":"AAPL/USD","feedId":"0x...","adapter":"0x...","decimals":8,
#      "roundId":184,"answer":"23144000000","price":"231.44000000",
#      "updatedAt":1758470400,"observedAt":1758470396,
#      "status":2,"statusName":"closed","source":2,"sourceName":"pyth",
#      "ageSecs":51840,"staleAfterSecs":330,"staleOnchain":false, ... }}
#
# staleOnchain is FALSE at fourteen hours old, because the market is closed.

O objeto feed

A partir do serviço de oráculo

O que ela acrescenta em relação à cadeia é o detalhe do cálculo: qual mercado estava atualizado, qual entrou na mediana, a que distância cada um ficou dela, e por que um feed não está publicando. Quando um preço falta, é aí que está a razão.

Duas portas, dois públicos. A API de leitura responde na 3005; o lote que o nó consulta é um ouvinte separado na 3006, carregando um HMAC dos bytes exatos do corpo em X-Pickle-Batch-Hmac, e pedir /v1/publish ao ouvinte público responde 404 em vez de admitir que a rota existe. Todo corpo de erro é uma string fixa: sem caminho, sem origem a montante, sem texto de exceção.

O que uma visão de feed carrega além da cadeia

Defasagem

staleOnchain é o nó aplicando essas regras por você, no relógio de parede da sua requisição em vez do relógio do selamento. É uma comodidade: um consumidor dentro de um contrato não tem esse campo e precisa comparar updatedAt com a sua própria tolerância, que é a verificação que o exemplo acima faz.

updatedAt é o sinal honesto em todos os casos, porque ele simplesmente para de avançar quando a publicação para. Não há verificação de idade on-chain em que se apoiar: There is deliberately no on-chain age check on observedAt. The node replays its write-ahead log with the restart-time timestamp, so a rule of the form block.timestamp - observedAt <= maxAge would fail every replayed update. Freshness is enforced by the publisher, which does not submit a stale aggregate, and by you, through updatedAt - which simply stops advancing when publication stops.

O serviço reporta uma reason ao lado de stale, e as razões merecem ser tratadas separadamente: too_few_sources significa que mercados caíram, cross_check_diverged significa que os mercados e a segunda fonte discordam e o feed está deliberadamente em silêncio, market_closed significa que não há absolutamente nada errado. Como cada uma surge está em Como um preço é formado.

Horários de mercado

Each feed with a Pyth leg carries a schedule: a time zone, seven day patterns starting Monday, and a list of dated overrides for holidays and half-days. It is resolved against the real time-zone database, so a market opens at 09:30 local whatever the daylight-saving offset that day.

The upstream also reports whether the market is open right now. That flag wins while its poll is fresh and no scheduled transition has passed since - it knows about a halt or an unlisted holiday that the schedule does not. Otherwise the schedule decides.

The status machinery applies to a feed whose price comes from the second source, which is every real-world feed. A feed publishing an exchange median reports status open, and that is consistent rather than a gap: all thirteen of them are crypto pairs whose schedule is open every day, all day.

Para um consumidor isso quer dizer três coisas. Um feed de ação pode ficar legitimamente inalterado por dois dias e meio sem estar defasado. Uma verificação de atualidade ingênua rejeita todo feed do mundo real todo fim de semana, e cada um deles toda noite. E uma posição que não deve ser liquidada sobre um preço que ninguém está fazendo agora deveria ler status e recusar-se a agir enquanto ele valer 2, em vez de agir sobre um preço em pé, correto mas imóvel.

const feed = result;                       // one feed object

if (feed.roundId === 0) throw new Error("never written");
if (feed.statusName === "unknown") throw new Error("status not established");

const closed = feed.statusName === "closed";
if (!closed && feed.staleOnchain) throw new Error("stale while open");

// closed === true is a valid, current price for a market that is not trading.
// Decide deliberately whether your product acts on it.

Rodadas, histórico e pulos

Rounds live in a fixed-size ring per feed rather than an append-only history. Round r sits at index r % capacity, is readable while latestRound - r < capacity, and is overwritten afterwards.

getRoundData on an evicted round reverts with "No data present", not with a zero answer. A feed with capacity 1,024 keeps its last 1,024 rounds and no more, so an indexer that wants full history reads the FeedUpdated logs rather than paging the ring.

updateMany never reverts on a bad item. One stale or out-of-range feed in a batch of sixty must not cost the other fifty-nine their round, so a bad item is skipped with a FeedSkipped(feedId, reason) log and the rest are written. Only a malformed batch - mismatched array lengths, over maxBatch, or a sender that is not the publisher - reverts.

Um item pulado só é visível como um log FeedSkipped: a rodada não avança e a resposta anterior permanece. Um consumidor que observa um feed deveria portanto observar FeedUpdated com o identificador do feed como tópico indexado - é o evento que o adaptador não emite - e tratar um longo silêncio pelo que ele é, em vez de esperar um erro que nunca chega.