Skip to content

joaquinbejar/PriceLevel

BranchesTags

Repository files navigation

Dual License Crates.io Downloads Stars Issues PRs

Build Status Coverage Dependencies Documentation

PriceLevel

A high-performance, lock-free price level implementation for limit order books in Rust. This library provides the building blocks for creating efficient trading systems with support for multiple order types and concurrent access patterns.

Features

  • Lock-free architecture for high-throughput trading applications
  • Support for diverse order types including standard limit orders, iceberg orders, post-only, fill-or-kill, and more
  • Thread-safe operations with atomic counters and lock-free data structures
  • Efficient order matching and execution logic
  • Designed with domain-driven principles for financial markets
  • Comprehensive test suite demonstrating concurrent usage scenarios
  • Built with crossbeam's lock-free data structures (crossbeam-skiplist)
  • Optimized statistics tracking for each price level
  • Memory-efficient implementations suitable for high-frequency trading systems

Perfect for building matching engines, market data systems, algorithmic trading platforms, and financial exchanges where performance and correctness are critical.

Supported Order Types

The library provides comprehensive support for various order types used in modern trading systems:

  • Standard Limit Order: Basic price-quantity orders with specified execution price
  • Iceberg Order: Orders with visible and hidden quantities that replenish automatically
  • Post-Only Order: Orders that will not execute immediately against existing orders
  • Trailing Stop Order: Orders that adjust based on market price movements
  • Pegged Order: Orders that adjust their price based on a reference price
  • Market-to-Limit Order: Orders that convert to limit orders after initial execution
  • Reserve Order: Orders with custom replenishment logic for visible quantities

Time-in-Force Options

The library supports the following time-in-force policies:

  • Good Till Canceled (GTC): Order remains active until explicitly canceled
  • Immediate Or Cancel (IOC): Order must be filled immediately (partially or completely) or canceled
  • Fill Or Kill (FOK): Order must be filled completely immediately or canceled entirely
  • Good Till Date (GTD): Order remains active until a specified date/time
  • Day Order: Order valid only for the current trading day

Implementation Details

  • Thread Safety: Uses atomic operations and lock-free data structures to ensure thread safety without mutex locks
  • Order Queue Management: Specialized order queue keeping strict price-time priority via a lock-free crossbeam-skiplist ordered index
  • Statistics Tracking: Each price level tracks execution statistics in real-time
  • Snapshot Capabilities: Create point-in-time snapshots of price levels for market data distribution
  • Efficient Matching: Optimized algorithms for matching incoming orders against existing orders
  • Support for Special Order Types: Custom handling for iceberg orders, reserve orders, and other special types

Price Level Features

  • Atomic Counters: Uses atomic types for thread-safe quantity tracking
  • Efficient Order Storage: Optimized data structures for order storage and retrieval
  • Visibility Controls: Separate tracking of visible and hidden quantities
  • Performance Monitoring: Built-in statistics for monitoring execution performance
  • Order Matching Logic: Sophisticated algorithms for matching orders at each price level

Performance Benchmark Results

The pricelevel library has been thoroughly tested for performance in high-frequency trading scenarios. Below are the results from recent simulations conducted on an M4 Max processor, demonstrating the library's capability to handle intensive concurrent trading operations.

High-Frequency Trading Simulation

Simulation Parameters
  • Price Level: 10000
  • Duration: 5002 ms (5.002 seconds)
  • Threads: 30 total
    • 10 maker threads (adding orders)
    • 10 taker threads (executing matches)
    • 10 canceller threads (cancelling orders)
  • Initial Orders: 1000 orders seeded before simulation
Performance Metrics
Metric Total Operations Rate (per second)
Orders Added 715,814 143,095.10
Matches Executed 374,910 74,946.54
Cancellations 96,575 19,305.87
Total Operations 1,187,299 237,347.51
Final State After Simulation
  • Price: 10000
  • Visible Quantity: 4,590,308
  • Hidden Quantity: 4,032,155
  • Total Quantity: 8,622,463
  • Order Count: 704,156
Price Level Statistics
  • Orders Added: 716,814
  • Orders Removed: 215
  • Orders Executed: 401,864
  • Quantity Executed: 1,124,714
  • Value Executed: 11,247,140,000
  • Average Execution Price: 10,000.00
  • Average Waiting Time: 1,788.31 ms
  • Time Since Last Execution: 1 ms

Contention Pattern Analysis

Hot Spot Contention Test

Performance under different levels of contention targeting specific price levels:

Hot Spot % Operations/second
0% 7,548,438.05
25% 7,752,860.57
50% 7,584,981.59
75% 7,267,749.39
100% 6,970,720.77
Read/Write Ratio Test

Performance under different read/write operation ratios:

Read % Operations/second
0% 6,353,202.47
25% 34,727.89
50% 28,783.28
75% 31,936.73
95% 54,316.57

Analysis

The simulation demonstrates the library's exceptional performance capabilities:

  • High-Frequency Trading: Over 264,000 operations per second in realistic mixed workloads
  • Hot Spot Performance: Up to 7.75 million operations per second under optimal conditions
  • Write-Heavy Workloads: Over 6.3 million operations per second for pure write operations
  • Lock-Free Architecture: Maintains high throughput with minimal contention overhead

The performance characteristics demonstrate that the pricelevel library is suitable for production use in high-performance trading systems, matching engines, and other financial applications where microsecond-level performance is critical.

Changes in v0.8.0

  • Price-time priority across partial fills (issue #39). A partial fill previously re-queued the resting maker's residual at the back of its price level, so the next aggressor at that price matched a later arrival instead of the older, partially-filled maker (a wrong maker_order_id in the trade stream). The order queue now keeps strict price-time priority: the residual stays at the front. Iceberg / reserve replenishment keeps its existing semantics (a refreshed tranche still loses time priority).

  • Internal queue moved to a lock-free crossbeam-skiplist ordered index. The method surface of [OrderQueue] is unchanged, but because the new index relies on interior mutability, [OrderQueue] and [PriceLevel] no longer implement [std::panic::UnwindSafe] / [std::panic::RefUnwindSafe] (they remain Send + Sync). This is the only breaking change and is why this release is 0.8.0 rather than a patch. Callers that wrapped these types in [std::panic::catch_unwind] are affected; nothing else is.

  • Matching concurrency contract. [PriceLevel::match_order] assumes a single logical matcher per level at a time. Concurrent add_order / cancel from other threads are safe, but two concurrent match_order calls on the same level — or a match_order racing a cancel of the resting order it is currently matching — are the caller's responsibility to serialize.

  • Reserve replenish amounts are now NonZeroU64 (issue #70). A replenish amount of 0 is structurally invalid: it would draw an empty visible tranche from the hidden quantity, silently leaving nothing visible. The reserve replenish surface therefore moved from Quantity (which permits 0) and raw u64 to [std::num::NonZeroU64]:

    v0.8 (before) v0.8 (now)
    ReserveOrder.replenish_amount: Option<Quantity> Option<NonZeroU64>
    DEFAULT_RESERVE_REPLENISH_AMOUNT: u64 NonZeroU64 (value 80)
    OrderType::refresh_iceberg(&self, u64) refresh_iceberg(&self, NonZeroU64)

    Constructing a reserve order with a zero replenish is now impossible at the type level. Build the amount with [std::num::NonZeroU64::new], which returns an Option. For a known-good literal, a compile-time constant is simplest. For a runtime value n, match on NonZeroU64::new(n) and treat None as an invalid amount to reject — do not blindly .unwrap() it (that panics on 0), and do not pass NonZeroU64::new(n) straight into the Option field (that silently maps 0 to None, which falls back to the default replenish instead of flagging the bad input). On the text / JSON deserialization path a replenish_amount of 0 is rejected with a typed [PriceLevelError::InvalidFieldValue] (text) or a deserialization error (JSON) rather than silently accepted — never a panic. Reading the default as a raw integer now requires DEFAULT_RESERVE_REPLENISH_AMOUNT.get().

Migration Guide (v0.6 → v0.7)

Version 0.7.0 introduces several intentional breaking changes to improve type safety, correctness, and API ergonomics. This section provides a complete mapping from the old API surface to the new one.

Execution Domain Rename

The execution domain was renamed from Transaction to Trade to align with standard financial terminology.

v0.6 v0.7
Transaction [Trade]
TransactionList [TradeList]
transaction_id field [Trade::trade_id()] accessor
Transaction: parsing prefix Trade: parsing prefix

Identifier Types

Raw Uuid identifiers were replaced with the [Id] enum, which supports UUID, ULID, and sequential (u64) formats. Trade IDs are generated via [UuidGenerator].

v0.6 v0.7
Uuid (raw) [Id] enum (Uuid, Ulid, Sequential)
Uuid::new_v4() [Id::new()] or [Id::new_uuid()]
u64 order/trade IDs [Id::from_u64()] or [Id::sequential()]
AtomicU64 trade counter [UuidGenerator::next()]

Domain Newtypes

Raw numeric primitives used in the public API were replaced with validated domain newtypes. Each provides new(), try_new(), Display, FromStr, and serde support.

v0.6 v0.7 Inner
u128 (price) [Price] u128
u64 (quantity) [Quantity] u64
u64 (timestamp) [TimestampMs] u64 
use pricelevel::{Price, Quantity, TimestampMs};

let price = Price::new(10_000);
let qty   = Quantity::new(100);
let ts    = TimestampMs::new(1_716_000_000_000);

// Convert back to primitives
assert_eq!(price.as_u128(), 10_000);
assert_eq!(qty.as_u64(), 100);
assert_eq!(ts.as_u64(), 1_716_000_000_000);

Checked Arithmetic

All arithmetic in financial-critical paths now uses checked operations and returns Result<T, PriceLevelError> instead of raw values. No silent saturation or wrapping is performed.

Method v0.6 Return v0.7 Return
[PriceLevel::total_quantity()] u64 Result<u64, PriceLevelError>
[MatchResult::executed_quantity()] u64 Result<u64, PriceLevelError>
[MatchResult::executed_value()] u128 Result<u128, PriceLevelError>
[MatchResult::average_price()] Option<f64> Result<Option<f64>, PriceLevelError>
[MatchResult::add_trade()] () Result<(), PriceLevelError> 
use pricelevel::{PriceLevel, PriceLevelError};

let level = PriceLevel::new(10_000);
// total_quantity() now returns Result
let total: Result<u64, PriceLevelError> = level.total_quantity();
assert_eq!(total.unwrap(), 0);

Private Fields and Accessor Methods

All struct fields in the execution and snapshot modules are now private. Use the provided accessor methods instead of direct field access.

Trade:

v0.6 (field) v0.7 (accessor)
trade.trade_id trade.trade_id()
trade.taker_order_id trade.taker_order_id()
trade.maker_order_id trade.maker_order_id()
trade.price trade.price()
trade.quantity trade.quantity()
trade.taker_side trade.taker_side()
trade.timestamp trade.timestamp()

MatchResult:

v0.6 (field) v0.7 (accessor)
result.order_id result.order_id()
result.trades result.trades()
result.remaining_quantity result.remaining_quantity()
result.is_complete result.is_complete()
result.filled_order_ids result.filled_order_ids()

TradeList:

v0.6 (field) v0.7 (accessor)
list.trades (direct Vec) list.as_vec() / list.into_vec()
list.trades.push(t) list.add(t)
list.trades.len() list.len()
list.trades.is_empty() list.is_empty()

Iterator API Changes

The iter_orders() method now returns an iterator instead of a Vec, reducing allocations on the hot path. Use snapshot_orders() when a materialized Vec is needed.

v0.6 v0.7
level.iter_orders() -> Vec<Arc<OrderType<()>>> level.iter_orders() -> impl Iterator
(no equivalent) level.snapshot_orders() -> Vec<Arc<OrderType<()>>>

Snapshot Persistence and Recovery

Snapshots are now protected with SHA-256 checksums via [PriceLevelSnapshotPackage]. The full persistence/recovery flow is:

use pricelevel::PriceLevel;

let level = PriceLevel::new(10_000);

// Serialize to JSON (includes checksum)
let json = level.snapshot_to_json().unwrap();

// Restore from JSON (validates checksum)
let restored = PriceLevel::from_snapshot_json(&json).unwrap();

Compiler Attributes

  • #[must_use] is now applied to all pure/computed methods (price(), quantity(), trade_id(), order_count(), visible_quantity(), is_complete(), etc.). Ignoring a return value from these methods will produce a compiler warning.
  • #[repr(u8)] is applied to small enums exposed in the public API ([Side], [TimeInForce]).

Error Handling

[PriceLevelError] gained new variants for the expanded error surface:

Variant Purpose
InvalidOperation { message } Checked arithmetic overflow, invalid state transitions
SerializationError { message } JSON/serde serialization failures
DeserializationError { message } JSON/serde deserialization failures
ChecksumMismatch { expected, actual } Snapshot integrity validation failure

Quick Migration Checklist

  1. Replace Transaction / TransactionList with [Trade] / [TradeList].
  2. Replace raw Uuid with [Id]; use [UuidGenerator] for trade IDs.
  3. Wrap raw price/quantity/timestamp literals with Price::new(), Quantity::new(), TimestampMs::new().
  4. Replace direct field access on Trade, MatchResult, TradeList with accessors.
  5. Handle Result returns from total_quantity(), executed_quantity(), executed_value(), average_price(), and add_trade().
  6. Replace iter_orders() collecting into Vec with snapshot_orders() if needed.
  7. Update snapshot code to use [PriceLevelSnapshotPackage] for checksum validation.
  8. Address new #[must_use] warnings on query methods.

Migration Guide (deterministic match_order timestamp)

[PriceLevel::match_order] now takes an explicit timestamp: TimestampMs argument, inserted between taker_order_id and the trade-id generator:

Before After
level.match_order(qty, taker_id, &gen) level.match_order(qty, taker_id, ts, &gen)

Why. The match path previously read the wall clock once per emitted [Trade] (SystemTime::now()) and once per fill inside the statistics update. That made the trade stream non-deterministic (each replay produced different Trade::timestamp values) and put two syscalls per fill on the hot path. The caller now threads a single taker timestamp in; it is stamped onto every [Trade] and used as the execution time for statistics. No clock is read on the match path, so matching the same input twice with the same timestamp yields a byte-identical trade stream — a prerequisite for snapshot/replay equivalence.

Pass the taker's arrival timestamp (or any deterministic value for tests/replay), e.g. [TimestampMs::new].

Migration Guide (taker time-in-force / kind semantics — breaking)

[PriceLevel::match_order] now honors the taker's [TimeInForce] and a new TakerKind. Two parameters are inserted between taker_order_id and timestamp:

Before After
level.match_order(qty, taker_id, ts, &gen) level.match_order(qty, taker_id, tif, kind, ts, &gen)

To preserve the previous "fill what you can, report the remainder" behavior, pass [TimeInForce::Gtc] and [TakerKind::Standard].

New single-level semantics. Let available be the quantity this level can actually fill for the taker, capped at the incoming quantity:

  • [TakerKind::PostOnly]: rejected if available > 0 (would take liquidity) — zero trades, full remainder, queue untouched.
  • [TimeInForce::Fok]: killed if available < incoming — zero trades, full remainder, queue untouched; otherwise filled completely.
  • [TimeInForce::Ioc]: fills available, discards the remainder (the taker is never rested by this layer).
  • [TimeInForce::Gtc] / [TimeInForce::Gtd] / [TimeInForce::Day] and [TakerKind::MarketToLimit]: fill available, report the remainder in MatchResult::remaining_quantity for the order book to rest / convert.

New MatchResult signal. A fill-or-kill kill and a post-only rejection both leave zero trades and the full remainder — indistinguishable through the old fields from "the level had no liquidity". [MatchResult] gains an additive MatchOutcome (Filled / PartiallyFilled / NotFilled / Killed / Rejected), read via MatchResult::outcome, MatchResult::was_killed, and MatchResult::was_rejected. All existing fields and accessors are unchanged. The field is #[serde(default)] so older JSON deserializes (as NotFilled); the text Display / FromStr format is unchanged and re-derives the benign outcome on parse (a Killed / Rejected signal is not carried by the text format).

Resting-maker time-in-force expiry is still not enforced by the match path — only the taker's intent is honored here. Skipping / evicting expired makers remains the order book's responsibility.

Migration Guide (snapshot format v1 → v2)

The checksum-protected snapshot format now persists per-level statistics (issue #63). [PriceLevelSnapshot] carries the eight PriceLevelStatistics counters — orders added / removed / executed, quantity and value executed, last-execution and first-arrival timestamps, and the waiting-time sum — and [PriceLevel::from_snapshot_json] / [PriceLevel::from_snapshot] restore them instead of resetting to a fresh, zeroed set. The new field is covered by the package SHA-256 checksum automatically.

The snapshot format version (SNAPSHOT_FORMAT_VERSION) is bumped from 1 to 2. Snapshot packages written by an earlier release carry version: 1 and no statistics; they are no longer accepted — [PriceLevelSnapshotPackage::validate] rejects them up-front with a [PriceLevelError::InvalidOperation] version mismatch (not a confusing checksum error). Re-take any persisted snapshots with this release. No code changes are required at the call sites: snapshot_to_json() / from_snapshot_json() keep the same signatures.

Migration Guide (Trade::total_value is now checked)

Trade::total_value now returns Result<u128, PriceLevelError> instead of u128. It computes price * quantity with checked_mul and returns [PriceLevelError::InvalidOperation] on overflow, matching the checked arithmetic of MatchResult::executed_value, which previously used an unchecked * that could panic in debug or wrap in release. Callers must handle the Result (e.g. trade.total_value()?).

Migration Guide (newtypes at the accessor boundary — breaking)

Accessors that previously returned raw integers for a domain concept now return the crate newtype, so raw u64 / u128 no longer leak across module boundaries (OrderType::price / id / side already returned newtypes — this completes the quantity / timestamp surface). Call .as_u64() / .as_u128() to recover the primitive, or keep working in the newtype.

Method Before After
[OrderType::visible_quantity] u64 [Quantity]
[OrderType::hidden_quantity] u64 [Quantity]
[OrderType::timestamp] u64 [TimestampMs]
[MatchResult::new] (initial_quantity) u64 [Quantity]
[MatchResult::with_capacity] (initial_quantity) u64 [Quantity]
MatchResult::remaining_quantity u64 [Quantity]
[MatchResult::executed_quantity] Result<u64, _> Result<[Quantity], _>
[PriceLevelSnapshot::new] (price) u128 [Price]
[PriceLevelSnapshot::with_orders] (price) u128 [Price]
[PriceLevelSnapshot::with_orders_and_stats] (price) u128 [Price]
[PriceLevelSnapshot::price] u128 [Price]
[PriceLevelSnapshot::visible_quantity] u64 [Quantity]
[PriceLevelSnapshot::hidden_quantity] u64 [Quantity]
[PriceLevelSnapshot::total_quantity] Result<u64, _> Result<[Quantity], _>

[MatchResult::executed_value] / Trade::total_value still return u128 — there is no monetary newtype. [PriceLevel::match_order] keeps its incoming_quantity: u64 input (it is converted to [Quantity] at the [MatchResult] boundary internally); its 124 call sites are unchanged.

Snapshot wire format is unchanged. [Price] and [Quantity] are #[serde(transparent)], so a snapshot serializes the same JSON numbers as before; the snapshot format version is not bumped and the SHA-256 checksum over an unchanged payload still validates. Existing snapshot JSON restores without migration.

Setup Instructions

  1. Clone the repository:
git clone https://github.com/joaquinbejar/PriceLevel.git
cd PriceLevel
  1. Build the project:
make build
  1. Run tests:
make test
  1. Format the code:
make fmt
  1. Run linting:
make lint
  1. Clean the project:
make clean
  1. Run the project:
make run
  1. Fix issues:
make fix
  1. Run pre-push checks:
make pre-push
  1. Generate documentation:
make doc
  1. Publish the package:
make publish
  1. Generate coverage report:
make coverage

Library Usage

To use the library in your project, add the following to your Cargo.toml:

[dependencies]
pricelevel = { git = "https://github.com/joaquinbejar/PriceLevel.git" }

Usage Examples

Here are some examples of how to use the library:

Testing

To run unit tests:

make test

To run tests with coverage:

make coverage

Contribution and Contact

We welcome contributions to this project! If you would like to contribute, please follow these steps:

  1. Fork the repository.
  2. Create a new branch for your feature or bug fix.
  3. Make your changes and ensure that the project still builds and all tests pass.
  4. Commit your changes and push your branch to your forked repository.
  5. Submit a pull request to the main repository.

If you have any questions, issues, or would like to provide feedback, please feel free to contact the project maintainer:

Joaquín Béjar García

We appreciate your interest and look forward to your contributions!

License: MIT

About

A high-performance, lock-free price level implementation for limit order books in Rust. This library provides the building blocks for creating efficient trading systems with support for multiple order types and concurrent access patterns.

Resources

Readme

License

MIT license
Activity

Stars

47 stars

Watchers

1 watching

Forks

13 forks
Report repository

Releases 12

v0.7.0 Latest
Feb 25, 2026
+ 11 releases

Packages

 
 
 

Contributors

Languages