Orderbook Engine

A compact, production-shaped single-book matching engine modeled after OrderBook-rs.

The first version keeps the business surface intentionally simple: one in-memory orderbook, serialized engine command worker, protocol envelopes, account-aware self-trade prevention, integer tick/lot/risk validation, limit/market/market-by-notional/post-only/stop/FOK orders, GTC/IOC/FOK time-in-force, FIFO matching inside each price level, enriched snapshots, REST APIs, WebSocket updates, SQLite/PostgreSQL audit storage, and a static frontend.

Shape

backend/
  src/
    engine/
      book.rs          # matching engine and sequencing
      command.rs       # serialized engine command worker
      matching.rs      # price-crossing and fill loop
      order_state.rs   # lifecycle history tracking
      errors.rs        # typed rejects
      reject_reason.rs # validation to typed rejects
      price_level.rs   # FIFO queue per price level
      sequencer.rs     # monotonic in-memory engine sequence
      snapshot.rs      # book snapshot builder
      trade.rs         # trade creation and retention
    api.rs             # REST + WebSocket transport
    db.rs              # SQLite/PostgreSQL audit storage
    model.rs           # DTOs shared by engine/API/frontend
  benches/             # Criterion benchmarks
  tests/                # API integration tests
database/              # SQL schemas and persistence notes
frontend/              # static trading dashboard

See ARCHITECTURE.md for the frontend, backend, database, and engine plan. See REFERENCE_ALIGNMENT.md for the current match against the reference repo.

Phases

Phase 1: limit order + market order + matching + cancel
Phase 2: Axum REST API + WebSocket frontend + PostgreSQL persistence
Phase 3: benchmarks + snapshots + risk checks
Phase 4: concurrency + sequencer + advanced order types

Run

cd backend
cargo run --release

Open http://127.0.0.1:8080.

Useful environment variables:

ORDERBOOK_ADDR=127.0.0.1:8080
ORDERBOOK_DB=data/orderbook.db
RUST_LOG=info

For PostgreSQL persistence, point ORDERBOOK_DB at a PostgreSQL URL:

ORDERBOOK_DB=postgres://orderbook:orderbook@localhost:5432/orderbook

The server creates the same schema at startup for both backends. SQL copies live in database/migrations/.

CLI

Start the backend, then use the CLI from another terminal:

cd backend
cargo run --release --bin orderbook-engine
cargo run --bin orderbook-cli -- health
cargo run --bin orderbook-cli -- submit --side buy --type limit --quantity 10 --price 10000
cargo run --bin orderbook-cli -- book --depth 10
cargo run --bin orderbook-cli -- orders
cargo run --bin orderbook-cli -- cancel 1

The CLI uses ORDERBOOK_API or --url:

ORDERBOOK_API=http://127.0.0.1:8080 cargo run --bin orderbook-cli -- metrics
cargo run --bin orderbook-cli -- --url http://127.0.0.1:8080 trades --limit 20

Live CLI smoke coverage has been verified against a running backend for health, metrics, submit, book, orders, history, and cancel flows.

API

• POST /api/orders submits an order.
• GET /api/orders returns active resting/partially-filled orders.
• DELETE /api/orders mass-cancels active resting/partially-filled orders.
• DELETE /api/orders/:id cancels a resting order.
• PATCH /api/orders/:id cancel-replaces a resting order.
• GET /api/orders/:id/history returns in-memory order lifecycle history.
• GET /api/book returns top-of-book depth.
• GET /api/trades returns recent trades.
• GET /api/metrics returns in-memory engine metrics.
• GET /api/engine-snapshot exports a complete in-memory engine snapshot.
• POST /api/engine-snapshot restores the in-memory book from a complete engine snapshot.
• GET /api/engine-snapshot/checkpoint returns the latest persisted snapshot checkpoint.
• POST /api/engine-snapshot/checkpoint persists the current engine snapshot as a replay checkpoint.
• POST /api/replay rebuilds the in-memory book from the latest checkpoint plus durable event journal.
• GET /api/risk/kill-switch returns kill switch state.
• POST /api/risk/kill-switch enables/disables kill switch order blocking.
• GET /ws upgrades to a WebSocket stream for book, trade, order, and cancel events.

Prices and quantities are unsigned integers. In a real venue these should represent fixed-point ticks and lots. Supported order type values are limit, market, market_by_notional, post_only, stop_limit, and stop_market. market_by_notional is buy-side and uses quote_quantity instead of base quantity. Stop orders use stop_price; stop-limit also uses price. Supported time_in_force values are gtc, ioc, and fok. Orders accept an optional account_id; when omitted, the order is anonymous for backward-compatible local testing. The matcher prevents trades between resting and taking orders that carry the same non-empty account id.

Quality

cd backend
cargo fmt
cargo test
cargo clippy --all-targets -- -D warnings
cargo bench

Rust Workflow

This repo is configured as a Rust-first project:

• backend/rust-toolchain.toml pins the stable toolchain with rustfmt and clippy.
• backend/rustfmt.toml keeps formatting consistent.
• backend/.cargo/config.toml adds aliases:
  • cargo dev
  • cargo t
  • cargo check-all
  • cargo b
• unsafe_code is forbidden for this engine.
• Criterion benchmarks cover add-only, crossing, cancel, and mixed workloads.
• Phase 3 benchmark coverage also includes snapshot depth, risk rejection, metrics, and snapshot capture workloads.
• API integration tests cover matching, active orders, cancel, persisted history, event journal, deterministic replay, command-worker transport, and account-aware self-trade prevention.
• Performance guard tests cover crossing and snapshot workloads with explicit latency guardrails.
• CLI live smoke flow has been checked against the running REST backend.

Recommended local loop:

cd backend
cargo fmt
cargo test
cargo check-all