# 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`