chore: sync submodule state (parent ref update)

Made-with: Cursor

docs/08-simulation-model.md

@@ -0,0 +1,156 @@
+# Two-Layer Routing Simulation Model
+
+Design graph vs deployed graph; multi-chain supergraph; edge types; PMM edge function; router optimization; scenario-based simulation; and the three key metrics.
+
+---
+
+## 1. Two-layer model
+
+- **Design graph** — What *could* route: 11 EVM chains, hub per chain, cW* tokens and anchor stables as defined in `config/token-map.json`, `config/chains.json`, `config/pool-matrix.json`. No per-chain addresses; topology and assumed liquidity/fees only.
+- **Deployed graph** — What *actually* routes: filled from `config/deployment-status.json` (cw token addresses, anchor addresses, PMM pool addresses and params). Until that is populated, simulation is **structural** (topology + assumed params), not empirical (real addresses, depths, aggregator behavior).
+
+Until deployment state is filled, run **scenario-based** simulation only.
+
+---
+
+## 2. Multi-chain routing supergraph
+
+**Nodes:** `(chain c, token t)`. Examples: `(56, cWUSDC)`, `(137, USDT)`, `(42161, DAI)`.
+
+### Edge types
+
+**A) DEX swap edge (PMM or AMM)**
+
+```
+(c, t_a) --[swap]--> (c, t_b)
+```
+
+Stateful output: `y = f_e(x; s_e)` (output amount depends on input size and pool state).
+
+**B) Bridge edge (cross-chain transfer)**
+
+```
+(c_i, cWUSDC) --[bridge]--> (c_j, cWUSDC)
+```
+
+Bridge cost model (with optional latency risk premium):
+
+- **Base:** `y = x * (1 - β_ij) - γ_ij`
+  - `β_ij`: fractional bridge fee/slippage
+  - `γ_ij`: fixed cost (gas + messaging + relayer)
+- **With latency risk:** `y = x * (1 - β_ij) - γ_ij - ρ(Δt) * x`
+  - `ρ(Δt)`: penalty increasing with bridge finality time (e.g. piecewise linear in Δt). Stops the sim from overestimating “free” cross-chain loop arb; include bridge latency and probabilistic settlement delay so cross-chain arbitrage loops are not under-penalized.
+
+**C) Mint/Burn to Home (ChainID 138)**
+
+If 138 is the canonical issuer and redemption is allowed:
+
+```
+(138, cUSDC) <--> (c, cWUSDC)
+```
+
+Model as bridge-like edges with their own fees, latency, and risk.
+
+---
+
+## 3. Single-sided PMM edge function (router drain risk)
+
+For each public chain `c` and cW token `T`, edge pools are:
+
+```
+(c, T) <--> (c, Q)   where Q ∈ {USDT, USDC, DAI, BUSD, mUSD}
+```
+
+(availability of Q differs by chain.)
+
+Use an oracle-anchored, inventory-sensitive slippage function (PMM-like). Practical form:
+
+- `y(x) = (1 - φ) * P * [ x - k * ( x - D * ln(1 + x/D) ) ]`
+- `P`: oracle price (≈ 1 for USD pegs; EURUSD-based for EUR pegs)
+- `k`: curvature (lower = tighter peg, more attractive to routers)
+- `φ`: fee (e.g. bps)
+- **Effective depth** (key for router drain):
+  - `D = D_0 * min(1, I_T / I_T^*)`
+  - `I_T`: remaining inventory of T in the pool; `I_T^*`: target/baseline inventory.
+
+As inventory is drained, D drops and marginal rate worsens, reproducing “routers drain LP until marginal rate worsens.”
+
+---
+
+## 4. Router behavior = flow optimization with path splitting
+
+Aggregators choose 1–N paths and split flow. For input `X` converting `(c, S) → (c, T)`:
+
+- Choose paths `P_i` and allocations `x_i` with `max_{x_i ≥ 0} Σ_i F_{P_i}(x_i)` s.t. `Σ_i x_i = X`.
+- At optimum, **marginal output equalizes** across used paths: `d/dx F_{P_i}(x_i) = λ`.
+
+So PMM pools are “mined” for inventory: as long as their marginal rate is best, routers keep allocating to them.
+
+**Cross-chain:** For routes `(c_1, S) → … → (c_2, T)` including bridge edges, a bridge+swap route is chosen when:
+
+- effective cost = (swap impact + fees on DEX edges) + (bridge fee + gas + latency risk on bridge edges)  
+is lower than alternatives.
+
+If PMM pools are too tight (low k, low fee), they become preferred entry/exit ramps on many chains → inventory oscillation and frequent bot intervention.
+
+---
+
+## 5. What you can simulate right now (design-only)
+
+**A) Design routing stress test**
+
+Assume: all 11 chains; hub quote per chain; one PMM pool per cW token vs hub; optional extra quote pools on some chains. Run:
+
+- Stable-to-stable demand per chain
+- Random bridge inflow/outflow shocks
+- “Arb/MEV” agents that trade toward oracle when profitable
+
+Outputs:
+
+- Inventory drawdown distributions per cW token per chain
+- Frequency/size of bot interventions
+- How often routers pick your pools vs alternatives
+
+**B) Topology sensitivity**
+
+Compare:
+
+- **Hub model:** only `cW* / USDC` (or hub) per chain
+- **Full quote model:** `cW* / {USDC, USDT, DAI, BUSD, mUSD}`
+
+Typically: full quote increases route cycles, MEV, and inventory churn; hub model reduces reflexivity and control costs.
+
+---
+
+## 6. Moving to deployment-realistic simulation
+
+Use **`config/deployment-status.json`** (see below) to define:
+
+- Per chain: cW token addresses, anchor stable addresses, which PMM pools exist and their params (fee, k, initial liquidity), and whether each pool is “defense” vs “public routing.”
+
+With that, you can simulate: reachable routes (graph correctness), pool parameters (k, fee), and bridge availability — even before feeding real pool balances.
+
+---
+
+## 7. Three metrics to watch
+
+1. **Router capture ratio**
+   - `capture(T, c) = (volume routed through your PMM pools) / (total relevant stable volume on chain c for token T)`
+
+2. **Inventory churn**
+   - `churn(T, c) = Σ_t |ΔI_{T,t}| / I_T^*`
+   - High churn → expensive rebalancing and bot intervention.
+
+3. **Intervention cost**
+   - Bridge/mint/burn volume and cost needed to keep pegs inside band.
+
+Interpretation: aim to be a **peg stabilizer** (good); avoid becoming the **global routing venue** (expensive).
+
+---
+
+## 8. Config and params
+
+- **Design graph:** `config/token-map.json`, `config/chains.json`, `config/pool-matrix.json`
+- **Deployed graph:** `config/deployment-status.json`
+- **Simulation parameters:** `config/simulation-params.json` (hub per chain, default k, fee, inventory targets)
+- **Peg bands:** `config/peg-bands.json`