NAUTILUS / RUST source 3eb18933
Pages
3.5 native-rust DeepWiki source ↗

Rust edition: this page follows the live DeepWiki structure but treats the current Rust crates as implementation authority. Non-Rust surfaces are identified at their boundary and are not presented as Rust APIs.

Order Book Management

Relevant Rust source files

  • crates/model/src/orderbook/mod.rs
  • crates/model/src/orderbook/book.rs
  • crates/model/src/orderbook/own.rs
  • crates/model/src/data/order.rs

Purpose and Scope

This document describes the order book management system in NautilusTrader, which maintains real-time representations of market depth across multiple granularity levels. The system processes incremental updates (deltas) from venues, reconstructs order books, and provides specialized tracking for a trader's own orders.

The implementation is split between a high-performance Rust core for the logic and a legacy bindings layer for strategy integration and data processing.

Book Types and Granularity

NautilusTrader supports three order book types, representing different levels of market depth granularity:

Book Type Description Update Granularity Use Case
L1_MBP Top-of-book Best bid/ask only Low-latency price feeds, simple strategies
L2_MBP Market By Price Aggregated price levels Standard depth analysis, liquidity metrics
L3_MBO Market By Order Individual orders with IDs High-frequency trading, order flow analysis

Book Entity Mapping

Order-book inputs are canonical OrderBookDelta, OrderBookDeltas, or OrderBookDepth10 model values. OrderBook applies those values under the selected L1/L2/L3 semantics and exposes snapshots and derived best-price state.

Sources:

Core Data Structures

OrderBook

The central structure for market depth. It maintains buy (bid) and sell (ask) orders in price-time priority using BookLadder instances for each side.

  • Internal State: Tracks sequence (last event number), ts_last (last update timestamp), and update_count.
  • Storage: Uses BookLadder in Rust to maintain price levels, with separate ladders for bids and asks.
  • Functionality: Supports adding, updating, and deleting orders, as well as clearing the book or specific sides.

Sources:

OrderBookDelta and Deltas

Represents incremental changes to the book state.

  • Actions: ADD, UPDATE, DELETE, CLEAR.
  • Batching: OrderBookDeltas allows atomic application of multiple updates.

Sources:

OrderBookDepth10

A fixed-depth snapshot containing the top 10 bid and ask levels.

  • Application: Can be applied directly to an OrderBook to update its top-of-book state via apply_depth.

Sources:

Order Book Reconstruction

The system reconstructs the state of the market by applying deltas to an OrderBook instance.

Data Flow: Delta to Book State

Databento order-book records crossing DBN decode and model normalization before DataEngine updates cached books and publishes subscribers.

Integrity and Staleness

The system includes specialized logic to handle "crossed" books (where best bid > best ask).

  • clear_stale_levels: Automatically removes overlapped bid/ask levels to maintain a valid spread. It can clear crossed bids, asks, or both.
  • book_check_integrity: Validates that the book is not crossed and levels are consistent.

Sources:

OwnOrderBook

The OwnOrderBook is a specialized component used to track the trader's own working orders on a specific instrument. Unlike the general OrderBook which tracks the whole market, this tracks the lifecycle and exposure of user-submitted orders.

OwnBookOrder

Represents a single user order within the OwnOrderBook.

  • Fields: trader_id, client_order_id, venue_order_id, status (SUBMITTED, ACCEPTED, etc.), and various timestamps (ts_submitted, ts_accepted, ts_init).
  • Exposure: Provides exposure() (price * size) and signed_size() (positive for buys, negative for sells).

Sources:

Functionality

  • Tracking: Maintains internal ladders to provide bid_client_order_ids and ask_client_order_ids.
  • Management: Provides methods to add, update, and delete own orders, ensuring the internal state reflects the trader's current market exposure.
  • Lifecycle: Tracks orders from initialization through to terminal states, maintaining ts_last and update_count for the book.

Sources:

Implementation Details

Precision System

NautilusTrader uses a fixed-point precision system for all price and quantity calculations within the order book to avoid floating-point errors.

  • Price/Quantity: Handled via Price and Quantity types which encapsulate fixed-point logic.
  • Precision Modes: Supports 64-bit and 128-bit (high precision) modes defined via HIGH_PRECISION and FIXED_PRECISION.
  • Arithmetic: Methods like get_avg_px_for_quantity utilize these types for accurate price discovery across levels.

Sources:

Performance Metrics

The system is optimized for high-frequency updates. Rust BTreeMap is used for BookLadder to maintain price levels in sorted order, ensuring efficient top-of-book access and incremental updates. BookPrice ordering is side-dependent: descending for bids and ascending for asks.

Sources: