Limit order book simulator

A C++ limit order book with price-time priority matching, capable of replaying LOBSTER market data.

Overview

This project implements a single-instrument limit order book and matching engine in C++. It processes a stream of order messages (add, cancel, modify), replays them sequentially, and executes trades when incoming orders cross the spread. Orders are matched by best price first, then by arrival time within each price level. Supports partial fills and full order lifecycle management. Can also replay historical LOBSTER data and validate the resulting book state against known snapshots.

The data structures are modeled after what you'd see in a real trading system.

• Bid and ask sides are stored as std::map<Price, Level> containers, descending for bids, ascending for asks, giving $O(\log P)$ access to the best price.
• Each price level holds a FIFO queue (std::list<Order>) to preserve time priority with $O(1)$ removal.
• There's also an std::unordered_map<OrderId, OrderRef> index that maps order IDs directly to their location (side, price, iterator), so cancels and modifies are $O(1)$ on average without needing to scan the book.

Build

Requires CMake 3.14+ and a C++17 compiler.

mkdir build && cd build && cmake ../ && make && cd ../

This builds two executables:

• lob_simulator: A very simple CLI for replaying LOBSTER data
• lob_simulator_tui: TUI (terminal user interface) with real-time visualization

Run tests with:

# in build/ dir
ctest

Run benchmarks with:

./build/benchmark

Performance

Operation	Throughput
Insert (no matching)	~4.3M ops/sec
Cancel (random order)	~2.1M ops/sec
Matching (aggressive)	~8.0M ops/sec
Mixed workload (60% insert, 30% cancel, 10% modify)	~4.4M ops/sec

Benchmarked with 1M operations, compiled with -O3 flag. Run ./build/benchmark to reproduce.

Usage

lob_simulator (CLI)

# basic replay
./build/lob_simulator replay data/sample_lobster_messages.csv

# replay with validation against a book snapshot
./build/lob_simulator replay data/sample_lobster_messages.csv --validate data/sample_lobster_book.csv

# full AAPL dataset
./build/lob_simulator replay data/AAPL_2012-06-21_34200000_57600000_message_10.csv

lob_simulator_tui (visual dashboard)

# launch TUI using speed multiplier (default: 10x)
./build/lob_simulator_tui replay data/AAPL_2012-06-21_34200000_57600000_message_10.csv --speed 1 

The dashboard displays:

• BBO panel: Best bid/offer prices with spread and midpoint
• Depth chart: ASCII visualization of order book depth (bids in green, asks in red)
• Trades panel: Scrolling list of recent executions
• Status bar: Replay progress, speed, and controls

Keyboard controls:

Key	Action
Space	Pause/resume replay
+ / -	Increase/decrease speed
R	Restart replay
Q	Quit

The data/ folder has sample LOBSTER files and a full AAPL dataset. See data/README.md for format info.

Structure

• include/: Header files.
• src/: The actual implementation.
• tests/: Test files.
• data/: LOBSTER sample data.