Matchcore

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.3

This release focuses on performance optimizations.

In-place level updates #132

Orders are now updated in place instead of being removed and reinserted into the HashMap. This reduces overhead and improves price amendment performance by ~40%.
Switch to FxHashMap #135

Replaces the standard HashMap (SipHash) with FxHashMap, a fast non-cryptographic hasher optimized for integer-heavy workloads. This significantly improves overall performance, especially:
- Cancellation throughput: ~40-52% faster
- Large-volume matching: ~35-60% faster

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)

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	~99 ns
Single iceberg order into a fresh book	~100 ns
Single post-only order into a fresh book	~100 ns
Single good-till-date order into a fresh book	~114 ns
Single pegged order into a fresh book	~55 ns

10k orders submit

Benchmark	Time (median)
10k standard orders into a fresh book	~306.48 µs
10k iceberg orders into a fresh book	~307.58 µs
10k post-only orders into a fresh book	~307.48 µs
10k good-till-date orders into a fresh book	~322.02 µs
10k pegged orders into a fresh book	~218.41 µs

Amend

Single-order amend

Benchmark	Time (median)
Single order in single-level book quantity decrease	~770 ns
Single order in multi-level book quantity decrease	~609 ns
Single order in single-level book quantity increase	~792 ns
Single order in multi-level book quantity increase	~666 ns
Single order in single-level book price update	~816 ns
Single order in multi-level book price update	~671 ns

10k orders amend

Benchmark	Time (median)
10k orders in single-level book quantity decrease	~153.35 µs
10k orders in multi-level book quantity decrease	~130.82 µs
10k orders in single-level book quantity increase	~165.50 µs
10k orders in multi-level book quantity increase	~165.83 µs
10k orders in single-level book price update	~288.02 µs
10k orders in multi-level book price update	~276.97 µs

Cancel

Benchmark	Time (median)
Single order in single-level book cancel	~792 ns
Single order in multi-level book cancel	~658 ns
10k orders in single-level book cancel	~127.33 µs
10k orders in multi-level book cancel	~104.71 µs

Matching

Single-level standard book

Match volume	Time (median)
1	~431 ns
10	~441 ns
100	~635 ns
1000	~1.62 µs
10000	~9.98 µs

Multi-level standard book

Match volume	Time (median)
1	~545 ns
10	~555 ns
100	~731 ns
1000	~1.77 µs
10000	~10.76 µs

Single-level iceberg book

Match volume	Time (median)
1	~436 ns
10	~524 ns
100	~1.10 µs
1000	~5.26 µs
10000	~38.93 µs

Multi-level iceberg book

Match volume	Time (median)
1	~543 ns
10	~641 ns
100	~1.19 µs
1000	~4.32 µs
10000	~35.51 µs

Mixed workload

Benchmark	Time (median)
Submit + amend + match + cancel	~9.68 µ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.

Makefile

The project uses a Makefile to simplify the development process.

See the Makefile for more details, or run make to see the available commands.

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Contributions are welcome! If you would like to contribute, please follow these steps:

Fork the repository
Create a new branch for your changes
Make your changes
Run all the checks (make check)
Submit a pull request

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in matchcore by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

matchcore 0.3.1