Limit Order Book (LOB) Engine — C++20

<!-- Core Project Badges -->

A high-performance C++ matching engine that processes buy/sell orders with exchange-style semantics.
Demonstrates low-latency hot-path design, cache-friendly data structures,
reproducible benchmarking, and clean build/test tooling.

---

🧰 Tech Stack

🔤 Languages & Compilers

✅ Testing & CI/CD

⚡ Performance & Profiling

📂 Data & Processing

🐳 Containers & Release

📊 Visualization & Reporting

🖥️ Systems & Infra

⚡ Throughput: 20.7M msgs/sec 📊 Latency: p50=0.04µs, p99≈1µs ✅ Verified on real BTCUSDT BinanceUS data

🔎 Quick Highlights

• Core engine (BookCore): limit & market orders, cancels, modifies, FIFO per price level.
• Order flags: IOC, FOK, POST_ONLY, STP (self-trade prevention).
• Persistence: binary snapshots (write/load) + replay tool.
• Performance: slab memory pool, side-specialized matching (branch elimination), cache-hot best-level pointers, -fno-exceptions -fno-rtti.
• Tooling: benchmark tool (percentiles + histogram CSVs), Catch2 unit tests, profiling toggle (-fno-omit-frame-pointer -g).

---

🧭 Architecture

Engine flow

+-------------------+          +----------------+
|  Incoming Orders  |  ----->  |    BookCore    |
+-------------------+          |  (match/rest)  |
                               +--------+-------+
                                        |
                                        v
+--------------------+          +-------------------+
| PriceLevels (B/A)  |<-------->|   LevelFIFO(s)    |
| best_bid/ask +     |          |  intrusive queues |
| best_level_ptr     |          +-------------------+
+-------------------+                   |
                                        v
                               +-------------------+
                               | Logger / Snapshot |
                               |  (events, trades) |
                               +-------------------+

Data layout

Bids ladder (higher is better)        Asks ladder (lower is better)
best_bid --> [px=100][FIFO] -> ...    best_ask --> [px=101][FIFO] -> ...

LevelFIFO (intrusive):
  head <-> node <-> node <-> ... <-> tail   (FIFO fairness, O(1) ops)

Memory pool (slab allocator)

+------------------------- 1 MiB slab -------------------------+
| [OrderNode][OrderNode][OrderNode] ... [OrderNode]            |
+--------------------------------------------------------------+
                      ^ free list (O(1) alloc/free)

---

🗂️ Repository Layout

cpp/
  include/lob/
    book_core.hpp        # engine API & hot-path helpers
    price_levels.hpp     # ladders: contiguous & sparse implementations
    types.hpp            # Tick, Quantity, IDs, flags, enums
    logging.hpp          # snapshot writer/loader, event logger interface
    mempool.hpp          # slab allocator for OrderNode
  src/
    book_core.cpp        # engine implementation (side-specialized matching)
    price_levels.cpp     # TU for headers (keeps targets happy)
    logging.cpp          # snapshot I/O + logger implementation
    util.cpp             # placeholder TU for lob_util
  tools/
    bench.cpp            # synthetic benchmark -> CSV + histogram
    replay.cpp           # snapshot replay tool
  CMakeLists.txt         # inner build (library + tools + tests)
docs/
  bench.md               # benchmark method + sample results
  bench.csv              # percentiles output (generated by bench_tool)
  hist.csv               # latency histogram 0–100µs (generated)
python/
  olob/_bindings.cpp     # pybind11 module (target: lob_cpp -> _lob)
CMakeLists.txt           # outer build (FetchContent Catch2; drives inner)

---

🛠️ Build & Run

Configure & build (Release)

rm -rf build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
      -DLOB_BUILD_TESTS=ON -DLOB_PROFILING=ON
cmake --build build -j

CMake options

• LOB_BUILD_TESTS (ON/OFF): build Catch2 tests.
• LOB_PROFILING (ON/OFF): add -fno-omit-frame-pointer -g for clean profiler stacks.
• LOB_ENABLE_ASAN (Debug only): AddressSanitizer for tests/tools.
• LOB_LTO (Release only): optional -flto.

Unit tests

ctest --test-dir build --output-on-failure

Benchmark (CSV + histogram)

./build/cpp/bench_tool --msgs 2000000 --warmup 50000 \
  --out-csv docs/bench.csv --hist docs/hist.csv

Example output:

msgs=2000000, time=0.156s, rate=12854458.3 msgs/s
latency_us: p50=0.04 p90=0.08 p99=0.08 p99.9=0.12

See docs/bench.md, docs/bench.csv, and docs/hist.csv for reproducible results.

Replay from snapshot

./build/cpp/replay_tool <snapshot.bin>

---

📚 Engine API (Essentials)

Types (include/lob/types.hpp)

• Side { Bid, Ask }, Tick (price), Quantity, OrderId, UserId, Timestamp, SeqNo.
• Flags: IOC, FOK, POST_ONLY, STP.

Orders / results

• NewOrder { seq, ts, id, user, side, price, qty, flags }.
• ModifyOrder { seq, ts, id, new_price, new_qty, flags }.
• ExecResult { filled, remaining }.

BookCore (include/lob/book_core.hpp)

• ExecResult submit_limit(const NewOrder&).
• ExecResult submit_market(const NewOrder&).
• bool cancel(OrderId id).
• ExecResult modify(const ModifyOrder&).

Ladders (include/lob/price_levels.hpp)

• PriceLevelsContig(PriceBand) — contiguous array for bounded tick ranges.
• PriceLevelsSparse — unordered_map<Tick, LevelFIFO> for unbounded ranges.
• Both expose best_bid()/best_ask() and cache-hot best_level_ptr(Side).

Snapshots & logging (include/lob/logging.hpp, src/logging.cpp)

• SnapshotWriter::write_snapshot(...).
• load_snapshot_file(...).
• IEventLogger + JsonlBinLogger (jsonl + binary events/trades; optional snapshots).

---

⚙️ Design & Performance Choices

• Slab allocator (arena)
  O(1) alloc/free for hot-path order nodes. Snapshot-loaded nodes tagged for safe deletion.
• Branch elimination
  Side-specialized templates eliminate per-iteration if (side).
• Cache-hot top-of-book
  Direct pointer to best level reduces cache misses.
• Lean binary
  Compiled with -fno-exceptions -fno-rtti -O3 -march=native.
• Deterministic FIFO
  Intrusive list ensures strict arrival order.
• Reproducibility
  Benchmarks emit percentiles + histograms into CSVs.

---

🧪 Minimal Integration (C++)

using namespace lob;
PriceLevelsSparse bids, asks;
BookCore book(bids, asks, /*logger*/nullptr);

NewOrder o{1, 0, 42, 7, Side::Bid, 1000, 10, 0};
auto r1 = book.submit_limit(o);   // may trade or rest at 1000
auto ok = book.cancel(42);        // cancel by ID

---

🔬 Profiling

Linux (perf)

perf stat -d ./build/cpp/bench_tool --msgs 2000000
perf record -g -- ./build/cpp/bench_tool --msgs 2000000
perf report

macOS (Instruments)
Use Time Profiler with frame pointers (-DLOB_PROFILING=ON).

---

🌐 Crypto Data Connector

A Python CLI ships alongside the C++ engine to capture and normalize live exchange data.

**Capture raw Binance U