Чтение цены

Из контракта

Существуют две формы, и они держат одни и те же раунды. Реестр индексирует каждое чтение по feedId; адаптер на каждый фид закрепляет один feedId за адресом, так что потребителю, написанному под Chainlink, не нужно знать об идентификаторах фидов ничего.

// 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, несущий HMAC точных байтов тела в X-Pickle-Batch-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.

Сервис сообщает reason рядом со stale, и эти причины стоит обрабатывать по отдельности: 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: раунд не продвигается, а предыдущий ответ остаётся в силе. Поэтому потребителю, следящему за одним фидом, следует следить за FeedUpdated с идентификатором фида в индексированном топике - это событие, которого адаптер не испускает, - и трактовать долгую тишину как то, чем она является, а не ждать ошибки, которая никогда не придёт.