55 lines
3.5 KiB
Markdown
55 lines
3.5 KiB
Markdown
# 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. **Arb step (optional):** agents that trade toward oracle when profitable; update inventories again.
|
||
6. **Bot intervention step:** apply policy from config (or keep exogenous); record intervention cost.
|
||
7. **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`.
|
||
- **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`.
|
||
|
||
Tuning: see constants in script and [scripts/README.md](../scripts/README.md).
|