# itch5
A fast, zero-copy parser for the [Nasdaq TotalView-ITCH 5.0](https://www.nasdaqtrader.com/content/technicalsupport/specifications/dataproducts/NQTVITCHspecification.pdf) binary protocol.
ITCH 5.0 is Nasdaq's real-time market data feed. It carries every order book event — adds, cancels, executes, replaces — plus market-wide events, trading halts, and cross-trade notifications, all encoded as compact fixed-length binary messages framed with a 2-byte big-endian length prefix.
## Usage
Add the crate to your `Cargo.toml`:
```toml
[dependencies]
itch5 = "0.1"
# Optional: enable chrono for `messages::Timestamp::to_naive_time` method
# itch5 = {version = "0.1", features = ["chrono"]}
```
Implement [`MessageHandler`] for the message types you care about, then feed bytes to [`Parser`]:
```rust
use std::ops::ControlFlow;
use itch5::{MessageHandler, Parser, messages::TradeMessage};
#[derive(Default)]
struct TradeCounter {
count: u64,
}
impl MessageHandler for TradeCounter {
fn on_trade_message(&mut self, msg: &TradeMessage) -> ControlFlow<()> {
self.count += 1;
ControlFlow::Continue(())
}
}
fn main() {
let data: &[u8] = /* your ITCH feed bytes */ &[];
let mut handler = TradeCounter::default();
Parser::new(data).parse_stream(&mut handler).unwrap();
println!("trades: {}", handler.count);
}
```
Return `ControlFlow::Break(())` from any handler method to stop parsing early.
## Core API
### `Parser`
```rust
Parser::new(buf: &[u8]) -> Parser<'_>
Parser::parse_stream(&mut self, handler: &mut impl MessageHandler) -> Result<(), ParseError>
```
Iterates over every framed message in `buf`, dispatching each one to the corresponding method on `handler`. The buffer is borrowed for the lifetime of the parser; no heap allocation occurs.
### `parse_one`
```rust
parse_one(buf: &[u8]) -> Result<(&[u8], &[u8]), ParseError>
```
Parses a single length-prefixed message. Returns `(body, remainder)` where `body` starts with the one-byte message-type tag. Useful when you need the raw bytes rather than typed structs — for example, to forward messages to another consumer.
### `MessageHandler`
A visitor trait with one method per message type. Every method has a default no-op implementation, so you only override what you need:
```rust
pub trait MessageHandler {
fn on_add_order_no_mpid_attribution(&mut self, msg: &AddOrderNoMPIDAttribution) -> ControlFlow<()> { ... }
fn on_order_executed_message(&mut self, msg: &OrderExecutedMessage) -> ControlFlow<()> { ... }
fn on_trade_message(&mut self, msg: &TradeMessage) -> ControlFlow<()> { ... }
// ... 20 more
}
```
### `ParseError`
```rust
pub enum ParseError {
EmptyBuffer,
UnknownMessageType(u8),
MalformedData,
}
```
## Message Types
All 23 ITCH 5.0 message types are covered:
| `S` | `SystemEventMessage` | Market/session lifecycle events |
| `R` | `StockDirectory` | Daily instrument reference data |
| `H` | `StockTradingAction` | Trading halt and resume |
| `Y` | `RegSHORestriction` | Regulation SHO short-sale restriction |
| `L` | `MarketParticipantPosition` | Market maker status and mode |
| `V` | `MWCBDeclineLevelMessage` | Market-wide circuit breaker levels |
| `W` | `MWCBStatusMessage` | Market-wide circuit breaker status |
| `K` | `QuotingPeriodUpdate` | IPO quotation release |
| `J` | `LULDAuctionCollar` | Limit Up/Limit Down auction collar |
| `h` | `OperationalHalt` | Exchange-specific operational halt |
| `A` | `AddOrderNoMPIDAttribution` | New order (anonymous) |
| `F` | `AddOrderWithMPIDAttribution` | New order (attributed) |
| `E` | `OrderExecutedMessage` | Order execution |
| `C` | `OrderExecutedWithPriceMessage` | Order execution at non-display price |
| `X` | `OrderCancelMessage` | Partial order cancellation |
| `D` | `OrderDeleteMessage` | Full order removal |
| `U` | `OrderReplaceMessage` | Cancel-and-replace |
| `P` | `TradeMessage` | Non-displayed trade |
| `Q` | `CrossTradeMessage` | Opening/closing/halt cross execution |
| `B` | `BrokenTradeMessage` | Trade break |
| `I` | `NetOrderImbalanceIndicatorMessage` | Cross imbalance data |
| `N` | `RetailPriceImprovementIndicator` | Retail interest flags |
| `O` | `DirectListingwithCapitalRaisePriceDiscoveryMessage` | Direct listing price discovery |
## Price Types
Prices in the ITCH protocol are fixed-point integers. The crate provides two newtype wrappers:
| `Price4` | 4 | 4 decimal places |
| `Price8` | 8 | 8 decimal places |
## Symbol
`Symbol` is an 8-byte ASCII stock ticker, space-padded on the right per the ITCH specification.
```rust
let sym: Symbol = msg.stock();
println!("{}", sym.as_str()); // e.g. "AAPL " trimmed to "AAPL"
// Parse from a string
let sym: Symbol = "MSFT".parse().unwrap();
// Compact hash/unhash for use as a map key
let key: u64 = sym.hash();
let restored: Symbol = Symbol::from_hash(key);
```
## Timestamp
`Timestamp` is a `u48` representing nanoseconds since midnight.
The crate provides a `Timestamp` newtype wrapper.
```rust
let ts: &Timestamp = Timestamp::ref_from_bytes(b"000001").unwrap();
let dur: std::time::Duration = ts.to_dur();
// requires feature `chrono` to be enabled.
let naivetime: chrono::NaiveTime = ts.to_naive_time();
```
## Wire Format
Each ITCH message is framed as:
```
[2 bytes: big-endian message length][message body]
```
The message body begins with a single ASCII tag byte that identifies the message type, followed by fixed-width fields in network byte order (big-endian). All message structs are `#[repr(C, packed)]` and implement `zerocopy::FromBytes`, so parsing is a bounds-checked pointer cast with no copying.
## Examples
Count every trade in an ITCH binary file:
```
cargo run --example parse_file -- /path/to/feed.itch
```
The source is in [`examples/parse_file.rs`](examples/parse_file.rs). It memory-maps the file and counts `TradeMessage` events.
## Benchmarks
```sh
# Default: uses the 1M-message sample at ../data/itch_1000_000
taskset -c 3 cargo bench -p itch5
# Or override the sample location:
ITCH5_BENCH_FILE=/path/to/feed.itch cargo bench -p itch5
```
The suite ([`benches/itch_bench.rs`](benches/itch_bench.rs)) is structured around the questions an HFT consumer would actually ask:
- **`itch5/framing/parse_one_only_100k`** — pure wire-format framing
cost. Walks a synthetic stream with [`parse_one`] and only inspects
the tag byte. This is the floor: length-prefix decode and slice
splits, no dispatch, no `cast`.
- **`itch5/per_msg_type/{add_no_mpid,add_with_mpid,order_executed,
order_cancel,order_delete,order_replace,trade}`** — full
`parse_stream` over a homogeneous synthetic stream of each hot
message type, dispatched into a no-op handler. Surfaces dispatch +
cast cost per type so a regression in one is isolatable.
- **`itch5/full_file/{noop_handler,counting_handler}`** — the
recorded sample replayed end-to-end. `noop` reports the parser's
intrinsic ceiling; `counting` reports what an order-book consumer
pays after touching every accessor on the hot message types.
Reported in messages/sec *and* bytes/sec.
- **`itch5/field_accessors/{price4_into_i64,timestamp_to_u64,
symbol_to_u64}`** — confirms each zero-copy big-endian accessor
folds to a single load (or load + bswap) at release optimization.
If the sample file is unavailable, the data-driven group prints a
notice and skips; the synthetic and accessor groups still run.
## License
[Unlicense](https://unlicense.org/) — public domain.