Leer un precio

Desde un contrato

Existen dos formas, y guardan las mismas rondas. El registro indexa cada lectura por feedId; un adaptador por feed fija un feedId a una dirección, para que un consumidor escrito contra Chainlink no necesite saber nada de los 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);

Las seis cosas que un consumidor de Chainlink debería saber antes de fiarse de esto:

• 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 consumidor que hace sus propias comprobaciones quiere el registro y no el adaptador, porque el estado y la hora de observación no están en la tupla de 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);
}

Las lecturas del 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)

Las lecturas del 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)

Ninguna de las dos direcciones se imprime en este sitio. Resolver las direcciones explica cómo obtenerlas desde la cadena.

La respuesta y sus decimales

Una respuesta es un entero de coma fija, no un flotante y no wei. Cada feed del conjunto de génesis lleva decimals = 8, así que una respuesta de 415012345678 vale 4150.12345678. El campo admite de 0 a 18 y es propio de cada feed, así que léalo del feed en lugar de compilar un 8 dentro de su 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

Tres métodos, todos ellos lecturas simples sin clave y sin cuenta. Están listados junto a todos los demás en la referencia JSON-RPC; lo que sigue es lo que responden para esta capa.

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.

El objeto feed

Desde el servicio de oráculo

Lo que añade sobre la cadena es el detalle del cálculo: qué mercado estaba fresco, cuál entró en la mediana, a qué distancia quedó cada uno de ella, y por qué un feed no está publicando. Cuando falta un precio, ahí está la razón.

Dos puertos, dos públicos. La API de lectura responde en el 3005; el lote que el nodo consulta es un servicio de escucha aparte en el 3006, que lleva un HMAC de los bytes exactos del cuerpo en X-Pickle-Batch-Hmac, y pedir /v1/publish al servicio de escucha público responde 404 en lugar de admitir que la ruta existe. Cada cuerpo de error es una cadena fija: sin ruta, sin origen aguas arriba, sin texto de excepción.

Qué lleva la vista de un feed más allá de la cadena

La obsolescencia

staleOnchain es el nodo aplicando esas reglas por usted, sobre el reloj de pared de su petición y no sobre el del sellado. Es una comodidad: un consumidor dentro de un contrato no tiene ese campo y debe comparar updatedAt contra su propia tolerancia, que es la comprobación que hace el ejemplo de más arriba.

updatedAt es la señal honesta en todos los casos, porque sencillamente deja de avanzar cuando la publicación se detiene. No hay ninguna comprobación de edad en cadena en la que apoyarse: 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.

El servicio informa de una reason junto a stale, y esas razones merecen tratarse por separado: too_few_sources significa que se cayeron mercados, cross_check_diverged significa que los mercados y la segunda fuente no coinciden y el feed calla deliberadamente, market_closed significa que no pasa nada en absoluto. Cómo surge cada una está en Cómo se forma un precio.

Los horarios 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 un consumidor eso significa tres cosas. Un feed de acciones puede quedar legítimamente sin cambios durante dos días y medio sin estar obsoleto. Una comprobación de frescura ingenua rechaza todos los feeds del mundo real cada fin de semana, y cada uno de ellos cada noche. Y una posición que no debe liquidarse sobre un precio que nadie está haciendo ahora mismo debería leer status y negarse a actuar mientras valga 2, en lugar de actuar sobre un precio vigente que es correcto pero inmóvil.

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.

Rondas, historial y omisiones

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 elemento omitido solo se ve como un log FeedSkipped: la ronda no avanza y la respuesta anterior se mantiene. Un consumidor que vigila un feed debería por tanto vigilar FeedUpdated con el identificador del feed como topic indexado - es el evento que el adaptador no emite - y tratar un silencio largo por lo que es, en lugar de esperar un error que nunca llega.