dgtony/orderbook-rs

Purpose and Entry Points

This is a Rust library implementing a single-threaded, reactive order-matching engine for one currency pair. It accepts order commands and returns ordered processing events. The public library surface is rooted at src/lib.rs; the executable usage example is src/bin/example.rs.

Engine Boundary

src/engine/mod.rs assembles the matching-engine modules. The engine is in-memory and scoped to one order book/pair; callers own ingestion, persistence, concurrency, networking, and routing across instruments. There is no indicated external service, database, or deployment infrastructure.

Domain and Command/Event Model

src/engine/domain.rs defines trading-domain concepts such as assets, sides, prices/quantities, orders, and generated events. src/engine/orders.rs represents inbound commands: new market/limit orders, amendments, and cancellations. This command/event boundary lets each submitted command yield one or more acceptance, fill, amendment, cancellation, or validation-result events.

Validation and Sequencing

src/engine/validation.rs rejects invalid commands before they mutate book state. src/engine/sequence.rs assigns monotonically increasing order identifiers, separating identity allocation from matching logic. Processing therefore follows: command intake → validation → ID allocation where applicable → state transition/matching → event vector returned to caller.

Order Book State and Price-Time Queues

src/engine/orderbook.rs owns the book’s bid/ask state and coordinates matching, resting orders, amendments, cancellations, and spread access. src/engine/order_queues.rs provides the per-side/price-level queue structures used to retain resting limit orders and enforce queue ordering. Market orders consume available opposing liquidity and do not rest; unmatched limit quantity can remain on the book.

Matching and Event Flow

For a new limit order, the book accepts it, matches it against crossing opposite-side prices, emits fills for both aggressor and resting orders, and queues remaining quantity when applicable. A market order follows the same consumption path without a resting-price level. Amend and cancel commands locate an existing resting order on the declared side, update/remove queue state, and emit their respective events. Partial fills preserve remaining order state until filled, cancelled, or amended.

Runtime Characteristics

The runtime is native Rust, declared by Cargo.toml, with a library-first design and a small CLI/example binary. Engine instances are intentionally single-threaded and reactive: a caller synchronously submits one command and receives its event results, making ordering and state ownership local to the instance.