OrderBook

by Daniel Kaminsky

A C++17 limit order book engine with unit tests. It models a single-symbol order book with price levels, FIFO queues per level, and basic operations for adding, matching, cancelling, and modifying orders.

Key Features

• Fully functional C++ limit order book engine

  • Models a single-symbol exchange with price–time priority matching.
  • Supports limit orders, market-style execution, partial fills, and crossing logic.

• Complete order lifecycle management

  • Orders can be placed, matched, cancelled, and modified at any time.
  • Correctly handles state transitions (UNFILLED, PARTIALLY_FILLED, FILLED, REJECTED) and remaining quantity tracking.

• Explicit execution and result modeling

  • Executions are represented using dedicated domain types (Fill, Trade, OrderResult).
  • Each operation returns a structured summary including executions, remaining quantity, and aggregate cost.

• Non-trivial system design and data structures

  • Implemented using ~9 core classes/structs with clear separation of concerns.
  • Uses ordered containers and iterator-based indexing to enforce price–time priority and enable efficient order lookup.

• Tested, automated, and build-system integrated

  • ~20 unit and integration tests covering matching, cancellation, modification, and edge cases.
  • Continuous integration via GitHub Actions.
  • CMake-based build system with automatic dependency management (GoogleTest).

High-Level Architecture

Project Structure

├── app/
│   └── main.cpp                  # Basic entry point console
├── docs/
│   ├── design.md
│   └── OrderBookUMLDiagram.png
├── include/
│   ├── types.hpp                 # Type aliases (OrderID, Price) and enums (Side, State)
│   ├── Order.hpp                 # Single order representation and validation
│   ├── PriceLevel.hpp            # FIFO queue at a single price level
│   ├── Entry.hpp                 # Part of OrderMap: lookup from order_id to its location
│   ├── OrderMap.hpp              # Lookup from order_id to (price, iterator, side)
│   ├── TradeEvent.hpp            # Fill/trade/order result types
│   └── OrderBook.hpp             # Public order book interface
├── src/
│   ├── Order.cpp
│   ├── PriceLevel.cpp
│   ├── OrderMap.cpp
│   └── OrderBook.cpp
├── tests/
│   ├── test_order.cpp
│   ├── test_price_level.cpp
│   ├── test_order_map.cpp
│   └── test_order_book.cpp       # End-to-end tests for matching, cancel, modify
├── .github/
│   └── workflows/
│       └── ci.yml                # Continuous integration pipeline
├── CMakeLists.txt                # Build system configuration
└── ReadMe.md

Building

Requirements:

• CMake ≥ 3.10
• A C++17-compatible compiler (e.g., g++, clang++, MSVC)

Build steps:

mkdir build
cd build
cmake ..
cmake --build .

This will:

• Build the main executable: OrderBook
• Build test binaries: test_order, test_price_level, test_order_map, test_order_book

GoogleTest is fetched automatically via CMake’s FetchContent.

Running Tests

From the build/ directory:

ctest --output-on-failure

Or run a specific test executable:

./test_order
./test_price_level
./test_order_map
./test_order_book

Using the OrderBook (API Overview)

Basic usage (conceptual):

OrderBook book;

// Place a resting buy at 100 for 10 units
auto res1 = book.buy(100, 10);

// Place a crossing sell at 100 for 10 units
auto res2 = book.sell(100, 10);

// Cancel a resting order
bool ok = book.cancel(res1.order_id);

// Modify an order’s price/quantity
auto res3 = book.modify(res1.order_id, 105, 5);

Check TradeEvent::OrderResult for:

• state – State::Unfilled, PartiallyFilled, Filled, Rejected
• fill – vector of TradeEvent::Fill for any executions
• total_cost – aggregate cost of fills for that operation
• remaining – quantity that’s still open after the operation