Venue reports, books and funding

A node signs three payloads next to the price update:

• A venue report says what the node saw for each source of one feed, and how the source counted in the price.
• A book update carries the local book of one venue instrument, so that a client can keep its own copy.
• A funding update carries the funding of one perpetual, as its venue states it.

All use the same key, digest and signature format as a price update. See Signing and the price payload. A node builds venue reports and book deltas only for clients that subscribe. See Subscriptions.

Common rules

• All integers are big-endian. The version byte is 1.
• Each payload is canonical. A decoder refuses any other byte form. Trailing bytes are an error.
• Each frame is frame_type ‖ signer address[20] ‖ payload ‖ signature[65]. The signer address is an unauthenticated routing hint.

Venue codes are the same as the bits of the source bitmap:

Market codes:

A decoder refuses an unknown venue or market code.

VenueReport v1

Kind 0x03. The payload is a 55-byte header and n entries of 96 + L bytes each, where L is the length of the entry's symbol, 1 to 32.

Header

Entry

Each entry is 96 + L bytes, where L is the length of its symbol. Offsets are from the start of the entry.

The ten slots, in order:

Bits 10–15 of present must be 0.

Source status codes

Report rules

• Prices before conversion. The prices are the venue's own, before any peg conversion. The status and the weight refer to the converted price.
• Impact prices. The impact prices are for the feed's impact_notional, from the node's local book. A book that runs out of levels gives no impact price.
• Status. The status comes from the last evaluation of the feed. See Aggregation.
• Symbol. 1–32 bytes of printable ASCII without spaces. It names the instrument without the node's config.
• Canonical form. A decoder refuses an unknown venue, market or status code, a bad symbol, an unknown present bit, a non-zero absent slot, and a weight above 10,000.
• Cadence. One report after new input, at most one a second, and one at each heartbeat. The node signs a report only for a feed that some client subscribed to. The first report goes out at the next evaluation after the subscription.
• Sequence. The node seeds the report seq from its clock in milliseconds at startup, as for prices.

Report size bounds

A feed with more than 32 sources is a config error.

Verify a report

A consumer verifies a report like a price update: the signature, the registry, the clock and its own seq for each (node, feed) pair. The coherence check is different: each entry's local_recv_ns must not be later than publish_time_ns. A consumer does not combine reports across nodes.

BookUpdate v1

Kind 0x04. A book update is a snapshot of the top 50 levels on each side, or a delta: the levels that changed since the previous frame. The offsets after the symbol depend on its length L.

The payload length is 56 + L + 16 × (bids + asks) bytes.

Book rules

• Symbol. 1–32 bytes of printable ASCII without spaces (0x21–0x7E).
• Exponents. A decoder refuses a price or size exponent other than −8.
• Order. Prices are strictly ordered on each side: bids descend, asks ascend. No price repeats.
• Snapshot. A snapshot has no level with size 0.
• Delta. A delta lists each level whose size changed, with the new size. It lists each level that left the top 50 with size 0. Size 0 removes the level.
• Counts. A delta of a 50-level window changes at most 100 levels on a side. The limit of 128 covers that.
• Venue seq. It names the venue book state that the node signed: Binance and Bybit u, OKX seqId, Deribit change_id, and for Hyperliquid the time of the book message, in milliseconds. The node records no venue update id for Coinbase, Kraken, Bitfinex, MEXC and KuCoin, so bit 1 is clear for their books. A zero id is real on some venues, so bit 1, not a zero, marks an absent id. An empty snapshot after a drop has none.

Book size bounds

How books travel

The node keeps a local book for each venue instrument that reads depth: a source of a feed with impact_notional set and book_top in its kinds. See Aggregation. The node sends the book to clients in its own format:

A client that applies a snapshot, and then each delta in seq order, holds exactly the node's top 50 levels.

Keep a book on the client

Do these steps for each (node, book) pair:

1. Verify the frame: signature, registry, clock, and a seq greater than the last one.
2. If the frame is a snapshot, replace the book with its levels.
3. If the frame is a delta, apply it only when its seq is the last seq plus 1. For each level, set the new size. Remove the level when the size is 0.
4. If a seq is missing, mark the book invalid. Ignore deltas until the next snapshot.
5. An empty snapshot means that the venue connection dropped or has no data yet. Do not use that book.

Keep one book for each node. Never mix the levels of two nodes in one book. The Rust SDK keeps one book for each node and returns the freshest valid one. See Rust SDK. A new subscriber gets the latest snapshot and the deltas after it at once. See Fanout and backpressure.

FundingUpdate v1

Kind 0x05. A funding update carries one perpetual's funding. Nothing is converted: the rate is a fraction over the venue's own basis, and open interest is in the venue's own unit.

The payload length is 104 + L bytes: 105 to 136. A frame is 191 to 222 bytes.

Funding fields by venue

The node takes the fields from messages that it already reads.

Funding rules

• Flags. A field whose flag is clear is 0, and so is the unit without open interest. A decoder refuses anything else.
• Whole state. Each frame carries every field that the venue sent, so a client needs only the latest frame. Bybit sends only the changed fields; the node keeps the last value of each until the connection drops.
• Cadence. A frame goes out on a change, at most once a second for each perpetual, and at least once a minute. The node signs frames whether or not a client subscribed. After a venue connection drops, it signs nothing for that venue's perpetuals until new data arrives.
• Age. A new subscriber gets the latest frame at once, and that frame can be a minute old. A client accepts a funding frame up to two minutes old.
• Precision. A rate keeps 12 decimal places. OKX sends 16; the last 4 round away.
• Binance interval. The markPrice stream does not state the interval. The node gets it from the fundingInfo REST list of Binance, when the connection opens and each hour after. A perpetual that the list leaves out pays every 8 hours. Until the first list arrives, a Binance frame has no interval_ns.

Golden vectors

The repository holds test vectors for the wire format: payload bytes, digests, signatures and frames. cargo test -p oracle-wire --test golden checks them, and a change in the vectors means that the wire format changed.