Binary Encoding & Zero-Copy Parsing

ITCH's Add Order message is 36 bytes: message type (1), stock locate (2), tracking number (2), timestamp (6), order reference number (8), buy/sell indicator (1), shares (4), stock (8), price (4). A few of those choices are worth copying, and a few are not:

• Stock locate is a 2-byte integer that indexes the day's instrument directory. A subscriber keeps an array of books indexed by locate code, so it never hashes a symbol on the hot path. The 8-byte symbol is sent anyway, mostly for human debugging and for consumers that never built the directory.
• 6-byte timestamps save two bytes per message. 2^48 nanoseconds is about 78 hours, which is plenty for a trading day. The cost is that you cannot load a 6-byte field with one native load. You have to assemble it from smaller pieces.
• 4-byte prices with implied decimals are fixed-point integers. Every price level comparison in the book is then an exact integer compare. Floats would be wrong here, because 0.1 has no exact binary representation and two "equal" prices could land on different levels.
• Big-endian everywhere is a convention inherited from network protocols. On x86-64 and ARM, which are both little-endian, every multi-byte field needs a byte swap. That swap is cheap, but it is never free to reason about.

The exchange's own feed is little-endian, the same choice SBE makes by default and CME MDP 3.0 inherits. Your servers and nearly every consumer's servers are little-endian, so a field load is a plain mov. Fields are placed at naturally aligned offsets: a u64 starts at a multiple of 8, a u32 at a multiple of 4. Message lengths are multiples of 8. If a receive buffer starts 8-aligned, every field of every message in it is aligned too.

AddOrder  (type 'A', 40 bytes, little-endian)
offset size field
 0      1   msg_type      b'A'
 1      1   side          b'B' | b'S'
 2      2   instrument    u16   index into the instrument directory
 4      4   qty           u32
 8      8   seq           u64   per-instrument book sequence (week 10)
16      8   order_id      u64
24      8   price         i64   ticks; negative prices are legal
32      8   timestamp_ns  u64   ns since midnight

This is the layout the drills use. The repo's own protocol, described in the capstone, follows the same rules (little-endian, aligned fields, lengths a multiple of 8) with its own set of messages.

In Rust, the standard library does all of this with to_le_bytes / from_le_bytes on every integer type. On a little-endian target, u64::from_le_bytes(arr) compiles to a single load. from_be_bytes adds a bswap, or uses one movbe when the target CPU supports it. Either way the byte-order work costs about a cycle, so "which endianness" is really a question of consistency, not speed.

// The whole encoding toolkit: fixed offsets + to_le_bytes.
out[8..16].copy_from_slice(&msg.seq.to_le_bytes());
let seq = u64::from_le_bytes(buf[8..16].try_into().unwrap());

Why i64 for price? Instruments such as calendar spreads trade at negative prices, and in April 2020 the front-month WTI crude future did too. A u64 price is a latent outage.

// AddOrder, 40 bytes, little-endian (see the layout table above).
//  0 u8 msg_type 'A' | 1 u8 side 'B'/'S' | 2 u16 instrument | 4 u32 qty
//  8 u64 seq | 16 u64 order_id | 24 i64 price | 32 u64 timestamp_ns

pub const ADD_ORDER: u8 = b'A';
pub const ADD_ORDER_LEN: usize = 40;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Side {
    Buy,
    Sell,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AddOrder {
    pub side: Side,
    pub instrument: u16,
    pub qty: u32,
    pub seq: u64,
    pub order_id: u64,
    pub price: i64,
    pub timestamp_ns: u64,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CodecError {
    /// Destination (encode) or source (decode) shorter than 40 bytes.
    BufferTooShort { need: usize, have: usize },
    UnknownType(u8),
    BadSide(u8),
}

/// Write `msg` into the first 40 bytes of `buf` and return 40.
/// Must not allocate, and must not touch bytes past offset 40.
pub fn encode_add_order(msg: &AddOrder, buf: &mut [u8]) -> Result<usize, CodecError> {
    todo!()
}

/// Decode from the first 40 bytes of `buf` (trailing bytes are ignored).
/// Check order: length, then type byte, then side byte.
pub fn decode_add_order(buf: &[u8]) -> Result<AddOrder, CodecError> {
    todo!()
}

The C instinct is to declare a #[repr(C)] struct that matches the wire layout and cast the buffer pointer to it. That would make decoding free. In Rust it is undefined behaviour for three separate reasons:

1. Alignment. Creating a &AddOrderWire from a pointer that is not aligned to the struct's alignment (8 here) is UB, even if you never read through it. A buffer slice starting at offset 36 of a packet is not 8-aligned. On x86 the hardware would perform an unaligned load with little or no penalty, unless it splits a cache line. The compiler is still allowed to assume alignment and optimize on that assumption.
2. Validity. A Side enum has two valid bit patterns. A byte of b'Z' in that position makes the reference point at an invalid value, and that is UB the moment it is produced. The same applies to bool, char and references.
3. Endianness and padding. A native struct uses host byte order and may contain padding the compiler is free to fill with anything. Neither is part of a wire contract.

The sound shortcuts are crates that encode those rules in traits. zerocopy (FromBytes, KnownLayout, Immutable, Unaligned, plus byte-order-aware integer types like zerocopy::byteorder::U64<LittleEndian>) and bytemuck (Pod, try_from_bytes) let you overlay a struct on bytes when every field accepts every bit pattern and the alignment is 1 or checked. Enums stay as raw u8 in the overlay and are validated when you read them.

Bounds checks: pay once. Indexing a slice with buf[24..32] checks bounds every time. Inside a function that reads six fields that's six checks and six panic paths. They are cheap when predicted, but they bloat the code and block vectorization. Convert once to a fixed-size array, and every later constant index is checked at compile time:

// One check up front. After this, b[24..32] on a &[u8; 40] needs no runtime check.
let b: &[u8; 40] = buf.first_chunk().ok_or(CodecError::BufferTooShort { need: 40, have: buf.len() })?;
let price = i64::from_le_bytes(b[24..32].try_into().unwrap()); // unwrap is provably infallible, compiled away

A decoder that returns an owned AddOrder copies all 40 bytes into a struct. For a feed handler that only needs the order id and quantity of a cancel, that work is wasted. A view is a struct holding &'a [u8] that has been validated once (type byte and length). Its accessor methods decode one field each. The lifetime 'a ties the view to the buffer, so the borrow checker stops you from keeping a view after the receive buffer is reused. In C++ the same bug compiles and turns into a use-after-free.

The second design trick is the common prefix. Put the fields every message type carries (type, instrument, qty, seq, order id) at the same offsets in every message. Generic code, such as sequence tracking, per-instrument routing or a capture indexer, can then read them without dispatching on type at all.

Common 24-byte prefix (all types)      AddOrder adds        Cancel ('X') is
 0 u8 type   1 u8 side/0  2 u16 instr   24 i64 price         just the prefix:
 4 u32 qty   8 u64 seq   16 u64 id      32 u64 timestamp_ns  24 bytes total

// Two types share the 24-byte prefix at identical offsets:
//  0 u8 msg_type 'A' (40 bytes) | 'X' (24 bytes)   1 u8 side ('B'/'S'; 0 for 'X')
//  2 u16 instrument   4 u32 qty   8 u64 seq   16 u64 order_id
//  AddOrder only: 24 i64 price, 32 u64 timestamp_ns.  All little-endian.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ParseError {
    UnknownType(u8),
    /// Fewer bytes than the message needs (`need: 1` when the input is empty).
    Truncated { need: usize, have: usize },
}

pub fn msg_len(msg_type: u8) -> Option<usize> {
    match msg_type {
        b'A' => Some(40),
        b'X' => Some(24),
        _ => None,
    }
}

/// A borrowed view of exactly one message. Copies nothing.
#[derive(Debug, Clone, Copy)]
pub struct MsgView<'a> {
    bytes: &'a [u8],
}

impl<'a> MsgView<'a> {
    /// Validate type and length once. The view covers exactly msg_len bytes;
    /// anything after them in `buf` is not part of this message.
    pub fn parse(buf: &'a [u8]) -> Result<MsgView<'a>, ParseError> {
        todo!()
    }
    pub fn bytes(&self) -> &'a [u8] {
        self.bytes
    }
    pub fn msg_type(&self) -> u8 { todo!() }
    pub fn instrument(&self) -> u16 { todo!() }
    pub fn qty(&self) -> u32 { todo!() }
    pub fn seq(&self) -> u64 { todo!() }
    pub fn order_id(&self) -> u64 { todo!() }
    /// Some(price) for AddOrder, None for Cancel.
    pub fn price(&self) -> Option<i64> { todo!() }
}

/// Back-to-back messages in one buffer. After the first error, yield that
/// error once and then None forever: the stream position is lost.
pub struct Messages<'a> {
    buf: &'a [u8],
    pos: usize,
    failed: bool,
}

pub fn messages(buf: &[u8]) -> Messages<'_> {
    Messages { buf, pos: 0, failed: false }
}

impl<'a> Iterator for Messages<'a> {
    type Item = Result<MsgView<'a>, ParseError>;
    fn next(&mut self) -> Option<Self::Item> {
        todo!()
    }
}

A decoder for one message is half the problem. The other half is framing: finding message boundaries in whatever the transport hands you.

• TCP is a byte stream. One read() can return half a message or three and a half messages. Every TCP protocol therefore carries an explicit length. SoupBinTCP (under OUCH and ITCH-over-TCP) prefixes each packet with a 2-byte length. FIX uses its BodyLength field (week 14). Your gateway will use a 2-byte little-endian length prefix, and you'll write the incremental decoder for it this week in crates/wire, ready for the gateway to use in week 13.
• UDP preserves datagram boundaries but not delivery or order. MoldUDP64 puts a sequence number and a message count in each packet header and length-prefixes each message inside. A receiver detects gaps from the header alone, without parsing a single message.

Treat every byte from the network as hostile. A decoder in the gateway sees input from clients you do not control, including buggy ones. A panic there is a remotely triggerable crash of your exchange. The rules:

• Never index without a checked length. Return Err, never unwrap on data-derived values.
• Validate a length field before you act on it. Reject lengths above the protocol maximum before you allocate or wait for the bytes.
• Fuzz it. cargo fuzz with a target that feeds arbitrary bytes into messages() and asserts nothing panics will find the case you forgot in minutes.

The week's benchmark targets are a single decode in 15 ns at p50 and a mixed stream at 40 million messages per second, 25 ns per message including framing. At 3–4 GHz, 15 ns is 45–60 cycles. That is plenty for a type dispatch and a handful of loads. It is not enough for an allocation: a malloc/free pair costs roughly 10–20 ns even on a good allocator's fast path, most of the budget, and a cache miss to DRAM costs ~80–100 ns. Two measurement traps matter at this scale:

1. The timer costs as much as the work. Instant::now() on Linux x86-64 goes through the vDSO and costs roughly 15–25 ns on typical hardware. Timing each decode individually measures the clock. Time a batch of thousands of messages and divide, as the drill's last case does, as the repo's w11.decode does (1,000 decodes per timed sample), and as criterion does for you.
2. The optimizer deletes unused work. If nothing reads the decoded value, LLVM can remove the decode entirely, and you'll "measure" 0.3 ns. Route inputs and outputs through std::hint::black_box, and accumulate something from every message.

A mixed stream is harder than a uniform one for a specific reason. The type dispatch becomes an unpredictable branch, and each mispredict costs roughly 15–20 cycles on modern x86 cores. If your mixed-stream throughput is far below single-type throughput, that branch is usually why. Ordering the match arms by frequency won't fix it, but a branch-light design that reads the common prefix unconditionally will.