0x14-b Order Commands: Feature Completion

🇺🇸 English    |    🇨🇳 中文

🇺🇸 English

1. Gap Analysis

Based on code review of src/engine.rs, src/models.rs, src/orderbook.rs:

✅ Already Implemented

❌ Missing (Required for 0x14-b)

Based on exchange_core_verification_kit/test_datasets_and_steps.md L162-171 (Command Distribution):

Note: FOK_BUDGET (Fill-or-Kill by Quote Budget) is ~1% of benchmark commands. Required for full S-to-Huge parity.

2. Architectural Requirements

2.1 Data Model Extensions (Schema)

We must extend InternalOrder to support varied execution strategies without polluting the core OrderType.

New Enum: TimeInForce

#![allow(unused)]
fn main() {
pub enum TimeInForce {
    GTC, // Good Till Cancel (Default)
    IOC, // Immediate or Cancel (Taker only, cancel remainder)
    FOK, // Fill or Kill (All or Nothing) - Optional for now
}
}

Updated InternalOrder:

• Add pub time_in_force: TimeInForce
• Add pub post_only: bool (Future proofing, Generator doesn’t strictly use it yet but good practice)

2.2 Matching Engine Logic

The Matching Engine must process orders sequentially based on seq_id.

Execution Flow:

1. Incoming Order: Parse TimeInForce and OrderType.
2. Matching:
   • Limit GTC: Match against opposite book. Remaining -> Add to Book.
   • Limit IOC: Match against opposite book. Remaining -> Expire (do not add to book).
   • Market: Match against opposite book at any price. Remaining -> Expire (or defined slippage protection).
3. Command Handling:
   • MoveOrder: Atomic “Cancel old ID + Place new ID”. Priority Loss is acceptable (and expected).
   • ReduceOrder: Reduce qty in-place. Priority Preservation required if implemented efficiently, else re-insert. Exchange-Core typically preserves priority on reduce.

2.3 FokBudget Handling (Spot)

• Generator produces FokBudget? -> Checks show mostly Gtc/Ioc.
• Correction: CommandType::FokBudget exists in Generator enum but usage is rare in the Spot Benchmark. We prioritize IOC and GTC.

3. Developer Specification

3.1 Task List

1. Model Update:
   • Modify src/models.rs: Add TimeInForce enum.
   • Update InternalOrder struct.
2. Engine Implementation (src/engine/matching.rs):
   • Implement process_order(&mut self, order: InternalOrder) -> OrderResult.
   • Implement match_market_order.
   • Implement match_limit_order.
3. Command Logic:
   • Implement reduce_order(price, old_qty, new_qty).
   • Implement move_order (atomic cancel + place).

3.2 Acceptance Criteria

• Unit Tests:
  • test_ioc_partial_fill: 100 qty order vs 60 qty book -> 60 filled, 40 expired.
  • test_gtc_maker: 100 qty order vs empty book -> 100 rests in book.
  • test_market_sweep: Market order consumes multiple price levels.

4. QA Verification Plan

• Property: Ioc orders must never appear in all_orders() (the book) after processing.
• Property: Gtc orders must appear in book if not fully matched.
• | Latency | Measure process_order time | ✅ < 5µs (Verified) |

5. Implementation Status & Results

Note

✅ Phase 0x14-b: 100% Feature Parity Achieved

5.1 Verification Matrix

5.2 Key Technical Findings

1. Asynchronous Consistency: Fixed a critical bug where Cancel/Reduce actions bypassed the MEResult persistence queue.
2. Priority Preservation: Verified that ReduceOrder maintains temporal priority, while MoveOrder (Price change) correctly resets it.
3. Reactive Loop: Optimized the matching engine to handle state transitions without synchronous blocking on I/O.

6. Validation Commands

Automated QA Suite:

# Run all 0x14-b specific QA tests
./scripts/test_0x14b_qa.sh --with-gateway

Unit Verification:

cargo test test_ioc_ test_mov_ test_reduce_

🇨🇳 中文

1. 差距分析 (基于 Verification Kit)

基于 exchange_core_verification_kit/test_datasets_and_steps.md L162-171 命令分布：

✅ 已实现

❌ 需新增

说明: FOK_BUDGET (按报价币金额买入) 占比 ~1%，完成 S-to-Huge 全量测试需实现。

2. 架构需求

2.1 数据模型扩展 (Schema)

必须扩展 InternalOrder 以支持多种执行策略。

新枚举: TimeInForce

#![allow(unused)]
fn main() {
pub enum TimeInForce {
    GTC, // Good Till Cancel (默认: 一直有效直到取消)
    IOC, // Immediate or Cancel (Taker 专用: 剩余未成交部分立即过期)
    FOK, // Fill or Kill (全部成交或全部取消) - 暂可选
}
}

更新 InternalOrder:

• 新增 pub time_in_force: TimeInForce
• 新增 pub post_only: bool (为未来准备，虽然生成器暂时未严格使用)

2.2 撮合引擎逻辑

撮合引擎必须基于 seq_id 顺序处理 订单。

执行流:

1. 新订单接入: 解析 TimeInForce 和 OrderType。
2. 撮合过程:
   • Limit GTC: 与对手盘撮合。剩余部分 -> 加入订单簿。
   • Limit IOC: 与对手盘撮合。剩余部分 -> 立即过期 (Expire) (不入簿)。
   • Market: 与对手盘在任意价格撮合。剩余部分 -> 过期 (或滑点保护)。
3. 指令处理:
   • MoveOrder: 原子化 “取消旧ID + 下单新ID”。优先级丢失 是可接受的 (且预期的)。
   • ReduceOrder: 原地减少数量。如果实现得当，应保留优先级。Exchange-Core 通常在减量时保留优先级。

2.3 FokBudget 处理 (现货)

• 生成器会产生 FokBudget 吗？ -> 代码显示主要是 Gtc/Ioc。
• 修正: CommandType::FokBudget 存在于枚举中，但在现货 Benchmark 中极少使用。我们优先保证 IOC 和 GTC 的正确性。

3. 开发规范 (Developer Specification)

3.1 任务清单

1. 模型更新:
   • 修改 src/models.rs: 增加 TimeInForce 枚举。
   • 更新 InternalOrder 结构体。
2. 引擎实现 (src/engine/matching.rs):
   • 实现 process_order(&mut self, order: InternalOrder) -> OrderResult。
   • 实现 match_market_order (市价撮合)。
   • 实现 match_limit_order (限价撮合)。
3. 指令逻辑:
   • 实现 reduce_order(price, old_qty, new_qty)。
   • 实现 move_order (atomic cancel + place)。

3.2 验收标准

• 单元测试:
  • test_ioc_partial_fill: 100 qty 订单 vs 60 qty 深度 -> 成交 60, 过期 40。
  • test_gtc_maker: 100 qty 订单 vs 空订单簿 -> 100 进入 OrderBook。
  • test_market_sweep: 市价单吃掉多个价格档位。

4. QA 验证计划

• 属性: Ioc 订单处理后，绝不 应出现在 all_orders() (订单簿) 中。
• 属性: Gtc 订单若未完全成交，必须 出现在订单簿中。
• | 延迟 | 测量 process_order 处理时间 | ✅ < 5µs (已验证) |

5. 实施结果与验证

Note

✅ Phase 0x14-b: 100% 功能对齐已完成

5.1 验证矩阵

5.2 关键技术点总结

1. 异步一致性: 修复了 Cancel/Reduce 操作绕过 MEResult 持久化队列的 Bug，确保数据库状态与内存一致。
2. 优先级保留: 通过单元测试验证了 ReduceOrder 成功保留时间优先级，而 MoveOrder (改价) 正确重置了优先级。
3. 响应式架构: 优化了撮合引擎的反应循环，确保所有指令都在微秒级完成且具备确定性的副作用路径。

6. 验证命令

一键回归测试:

# 运行所有 0x14-b QA 自动化测试
./scripts/test_0x14b_qa.sh --with-gateway

单元逻辑验证:

cargo test test_ioc_ test_mov_ test_reduce_