Skip to content

Developers: request a price update

Feeds update on their own heartbeat. If you need a fresh price sooner, for example before a stop order or a liquidation, you can pay for a round: put a request on chain, and the next round that answers it rewrites the feeds you asked for.

  • A fee of at least the round’s floor: 0.05 ERG, on testnet as on mainnet. The floor lives in the round box, and the tool reads it and refuses less: a request below it could never be answered. It’s governed (a parameter change, after its notice), and can never go below 0.041333334 ERG.
  • A deadline at least 4 and at most 720 blocks after the current height; 10 or more is recommended. A request confirmed at a block is typically answered 2 to 4 blocks later, after the operators post and the round’s next window, so allow a margin for a missed block. An unanswered fee stays locked until the deadline, so the tool refuses one more than 720 blocks ahead.
  • No USE. USE (feed 1) is parked: a round rewrites it unchanged, so a fee for it would buy nothing. The tool refuses a request that names it.
  • ERG only. The request box holds your fee as ERG, and no tokens. One with a token is left out.
  • Refunded if unanswered. A request can be answered up to and including its deadline block. From the block after, only your refund key can take the fee back.
  • The next round with a quorum for your feeds answers it, and rewrites each feed you asked for. The operators must post for it, and do so automatically for a request the keeper would answer. A requested feed without a quorum is skipped, and the request waits for a later round, or its refund.
  • At most 16 requests a round, earliest deadline first, then the highest fee. The rest wait for the next round, or their deadline.
  • The fees are split across all the round’s requests together (T, their sum):
    • each operator who reported fresh gets an equal share, ⌊0.75 × T ÷ the number of them⌋;
    • the treasury gets ⌊T ÷ 10⌋;
    • whoever aggregated the round gets the rest, at most 15% plus rounding.
  • A round run only because of requests pays the operators no KOR: the fees are their pay.

kadia-oracle’s oracle-request tool (or pull::create from Rust) builds an unsigned transaction from the payer’s plain boxes. It signs and submits nothing: your own wallet signs it, and the refund too.

oracle-request --node <node URL> --deployment deployment.json create \
--feeds 0,2 --fee <nanoERG> --deadline-in <blocks> --refund <key> --payer <key>
  • --feeds: the feed indexes you want, for example 0,2 for ERG/USD and BTC.
  • --fee: in nanoERG, at least the floor (50,000,000 for 0.05 ERG).
  • --deadline-in: blocks from now, 4 to 720 (30 by default; 10 or more is recommended).
  • --refund: the key that can take the fee back after the deadline.

To take an unanswered request’s fee back after its deadline:

oracle-request --node <node URL> --deployment deployment.json refund <request box id>
Technical details

Sources: kadia-oracle merge/cowrite-into-main at revision 71806fe (71806fec6efd1521ea9d891263a971f690e18b90): contracts/drafts/oracle/request.es (the request box), ops/crates/oracle-ops/src/pull.rs (the checks) and ops/crates/oracle-ops/src/bin/oracle-request.rs (the tool).