NanoExchange

Deterministic C++20 limit order book + matching engine with binary event logging, replay verification, and state hashing.

This repository is built to demonstrate strong systems engineering fundamentals:

• deterministic execution and reproducibility
• clean domain modeling (commands, events, book state)
• event-sourced replay with integrity checks
• test-first confidence on core behavior

Why This Project Stands Out

• Deterministic engine path: same command stream -> same events -> same final hash.
• Price-time priority order book with explicit buy/sell side semantics.
• Event-sourced binary log (NXLG header, NXTL trailer) for replay and auditability.
• Portable CMake + Ninja workflow and focused formatting tooling.
• Unit tests covering wire types, order book, matching fills, engine events, hashing, and log roundtrip.

Tech Stack

• Language: C++20
• Build: CMake 3.20+
• Generator: Ninja (recommended)
• Compiler: Clang or GCC (AppleClang works on macOS)
• Tests: CTest
• Formatting: clang-format

Repository Layout

src/core/
  command.h          # fixed-width command model (New/Cancel/Modify)
  event.h            # fixed-width event model (Ack/Reject/Fill/Cancelled/Modified)
  order_book.*       # price levels + FIFO queues + ID index
  matching_engine.*  # command handling + matching + event emission
  state_hash.*       # deterministic 64-bit state hash
  types.h            # domain aliases: OrderId, Price, Qty, Side
src/io/
  binary_log.*       # binary log writer/reader for commands/events
tools/
  record_demo.cpp    # deterministic command stream generator + logger
  replay.cpp         # replays logs and verifies final hash
  format.sh          # clang-format helper
tests/unit/
  test_*.cpp         # unit and behavior tests
benches/
  bench_stub.cpp     # benchmark scaffold

Quick Start

cmake -S . -B build -G Ninja
cmake --build build
ctest --test-dir build --output-on-failure
./build/nx_bench
./build/nx_latency_bench

Expected benchmark output shape:

bench_stub accepted=1000 rejected=0 emitted=1000 orders=1000

Latency benchmark output shape:

latency_bench warmup_ops=10000 measured_ops=200000 p50_ns=... p99_ns=... p99_9_ns=... throughput_ops_per_sec=...

CSV export:

./build/nx_latency_bench --csv out.csv

Deterministic Replay Demo

Record a reproducible command stream:

./build/nx_record_demo demo.bin 200

Replay and verify hash from trailer:

./build/nx_replay demo.bin

Typical output:

record: commands=200 events=306 final_hash=5037693348838137872
replay: commands=200 logged_events=306 replay_events=306 final_hash=5037693348838137872
hash OK

Build Targets

• Library: nx_core
• Tests: nx_tests, nx_wire_tests, nx_book_tests, nx_engine_tests, nx_matching_tests, nx_hash_tests, nx_log_tests
• Tools: nx_record_demo, nx_replay
• Benchmark: nx_bench, nx_latency_bench

Engineering Notes

• Price and quantity use integer ticks/lots (int64_t) to avoid floating-point drift.
• Commands and events are fixed-width/trivially copyable for fast logging.
• State hash is derived from a deterministic snapshot ordering (asks low->high FIFO, bids high->low FIFO).
• Matching emits explicit event records for downstream consumers and replay validation.

Usage Guide

Detailed workflows are in docs/usage.md.