cross-chain-pmm-lps/spec/13-minimal-router-sim.md

Minimal Router Simulator Architecture

Lightweight simulator to make routing/DeFi effects on single-sided PMM measurable before building an on-chain-accurate engine. No exact DODO math required; need routing selection + flow splitting + inventory updates.

---

1. Build supergraph

• Nodes: (chain, token) from scenario chainsIncluded × tokensIncluded plus anchor stables per chain.
• Edges:
  • PMM edges: from deployment-status.json (deployed) or from design + simulation-params.json (design). One edge per pool (c, T) ↔ (c, Q).
  • AMM “background”: anchor stable conversions (e.g. USDC↔USDT) — model as deep constant-product or fixed spread so PMM is not the only path.
  • Bridge edges: (c_i, cW*) → (c_j, cW*) with cost y = x(1−β) − γ − ρ(Δt)·x (β, γ, ρ from scenario latencyModel / params).

---

2. Epoch loop

For each epoch:

1. Sample N trades from orderflowModel (source chain, target chain, token, size).
2. Compute candidate paths (e.g. k-shortest paths or enumerate swap+bridge combos).
3. Allocate flow by marginal-equalization heuristic (waterfilling): split volume across paths so marginal output equalizes.
4. Update PMM inventories and implied prices (use inventory-sensitive depth D = D_0·min(1, I_T/I_T^*)).
5. Micro-support step (optional): run gas-budgeted support trades for selected rails (e.g. cWUSDC, cWUSDT) to model tiny turnover-seeding or inventory-corrective activity.
6. Arb step (optional): agents that trade toward oracle when profitable; update inventories again.
7. Bot intervention step: apply policy from config (or keep exogenous); record intervention cost.
8. Emit scorecard (or accumulate for end-of-run scorecard).

---

3. What this shows immediately

• Inventory mining: routers drain PMM until marginal rate worsens.
• Reflexive multi-hop: route cycles through multiple PMM pools (count as reflexive_route_count).
• Full-quote vs hub churn: compare churn_mean and churn_max across scenarios.

AMM edges can be mocked (e.g. fixed 5 bps spread); relative behavior of PMM vs alternatives is still correct.

---

4. Implementation status

scripts/run-scenario.cjs implements the real pipeline (PR#1 + PR#2):

• Graph: Nodes (chainId, token); PMM edges from scenario + simulation-params + pool-matrix (hub + optional full-quote); AMM background edges (anchor↔anchor, fee-only); bridge edges wired (cost used for bot intervention; cross-chain routing optional later).
• PMM state: Per-pool I_T, D = D_0·min(1, I_T/I_T^*), sell/buy with documented formula; routing controls applied.
• Routing: Candidate paths (same-chain, length ≤3), top-K by cost; waterfilling by chunk (5%), marginal-equalization.
• Arb step (PR#2): Implied price (sell/buy probe) vs oracle P; deviation δ; if |δ| > DELTA_ARB_BPS, trade in corrective direction with size min(x_max, α·|δ|·I_T^*); profit gate (skip if profit ≤ 0). Tuning: DELTA_ARB_BPS, ARB_ALPHA, ARB_MAX_FRACTION_OF_TARGET.
• Micro-support step: When scenario.microTradePolicy is enabled, run tiny support trades on selected cW rails before arb. Policy can prefer matched quotes (cWUSDC/USDC, cWUSDT/USDT), stay inside an inventory band, alternate when inside band, and clip the trade count by a per-epoch gas budget.
• Bot step (PR#2): If I_T < 0.5·I_T^* inject; if I_T > 1.5·I_T^* withdraw; action clipped to BOT_MAX_FRACTION_OF_TARGET·I_T^*; intervention cost = |u|·(β+ρ)+γ (bridge params + latency ρ from scenario latencyModel).
• Bridge shock: When scenario.bridgeShock is set, extra trades (sell cW on fromChain, buy cW on toChain) over durationEpochs at magnitudeFraction of baseline.
• Determinism: RNG seeded from scenario.seed or hash of scenario name.
• Scorecard: All PR#1 metrics plus peak_deviation_bps, intervention_cost_*, arb_volume_total, arb_profit_total, and support-lane micro_trade_* metrics.

Tuning: see constants in script and scripts/README.md.