Skip to content

Developers: reading the oracle's feeds

A deployment publishes the oracle’s launch manifest: on a Kadia site, at /manifests/testnet/oracle.json. The site’s config pins its SHA-256 (oracle.manifestSha256). Hash the raw bytes and compare before you parse.

Check that:

  • schema is kadia-oracle/launch-manifest/1, and target is your network;
  • committee gives id, seats, quorumFloor and hotKeys;
  • feeds is a list of entries with:
    • index, name and typeId;
    • nft, the token that marks the feed’s box;
    • scale (100,000,000 for every feed), and unit (“USD x 1e8”);
    • params, with heartbeat, obsBlocks and the move limits;
    • status, which is live or abstaining.

Bridged feeds (indexes 2 to 7) name their token in name, as “(bridged rsXXX)”.

The feed lives in the one unspent box holding its NFT (amount 1). Its box id changes with every write; genesisBox in the manifest is only the first.

GET {node}/info → fullHeight
GET {node}/blockchain/box/unspent/byTokenId/{feed.nft}

Keep only boxes that hold that token with amount 1. Refuse zero boxes or more than one.

Register Type Fields
R4 Long The value. The price is value / scale.
R5 Coll[Int] [committeeId, feedIndex, typeId, updatedAt, firstAt, flags, gapBps, pendingDir, windowStart, epochAtWrite]
R6 Coll[Long] [pending, referenceValue, windowRef, marketMedian]
R7 Coll[Int] [nIssued, nActive, nFresh, nInBand, nAssert, nRefInBand]
R8 Coll[Int] [HB, DEV, BAND, B, PEG_LIMIT, OBS, VMAX_LOG2]
R9 Coll[Byte] specHash, 32 bytes

Check R5’s first three fields against the manifest’s committee.id, the feed’s index and its typeId, and refuse a mismatch. updatedAt is the height of the last write.

Bit value Name Meaning
1 OBS Observation only: display the value, don’t act on it
2 PAUSED A guardian pause is in force (the price is still accurate)
4 PEG_OR_BRIDGE A peg or bridge problem. Bridged feeds and USE only, never ERG/USD
8 UNSAFE_MOVE A big move is held until the next round confirms it
16 CHANGE_PENDING A script upgrade is announced
32 ROSTER_SHORT Fewer active operators than the target
64 UNPAID The round that wrote this paid no rewards
128 FAST_MOVE The value moved more than B from windowRef in the current window
256 REMOVAL_PENDING The issuer has a removal pending
512 RATE_MISSING USE only: the redemption rate was missing this round
1024 REF_SHORT Too few reference values in band

With age = fullHeight − updatedAt:

  • Stale when age > maxAge. Don’t use the value. maxAge is the consumer’s own: the oracle spec says “typically 3 heartbeats”. A consumer that’s stale blocks new risk and suspends liquidations.
  • Late when age > heartbeat but not stale. The value is still usable; a round is overdue.
  • In observation while OBS is set, or while fullHeight < firstAt + obsBlocks. Display the value, but don’t act on it.
    • On testnet the observation period is 720 blocks.
    • On mainnet it’s at least 10,080 blocks. The spec’s table gives 20,160 for feeds 0 and 1 and 21,600 for the bridged feeds.
  • The oracle page: stale past the max_age in the deployment’s status file (/api/status/testnet/oracle/status.json, feeds[].max_age), and otherwise past 3 heartbeats.
  • Lending v1 on testnet: 30 blocks for ERG/USD, and 90 for the bridged feeds.
  • Stop orders: maxAge defaults to min(720, 3 × heartbeat), and is at most 720 blocks.

The oracle runs two deployments on testnet:

Deployment Launch manifest Who reads it
ed79c28 SHA-256 08fd2048… Today’s consumers: lending, DEX stop orders and the public status file
Co-write, with price requests (revision 71806fe) SHA-256 daea3459…; first round at block 619,118 Runs beside it. It answers price update requests

The co-write manifest’s full SHA-256 is daea345919d6d7e7b6313479d456e2ddfce76af90a20a7eef9f9b595da006947.

Read the deployment your consumer reads: its manifest names its own feed NFTs. The ed79c28 manifest still says “heartbeat plus a margin” in its reading.stale text, written before kadia-oracle corrected it (36bbddf). The co-write manifest has the corrected text. Follow the rule above either way.

Technical details

Sources: kadia-oracle at commit 083061f (083061f1f51023a95ce6a7ea5888b4165ac1edab): oracle-v1-spec.md and ops/crates/oracle-ops/src/bin/oracle-genesis.rs, which writes the manifest. kadia-web packages/data/src/live/oracle.ts (the reader), packages/data/src/oracle-status.ts (the staleness rule), packages/dex-sdk/src/stop.ts (stop orders), at kadia-web 1586b24.