sica-fondt/core/docs/plans/M3g-market-microstructure-sims.md

M3g — Market microstructure sims

1. Component

Market microstructure simulation: models order flow, liquidity depth, slippage, spread dynamics, and cross-exchange arbitrage at the fastest time scales (tick-level to hourly). Pops here are market makers, takers, and arbitrageurs interacting across multiple venues. The sim that operates at the highest temporal resolution — where M3a provides statistical forecasts and M3c models pool mechanics, M3g models the plumbing of how orders actually execute.

2. Status / certainty

DESIGN-FIRST · ABSENT. Order-book microstructure theory C4 (established academic field); DEX-specific microstructure C2 (emerging). Implementation C1.

3. Language & location

TBD · src/economy/sims/microstructure/. Needs high-frequency data handling and event-driven simulation. Rust, C++, or Python with optimized event loop.

4. Does / does-not

• Does: simulate order flow across venues (DEXs and CEXs); model bid-ask spread dynamics as a function of inventory risk and adverse selection; simulate slippage curves for various order sizes; model cross-exchange arbitrage opportunities and their decay; operate at tick-level resolution (sub-second to minute); produce bounded predictions on execution quality, optimal routing, and liquidity conditions.
• Does-not: model protocol consensus (M3f); model macro token supply (M3e); model social behavior (M3b); execute trades (Marketplace does).

5. Interface contract

• Implements query(PredictionQuery) -> BoundedPrediction per M3 hub.
• Output bounds: execution cost ranges and liquidity intervals. Example: { value: 0.0034, lower_bound: 0.0018, upper_bound: 0.0052, confidence: 0.85, time_horizon: "next_trade", sim_type: "market_microstructure" } — expected slippage (%) for a 10 ETH market sell. Example: { value: 12400, lower_bound: 8200, upper_bound: 18600, confidence: 0.78, time_horizon: "1h", sim_type: "market_microstructure" } — available depth (USD) within 50bps of mid.
• Prediction types: slippage_estimate, spread_forecast, depth_profile, cross_venue_arb, optimal_execution_route, liquidity_score.
• Calibration: ingests price_tick, dex_pool_state, and execution_fill from M2.

6. Dependencies & stubs

• M2 Data Feeds — tick data and pool state; stub: canned order book snapshots.
• M3c AMM sims — pool mechanics for DEX venues; stub: fixed pool state.
• M3 Sims hub — lifecycle management; stub: manual init.

7. Invariants / laws

• L1 (C4): microstructure operates at the highest temporal resolution — predictions are valid for seconds to hours, not days. Stale microstructure data is worse than no data.
• L2 (C4): slippage is a function of order size and current depth — not a fixed percentage. The sim must model the non-linear relationship.
• L3 (C3): cross-venue arbitrage opportunities decay — the sim models the time-to-close of an arb opportunity, not just its existence.

8. Build steps

1. Implement a simplified order-book simulator (limit orders, market orders, cancels).
2. Add spread dynamics (inventory-based market maker model).
3. Add slippage curves (order size → execution cost).
4. Add cross-venue arb detection and decay modeling.
5. Wire M2 tick data → calibration.

9. Tests

Slippage: larger orders produce greater slippage. Spread: spread widens under adverse selection. Arb decay: detected arb opportunity closes over time. Depth: depth profile matches order book state. Bounds: all outputs bounded. Resolution: predictions update at tick frequency.

10. Open items

• CEX order book data access (API limitations, costs).
• DEX-specific microstructure (AMM pools don't have order books — translate pool state to equivalent depth/spread).
• Latency modeling (how fast can our traders actually reach an arb?).
• Which venues to model initially.