Einen Preis lesen

Aus einem Contract

Es gibt zwei Formen, und sie halten dieselben Runden. Das Register schlüsselt jeden Lesezugriff über feedId; ein Adapter pro Feed heftet eine feedId an eine Adresse, sodass eine gegen Chainlink geschriebene Konsumentin nichts über Feed-IDs wissen muss.

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

Die sechs Dinge, die eine Chainlink-Konsumentin wissen sollte, bevor sie sich darauf verlässt:

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

Wer selbst prüft, will das Register statt des Adapters, denn der Status und die Beobachtungszeit stehen nicht im Chainlink-Tupel:

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

Die Lesezugriffe des Registers

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

Die Lesezugriffe des Adapters

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

Keine der beiden Adressen ist auf dieser Website gedruckt. Die Adressen auflösen zeigt, wie Sie sie aus der Chain bekommen.

Die Antwort und ihre Dezimalstellen

Eine Antwort ist eine Festkomma-Ganzzahl, kein Float und kein Wei. Jeder Feed in der Genesis-Menge trägt decimals = 8, eine Antwort von 415012345678 ist also 4150.12345678. Das Feld erlaubt 0 bis 18 und gilt pro Feed, lesen Sie es also aus dem Feed, statt die 8 in Ihre Konsumentin einzukompilieren.

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

Über JSON-RPC

Drei Methoden, alle schlichte Lesezugriffe ohne Schlüssel und ohne Konto. Sie stehen mit jeder anderen Methode in der JSON-RPC-Referenz; was folgt, ist das, was sie für diese Schicht beantworten.

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.

Das Feed-Objekt

Aus dem Orakeldienst

Was er gegenüber der Chain hinzufügt, ist der Rechenweg: welcher Handelsplatz frisch war, welcher in den Median einging, wie weit jeder davon entfernt lag, und warum ein Feed nicht veröffentlicht. Wenn ein Preis fehlt, steht hier der Grund.

Zwei Ports, zwei Publikumsgruppen. Die Lese-API antwortet auf 3005; der Batch, den der Node abfragt, ist ein eigener Listener auf 3006, der einen HMAC über genau die Bytes des Körpers in X-Pickle-Batch-Hmac trägt, und den öffentlichen Listener nach /v1/publish zu fragen antwortet mit 404, statt zuzugeben, dass die Route existiert. Jeder Fehlerkörper ist ein fester String: kein Pfad, kein Upstream, kein Ausnahmetext.

Was eine Feed-Ansicht über die Chain hinaus trägt

Veraltete Preise

staleOnchain ist der Node, der diese Regeln für Sie anwendet, an der Wanduhr Ihrer Anfrage statt der der Versiegelung. Es ist eine Bequemlichkeit: Eine Konsumentin innerhalb eines Contracts hat kein solches Feld und muss updatedAt gegen ihre eigene Toleranz vergleichen, was die Prüfung ist, die das Beispiel oben macht.

updatedAt ist in jedem Fall das ehrliche Signal, denn es rückt schlicht nicht mehr vor, sobald die Veröffentlichung aufhört. Es gibt keine Alterskontrolle on-chain, auf die man sich stützen könnte: 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.

Der Dienst meldet neben stale einen reason, und die Gründe lohnen es, getrennt behandelt zu werden: too_few_sources heißt, Handelsplätze sind weggefallen, cross_check_diverged heißt, die Handelsplätze und die zweite Quelle widersprechen sich und der Feed schweigt absichtlich, market_closed heißt, es ist überhaupt nichts falsch. Wie jeder davon entsteht, steht unter Wie ein Preis entsteht.

Handelszeiten

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.

Für eine Konsumentin heißt das dreierlei. Ein Aktien-Feed kann zweieinhalb Tage lang berechtigterweise unverändert sein, ohne veraltet zu sein. Eine naive Frischeprüfung lehnt jeden Feed auf einen realen Vermögenswert jedes Wochenende ab, und jeden davon jede Nacht. Und eine Position, die nicht auf einem Preis liquidiert werden darf, den gerade niemand stellt, sollte status lesen und sich weigern zu handeln, solange er 2 ist, statt auf einem stehenden Preis zu handeln, der richtig, aber bewegungslos ist.

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.

Runden, Historie und Auslassungen

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.

Ein ausgelassener Eintrag ist nur als FeedSkipped-Log sichtbar: Die Runde rückt nicht vor, und die vorherige Antwort bleibt stehen. Wer einen Feed beobachtet, sollte daher FeedUpdated mit der Feed-ID als indexiertem Topic beobachten - es ist das Event, das der Adapter nicht ausgibt - und ein langes Schweigen als das nehmen, was es ist, statt auf einen Fehler zu warten, der nie kommt.