0x00 Project Roadmap

Vision: Build a production-grade cryptocurrency exchange from Hello World to Microsecond Latency. Current Status: Phase V (Extreme Optimization) - Order Commands parity complete.

📊 Progress Overview

This project documents the complete journey of building a 1.3M orders/sec matching engine. Below is the current status of each phase.

✅ Phase I: Core Matching Engine

Status: Complete

✅ Phase II: Productization

Status: Complete

🔶 Phase III: Resilience & Funding

Status: Complete

🔶 Phase IV: Trading Integration & Verification

Status: Pending Verification

Context: The Core Engine and Trading APIs are implemented but currently tested with Mocks. This phase bridges the gap between the Real Chain (0x11) and the Matching Engine (0x01).

⏳ Phase V: Extreme Optimization (Metal Mode)

Status: In Progress

Codename: “Metal Mode” Goal: Push Rust to the physical limits of the hardware.

🏆 Key Milestones

🎯 What You’ll Learn

1. Financial Precision - Why f64 fails and how to use fixed-point u64
2. High-Performance Data Structures - BTreeMap for O(log n) order matching
3. Lock-Free Concurrency - LMAX Disruptor-style Ring Buffer
4. Event Sourcing - WAL-based deterministic state reconstruction
5. Real-World Blockchain Integration - Handling Re-orgs, Confirmations, and UTXO management
6. Production Security - Watch-only wallets & Ed25519 authentication

Last Updated: 2025-12-31

0x01 Genesis: Basic Engine

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

This is the first version of 0xInfinity. In this stage, we have built a minimal prototype of a Central Limit Order Book (CLOB). Our goal is to intuitively demonstrate real-world trading logic using standard data structures to manage orders.

1. Visualizing the Orderbook

An Orderbook is essentially a list of orders arranged by price. We place Sells (Asks) at the top and Buys (Bids) at the bottom. The gap in the middle is called the “Spread”.

We maintain two lists in memory:

• Sells: Sorted by price Low to High (Buyers want the cheapest price).
• Buys: Sorted by price High to Low (Sellers want the most expensive price).

===========================================================
               ORDER BOOK SNAPSHOT
===========================================================

    Side   |   Price (f64)   |   Qty    |   Orders (FIFO)
-----------------------------------------------------------
    SELL   |     102.00      |   5.0    |   [Order #2]
    SELL   |     101.00      |   5.0    |   [Order #3]     ^
                                                           | Best Ask (Lowest)
-----------------------------------------------------------
             $$$  MARKET SPREAD  $$$
-----------------------------------------------------------
                                                           | Best Bid (Highest)
    BUY    |     100.00      |   10.0   |   [Order #1]     v
    BUY    |      99.00      |   10.0   |   [Order #5]

===========================================================

2. Program Output

After executing cargo run, we can observe the actual output of the engine:

--- 0xInfinity: Stage 1 (Genesis) ---

[1] Makers coming in...

[2] Taker eats liquidity...
MATCH: Buy 4 eats Sell 1 @ Price 100 (Qty: 10)
MATCH: Buy 4 eats Sell 3 @ Price 101 (Qty: 2)

[3] More makers...

--- End of Simulation ---

🇨🇳 中文

📦 代码变更: 查看 Diff

这是 0xInfinity 的第一个版本。 在这一阶段，我们构建了一个最简单的**中央限价订单簿（CLOB）**雏形。我们的目标是直观地展示现实世界的交易逻辑，使用标准的数据结构来管理订单。

1. 订单簿布局 (Visualizing the Orderbook)

订单簿本质上是一个按价格排列的列表。我们将**卖单（Sells）**放在上方，**买单（Buys）**放在下方。中间的空隙被称为“价差（Spread）”。

我们在内存中维护了两个列表：

• Sells: 按价格 从低到高 排列（买家希望买到最便宜的）。
• Buys: 按价格 从高到低 排列（卖家希望卖给最贵的）。

===========================================================
               ORDER BOOK SNAPSHOT
===========================================================

    Side   |   Price (f64)   |   Qty    |   Orders (FIFO)
-----------------------------------------------------------
    SELL   |     102.00      |   5.0    |   [Order #2]
    SELL   |     101.00      |   5.0    |   [Order #3]     ^
                                                           | Best Ask (Lowest)
-----------------------------------------------------------
             $$$  MARKET SPREAD  $$$
-----------------------------------------------------------
                                                           | Best Bid (Highest)
    BUY    |     100.00      |   10.0   |   [Order #1]     v
    BUY    |      99.00      |   10.0   |   [Order #5]

===========================================================

2. 运行结果 (Program Output)

执行 cargo run 后，我们可以看到引擎的实际运行结果：

--- 0xInfinity: Stage 1 (Genesis) ---

[1] Makers coming in...

[2] Taker eats liquidity...
MATCH: Buy 4 eats Sell 1 @ Price 100 (Qty: 10)
MATCH: Buy 4 eats Sell 3 @ Price 101 (Qty: 2)

[3] More makers...

--- End of Simulation ---

0x02: The Curse of Float

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

1. The Rookie Mistake

Experienced developers might have noticed that the price type was f64. This is problematic. In models.rs, we had this line:

#![allow(unused)]
fn main() {
pub price: f64, // The root of all evil
}

In most general-purpose applications where absolute precision is not critical, using floating-point numbers is fine. If single precision isn’t enough, double precision usually suffices. However, in the financial domain, storing monetary values as floats is considered an engineering disaster.

If you use floats to store money, it is impossible to maintain a 100% accurate ledger over time. Even with frequent reconciliation, you often end up accepting a “close enough” result.

Moreover, using floats introduces accumulation errors. Over millions of transactions, these tiny errors add up. While various rounding modes can mitigate this if done correctly, the root cause remains.

The biggest issue isn’t just the error itself (which might be acceptable within a tolerance), but the fact that you cannot fundamentally verify the correctness of the settlement, potentially hiding real bugs.

2. The Precision Trap

Run this incredibly simple code (you can run it in this project via cargo run --example the_curse_of_float):

fn main() {
    let a: f64 = 0.1;
    let b: f64 = 0.2;
    let sum = a + b;

    // You expect this to pass, right?
    if sum == 0.3 {
        println!("Math works!");
    } else {
        println!("PANIC: Math is broken! Sum is {:.20}", sum);
    }
}

The output might surprise you:

PANIC: Math is broken! Sum is 0.30000000000000004441

See that extra 0.00000000000000004441? What is that? Why does it happen?

The main issue isn’t just about floating-point precision being “insufficient,” but that computers simply cannot precisely represent certain numbers.

Computers use binary, while humans use decimal. Just as 1/3 = 0.3333... repeats infinitely in decimal, 0.1 is a repeating fraction in binary that cannot be represented exactly.

In a matching engine, if an Ask in your OrderBook is 0.3 and a user’s Bid is computed as 0.1 + 0.2, these two orders—which inherently should match—will never match due to floating-point errors.

3. Why Blockchain Hates Floats

If you’ve worked with Ethereum smart contracts, you know there are no floating-point numbers in Solidity. Many people wonder why.

There is only one reason: Blockchain cores require 100% deterministic outputs for the same input. Regardless of time, location, hardware, OS, or CPU architecture, running the same code must yield exactly the same result. Only with absolute consistency—down to the last bit—can we ensure that everyone shares the same ledger and the same “consensus.”

Specifically, while floating-point calculations follow the IEEE 754 standard, edge cases can cause minute differences across CPUs:

Node A (Intel) Result: 100.00000000000001
Node B (ARM)   Result: 100.00000000000000

Once this happens, the storage Hash differs, consensus breaks, and the chain forks.

4. The Decimal Temptation

When people realize the issue with f64, they often look for a precise decimal type, such as rust_decimal.

However, even with Decimal, different hardware, programming languages, or even compiler versions can lead to subtle differences. Achieving the 100% determinism required by blockchain is difficult.

The only thing that guarantees 100% determinism is Integer arithmetic. If integer calculations are inconsistent, it is 100% a bug.

Problems with Decimal:

• Software Emulation: Decimal is a software struct, not a hardware primitive.
• Implementation Dependency: Consistency depends on the library implementation.
• “Dialects”: If your backend uses Rust (rust_decimal), risk engine uses Python (decimal), and frontend uses JS (BigInt), subtle differences in “Rounding Mode” or “Overflow Handling” can lead to ledger discrepancies over time.

5. Need for Speed: f64 vs u64

Besides determinism, another core reason we avoid Decimal is Performance.

u64 (Native Integer):

• When executing a + b, the CPU has a dedicated ALU circuit for 64-bit integer addition.
• It completes in as little as 1 clock cycle.

Decimal (Software Struct):

• When executing addition, the CPU runs a complex piece of code: checking Scale, aligning decimals, handling overflow, and finally calculating.
• This takes hundreds to thousands of times more instruction cycles.

In most apps, CPU cycles are abundant, so this doesn’t matter. But we are writing an HFT (High-Frequency Trading) engine where every nanosecond counts.

Cache Efficiency:

• u64 takes 8 bytes.
• Decimal typically takes 16 bytes (128-bit).
• Using u64 means your CPU cache can store twice as much price data, effectively doubling your throughput.

We will discuss Cache mechanics in detail later.

Summary

Two reasons to ban floating-point numbers:

1. No 100% Determinism — Fails to meet blockchain consensus and precise reconciliation requirements.
2. Performance Issues — For HFT engines, Integer is the only choice.

Refactoring Results

We have refactored all f64 fields in models.rs to u64:

#![allow(unused)]
fn main() {
pub struct Order {
    pub id: u64,
    pub price: u64,  // Use Integer for Price
    pub qty: u64,    // Use Integer for Quantity
    pub side: Side,
}
}

Output after cargo run:

--- 0xInfinity: Stage 2 (Integer) ---

[1] Makers coming in...

[2] Taker eats liquidity...
MATCH: Buy 4 eats Sell 1 @ Price 100 (Qty: 10)
MATCH: Buy 4 eats Sell 3 @ Price 101 (Qty: 2)

[3] More makers...

--- End of Simulation ---

Now all price comparisons are precise integer comparisons, free from floating-point errors.

🇨🇳 中文

📦 代码变更: 查看 Diff

1. 新手常犯的错误 (The Rookie Mistake)

有经验的老手，应该马上看到 price 的类型是 f64，这是有问题的。因为我们在 models.rs 里有这行代码：

#![allow(unused)]
fn main() {
pub price: f64, // The root of all evil
}

在大多数不要求计算结果绝对精确的场合，使用浮点数是没问题的。如果单精度不够，那就使用双精度，一般都不会有什么问题。但是在金融领域，使用浮点数存储金额，属于工程事故。

使用浮点数存储金额，稍微长一点时间，都不可能做到账本的完全精确、分毫不差。即使通过频繁的对账校验，最后也只能接受“大差不差，差不多就行“的结果。

而且使用浮点数存储金额，会带来累积误差。在常年累月的交易后，这些微小的误差会越来越多。使用各种不同的误差舍入模式，如果做对了，可以减少累积误差。

如果说累积误差在一定范围内是可以接受的，那么误差本身一般不是问题。最大的问题是：如果不能从根本上检验结算的正确性，就可能因此而隐藏了真正的 bug。

2. 精度陷阱 (The Precision Trap)

跑一下这段极其简单的代码（你可以在本项目中运行 cargo run --example the_curse_of_float）：

fn main() {
    let a: f64 = 0.1;
    let b: f64 = 0.2;
    let sum = a + b;

    // You expect this to pass, right?
    if sum == 0.3 {
        println!("Math works!");
    } else {
        println!("PANIC: Math is broken! Sum is {:.20}", sum);
    }
}

输出结果会让人惊讶：

PANIC: Math is broken! Sum is 0.30000000000000004441

看到了吗？那个多出来的 0.00000000000000004441。这是什么鬼？为什么会这样？

主要的问题不仅仅是浮点数精度够不够的问题，而是计算机根本无法精确表示某些数字的问题。

计算机是二进制的，而人类的常用数字是十进制的。就像十进制里 1/3 = 0.3333... 永远写不完一样，在二进制里，0.1 也是一个用二进制永远无法完全精确表达的数。

在撮合引擎里，如果你的 OrderBook 里的 Ask 是 0.3，而用户的 Bid 是 0.1 + 0.2，由于浮点误差，这两个本来应该成交的单子，永远不会匹配。

3. 区块链的零容忍 (Why Blockchain Hates Floats)

如果了解过以太坊的智能合约语言就知道，在合约里面是没有任何浮点数的。很多人不知道为什么。

原因只有一个：区块链的核心是要求同样的输入必须 100% 确定的输出。无论你在什么时间、什么地方，都必须在不同的硬件、不同的操作系统、不同的 CPU 架构上，运行同一段代码，并得到完全一致的结果。只有完全一致，一个 bit 的误差都没有，才能确定全球所有人共享的都是同一个账本、同一种“比特币“。

具体而言，浮点数计算遵循 IEEE 754 标准，但在极端边缘情况下，不同的 CPU 对浮点数的处理可能会有极其微小的差异：

Node A (Intel) 算出结果：100.00000000000001
Node B (ARM) 算出结果：100.00000000000000

一旦发生这种情况，Hash 就会不同，共识就会破裂，链就会分叉。

4. Decimal 的诱惑与陷阱 (The Decimal Temptation)

有人意识到 f64 的问题时，会寻找一种精确的小数类型，比如 rust_decimal。

但即使是 Decimal，在不同的硬件、不同编程语言，甚至同一种语言的不同版本、编译器的实现上，都可能有细微的差别，都不可能做到区块链要求的 100% 确定性。

能做到 100% 确定性的，只有整数。如果全部是整数计算结果也不一致的话，可以 100% 确定是有 bug。

Decimal 的问题

Decimal (Software Struct):

• Decimal 是软件模拟的
• Decimal 的一致性依赖于库的实现
• 如果你的后端用 Rust (rust_decimal)，风控用 Python (decimal)，前端用 JS (BigInt)，不同的库对“舍入模式 (Rounding Mode)“和“溢出处理“可能有不同的“方言”
• 这种微小的差异会导致长时间之后系统对不上账

5. 性能之争: f64 vs u64 (Need for Speed)

除了 100% 确定性，我们不使用 Decimal 的另一个核心理由是：性能。

u64 (Native Integer):

• 当你执行 a + b 时，CPU 内部有专门的 ALU 电路直接处理 64 位整数加法
• 它最快只需要 1 个时钟周期 就完成了计算

Decimal (Software Struct):

• 当你执行加法时，CPU 实际上是在运行一段复杂的代码：检查 Scale、调整对齐、处理溢出、最后计算
• 这需要多 上百倍甚至几千倍 的指令周期

大多数情况下，CPU 时钟周期都过剩，因此一般应用无需过多考虑。而且大多数现代 CPU 都有浮点计算单元，也会很快。但我们要写的是 HFT 引擎，纳秒必争。

还有就是 Cache Efficiency（缓存效率）：

• u64 占 8 字节
• Decimal 通常占 16 字节 (128-bit)
• 使用 u64 意味着你的 CPU 缓存能多存一倍的价格数据，这直接意味着吞吐量翻倍

关于 Cache 的问题，后面再详细讨论。

Summary

不能使用浮点数的两个理由：

1. 不能保证 100% 确定性 — 无法满足区块链共识和精确对账的要求
2. Decimal 有性能问题 — 对于 HFT 引擎来说，整数是唯一的选择

重构后的运行结果

我们已经把 models.rs 中的 f64 全部重构为 u64：

#![allow(unused)]
fn main() {
pub struct Order {
    pub id: u64,
    pub price: u64,  // 使用整数表示价格
    pub qty: u64,    // 使用整数表示数量
    pub side: Side,
}
}

运行 cargo run 后的输出：

--- 0xInfinity: Stage 2 (Integer) ---

[1] Makers coming in...

[2] Taker eats liquidity...
MATCH: Buy 4 eats Sell 1 @ Price 100 (Qty: 10)
MATCH: Buy 4 eats Sell 3 @ Price 101 (Qty: 2)

[3] More makers...

--- End of Simulation ---

现在所有的价格比较都是精确的整数比较，不再有浮点数误差的问题。

0x03: Decimal World

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

In the previous chapter, we refactored all f64 to u64, solving the floating-point precision issues. But this introduced a new problem: Clients use decimals, while we use integers internally. How do we convert between them?

1. The Decimal Conversion Problem

When a user places an order, the input price might be "100.50" and quantity "10.5". However, our engine uses u64 integers:

#![allow(unused)]
fn main() {
pub struct Order {
    pub id: u64,
    pub price: u64,   // Integer representation
    pub qty: u64,     // Integer representation
    pub side: Side,
}
}

Core Question: How to perform lossless conversion between decimal strings and u64?

The answer is the Fixed Decimal scheme:

#![allow(unused)]
fn main() {
/// Convert decimal string to u64
/// e.g., "100.50" with 2 decimals -> 10050
fn parse_decimal(s: &str, decimals: u32) -> u64 {
    let multiplier = 10u64.pow(decimals);
    // ... Parsing Logic
}

/// Convert u64 back to decimal string for display
/// e.g., 10050 with 2 decimals -> "100.50"
fn format_decimal(value: u64, decimals: u32) -> String {
    let multiplier = 10u64.pow(decimals);
    let int_part = value / multiplier;
    let dec_part = value % multiplier;
    format!("{}.{:0>width$}", int_part, dec_part, width = decimals as usize)
}
}

2. The u64 Max Value (Range Analysis)

The maximum value of u64 is:

u64::MAX = 18,446,744,073,709,551,615

If we use 8 decimal places (similar to Bitcoin’s satoshi), the maximum representable value is:

184,467,440,737.09551615

This means:

• For Price: We can represent up to ~184 Billion. (If Bitcoin hits this price, we’ll upgrade…)
• For Quantity: It can hold the entire total supply of BTC (21 million).

Decimals Configuration for Different Assets

Different blockchain assets have different native precisions:

The Question: ETH natively uses 18 decimals. Will we lose precision if we use only 8?

The answer is: It is sufficient for an Exchange. Because:

• With 8 decimals, the smallest supported unit is 0.00000001 ETH.
• There’s no real need to trade 0.000000000000000001 ETH (value ≈ $0.000000000000003).

So we can choose a reasonable internal precision, not necessarily identical to the native chain.

Thus, we need a SymbolManager to manage:

• Internal precision (decimals) for each asset.
• User display precision (display_decimals).
• Price precision configuration for trading pairs.
• Conversion between on-chain and internal precision during Deposit/Withdrawal.

ETH Decimals Analysis: 8 vs 12 bits

Let’s analyze the maximum ETH amount representable by u64 under different decimal configs:

ETH Total Supply ≈ 120 Million ETH

Why we chose 8 decimals for ETH?

• 0.00000001 ETH ≈ $0.00000003, far below any meaningful trade size.
• Max capacity 184 Billion ETH > Total Supply (120M).
• Just convert precision during Deposit/Withdrawal.

Configuration Example:

#![allow(unused)]
fn main() {
// BTC: 8 decimals (Same as satoshi)
manager.add_asset(1, 8, 3, "BTC");

// USDT: 8 decimals (Native is 6, we align to 8 internally)
manager.add_asset(2, 8, 2, "USDT");

// ETH: 8 decimals (Safe range, sufficient precision)
manager.add_asset(3, 8, 4, "ETH");
}

3. Symbol Configuration

Different trading pairs have different precision requirements:

We use SymbolManager to manage these configs:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct SymbolInfo {
    pub symbol: String,
    pub symbol_id: u32,
    pub base_asset_id: u32,
    pub quote_asset_id: u32,
    pub price_decimal: u32,         // Decimals for Price
    pub price_display_decimal: u32, // Display decimals for Price
}

#[derive(Debug, Clone)]
pub struct AssetInfo {
    pub asset_id: u32,
    pub decimals: u32,         // Internal precision (usually 8)
    pub display_decimals: u32, // Max decimals for input/display
    pub name: String,
}
}

4. decimals vs display_decimals

Distinguishing these two concepts is crucial:

decimals (Internal Precision)

• Determines the multiplier for u64.
• Usually 8 (like satoshi).
• This is internal storage format, invisible to users.

display_decimals (Display Precision)

• Determines how many decimal places users can see/input.
• E.g., BTC displays 3 digits: 0.001 BTC.
• USDT displays 2 digits: 100.00 USDT.

Why separate them?

1. UX: Users don’t need to see 8 decimal places.
2. Validation: Limit user input precision.
3. Cleanliness: Avoid trailing zeros.

5. Program Output

Output after cargo run:

--- 0xInfinity: Stage 3 (Decimal World) ---
Symbol: BTC_USDT (ID: 0)
Price Decimals: 2, Qty Display Decimals: 3

[1] Makers coming in...
    Order 1: Sell 10.000 BTC @ $100.00
    Order 2: Sell 5.000 BTC @ $102.00
    Order 3: Sell 5.000 BTC @ $101.00

[2] Taker eats liquidity...
    Order 4: Buy 12.000 BTC @ $101.50
MATCH: Buy 4 eats Sell 1 @ Price 10000 (Qty: 10000)
MATCH: Buy 4 eats Sell 3 @ Price 10100 (Qty: 2000)

[3] More makers...
    Order 5: Buy 10.000 BTC @ $99.00

--- End of Simulation ---

--- u64 Range Demo ---
u64::MAX = 18446744073709551615
With 8 decimals, max representable value = 184467440737.09551615

Observation:

• User input is decimal string "100.00".
• Internal storage is integer 10000.
• Display converts back to "100.00".

This is the core of Decimal World: Seamless lossless conversion between Decimal Strings and u64 Integers.

📖 True Story: JavaScript Number Overflow

During development, we encountered a bizarre bug:

Symptom: The backend returned raw ETH amount (in wei). During testing with small amounts (0.00x ETH), frontend worked fine. But once the amount hit ~0.009 ETH, the number started losing precision and became incorrect!

Root Cause: JavaScript’s Number type uses IEEE 754 double-precision floats. The maximum safe integer is 2^53 - 1:

> console.log(Number.MAX_SAFE_INTEGER);
9007199254740991                          // ~ 9 * 10^15

// 1 ETH = 10^18 wei
> const oneEthInWei = 1000000000000000000;

// The Issue: When wei amount exceeds MAX_SAFE_INTEGER
> const smallAmount = 1000000000000000;     // 0.001 ETH = 10^15 wei ✅ Safe
> const dangerAmount = 9007199254740992;    // ~ 0.009 ETH ⚠️ Just exceeded limit!
> const tenEthInWei = 10000000000000000000; // 10 ETH = 10^19 wei ❌ Overflow!

// Verify Precision Loss: Adding 1 has no effect!
> console.log(tenEthInWei + 1);
10000000000000000000                       // No +1!
> console.log(tenEthInWei === tenEthInWei + 1);
true                                       // 😱 WHAT?!

Why ~0.009 ETH?

> console.log(Number.MAX_SAFE_INTEGER / 1e18);
0.009007199254740991                       // 0.009 ETH is the safety limit!

Solution:

// ✅ Solution 1: Backend returns String, Frontend uses BigInt
> const weiString = "10000000000000000000";  // String from backend
> const weiBigInt = BigInt(weiString);       // Convert to BigInt
> console.log((weiBigInt + 1n).toString());
10000000000000000001                       // ✅ Correct!

// ✅ Solution 2: Use libraries like ethers.js
// import { formatEther, parseEther } from 'ethers';
// const eth = formatEther(weiBigInt);  // "10.0"

Summary

This chapter solved:

1. ✅ Decimal Conversion: parse_decimal() and format_decimal() for bidirectional lossless conversion.
2. ✅ u64 Range: Max value 184 Billion (at 8 decimals), sufficient for any financial scenario.
3. ✅ Symbol Config: SymbolManager handles precision settings per pair.
4. ✅ Precision Definitions: Distinct decimals (internal) vs display_decimals (UI).

🇨🇳 中文

📦 代码变更: 查看 Diff

在上一章中，我们将所有的 f64 重构为 u64，解决了浮点数的精度问题。但这引入了一个新的问题：客户端使用的是十进制，而我们内部使用的是整数，如何进行转换？

1. 十进制转换问题 (The Decimal Conversion Problem)

用户在下单时，输入的价格是 "100.50"，数量是 "10.5"。但我们的引擎内部使用的是 u64 整数：

#![allow(unused)]
fn main() {
pub struct Order {
    pub id: u64,
    pub price: u64,   // 整数表示
    pub qty: u64,     // 整数表示
    pub side: Side,
}
}

核心问题：如何在十进制字符串和 u64 之间进行无损转换？

答案是使用 固定小数位数（Fixed Decimal） 方案：

#![allow(unused)]
fn main() {
/// 将十进制字符串转换为 u64
/// e.g., "100.50" with 2 decimals -> 10050
fn parse_decimal(s: &str, decimals: u32) -> u64 {
    let multiplier = 10u64.pow(decimals);
    // ... 解析逻辑
}

/// 将 u64 转换回十进制字符串用于显示
/// e.g., 10050 with 2 decimals -> "100.50"
fn format_decimal(value: u64, decimals: u32) -> String {
    let multiplier = 10u64.pow(decimals);
    let int_part = value / multiplier;
    let dec_part = value % multiplier;
    format!("{}.{:0>width$}", int_part, dec_part, width = decimals as usize)
}
}

2. u64 的最大值问题 (u64 Max Value)

u64 的最大值是：

u64::MAX = 18,446,744,073,709,551,615

如果我们使用 8 位小数（类似比特币的 satoshi），可以表示的最大值是：

184,467,440,737.09551615

这意味着：

• 对于价格：可以表示到约 1844 亿，某天比特币需要这么大价格表示的时候再升级吧….
• 对于数量：可以装进去全部比特币BTC总量了（总供应量 2100 万）

不同资产的 Decimals 配置

不同的区块链资产有不同的原生精度：

问题来了：但是 ETH 原生是 18 位小数，但我们只用 8 位会丢失精度吗？

答案是：在交易所场景下足够使用。因为：

• 定义8位的时候交易所交易的最小支持精度是 0.00000001 ETH, 足够了
• 没有必要支持交易 0.000000000000000001 ETH（价值约 $0.000000000000003）

所以我们可以选择一个合理的内部精度，不一定要和原生链一致。

因此，我们需要一个资产和币对的基本配置管理器（SymbolManager），用于：

• 管理每个资产的内部精度（decimals）
• 管理用户可见的显示精度（display_decimals）
• 管理交易对的价格精度配置
• 在入金/提币时进行链上精度和内部精度的转换

ETH Decimals 分析：8 到 12 位的选择

让我们分析不同 decimals 配置下，u64 能表示的最大 ETH 数量：

ETH 当前总供应量约 1.2 亿 ETH

分析：

• 8 位小数：最大 1844 亿 ETH，余量巨大，精度 0.00000001 ETH 对交易所足够
• 10 位小数：最大 18 亿 ETH，精度更高
• 12 位小数：最大 1800 万 ETH，精度最高，⚠️ 但小于总供应量

为什么 ETH 选择 8 位小数？

虽然 ETH 原生是 18 位小数（wei），但对于交易所来说：

• 0.00000001 ETH ≈ $0.00000003，远小于任何有意义的交易金额
• 最大可表示 1844 亿 ETH，远超总供应量（1.2 亿）
• 入金/提币时进行精度转换即可

配置示例：

#![allow(unused)]
fn main() {
// BTC: 8 位小数（和链上 satoshi 一致）
manager.add_asset(1, 8, 3, "BTC");

// USDT: 8 位小数
manager.add_asset(2, 8, 2, "USDT");

// ETH: 8 位小数（精度足够，范围安全）
manager.add_asset(3, 8, 4, "ETH");
}

3. 交易对配置 (Symbol Configuration)

不同的交易对可能有不同的精度要求：

我们使用 SymbolManager 来管理这些配置：

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct SymbolInfo {
    pub symbol: String,
    pub symbol_id: u32,
    pub base_asset_id: u32,
    pub quote_asset_id: u32,
    pub price_decimal: u32,         // 价格的小数位数
    pub price_display_decimal: u32, // 价格显示的小数位数
}

#[derive(Debug, Clone)]
pub struct AssetInfo {
    pub asset_id: u32,
    pub decimals: u32,         // 内部精度（通常是 8）
    pub display_decimals: u32, // 显示/输入的最大小数位数
    pub name: String,
}
}

4. decimals vs display_decimals

这里有两个概念需要区分：

decimals (内部精度)

• 决定了 u64 乘以多少
• 通常是 8（类似 satoshi）
• 这是内部存储精度，用户看不到

display_decimals (显示精度)

• 决定了用户可以输入/看到多少位小数
• 例如 BTC 显示 3 位：0.001 BTC
• USDT 显示 2 位：100.00 USDT

为什么要分开？

1. 用户体验：用户不需要看到 8 位小数的精度
2. 输入验证：可以限制用户输入的小数位数
3. 显示简洁：避免显示过多无意义的零

5. 运行结果

运行 cargo run 后的输出：

--- 0xInfinity: Stage 3 (Decimal World) ---
Symbol: BTC_USDT (ID: 0)
Price Decimals: 2, Qty Display Decimals: 3

[1] Makers coming in...
    Order 1: Sell 10.000 BTC @ $100.00
    Order 2: Sell 5.000 BTC @ $102.00
    Order 3: Sell 5.000 BTC @ $101.00

[2] Taker eats liquidity...
    Order 4: Buy 12.000 BTC @ $101.50
MATCH: Buy 4 eats Sell 1 @ Price 10000 (Qty: 10000)
MATCH: Buy 4 eats Sell 3 @ Price 10100 (Qty: 2000)

[3] More makers...
    Order 5: Buy 10.000 BTC @ $99.00

--- End of Simulation ---

--- u64 Range Demo ---
u64::MAX = 18446744073709551615
With 8 decimals, max representable value = 184467440737.09551615

可以看到：

• 用户输入的是十进制字符串 "100.00"
• 内部存储为整数 10000
• 显示时又转换回 "100.00"

这就是 Decimal World 的核心：在十进制和 u64 整数之间无缝转换。

📖 真实踩坑故事：JavaScript Number 溢出

在我们的开发过程中，曾经遇到过一个非常诡异的 bug：

现象：后端返回给前端的是原始 ETH 数量（单位 wei）。在开发测试阶段，因为测试金额非常小（0.00x 个 ETH 级别），前端都能正常显示和处理。但上线后只要金额稍大一点（实际上超过约 0.009 ETH），数字就开始出现精度问题，变成一个不正确的数值！

根本原因：JavaScript 的 Number 类型使用 IEEE 754 双精度浮点数，最大安全整数是 2^53 - 1：

> console.log(Number.MAX_SAFE_INTEGER);
9007199254740991                          // 约 9 * 10^15

// 1 ETH = 10^18 wei
> const oneEthInWei = 1000000000000000000;

// 问题演示：当 wei 数量超过 MAX_SAFE_INTEGER 时
> const smallAmount = 1000000000000000;     // 0.001 ETH = 10^15 wei ✅ 安全
> const dangerAmount = 9007199254740992;    // 约 0.009 ETH ⚠️ 刚好超过安全范围
> const tenEthInWei = 10000000000000000000; // 10 ETH = 10^19 wei ❌ 溢出！

// 验证精度丢失：加 1 后值不变！
> console.log(tenEthInWei + 1);
10000000000000000000                       // 没有 +1!

> console.log(tenEthInWei + 2);
10000000000000000000                       // 还是一样!

> console.log(tenEthInWei + 1000);
10000000000000000000                       // 加 1000 也还是一样!

> console.log(tenEthInWei === tenEthInWei + 1);
true                                       // 😱 见鬼了！

为什么超过约 0.009 个 ETH 就出问题？

> console.log(Number.MAX_SAFE_INTEGER / 1e18);
0.009007199254740991                       // 约 0.009 ETH 就是安全边界！

// 虽然输出看起来正确，但实际上精度已经丢失，验证方法：
> const nineEth = 9n * 10n ** 18n;         // BigInt 表示 9 ETH
> const nineEthNum = Number(nineEth);      // 转为 Number
> console.log(nineEthNum);
9000000000000000000                        // 看起来正确...

> console.log(nineEthNum + 1);
9000000000000000000                        // 但是 +1 没有效果！

> console.log(nineEthNum === nineEthNum + 1);
true                                       // 证明精度已丢失

正确的处理方案：

// ✅ 方案 1: 后端返回字符串，前端用 BigInt 处理
> const weiString = "10000000000000000000";  // 后端返回字符串
> const weiBigInt = BigInt(weiString);       // 转为 BigInt
> console.log(weiBigInt.toString());
10000000000000000000                       // ✅ 精确！

// BigInt 可以正确进行算术运算
> console.log((weiBigInt + 1n).toString());
10000000000000000001                       // ✅ +1 正确！

// ✅ 方案 2: 使用专业库如 ethers.js
// import { formatEther, parseEther } from 'ethers';
// const eth = formatEther(weiBigInt);  // "10.0"

Summary

本章解决了以下问题：

1. ✅ 十进制转换：parse_decimal() 和 format_decimal() 实现双向无损转换
2. ✅ u64 范围：最大值 1844 亿（8 位小数），足够应对任何金融场景
3. ✅ 交易对配置：SymbolManager 管理每个交易对的精度设置
4. ✅ 两种精度定义：decimals（内部）vs display_decimals（显示）

0x04 OrderBook Refactoring (BTreeMap)

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

In the previous chapters, we completed the transition from Float to Integer and established a precision configuration system. However, our OrderBook data structure was still a “toy” implementation—re-sorting on every match! This chapter upgrades it to a truly production-ready data structure.

1. The Problem with the Naive Implementation

Let’s review the original engine.rs:

#![allow(unused)]
fn main() {
pub struct OrderBook {
    bids: Vec<PriceLevel>,  // Was 'buys'
    asks: Vec<PriceLevel>,  // Was 'sells'
}
}

💡 Naming Convention: We renamed buys/sells to bids/asks. These are standard options industry terms:

• Bid: Price buyers are willing to pay.
• Ask: Price sellers are demanding.

Using professional terminology aligns the code with industry docs and APIs.

#![allow(unused)]
fn main() {
fn match_buy(&mut self, buy_order: &mut Order) {
    // Problem 1: Re-sort every time! O(n log n)
    self.asks.sort_by_key(|l| l.price);
    
    for level in self.asks.iter_mut() {
        // ...matching logic...
    }
    
    // Problem 2: Removing empty levels shifts the whole array! O(n)
    self.asks.retain(|l| !l.orders.is_empty());
}

fn rest_order(&mut self, order: Order) {
    // Problem 3: Finding price level is a linear scan! O(n)
    let level = self.asks.iter_mut().find(|l| l.price == order.price);
    // ...
}
}

Time Complexity Analysis

In an active exchange with tens of thousands of orders per second, O(n) operations quickly become a performance bottleneck.

2. The BTreeMap Solution

Rust’s standard library provides BTreeMap, a Self-Balancing Binary Search Tree:

#![allow(unused)]
fn main() {
use std::collections::BTreeMap;

pub struct OrderBook {
    /// Asks: price -> orders (Ascending, Lowest Price = Best Ask)
    asks: BTreeMap<u64, VecDeque<Order>>,
    
    /// Bids: (u64::MAX - price) -> orders (Trick: Highest Price First)
    bids: BTreeMap<u64, VecDeque<Order>>,
}
}

Key Trick: Key Design for Bids

BTreeMap sorts keys in ascending order by default. This works perfectly for Asks (lowest price first). But for Bids, we need highest price first.

Solution: Use u64::MAX - price as the key.

#![allow(unused)]
fn main() {
// Insert Bid
let key = u64::MAX - order.price;
self.bids.entry(key).or_insert_with(VecDeque::new).push_back(order);

// Read Real Price
let price = u64::MAX - key;
}

Thus, Price 100 becomes Key u64::MAX - 100, and Price 99 becomes u64::MAX - 99. Since (u64::MAX - 100) < (u64::MAX - 99), Price 100 comes before Price 99!

Why not Reverse or Custom Comparator?

You might ask: Why not BTreeMap<Reverse<u64>, ...>?

Comparison:

Key Advantages:

• Simple: Just two lines of code.
• Zero Overhead: Subtraction is a single-cycle CPU instruction.
• Type Safe: Key remains u64.
• No Overflow: Price is always < u64::MAX.

Time Complexity Comparison

*Note: Cancelling requires linear scan in VecDeque (O(n)). O(1) cancel requires an auxiliary HashMap index. **Note: BTreeMap::first_key_value() is amortized O(1).

3. New Data Models

Order

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct Order {
    pub id: u64,
    pub price: u64,          // Internal Integer Price
    pub qty: u64,            // Original Qty
    pub filled_qty: u64,     // Filled Qty
    pub side: Side,
    pub order_type: OrderType,
    pub status: OrderStatus,
}
}

Trade

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct Trade {
    pub id: u64,
    pub buyer_order_id: u64,
    pub seller_order_id: u64,
    pub price: u64,
    pub qty: u64,
}
}

OrderResult

#![allow(unused)]
fn main() {
pub struct OrderResult {
    pub order: Order,       // Updated Order
    pub trades: Vec<Trade>, // Generated Trades
}
}

4. Core API

#![allow(unused)]
fn main() {
impl OrderBook {
    /// Add order, return match result
    pub fn add_order(&mut self, order: Order) -> OrderResult;
    
    /// Cancel order
    pub fn cancel_order(&mut self, order_id: u64, price: u64, side: Side) -> bool;
    
    /// Get Best Bid
    pub fn best_bid(&self) -> Option<u64>;
    
    /// Get Best Ask
    pub fn best_ask(&self) -> Option<u64>;
    
    /// Get Spread
    pub fn spread(&self) -> Option<u64>;
}
}

5. Execution Results

=== 0xInfinity: Stage 4 (BTree OrderBook) ===
Symbol: BTC_USDT (ID: 0)
Price Decimals: 2, Qty Display Decimals: 3

[1] Makers coming in...
    Order 1: Sell 10.000 BTC @ $100.00 -> New
    Order 2: Sell 5.000 BTC @ $102.00 -> New
    Order 3: Sell 5.000 BTC @ $101.00 -> New

    Book State: Best Bid=None, Best Ask=Some("100.00"), Spread=None

[2] Taker eats liquidity...
    Order 4: Buy 12.000 BTC @ $101.50
    Trades:
      - Trade #1: 10.000 @ $100.00
      - Trade #2: 2.000 @ $101.00
    Order Status: Filled, Filled: 12.000/12.000

    Book State: Best Bid=None, Best Ask=Some("101.00")

[3] More makers...
    Order 5: Buy 10.000 BTC @ $99.00 -> New

    Final Book State: Best Bid=Some("99.00"), Best Ask=Some("101.00"), Spread=Some("2.00")

=== End of Simulation ===

Observations:

• Orders matched correctly by price priority (First $100, then $101).
• Every trade recorded in Trades.
• Real-time tracking of Best Bid/Ask and Spread.

6. Unit Tests

We added 8 unit tests covering core scenarios:

$ cargo test

running 8 tests
test engine::tests::test_add_resting_order ... ok
test engine::tests::test_cancel_order ... ok
test engine::tests::test_fifo_at_same_price ... ok
test engine::tests::test_full_match ... ok
test engine::tests::test_multiple_trades_single_order ... ok
test engine::tests::test_partial_match ... ok
test engine::tests::test_price_priority ... ok
test engine::tests::test_spread ... ok

test result: ok. 8 passed; 0 failed

7. Is BTreeMap Enough?

For an exchange not chasing extreme performance, BTreeMap is perfectly adequate:

If you want to build a Ferrari-level matching engine (nanosecond latency, millions of TPS), you need:

• Lock-free data structures
• Memory pools (avoid heap allocation)
• CPU Cache optimization
• FPGA acceleration

But that’s for later. For now, we have a Correct and Efficient baseline implementation.

Summary

This chapter accomplished:

1. ✅ Analyzed Problem: O(n) bottleneck in Vec implementation.
2. ✅ Refactored to BTreeMap: O(log n) insert/search/delete.
3. ✅ Defined Types: Standard Order/Trade/OrderResult models.
4. ✅ Refined API: best_bid/ask, spread, cancel_order.
5. ✅ Added Tests: 8 tests covering core logic.

🇨🇳 中文

📦 代码变更: 查看 Diff

在前三章中，我们完成了从浮点数到整数的转换，并建立了精度配置系统。但我们的 OrderBook 数据结构还是一个“玩具“实现——每次撮合都需要重新排序！本章我们将把它升级为一个真正生产可用的数据结构。

1. 原有实现的问题

让我们回顾一下原来的 engine.rs：

#![allow(unused)]
fn main() {
pub struct OrderBook {
    bids: Vec<PriceLevel>,  // 原来叫 buys
    asks: Vec<PriceLevel>,  // 原来叫 sells
}
}

💡 命名规范：我们把 buys/sells 改名为 bids/asks。这是金融行业的标准术语：

• Bid（买盘）：买方愿意出的价格
• Ask（卖盘）：卖方要求的价格

使用专业术语可以让代码更易于与行业文档、API 对接。

#![allow(unused)]
fn main() {
fn match_buy(&mut self, buy_order: &mut Order) {
    // 问题 1: 每次都要重新排序！O(n log n)
    self.asks.sort_by_key(|l| l.price);
    
    for level in self.asks.iter_mut() {
        // ...matching logic...
    }
    
    // 问题 2: 删除空档位需要移动整个数组！O(n)
    self.asks.retain(|l| !l.orders.is_empty());
}

fn rest_order(&mut self, order: Order) {
    // 问题 3: 查找价格档位是线性扫描！O(n)
    let level = self.asks.iter_mut().find(|l| l.price == order.price);
    // ...
}
}

时间复杂度分析

在一个活跃的交易所，每秒可能有数万笔订单。如果每笔订单都要 O(n) 操作，这里很快就会成为性能瓶颈。

2. BTreeMap 解决方案

Rust 标准库提供了 BTreeMap，它是一个自平衡二叉搜索树：

#![allow(unused)]
fn main() {
use std::collections::BTreeMap;

pub struct OrderBook {
    /// 卖单: price -> orders (按价格升序，最低价 = 最优卖价)
    asks: BTreeMap<u64, VecDeque<Order>>,
    
    /// 买单: (u64::MAX - price) -> orders (技巧：让最高价排在前面)
    bids: BTreeMap<u64, VecDeque<Order>>,
}
}

关键技巧：买单的 Key 设计

BTreeMap 默认按 key 升序排列。对于卖单，这正好是我们想要的（最低价优先）。但对于买单，我们需要最高价优先。

解决方案：使用 u64::MAX - price 作为 key：

#![allow(unused)]
fn main() {
// 插入买单
let key = u64::MAX - order.price;
self.bids.entry(key).or_insert_with(VecDeque::new).push_back(order);

// 读取真实价格
let price = u64::MAX - key;
}

这样，价格 100 对应 key u64::MAX - 100，价格 99 对应 key u64::MAX - 99。由于 (u64::MAX - 100) < (u64::MAX - 99)，价格 100 会排在价格 99 前面！

为什么不用 Reverse 或自定义比较器？

你可能会问：为什么不用 BTreeMap<Reverse<u64>, ...> 或者自定义比较器？

方案对比：

关键优势：

• 简单：只需要两行代码（插入时 u64::MAX - price，读取时再减回来）
• 零开销：减法操作在 CPU 上是单周期指令
• 类型安全：key 仍然是 u64，不需要额外的 wrapper 类型
• 无溢出风险：价格永远小于 u64::MAX，减法不会溢出

时间复杂度对比

*注: 取消订单需要在 VecDeque 中线性查找订单 ID，这是 O(n)。如果需要 O(1) 取消，需要额外的 HashMap 索引。

**注: BTreeMap 的 first_key_value() 是 O(1) 摊销复杂度。

3. 新的数据模型

Order（订单）

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct Order {
    pub id: u64,
    pub price: u64,          // 价格（内部单位）
    pub qty: u64,            // 原始数量
    pub filled_qty: u64,     // 已成交数量
    pub side: Side,
    pub order_type: OrderType,
    pub status: OrderStatus,
}
}

Trade（成交记录）

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct Trade {
    pub id: u64,
    pub buyer_order_id: u64,
    pub seller_order_id: u64,
    pub price: u64,
    pub qty: u64,
}
}

OrderResult（下单结果）

#![allow(unused)]
fn main() {
pub struct OrderResult {
    pub order: Order,      // 更新后的订单
    pub trades: Vec<Trade>, // 产生的成交
}
}

4. 核心 API

#![allow(unused)]
fn main() {
impl OrderBook {
    /// 添加订单，返回成交结果
    pub fn add_order(&mut self, order: Order) -> OrderResult;
    
    /// 取消订单
    pub fn cancel_order(&mut self, order_id: u64, price: u64, side: Side) -> bool;
    
    /// 获取最优买价
    pub fn best_bid(&self) -> Option<u64>;
    
    /// 获取最优卖价
    pub fn best_ask(&self) -> Option<u64>;
    
    /// 获取买卖价差
    pub fn spread(&self) -> Option<u64>;
}
}

5. 运行结果

=== 0xInfinity: Stage 4 (BTree OrderBook) ===
Symbol: BTC_USDT (ID: 0)
Price Decimals: 2, Qty Display Decimals: 3

[1] Makers coming in...
    Order 1: Sell 10.000 BTC @ $100.00 -> New
    Order 2: Sell 5.000 BTC @ $102.00 -> New
    Order 3: Sell 5.000 BTC @ $101.00 -> New

    Book State: Best Bid=None, Best Ask=Some("100.00"), Spread=None

[2] Taker eats liquidity...
    Order 4: Buy 12.000 BTC @ $101.50
    Trades:
      - Trade #1: 10.000 @ $100.00
      - Trade #2: 2.000 @ $101.00
    Order Status: Filled, Filled: 12.000/12.000

    Book State: Best Bid=None, Best Ask=Some("101.00")

[3] More makers...
    Order 5: Buy 10.000 BTC @ $99.00 -> New

    Final Book State: Best Bid=Some("99.00"), Best Ask=Some("101.00"), Spread=Some("2.00")

=== End of Simulation ===

可以看到：

• 订单按价格优先级正确匹配（先 $100，再 $101）
• 每笔成交都记录在 Trade 中
• 实时追踪 Best Bid/Ask 和 Spread

6. 单元测试

我们添加了 8 个单元测试来验证核心功能：

$ cargo test

running 8 tests
test engine::tests::test_add_resting_order ... ok
test engine::tests::test_cancel_order ... ok
test engine::tests::test_fifo_at_same_price ... ok
test engine::tests::test_full_match ... ok
test engine::tests::test_multiple_trades_single_order ... ok
test engine::tests::test_partial_match ... ok
test engine::tests::test_price_priority ... ok
test engine::tests::test_spread ... ok

test result: ok. 8 passed; 0 failed

覆盖的场景包括：

• ✅ 订单挂单（无匹配）
• ✅ 完全成交
• ✅ 部分成交
• ✅ 价格优先级（Price Priority）
• ✅ 同价格 FIFO
• ✅ 取消订单
• ✅ 价差计算
• ✅ 一个大单吃掉多个小单

7. BTreeMap 够用吗？

对于一个不追求极致性能的交易所，BTreeMap 完全够用：

如果你要打造一个法拉利级别的撮合引擎（纳秒级延迟、每秒百万单），需要考虑：

• 无锁数据结构
• 内存池（避免动态分配）
• CPU Cache 优化
• FPGA 硬件加速

但那是后话了。现在，我们有了一个正确且高效的基础实现。

Summary

本章完成了以下工作：

1. ✅ 分析原有问题：Vec 实现的 O(n) 复杂度瓶颈
2. ✅ 重构为 BTreeMap：O(log n) 的插入、查找、删除
3. ✅ 定义规范类型：Order、Trade、OrderResult
4. ✅ 完善 API：best_bid/ask、spread、cancel_order
5. ✅ 添加单元测试：8 个测试覆盖核心场景

0x05 User Account & Balance Management

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

In previous chapters, our matching engine could match orders correctly. But there’s a key question: User Funds? In a real exchange, users must have sufficient funds before placing an order, and funds must be transferred upon matching.

This chapter implements the user account system, including:

• Balance Management (Avail / Frozen)
• Pre-trade Fund Validation
• Post-trade Settlement

1. Dual State of Balance: Avail vs Frozen

In an exchange, a balance has two states:

Why do we need Frozen?

Suppose Alice has 10 BTC and she places two sell orders:

• Order A: Sell 8 BTC
• Order B: Sell 5 BTC

Without a freeze mechanism, these two orders require 13 BTC, but Alice only has 10! This is the Over-Selling problem.

Correct Flow:

1. Alice has 10 BTC (avail=10, frozen=0)
2. Place Order A (8 BTC) → freeze 8 BTC → (avail=2, frozen=8) ✅
3. Place Order B (5 BTC) → try freeze 5 BTC → Fail! avail only 2 ❌

2. Balance Structure

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Default)]
pub struct Balance {
    pub avail: u64,  // Available Balance
    pub frozen: u64, // Frozen Balance
}

impl Balance {
    /// Deposit (Increase avail)
    /// Returns false on overflow - Financial systems must detect this!
    pub fn deposit(&mut self, amount: u64) -> bool {
        match self.avail.checked_add(amount) {
            Some(new_avail) => {
                self.avail = new_avail;
                true
            }
            None => false, // Overflow! Alert and investigate.
        }
    }
}

Why checked_add?

Method	Overflow Behavior (250u8 + 10u8)	Use Case
+ (Std)	Panic (Debug) or Wrap (Release)	General logic, overflow is bug
wrapping_add	4 (Wrap)	Hashing, Graphics
saturating_add	255 (Cap)	Quotas, Token buckets
checked_add	None	✅ Finance, Overflow must error!

⚠️ In financial systems, “too much money causing overflow” is a severe bug. It must return an error for handling, not silently wrap or saturate.

#![allow(unused)]
fn main() {
    /// Freeze (avail → frozen)
    pub fn freeze(&mut self, amount: u64) -> bool {
        if self.avail >= amount {
            self.avail -= amount;
            self.frozen += amount;
            true
        } else {
            false
        }
    }

    /// Unfreeze (frozen → avail), for cancellations
    pub fn unfreeze(&mut self, amount: u64) -> bool {
        if self.frozen >= amount {
            self.frozen -= amount;
            self.avail += amount;
            true
        } else {
            false
        }
    }

    /// Consume Frozen (Fund leaves account after match)
    pub fn consume_frozen(&mut self, amount: u64) -> bool {
        if self.frozen >= amount {
            self.frozen -= amount;
            true
        } else {
            false
        }
    }

    /// Receive Funds (Fund enters account after match)
    pub fn receive(&mut self, amount: u64) {
        self.avail = self.avail.checked_add(amount);
    }
}
}

3. User Account Structure

Each user holds balances for multiple assets:

#![allow(unused)]
fn main() {
/// Use FxHashMap for O(1) asset lookup
/// FxHashMap is faster for integer keys
pub struct UserAccount {
    pub user_id: u64,
    balances: FxHashMap<u32, Balance>, // asset_id -> Balance
}

impl UserAccount {
    pub fn deposit(&mut self, asset_id: u32, amount: u64) {
        self.get_balance_mut(asset_id).deposit(amount);
    }

    pub fn avail(&self, asset_id: u32) -> u64 {
        self.balances.get(&asset_id).map(|b| b.avail).unwrap_or(0)
    }

    pub fn frozen(&self, asset_id: u32) -> u64 {
        self.balances.get(&asset_id).map(|b| b.frozen).unwrap_or(0)
    }
}
}

4. Order Placing: Freezing Funds

When placing an order, we freeze specific assets based on order side:

Using SymbolManager for Precision

Each pair has its own precision config:

#![allow(unused)]
fn main() {
let symbol_info = manager.get_symbol_info("BTC_USDT").unwrap();
let price_decimal = symbol_info.price_decimal;  // 2
let base_asset = manager.assets.get(&symbol_info.base_asset_id).unwrap();
let qty_decimal = base_asset.decimals;  // 8
let qty_unit = 10u64.pow(qty_decimal);  // 100_000_000

// price = 100 USDT (Internal: 100 * price_unit)
// qty = 10 BTC (Internal: 10 * qty_unit)
// cost = price * qty / qty_unit (Prevent overflow)
let cost = price * qty / qty_unit;

if accounts.freeze(user_id, USDT, cost) {
    let result = book.add_order(Order::new(id, user_id, price, qty, Side::Buy));
} else {
    println!("REJECTED: Insufficient balance");
}

// Sell Order: Freeze BTC
if accounts.freeze(user_id, BTC, qty) {
    let result = book.add_order(Order::new(id, user_id, price, qty, Side::Sell));
}
}

5. Settlement: Fund Transfer

When orders match, funds transfer between buyer and seller:

Trade: Alice sells 1 BTC to Bob @ $100

Before:
  Alice: BTC(frozen=1), USDT(avail=0)
  Bob:   BTC(avail=0), USDT(frozen=100)

Settlement:
  Alice: consume_frozen(BTC, 1) + receive(USDT, 100)
  Bob:   consume_frozen(USDT, 100) + receive(BTC, 1)

After:
  Alice: BTC(frozen=0), USDT(avail=100)
  Bob:   BTC(avail=1), USDT(frozen=0)

Code Implementation:

#![allow(unused)]
fn main() {
pub fn settle_trade(
    &mut self,
    buyer_id: u64,
    seller_id: u64,
    base_asset_id: u32,
    quote_asset_id: u32,
    base_amount: u64,    // Trade Qty
    quote_amount: u64,   // Trade Amount (price × qty)
) {
    // Buyer: Use USDT, Get BTC
    self.get_account_mut(buyer_id)
        .get_balance_mut(quote_asset_id)
        .consume_frozen(quote_amount);
    self.get_account_mut(buyer_id)
        .get_balance_mut(base_asset_id)
        .receive(base_amount);

    // Seller: Use BTC, Get USDT
    self.get_account_mut(seller_id)
        .get_balance_mut(base_asset_id)
        .consume_frozen(base_amount);
    self.get_account_mut(seller_id)
        .get_balance_mut(quote_asset_id)
        .receive(quote_amount);
}
}

6. Refined Trade Structure

To support settlement, Trade needs user IDs:

#![allow(unused)]
fn main() {
pub struct Trade {
    pub id: u64,
    pub buyer_order_id: u64,
    pub seller_order_id: u64,
    pub buyer_user_id: u64,   // New
    pub seller_user_id: u64,  // New
    pub price: u64,
    pub qty: u64,
}
}

7. Execution Results

=== 0xInfinity: Stage 5 (User Balance) ===
Symbol: BTC_USDT | Price: 2 decimals, Qty: 8 decimals
Cost formula: price * qty / 100000000

[0] Initial deposits...
    Alice: 100.00000000 BTC, 10000.00 USDT
    Bob:   5.00000000 BTC, 200000.00 USDT

[1] Alice places sell orders...
    Order 1: Sell 10.00000000 BTC @ $100.00 -> New
    Order 2: Sell 5.00000000 BTC @ $101.00 -> New
    Alice balance: avail=85.00000000 BTC, frozen=15.00000000 BTC

[2] Bob places buy order (taker)...
    Order 3: Buy 12.00000000 BTC @ $101.00 (cost: 1212.00 USDT)
    Trades:
      - Trade #1: 10.00000000 BTC @ $100.00
      - Trade #2: 2.00000000 BTC @ $101.00
    Order status: Filled

[3] Final balances:
    Alice: 85.00000000 BTC (frozen: 3.00000000), 11202.00 USDT
    Bob:   17.00000000 BTC, 198798.00 USDT (frozen: 0.00)

    Book: Best Bid=None, Best Ask=Some("101.00")

Analysis:

• Alice initial 100 BTC. Sold 10+2=12. Remaining 85 avail + 3 frozen = 88 BTC ✓
• Alice got 10×100 + 2×101 = 1202 USDT. Initial 10000 + 1202 = 11202 USDT ✓
• Bob initial 5 BTC. Bought 12. Total 17 BTC ✓
• Bob spent 1202 USDT. Initial 200000 - 1202 = 198798 USDT ✓

Summary

This chapter accomplished:

1. ✅ Implemented Balance: Dual-state (avail/frozen).
2. ✅ Implemented UserAccount: Multi-asset support.
3. ✅ Implemented AccountManager: Managing all users.
4. ✅ Pre-trade Freeze: Prevent over-selling/buying.
5. ✅ Post-trade Settlement: Correct fund transfer.
6. ✅ Refined Trade: Included user_ids.

Now our engine not only matches orders but also ensures funding sufficiency and correct settlement!

🇨🇳 中文

📦 代码变更: 查看 Diff

在前几章中，我们的撮合引擎已经可以正确匹配订单并产生成交。但有一个关键问题：钱从哪里来？ 在真实的交易所中，用户必须先有足够的资金才能下单，成交后资金才会转移。

本章我们将实现用户账户系统，包括：

• 余额管理（可用 / 冻结）
• 下单前资金校验
• 成交后资金结算

1. 余额的双重状态：Avail vs Frozen

在交易所中，用户的余额有两种状态：

为什么需要冻结？

假设 Alice 有 10 BTC，她同时挂了两个卖单：

• 卖单 A：卖 8 BTC
• 卖单 B：卖 5 BTC

如果没有冻结机制，这两个订单共需要 13 BTC，但 Alice 只有 10 BTC！这就是超卖问题。

正确的流程：

1. Alice 有 10 BTC (avail=10, frozen=0)
2. 下卖单 A (8 BTC) → freeze 8 BTC → (avail=2, frozen=8) ✅
3. 下卖单 B (5 BTC) → 尝试 freeze 5 BTC → 失败！avail 只有 2 ❌

2. Balance 结构

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Default)]
pub struct Balance {
    pub avail: u64,  // 可用余额 (简短命名，JSON 输出更高效)
    pub frozen: u64, // 冻结余额
}

impl Balance {
    /// 存款 (增加 avail)
    /// 返回 false 表示溢出 - 金融系统必须检测此错误
    pub fn deposit(&mut self, amount: u64) -> bool {
        match self.avail.checked_add(amount) {
            Some(new_avail) => {
                self.avail = new_avail;
                true
            }
            None => false, // 溢出！需要报警和调查
        }
    }
}

为什么要用 checked_add？

方法	溢出行为 (250u8 + 10u8)	适用场景
+ (标准)	Panic (Debug) 或 4 (Release回绕)	常规逻辑，溢出是 Bug
wrapping_add	4 (回绕)	哈希计算、图形算法
saturating_add	255 (封顶)	资源配额、令牌桶
checked_add	None	✅ 金融余额，溢出必须报错!

⚠️ 金融系统中，“钱多到溢出“是严重的 Bug，必须返回错误让上层处理，而不是静默封顶或回绕。

#![allow(unused)]
fn main() {

    /// 冻结 (avail → frozen)
    pub fn freeze(&mut self, amount: u64) -> bool {
        if self.avail >= amount {
            self.avail -= amount;
            self.frozen += amount;
            true
        } else {
            false
        }
    }

    /// 解冻 (frozen → avail)，用于取消订单
    pub fn unfreeze(&mut self, amount: u64) -> bool {
        if self.frozen >= amount {
            self.frozen -= amount;
            self.avail += amount;
            true
        } else {
            false
        }
    }

    /// 消耗冻结资金 (成交后，资金离开账户)
    pub fn consume_frozen(&mut self, amount: u64) -> bool {
        if self.frozen >= amount {
            self.frozen -= amount;
            true
        } else {
            false
        }
    }

    /// 接收资金 (成交后，资金进入账户)
    pub fn receive(&mut self, amount: u64) {
        self.avail = self.avail.checked_add(amount);
    }
}
}

3. 用户账户结构

每个用户持有多种资产的余额：

#![allow(unused)]
fn main() {
/// 使用 FxHashMap 实现 O(1) 资产查找
/// FxHashMap 使用更简单、更快的哈希函数，特别适合整数键
pub struct UserAccount {
    pub user_id: u64,
    balances: FxHashMap<u32, Balance>, // asset_id -> Balance
}

impl UserAccount {
    pub fn deposit(&mut self, asset_id: u32, amount: u64) {
        self.get_balance_mut(asset_id).deposit(amount);
    }

    pub fn avail(&self, asset_id: u32) -> u64 {
        self.balances.get(&asset_id).map(|b| b.avail).unwrap_or(0)
    }

    pub fn frozen(&self, asset_id: u32) -> u64 {
        self.balances.get(&asset_id).map(|b| b.frozen).unwrap_or(0)
    }
}
}

4. 下单流程：冻结资金

在下单时，我们需要根据订单类型冻结相应的资产：

从 SymbolManager 获取精度配置

每个交易对有独立的精度配置：

#![allow(unused)]
fn main() {
let symbol_info = manager.get_symbol_info("BTC_USDT").unwrap();
let price_decimal = symbol_info.price_decimal;  // 2 (价格精度)

let base_asset = manager.assets.get(&symbol_info.base_asset_id).unwrap();
let qty_decimal = base_asset.decimals;  // 8 (数量精度)
let qty_unit = 10u64.pow(qty_decimal);  // 100_000_000

// price = 100 USDT (内部单位: 100 * price_unit)
// qty = 10 BTC (内部单位: 10 * qty_unit)
// cost = price * qty / qty_unit (确保不会溢出)
let cost = price * qty / qty_unit;

if accounts.freeze(user_id, USDT, cost) {
    let result = book.add_order(Order::new(id, user_id, price, qty, Side::Buy));
} else {
    println!("REJECTED: Insufficient balance");
}

// 卖单：冻结 BTC
if accounts.freeze(user_id, BTC, qty) {
    let result = book.add_order(Order::new(id, user_id, price, qty, Side::Sell));
}
}

这样，精度配置跟着 Symbol 走，price * qty / qty_unit 保证结果在合理范围内。

5. 成交结算：资金转移

当订单匹配成交后，需要在买卖双方之间转移资金：

Trade: Alice sells 1 BTC to Bob @ $100

Before:
  Alice: BTC(frozen=1), USDT(avail=0)
  Bob:   BTC(avail=0), USDT(frozen=100)

Settlement:
  Alice: consume_frozen(BTC, 1) + receive(USDT, 100)
  Bob:   consume_frozen(USDT, 100) + receive(BTC, 1)

After:
  Alice: BTC(frozen=0), USDT(avail=100)
  Bob:   BTC(avail=1), USDT(frozen=0)

代码实现：

#![allow(unused)]
fn main() {
pub fn settle_trade(
    &mut self,
    buyer_id: u64,
    seller_id: u64,
    base_asset_id: u32,  // 如 BTC
    quote_asset_id: u32, // 如 USDT
    base_amount: u64,    // 成交数量
    quote_amount: u64,   // 成交金额 (price × qty)
) {
    // Buyer: 消耗 USDT，获得 BTC
    self.get_account_mut(buyer_id)
        .get_balance_mut(quote_asset_id)
        .consume_frozen(quote_amount);
    self.get_account_mut(buyer_id)
        .get_balance_mut(base_asset_id)
        .receive(base_amount);

    // Seller: 消耗 BTC，获得 USDT
    self.get_account_mut(seller_id)
        .get_balance_mut(base_asset_id)
        .consume_frozen(base_amount);
    self.get_account_mut(seller_id)
        .get_balance_mut(quote_asset_id)
        .receive(quote_amount);
}
}

6. Trade 结构的完善

为了正确结算，Trade 结构需要包含买卖双方的用户 ID：

#![allow(unused)]
fn main() {
pub struct Trade {
    pub id: u64,
    pub buyer_order_id: u64,
    pub seller_order_id: u64,
    pub buyer_user_id: u64,   // 新增
    pub seller_user_id: u64,  // 新增
    pub price: u64,
    pub qty: u64,
}
}

在撮合时，从 Order 中提取 user_id 并写入 Trade：

#![allow(unused)]
fn main() {
trades.push(Trade::new(
    self.trade_id_counter,
    buy_order.id,
    sell_order.id,
    buy_order.user_id,   // 从订单获取用户 ID
    sell_order.user_id,
    price,
    trade_qty,
));
}

7. 运行结果

=== 0xInfinity: Stage 5 (User Balance) ===
Symbol: BTC_USDT | Price: 2 decimals, Qty: 8 decimals
Cost formula: price * qty / 100000000

[0] Initial deposits...
    Alice: 100.00000000 BTC, 10000.00 USDT
    Bob:   5.00000000 BTC, 200000.00 USDT

[1] Alice places sell orders...
    Order 1: Sell 10.00000000 BTC @ $100.00 -> New
    Order 2: Sell 5.00000000 BTC @ $101.00 -> New
    Alice balance: avail=85.00000000 BTC, frozen=15.00000000 BTC

[2] Bob places buy order (taker)...
    Order 3: Buy 12.00000000 BTC @ $101.00 (cost: 1212.00 USDT)
    Trades:
      - Trade #1: 10.00000000 BTC @ $100.00
      - Trade #2: 2.00000000 BTC @ $101.00
    Order status: Filled

[3] Final balances:
    Alice: 85.00000000 BTC (frozen: 3.00000000), 11202.00 USDT
    Bob:   17.00000000 BTC, 198798.00 USDT (frozen: 0.00)

    Book: Best Bid=None, Best Ask=Some("101.00")

分析：

• Alice 初始有 100 BTC，卖出 10+2=12 BTC，还剩 85 + 3(frozen) = 88 BTC ✓
• Alice 收到 10×100 + 2×101 = 1202 USDT，加上初始 10000 = 11202 USDT ✓
• Bob 初始有 5 BTC，买入 12 BTC = 17 BTC ✓
• Bob 花费 1202 USDT，初始 200000 - 1202 = 198798 USDT ✓

Summary

本章完成了以下工作：

1. ✅ 实现 Balance 结构：avail/frozen 双状态余额管理
2. ✅ 实现 UserAccount：一个用户持有多种资产余额
3. ✅ 实现 AccountManager：管理所有用户账户
4. ✅ 下单前资金冻结：防止超卖/超买
5. ✅ 成交后资金结算：在买卖双方间正确转移资金
6. ✅ 完善 Trade 结构：包含买卖双方 user_id
7. ✅ 添加单元测试：4 个新测试覆盖余额管理

现在我们的撮合引擎不仅能正确匹配订单，还能确保用户有足够的资金，并在成交后正确结算！

0x06 Enforced Balance Management

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

In the previous chapter, we implemented balance management. However, in financial systems, fund operations are the most critical part and must be foolproof. This chapter upgrades balance management to a Type-System Enforced version.

1. Why “Enforced”?

The previous implementation had flaws:

#![allow(unused)]
fn main() {
// ❌ Problem 1: Public fields, easily modified unintentionally
pub struct Balance {
    pub avail: u64,   // Dev might assign directly, bypassing logic
    pub frozen: u64,
}

// ❌ Problem 2: Returns bool, unclear error
fn freeze(&mut self, amount: u64) -> bool {
    // Failed? Why? Don't know.
}

// ❌ Problem 3: No Audit Trail
// Balance changed, but no versioning for tracing.
}

These issues can lead to:

• Developers accidentally bypassing checks: In complex logic, one might modify fields directly.
• Hard to debug: “Operation failed” doesn’t tell you why.
• Audit difficulty: No change tracking makes it hard to pinpoint when a bug occurred.

Note: This is not to prevent malicious attacks (it’s an internal system), but to prevent developer errors. Just like Rust’s ownership system—we use types to reduce the chance of shooting ourselves in the foot.

2. Enforced Balance Design

The new version enforces safety via Rust Type System:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct Balance {
    avail: u64,      // ← Private! Only accessible via methods
    frozen: u64,     // ← Private!
    version: u64,    // ← Private! Auto-increment on change
}
}

Core Principles

Method Renaming

3. Balance API Details

Safe Getters

#![allow(unused)]
fn main() {
impl Balance {
    /// Get Available (Read-only)
    pub const fn avail(&self) -> u64 { self.avail }
    
    /// Get Frozen (Read-only)
    pub const fn frozen(&self) -> u64 { self.frozen }
    
    /// Get Total (avail + frozen)
    /// Returns None on overflow (data corruption)
    pub const fn total(&self) -> Option<u64> {
        self.avail.checked_add(self.frozen)
    }
    
    /// Get Version (Read-only)
    pub const fn version(&self) -> u64 { self.version }
}
}

Why const fn? Compiler guarantees state is never modified, providing strongest safety.

Validated Mutations

Every mutation method:

1. Validates preconditions
2. Uses checked arithmetic
3. Returns Result
4. Auto-increments version

#![allow(unused)]
fn main() {
/// Deposit: Increase Available
pub fn deposit(&mut self, amount: u64) -> Result<(), &'static str> {
    self.avail = self.avail.checked_add(amount)
        .ok_or("Deposit overflow")?;  // ← Return Error on Overflow
    self.version = self.version.wrapping_add(1);  // ← Auto Increment
    Ok(())
}

/// Lock: Avail → Frozen
pub fn lock(&mut self, amount: u64) -> Result<(), &'static str> {
    if self.avail < amount {
        return Err("Insufficient funds to lock");  // ← Explicit Error
    }
    self.avail = self.avail.checked_sub(amount)
        .ok_or("Lock avail underflow")?;
    self.frozen = self.frozen.checked_add(amount)
        .ok_or("Lock frozen overflow")?;
    self.version = self.version.wrapping_add(1);
    Ok(())
}

/// Unlock: Frozen → Avail
pub fn unlock(&mut self, amount: u64) -> Result<(), &'static str> {
    if self.frozen < amount {
        return Err("Insufficient frozen funds");
    }
    self.frozen = self.frozen.checked_sub(amount)
        .ok_or("Unlock frozen underflow")?;
    self.avail = self.avail.checked_add(amount)
        .ok_or("Unlock avail overflow")?;
    self.version = self.version.wrapping_add(1);
    Ok(())
}

/// Spend Frozen: Funds leave account after match
pub fn spend_frozen(&mut self, amount: u64) -> Result<(), &'static str> {
    if self.frozen < amount {
        return Err("Insufficient frozen funds");
    }
    self.frozen = self.frozen.checked_sub(amount)
        .ok_or("Spend frozen underflow")?;
    self.version = self.version.wrapping_add(1);
    Ok(())
}
}

4. UserAccount Refactoring

UserAccount is also refactored:

Data Structure Change

#![allow(unused)]
fn main() {
// Old: FxHashMap
pub struct UserAccount {
    pub user_id: u64,
    balances: FxHashMap<u32, Balance>,
}

// New: O(1) Direct Array Indexing
pub struct UserAccount {
    user_id: UserId,      // Private
    assets: Vec<Balance>, // Private, asset_id as index
}
}

O(1) Direct Array Indexing

#![allow(unused)]
fn main() {
// deposit() auto-creates slot
pub fn deposit(&mut self, asset_id: AssetId, amount: u64) -> Result<(), &'static str> {
    let idx = asset_id as usize;
    if idx >= self.assets.len() {
        self.assets.resize(idx + 1, Balance::default());
    }
    self.assets[idx].deposit(amount)
}

// get_balance_mut() returns Result
pub fn get_balance_mut(&mut self, asset_id: AssetId) -> Result<&mut Balance, &'static str> {
    self.assets.get_mut(asset_id as usize).ok_or("Asset not found")
}
}

🚀 Why Vec<Balance> is Highest Performance?

1. Cache-Friendly Vec<Balance> is contiguous in memory. Loading one Balance loads neighbors into CPU cache line.

2. get_balance() is High Frequency Each order triggers 5-10 balance checks. O(1) + Cache Friendly is critical for millions of TPS.

Settlement Methods

New methods dedicated to handling all settlement logic for buyer/seller in one go:

#![allow(unused)]
fn main() {
/// Buyer Settlement: Spend Quote, Gain Base, Refund unused Quote
pub fn settle_as_buyer(
    &mut self,
    quote_asset_id: AssetId,
    base_asset_id: AssetId,
    spend_quote: u64,   // Consumed USDT
    gain_base: u64,     // Gained BTC
    refund_quote: u64,  // Refunded USDT
) -> Result<(), &'static str> {
    // 1. Spend Quote (Frozen)
    self.get_balance_mut(quote_asset_id).spend_frozen(spend_quote)?;
    
    // 2. Gain Base (Available)
    self.get_balance_mut(base_asset_id).deposit(gain_base)?;
    
    // 3. Refund (Frozen → Available)
    if refund_quote > 0 {
        self.get_balance_mut(quote_asset_id).unlock(refund_quote)?;
    }
    Ok(())
}
}

5. Execution Results

=== 0xInfinity: Stage 6 (Enforced Balance) ===
Symbol: BTC_USDT | Price: 2 decimals, Qty: 8 decimals
Cost formula: price * qty / 100000000

[0] Initial deposits...
    Alice: 100.00000000 BTC, 10000.00 USDT
    Bob:   5.00000000 BTC, 200000.00 USDT

[1] Alice places sell orders...
    Order 1: Sell 10.00000000 BTC @ $100.00 -> New
    Order 2: Sell 5.00000000 BTC @ $101.00 -> New
    Alice balance: avail=85.00000000 BTC, frozen=15.00000000 BTC

[2] Bob places buy order (taker)...
    Order 3: Buy 12.00000000 BTC @ $101.00 (cost: 1212.00 USDT)
    Trades:
      - Trade #1: 10.00000000 BTC @ $100.00
      - Trade #2: 2.00000000 BTC @ $101.00
    Order status: Filled

[3] Final balances:
    Alice: 85.00000000 BTC (frozen: 3.00000000), 11202.00 USDT
    Bob:   17.00000000 BTC, 198798.00 USDT (frozen: 0.00)

    Book: Best Bid=None, Best Ask=Some("101.00")

=== End of Simulation ===

Results are consistent with the previous chapter, but now all operations are protected by the Type System!

6. Unit Tests

We added 8 new tests for enforced_balance. Total 16 tests passing.

test enrolled_balance::tests::test_deposit ... ok
test enrolled_balance::tests::test_deposit_overflow ... ok
test enrolled_balance::tests::test_lock_unlock ... ok
...
test result: ok. 16 passed; 0 failed

7. Error Handling Example

With the new API, Result must be handled:

#![allow(unused)]
fn main() {
// ❌ Compile Error: Unhandled Result
balance.deposit(100);

// ✅ Correct: Propagate
balance.deposit(100)?;

// ✅ Correct: Unwrap (Only if sure)
balance.deposit(100).unwrap();

// ✅ Correct: Match
match balance.lock(1000) {
    Ok(()) => println!("Locked successfully"),
    Err(e) => println!("Failed to lock: {}", e),
}
}

Summary

This chapter accomplished:

1. ✅ Encapsulation: Private fields prevent accidental modification.
2. ✅ Result Return: All mutations return explicit errors.
3. ✅ Versioning: Auto-increment version for audit.
4. ✅ Checked Arithmetic: Prevents overflow.
5. ✅ Renaming: lock/unlock/spend_frozen are clearer.
6. ✅ Settlement Helper: settle_as_buyer/seller.
7. ✅ Asset ID: Constraint for future O(1) array optimization.

Now our balance management is Type-Safe—the compiler prevents most balance-related bugs!

🇨🇳 中文

📦 代码变更: 查看 Diff

在上一章中，我们实现了用户账户的余额管理。但在金融系统中，资金操作是最核心、最关键的操作，必须确保万无一失。本章我们将余额管理升级为类型系统强制的安全版本。

1. 为什么需要“强制“版本？

上一章的实现存在几个隐患：

#![allow(unused)]
fn main() {
// ❌ 旧版问题1：字段是公开的，容易被无意修改
pub struct Balance {
    pub avail: u64,   // 开发者可能不小心直接赋值，绕过业务逻辑校验
    pub frozen: u64,
}

// ❌ 旧版问题2：返回 bool，错误信息不明确
fn freeze(&mut self, amount: u64) -> bool {
    // 失败了？为什么失败？不知道
}

// ❌ 旧版问题3：无审计追踪
// 余额变了，但没有版本号，无法追溯
}

这些问题可能导致：

• 开发者无意中绕过校验：在复杂的业务代码中，可能不小心直接修改公开字段
• 错误难以排查：只知道操作失败，不知道具体原因
• 审计困难：没有变更追踪，难以定位问题发生的时间点

注意：这不是防止恶意攻击（这是内部系统），而是防止开发者无意挖坑。 就像 Rust 的所有权系统一样——我们用类型系统来减少挖坑的机会。

2. 强制余额设计 (Enforced Balance)

新版本通过 Rust 类型系统 强制安全：

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct Balance {
    avail: u64,      // ← 私有！只能通过方法访问
    frozen: u64,     // ← 私有！
    version: u64,    // ← 私有！每次变更自动递增
}
}

核心原则

方法命名变更

3. Balance API 详解

只读方法 (Safe Getters)

#![allow(unused)]
fn main() {
impl Balance {
    /// 获取可用余额 (只读)
    pub const fn avail(&self) -> u64 { self.avail }
    
    /// 获取冻结余额 (只读)
    pub const fn frozen(&self) -> u64 { self.frozen }
    
    /// 获取总余额 (avail + frozen)
    /// 返回 None 表示溢出（数据损坏）
    pub const fn total(&self) -> Option<u64> {
        self.avail.checked_add(self.frozen)
    }
    
    /// 获取版本号 (只读)
    pub const fn version(&self) -> u64 { self.version }
}
}

为什么用 const fn？ 编译器保证永远不会修改状态，提供最强的安全保证。

变更方法 (Validated Mutations)

每个变更方法都：

1. 验证前置条件
2. 使用 checked 算术
3. 返回 Result
4. 自动递增 version

#![allow(unused)]
fn main() {
/// 存款：增加可用余额
pub fn deposit(&mut self, amount: u64) -> Result<(), &'static str> {
    self.avail = self.avail.checked_add(amount)
        .ok_or("Deposit overflow")?;  // ← 溢出返回错误
    self.version = self.version.wrapping_add(1);  // ← 自动递增
    Ok(())
}

/// 锁定：可用 → 冻结
pub fn lock(&mut self, amount: u64) -> Result<(), &'static str> {
    if self.avail < amount {
        return Err("Insufficient funds to lock");  // ← 明确错误信息
    }
    self.avail = self.avail.checked_sub(amount)
        .ok_or("Lock avail underflow")?;
    self.frozen = self.frozen.checked_add(amount)
        .ok_or("Lock frozen overflow")?;
    self.version = self.version.wrapping_add(1);
    Ok(())
}

/// 解锁：冻结 → 可用
pub fn unlock(&mut self, amount: u64) -> Result<(), &'static str> {
    if self.frozen < amount {
        return Err("Insufficient frozen funds");
    }
    self.frozen = self.frozen.checked_sub(amount)
        .ok_or("Unlock frozen underflow")?;
    self.avail = self.avail.checked_add(amount)
        .ok_or("Unlock avail overflow")?;
    self.version = self.version.wrapping_add(1);
    Ok(())
}

/// 消费冻结资金：成交后资金离开账户
pub fn spend_frozen(&mut self, amount: u64) -> Result<(), &'static str> {
    if self.frozen < amount {
        return Err("Insufficient frozen funds");
    }
    self.frozen = self.frozen.checked_sub(amount)
        .ok_or("Spend frozen underflow")?;
    self.version = self.version.wrapping_add(1);
    Ok(())
}
}

4. UserAccount 重构

新版 UserAccount 也进行了重构：

数据结构变更

#![allow(unused)]
fn main() {
// 旧版：使用 FxHashMap
pub struct UserAccount {
    pub user_id: u64,
    balances: FxHashMap<u32, Balance>,
}

// 新版：O(1) 直接数组索引
pub struct UserAccount {
    user_id: UserId,      // 私有
    assets: Vec<Balance>, // 私有，asset_id 作为下标
}
}

O(1) 直接数组索引

#![allow(unused)]
fn main() {
// deposit() 自动创建资产槽位（唯一入口）
pub fn deposit(&mut self, asset_id: AssetId, amount: u64) -> Result<(), &'static str> {
    let idx = asset_id as usize;
    if idx >= self.assets.len() {
        self.assets.resize(idx + 1, Balance::default());
    }
    self.assets[idx].deposit(amount)
}

// get_balance_mut() 不创建槽位，返回 Result
pub fn get_balance_mut(&mut self, asset_id: AssetId) -> Result<&mut Balance, &'static str> {
    self.assets.get_mut(asset_id as usize).ok_or("Asset not found")
}
}

🚀 为什么 Vec<Balance> 直接索引是最高效选择？

1. 极佳的缓存友好性 (Cache-Friendly)

Vec<Balance> 是连续内存布局，相邻资产的 Balance 在内存中也相邻。 当 CPU 读取一个 Balance 时，整个缓存行（通常 64 字节）会被加载， 相邻的 Balance 数据也一并进入 L1/L2 缓存，后续访问几乎零延迟。

2. get_balance() 是高频调用函数

在撮合引擎中，每笔订单都需要多次调用 get_balance()：

• 下单前检查余额
• 冻结资金
• 每笔成交结算（买方 + 卖方各 2-3 次）
• 退款未使用资金

一笔订单可能产生 5-10 次 get_balance() 调用。 在高频交易场景（每秒万笔订单），这意味着每秒 5-10 万次调用。 O(1) + 缓存友好 对性能至关重要。

结算方法

新增专门的结算方法，一次性处理买方或卖方的所有结算：

#![allow(unused)]
fn main() {
/// 买方结算：消费 Quote，获得 Base，退款未使用的 Quote
pub fn settle_as_buyer(
    &mut self,
    quote_asset_id: AssetId,
    base_asset_id: AssetId,
    spend_quote: u64,   // 消费的 USDT
    gain_base: u64,     // 获得的 BTC
    refund_quote: u64,  // 退款的 USDT
) -> Result<(), &'static str> {
    // 1. 消费 Quote (Frozen)
    self.get_balance_mut(quote_asset_id).spend_frozen(spend_quote)?;
    
    // 2. 获得 Base (Available)
    self.get_balance_mut(base_asset_id).deposit(gain_base)?;
    
    // 3. 退款 (Frozen → Available)
    if refund_quote > 0 {
        self.get_balance_mut(quote_asset_id).unlock(refund_quote)?;
    }
    Ok(())
}
}

5. 运行结果

=== 0xInfinity: Stage 6 (Enforced Balance) ===
Symbol: BTC_USDT | Price: 2 decimals, Qty: 8 decimals
Cost formula: price * qty / 100000000

[0] Initial deposits...
    Alice: 100.00000000 BTC, 10000.00 USDT
    Bob:   5.00000000 BTC, 200000.00 USDT

[1] Alice places sell orders...
    Order 1: Sell 10.00000000 BTC @ $100.00 -> New
    Order 2: Sell 5.00000000 BTC @ $101.00 -> New
    Alice balance: avail=85.00000000 BTC, frozen=15.00000000 BTC

[2] Bob places buy order (taker)...
    Order 3: Buy 12.00000000 BTC @ $101.00 (cost: 1212.00 USDT)
    Trades:
      - Trade #1: 10.00000000 BTC @ $100.00
      - Trade #2: 2.00000000 BTC @ $101.00
    Order status: Filled

[3] Final balances:
    Alice: 85.00000000 BTC (frozen: 3.00000000), 11202.00 USDT
    Bob:   17.00000000 BTC, 198798.00 USDT (frozen: 0.00)

    Book: Best Bid=None, Best Ask=Some("101.00")

=== End of Simulation ===

结果与前一章一致，但现在所有余额操作都通过类型系统保护！

6. 单元测试

新增 8 个 enforced_balance 测试：

$ cargo test

test result: ok. 16 passed; 0 failed

7. 错误处理示例

使用新 API 时，必须处理 Result：

#![allow(unused)]
fn main() {
// ❌ 编译错误：未处理的 Result
balance.deposit(100);

// ✅ 正确：显式处理
balance.deposit(100)?;  // 使用 ? 传播错误

// ✅ 正确：使用 unwrap（仅在确定不会失败时）
balance.deposit(100).unwrap();

// ✅ 正确：匹配处理
match balance.lock(1000) {
    Ok(()) => println!("Locked successfully"),
    Err(e) => println!("Failed to lock: {}", e),
}
}

Summary

本章完成了以下工作：

1. ✅ 私有字段封装：所有余额字段私有化，防止无意修改
2. ✅ Result 返回类型：所有变更操作返回明确的错误信息
3. ✅ 版本追踪：每次变更自动递增 version，支持审计
4. ✅ Checked 算术：所有运算使用 checked_add/sub，溢出返回错误
5. ✅ 方法重命名：lock/unlock/spend_frozen 语义更清晰
6. ✅ 结算方法：settle_as_buyer/settle_as_seller 一站式结算
7. ✅ Asset ID 约束：为未来 O(1) 直接索引优化做准备
8. ✅ 16 个测试通过：包括 8 个新的 enforced_balance 测试

现在我们的余额管理是类型安全的——编译器本身就能防止大部分余额操作错误！

0x07-a Testing Framework - Correctness

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

Core Objective: To establish a verifiable, repeatable, and traceable testing infrastructure for the matching engine.

This chapter is not just about “how to test”, but importantly about understanding “why designed this way”—these design decisions stem directly from real-world exchange requirements.

1. Why a Testing Framework?

1.1 The Uniqueness of Matching Engines

A matching engine is not a generic CRUD app. A single bug can lead to:

• Fund Errors: Users’ funds disappearing or inflating.
• Order Loss: Orders executed but not recorded.
• Inconsistent States: Contradictions between balances, orders, and ledgers.

Therefore, we need:

1. Deterministic Testing: Same input must yield same output.
2. Complete Audit: Every penny movement must be traceable.
3. Fast Verification: Quickly confirm correctness after every code change.

1.2 Golden File Testing Pattern

We adopt the Golden File Pattern:

fixtures/         # Input (Fixed)
    ├── orders.csv
    └── balances_init.csv

baseline/         # Golden Baseline (Result of first correct run, committed to git)
    ├── t1_balances_deposited.csv
    ├── t2_balances_final.csv
    ├── t2_ledger.csv
    └── t2_orderbook.csv

output/           # Current Run Result (gitignored)
    └── ...

Why this pattern?

1. Determinism: Fixed seeds ensure identical random sequences.
2. Version Control: Baselines are committed; any change triggers a git diff.
3. Fast Feedback: Just diff baseline/ output/.
4. Auditable: Baseline is the “contract”; deviations require explanation.

2. Precision Design: decimals vs display_decimals

2.1 Why Two Precisions?

This is the most error-prone area in exchanges. Consider this real case:

User sees:      Buy 0.01 BTC @ $85,000.00
Internal store: qty=1000000 (satoshi), price=85000000000 (micro-cents)

If we confuse these layers:

• User enters 0.01, system treats as 0.01 satoshi (= 0.00000001 BTC).
• Or user account shows 100 BTC, but actually has 0.000001 BTC.

Solution: Clearly distinguish two layers.

2.2 Precision Layers

┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Client (display_decimals)                          │
│   - Numbers seen by users                                   │
│   - Can be adjusted based on business needs                 │
│   - E.g.: BTC displays 6 decimals (0.000001 BTC)            │
└─────────────────────────────────────────────────────────────┘
                              ↓
                    Auto Convert (× 10^decimals)
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Internal (decimals)                                │
│   - Precision for internal storage and calculation          │
│   - NEVER change once set                                   │
│   - E.g.: BTC stored with 8 decimals (satoshi)              │
└─────────────────────────────────────────────────────────────┘

2.3 Configuration Design

assets_config.csv (Asset Precision Config):

asset_id,asset,decimals,display_decimals
1,BTC,8,6     # Min unit 0.000001 BTC ≈ $0.085
2,USDT,6,4    # Min unit 0.0001 USDT
3,ETH,8,4     # Min unit 0.0001 ETH ≈ $0.40

symbols_config.csv (Trading Pair Config):

symbol_id,symbol,base_asset_id,quote_asset_id,price_decimal,price_display_decimal
0,BTC_USDT,1,2,6,2    # Price min unit $0.01
1,ETH_USDT,3,2,6,2

Key Design: Precision Source

⚠️ Note: Price precision comes from Symbol config, NOT Quote Asset! This is because the same quote asset (e.g., USDT) may have different price precisions in different pairs.

Why decimals cannot change?

Suppose BTC decimals change from 8 to 6:

• Original balance 100,000,000 (= 1 BTC with 8 decimals).
• New interpretation 100,000,000 / 10^6 = 100 BTC.
• User gains 99 BTC out of thin air!

Why display_decimals can change?

This is just the display layer:

• Original display: 0.12345678 BTC.
• New display (6 decimals): 0.123456 BTC.
• Internal storage remains 12,345,678 satoshis.

3. Balance Format: Row vs Column

3.1 Problem: Storing Multi-Asset Balances

Option A: Columnar (One column per asset)

user_id,btc_avail,btc_frozen,usdt_avail,usdt_frozen
1,10000000000,0,10000000000000,0

Option B: Row-based (One row per asset)

user_id,asset_id,avail,frozen,version
1,1,10000000000,0,0
1,2,10000000000000,0,0

3.2 Why Row-based?

Real Scenario: An exchange supports 500+ assets, but users avg 3-5 holdings. Row-based design saves 99% storage space.

4. Timeline Snapshot Design

4.1 Why Multiple Snapshots?

Matching is a multi-stage process:

T0: Initial State (fixtures/balances_init.csv)
    ↓ deposit()
T1: Deposit Done (baseline/t1_balances_deposited.csv)
    ↓ execute orders
T2: Trading Done (baseline/t2_balances_final.csv)

Errors can occur at any stage:

• T0→T1: Is deposit logic correct?
• T1→T2: Is trade settlement correct?

Snapshots pinpoint issues:

# Verify Deposit
diff balances_init.csv t1_balances_deposited.csv

# Verify Settlement
diff t1_balances_deposited.csv t2_balances_final.csv

4.2 Naming Convention

t1_balances_deposited.csv   # t1 stage, balances type, deposited state
t2_balances_final.csv       # t2 stage, balances type, final state
t2_ledger.csv               # t2 stage, ledger type
t2_orderbook.csv            # t2 stage, orderbook type

Principle: {Time}_{Type}_{State}.csv

Benefits:

1. Natural sort order by time.
2. Clear content identification.
3. Avoids ambiguity.

5. Settlement Ledger Design

5.1 Why Ledger?

t2_ledger.csv is the system’s Audit Log. Every penny movement is recorded here.

Without Ledger:

• User complaint: “Where did my money go?”
• Support: “Your balance is X.”
• Unanswerable: “When did it change? Why?”

With Ledger:

trade_id,user_id,asset_id,op,delta,balance_after
1,96,2,debit,849700700,9999150299300
1,96,1,credit,1000000,10001000000

Traceability:

• Trade #1 caused User #96’s USDT to decrease by 849,700,700.
• Simultaneously BTC increased by 1,000,000.
• What is the balance after change.

5.2 Why delta + after instead of before + after?

Option A: before + after

delta,balance_before,balance_after
849700700,10000000000,9999150299300

Option B: delta + after

delta,balance_after
849700700,9999150299300

Why B?

1. Less Redundancy: before = after - delta.
2. Usefulness: We mostly verify “Is the final state correct?”.
3. Clarity: Delta directly explains the change.

6. ME Orderbook Snapshot

6.1 Why Orderbook Snapshot?

After trading, the Orderbook still holds unfilled orders. These orders:

• Reside in RAM.
• Are lost if system restarts.

t2_orderbook.csv is a Full Snapshot of ME State:

order_id,user_id,side,order_type,price,qty,filled_qty,status
6,907,sell,limit,85330350000,2000000,0,New

Uses:

1. Recovery: Revert Orderbook state after restart.
2. Verification: Compare against theoretical expectations.
3. Debugging: Check stuck orders.

6.2 Why Record All Fields?

The goal is Full Recovery. Rebuilding Order struct requires:

#![allow(unused)]
fn main() {
struct Order {
    id, user_id, price, qty, filled_qty, side, order_type, status
}
}

Missing any field prevents recovery.

7. Test Script Design

7.1 Modular Scripts

scripts/
├── test_01_generate.sh     # Step 1: Generate Data
├── test_02_baseline.sh     # Step 2: Generate Baseline
├── test_03_verify.sh       # Step 3: Run & Verify
└── test_e2e.sh             # Combo: Full E2E Flow

Why Modular?

1. Isolated Debugging: Run only relevant steps.
2. Flexible Composition: CI can verify without regenerating.
3. Readability: One script, one job.

7.2 Usage

# Daily Test (Use existing baseline)
./scripts/test_e2e.sh

# Regenerate Baseline & Test
./scripts/test_e2e.sh --regenerate

8. CLI Design: --baseline Switch

8.1 Why Switch?

Default behavior:

• Output to output/
• Never overwrite baseline

Update baseline:

• Add --baseline arg
• Output to baseline/

Why not auto-overwrite?

1. Safety: Prevent accidental baseline corruption.
2. Intent: Updating baseline is a conscious decision.
3. Git Friendly: Changes trigger diff.

8.2 Implementation

#![allow(unused)]
fn main() {
fn get_output_dir() -> &'static str {
    let args: Vec<String> = std::env::args().collect();
    if args.iter().any(|a| a == "--baseline") {
        "baseline"
    } else {
        "output"
    }
}
}

9. Execution Example

9.1 Full Flow

# 1. Generate Data
python3 scripts/generate_orders.py --orders 100000 --seed 42

# 2. Generate Baseline (First run or update)
cargo run --release -- --baseline

# 3. Daily Test
./scripts/test_e2e.sh

9.2 Verification Output

╔════════════════════════════════════════════════════════════╗
║     0xInfinity Testing Framework - E2E Test                ║
╚════════════════════════════════════════════════════════════╝

  t1_balances_deposited.csv: ✅ MATCH
  t2_balances_final.csv: ✅ MATCH
  t2_ledger.csv: ✅ MATCH
  t2_orderbook.csv: ✅ MATCH

✅ All tests passed!

10. Summary

This chapter established a complete testing infrastructure:

Core Philosophy:

Testing is not an afterthought, but part of the design. A good testing framework gives you confidence when changing code.

Next section (0x07-b) will add performance benchmarks on top of this.

🇨🇳 中文

📦 代码变更: 查看 Diff

核心目的：为撮合引擎建立可验证、可重复、可追溯的测试基础设施。

本章不仅是“如何测试“，更重要的是理解“为什么这样设计“——这些设计决策直接源于真实交易所的需求。

1. 为什么需要测试框架？

1.1 撮合引擎的特殊性

撮合引擎不是普通的 CRUD 应用。一个 bug：

• 资金错误：用户资金凭空消失或增加
• 订单丢失：订单被执行但没有记录
• 状态不一致：余额、订单、成交记录互相矛盾

因此，我们需要：

1. 确定性测试：相同的输入必须产生相同的输出
2. 完整审计：每一分钱的变动都可追溯
3. 快速验证：每次修改代码后能快速确认没有破坏正确性

1.2 Golden File 测试模式

我们采用 Golden File 模式：

fixtures/         # 输入（固定）
    ├── orders.csv
    └── balances_init.csv

baseline/         # 黄金基准（第一次正确运行的结果，git 提交）
    ├── t1_balances_deposited.csv
    ├── t2_balances_final.csv
    ├── t2_ledger.csv
    └── t2_orderbook.csv

output/           # 当前运行结果（gitignored）
    └── ...

为什么选择这种模式？

1. 确定性：固定的 seed 保证相同的随机数序列
2. 版本控制：baseline 提交到 git，任何变化都能被 diff 检测
3. 快速反馈：只需 diff baseline/ output/
4. 可审计：baseline 是“合约“，任何偏离都需要解释

2. 精度设计：decimals vs display_decimals

2.1 为什么需要两种精度？

这是交易所最容易出错的地方。看这个真实案例：

用户看到：买入 0.01 BTC @ $85,000.00
内部存储：qty=1000000 (satoshi), price=85000000000 (微美分)

如果混淆这两层，会发生什么？

• 用户输入 0.01，系统理解为 0.01 satoshi = 实际 0.0000001 BTC
• 或者用户账户显示有 100 BTC，实际只有 0.000001 BTC

解决方案：明确区分两层精度

2.2 精度层次

┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Client (display_decimals)                          │
│   - 用户看到的数字                                            │
│   - 可以根据业务需求调整                                        │
│   - 例如：BTC 数量显示 6 位小数 (0.000001 BTC)              │
└─────────────────────────────────────────────────────────────┘
                              ↓
                    自动转换 (× 10^decimals)
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Internal (decimals)                                │
│   - 内部存储和计算的精度                                        │
│   - 一旦设定永不改变                                            │
│   - 例如：BTC 存储 8 位精度 (satoshi)                          │
└─────────────────────────────────────────────────────────────┘

2.3 配置文件设计

assets_config.csv（资产精度配置）：

asset_id,asset,decimals,display_decimals
1,BTC,8,6     # 最小单位 0.000001 BTC ≈ $0.085
2,USDT,6,4   # 最小单位 0.0001 USDT
3,ETH,8,4    # 最小单位 0.0001 ETH ≈ $0.40

symbols_config.csv（交易对配置）：

symbol_id,symbol,base_asset_id,quote_asset_id,price_decimal,price_display_decimal
0,BTC_USDT,1,2,6,2    # 价格最小单位 $0.01
1,ETH_USDT,3,2,6,2

关键设计：精度来源

⚠️ 注意：price 精度来自 symbol 配置，不是 quote_asset！ 这样设计是因为同一个 quote asset（如 USDT）在不同交易对中可能有不同的价格精度。

为什么 decimals 不能改变？

假设 BTC decimals 从 8 改为 6：

• 原来账户余额 100000000 (= 1 BTC)
• 现在变成 100000000 / 10^6 = 100 BTC
• 用户凭空获得 99 BTC！

为什么 display_decimals 可以改变？

这只是显示层，不影响存储：

• 原来显示 0.12345678 BTC
• 调整后显示 0.123456 BTC（6位）
• 内部存储仍然是 12345678 satoshi

3. 余额格式设计：行式 vs 列式

3.1 问题：如何存储多资产余额？

Option A：列式（每个资产一列）

user_id,btc_avail,btc_frozen,usdt_avail,usdt_frozen
1,10000000000,0,10000000000000,0

Option B：行式（每个资产一行）

user_id,asset_id,avail,frozen,version
1,1,10000000000,0,0
1,2,10000000000000,0,0

3.2 为什么选择行式？

真实场景：交易所支持 500+ 种资产，但用户平均只持有 3-5 种。行式设计节省 99% 的存储空间。

4. 时间线快照设计

4.1 为什么需要多个快照？

撮合过程不是单一操作，而是多阶段流程：

T0: 初始状态 (fixtures/balances_init.csv)
    ↓ deposit()
T1: 充值完成 (baseline/t1_balances_deposited.csv)
    ↓ execute orders
T2: 交易完成 (baseline/t2_balances_final.csv)

每个阶段都可能出错：

• T0→T1：deposit 逻辑是否正确？
• T1→T2：交易结算是否正确？

有了快照，可以精确定位问题：

# 验证 deposit 正确性
diff balances_init.csv t1_balances_deposited.csv

# 验证交易结算正确性
diff t1_balances_deposited.csv t2_balances_final.csv

4.2 文件命名设计

t1_balances_deposited.csv   # t1 阶段，balances 类型，deposited 状态
t2_balances_final.csv       # t2 阶段，balances 类型，final 状态
t2_ledger.csv               # t2 阶段，ledger 类型
t2_orderbook.csv            # t2 阶段，orderbook 类型

命名原则：{时间点}_{数据类型}_{状态}.csv

这样的命名：

1. 按时间排序时自然有序
2. 一眼看出数据是什么
3. 避免文件名歧义

5. Settlement Ledger 设计

5.1 为什么需要 Ledger？

t2_ledger.csv 是整个系统的审计日志。每一分钱的变动都记录在这里。

没有 Ledger 的问题：

• 用户投诉：我的钱去哪了？
• 只能说：交易后余额是 X
• 无法回答：什么时候变的？为什么变？

有了 Ledger：

trade_id,user_id,asset_id,op,delta,balance_after
1,96,2,debit,849700700,9999150299300
1,96,1,credit,1000000,10001000000

可以完整追溯：

• Trade #1 导致 User #96 的 USDT 减少 849700700
• 同时 BTC 增加 1000000
• 变化后余额是多少

5.2 为什么用 delta + after，而不是 before + after？

Option A：before + after

delta,balance_before,balance_after
849700700,10000000000,9999150299300

Option B：delta + after

delta,balance_after
849700700,9999150299300

选择 Option B 的原因：

1. 冗余更少：before = after - delta，可计算得出
2. after 更有用：通常我们想验证的是“最终状态对不对“
3. delta 直接说明变化：不需要心算 before - after

6. ME Orderbook 快照

6.1 为什么需要 Orderbook 快照？

交易完成后，Orderbook 里仍然有未成交的挂单。这些订单：

• 在内存中
• 如果系统重启，会丢失

t2_orderbook.csv 是 ME 状态的完整快照：

order_id,user_id,side,order_type,price,qty,filled_qty,status
6,907,sell,limit,85330350000,2000000,0,New

用途：

1. 状态恢复：重启后可以从快照恢复 Orderbook
2. 正确性验证：与理论预期对比
3. 调试：哪些订单还在挂着？

6.2 为什么记录所有字段？

快照目的是完整恢复。恢复时需要重建 Order 结构体：

#![allow(unused)]
fn main() {
struct Order {
    id,
    user_id,
    price,
    qty,
    filled_qty,
    side,
    order_type,
    status,
}
}

缺少任何字段都无法恢复。

7. 测试脚本设计

7.1 模块化脚本

scripts/
├── test_01_generate.sh     # Step 1: 生成测试数据
├── test_02_baseline.sh     # Step 2: 生成基准
├── test_03_verify.sh       # Step 3: 运行并验证
└── test_e2e.sh             # 组合：完整 E2E 流程

为什么模块化？

1. 单独调试：出问题时只运行相关步骤
2. 灵活组合：CI 可以只运行 verify，不重新生成数据
3. 可读性：每个脚本做一件事

7.2 使用方式

# 日常测试（使用现有 baseline）
./scripts/test_e2e.sh

# 重新生成基准并测试
./scripts/test_e2e.sh --regenerate

8. 命令行设计：–baseline 开关

8.1 为什么需要开关？

默认行为：

• 输出到 output/
• 不会覆盖 baseline

需要更新基准时：

• 加 --baseline 参数
• 输出到 baseline/

为什么不自动覆盖？

1. 安全：防止意外覆盖基准
2. 意图明确：更新基准是有意识的决定
3. Git 友好：baseline 变化会触发 git diff
4. 代码实现：

#![allow(unused)]
fn main() {
fn get_output_dir() -> &'static str {
    let args: Vec<String> = std::env::args().collect();
    if args.iter().any(|a| a == "--baseline") {
        "baseline"
    } else {
        "output"
    }
}
}

9. 运行示例

9.1 完整流程

# 1. 生成测试数据
python3 scripts/generate_orders.py --orders 100000 --seed 42

# 2. 生成基准（首次或需要更新时）
cargo run --release -- --baseline

# 3. 日常测试
./scripts/test_e2e.sh

9.2 验证输出

╔════════════════════════════════════════════════════════════╗
║     0xInfinity Testing Framework - E2E Test                ║
╚════════════════════════════════════════════════════════════╝

  t1_balances_deposited.csv: ✅ MATCH
  t2_balances_final.csv: ✅ MATCH
  t2_ledger.csv: ✅ MATCH
  t2_orderbook.csv: ✅ MATCH

✅ All tests passed!

10. Summary

本章建立了完整的测试基础设施：

核心理念：

测试不是事后补的，而是设计的一部分。好的测试框架能让你在改动代码时有信心。

下一节 (0x07-b) 将在此基础上添加性能测试和优化基准。

0x07-b Performance Baseline - Initial Setup

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

Core Objective: To establish a quantifiable, traceable, and comparable performance baseline.

Building on the testing framework from 0x07-a, this chapter adds detailed performance metric collection and analysis capabilities.

1. Why a Performance Baseline?

1.1 The Performance Trap

Optimization without a baseline is blind:

• Premature Optimization: Optimizing code that accounts for 1% of runtime.
• Delayed Regression Detection: A refactor drops performance by 50%, but it’s only discovered 3 months later.
• Unquantifiable Improvement: Promoting “it’s much faster,” but exactly how much?

1.2 Value of a Baseline

With a baseline, you can:

1. Verify before Commit: Ensure performance hasn’t degraded.
2. Pinpoint Bottlenecks: Identify which component consumes the most time.
3. Quantify Optimization: “Throughput increased from 30K ops/s to 100K ops/s.”

2. Metric Design

2.1 Throughput Metrics

2.2 Time Breakdown

We decompose execution time into four components:

┌─────────────────────────────────────────────────────────────┐
│ Order Processing (per order)                                │
├─────────────────────────────────────────────────────────────┤
│ 1. Balance Check     │ Account lookup + balance validation  │
│    - Account lookup  │ FxHashMap O(1)                       │
│    - Fund locking    │ Check avail >= required, then lock   │
├─────────────────────────────────────────────────────────────┤
│ 2. Matching Engine   │ book.add_order()                     │
│    - Price lookup    │ BTreeMap O(log n)                    │
│    - Order matching  │ iterate + partial fill               │
├─────────────────────────────────────────────────────────────┤
│ 3. Settlement        │ settle_as_buyer/seller               │
│    - Balance update  │ HashMap O(1)                         │
├─────────────────────────────────────────────────────────────┤
│ 4. Ledger I/O        │ write_entry()                        │
│    - File write      │ Disk I/O                             │
└─────────────────────────────────────────────────────────────┘

2.3 Latency Percentiles

Sample total processing latency every N orders:

3. Initial Baseline Data

3.1 Test Environment

• Hardware: MacBook Pro M Series
• Data: 100,000 Orders, 47,886 Trades
• Mode: Release build (--release)

3.2 Throughput

Throughput: ~29,000 orders/sec | ~14,000 trades/sec
Execution Time: ~3.5s

3.3 Time Breakdown 🔥

=== Performance Breakdown ===
Balance Check:       17.68ms (  0.5%)  ← FxHashMap O(1)
Matching Engine:     36.04ms (  1.0%)  ← Extremely Fast!
Settlement:           4.77ms (  0.1%)  ← Negligible
Ledger I/O:        3678.68ms ( 98.4%) ← Bottleneck!

Key Findings:

• Ledger I/O consumes 98.4% of time.
• Balance Check + Matching + Settlement total only ~58ms.
• Theoretical Limit: ~1.7 Million orders/sec (without I/O).

3.4 Order Lifecycle Timeline 📊

                           Order Lifecycle
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
    │   Balance   │    │  Matching   │    │ Settlement  │    │  Ledger     │
    │   Check     │───▶│   Engine    │───▶│  (Balance)  │───▶│   I/O       │
    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
          │                  │                  │                  │
          ▼                  ▼                  ▼                  ▼
    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
    │ FxHashMap   │    │  BTreeMap   │    │Vec<Balance> │    │  File::     │
    │   +Vec O(1) │    │  O(log n)   │    │    O(1)     │    │  write()    │
    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    Total Time:   17.68ms            36.04ms            4.77ms          3678.68ms
    Percentage:    0.5%               1.0%              0.1%             98.4%
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    Per-Order:    0.18µs             0.36µs            0.05µs           36.79µs
    Potential:   5.6M ops/s         2.8M ops/s       20M ops/s         27K ops/s
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

                        Business Logic ~58ms (1.6%)        I/O ~3679ms (98.4%)
                    ◀─────────────────────────▶      ◀───────────────────────▶
                             Fast ✅                        Bottleneck 🔴

Analysis:

E2E Result:

• Actual Throughput: ~29K orders/sec (I/O Bound)
• Theoretical Limit (No I/O): ~1.7M orders/sec (60x room for improvement!)

3.5 Latency Percentiles

=== Latency Percentiles (sampled) ===
  Min:        125 ns
  Avg:      34022 ns
  P50:        583 ns   ← Typical order < 1µs
  P99:     391750 ns   ← 99% of orders < 0.4ms
  P99.9:  1243833 ns   ← Tail latency ~1.2ms
  Max:    3207875 ns   ← Worst case ~3ms

4. Output Files

4.1 t2_perf.txt (Machine Readable)

# Performance Baseline - 0xInfinity
# Generated: 2025-12-16
orders=100000
trades=47886
exec_time_ms=3451.78
throughput_ops=28971
throughput_tps=13873
matching_ns=32739014
settlement_ns=3085409
ledger_ns=3388134698
latency_min_ns=125
latency_avg_ns=34022
latency_p50_ns=583
latency_p99_ns=391750
latency_p999_ns=1243833
latency_max_ns=3207875

4.2 t2_summary.txt (Human Readable)

Contains full execution summary and performance breakdown.

5. PerfMetrics Implementation

#![allow(unused)]
fn main() {
/// Performance metrics for execution analysis
#[derive(Default)]
struct PerfMetrics {
    // Timing breakdown (nanoseconds)
    total_balance_check_ns: u64,  // Account lookup + balance check + lock
    total_matching_ns: u64,       // OrderBook.add_order()
    total_settlement_ns: u64,     // Balance updates after trade
    total_ledger_ns: u64,         // Ledger file I/O
    
    // Per-order latency samples
    latency_samples: Vec<u64>,
    sample_rate: usize,
}

impl PerfMetrics {
    fn new(sample_rate: usize) -> Self { ... }
    
    fn add_order_latency(&mut self, latency_ns: u64) { ... }
    fn add_balance_check_time(&mut self, ns: u64) { ... }
    fn add_matching_time(&mut self, ns: u64) { ... }
    fn add_settlement_time(&mut self, ns: u64) { ... }
    fn add_ledger_time(&mut self, ns: u64) { ... }
    
    fn percentile(&self, p: f64) -> Option<u64> { ... }
    fn min_latency(&self) -> Option<u64> { ... }
    fn max_latency(&self) -> Option<u64> { ... }
    fn avg_latency(&self) -> Option<u64> { ... }
}
}

6. Optimization Roadmap

Based on baseline data, future directions:

6.1 Short Term (0x07-c)

6.2 Mid Term (0x08+)

6.3 Long Term

7. Commands Reference

# Run and generate performance data
cargo run --release

# Update baseline (when code changes)
cargo run --release -- --baseline

# View performance data
cat output/t2_perf.txt

# Compare performance changes
python3 scripts/compare_perf.py

compare_perf.py Output Example

╔════════════════════════════════════════════════════════════════════════╗
║                    Performance Comparison Report                       ║
╚════════════════════════════════════════════════════════════════════════╝

Metric                           Baseline         Current       Change
───────────────────────────────────────────────────────────────────────────
Orders                             100000          100000            -
Trades                              47886           47886            -

Exec Time                       3753.87ms       3484.37ms        -7.2%
Throughput (orders)               26639/s         28700/s        +7.7%
Throughput (trades)               12756/s         13743/s        +7.7%

───────────────────────────────────────────────────────────────────────────
Timing Breakdown (lower is better):

Metric                           Baseline         Current     Change        OPS
Balance Check                     17.68ms         16.51ms      -6.6%       6.1M
Matching Engine                   36.04ms         35.01ms      -2.8%       2.9M
Settlement                         4.77ms          5.22ms      +9.4%      19.2M
Ledger I/O                      3678.68ms       3411.49ms      -7.3%        29K

───────────────────────────────────────────────────────────────────────────
Latency Percentiles (lower is better):

Metric                           Baseline         Current       Change
Latency MIN                         125ns           125ns        +0.0%
Latency AVG                        37.9µs          34.8µs        -8.2%
Latency P50                         584ns           541ns        -7.4%
Latency P99                       420.2µs         398.9µs        -5.1%
Latency P99.9                      1.63ms          1.24ms       -24.3%
Latency MAX                        9.76ms          3.53ms       -63.9%

───────────────────────────────────────────────────────────────────────────
✅ No significant regressions detected

Summary

This chapter accomplished:

1. PerfMetrics Structure: Collecting time breakdown & latency samples.
2. Time Breakdown: Balance Check / Matching / Settlement / Ledger I/O.
3. Latency Percentiles: P50 / P99 / P99.9 / Max.
4. t2_perf.txt: Machine-readable baseline file.
5. compare_perf.py: Tool to detect regression.
6. Key Finding: Ledger I/O takes 98.4%, major bottleneck.

🇨🇳 中文

📦 代码变更: 查看 Diff

核心目的：建立可量化、可追踪、可比较的性能基线。

本章在 0x07-a 测试框架基础上，添加详细的性能指标收集和分析能力。

1. 为什么需要性能基线？

1.1 性能陷阱

没有基线的优化是盲目的：

• 过早优化：优化了占 1% 时间的代码
• 回归发现延迟：某次重构导致性能下降 50%，但 3 个月后才发现
• 无法量化改进：说“快了很多“，但具体快了多少？

1.2 基线的价值

有了基线，你可以：

1. 每次提交前验证：性能没有下降
2. 精确定位瓶颈：哪个组件消耗最多时间
3. 量化优化效果：从 30K ops/s 提升到 100K ops/s

2. 性能指标设计

2.1 吞吐量指标

2.2 时间分解

我们将执行时间分解为四个组件：

┌─────────────────────────────────────────────────────────────┐
│ Order Processing (per order)                                │
├─────────────────────────────────────────────────────────────┤
│ 1. Balance Check     │ Account lookup + balance validation  │
│    - Account lookup  │ FxHashMap O(1)                       │
│    - Fund locking    │ Check avail >= required, then lock   │
├─────────────────────────────────────────────────────────────┤
│ 2. Matching Engine   │ book.add_order()                     │
│    - Price lookup    │ BTreeMap O(log n)                    │
│    - Order matching  │ iterate + partial fill               │
├─────────────────────────────────────────────────────────────┤
│ 3. Settlement        │ settle_as_buyer/seller               │
│    - Balance update  │ HashMap O(1)                         │
├─────────────────────────────────────────────────────────────┤
│ 4. Ledger I/O        │ write_entry()                        │
│    - File write      │ Disk I/O                             │
└─────────────────────────────────────────────────────────────┘

2.3 延迟百分位数

采样每 N 个订单的总处理延迟，计算：

3. 初始基线数据

3.1 测试环境

• 硬件：MacBook Pro M 系列
• 数据：100,000 订单，47,886 成交
• 模式：Release build (--release)

3.2 吞吐量

Throughput: ~29,000 orders/sec | ~14,000 trades/sec
Execution Time: ~3.5s

3.3 时间分解 🔥

=== Performance Breakdown ===
Balance Check:       17.68ms (  0.5%)  ← FxHashMap O(1)
Matching Engine:     36.04ms (  1.0%)  ← 极快！
Settlement:           4.77ms (  0.1%)  ← 几乎可忽略
Ledger I/O:        3678.68ms ( 98.4%) ← 瓶颈！

关键发现：

• Ledger I/O 占用 98.4% 的时间
• Balance Check + Matching + Settlement 总共只需 ~58ms
• 理论上限：~170 万 orders/sec（如果没有 I/O）

3.4 订单生命周期性能时间线 📊

                           订单生命周期 (Order Lifecycle)
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
    │   Balance   │    │  Matching   │    │ Settlement  │    │  Ledger     │
    │   Check     │───▶│   Engine    │───▶│  (Balance)  │───▶│   I/O       │
    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
          │                  │                  │                  │
          ▼                  ▼                  ▼                  ▼
    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
    │ FxHashMap   │    │  BTreeMap   │    │Vec<Balance> │    │  File::     │
    │   +Vec O(1) │    │  O(log n)   │    │    O(1)     │    │  write()    │
    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    Total Time:   17.68ms            36.04ms            4.77ms          3678.68ms
    Percentage:    0.5%               1.0%              0.1%             98.4%
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    Per-Order:    0.18µs             0.36µs            0.05µs           36.79µs
    Potential:   5.6M ops/s         2.8M ops/s       20M ops/s         27K ops/s
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

                        业务逻辑 ~58ms (1.6%)              I/O ~3679ms (98.4%)
                    ◀─────────────────────────▶      ◀───────────────────────▶
                             极快 ✅                        瓶颈 🔴

性能分析:

E2E 结果:

• 实际吞吐量: ~29K orders/sec (受限于 Ledger I/O)
• 理论上限 (无 I/O): ~1.7M orders/sec (60x 提升空间!)

3.5 延迟百分位数

=== Latency Percentiles (sampled) ===
  Min:        125 ns
  Avg:      34022 ns
  P50:        583 ns   ← 典型订单 < 1µs
  P99:     391750 ns   ← 99% 的订单 < 0.4ms
  P99.9:  1243833 ns   ← 尾延迟 ~1.2ms
  Max:    3207875 ns   ← 最坏 ~3ms

4. 输出文件

4.1 t2_perf.txt（机器可读）

# Performance Baseline - 0xInfinity
# Generated: 2025-12-16
orders=100000
trades=47886
exec_time_ms=3451.78
throughput_ops=28971
throughput_tps=13873
matching_ns=32739014
settlement_ns=3085409
ledger_ns=3388134698
latency_min_ns=125
latency_avg_ns=34022
latency_p50_ns=583
latency_p99_ns=391750
latency_p999_ns=1243833
latency_max_ns=3207875

4.2 t2_summary.txt（人类可读）

包含完整的执行摘要和性能分解。

5. PerfMetrics 实现

#![allow(unused)]
fn main() {
/// Performance metrics for execution analysis
#[derive(Default)]
struct PerfMetrics {
    // Timing breakdown (nanoseconds)
    total_balance_check_ns: u64,  // Account lookup + balance check + lock
    total_matching_ns: u64,       // OrderBook.add_order()
    total_settlement_ns: u64,     // Balance updates after trade
    total_ledger_ns: u64,         // Ledger file I/O
    
    // Per-order latency samples
    latency_samples: Vec<u64>,
    sample_rate: usize,
}

impl PerfMetrics {
    fn new(sample_rate: usize) -> Self { ... }
    
    fn add_order_latency(&mut self, latency_ns: u64) { ... }
    fn add_balance_check_time(&mut self, ns: u64) { ... }
    fn add_matching_time(&mut self, ns: u64) { ... }
    fn add_settlement_time(&mut self, ns: u64) { ... }
    fn add_ledger_time(&mut self, ns: u64) { ... }
    
    fn percentile(&self, p: f64) -> Option<u64> { ... }
    fn min_latency(&self) -> Option<u64> { ... }
    fn max_latency(&self) -> Option<u64> { ... }
    fn avg_latency(&self) -> Option<u64> { ... }
}
}

6. 优化路线图

基于基线数据，后续优化方向：

6.1 短期（0x07-c）

6.2 中期（0x08+）

6.3 长期

7. 命令参考

# 运行并生成性能数据
cargo run --release

# 更新基线（当代码变化时）
cargo run --release -- --baseline

# 查看性能数据
cat output/t2_perf.txt

# 对比性能变化
python3 scripts/compare_perf.py

compare_perf.py 输出示例

╔════════════════════════════════════════════════════════════════════════╗
║                    Performance Comparison Report                       ║
╚════════════════════════════════════════════════════════════════════════╝

Metric                           Baseline         Current       Change
───────────────────────────────────────────────────────────────────────────
Orders                             100000          100000            -
Trades                              47886           47886            -

Exec Time                       3753.87ms       3484.37ms        -7.2%
Throughput (orders)               26639/s         28700/s        +7.7%
Throughput (trades)               12756/s         13743/s        +7.7%

───────────────────────────────────────────────────────────────────────────
Timing Breakdown (lower is better):

Metric                           Baseline         Current     Change        OPS
Balance Check                     17.68ms         16.51ms      -6.6%       6.1M
Matching Engine                   36.04ms         35.01ms      -2.8%       2.9M
Settlement                         4.77ms          5.22ms      +9.4%      19.2M
Ledger I/O                      3678.68ms       3411.49ms      -7.3%        29K

───────────────────────────────────────────────────────────────────────────
Latency Percentiles (lower is better):

Metric                           Baseline         Current       Change
Latency MIN                         125ns           125ns        +0.0%
Latency AVG                        37.9µs          34.8µs        -8.2%
Latency P50                         584ns           541ns        -7.4%
Latency P99                       420.2µs         398.9µs        -5.1%
Latency P99.9                      1.63ms          1.24ms       -24.3%
Latency MAX                        9.76ms          3.53ms       -63.9%

───────────────────────────────────────────────────────────────────────────
✅ No significant regressions detected

Summary

本章完成了以下工作：

1. PerfMetrics 结构：收集时间分解和延迟样本
2. 时间分解：Balance Check / Matching / Settlement / Ledger I/O
3. 延迟百分位数：P50 / P99 / P99.9 / Max
4. t2_perf.txt：机器可读的性能基线文件
5. compare_perf.py：对比工具，检测性能回归
6. 关键发现：Ledger I/O 占 98.4%，是主要瓶颈

0x08-a Trading Pipeline Design

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

Core Objective: To design a complete trading pipeline architecture that ensures order persistence, balance consistency, and system recoverability.

This chapter addresses the most critical design issues in a matching engine: Service Partitioning, Data Flow, and Atomicity Guarantees.

1. Why Persistence?

1.1 The Problem Scenario

Suppose the system crashes during matching:

User A sends Buy Order → ME receives & fills → System Crash
                                               ↓
                                        User A's funds deducted
                                        But no trade record
                                        Order Lost!

Consequences of No Persistence:

• Order Loss: User orders vanish.
• Inconsistent State: Funds changed but no record exists.
• Unrecoverable: Upon restart, valid orders are unknown.

1.2 Solution: Persist First, Match Later

User A Buy Order → WAL Persist → ME Match → System Crash
                     ↓             ↓
                Order Saved    Replay & Recover!

2. Unique Ordering

2.1 Why Unique Ordering?

In distributed systems, multiple nodes must agree on order sequence:

Result: Matching results differ between nodes!

2.2 Solution: Single Sequencer + Global Sequence ID

All Orders → Sequencer → Assign Global sequence_id → Persist → Dispatch to ME
              ↓
         Unique Arrival Order

3. Order Lifecycle

3.1 Persist First, Execute Later

┌─────────────────────────────────────────────────────────────────────────┐
│                          Order Lifecycle                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐             │
│   │ Gateway │───▶│Pre-Check│───▶│   WAL   │───▶│   ME    │             │
│   │(Receiver)│    │(Balance) │    │(Persist)│    │ (Match) │             │
│   └─────────┘    └─────────┘    └─────────┘    └─────────┘             │
│        │              │              │              │                   │
│        ▼              ▼              ▼              ▼                   │
│   Receive Order   Insufficient?   Disk Write     Execute Match           │
│                   Early Reject    Assign SeqID   Guaranteed Exec         │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

3.2 Pre-Check: Reducing Invalid Orders

Pre-Check queries UBSCore (User Balance Core Service) for balance info. Read-Only, No Side Effects.

#![allow(unused)]
fn main() {
async fn pre_check(order: Order) -> Result<Order, Reject> {
    // 1. Query UBSCore for balance (Read-Only)
    let balance = ubscore.query_balance(order.user_id, asset);

    // 2. Calculate required amount
    let required = match order.side {
        Buy  => order.price * order.qty / QTY_UNIT,  // quote
        Sell => order.qty,                            // base
    };

    // 3. Balance Check (Read-Only, No Lock)
    if balance.avail < required {
        return Err(Reject::InsufficientBalance);
    }

    // 4. Pass
    Ok(order)
}
// Note: Balance might be consumed by others between Pre-Check and WAL.
// This is allowed; WAL's Balance Lock will handle it.
}

Why Pre-Check?

The Core Flow (WAL + Balance Lock + Matching) is expensive. We must filter garbage orders fast.

Pre-Check Items:

• ✅ Balance Check
• 📋 User Status (Banned?)
• 📋 Format Validation
• 📋 Rate Limiting
• 📋 Risk Rules

3.3 Must Execute Once Persisted

Once an order is persisted, it MUST end in one of these states:

┌─────────────────────┐
│   Order Persisted   │
└─────────────────────┘
           │
           ├──▶ Filled
           ├──▶ PartialFilled
           ├──▶ New (Booked)
           ├──▶ Cancelled
           ├──▶ Expired
           └──▶ Rejected (Insufficient Balance) ← Valid Final State!

❌ Never: Logged but state unknown.

4. WAL: Why it’s the Best Choice?

4.1 What is WAL (Write-Ahead Log)?

WAL is an Append-Only log structure:

┌─────────────────────────────────────────────────────────────────┐
│                          WAL File                               │
├─────────────────────────────────────────────────────────────────┤
│  Entry 1  │  Entry 2  │  Entry 3  │  Entry 4  │  ...  │ ← Append│
│ (seq=1)   │ (seq=2)   │ (seq=3)   │ (seq=4)   │       │         │
└─────────────────────────────────────────────────────────────────┘
                                                          ↑
                                                     Append Only!

4.2 Why WAL for HFT?

Why is WAL fast?

1. Sequential Write vs Random Write:
   • HDD: No seek time (~10ms saved).
   • SSD: Reduces Write Amplification.
   • Result: 10-100x faster.
2. No Transaction Overhead:
   • DB: Txn start, lock, redo log, data page, binlog, commit…
   • WAL: Serialize -> Append -> (Optional) Fsync.
3. Group Commit:
   • Batch multiple writes into one fsync.

#![allow(unused)]
fn main() {
// Group Commit Logic
pub fn flush(&mut self) -> io::Result<()> {
    self.file.write_all(&self.buffer)?;
    self.file.sync_data()?;  // fsync once for N orders
    self.buffer.clear();
    Ok(())
}
}

5. Single Thread + Lock-Free Architecture

5.1 Why Single Thread?

Intuition: Concurrency = Fast. Reality in HFT: Single Thread is Faster.

5.2 Mechanical Sympathy

CPU Cache Hierarchy:

• L1 Cache: ~1ns
• L2 Cache: ~4ns
• RAM: ~100ns

Single Thread Advantage: Data stays in L1/L2 (Hot). No cache line contention.

5.3 LMAX Disruptor Pattern

Originating from LMAX Exchange (6M TPS on single thread):

1. Single Writer (Avoid write contention)
2. Pre-allocated Memory (Avoid GC/malloc)
3. Cache Padding (Avoid false sharing)
4. Batch Consumption

6. Ring Buffer: Inter-Service Communication

6.1 Why Ring Buffer?

6.2 Ring Buffer Principle

      write_idx                       read_idx
          ↓                               ↓
   ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
   │ 8 │ 9 │10 │11 │12 │13 │14 │ 0 │ 1 │ 2 │ ...
   └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
         ↑                               ↑
     New Data                        Consumer

• Fixed size, circular.
• Zero allocation during runtime.
• SPSC (Single Producer Single Consumer) is lock-free.

7. Overall Architecture

7.1 Core Services

7.2 UBSCore Service (User Balance Core)

Single Entry Point for ALL Balance Operations.

Why UBSCore?

• Atomic: Single thread = No Double Spend.
• Audit: Complete trace of all changes.
• Recovery: Single WAL restores state.

Pipeline Role:

1. Write Order WAL (Persist)
2. Lock Balance
   • Success → Forward to ME
   • Fail → Rejected
3. Handle Trade Events (Settlement)
   • Update buyer/seller balances.

7.3 Matching Engine (ME)

ME is Pure Matching. It ignores Balances.

• Does: Maintain OrderBook, Match by Price/Time, Generate Trade Events.
• Does NOT: Check balance, lock funds, persist data.

Trade Event Drive Balance Update: TradeEvent contains {price, qty, user_ids} → sufficient to calculate balance changes.

7.4 Settlement Service

Settlement Persists, does not modify Balances.

• Persist Trade Events, Order Events.
• Write Audit Log (Ledger).

7.5 Architecture Diagram

┌──────────────────────────────────────────────────────────────────────────────────┐
│                         0xInfinity HFT Architecture                               │
├──────────────────────────────────────────────────────────────────────────────────┤
│   Client Orders                                                                   │
│        │                                                                          │
│        ▼                                                                          │
│   ┌──────────────┐                                                                │
│   │   Gateway    │                                                                │
│   └──────┬───────┘                                                                │
│          ▼                                                                        │
│   ┌──────────────┐         query balance                                          │
│   │  Pre-Check   │ ──────────────────────────────▶   UBSCore Service              │
│   └──────┬───────┘                                                                │
│          ▼                                                                        │
│   ┌──────────────┐                                   ┌────────────────────┐       │
│   │ Order Buffer │                                   │  Balance State     │       │
│   └──────┬───────┘                                   │  (RAM, Single Thd) │       │
│          │ Ring Buffer                               └────────────────────┘       │
│          ▼                                                                        │
│   ┌──────────────────────────────────────────┐                                    │
│   │  UBSCore: Order Processing               │       Operations:                  │
│   │  1. Write Order WAL (Persist)            │       - lock / unlock              │
│   │  2. Lock Balance                         │       - spend_frozen               │
│   │     - OK → forward to ME                 │       - deposit                    │
│   │     - Fail → Rejected                    │                                    │
│   └──────────────┬───────────────────────────┘                                    │
│                  │ Ring Buffer (valid orders)                                     │
│                  ▼                                                                │
│   ┌──────────────────────────────────────────┐                                    │
│   │         Matching Engine (ME)             │                                    │
│   │                                          │                                    │
│   │  Pure Matching, Ignore Balance           │                                    │
│   │  Output: Trade Events                    │                                    │
│   └──────────────┬───────────────────────────┘                                    │
│                  │ Ring Buffer (Trade Events)                                     │
│         ┌───────┴────────┐                                                        │
│         ▼                ▼                                                        │
│   ┌───────────┐   ┌─────────────────────────┐                                     │
│   │ Settlement│   │ Balance Update Events   │────▶   Execute Balance Update       │
│   │           │   │ (from Trade Events)     │                                     │
│   │ Persist:  │   └─────────────────────────┘                                     │
│   │ - Trades  │                                                                   │
│   │ - Ledger  │                                                                   │
│   └───────────┘                                                                   │
└───────────────────────────────────────────────────────────────────────────────────┘

7.7 Event Sourcing + Pure State Machine

Order WAL = Single Source of Truth

State(t) = Replay(Order_WAL[0..t])

Any state (Balance, OrderBook) can be 100% reconstructed by replaying the Order WAL.

Pure State Machines:

• UBSCore: Order Events → Balance Events (Deterministic)
• ME: Valid Orders → Trade Events (Deterministic)

Recovery Flow:

1. Load Checkpoint (Snapshot).
2. Replay Order WAL from checkpoint.
3. ME re-matches and generates events.
4. UBSCore applies balance updates.
5. System Restored.

8. Summary

Core Decisions:

• Persist First: WAL ensures recoverability.
• Pre-Check: Filters invalid orders early.
• Single Thread + Lock-Free: Avoids contention, maximizes throughput.
• UBSCore: Centralized, atomic balance management.
• Responsibility Segregation: UBSCore (Money), ME (Match), Settlement (Log).

Refactoring: For the upcoming implementation, we refactored the code structure:

• lib.rs, main.rs, core_types.rs, config.rs
• orderbook.rs, balance.rs, engine.rs
• csv_io.rs, ledger.rs, perf.rs

Next: Detailed implementation of UBSCore and Ring Buffer.

🇨🇳 中文

📦 代码变更: 查看 Diff

核心目的：设计完整的交易流水线架构，确保订单持久化、余额一致性和系统可恢复性。

本章解决撮合引擎最关键的设计问题：服务划分、数据流和原子性保证。

1. 为什么需要持久化？

1.1 问题场景

假设系统在撮合过程中崩溃：

用户 A 发送买单 → ME 接收并成交 → 系统崩溃
                                    ↓
                            用户 A 的钱扣了
                            但没有成交记录
                            订单丢失!

没有持久化的后果：

• 订单丢失：用户下的单消失了
• 状态不一致：资金变动了但没有记录
• 无法恢复：重启后不知道有哪些订单

1.2 解决方案：先持久化，后撮合

用户 A 发送买单 → WAL 持久化 → ME 撮合 → 系统崩溃
                    ↓              ↓
               订单已保存      可以重放恢复!

2. 唯一排序 (Unique Ordering)

2.1 为什么需要唯一排序？

在分布式系统中，多个节点必须对订单顺序达成一致：

结果：两个节点的撮合结果可能不同！

2.2 解决方案：单点排序 + 全局序号

所有订单 → Sequencer → 分配全局 sequence_id → 持久化 → 分发到 ME
              ↓
         唯一的到达顺序

3. 订单生命周期

3.1 先持久化，后执行

┌─────────────────────────────────────────────────────────────────────────┐
│                         订单生命周期                                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐             │
│   │ Gateway │───▶│Pre-Check│───▶│   WAL   │───▶│   ME    │             │
│   │(接收订单)│    │(余额校验)│    │ (持久化)│    │ (撮合) │             │
│   └─────────┘    └─────────┘    └─────────┘    └─────────┘             │
│        │              │              │              │                   │
│        ▼              ▼              ▼              ▼                   │
│    接收订单      余额不足?        写入磁盘        执行撮合               │
│                  提前拒绝        分配seq_id      保证执行               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

3.2 Pre-Check：减少无效订单

Pre-Check 通过查询 UBSCore (User Balance Core Service，用户余额核心服务，详见第 7.2 节) 获取余额信息，只读，无副作用：

#![allow(unused)]
fn main() {
async fn pre_check(order: Order) -> Result<Order, Reject> {
     // 1. 查询 UBSCore 获取余额 (只读查询)
     let balance = ubscore.query_balance(order.user_id, asset);

     // 2. 计算所需金额
     let required = match order.side {
         Buy  => order.price * order.qty / QTY_UNIT,  // quote
         Sell => order.qty,                            // base
     };

     // 3. 余额检查 (只读，不锁定)
     if balance.avail < required {
         return Err(Reject::InsufficientBalance);
     }

     // 4. 检查通过，放行订单到下一阶段
     Ok(order)
}
// 注意：Pre-Check 不锁定余额！
// 余额可能在 Pre-Check 和 WAL 之间被其他订单消耗
// 这是允许的，WAL 后的 Balance Lock 会处理这种情况
}

为什么需要 Pre-Check？

核心流程（WAL 持久化、Balance Lock、撮合）的延迟成本很高。 用户可能提交大量垃圾订单，我们需要最快速地预过滤，减少进入核心流程的订单量。

Pre-Check 可以包含多种快速检查：

• ✅ 余额检查（当前实现）
• 📋 用户状态检查（是否被禁用）
• 📋 订单格式校验
• 📋 频率限制 (Rate Limit)
• 📋 风控规则（未来扩展）

重要：Pre-Check 是“尽力而为“的过滤器，不保证 100% 准确。 通过 Pre-Check 的订单，仍可能在 WAL + Balance Lock 阶段被拒绝。

3.3 一旦持久化，必须完整执行

订单被持久化后，无论发生什么，都必须有以下其中一个结果：

┌─────────────────────┐
│ 订单已持久化         │
└─────────────────────┘
           │
           ├──▶ 成交 (Filled)
           ├──▶ 部分成交 (PartialFilled)
           ├──▶ 挂单中 (New)
           ├──▶ 用户取消 (Cancelled)
           ├──▶ 系统过期 (Expired)
           └──▶ 余额不足被拒绝 (Rejected)  ← 也是合法的终态！

❌ 绝对不能：订单消失 / 状态未知

4. WAL：为什么是最佳选择？

4.1 什么是 WAL (Write-Ahead Log)?

WAL 是一种追加写 (Append-Only) 的日志结构：

┌─────────────────────────────────────────────────────────────────┐
│                          WAL File                               │
├─────────────────────────────────────────────────────────────────┤
│  Entry 1  │  Entry 2  │  Entry 3  │  Entry 4  │  ...  │ ← 追加  │
│ (seq=1)   │ (seq=2)   │ (seq=3)   │ (seq=4)   │       │         │
└─────────────────────────────────────────────────────────────────┘
                                                          ↑
                                                     只追加，不修改

4.2 为什么 WAL 是 HFT 最佳实践？

为什么 WAL 这么快？

1. 顺序写 vs 随机写：
   • 机械硬盘不用寻道。
   • SSD 减少写放大。
   • 结果：快 10-100 倍。
2. 无事务开销：
   • 无需锁、redo log、binlog 等数据库复杂机制。
3. 批量刷盘 (Group Commit)：
   • 合并多次写入一次 fsync。

5. 单线程 + Lock-Free 架构

5.1 为什么选择单线程？

大多数人直觉认为：并发 = 快。但在 HFT 领域，单线程往往更快：

5.2 Mechanical Sympathy

CPU Cache Hierarchy:

• L1 Cache: ~1ns
• L2 Cache: ~4ns
• RAM: ~100ns

单线程优势：数据始终在 L1/L2 缓存中（热数据），无 cache line 争用。

5.3 LMAX Disruptor 模式

这种单线程 + Ring Buffer 的架构源自 LMAX Exchange（伦敦多资产交易所），号称能在单线程上处理 600 万订单/秒：

1. Single Writer (避免写竞争)
2. Pre-allocated Memory (避免 GC/malloc)
3. Cache Padding (避免 false sharing)
4. Batch Consumption

6. Ring Buffer：服务间通信

6.1 为什么使用 Ring Buffer？

服务间通信的选择：

6.2 Ring Buffer 原理

      write_idx                       read_idx
          ↓                               ↓
   ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
   │ 8 │ 9 │ 10│ 11│ 12│ 13│ 14│ 15│ 0 │ 1 │ ...
   └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
         ↑                               ↑
     新数据写入                        消费者读取

• 固定大小，循环使用
• 无需动态分配
• Single Producer, Single Consumer ({SPSC) 可完全无锁

7. 整体架构

7.1 核心服务

7.2 UBSCore Service (User Balance Core)

UBSCore 是所有账户余额操作的唯一入口，单线程执行保证原子性。

应用场景：

1. Write Order WAL (持久化)
2. Lock Balance (锁定)
3. Handle Trade Events (成交后结算)

7.3 Matching Engine (ME)

ME 是纯撮合引擎，不关心余额。

• 负责：维护 OrderBook，撮合，生成 Trade Events。
• 不负责：检查余额，锁定资金，持久化。

Trade Event 驱动余额更新： TradeEvent 包含 {price, qty, user_ids}，足够计算出余额变化。

7.4 Settlement Service

Settlement 负责持久化，不修改余额。

• 持久化 Trade Events，Order Events。
• 写审计日志 (Ledger)。

7.5 完整架构图

┌──────────────────────────────────────────────────────────────────────────────────┐
│                         0xInfinity HFT Architecture                               │
├──────────────────────────────────────────────────────────────────────────────────┤
│   Client Orders                                                                   │
│        │                                                                          │
│        ▼                                                                          │
│   ┌──────────────┐                                                                │
│   │   Gateway    │                                                                │
│   └──────┬───────┘                                                                │
│          ▼                                                                        │
│   ┌──────────────┐         query balance                                          │
│   │  Pre-Check   │ ──────────────────────────────▶   UBSCore Service              │
│   └──────┬───────┘                                                                │
│          ▼                                                                        │
│   ┌──────────────┐                                   ┌────────────────────┐       │
│   │ Order Buffer │                                   │  Balance State     │       │
│   └──────┬───────┘                                   │  (RAM, Single Thd) │       │
│          │ Ring Buffer                               └────────────────────┘       │
│          ▼                                                                        │
│   ┌──────────────────────────────────────────┐                                    │
│   │  UBSCore: Order Processing               │       Operations:                  │
│   │  1. Write Order WAL (持久化)              │       - lock / unlock              │
│   │  2. Lock Balance                         │       - spend_frozen               │
│   │     - OK → forward to ME                 │       - deposit                    │
│   │     - Fail → Rejected                    │                                    │
│   └──────────────┬───────────────────────────┘                                    │
│                  │ Ring Buffer (valid orders)                                     │
│                  ▼                                                                │
│   ┌──────────────────────────────────────────┐                                    │
│   │         Matching Engine (ME)             │                                    │
│   │                                          │                                    │
│   │  纯撮合，不关心 Balance                   │                                    │
│   │  输出: Trade Events                      │                                    │
│   └──────────────┬───────────────────────────┘                                    │
│                  │ Ring Buffer (Trade Events)                                     │
│         ┌───────┴────────┐                                                        │
│         ▼                ▼                                                        │
│   ┌───────────┐   ┌─────────────────────────┐                                     │
│   │ Settlement│   │ Balance Update Events   │────▶   执行余额更新                 │
│   │           │   │ (from Trade Events)     │                                     │
│   │ 持久化:    │   └─────────────────────────┘                                     │
│   │ - Trades  │                                                                   │
│   │ - Ledger  │                                                                   │
│   └───────────┘                                                                   │
└───────────────────────────────────────────────────────────────────────────────────┘

7.7 Event Sourcing + Pure State Machine

Order WAL = Single Source of Truth

State(t) = Replay(Order_WAL[0..t])

只要有 Order WAL，就能恢复整个系统状态！

Pure State Machines:

• UBSCore: Order Events → Balance Events (确定性)
• ME: Valid Orders → Trade Events (确定性)

恢复流程:

1. 加载最近快照 Checkpoint。
2. 重放 Order WAL。
3. 系统恢复到崩溃前状态。

8. Summary

核心设计：

• 先持久化：WAL 保证可恢复性。
• Pre-Check：提前过滤无效订单。
• 单线程 + 无锁：避免锁竞争，最大化吞吐。
• UBSCore：集中式、原子的余额管理。
• 职责分离：UBSCore (钱)，ME (撮合)，Settlement (日志)。

代码重构： 为后续章节准备，我们重构了 src 目录结构，模块化了 main.rs, core_types.rs 等。

下一步：实现 UBSCore 和 Ring Buffer。

0x08-b UBSCore Implementation

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

Objective: From design to implementation: Building a Safety-First Balance Core Service.

In the previous chapter (0x08-a), we designed the full HFT pipeline architecture. Now, it’s time to implement the core components. This chapter covers:

1. Ring Buffer - Lock-free inter-service communication.
2. Write-Ahead Log (WAL) - Order persistence.
3. UBSCore Service - The core balance service.

1. Technology Selection: Safety First

In financial systems, maturity and stability outweigh extreme performance.

1.1 Ring Buffer Selection

Our Choice: crossbeam-queue

Reasons:

• Maintained by Rust core team members.
• Base dependency for tokio, actix, rayon.
• If it has a bug, half the Rust ecosystem collapses.

Financial System Selection Principle: Use what lets you sleep at night.

#![allow(unused)]
fn main() {
use crossbeam_queue::ArrayQueue;

// Create fixed-size ring buffer
let queue: ArrayQueue<OrderMessage> = ArrayQueue::new(1024);

// Producer: Non-blocking push
queue.push(order_msg).unwrap();

// Consumer: Non-blocking pop
if let Some(msg) = queue.pop() {
    process(msg);
}
}

2. Write-Ahead Log (WAL)

WAL is the system’s Single Source of Truth.

2.1 Design Principles

#![allow(unused)]
fn main() {
/// Write-Ahead Log for Orders
///
/// Principles:
/// 1. Append-Only: Sequential I/O, max performance.
/// 2. Group Commit: Batch fsyncs.
/// 3. Monotonic sequence_id: Deterministic replay.
pub struct WalWriter {
    writer: BufWriter<File>,
    next_seq: SeqNum,
    pending_count: usize,
    config: WalConfig,
}
}

2.2 Group Commit Strategy

We choose Every 100 Entries to balance performance and safety:

#![allow(unused)]
fn main() {
pub struct WalConfig {
    pub path: String,
    pub flush_interval_entries: usize,  // Flush every N entries
    pub sync_on_flush: bool,            // Whether to call fsync
}
}

2.3 WAL Entry Format

Currently CSV (readable for dev):

seq_id,timestamp_ns,order_id,user_id,price,qty,side,order_type
1,1702742400000000000,1001,100,85000000000,100000000,Buy,Limit

In production, switch to Binary (54 bytes/entry) for better performance.

3. UBSCore Service

UBSCore is the Single Entry Point for all balance operations.

3.1 Responsibilities

1. Balance State Management: In-memory balance state.
2. Order WAL Writing: Persist orders.
3. Balance Operations: lock/unlock/spend_frozen/deposit.

3.2 Core Structure

#![allow(unused)]
fn main() {
pub struct UBSCore {
    /// User Accounts - Authoritative Balance State
    accounts: FxHashMap<UserId, UserAccount>,
    /// Write-Ahead Log
    wal: WalWriter,
    /// Configuration
    config: TradingConfig,
    /// Pending Orders (Locked but not filled)
    pending_orders: FxHashMap<OrderId, PendingOrder>,
    /// Statistics
    stats: UBSCoreStats,
}
}

3.3 Order Processing Flow

process_order(order):
  │
  ├─ 1. Write to WAL ──────────► Get seq_id
  │
  ├─ 2. Validate order ────────► Check price/qty
  │
  ├─ 3. Get user account ──────► Lookup user
  │
  ├─ 4. Calculate lock amount ─► Buy: price * qty / qty_unit
  │                              Sell: qty
  │
  └─ 5. Lock balance ──────────► Success → Ok(ValidOrder)
                                 Fail    → Err(Rejected)

Implementation:

#![allow(unused)]
fn main() {
pub fn process_order(&mut self, order: Order) -> Result<ValidOrder, OrderEvent> {
    // Step 1: Write to WAL FIRST (persist before any state change)
    let seq_id = self.wal.append(&order)?;

    // Step 2-4: Validate and calculate
    // ...

    // Step 5: Lock balance
    let lock_result = account
        .get_balance_mut(locked_asset_id)
        .and_then(|balance| balance.lock(locked_amount));

    match lock_result {
        Ok(()) => {
            // Track pending order
            self.pending_orders.insert(order.id, PendingOrder { ... });
            Ok(ValidOrder::new(seq_id, order, locked_amount, locked_asset_id))
        }
        Err(_) => Err(OrderEvent::Rejected { ... })
    }
}
}

3.4 Settlement

#![allow(unused)]
fn main() {
pub fn settle_trade(&mut self, event: &TradeEvent) -> Result<(), &'static str> {
    let trade = &event.trade;
    let quote_amount = trade.price * trade.qty / self.config.qty_unit();

    // Buyer: spend USDT, receive BTC
    buyer.get_balance_mut(quote_id)?.spend_frozen(quote_amount)?;
    buyer.get_balance_mut(base_id)?.deposit(trade.qty)?;

    // Seller: spend BTC, receive USDT
    seller.get_balance_mut(base_id)?.spend_frozen(trade.qty)?;
    seller.get_balance_mut(quote_id)?.deposit(quote_amount)?;

    Ok(())
}
}

4. Message Types

Services communicate via defined message types:

#![allow(unused)]
fn main() {
// Gateway → UBSCore
pub struct OrderMessage {
    pub seq_id: SeqNum,
    pub order: Order,
    // ...
}

// UBSCore → ME
pub struct ValidOrder {
    pub seq_id: SeqNum,
    pub order: Order,
    pub locked_amount: u64,
    // ...
}

// ME → UBSCore + Settlement
pub struct TradeEvent {
    pub trade: Trade,
    pub taker_order_id: OrderId,
    pub maker_order_id: OrderId,
    // ...
}
}

5. Integration & Usage

5.1 CLI Arguments

# Original Pipeline
cargo run --release

# UBSCore Pipeline (Enable WAL)
cargo run --release -- --ubscore

5.2 Performance Comparison

Analysis:

• WAL introduces ~5% overhead.
• Acceptable cost for safety.
• Main bottleneck remains Ledger I/O.

6. Tests

6.1 Unit Tests

cargo test
# 31 tests passing

6.2 E2E Tests

sh scripts/test_e2e.sh
# ✅ All tests passed!

7. New Files

8. Key Learnings

8.1 Safety First

• Maturity > Performance
• Auditable > Rapid Dev

8.2 WAL is Single Source of Truth

All state = f(WAL). Foundation for Disaster Recovery and Audit.

8.3 Single Thread Advantage

UBSCore uses single thread for natural atomicity (no locking needed for balance ops) and predictable latency.

9. Critical Bug Fix: Cost Calculation Overflow

9.1 The Issue

Testing with --ubscore revealed 1032 rejected orders that were accepted in the legacy mode.

9.2 Root Cause

Overflow in price * qty (u64).

Example Order #21:

• Price: 84,956.01 USDT (6 decimals) -> 84,956,010,000
• Qty: 2.56 BTC (8 decimals) -> 256,284,400
• Product: 2.177 × 10^19 > u64::MAX

9.3 Why Legacy Mode Passed?

Release Code Wrapping Arithmetic: Legacy code cost = price * qty wrapped around, resulting in a much smaller, incorrect value. users were locked for 33k USDT but bought 217k USDT worth of BTC!

9.4 The Fix

#![allow(unused)]
fn main() {
// Use u128 for intermediate calculation
let cost_128 = (self.price as u128) * (self.qty as u128) / (qty_unit as u128);
if cost_128 > u64::MAX as u128 {
    Err(CostError::Overflow)
}
}

9.5 Configuration Issue

USDT with 6 decimals is risky. Recommended: 2 decimals. Binance uses 2 decimals for USDT price.

10. Improvement: Ledger Integrity & Determinism

10.1 Incomplete Ledger

Current Ledger lacks Deposit, Lock, Unlock, SpendFrozen. Only tracks Settlement.

10.2 Pipeline Non-Determinism

Pipeline concurrency means Lock and Settlement events interleave non-deterministically. Snapshot comparison is impossible.

10.3 Solution: Version Space Separation

Separate version counters for Lock events and Settle events.

Validation Strategy: Verify the Final Set of events, sorted by their respective versions/source IDs, rather than checking snapshot consistency at arbitrary times.

11. Design Discussion: Causal Chain

UBSCore has inputs from OrderQueue and TradeQueue. Interleaving is random.

Solution:

1. OrderQueue strictly follows order_seq_id.
2. TradeQueue strictly follows trade_id.
3. Link every Balance Event to its source (order_seq_id or trade_id).
4. This forms a Causal Chain for audit.

#![allow(unused)]
fn main() {
struct BalanceEvent {
    // ...
    source_type: SourceType, // Order | Trade
    source_id: u64,          // order_seq_id | trade_id
}
}

This allows offline verification: Lock(source=Order N) must exist if Order N exists. Settle(source=Trade M) must exist if Trade M exists.

12. Next Steps (0x08-c)

1. Implement Version Space Separation.
2. Expand BalanceEvent with causal links.
3. Integrate Ring Buffer.
4. Develop Causal Chain Audit Tools.

🇨🇳 中文

📦 代码变更: 查看 Diff

从设计到实现：构建安全第一的余额核心服务

概述

在上一章（0x08-a）中，我们设计了完整的 HFT 交易流水线架构。现在，是时候实现核心组件了。本章我们将构建：

1. Ring Buffer - 服务间无锁通信
2. Write-Ahead Log (WAL) - 订单持久化
3. UBSCore Service - 余额核心服务

1. 技术选型：安全第一

在金融系统中，成熟稳定比极致性能更重要。

1.1 Ring Buffer 选型

我们的选择：crossbeam-queue

理由：

• Rust 核心团队成员参与维护
• 被 tokio, actix, rayon 作为底层依赖
• 如果它有 Bug，半个 Rust 生态都会崩

金融系统选型原则：用它睡得着觉。

#![allow(unused)]
fn main() {
use crossbeam_queue::ArrayQueue;

// 创建固定容量的 ring buffer
let queue: ArrayQueue<OrderMessage> = ArrayQueue::new(1024);

// 生产者：非阻塞 push
queue.push(order_msg).unwrap();

// 消费者：非阻塞 pop
if let Some(msg) = queue.pop() {
    process(msg);
}
}

2. Write-Ahead Log (WAL)

WAL 是系统的唯一事实来源 (Single Source of Truth)。

2.1 设计原则

#![allow(unused)]
fn main() {
/// Write-Ahead Log for Orders
///
/// 设计原则:
/// 1. 追加写 (Append-Only) - 顺序 I/O，最大化性能
/// 2. Group Commit - 批量刷盘，减少 fsync 次数
/// 3. 单调递增 sequence_id - 保证确定性重放
pub struct WalWriter {
    writer: BufWriter<File>,
    next_seq: SeqNum,
    pending_count: usize,
    config: WalConfig,
}
}

2.2 Group Commit 策略

我们选择 每 100 条刷盘，在性能和安全间取得平衡：

#![allow(unused)]
fn main() {
pub struct WalConfig {
    pub path: String,
    pub flush_interval_entries: usize,  // 每 N 条刷盘
    pub sync_on_flush: bool,            // 是否调用 fsync
}
}

2.3 WAL 条目格式

当前使用 CSV 格式（开发阶段可读性好）：

seq_id,timestamp_ns,order_id,user_id,price,qty,side,order_type
1,1702742400000000000,1001,100,85000000000,100000000,Buy,Limit

生产环境可切换为二进制格式（54 bytes/entry）以提升性能。

3. UBSCore Service

UBSCore 是所有余额操作的唯一入口。

3.1 职责

1. Balance State Management - 内存中的余额状态
2. Order WAL Writing - 持久化订单
3. Balance Operations - lock/unlock/spend_frozen/deposit

3.2 核心结构

#![allow(unused)]
fn main() {
pub struct UBSCore {
    /// 用户账户 - 权威余额状态
    accounts: FxHashMap<UserId, UserAccount>,
    /// Write-Ahead Log
    wal: WalWriter,
    /// 交易配置
    config: TradingConfig,
    /// 待处理订单（已锁定但未成交）
    pending_orders: FxHashMap<OrderId, PendingOrder>,
    /// 统计信息
    stats: UBSCoreStats,
}
}

3.3 订单处理流程

process_order(order):
  │
  ├─ 1. Write to WAL ──────────► 获得 seq_id
  │
  ├─ 2. Validate order ────────► 价格/数量检查
  │
  ├─ 3. Get user account ──────► 查找用户
  │
  ├─ 4. Calculate lock amount ─► Buy: price * qty / qty_unit
  │                              Sell: qty
  │
  └─ 5. Lock balance ──────────► Success → Ok(ValidOrder)
                                 Fail    → Err(Rejected)

代码实现：

#![allow(unused)]
fn main() {
pub fn process_order(&mut self, order: Order) -> Result<ValidOrder, OrderEvent> {
    // Step 1: Write to WAL FIRST (persist before any state change)
    let seq_id = self.wal.append(&order)?;

    // Step 2-4: Validate and calculate
    // ...

    // Step 5: Lock balance
    let lock_result = account
        .get_balance_mut(locked_asset_id)
        .and_then(|balance| balance.lock(locked_amount));

    match lock_result {
        Ok(()) => {
            // Track pending order
            self.pending_orders.insert(order.id, PendingOrder { ... });
            Ok(ValidOrder::new(seq_id, order, locked_amount, locked_asset_id))
        }
        Err(_) => Err(OrderEvent::Rejected { ... })
    }
}
}

3.4 成交结算

#![allow(unused)]
fn main() {
pub fn settle_trade(&mut self, event: &TradeEvent) -> Result<(), &'static str> {
    let trade = &event.trade;
    let quote_amount = trade.price * trade.qty / self.config.qty_unit();

    // Buyer: spend USDT, receive BTC
    buyer.get_balance_mut(quote_id)?.spend_frozen(quote_amount)?;
    buyer.get_balance_mut(base_id)?.deposit(trade.qty)?;

    // Seller: spend BTC, receive USDT
    seller.get_balance_mut(base_id)?.spend_frozen(trade.qty)?;
    seller.get_balance_mut(quote_id)?.deposit(quote_amount)?;

    Ok(())
}
}

4. 消息类型

服务间通过明确定义的消息类型通信：

#![allow(unused)]
fn main() {
// Gateway → UBSCore
pub struct OrderMessage {
    pub seq_id: SeqNum,
    pub order: Order,
    // ...
}

// UBSCore → ME
pub struct ValidOrder {
    pub seq_id: SeqNum,
    pub order: Order,
    pub locked_amount: u64,
    // ...
}

// ME → UBSCore + Settlement
pub struct TradeEvent {
    pub trade: Trade,
    pub taker_order_id: OrderId,
    pub maker_order_id: OrderId,
    // ...
}
}

5. 集成与使用

5.1 命令行参数

# 原始流水线
cargo run --release

# UBSCore 流水线（启用 WAL）
cargo run --release -- --ubscore

5.2 性能对比

分析：

• WAL 写入引入约 5% 的开销
• 这是可接受的代价，换取了数据安全性
• 主要瓶颈仍是 Ledger I/O（下一章优化目标）

6. 测试

6.1 单元测试

cargo test
# 31 tests passing

6.2 E2E 测试

sh scripts/test_e2e.sh
# ✅ All tests passed!

7. 新增文件

8. 关键学习

8.1 安全第一

• 成熟稳定 > 极致性能
• 可审计 > 快速开发
• 用它睡得着觉 是选型的最高标准

8.2 WAL 是唯一事实来源

All state = f(WAL)。任何时刻，系统状态都可以从 WAL 100% 重建。这也是灾难恢复和审计合规的基础。

8.3 单线程是优势

UBSCore 选择单线程不是因为简单，而是因为：

• 自然的原子性（无锁）
• 不可能双重支付
• 可预测的延迟

9. 重要 Bug 修复：Cost 计算溢出

9.1 问题发现

在实现 UBSCore 并运行 --ubscore 模式测试时，发现了 1032 个订单被拒绝，而传统模式全部接受。

9.2 根本原因

Cost 计算时 price * qty 溢出 u64。

订单 #21:

• price = 84,956,010,000 (84956.01 USDT，6位精度)
• qty = 256,284,400 (2.562844 BTC，8位精度)
• price * qty = 2.177 × 10^19 > u64::MAX

9.3 传统模式为什么没报错？

Release 模式的 wrapping arithmetic！ 传统模式下，溢出后值变小，虽然通过了检查，但是锁定的金额严重不足！这是一个巨大的金融漏洞。

9.4 修复方案

#![allow(unused)]
fn main() {
// 使用 u128 进行中间计算
let cost_128 = (self.price as u128) * (self.qty as u128) / (qty_unit as u128);
if cost_128 > u64::MAX as u128 {
    Err(CostError::Overflow)
}
}

9.5 配置问题：USDT 精度过高

USDT 使用 6 位精度导致溢出风险。建议使用 2 位精度（Binance 标准）。

10. 待改进：Ledger 完整性与确定性

10.1 当前 Ledger 不完整

当前 Ledger 缺失 Deposit, Lock, Unlock, SpendFrozen 等操作。

10.2 Pipeline 模式的确定性问题

由于 Ring Buffer 并行处理，Lock 和 Settle 事件的交错顺序不固定，导致无法通过快照对比来验证一致性。

10.3 解决方案：分离 Version 空间

为每种事件类型维护独立的 version：

验证策略： 不再验证任意时刻的快照，而是验证处理完成后的最终事件集合（按各自 Version 排序）。

11. 设计讨论全记录

11.1 因果链设计

UBSCore 有两个输入源：OrderQueue 和 TradeQueue。 为了审计，我们建立了因果链：

#![allow(unused)]
fn main() {
struct BalanceEvent {
    // ...
    source_type: SourceType, // Order | Trade
    source_id: u64,          // order_seq_id | trade_id
}
}

这不仅解决了审计问题，还让我们可以快速定位问题源头：Lock 必定对应一个 Order，Settle 必定对应一个 Trade。

12. 下一章任务 (0x08-c)

1. 实现分离 Version 空间 - lock_version / settle_version
2. 扩展 BalanceEvent - 添加 event_type, version, source_id
3. Ring Buffer 集成
4. 因果链审计工具

0x08-c Complete Event Flow & Verification

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

Core Objective: Implement a complete Event Sourcing architecture, verify equivalence with the legacy version, and upgrade the baseline.

Problems Identified

In the previous chapter (0x08-b), we implemented the UBSCore service but identified several issues:

1. Incomplete Ledger

The current Ledger only records settlement operations (Credit/Debit), missing other critical balance changes:

2. Pipeline Determinism Issue

With a multi-stage Ring Buffer pipeline, the interleaving order of Lock and Settle events is non-deterministic:

Run 1: [Lock1, Lock2, Lock3, Settle1, Settle2, Settle3]
Run 2: [Lock1, Settle1, Lock2, Settle2, Lock3, Settle3]

Result: Final state is identical, but the intermediate version sequence differs. Direct diff verification fails.

Objectives

1. Implement Separate Version Spaces

#![allow(unused)]
fn main() {
struct Balance {
    avail: u64,
    frozen: u64,
    lock_version: u64,    // Increments only on lock/unlock
    settle_version: u64,  // Increments only on settle
}
}

2. Expand BalanceEvent

#![allow(unused)]
fn main() {
struct BalanceEvent {
    user_id: u64,
    asset_id: u32,
    event_type: EventType,  // Deposit | Lock | Unlock | Settle
    version: u64,           // Increments within strict version space
    source_type: SourceType,// Order | Trade | External
    source_id: u64,         // order_seq_id | trade_id | ref_id
    delta: i64,
    avail_after: u64,
    frozen_after: u64,
}
}

3. Record ALL Balance Operations

Order(seq=5) ──Trigger──→ Lock(buyer USDT, lock_version=1)
     │
     └──→ Trade(id=3)
              │
              ├──Trigger──→ Settle(buyer: -USDT, +BTC, settle_version=1)
              └──Trigger──→ Settle(seller: -BTC, +USDT, settle_version=1)

4. Verify Equivalence & Upgrade Baseline

Ensure the refactored system produces the exact same final state as the pre-refactor version.

Implementation Progress

Phase 1: Separate Version Spaces ✅ Done

Goal: Solve Pipeline Determinism.

1.1 Modify Balance Struct

#![allow(unused)]
fn main() {
// src/balance.rs
pub struct Balance {
    avail: u64,
    frozen: u64,
    lock_version: u64,    // lock/unlock/deposit/withdraw
    settle_version: u64,  // spend_frozen/deposit
}
}

1.2 Version Increment Logic

1.3 Equivalence Verification ✅

Script: scripts/verify_baseline_equivalence.py

$ python3 scripts/verify_baseline_equivalence.py

╔════════════════════════════════════════════════════════════╗
║     Baseline Equivalence Verification                      ║
╚════════════════════════════════════════════════════════════╝
...
=== Step 3: Compare avail and frozen values ===
✅ EQUIVALENT: avail and frozen values are IDENTICAL

Phase 2: Expand BalanceEvent ✅ Done

Goal: Full Event Sourcing.

2.1 Event Types & Structure

Implemented in src/messages.rs:

#![allow(unused)]
fn main() {
pub enum BalanceEventType { Deposit, Withdraw, Lock, Unlock, Settle }
pub enum SourceType { Order, Trade, External }

pub struct BalanceEvent {
    pub user_id: u64,
    pub asset_id: u32,
    pub event_type: BalanceEventType,
    pub version: u64,
    pub source_type: SourceType,
    pub source_id: u64,
    pub delta: i64,
    // ...
}
}

Phase 3: Record All Operations in Ledger ✅ Done

Goal: Every balance change is recorded.

3.1 Event Log File

UBSCore mode generates output/t2_events.csv:

user_id,asset_id,event_type,version,source_type,source_id,delta,avail_after,frozen_after
655,2,lock,2,order,1,-3315478,996684522,3315478
96,2,settle,2,trade,1,-92889,999907111,0
604,1,deposit,1,external,1,10000000000,10000000000,0

3.2 Recorded Operations

3.3 Event Stats

Total events: 293,544
  Deposit events: 2,000
  Lock events: 100,000
  Settle events: 191,544

Phase 4: Validation Tests ✅ Done

Goal: Verify Event Correctness.

4.1 Event Correctness Verification

scripts/verify_balance_events.py - 7 Checks:

4.2 Events Baseline Verification

scripts/verify_events_baseline.py:

$ python3 scripts/verify_events_baseline.py
...
Comparing by event type...
  deposit: output=2000, baseline=2000 ✅
  lock: output=100000, baseline=100000 ✅
  settle: output=191544, baseline=191544 ✅

╔════════════════════════════════════════════════════════════╗
║     ✅ Events match baseline!                             ║
╚════════════════════════════════════════════════════════════╝

4.3 Full E2E Test

Run scripts/test_ubscore_e2e.sh:

$ bash scripts/test_ubscore_e2e.sh

=== Step 1: Run with UBSCore mode ===
...
=== Step 2: Verify standard baselines ===
  ✅ All MATCH

=== Step 3: Verify balance events correctness ===
  ✅ All 7 checks passed!

=== Step 4: Verify events baseline ===
  ✅ Events match baseline!

Baseline Files

Next Steps

• 0x08-d: Multi-threaded Pipeline: Implement Ring Buffer to connect services.
• 0x09: Multi-Symbol Support: Scale to multiple trading pairs.

References

• Event Sourcing
• LMAX Disruptor

🇨🇳 中文

📦 代码变更: 查看 Diff

核心目标：实现完整的事件溯源架构，验证与旧版本的等效性，升级 baseline。

本章问题

上一章（0x08-b）我们实现了 UBSCore 服务，但发现了几个问题：

1. Ledger 不完整

当前 Ledger 只记录结算操作（Credit/Debit），缺失其他余额变更：

2. Pipeline 确定性问题

当采用 Ring Buffer 多阶段 Pipeline 时，Lock 和 Settle 的交错顺序不确定：

运行 1: [Lock1, Lock2, Lock3, Settle1, Settle2, Settle3]
运行 2: [Lock1, Settle1, Lock2, Settle2, Lock3, Settle3]

最终状态相同，但中间 version 序列不同 → 无法直接 diff 验证。

本章目标

1. 实现分离 Version 空间

#![allow(unused)]
fn main() {
struct Balance {
    avail: u64,
    frozen: u64,
    lock_version: u64,    // 只在 lock/unlock 时递增
    settle_version: u64,  // 只在 settle 时递增
}
}

2. 扩展 BalanceEvent

#![allow(unused)]
fn main() {
struct BalanceEvent {
    user_id: u64,
    asset_id: u32,
    event_type: EventType,  // Deposit | Lock | Unlock | Settle
    version: u64,           // 在对应 version 空间内递增
    source_type: SourceType,// Order | Trade | External
    source_id: u64,         // order_seq_id | trade_id | ref_id
    delta: i64,
    avail_after: u64,
    frozen_after: u64,
}
}

3. 记录所有余额操作

Order(seq=5) ──触发──→ Lock(buyer USDT, lock_version=1)
     │
     └──→ Trade(id=3)
              │
              ├──触发──→ Settle(buyer: -USDT, +BTC, settle_version=1)
              └──触发──→ Settle(seller: -BTC, +USDT, settle_version=1)

4. 验证等效性并升级 Baseline

确保重构后的系统与重构前产生相同的最终状态。

实现进度

Phase 1: 分离 Version 空间 ✅ 已完成

目标：解决 Pipeline 确定性问题

1.1 修改 Balance 结构

#![allow(unused)]
fn main() {
// src/balance.rs
pub struct Balance {
    avail: u64,
    frozen: u64,
    lock_version: u64,    // lock/unlock/deposit/withdraw 操作递增
    settle_version: u64,  // spend_frozen/deposit 操作递增
}
}

1.2 Version 递增逻辑

1.3 等效性验证 ✅

验证脚本：scripts/verify_baseline_equivalence.py

$ python3 scripts/verify_baseline_equivalence.py

╔════════════════════════════════════════════════════════════╗
║     Baseline Equivalence Verification                      ║
╚════════════════════════════════════════════════════════════╝
...
=== Step 3: Compare avail and frozen values ===
✅ EQUIVALENT: avail and frozen values are IDENTICAL

Phase 2: 扩展 BalanceEvent ✅ 已完成

目标：完整的事件溯源

2.1 事件类型和结构

已在 src/messages.rs 中实现：

#![allow(unused)]
fn main() {
pub enum BalanceEventType { Deposit, Withdraw, Lock, Unlock, Settle }
pub enum SourceType { Order, Trade, External }

pub struct BalanceEvent {
    pub user_id: u64,
    pub asset_id: u32,
    pub event_type: BalanceEventType,
    pub version: u64,
    pub source_type: SourceType,
    pub source_id: u64,
    pub delta: i64,
    // ...
}
}

Phase 3: Ledger 记录所有操作 ✅ 已完成

目标：每个余额变更都有记录

3.1 事件日志文件

UBSCore 模式下生成 output/t2_events.csv：

user_id,asset_id,event_type,version,source_type,source_id,delta,avail_after,frozen_after
655,2,lock,2,order,1,-3315478,996684522,3315478
96,2,settle,2,trade,1,-92889,999907111,0
604,1,deposit,1,external,1,10000000000,10000000000,0

3.2 当前记录的操作

3.3 事件统计

Total events: 293,544
  Deposit events: 2,000
  Lock events: 100,000
  Settle events: 191,544

Phase 4: 验证测试 ✅ 已完成

目标：验证事件正确性

4.1 事件正确性验证

scripts/verify_balance_events.py - 7 项检查：

4.2 Events Baseline 验证

scripts/verify_events_baseline.py:

$ python3 scripts/verify_events_baseline.py
...
Comparing by event type...
  deposit: output=2000, baseline=2000 ✅
  lock: output=100000, baseline=100000 ✅
  settle: output=191544, baseline=191544 ✅

╔════════════════════════════════════════════════════════════╗
║     ✅ Events match baseline!                             ║
╚════════════════════════════════════════════════════════════╝

4.3 完整 E2E 测试

运行 scripts/test_ubscore_e2e.sh：

$ bash scripts/test_ubscore_e2e.sh

=== Step 1: Run with UBSCore mode ===
...
=== Step 2: Verify standard baselines ===
  ✅ All MATCH

=== Step 3: Verify balance events correctness ===
  ✅ All 7 checks passed!

=== Step 4: Verify events baseline ===
  ✅ Events match baseline!

Baseline 文件

下一步

• 0x08-d: 多线程 Pipeline - 实现 Ring Buffer 连接各服务
• 0x09: 多 Symbol 支持 - 扩展到多交易对

参考

• Event Sourcing - 事件溯源模式
• LMAX Disruptor - Ring Buffer 架构原型

0x08-d Complete Order Lifecycle & Cancel Optimization

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

Core Objective: Implement full order lifecycle management (including Cancel and Refund), design a dual-track testing framework, and analyze performance bottlenecks.

1. Feature Implementation Overview

In this chapter, we completed the following core features to equip the trading engine with full order processing capabilities:

1.1 Order Events & State Management

Implemented complete OrderEvent enum and CSV logging.

OrderStatus (src/models.rs): Follows Binance-style Screaming Snake Case.

#![allow(unused)]
fn main() {
pub enum OrderStatus {
    NEW,              // Booked
    PARTIALLY_FILLED, 
    FILLED,           
    CANCELED,         // User Cancelled
    REJECTED,         // Risk Check Failed
    EXPIRED,          // System Expired
}
}

OrderEvent (src/messages.rs): Used for Event Sourcing and Audit Logs.

CSV Log Format (output/t2_order_events.csv):

event_type,order_id,user_id,seq_id,filled_qty,remaining_qty,price,reason
accepted,1,100,101,,,,
rejected,3,102,103,,,,insufficient_balance
partial_filled,1,100,,5000,1000,,
filled,1,100,,0,,85000,
cancelled,5,100,,,2000,,

1.2 Cancel Workflow

1. Parsing: scripts/csv_io.rs supports action=cancel.
2. Removal: MatchingEngine calls OrderBook::remove_order_by_id.
3. Unlock: UBSCore generates Unlock event to refund frozen funds.
4. Logging: Record Cancelled event.

2. Dual-Track Testing Framework

To guarantee baseline stability while adding new features:

2.1 Regression Baseline

• Dataset: fixtures/orders.csv (100k orders, Place only).
• Script: scripts/test_e2e.sh
• Goal: Ensure no performance regression for legacy flows.

2.2 Feature Testing

• Dataset: fixtures/test_with_cancel/orders.csv (1M orders, 30% Cancel).
• Script: scripts/test_cancel.sh
• Goal: Verify lifecycle closure (Lock = Settle + Unlock).

3. Major Performance Issue

When scaling Cancel tests from 1,000 to 1,000,000 orders, we hit a severe performance wall.

3.1 Symptoms

• Baseline (100k Place): ~3 seconds.
• Cancel Test (1M Place+Cancel): > 7 minutes (430s).
• Bottleneck: Matching Engine consumes 98% CPU.

3.2 Root Cause Analysis

The culprit is OrderBook::remove_order_by_id:

#![allow(unused)]
fn main() {
// src/orderbook.rs
pub fn remove_order_by_id(&mut self, order_id: u64) -> Option<InternalOrder> {
    // Scan ALL price levels -> Scan ALL orders in level
    for (key, orders) in self.bids.iter_mut() {
        if let Some(pos) = orders.iter().position(|o| o.order_id == order_id) {
            // ...
        }
    }
    // Scan asks...
}
}

• Complexity: O(N).
• Worst Case: With 500k orders piled up in the book, executing 300k cancels means 150 billion comparisons.

3.3 Solution (Next Step)

Introduce Order Index:

• Structure: HashMap<OrderId, (Price, Side)>.
• Complexity: Reduces Cancel from O(N) to O(1).

4. Verification Scripts

1. verify_balance_events.py:

   • Added Check 8: Verify Frozen Balance history consistency.
   • Verify Unlock events correctly release funds.

2. verify_order_events.py:

   • Verify every Accepted order has a final state.
   • Verify Cancelled orders correspond to existing Accepted orders.

5. Summary

We implemented full order lifecycle management and established a rigorous testing framework. Crucially, mass stress testing exposed a Big O algorithm defect in the cancel logic, setting the stage for the next optimization iteration.

🇨🇳 中文

📦 代码变更: 查看 Diff

核心目标：实现订单全生命周期管理（含撤单、退款），设计双轨制测试框架，并深入分析引入的性能瓶颈。

1. 功能实现概览

在本章中，我们完成了以下核心功能，使交易引擎具备了完整的订单处理能力：

1.1 订单事件与状态管理

实现了完整的 OrderEvent 枚举与 CSV 日志记录。

OrderStatus (src/models.rs): 注意遵循 Binance 风格的 Screaming Snake Case。

#![allow(unused)]
fn main() {
pub enum OrderStatus {
    NEW,              // 挂单中
    PARTIALLY_FILLED, // 部分成交
    FILLED,           // 完全成交
    CANCELED,         // 用户撤单 (注意拼写 CANCELED)
    REJECTED,         // 风控拒绝
    EXPIRED,          // 系统过期
}
}

OrderEvent (src/messages.rs): 用于 Event Sourcing 和审计日志。

CSV 日志格式 (output/t2_order_events.csv): 实际代码实现的列顺序如下：

event_type,order_id,user_id,seq_id,filled_qty,remaining_qty,price,reason
accepted,1,100,101,,,,
rejected,3,102,103,,,,insufficient_balance
partial_filled,1,100,,5000,1000,,
filled,1,100,,0,,85000,
cancelled,5,100,,,2000,,

1.2 撤单流程 (Cancel Workflow)

实现了 cancel 动作的处理流程：

1. 输入解析: scripts/csv_io.rs 支持新旧两种 CSV 格式。
   • 新格式: order_id,user_id,action,side,price,qty (支持 action=cancel)。
2. 撮合移除: MatchingEngine 调用 OrderBook::remove_order_by_id 移除订单。
3. 资金解锁: UBSCore 生成 Unlock 事件，返还冻结资金。
4. 事件记录: 记录 Cancelled 事件。

2. 双轨制测试框架

为了在引入新功能的同时保证原有基准不被破坏，我们设计了双轨制测试策略：

2.1 原始基准 (Regression Baseline)

• 数据集: fixtures/orders.csv (10万订单，仅 Place)。
• 脚本: scripts/test_e2e.sh
• 目的: 确保传统撮合性能不回退，验证核心正确性。
• 原则: 保持基准稳定 (非必要不修改，除非格式升级或重大调整)。

2.2 新功能测试 (Feature Testing)

• 数据集: fixtures/test_with_cancel/orders.csv (100万订单，含30% Cancel)。
• 脚本: scripts/test_cancel.sh
• 验证:
  • verify_balance_events.py: 验证资金守恒 (Lock = Settle + Unlock)。
  • verify_order_events.py: 验证订单生命周期闭环。

3. 重大性能问题分析 (Major Issue)

在将撤单测试规模从 1000 扩大到 100万 时，我们发现了一个严重的性能崩塌现象。

3.1 现象

• 基准测试 (10万 Place): 耗时 ~3秒。
• 撤单测试 (100万 Place+Cancel): 耗时 超过 7分钟 (430秒)。
• 瓶颈定位: Matching Engine 耗时占比 98%。

3.2 原因深入分析

通过代码审查，我们发现瓶颈在于 OrderBook::remove_order_by_id 的实现：

#![allow(unused)]
fn main() {
// src/orderbook.rs
pub fn remove_order_by_id(&mut self, order_id: u64) -> Option<InternalOrder> {
    // 遍历卖单簿的所有价格层级 --> 遍历每个层级的所有订单
    for (key, orders) in self.bids.iter_mut() {
        if let Some(pos) = orders.iter().position(|o| o.order_id == order_id) {
            // ...
        }
    }
    // 遍历买单簿...
}
}

• 复杂度: O(N)，其中 N 是当前 OrderBook 中的订单总数。
• 数据分布恶化: 在 test_with_cancel 数据集中，由于缺乏激进的“吃单”逻辑，大量订单堆积在撮合簿中（未成交）。假设盘口堆积了 50万 订单。
• 计算量: 执行 30万 次撤单，每次遍历 50万 数据 = 1500亿次 CPU 比较操作。

这解释了为什么系统在处理大规模撤单时速度极慢。

3.3 解决方案 (Next Step)

为了解决此问题，必须引入订单索引 (Order Index)：

• 结构: HashMap<OrderId, (Price, Side)>。
• 优化后复杂度: 撤单查找从 O(N) 降为 O(1)。

4. 验证脚本

我们提供了两个 Python脚本用于验证逻辑正确性：

1. verify_balance_events.py:

   • 新增 Check 8: 验证 Frozen Balance 的历史一致性。
   • 验证 Unlock 事件是否正确释放了资金。

2. verify_order_events.py:

   • 验证所有 Accepted 订单最终都有终态 (Filled/Cancelled/Rejected)。
   • 验证 Cancelled 订单真的对应了相应的 Accepted 事件。

5. 总结

本章不仅完成了功能的开发，更重要的是建立了数据隔离的测试体系，并通过大规模压测暴露了算法复杂度缺陷。这为下一步的持续迭代奠定了坚实基础。

0x08-e Performance Profiling & Optimization

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

Background: After introducing Cancel, execution time exploded from ~30s to 7+ minutes. We need to identify and fix the issue.

Goal:

1. Establish architecture-level profiling to pinpoint bottlenecks.
2. Fix the identified O(N) issues.
3. Verify improvements with data.

1. Symptoms

Performance collapsed after adding Cancel:

• Execution Time: ~30s → 7+ minutes
• Throughput: ~34k ops/s → ~3k ops/s

Hypothesis:

• Is it the O(N) Cancel scan?
• VecDeque removal overhead?
• Something else?

Hypothesis implies guessing. Profiling provides facts.

2. Optimization 1: Order Index

2.1 The Problem

Cancelling requires looking up an order. The naive remove_order_by_id iterates the entire book:

#![allow(unused)]
fn main() {
// Before: O(N) full scan
pub fn remove_order_by_id(&mut self, order_id: u64) -> Option<InternalOrder> {
    for (key, orders) in self.bids.iter_mut() {
        if let Some(pos) = orders.iter().position(|o| o.order_id == order_id) {
            // ...
        }
    }
    // Scan asks...
}
}

2.2 The Solution

Introduce order_index: FxHashMap<OrderId, (Price, Side)> for O(1) lookup.

#![allow(unused)]
fn main() {
pub struct OrderBook {
    asks: BTreeMap<u64, VecDeque<InternalOrder>>,
    bids: BTreeMap<u64, VecDeque<InternalOrder>>,
    order_index: FxHashMap<u64, (u64, Side)>,  // New
    trade_id_counter: u64,
}
}

2.3 Index Maintenance

2.4 Optimized Implementation

#![allow(unused)]
fn main() {
pub fn remove_order_by_id(&mut self, order_id: u64) -> Option<InternalOrder> {
    // O(1) Lookup
    let (price, side) = self.order_index.remove(&order_id)?;
    
    // O(log n) Find level
    let (book, key) = match side {
        Side::Buy => (&mut self.bids, u64::MAX - price),
        Side::Sell => (&mut self.asks, price),
    };
    
    // O(k) Find in level (k is small)
    let orders = book.get_mut(&key)?;
    let pos = orders.iter().position(|o| o.order_id == order_id)?;
    let order = orders.remove(pos)?;
    
    if orders.is_empty() {
        book.remove(&key);
    }
    
    Some(order)
}
}

2.5 Result 1

Huge improvement! But 87s for 1.3M orders is still slow (15k ops/s). Further analysis is needed.

3. Architecture Profiling

3.1 Design

Measure time at architectural stages:

Order Input
    │
    ▼
┌─────────────────┐
│  1. Pre-Trade   │  ← UBSCore: WAL + Balance Lock
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  2. Matching    │  ← Pure ME: process_order
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  3. Settlement  │  ← UBSCore: settle_trade
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  4. Event Log   │  ← Ledger writes
└─────────────────┘

3.2 PerfMetrics

#![allow(unused)]
fn main() {
pub struct PerfMetrics {
    pub total_pretrade_ns: u64,    // UBSCore WAL + Lock
    pub total_matching_ns: u64,    // Match processing
    pub total_settlement_ns: u64,  // Balance updates
    pub total_event_log_ns: u64,   // Ledger I/O
    
    pub place_count: u64,
    pub cancel_count: u64,
}
}

4. Optimization 2: Matching Engine

4.1 Bottleneck Identification

Profiling revealed Matching Engine used 96% of time. Deep dive found:

#![allow(unused)]
fn main() {
// Problem: Copy ALL price keys on every match
let prices: Vec<u64> = book.asks().keys().copied().collect();
}

With 250k+ price levels in the Cancel test, copying keys O(P) + Alloc every match is disastrous.

4.2 Solution

Use BTreeMap::range() to iterate only relevant prices.

#![allow(unused)]
fn main() {
// Solution: Iterate only valid price range
let max_price = if buy_order.order_type == OrderType::Limit {
    buy_order.price
} else {
    u64::MAX
};
let prices: Vec<u64> = book.asks().range(..=max_price).map(|(&k, _)| k).collect();
}

5. Final Results

5.1 Environment

• Dataset: 1.3M Orders (1M Place + 300k Cancel)
• HW: MacBook Pro M1

5.2 Breakdown

=== Performance Breakdown ===
Orders: 1300000, Trades: 538487

1. Pre-Trade:        621.97ms (  3.5%)  [  0.48 µs/order]
2. Matching:       15014.08ms ( 84.0%)  [ 15.01 µs/order]
3. Settlement:        21.57ms (  0.1%)  [  0.04 µs/trade]
4. Event Log:       2206.71ms ( 12.4%)  [  1.70 µs/order]

Total Tracked:     17864.33ms

5.3 Improvements

6. Comparison Table

7. Summary

7.1 Achievements

7.2 Final Design Pattern

┌─────────────────────────────────────────────────────────┐
│                     OrderBook                           │
│  ┌─────────────────┐    ┌─────────────────────────────┐ │
│  │   order_index   │◄───│  Sync on: rest, cancel,     │ │
│  │ FxHashMap<id,   │    │           match, remove     │ │
│  │   (price,side)> │    └─────────────────────────────┘ │
│  └────────┬────────┘                                    │
│           │ O(1) lookup                                 │
│           ▼                                             │
│  ┌─────────────────┐    ┌─────────────────────────────┐ │
│  │      bids       │    │          asks               │ │
│  │ BTreeMap<price, │    │  BTreeMap<price,            │ │
│  │   VecDeque>     │    │    VecDeque>                │ │
│  │  + range()      │    │    + range()                │ │
│  └─────────────────┘    └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Optimization Conclusion: From 7 minutes to 18 seconds. 24x boost. 🚀

🇨🇳 中文

📦 代码变更: 查看 Diff

背景：引入 Cancel 功能后，执行时间从 ~30s 暴涨到 7+ 分钟，需要定位并解决问题。

本章目的：

1. 建立正确的架构级 Profiling 方法
2. 通过 Profiling 精确定位性能瓶颈
3. 针对性修复发现的问题

关键点：直觉可以指导方向，但必须用 Profiling 数据验证。

1. 问题现象

引入 Cancel 后性能急剧下降：

• 执行时间：~30s → 7+ 分钟
• 吞吐量：~34k ops/s → ~3k ops/s

初始假设可能的原因：

• Cancel 的 O(N) 查找？
• VecDeque 删除开销？
• 其他未知问题？

但在 Profile 之前，这些都只是猜测。

2. Order Index 优化（第一次优化）

2.1 问题

撤单操作需要在 OrderBook 中查找订单。原始实现 remove_order_by_id 需要遍历整个订单簿：

#![allow(unused)]
fn main() {
// 优化前：O(N) 全表扫描
pub fn remove_order_by_id(&mut self, order_id: u64) -> Option<InternalOrder> {
    for (key, orders) in self.bids.iter_mut() {
        if let Some(pos) = orders.iter().position(|o| o.order_id == order_id) {
            // ...
        }
    }
    // 再遍历 asks...
}
}

2.2 解决方案

引入 order_index: FxHashMap<OrderId, (Price, Side)> 实现 O(1) 查找：

#![allow(unused)]
fn main() {
pub struct OrderBook {
    asks: BTreeMap<u64, VecDeque<InternalOrder>>,
    bids: BTreeMap<u64, VecDeque<InternalOrder>>,
    order_index: FxHashMap<u64, (u64, Side)>,  // 新增
    trade_id_counter: u64,
}
}

2.3 索引维护

2.4 优化后实现

#![allow(unused)]
fn main() {
pub fn remove_order_by_id(&mut self, order_id: u64) -> Option<InternalOrder> {
    // O(1) 查找
    let (price, side) = self.order_index.remove(&order_id)?;
    
    // O(log n) 定位价格层级
    let (book, key) = match side {
        Side::Buy => (&mut self.bids, u64::MAX - price),
        Side::Sell => (&mut self.asks, price),
    };
    
    // O(k) 在价格层级内查找 (k 通常很小)
    let orders = book.get_mut(&key)?;
    let pos = orders.iter().position(|o| o.order_id == order_id)?;
    let order = orders.remove(pos)?;
    
    if orders.is_empty() {
        book.remove(&key);
    }
    
    Some(order)
}
}

2.5 第一次优化结果

提升巨大！ 但 87s 处理 130万订单仍然很慢。需要继续分析。

3. 架构级 Profiling（定位真正瓶颈）

3.1 Profiling 设计

按照订单生命周期的顶层架构分阶段计时：

Order Input
    │
    ▼
┌─────────────────┐
│  1. Pre-Trade   │  ← UBSCore: WAL + Balance Lock
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  2. Matching    │  ← Pure ME: process_order
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  3. Settlement  │  ← UBSCore: settle_trade
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  4. Event Log   │  ← Ledger writes
└─────────────────┘

3.2 PerfMetrics 设计

#![allow(unused)]
fn main() {
pub struct PerfMetrics {
    // 顶层架构计时
    pub total_pretrade_ns: u64,    // UBSCore WAL + Lock
    pub total_matching_ns: u64,    // Pure ME
    pub total_settlement_ns: u64,  // Balance updates
    pub total_event_log_ns: u64,   // Ledger writes
    
    // 操作计数
    pub place_count: u64,
    pub cancel_count: u64,
}
}

4. Matching Engine 优化（第二次优化）

4.1 问题定位

通过架构级 Profiling 发现 Matching Engine 占用 96% 时间。深入分析发现：

#![allow(unused)]
fn main() {
// 问题代码：每次 match 都复制所有价格 keys
let prices: Vec<u64> = book.asks().keys().copied().collect();
}

当订单簿有 25万+ 价格层级时，每次 match 都要：

1. 遍历整个 BTreeMap 收集 keys - O(P)
2. 分配 Vec 存储 - 内存分配开销
3. 再遍历 Vec 进行匹配

4.2 优化方案

使用 BTreeMap::range() 只收集匹配范围内的 keys：

#![allow(unused)]
fn main() {
// 优化后：只收集匹配价格范围内的 keys
let max_price = if buy_order.order_type == OrderType::Limit {
    buy_order.price
} else {
    u64::MAX
};
let prices: Vec<u64> = book.asks().range(..=max_price).map(|(&k, _)| k).collect();
}

5. 性能测试结果

5.1 测试环境

• 数据集：130万订单（100万 Place + 30万 Cancel）
• 机器：MacBook Pro M1

5.2 最终 Breakdown

=== Performance Breakdown ===
Orders: 1300000 (Place: 1000000, Cancel: 300000), Trades: 538487

1. Pre-Trade:        621.97ms (  3.5%)  [  0.48 µs/order]
2. Matching:       15014.08ms ( 84.0%)  [ 15.01 µs/order]
3. Settlement:        21.57ms (  0.1%)  [  0.04 µs/trade]
4. Event Log:       2206.71ms ( 12.4%)  [  1.70 µs/order]

Total Tracked:     17864.33ms

5.3 优化效果

6. 执行性能对比

7. 总结

7.1 优化成果

7.2 最终设计模式

┌─────────────────────────────────────────────────────────┐
│                     OrderBook                           │
│  ┌─────────────────┐    ┌─────────────────────────────┐ │
│  │   order_index   │◄───│  Sync on: rest, cancel,     │ │
│  │ FxHashMap<id,   │    │           match, remove     │ │
│  │   (price,side)> │    └─────────────────────────────┘ │
│  └────────┬────────┘                                    │
│           │ O(1) lookup                                 │
│           ▼                                             │
│  ┌─────────────────┐    ┌─────────────────────────────┐ │
│  │      bids       │    │          asks               │ │
│  │ BTreeMap<price, │    │  BTreeMap<price,            │ │
│  │   VecDeque>     │    │    VecDeque>                │ │
│  │  + range()      │    │    + range()                │ │
│  └─────────────────┘    └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

本次优化先到此为止！从 7 分钟到 18 秒，吞吐量提升 24 倍！ 🚀

0x08-f Ring Buffer Pipeline Implementation

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

Goal: Connect services using Ring Buffers to implement a true Pipeline architecture.

Part 1: Single-Thread Pipeline

1.1 Background

Legacy Execution (Synchronous Serial):

for order in orders:
    1. ubscore.process_order(order)     # WAL + Lock
    2. engine.process_order(order)       # Match
    3. ubscore.settle_trade(trade)       # Settle
    4. ledger.write(event)               # Persist

Problem: No pipeline parallelism, latency accumulates.

1.2 Single-Thread Pipeline Architecture

Decouple services using Ring Buffers, but polling within a single thread loop:

┌─────────────────────────────────────────────────────────────────────────┐
│                    Single-Thread Pipeline (Round-Robin)                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   Stage 1: Ingestion          →  order_queue                            │
│   Stage 2: UBSCore Pre-Trade  →  valid_order_queue                      │
│   Stage 3: Matching Engine    →  trade_queue                            │
│   Stage 4: Settlement         →  (Ledger)                               │
│                                                                          │
│   All Stages executed in a round-robin loop                              │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Core Data Structures:

#![allow(unused)]
fn main() {
pub struct PipelineQueues {
    pub order_queue: Arc<ArrayQueue<SequencedOrder>>,
    pub valid_order_queue: Arc<ArrayQueue<ValidOrder>>,
    pub trade_queue: Arc<ArrayQueue<TradeEvent>>,
}
}

Execution Loop:

#![allow(unused)]
fn main() {
loop {
    // UBSCore: order_queue → valid_order_queue
    if let Some(order) = queues.order_queue.pop() {
        // ...
    }
    
    // ME: valid_order_queue → trade_queue
    if let Some(valid_order) = queues.valid_order_queue.pop() {
        // ...
    }
    
    // Settlement: trade_queue → persist
    if let Some(trade) = queues.trade_queue.pop() {
        // ...
    }
}
}

Part 2: Multi-Thread Pipeline

2.1 Architecture

Full Multi-Threaded Pipeline based on 0x08-a design:

┌───────────────────────────────────────────────────────────────────────────────────────┐
│                          Multi-Thread Pipeline (Full)                                  │
├───────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│  Thread 1: Ingestion       Thread 2: UBSCore              Thread 3: ME                │
│  ┌─────────────────┐       ┌──────────────────────┐       ┌─────────────────┐         │
│  │ Read orders     │       │  PRE-TRADE:          │       │ Match Order     │         │
│  │ Assign SeqNum   │──────▶│  - Write WAL         │──────▶│ in OrderBook    │         │
│  │                 │   ①   │  - process_order()   │  ③    │                 │         │
│  └─────────────────┘       │  - lock_balance()    │       │ Generate        │         │
│                            │                      │       │ TradeEvents     │         │
│                            └──────────┬───────────┘       └────────┬────────┘         │
│                                       ▲                            │                  │
│                                       │                            │                  │
│                                       │ ⑤ balance_update_queue     │ ④ trade_queue   │
│                                       └────────────────────────────┤                  │
│                                                                    │                  │
│                            ┌──────────────────────┐                ▼                  │
│                            │  POST-TRADE:         │       ┌─────────────────┐         │
│                            │  - settle_trade()    │       │ Thread 4:       │         │
│                            │  - spend_frozen()    │──────▶│ Settlement      │         │
│                            │  - deposit()         │  ⑥    │                 │         │
│                            │  - Generate Balance  │       │ Persist:        │         │
│                            │    Update Events     │       │ - Trade Events  │         │
│                            └──────────────────────┘       │ - Balance Events│         │
│                                                           │ - Ledger        │         │
│                                                           └─────────────────┘         │
│                                                                                        │
└───────────────────────────────────────────────────────────────────────────────────────┘

2.2 Key Design Points

1. ME Fan-out: ME sends TradeEvent in parallel to:
   • trade_queue → Settlement (Persist)
   • balance_update_queue → UBSCore (Balance Settle)
2. UBSCore as Single Balance Entry: Handles Pre-Trade Lock, Post-Trade Settle, and Refunds.
3. Settlement Consolidation: Consumes both Trade Events and Balance Events.

2.3 Data Types

BalanceUpdateRequest (ME → UBSCore): Contains Trade Event and optional Price Improvement data.

BalanceEvent (UBSCore → Settlement): The unified channel for ALL balance changes (Lock, Settle, Credit, Refund).

#![allow(unused)]
fn main() {
pub enum BalanceEventType {
    Lock,           // Pre-Trade
    SpendFrozen,    // Post-Trade
    Credit,         // Post-Trade
    RefundFrozen,   // Price Improvement
    // ...
}
}

2.4 Implementation Status

Verification & Performance (2025-12-17)

Correctness

E2E tests pass for both pipeline modes.

Performance Comparison

1.3M Orders (with 300k Cancel):

• Issue: Multi-Thread mode is currently slower (-30%) on large datasets and skips cancel orders.

100k Orders (Place only):

• Observation: Multi-threading shines on smaller, simpler datasets (+93%).

Analysis

Multi-threaded pipeline overhead (context switching, queue contention, event generation) outweighs benefits when per-order processing time is very low (due to optimizations). Also, missing Cancel logic reduces correctness.

Key Design Decisions

• Backpressure: Spin Wait (prioritize low latency).
• Shutdown: Graceful drain using Atomic Signals.
• Error Handling: Logging and metric counting; critical paths must succeed.

🇨🇳 中文

📦 代码变更: 查看 Diff

目标：使用 Ring Buffer 串接不同服务，实现真正的 Pipeline 架构

Part 1: 单线程 Pipeline

1.1 背景

原始执行模式 (同步串行):

for order in orders:
    1. ubscore.process_order(order)     # WAL + Lock
    2. engine.process_order(order)       # Match
    3. ubscore.settle_trade(trade)       # Settle
    4. ledger.write(event)               # Persist

问题：没有 Pipeline 并行，延迟累加

1.2 单线程 Pipeline 架构

使用 Ring Buffer 解耦各服务，但仍在单线程中轮询执行：

┌─────────────────────────────────────────────────────────────────────────┐
│                    Single-Thread Pipeline (Round-Robin)                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   Stage 1: Ingestion          →  order_queue                            │
│   Stage 2: UBSCore Pre-Trade  →  valid_order_queue                      │
│   Stage 3: Matching Engine    →  trade_queue                            │
│   Stage 4: Settlement         →  (Ledger)                               │
│                                                                          │
│   所有 Stage 在同一个 while 循环中轮询执行                               │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

核心数据结构:

#![allow(unused)]
fn main() {
pub struct PipelineQueues {
    pub order_queue: Arc<ArrayQueue<SequencedOrder>>,
    pub valid_order_queue: Arc<ArrayQueue<ValidOrder>>,
    pub trade_queue: Arc<ArrayQueue<TradeEvent>>,
}
}

执行流程:

#![allow(unused)]
fn main() {
loop {
    // UBSCore: order_queue → valid_order_queue
    if let Some(order) = queues.order_queue.pop() {
        // ...
    }
    
    // ME: valid_order_queue → trade_queue
    if let Some(valid_order) = queues.valid_order_queue.pop() {
        // ...
    }
    
    // Settlement: trade_queue → persist
    if let Some(trade) = queues.trade_queue.pop() {
        // ...
    }
}
}

Part 2: 多线程 Pipeline

2.1 架构

根据 0x08-a 原始设计，完整的多线程 Pipeline 数据流如下：

┌───────────────────────────────────────────────────────────────────────────────────────┐
│                          Multi-Thread Pipeline (完整版)                                │
├───────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│  Thread 1: Ingestion       Thread 2: UBSCore              Thread 3: ME                │
│  ┌─────────────────┐       ┌──────────────────────┐       ┌─────────────────┐         │
│  │ Read orders     │       │  PRE-TRADE:          │       │ Match Order     │         │
│  │ Assign SeqNum   │──────▶│  - Write WAL         │──────▶│ in OrderBook    │         │
│  │                 │   ①   │  - process_order()   │  ③    │                 │         │
│  └─────────────────┘       │  - lock_balance()    │       │ Generate        │         │
│                            │                      │       │ TradeEvents     │         │
│                            └──────────┬───────────┘       └────────┬────────┘         │
│                                       ▲                            │                  │
│                                       │                            │                  │
│                                       │ ⑤ balance_update_queue     │ ④ trade_queue   │
│                                       └────────────────────────────┤                  │
│                                                                    │                  │
│                            ┌──────────────────────┐                ▼                  │
│                            │  POST-TRADE:         │       ┌─────────────────┐         │
│                            │  - settle_trade()    │       │ Thread 4:       │         │
│                            │  - spend_frozen()    │──────▶│ Settlement      │         │
│                            │  - deposit()         │  ⑥    │                 │         │
│                            │  - Generate Balance  │       │ Persist:        │         │
│                            │    Update Events     │       │ - Trade Events  │         │
│                            └──────────────────────┘       │ - Balance Events│         │
│                                                           │ - Ledger        │         │
│                                                           └─────────────────┘         │
│                                                                                        │
└───────────────────────────────────────────────────────────────────────────────────────┘

2.2 关键设计点

1. ME Fan-out: ME 将 TradeEvent 并行发送到：
   • trade_queue → Settlement (持久化交易记录)
   • balance_update_queue → UBSCore (余额结算)
2. UBSCore 是余额操作的唯一入口: 处理 Pre-Trade 锁定、Post-Trade 结算和退款。
3. Settlement 聚合: 同时消费交易事件和余额事件。

2.3 数据类型

BalanceUpdateRequest (ME → UBSCore): 包含成交事件和可能的价格改善(Price Improvement)数据。

BalanceEvent (UBSCore → Settlement): 所有余额变更的统一通道 (Lock, Settle, Credit, Refund)。

#![allow(unused)]
fn main() {
pub enum BalanceEventType {
    Lock,           // Pre-Trade
    SpendFrozen,    // Post-Trade
    Credit,         // Post-Trade
    RefundFrozen,   // Price Improvement
    // ...
}
}

2.4 实现状态

验证与性能 (2025-12-17)

正确性

E2E 测试在两种模式下均通过。

性能对比

1.3M 订单 (含 30 万撤单):

• 问题: 多线程模式在大数据集上反而更慢 (-30%)，且目前跳过了撤单处理。

100k 订单 (仅 Place):

• 观察: 多线程在简单的小数据集上表现出色 (+93%)。

分析

在单笔处理极快的情况下，多线程带来的开销（上下文切换、队列竞争、事件生成）超过了并行的收益。此外，缺失撤单逻辑降低了正确性。

关键设计决策

• 背压: 自旋等待 (Spin Wait)，优先低延迟。
• 关闭: 使用原子信号优雅退出。
• 错误处理: 日志记录，核心路径必须成功。

0x08-g Multi-Thread Pipeline Design

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff | Key File: pipeline_mt.rs

Overview

The Multi-Thread Pipeline distributes processing logic across 4 independent threads, communicating via lock-free queues to achieve high throughput order processing.

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Ingestion  │────▶│   UBSCore   │────▶│     ME      │────▶│ Settlement  │
│  (Thread 1) │     │  (Thread 2) │     │  (Thread 3) │     │  (Thread 4) │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
      │                   │ ▲                 │                   │
      │                   │ │                 │                   │
      ▼                   ▼ │                 ▼                   ▼
  order_queue ────▶ action_queue      balance_update_queue   trade_queue
                           │                                balance_event_queue
                           └──────────────────────────────────────┘

Thread Responsibilities

Queue Design

Using crossbeam-queue::ArrayQueue for lock-free MPSC queues:

#![allow(unused)]
fn main() {
pub struct MultiThreadQueues {
    pub order_queue: Arc<ArrayQueue<OrderAction>>,     // 64K
    pub action_queue: Arc<ArrayQueue<ValidAction>>,    // 64K
    pub trade_queue: Arc<ArrayQueue<TradeEvent>>,      // 64K
    pub balance_update_queue: Arc<ArrayQueue<BalanceUpdateRequest>>,  // 64K
    pub balance_event_queue: Arc<ArrayQueue<BalanceEvent>>,           // 64K
}
}

Cancel Handling

1. Ingestion: Create OrderAction::Cancel.
2. UBSCore: Pass to action_queue (No lock needed).
3. ME: Remove from OrderBook, send BalanceUpdateRequest::Cancel.
4. UBSCore: Process unlock, generate BalanceEvent::Unlock.
5. Settlement: Persist BalanceEvent.

Consistency Verification

Test Script

# Run full comparison test
./scripts/test_pipeline_compare.sh highbal

# Supported Datasets:
#   100k    - 100k orders without cancel
#   cancel  - 1.3M orders with 30% cancel
#   highbal - 1.3M orders with 30% cancel, high balance (Recommended)

Verification Results (1.3M orders, 30% cancel, high balance)

╔════════════════════════════════════════════════════════════════╗
║                    ✅ ALL TESTS PASSED                         ║
║  Multi-thread pipeline matches single-thread exactly!          ║
╚════════════════════════════════════════════════════════════════╝

Key Metrics

Important Considerations

Balance Sufficiency

Insufficient balance may cause rejections. In concurrent environments, rejection timing can vary due to settlement latency, leading to non-deterministic results. Solution: Use highbal dataset (1000 BTC + 100M USDT per user).

Shutdown Synchronization

Wait for queues to drain before signaling shutdown:

#![allow(unused)]
fn main() {
while !queues.all_empty() {
    std::hint::spin_loop();
}
shutdown.request_shutdown();
}

Performance

Note: Multi-thread version includes overhead for BalanceEvent generation/persistence, matching Single-Thread performance. Future optimizations: Batch I/O, reduce contention.

Queue Priority Strategy (Future)

Current Implementation: Prioritize draining balance_update_queue completely before processing order_queue.

Future: Weighted Round-Robin: Allow alternating processing to improve responsiveness.

#![allow(unused)]
fn main() {
const SETTLE_WEIGHT: u32 = 3;  // settle : order = 3 : 1
}

File Structure

src/
├── pipeline.rs       # Shared types
├── pipeline_mt.rs    # Multi-thread impl
├── pipeline_runner.rs # Single-thread impl
└── main.rs

🇨🇳 中文

📦 代码变更: 查看 Diff | 关键文件: pipeline_mt.rs

概述

Multi-Thread Pipeline 将处理逻辑分布在 4 个独立线程中，通过无锁队列通信，实现高吞吐量的订单处理。

架构

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Ingestion  │────▶│   UBSCore   │────▶│     ME      │────▶│ Settlement  │
│  (Thread 1) │     │  (Thread 2) │     │  (Thread 3) │     │  (Thread 4) │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
      │                   │ ▲                 │                   │
      │                   │ │                 │                   │
      ▼                   ▼ │                 ▼                   ▼
  order_queue ────▶ action_queue      balance_update_queue   trade_queue
                           │                                balance_event_queue
                           └──────────────────────────────────────┘

线程职责

队列设计

使用 crossbeam-queue::ArrayQueue 实现无锁 MPSC 队列：

#![allow(unused)]
fn main() {
pub struct MultiThreadQueues {
    pub order_queue: Arc<ArrayQueue<OrderAction>>,     // 64K capacity
    pub action_queue: Arc<ArrayQueue<ValidAction>>,    // 64K capacity
    pub trade_queue: Arc<ArrayQueue<TradeEvent>>,      // 64K capacity
    pub balance_update_queue: Arc<ArrayQueue<BalanceUpdateRequest>>,  // 64K
    pub balance_event_queue: Arc<ArrayQueue<BalanceEvent>>,           // 64K
}
}

Cancel 订单处理

Cancel 订单流程：

1. Ingestion: 创建 OrderAction::Cancel { order_id, user_id }
2. UBSCore: 直接传递到 action_queue（无需 balance lock）
3. ME: 从 OrderBook 移除订单，发送 BalanceUpdateRequest::Cancel
4. UBSCore (Post-Trade): 处理 unlock，生成 BalanceEvent::Unlock
5. Settlement: 持久化 BalanceEvent

一致性验证

测试脚本

# 运行完整对比测试
./scripts/test_pipeline_compare.sh highbal

# 支持的数据集:
#   100k    - 100k orders without cancel
#   cancel  - 1.3M orders with 30% cancel
#   highbal - 1.3M orders with 30% cancel, high balance (推荐)

验证结果 (1.3M orders, 30% cancel, high balance)

╔════════════════════════════════════════════════════════════════╗
║                    ✅ ALL TESTS PASSED                         ║
║  Multi-thread pipeline matches single-thread exactly!          ║
╚════════════════════════════════════════════════════════════════╝

关键指标

注意事项

余额充足性

如果测试数据中用户余额不足，可能导致部分订单被 reject。在并发环境中，由于 settle 时序不同，这些 reject 可能与单线程结果不同。

解决方案: 使用 highbal 数据集，确保每个用户有充足余额（1000 BTC + 100M USDT）。

Shutdown 同步

Multi-thread pipeline 在 shutdown 时需要确保所有队列都已 drain：

#![allow(unused)]
fn main() {
while !queues.all_empty() {
    std::hint::spin_loop();
}
shutdown.request_shutdown();
}

性能

注：Multi-thread 当前版本包含 BalanceEvent 生成和持久化开销，性能与 Single-Thread 相当。未来优化方向包括批量 I/O 和减少队列竞争。

队列优先级策略 (未来)

当前实现: 完全优先 drain balance_update_queue，然后才处理新订单。

未来优化: 加权轮询 (Weighted Round-Robin): 允许交替处理，提高响应性。

#![allow(unused)]
fn main() {
const SETTLE_WEIGHT: u32 = 3;  // settle : order = 3 : 1
}

文件结构

src/
├── pipeline.rs       # 共享类型: PipelineStats, MultiThreadQueues, ShutdownSignal
├── pipeline_mt.rs    # Multi-thread 实现: run_pipeline_multi_thread()
├── pipeline_runner.rs # Single-thread 实现: run_pipeline()
└── main.rs           # --pipeline / --pipeline-mt 模式选择

0x08-h Performance Monitoring & Observability

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff | Key File: pipeline_services.rs

“If you can’t measure it, you can’t improve it.” This chapter focuses on introducing production-grade performance monitoring and observability for our multi-threaded pipeline.

Monitoring Dimensions

1. Latency Metrics

In HFT, averages are misleading. We care about Tail Latency.

• P50 (Median): General performance.
• P99 / P99.9: Stability in extreme cases.
• Max: Jitter, GC, or system calls.

2. Throughput

• Orders/sec: Processing capacity.
• Trades/sec: Matching capacity.

3. Queue Depth & Backpressure

Monitoring Ring Buffer occupancy reveals downstream bottlenecks and jitter.

4. Architectural Breakdown

Knowing where time is spent (Pre-Trade vs Matching vs Settlement).

Test Execution

Dataset: 1.3M orders (30% cancel) from fixtures/test_with_cancel_highbal/.

Single-Thread Run:

cargo run --release -- --pipeline --input fixtures/test_with_cancel_highbal

Multi-Thread Run:

cargo run --release -- --pipeline-mt --input fixtures/test_with_cancel_highbal

Compare Script:

./scripts/test_pipeline_compare.sh highbal

Analysis Results (1.3M Dataset)

1. Single-Thread Pipeline

• Throughput: 210,000 orders/sec (P50 Latency: 1.25 µs)
• Breakdown:
  • Matching Engine: 91.5% (The bottleneck)
  • UBSCore Lock: 5.6%
  • Persistence: 2.7%

2. Multi-Thread Pipeline (After Service Refactor)

• Throughput: ~64,450 orders/sec
• E2E Latency (P50): ~113 ms
• E2E Latency (P99): ~188 ms

Conclusion

1. Parallelism Works: Total task CPU time (~34s) > Wall time (17.5s).
2. Bottleneck: Matching Engine remains the serial bottleneck (~52k ops/s limit).
3. Latency Cost: Multi-threading introduces significant message passing latency (µs → ms).

Logging & Observability

We introduced a production-grade asynchronous logging system using tracing.

1. Non-blocking I/O

Using tracing-appender with a dedicated worker thread and memory buffer to prevent I/O blocking.

2. Environment-driven Config

• Dev: Detailed, human-readable.
• Prod: JSON format, high-frequency tracing disabled (0XINFI=off).

3. Standardized Targets

All pipeline logs use the 0XINFI namespace (e.g., 0XINFI::ME, 0XINFI::UBSC) for precise filtering.

Intent-Based Design: From Functions to Services

“Good architecture is not designed upfront, but evolved through refactoring.”

We refactored tightly coupled spawn_* functions into decoupled Service Structs.

Problem: Coupled Functions

#![allow(unused)]
fn main() {
// ❌ Business logic buried in thread spawning
fn spawn_me_stage(...) -> JoinHandle<OrderBook> {
    thread::spawn(move || {
        // Logic locked inside closure
    })
}
}

• Untestable: Cannot unit test logic without spawning threads.
• Not Reusable: Cannot be used in single-thread mode.

Solution: Service Structs

#![allow(unused)]
fn main() {
// ✅ Intent is clear and decoupled
pub struct MatchingService {
    book: OrderBook,
    // ...
}

impl MatchingService {
    pub fn run(&mut self, shutdown: &ShutdownSignal) { ... }
}
}

Benefits

• Testability: Services can be instantiated and tested in isolation.
• Reusability: Core logic is decoupled from threading model.
• Clarity: Code expresses “what” (Service), not just “how” (Thread).

🇨🇳 中文

📦 代码变更: 查看 Diff | 关键文件: pipeline_services.rs

在构建高性能低延迟交易系统时，“如果你无法测量它，你就无法优化它”。本章重点在于为我们的多线程 Pipeline 引入生产级的性能监控和延迟指标分析。

监控维度

1. 延迟指标 (Latency Metrics)

对于 HFT 系统，平均延迟往往是误导性的，我们更关心长尾延迟 (Tail Latency)。

• P50 (Median): 中位数延迟，反映平均水平。
• P99 / P99.9: 长尾延迟，反映系统在极端情况下的稳定性。
• Max: 峰值延迟，通常由系统抖动 (Jitter) 或 GC/系统调用引起。

2. 吞吐量 (Throughput)

• Orders/sec: 每秒处理订单数。
• Trades/sec: 每秒撮合成交数。

3. 队列深度与背压 (Queue Depth & Backpressure)

监控 Ring Buffer 的占用情况，识别下游瓶颈。

4. 架构内部阶段耗时 (Architectural Breakdown)

清晰地知道时间花在了哪里：Pre-Trade / Matching / Settlement / Logging。

测试执行方法

数据集: 130 万订单（含 30% 撤单） fixtures/test_with_cancel_highbal/。

运行单线程:

cargo run --release -- --pipeline --input fixtures/test_with_cancel_highbal

运行多线程:

cargo run --release -- --pipeline-mt --input fixtures/test_with_cancel_highbal

对比脚本:

./scripts/test_pipeline_compare.sh highbal

执行结果与分析 (1.3M 数据集)

1. 单线程流水线

• 性能: 210,000 orders/sec (P50: 1.25 µs)
• 瓶颈: Matching Engine 耗时 91.5%，是最大瓶颈。

2. 多线程流水线 (重构后)

• 吞吐量: ~64,450 orders/sec
• 端到端延迟 (P50): ~113 ms
• 端到端延迟 (P99): ~188 ms

结论

1. 并行有效: CPU 总耗时远大于执行时间。
2. 瓶颈: Matching Engine 依然是最大的串行瓶颈 (吞吐上限 ~52k)。
3. 延迟: 多线程引入的消息传递开销导致端到端延迟从微秒级退化到毫秒级。

日志与可观测性

引入基于 tracing 的生产级异步日志体系。

1. 异步非阻塞架构

使用 tracing-appender 独立线程写入日志，不阻塞业务线程。

2. 环境驱动配置

Dev 开启详细日志，Prod 使用 JSON 并关闭高频追踪。

3. 标准化日志目标

使用 0XINFI 命名空间 (如 0XINFI::ME) 实现精细过滤。

意图编码：从函数到服务

“好的架构不是一开始就设计出来的，而是通过不断重构演进出来的。”

我们将紧耦合的 spawn_* 函数重构为解耦的 Service 结构体。

问题：紧耦合

#![allow(unused)]
fn main() {
// ❌ 业务逻辑埋在线程创建中
fn spawn_me_stage(...) {
    thread::spawn(move || { ... })
}
}

无法单元测试，无法复用。

解决方案：Service 结构体

#![allow(unused)]
fn main() {
// ✅ 意图清晰，解耦
pub struct MatchingService { ... }

impl MatchingService {
    pub fn run(&mut self, shutdown: &ShutdownSignal) { ... }
}
}

收益

• 可测试性: 服务可独立实例化测试。
• 可复用性: 核心逻辑与线程模型解耦。
• 清晰度: 代码表达“做什么“ (Service)，而非“怎么做“ (Thread)。

0x09-a Gateway: Client Access Layer

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

📦 Code Changes: View Diff

Core Objective: Implement a lightweight HTTP Gateway to connect clients with the trading core system.

Background: From Core to MVP

We have built a functional Trading Core:

• OrderBook (0x04)
• Balance Management (0x05-0x06)
• Matching Engine (0x08)
• Pipeline & Monitoring (0x08-f/g/h)

To become a usable MVP, we need auxiliary systems:

┌─────────────────────────────────────────────────────────────────────────┐
│                        Complete Trading System MVP                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Client (Web/Mobile/API)                                                 │
│       │                                                                  │
│       ▼                                                                  │
│  ┌─────────────────┐                                                     │
│  │   0x09-a        │  ← This Chapter: Accept orders, return response     │
│  │   Gateway       │                                                     │
│  └────────┬────────┘                                                     │
│           │                                                                  │
│           ▼                                                                  │
│  ┌─────────────────────────────────────────────────────────────────┐     │
│  │              Trading Core (Completed)                            │     │
│  │  Ingestion → UBSCore → ME → Settlement                          │     │
│  └─────────────────────────────────────────────────────────────────┘     │

0x09 Series Plan