match-rust

High-performance cryptocurrency matching engines in Rust for contract (and spot) exchange paths — dual-track design with a Java-equivalent core and an experimental low-latency core.

Inspired in layout and packaging by perpetual_exchange / crypto-exchange (C++ R&D), while targeting Topic/JSON-compatible cutover against live Java services. Companion repository to that project.

License: Apache License 2.0
中文： README.zh-CN.md
Wiki： English · 中文

---

Features

Equivalence track (match-core)

• Price-time priority book aligned with java-contract-match observables
• Limit / market / gear, PostOnly / IOC / FOK (including documented Java quirks where required)
• Golden NDJSON replay via match-replay

Performance track (match-core-hp)

• Fixed-point price_tick / qty_lot
• Price-level book + FIFO, best-price cache, level pool
• Optional ART-style radix index (--features art)
• SPSC worker, cache-line padded ring, configurable wait strategy
• Async WAL experiment (match-wal)

Process shell (match-contract)

• Config → RPC restore → Redis → per-symbol workers
• Memory (and future RocketMQ) transport adapters
• /healthz /readyz /metrics (Prometheus / OTel-aligned names)
• Optional --features hp-engine for hp workers + L2/L3/L1 span counters

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│ match-contract / match-spot (shells)                        │
│  MQ/RPC/Redis/health  →  per-symbol worker                  │
└───────────────┬─────────────────────────────┬───────────────┘
                │ default                     │ feature hp-engine
                ▼                             ▼
         match-core                    match-core-hp
         (Java-shaped)                 (tick/lot + LevelIndex)
                │                             │
                └──────────┬──────────────────┘
                           ▼
                    match-protocol (DTO)
                           │
              match-replay / match-bench / match-wal

Crate	Role	Production default
match-protocol	Shared order DTOs / checks	—
match-core	Equivalence engine	Yes
match-core-hp	HP experimental engine	No
match-contract	Contract process shell	uses match-core
match-spot	Spot shell (stub)	—
match-replay	Golden replay CLI	—
match-bench	Criterion + fair_compare	—
match-wal	Async batched WAL	experimental

---

Quick Start

Prerequisites

• Rust 1.97.1+ (see rust-toolchain.toml)
• macOS / Linux

Build & test

git clone https://github.com/lanpishu6300/match-rust.git
cd match-rust
cargo test --workspace

# or
make test
make ci          # fmt + clippy + tests + art + fair_compare

Local contract shell (memory transport)

export MATCH_CONTRACT_CONFIG=crates/match-contract/config.example.yaml
export MATCH_CONTRACT_LOCAL_SYMBOLS=btcusdt
cargo run -p match-contract
# make run-local

Health (default port 31015):

Path	Meaning
GET /healthz	Process up
GET /readyz	Bootstrap finished
GET /metrics	Prometheus counters

---

Performance

Fair microbench (fill_rate must be > 0 — rejects zero-fill “fake peaks”):

make fair
# cargo run -p match-bench --release --bin fair_compare -- --n 50000

Criterion suite:

make bench

ART parity:

make test-art

WAL throughput:

make wal-bench

Published numbers and methodology: bench-results (中文), fair-compare (中文), e2e-budget (中文).

End-to-end latency is usually dominated by MQ/JSON (L4), not the L1 microkernel. See the e2e budget doc before chasing nanoseconds.

---

Documentation

Doc	Description
Wiki Home (EN) / Wiki 首页（中文）	Getting started, FAQ, roadmap
Full docs index · 中文	Specs, plans, ops
Architecture notes · 中文	Crate map & dual-track rules
Equivalence design · 中文	Protocol / cutover
HP design · 中文	Fixed-point / price-level
PE optimizations · 中文	Cache / ART / wal A→B→C
Coverage policy · 中文	100% branch gate (protocol/core/hp)
OSS best practices · 中文	Disruptor / Aeron / Seastar mapping
Cutover runbook · 中文	Per-symbol grey release
RMQ spike · 中文	RocketMQ status

---

Configuration

See crates/match-contract/config.example.yaml.

RocketMQ production adapter is not wired yet (transport: memory). Details: docs/rmq-spike.md.

---

Docker

docker build -t match-rust:local .
docker run --rm -p 31015:31015 \
  -e MATCH_CONTRACT_LOCAL_SYMBOLS=btcusdt \
  match-rust:local

---

Contributing & release

• CONTRIBUTING.md · CONTRIBUTING.zh-CN.md
• SECURITY.md · SECURITY.zh-CN.md · CODE_OF_CONDUCT.md · CODE_OF_CONDUCT.zh-CN.md · SUPPORT.md · SUPPORT.zh-CN.md
• CHANGELOG.md · CHANGELOG.zh-CN.md — version history
• CI: .github/workflows/ci.yml · coverage gate: make cov
• Issue templates under .github/ISSUE_TEMPLATE/

Suggested release tags: v0.1.0, v0.2.0, …

---

Status

Area	Status
match-core equivalence	In progress / golden replay
match-core-hp	Usable experimental
match-contract shell	Memory transport; RMQ TBD
Spot shell	Stub
Production default engine	match-core only

---

Acknowledgments

• Java baseline engines: java-contract-match, java-spot-match
• Layout/performance ideas from perpetual_exchange (crypto-exchange) ART / persistence research
• Industry patterns: LMAX Disruptor, Aeron, exchange price-level books