Crate matchcore

Expand description

Matchcore is a high-performance order book and price-time matching engine implemented as a single-threaded, deterministic, in-memory state machine.

It is designed for building low-latency trading systems, exchange simulators, and market-microstructure research tools.

The architecture follows principles popularized by the LMAX Architecture, prioritizing deterministic execution, minimal synchronization, and predictable performance.

§Features

Price-time priority matching engine
Deterministic state machine execution
Single-threaded design for minimal latency
Efficient in-memory order book
Support for advanced order types and flags (e.g., iceberg, pegged, time-in-force)
Designed for integration with event-driven trading systems
Clear command → outcome model for reproducible execution

§What’s New in v0.4

This release introduces price-conditional orders and a revamped cascading execution model, enabling richer order semantics and a scalable foundation for complex order interactions.

§Price-Conditional Orders

Adds a new order type that remains inactive until a price condition is satisfied.

Activated when the market price reaches a specified threshold:
- At or above a trigger price
- At or below a trigger price
On activation, submits a new order (market or limit) to the book
The activated order is treated as a fresh submission with new time priority

This abstraction supports:

Stop-loss orders
Take-profit orders

§Execution Model

Orders are stored in a price-conditional sub-book
Once triggered, they are moved into a ready queue
Execution is integrated with the matching engine via cascading

§Activation Strategy

Activation depends on whether a last-trade price exists:

§With last-trade price

Conditions are evaluated immediately on submit/amend
Orders that already satisfy the condition:
- Bypass the book
- Go directly into the ready queue
Remaining orders are organized by trigger price levels and activated via range scans (drain_levels)

§Without last-trade price

Conditions cannot be evaluated at submission time
All orders are placed into a single pre-trade level
On the first trade:
- Orders are evaluated in time priority order
- Triggered orders are drained via drain_pre_trade_level_at_price

§Cascading Execution Model

Introduces a deterministic mechanism to process dependent order activations.

After a primary order execution:

Execute all ready price-conditional orders triggered by the last-trade price change
Execute an eligible pegged taker order
Repeat until no further orders can be executed

This ensures:

Deterministic and reproducible behavior
Correct ordering of dependent executions
Proper handling of chained activations (conditional → pegged → conditional)

§Architecture

The design is heavily inspired by the LMAX architecture, a model widely used in low-latency trading systems.

Core principles include:

Single-threaded state machine
Event-driven command processing
Deterministic execution
In-memory data structures

These design choices eliminate synchronization overhead while guaranteeing reproducible behavior.

§Single-threaded

For an order book of a single instrument, events must be processed strictly sequentially.

Each event mutates the state of the book and the result of one event directly affects the next. Parallelizing matching for the same instrument therefore provides no performance benefit while introducing locking, contention, and complexity.

Running the matching engine on a single thread provides several advantages:

No locks, contention, or synchronization overhead
Predictable latency
Simpler correctness guarantees

This does not mean the entire application must be single-threaded.

A typical architecture may look like:

Command Reader/Decoder → Ring Buffer → Matchcore Engine → Ring Buffer → Execution Outcome Encoder/Writer

Systems can scale horizontally by sharding instruments across multiple engine threads.

For example:

Thread 1 → BTC-USD order book
Thread 2 → ETH-USD order book
Thread 3 → SOL-USD order book

§Deterministic

Matchcore operates as a pure deterministic state machine.

Given:

The same initial state
The same sequence of commands

the engine will always produce exactly the same results.

This property enables:

Deterministic replay
Offline backtesting
Simulation environments
Auditability
Event-sourced architectures

Deterministic execution is particularly valuable for trading systems where correctness and reproducibility are critical.

§In-memory

All state is maintained entirely in memory.

The order book, price levels, and internal queues are optimized for fast access and minimal allocations.

This design provides:

Extremely low latency
Predictable performance
Efficient memory access patterns

Persistence and replication are expected to be handled outside the engine, typically through event logs and snapshots.

§Core Concepts

Matchcore processes commands and produces outcomes.

Command → Matchcore Engine → Outcome

Commands represent user intent:

Submit order
Amend order
Cancel order

Outcomes describe the result of execution:

Applied successfully
Rejected because the command is invalid or cannot be executed in the current state of the order book

Successfully applied commands may also produce:

Trades
Order state changes
Triggered orders

§Example

use matchcore::*;

let mut book = OrderBook::new("ETH/USD");

let outcome = book.execute(&Command {
    meta: CommandMeta {
        sequence_number: SequenceNumber(0),
        timestamp: Timestamp(1000),
    },
    kind: CommandKind::Submit(SubmitCmd {
        order: NewOrder::Limit(LimitOrder::new(
            Price(100),
            QuantityPolicy::Standard {
                quantity: Quantity(10),
            },
            OrderFlags::new(Side::Buy, false /* post_only */, TimeInForce::Gtc),
        )),
    }),
});

println!("{}", outcome);

More examples can be found in the examples directory.

§Supported Order Features

Matchcore supports the following order types and execution options.

§Types

Market Order: executes immediately against the best available liquidity; optionally supports market-to-limit behavior if not fully filled
Limit Order: executes at the specified price or better
Pegged Order: dynamically reprices based on a reference price (e.g., best bid/ask)
Price-Conditional Order: becomes active when the market price satisfies a specified condition (e.g., at or above a trigger price); a generic category that includes stop-loss and take-profit orders

§Flags

Post-Only: ensures the order adds liquidity only
Time-in-Force: defines order lifetime (e.g., GTC, IOC, FOK, GTD)

§Quantity Policies

Standard: fully visible quantity
Iceberg: partially visible quantity with hidden reserve that replenishes

§Peg References

Primary: pegs to the same-side best price (e.g., best bid for buy)
Market: pegs to the opposite-side best price (e.g., best ask for buy)
Mid-Price: pegs to the midpoint between best bid and best ask

§Performance

Benchmarks are run with Criterion.

Matchcore is designed for low-latency, single-threaded, deterministic execution.

Representative benchmark results measured on an Apple M4 using Rust stable are shown below.

To run the benchmarks in your environment, run make bench.

§Submit

§Single-order submit

Benchmark	Time (median)
Single standard order into a fresh book	~104 ns
Single iceberg order into a fresh book	~104 ns
Single post-only order into a fresh book	~104 ns
Single good-till-date order into a fresh book	~116 ns
Single pegged order into a fresh book	~61 ns
Single price-conditional order into a fresh book	~112 ns
Single inactive price-conditional stop-limit order	~130 ns
Single active price-conditional stop-limit order	~142 ns

§10k orders submit

Benchmark	Time (median)
10k standard orders into a fresh book	~272.60 µs
10k iceberg orders into a fresh book	~274.71 µs
10k post-only orders into a fresh book	~272.47 µs
10k good-till-date orders into a fresh book	~284.36 µs
10k pegged orders into a fresh book	~252.08 µs
10k price-conditional orders into a fresh book	~280.79 µs
10k inactive price-conditional stop-limit orders	~264.40 µs
10k active price-conditional stop-limit orders	~540.86 µs

§Amend

§Single-order amend

Benchmark	Time (median)
Single order in single-level book quantity decrease	~775 ns
Single order in multi-level book quantity decrease	~621 ns
Single order in single-level book quantity increase	~814 ns
Single order in multi-level book quantity increase	~665 ns
Single order in single-level book price update	~809 ns
Single order in multi-level book price update	~684 ns

§10k orders amend

Benchmark	Time (median)
10k orders in single-level book quantity decrease	~188.42 µs
10k orders in multi-level book quantity decrease	~160.43 µs
10k orders in single-level book quantity increase	~211.50 µs
10k orders in multi-level book quantity increase	~185.59 µs
10k orders in single-level book price update	~261.89 µs
10k orders in multi-level book price update	~251.40 µs

§Cancel

Benchmark	Time (median)
Single order in single-level book cancel	~789 ns
Single order in multi-level book cancel	~613 ns
10k orders in single-level book cancel	~138.39 µs
10k orders in multi-level book cancel	~121.09 µs

§Matching

§Single-level standard book

Match volume	Time (median)
1	~475 ns
10	~484 ns
100	~669 ns
1000	~1.71 µs
10000	~10.63 µs

§Multi-level standard book

Match volume	Time (median)
1	~586 ns
10	~592 ns
100	~781 ns
1000	~1.90 µs
10000	~11.33 µs

§Single-level iceberg book

Match volume	Time (median)
1	~472 ns
10	~556 ns
100	~1.12 µs
1000	~5.16 µs
10000	~39.26 µs

§Multi-level iceberg book

Match volume	Time (median)
1	~580 ns
10	~666 ns
100	~1.23 µs
1000	~4.45 µs
10000	~36.30 µs

§Mixed workload

Benchmark	Time (median)
Submit + amend + match + cancel	~9.77 µs

§Notes

Benchmark results depend on CPU, compiler version, benchmark configuration, and system load.
These figures illustrate the general performance profile of the engine rather than serve as universal guarantees.
Full Criterion output includes confidence intervals and regression comparisons.

§Next Steps

§Additional Order Features

Stop orders
Last-trade peg reference

§Potential Performance Improvements

Currently, the order book stores price levels using BTreeMap<Price, LevelId> and Slab<PriceLevel>. This design provides:

O(log N) best-price lookup
O(log N) submit operations to locate the corresponding price level
O(1) amend operations (except when amending the order to a different price level)
O(1) cancel operations (except when cancelling the order removes the price level entirely)

where N is the number of price levels.

An alternative design is to store prices in Vec<(Price, LevelId)>, sorted by price from worst → best, which provides:

O(1) best-price lookup
O(N) insertion / deletion when creating or removing price levels

However, in real-world trading scenarios, most activity occurs near the best price, meaning the effective search distance is often small. This can make a linear scan competitive with tree-based structures for typical workloads.

Structs§

AmendCmd: Represents a command to amend an existing order
CancelCmd: Represents a command to cancel an existing order
Command: Represents a top-level command for all kinds of commands and orders
CommandEffects: Effects from the execution of a command
CommandMeta: Represents the common metadata for all command kinds
DepthStatistics: Represents the depth statistics of the order book
Level1: Represents the level 1 market data of the order book
Level2: Represents the level 1 market data of the order book
LevelEntries: Shared order tracking for a level
LimitBook: Limit order book that manages limit orders and price levels
LimitOrder: Generic limit order with various configuration options
LimitOrderPatch: Represents the patch to a limit order
MarketImpact: Represents the market impact analysis of a market order
MarketOrder: Market order that is executed immediately and does not reside in the order book
MatchResult: Result of a match operation
Notional: Represents a notional value (price * quantity)
OrderBook: Order book that manages all kinds of orders and levels
OrderFlags: Flags that are common to all order types
OrderFlagsPatch: Represents the patch to the flags of an order
OrderId: Represents an order ID
OrderOutcome: Outcome of the order execution
PegLevel: Peg level that manages the status of the orders with the same peg reference. It does not store the orders themselves, but only the time priority information of the orders.
PeggedBook: Pegged order book that manages pegged orders and peg levels
PeggedOrder: Pegged order that adjusts based on reference price
PeggedOrderPatch: Represents the patch to a pegged order
Price: Represents a price
PriceCondition: Represents the condition that must be met for a price-conditional order to be activated
PriceConditionalBook: Price-conditional order book that manages price-conditional orders
PriceConditionalOrder: Represents a price-conditional order
PriceConditionalOrderPatch: Represents the patch to a price-conditional order
PriceLevel: Price level that manages the status of the orders with the same price. It does not store the orders themselves, but only the time priority information of the orders.
Quantity: Represents a quantity
QueueEntry: Represents a time priority queue entry
RestingLimitOrder: Represents a limit order resting in the order book
RestingPeggedOrder: Represents a pegged order resting in the order book
RestingPriceConditionalOrder: Represents a resting price-conditional order
SequenceNumber: Represents a sequence number
SubmitCmd: Represents a command to submit a new order
Timestamp: Represents a timestamp The timestamp is expressed as a Unix timestamp (seconds since epoch).
Trade: A trade that was made during a match
TriggerPriceLevel: Trigger price level that manages the status of the orders with the same trigger price. It does not store the orders themselves, but only the time priority information of the orders.

Enums§

AmendPatch: Represents the patch to an existing order
CancelReason: Reason for the order cancellation
CommandError: Error that violates the invariants of a command
CommandFailure: Reason for the command execution failure
CommandKind: Represents the kind of command
CommandOutcome: Represents the outcome of a command execution
CommandReport: Report from the execution of a command
NewOrder: Represents a new order for all order types
OrderKind: Represents the kind of an order
PegReference: Reference price type for pegged orders
QuantityPolicy: Represents the quantity policy of an order
Side: Represents the side of an order
TimeInForce: Specifies how long an order remains active before it is executed or expires.
TriggerDirection: Direction of trigger evaluation relative to the trigger price
TriggerOrder: Represents the order to execute when the condition is met

Crate matchcore

Crate matchcore Copy item path

§Features

§What’s New in v0.4

§Price-Conditional Orders

§Execution Model

§Activation Strategy

§With last-trade price

§Without last-trade price

§Cascading Execution Model

§Architecture

§Single-threaded

§Deterministic

§In-memory

§Core Concepts

§Example

§Supported Order Features

§Types

§Flags

§Quantity Policies

§Peg References

§Performance

§Submit

§Single-order submit

§10k orders submit

§Amend

§Single-order amend

§10k orders amend

§Cancel

§Matching

§Single-level standard book

§Multi-level standard book

§Single-level iceberg book

§Multi-level iceberg book

§Mixed workload

§Notes

§Next Steps

§Additional Order Features

§Potential Performance Improvements

Structs§

Enums§

Crate matchcore