⚔️ 0xInfinity

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

"From Hello World to Microsecond Latency."

---

⚡ Why 0xInfinity?

This is not another "Toy Matching Engine" tutorial.

We are building a production-grade crypto trading engine that handles 1.3M orders/sec (P99 < 200µs) on a single core. This project documents the entire journey from a naive Vec<Order> implementation to a professional LMAX Disruptor-style Ring Buffer architecture.

🔥 Hardcore Tech Stack

• Zero GC: Pure Rust implementation with zero garbage collection pauses.
• Lock-free: High-performance Ring Buffer (crossbeam-queue) for inter-thread communication.
• Determinism: Event Sourcing architecture ensures 100% reproduceability.
• Safety: Ed25519 Authentication & Type-safe Asset handling.
• Persistence: TDengine (Time-Series Database) for high-speed audit logging.
• Crash Recovery: Universal WAL & Snapshot for bit-perfect state reconstruction.

🏗️ Architecture

graph TD
    Client[Client] -->|HTTP/WS| Gateway
    Gateway -->|RingBuffer| Ingestion
    subgraph "Trading Core (Single Thread)"
        Ingestion -->|SeqOrder| UBSCore["UBSCore (Risk/Balance)"]
        UBSCore -->|LockedOrder| ME["Matching Engine"]
        ME -->|Trade/OrderUpdate| Settlement
    end
    Settlement -->|Async| Persistence[TDengine]
    Settlement -->|Async| MktData["Market Data (K-Line)"]
    Settlement -->|Async| WS["WebSocket Push"]

Loading

✨ Core Features

• Order Management: Limit, Market, Cancel, Maker/Taker logic.
• Risk Control: Pre-trade balance check, exact fund locking.
• Market Data: Real-time Depth (Orderbook), K-Line (followers Binance format), Ticker.
• Interfaces: REST API, WebSocket Stream (Pub/Sub).
• Replay: Full determinism allows replaying from genesis for exactly-once state recovery.

---

🚀 The Journey

📖 Read the Book Online →

📊 Project Roadmap →

Chapters

Stage	Title	Description
0x01	Genesis	Basic OrderBook Engine
0x11	Deposit & Withdraw	✅ Mock Chain Integration (RC2 Released)
0x02	The Curse of Float	Float Curse → u64 Refactor
0x03	Decimal World	Decimal System & Precision
0x04	BTree OrderBook	BTreeMap Structure Refactor
0x05	User Balance	Account & Balance Management
0x06	Enforced Balance	Type-Safe Enforced Balance
0x07-a	Testing Framework	1M Orders Batch Testing
0x07-b	Performance Baseline	Baseline & Bottleneck Analysis
0x08-a	Trading Pipeline Design	Pipeline Architecture
0x08-b	UBSCore Implementation	UBSCore Implementation
0x08-c	Complete Event Flow	Complete Event Flow
0x08-d	Complete Order Lifecycle	Complete Order Lifecycle
0x08-e	Cancel Optimization	Cancel Optimization: Order Index
0x08-f	Ring Buffer Pipeline	Ring Buffer Performance
0x08-g	Multi-Thread Pipeline	Multi-Thread Pipeline
0x08-h	Performance Monitoring	Monitoring & Intent-Encoded
0x09-a	Gateway: Client Access Layer	HTTP Gateway Access Layer
0x09-b	Settlement Persistence	TDengine Persistence
0x09-c	WebSocket Push	Real-time Push
0x09-d	K-Line Aggregation	K-Line Aggregation
0x09-e	Order Book Depth	OrderBook Depth
0x09-f	Full Integration Test	E2E Integration & Regression
Part II	Productization
0x0A	Part II Introduction	Productization Roadmap
0x0A-a	Account System	PostgreSQL Account Manager
0x0A-b	API Auth	Ed25519 Authentication
0x0B	Funding & Transfer	Funding System Architecture
0x0B-a	Internal Transfer	FSM-based 2PC Transfer
0x0C	Trade Fee	Maker/Taker Fee System
Part III	Resilience
0x0D	Snapshot & Recovery	Universal WAL & Snapshot Persistence
0x0E	OpenAPI Integration	Swagger UI & SDK Generation
0x0F	Admin Dashboard	FastAPI Amis Admin + Trace ID
0x10	Web Frontend	Frontend Outsourcing Requirement
0x11	Deposit & Withdraw	✅ Mock Chain Integration
0x11-a	Real Chain Integration	✅ BTC Sentinel MVP
0x11-b	Sentinel Hardening	✅ DEF-002 Fix, ADR-005/006
Phase V	Extreme Optimization	"Metal Mode"
0x14	Extreme Optimization	Architecture Manifesto
0x14-a	Benchmark Harness	✅ 100% Bit-exact Parity (FILL)
0x14-b	Order Commands	✅ IOC, Move, Reduce (Feature Parity)
0x15	Zero-Copy	Planned
0x16	CPU Affinity	Planned
0x17	SIMD Matching	Planned

---

🏃 Quick Start

# Install git hooks
./scripts/install-hooks.sh

# Run Gateway mode (HTTP API + Trading Core)
cargo run --release -- --gateway --port 8080

# Run single-threaded pipeline (1.3M orders)
cargo run --release -- --pipeline --input fixtures/test_with_cancel_highbal

# Run multi-threaded pipeline
cargo run --release -- --pipeline-mt --input fixtures/test_with_cancel_highbal

# Compare both pipelines (ST vs MT)
./scripts/test_pipeline_compare.sh highbal

# Regression check (vs Golden Baseline)
./scripts/test_pipeline_compare.sh 100k

# Generate new baseline (requires --force)
./scripts/generate_baseline.sh 100k -f

---

📑 Regression Testing

We use a Golden Set strategy. Baselines are stored in baseline/.

• Consistnecy: MT mode must match ST mode 100%.
• Persistence: MT mode relies on TDengine for audit trails.
• Protection: Updates to baseline require generate_baseline.sh --force.

---

💾 Persistence (TDengine)

Start TDengine

docker run -d --name tdengine -p 6030:6030 -p 6041:6041 tdengine/tdengine:latest

Enable Persistence

Edit config/dev.yaml:

persistence:
  enabled: true
  tdengine_dsn: "taos+ws://root:taosdata@localhost:6041"

Start Persistence Mode

cargo run --release -- --gateway --env dev

Query Data

# Connect to TDengine
docker exec -it tdengine taos

# Query orders
USE trading;
SELECT * FROM orders LIMIT 10;

↑ Back to Top

---

🇨🇳 中文文档

"From Hello World to Microsecond Latency."

---

⚡ 为什么选择 0xInfinity?

这不是另一个 "玩具级撮合引擎" 教程。

我们正在构建一个生产级的加密货币交易引擎，在单核上可处理 130万订单/秒 (P99 < 200µs)。本项目记录了从最朴素的 Vec<Order> 实现到专业的 LMAX Disruptor 风格 Ring Buffer 架构的完整演进过程。

🔥 硬核技术栈

• 零 GC (Zero GC): 纯 Rust 实现，无垃圾回收暂停。
• 无锁并发 (Lock-free): 基于高性能 Ring Buffer (crossbeam-queue) 的线程间通信。
• 确定性 (Determinism): 事件溯源架构，确保 100% 可重现性。
• 安全性 (Safety): Ed25519 非对称鉴权 & 类型安全的资产处理。
• 持久化 (Persistence): 集成 TDengine 时序数据库，实现极速审计日志。
• 崩溃恢复 (Crash Recovery): 通用 WAL & 快照，实现比特级精确状态重建。

---

🏗️ 架构概览

graph TD
    Client[客户端] -->|HTTP/WS| Gateway
    Gateway -->|RingBuffer| Ingestion
    subgraph "核心交易线程 (Single Thread)"
        Ingestion -->|SeqOrder| UBSCore["UBSCore (风控/余额)"]
        UBSCore -->|LockedOrder| ME[撮合引擎]
        ME -->|Trade/OrderUpdate| Settlement
    end
    Settlement -->|异步| Persistence[TDengine]
    Settlement -->|异步| MktData["行情数据 (K-Line)"]
    Settlement -->|异步| WS[WebSocket 推送]

Loading

✨ 核心特性

• 订单管理: 限价单、市价单、撤单、Maker/Taker 逻辑。
• 风控系统: 交易前余额检查、精确资金锁定。
• 行情数据: 实时深度 (Orderbook)、K线 (Binance 格式)、Ticker。
• 接口支持: REST API、WebSocket流 (Pub/Sub)。
• 回放机制: 全确定性设计，允许从创世状态重放以实现精确的状态恢复。

---

🚀 学习之旅

📖 在线阅读完整教程 →

📊 项目路线图 →

章节索引

阶段	标题	描述
0x01	Genesis	基础订单簿引擎
0x02	The Curse of Float	浮点数的诅咒 → u64 重构
0x03	Decimal World	十进制转换与精度配置
0x04	BTree OrderBook	BTreeMap 数据结构重构
0x05	User Balance	用户账户与余额管理
0x06	Enforced Balance	类型安全的强制余额
0x07-a	Testing Framework	100万订单批量测试框架
0x07-b	Performance Baseline	性能基线与瓶颈分析
0x08-a	Trading Pipeline Design	交易流水线设计
0x08-b	UBSCore Implementation	UBSCore 实现
0x08-c	Complete Event Flow	完整事件流
0x08-d	Complete Order Lifecycle	完整订单生命周期
0x08-e	Cancel Optimization	撤单性能优化：Order Index
0x08-f	Ring Buffer Pipeline	Ring Buffer Pipeline 性能分析
0x08-g	Multi-Thread Pipeline	多线程 Pipeline
0x08-h	Performance Monitoring	性能监控与意图编码
0x09-a	Gateway: Client Access Layer	HTTP Gateway 客户端接入层
0x09-b	Settlement Persistence	TDengine 持久化层
0x09-c	WebSocket Push	实时推送
0x09-d	K-Line Aggregation	K线聚合
0x09-e	Order Book Depth	盘口深度
0x09-f	Full Integration Test	全功能集成与回归验收
Part II	产品化阶段 (Productization)
0x0A	Part II Introduction	产品化路线图
0x0A-a	Account System	PostgreSQL 账户管理
0x0A-b	API Auth	Ed25519 安全鉴权
0x0B	Funding & Transfer	资金体系架构
0x0B-a	Internal Transfer	FSM 内部转账
0x0C	Trade Fee	Maker/Taker 手续费系统
Part III	鲁棒性阶段 (Resilience)
0x0D	Snapshot & Recovery	通用 WAL & 快照持久化
0x0E	OpenAPI Integration	Swagger UI 与 SDK 生成
0x0F	Admin Dashboard	管理后台 + Trace ID 证据链
0x10	Web Frontend	前端外包需求文档
0x11	Deposit & Withdraw	✅ 充值与提现 (Mock Chain)
0x11-a	Real Chain Integration	✅ BTC Sentinel MVP
0x11-b	Sentinel Hardening	✅ Multi-chain & Security (ADR-005/006)
Phase V	极致优化 (Extreme Optimization)	"Metal Mode"
0x14	Extreme Optimization	架构宣言
0x14-a	Benchmark Harness	✅ 100% 比特精确对齐 (FILL phase)
0x14-b	Order Commands	✅ IOC, Move, Reduce (功能补全)
0x15	Zero-Copy	计划中
0x16	CPU Affinity	计划中
0x17	SIMD Matching	计划中

---

🏃 快速开始

# 安装 git hooks
./scripts/install-hooks.sh

# 运行 Gateway 模式 (HTTP API + 交易核心)
cargo run --release -- --gateway --port 8080

# 运行单线程流水线 (吞吐量基准测试)
cargo run --release -- --pipeline --input fixtures/test_with_cancel_highbal

# 运行多线程流水线
cargo run --release -- --pipeline-mt --input fixtures/test_with_cancel_highbal

# 对比测试 (单线程 vs 多线程)
./scripts/test_pipeline_compare.sh highbal

# 回归检查 (对比黄金基线)
./scripts/test_pipeline_compare.sh 100k

---

📑 回归测试与基线 (Regression)

本项目采用 Golden Set 基线比对策略。基线数据存储在 baseline/ 目录下，代表了系统 100% 正确的状态。

• 100% 资产一致性：多线程模式必须在 avail 和 frozen 金额上与单线程基准完全对齐。
• DB 持久化优先：多线程模式已移除本地 CSV 流水，全面采用 TDengine 进行审计。
• 基线保护：禁止随意修改基线，更新必须通过 generate_baseline.sh --force 并在确认逻辑正确后提交。

---

💾 结算持久化 (TDengine)

1. 启动 TDengine

docker run -d --name tdengine -p 6030:6030 -p 6041:6041 tdengine/tdengine:latest

2. 启用持久化配置

编辑 config/dev.yaml:

persistence:
  enabled: true
  tdengine_dsn: "taos+ws://root:taosdata@localhost:6041"

3. API 概览

公开接口 (Public):

• GET /api/v1/public/depth - 盘口深度
• GET /api/v1/public/klines - K 线数据
• GET /api/v1/public/trades - 公开交易历史
• GET /api/v1/public/assets - 资产列表

私有接口 (Private, Ed25519 签名):

• POST /api/v1/private/order - 创建订单
• POST /api/v1/private/cancel - 取消订单
• POST /api/v1/private/transfer - 内部转账
• GET /api/v1/private/balances/all - 查询余额
• WS /ws - WebSocket 实时推送

---