Lire un prix

Depuis un contrat

Deux formes existent, et elles détiennent les mêmes tours. Le registre indexe chaque lecture par feedId ; un adaptateur par flux épingle un feedId à une adresse, pour qu'un consommateur écrit contre Chainlink n'ait rien à savoir des identifiants de flux.

// 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);

Les six choses qu'un consommateur Chainlink devrait savoir avant de s'y fier :

• 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.

Un consommateur qui fait ses propres vérifications veut le registre plutôt que l'adaptateur, parce que le statut et l'heure d'observation ne sont pas dans le tuple 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);
}

Les lectures du registre

• 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)

Les lectures de l'adaptateur

• 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)

Aucune des deux adresses n'est imprimée sur ce site. Résoudre les adresses explique comment les obtenir depuis la chaîne.

La réponse et ses décimales

Une réponse est un entier en virgule fixe, pas un flottant et pas du wei. Chaque flux de l'ensemble de genèse porte decimals = 8, donc une réponse de 415012345678 vaut 4150.12345678. Le champ autorise 0 à 18 et est propre à chaque flux : lisez-le depuis le flux plutôt que de compiler 8 dans votre consommateur.

// 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.

En JSON-RPC

Trois méthodes, toutes de simples lectures sans clé ni compte. Elles sont listées avec toutes les autres dans la référence JSON-RPC ; ce qui suit est ce qu'elles répondent pour cette couche.

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.

L'objet feed

Depuis le service d'oracle

Ce qu'il ajoute par rapport à la chaîne, c'est le détail du calcul : quelle place était fraîche, laquelle est entrée dans la médiane, à quelle distance chacune s'en tenait, et pourquoi un flux ne publie pas. Quand un prix manque, c'est là qu'est la raison.

Deux ports, deux publics. L'API de lecture répond sur 3005 ; le lot que le nœud interroge est un écouteur séparé sur 3006, portant un HMAC des octets exacts du corps dans X-Pickle-Batch-Hmac, et demander /v1/publish à l'écouteur public répond 404 plutôt que d'admettre que la route existe. Chaque corps d'erreur est une chaîne fixe : pas de chemin, pas d'amont, pas de texte d'exception.

Ce que porte une vue de flux au-delà de la chaîne

La fraîcheur

staleOnchain est le nœud qui applique ces règles pour vous, à l'horloge murale de votre requête plutôt qu'à celle du scellement. C'est une commodité : un consommateur dans un contrat n'a pas ce champ et doit comparer updatedAt à sa propre tolérance, ce que fait l'exemple ci-dessus.

updatedAt est le signal honnête dans tous les cas, parce qu'il cesse simplement d'avancer quand la publication s'arrête. Il n'y a aucun contrôle d'âge on-chain sur lequel s'appuyer : 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.

Le service rapporte une reason à côté de stale, et ces raisons méritent d'être traitées séparément : too_few_sources signifie que des places ont décroché, cross_check_diverged signifie que les places et la seconde source ne sont pas d'accord et que le flux se tait délibérément, market_closed signifie que rien ne va mal du tout. Comment chacune survient est sur Comment un prix se forme.

Les heures de marché

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.

Pour un consommateur cela veut dire trois choses. Un flux d'action peut légitimement rester inchangé pendant deux jours et demi sans être périmé. Un contrôle de fraîcheur naïf rejette chaque flux d'actif réel chaque week-end, et chacun d'eux chaque nuit. Et une position qui ne doit pas être liquidée sur un prix que personne ne fait en ce moment devrait lire status et refuser d'agir tant qu'il vaut 2, plutôt qu'agir sur un prix debout, correct mais immobile.

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.

Tours, historique et sauts

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.

Un élément sauté n'est visible que comme un log FeedSkipped : le tour n'avance pas et la réponse précédente tient. Un consommateur qui surveille un flux devrait donc surveiller FeedUpdated avec l'identifiant du flux comme topic indexé - c'est l'événement que l'adaptateur n'émet pas - et traiter un long silence pour ce qu'il est, plutôt que d'attendre une erreur qui ne vient jamais.