Developers: reading the oracle's feeds
1. Read the manifest
Section titled “1. Read the manifest”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:
schemaiskadia-oracle/launch-manifest/1, andtargetis your network;committeegivesid,seats,quorumFloorandhotKeys;feedsis a list of entries with:index,nameandtypeId;nft, the token that marks the feed’s box;scale(100,000,000 for every feed), andunit(“USD x 1e8”);params, withheartbeat,obsBlocksand the move limits;status, which isliveorabstaining.
Bridged feeds (indexes 2 to 7) name their token in name, as “(bridged rsXXX)”.
2. Find the feed’s current box
Section titled “2. Find the feed’s current box”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 → fullHeightGET {node}/blockchain/box/unspent/byTokenId/{feed.nft}Keep only boxes that hold that token with amount 1. Refuse zero boxes or more than one.
3. Decode its registers
Section titled “3. Decode its registers”| 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.
Flags (R5[5])
Section titled “Flags (R5[5])”| 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 |
4. Is it usable now?
Section titled “4. Is it usable now?”With age = fullHeight − updatedAt:
- Stale when
age > maxAge. Don’t use the value.maxAgeis 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 > heartbeatbut not stale. The value is still usable; a round is overdue. - In observation while
OBSis set, or whilefullHeight < 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.
What Kadia’s own apps use
Section titled “What Kadia’s own apps use”- The oracle page: stale past the
max_agein 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:
maxAgedefaults tomin(720, 3 × heartbeat), and is at most 720 blocks.
Two testnet deployments, for now
Section titled “Two testnet deployments, for now”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.