Venue reports, books and funding

A price update says what a node concluded. A node also signs three more payloads:

• A venue report says what the node saw for each source of one feed: the book, the perp data, and how the source counted in the price.
• A book update carries one venue instrument's local book, so that a client can keep its own copy.
• A funding update carries one perpetual's funding, 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 ask. 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, so each report or update has exactly one encoding. Trailing bytes are an error.
• Each frame is frame_type ‖ signer address[20] ‖ payload ‖ signature[65]. The signer address is an unauthenticated routing hint, as in a price frame.

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 95 bytes each.

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, because a partial fill shows a tighter market than the book has.
• Status. The status comes from the last evaluation of the feed. See Aggregation.
• Symbol. The symbol names the instrument, so a stored report joins the venue's instrument data without the node's config. It is 1–32 bytes of printable ASCII without spaces.
• 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 builds and signs a report only for a feed that some client subscribed to. The first report goes out at the next evaluation after a client subscribes.
• 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. Each node reports what it saw, so 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 symbol has a variable length L, so the offsets after it depend on 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 exact venue book state that the node signed: Binance and Bybit u, OKX seqId, Deribit change_id. Two nodes' books of one instrument thus fall on one venue timeline. Coinbase and Kraken send no update id. 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. That is a source of a feed with impact_notional set and book_top in its kinds. The node builds the book from a venue snapshot and the changes after it, and it proves that each change follows the last one. A failed proof is a resync: the node drops the connection and starts from a fresh snapshot. See Aggregation.

The node then 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 client that subscribes 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, so a Binance frame has no interval_ns. Binance's fundingInfo REST endpoint gives it.

Golden vectors

The oracle-wire crate holds golden.json, in its tests/vectors folder. The file freezes the protocol: payload bytes, digests, signatures, frames, feed ids, the registry encoding, venue reports, book updates and funding updates. A change in this file means that the wire format changed and that old signatures no longer verify.

Each payload vector has these fields:

Each vector also carries the fixed test key that signed it. That key is a public fixture. Never use it for anything real.

In the decoded fields, each 64-bit value is a decimal string. Each byte string is 0x-hex. Venues, markets and statuses are names, such as binance, linear_perp and used. An absent optional value is null.

Check an independent encoder

Use the vectors to test an encoder in another language:

1. Compute the domain separator from its definition. Compare it with domain.separator.
2. For each entry in feed_ids, compute keccak256 of the symbol. Compare it with feed_id.
3. For each vector, encode the decoded fields with your encoder. Compare the bytes with payload.
4. Compute the digest of payload. Compare it with digest.
5. Build frame_type ‖ signer ‖ payload ‖ signature. Compare it with frame.
6. Recover the signer from signature and digest. Compare it with signer.
7. Decode payload with your decoder. Compare the fields, then encode them again and compare the bytes.

The signatures are deterministic. cast wallet sign --no-hash with the vector's test key gives the same bytes.

The project checks the vectors with a second implementation. check_layout.py, next to golden.json, packs each payload with Python struct from the layout tables and hashes it with cast keccak. It shares no code with the Rust encoder. Other independent checks:

• published Keccak-256 test vectors, which tell Keccak-256 from SHA3-256;
• the canonical Ethereum address of secret key 1;
• the domain separator, recomputed by foundry from the EIP-712 definition alone;
• full signatures, compared with cast wallet sign --no-hash.

The foundry and Python checks skip themselves when cast or python3 is not on PATH.

To regenerate the vectors after a deliberate format change, run this command and read the diff:

REGENERATE_GOLDEN=1 cargo test -p oracle-wire --test golden

The two secp256k1 backends must agree byte for byte. This command runs the vectors under k256:

cargo test -p oracle-wire --features pure-rust