读取一个价格

从一个合约里读

存在两种形态，而它们持有同样的轮次。注册表把每一次读取都以 feedId 为键；一个逐价格源的适配器把一个 feedId 钉在一个地址 上，于是一个照着 Chainlink 写出来的消费者完全不需要知道价格源 id 这回事。

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

一个 Chainlink 消费者在依赖它之前该知道的六件事：

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

一个自己做检查的消费者想要的是注册表而不是适配器，因为状态和观测时间不在 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);
}

注册表的读取函数

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

适配器的读取函数

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

本站不打印这两个地址中的任何一个。解析地址讲的就是你 怎样从链上取得它们。

答案和它的小数位

一个答案是一个定点整数，不是浮点数，也不是 wei。创世集合里的每一个价格源都 带着 decimals = 8，所以一个 415012345678 的答案就是 4150.12345678。这个字段允许 0 到 18，而且是逐价格源的，所以请从价格源上读它， 而不是把 8 编译进你的消费者里。

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

通过 JSON-RPC

三个方法，全都是普通读取，不需要密钥也不需要账户。它们和其他每一个方法一起列在JSON-RPC 参考里；下面写的是它们为这一层回答什么。

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.

价格源对象

从预言机服务读

它在链之外多给出的是那套演算过程：哪家交易所是新鲜的、哪家被纳入了中位数、每一家离中位数有 多远，以及一个价格源为什么不在发布。当一个价格缺失时，原因就在这里。

两个端口，两类受众。读取 API 在 3005 上应答；节点轮询的那个批次是 3006 上一个独立的监听器， 在 X-Pickle-Batch-Hmac 里携带确切请求体字节的一个 HMAC，而向公开监听器索取 /v1/publish 会回答 404，而不是承认这条路由存在。每一个错误体都是一个固定的 字符串：没有路径，没有上游，没有异常文本。

一个价格源视图在链之外还带着什么

过期

staleOnchain 是节点替你施加了那些规则，按的是你这次请求的挂钟，而不是封存时的 挂钟。它是一种便利：一个合约内部的消费者没有这样一个字段，必须拿 updatedAt 去 和自己的容忍度比较，也就是上面那个示例所做的检查。

在每一种情形下 updatedAt 都是那个诚实的信号，因为发布一停它就干脆不再前进。 链上没有一个年龄检查可以依靠：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.

服务在 stale 旁边报出一个 reason，而这些理由值得分开处理：too_few_sources 表示交易所掉线了，cross_check_diverged 表示交易所 和第二来源不一致、于是价格源刻意保持沉默，而 market_closed 表示根本没出任何 问题。每一种是怎么出现的，写在一个价格如何形成那一页上。

市场时段

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.

对一个消费者来说这意味着三件事。一个股票价格源可以合法地两天半原封不动而并不算过期。一个 天真的新鲜度检查会在每个周末拒绝每一个现实世界价格源，并且每个夜里拒绝它们每一个。而一个 不该按没人正在报价的价格被清算的头寸，应该去读 status，并在它是 2 时拒绝行动，而不是按一个正确但静止的挂牌价去行动。

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.

轮次、历史与跳过

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.

一条被跳过的条目只以一条 FeedSkipped 日志可见：那一轮不推进，前一个答案继续 有效。因此一个盯着某一个价格源的消费者应该以价格源 id 作为索引 topic 去盯 FeedUpdated，那是适配器不会发出的那个事件，并且把一段长时间的沉默当成它本来 的样子，而不是去等一个永远不会到来的错误。