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.

Simulated Exchange and Order Matching

Relevant Rust source files

• crates/system/src/kernel.rs
• crates/backtest/src/exchange.rs
• crates/execution/src/matching_engine/engine.rs
• crates/execution/src/matching_core/mod.rs
• crates/execution/src/models/fill.rs
• crates/execution/src/order_emulator/emulator.rs

Purpose and Scope

This page documents the simulated exchange and order matching infrastructure used during backtesting and emulation in NautilusTrader. It explains how SimulatedExchange replicates venue behavior, how OrderMatchingEngine processes market data and matches orders, and how MatchingCore implements the core matching logic. This system is designed for high-fidelity simulation, supporting queue position tracking, liquidity consumption, and adaptive price ordering for bar data.

Architecture Overview

The order matching system consists of three primary layers that work together to simulate realistic exchange behavior. While SimulatedExchange is specific to backtesting, the MatchingCore is also utilized by the OrderEmulator for local order simulation in live environments.

System Entity Mapping

The following diagram bridges the conceptual "Simulated Venue" to the specific code entities in the nautilus_trader codebase.

Sources:

SimulatedExchange

The SimulatedExchange (represented in BacktestEngine as a mapping of venues) simulates a trading venue during backtesting. It acts as the container for matching engines, account state, and venue-specific configurations.

Key Responsibilities

• Venue Management: Orchestrates multiple OrderMatchingEngine instances, one for each instrument traded on the venue
• Market Data Processing: Routes QuoteTick, TradeTick, and Bar data to the correct matching engine to update the order book and trigger matches
• In-flight Command Simulation: Manages a priority queue (inflight_queue) to simulate network latency for trading commands
• Simulation Modules: Supports SimulationModule extensions for custom venue behaviors like FX rollover interest or custom funding logic
• Settlement: Handles venue settlement, funding payments for perpetuals, and market status transitions

Sources:

OrderMatchingEngine

The OrderMatchingEngine (Rust implementation in crates/execution/src/matching_engine/engine.rs) handles the execution logic for a specific instrument. It bridges market data updates to the OrderMatchingCore.

Key Features

• Queue Position Tracking: Tracks the quantity ahead of an order at the time of placement. Orders only fill after queue_ahead has been consumed
• Liquidity Consumption: Tracks available liquidity per price level via bid_consumption and ask_consumption maps. Fills consume this liquidity to prevent unrealistic fills within a single market data update
• Precision Management: Validates that incoming market data matches the instrument's price and size precision to prevent rounding errors
• Account Identification: Maps TraderId to AccountId for correct event routing and accounting

Sources:

OrderMatchingCore

The OrderMatchingCore implements the fundamental order matching logic. It maintains internal books for resting limit and stop orders.

Book Layout and Priority

The Rust OrderMatchingCore utilizes a dual-book architecture:

• Resting Orders: Tracks orders that have been accepted and are waiting for a match

• Price-Time Priority: Orders are matched according to standard CLOB rules:

  • Bid Limits: Highest price first.
  • Ask Limits: Lowest price first.
  • FIFO: Within a price level, orders are processed in insertion order using RestingOrder structures.

Interaction Flow

OrderMatchingEngine supplies market state to MatchingCore; matching returns explicit fill or trigger actions that SimulatedExchange converts into the same order events consumed by the live engine path.

Sources:

Fill Models and Liquidity

The FillModel determines the price and quantity of a fill based on market conditions.

• DefaultFillModel: Standard fill logic used for backtesting, matching against available book liquidity
• BestPriceFillModel: Fills at the best available price regardless of book depth
• Fill Inside Spread: Configuration allowing limit orders to fill when the price is within the current bid-ask spread

Sources:

Adaptive High-Low Ordering for Bar Simulation

When backtesting using Bar data, the engine simulates price movement within the bar (Open, High, Low, Close). The sequence is determined adaptively to provide realistic triggers for stop orders:

1. Open is processed first.
2. If the High is closer to the Open than the Low, the sequence is: Open -> High -> Low -> Close.
3. If the Low is closer to the Open, the sequence is: Open -> Low -> High -> Close.

This ensures that if a bar spans both a stop-loss and a take-profit level, the one closer to the opening price is triggered first, mirroring typical market behavior. This behavior is toggled via the bar_adaptive_high_low_ordering flag in SimulatedExchange.

Sources: