Add cW M1 PMM stabilization mesh: docs, config, spec, peg bands, pool matrix

Made-with: Cursor

docs/01-token-map.md

@@ -0,0 +1,24 @@
+# Token Map (Canonical)
+
+## Home network (ChainID 138)
+
+**Mint / canonical inventory**
+
+- **Stables**: cUSDT, cUSDC, cAUSDT, cEURC, cEURT, cUSDW
+- **WETH / ETH**: WETH9, WETH10, ETH
+
+Canonical addresses for Chain 138 are in the parent repo: `docs/11-references/CHAIN138_TOKEN_ADDRESSES.md` and `config/token-mapping-multichain.json`.
+
+## Public networks (examples)
+
+Chains: 1 (Ethereum), 10 (Optimism), 56 (BSC), 100 (Gnosis), 137 (Polygon), 42161 (Arbitrum), 8453 (Base), 43114 (Avalanche), 25 (Cronos), 42220 (Celo), 1111 (Wemix), and others as needed.
+
+**Bridged representations (cW\*)**
+
+- cWUSDT, cWUSDC, cWAUSDT, cWEURC, cWEURT, cWUSDW
+
+**Public “anchor” stables to trade against**
+
+- USDT, USDC, mUSD, BUSD, DAI (per chain availability)
+
+Machine-readable mapping: [../config/token-map.json](../config/token-map.json).

docs/02-pool-topology.md

@@ -0,0 +1,33 @@
+# Pool Topology (Single-Sided PMM)
+
+## A. Public “Edge Pools” (primary stabilization rails)
+
+On **each public chain**, for each **cW\*** token, create **single-sided PMM pools** against the chain’s most liquid stables.
+
+For each chain `C` and each wrapped token `T ∈ {cWUSDT, cWUSDC, cWAUSDT, cWEURC, cWEURT, cWUSDW}`:
+
+Create pools such as:
+
+- `T / USDC`
+- `T / USDT`
+- `T / DAI`
+- `T / BUSD` (where relevant)
+- `T / mUSD` (where relevant)
+
+**Single-sided deposit is on the cW\*** side** (controllable inventory). The market provides the quote side via traders/arbs.
+
+Benefits:
+
+- Tight peg corridor around oracle price
+- Arbitrage can “heal” cross-chain drifts
+- Inventory-based signals for bridge flow pressure
+
+## B. Optional “Cross-Stable Hub” Pools
+
+To reduce quote fragmentation and pool count:
+
+- Pick **one quote stable per chain** as the “hub” (usually USDC, or USDT on some chains).
+- Deploy only `T / HUB` for each `T`.
+- Rely on existing deep markets (USDC/USDT/DAI) on that chain for secondary conversion.
+
+Configuration: [../config/pool-matrix.json](../config/pool-matrix.json), [../config/chains.json](../config/chains.json).

docs/03-bot-mesh.md

@@ -0,0 +1,20 @@
+# Bot-Driven Stabilization Mesh
+
+The mesh is a set of bots that watch **deviation**, **inventory**, and **bridge flow**, then re-balance by adding/removing cW inventory and executing trades to compress spreads.
+
+## Mesh definition
+
+For each public chain `C`, the bot manages a graph:
+
+**Nodes**
+
+- cWUSDT, cWUSDC, cWAUSDT, cWEURC, cWEURT, cWUSDW
+- USDT, USDC, DAI, BUSD, mUSD (anchor stables on that chain)
+
+**Edges**
+
+- Each single-sided PMM pool deployed: `cW* / stable`
+
+The mesh is **centered on each cW token** with spokes to the anchor stables.
+
+See [04-bot-policy.md](04-bot-policy.md) for inputs, actions, and [07-mesh-reflexivity.md](07-mesh-reflexivity.md) for risk controls.

docs/04-bot-policy.md

@@ -0,0 +1,43 @@
+# Bot Policy (What It Actually Does)
+
+## Inputs (per pool)
+
+- **Oracle price** `P_oracle(T)` — target peg: 1.00 for USD stables; FX for EUR tokens
+- **Pool mid price** `P_pool(T)`
+- **Deviation**: `δ = (P_pool - P_oracle) / P_oracle`
+- **Inventory imbalance** on cW side (how much of your token remains vs baseline)
+- Public chain liquidity/volatility conditions
+- Bridge backlog / mint-burn queue status (if available)
+
+## Actions
+
+### 1. Tight-peg maintenance trades
+
+- If `P_pool(T) > P_oracle + band` → bot **sells** `T` into pool (adds T inventory / absorbs quote)
+- If `P_pool(T) < P_oracle - band` → bot **buys** `T` from pool (removes T inventory / spends quote)
+
+### 2. Inventory re-centering
+
+- If pool is “too drained” of T (or too full), bot adjusts by:
+  - Adding/removing single-sided liquidity on T side
+  - Optionally bridging more T from ChainID 138 or redeeming back
+
+### 3. Cross-pool routing
+
+When multiple quotes exist (USDT/USDC/DAI), the bot routes to the best edge:
+
+- Trade where slippage + fee is lowest
+- Optionally rebalance quote asset via existing DEX routes (USDC ↔ USDT ↔ DAI)
+
+### 4. Bridge-aware throttling
+
+- If the bridge is congested or risk flags trip, bot widens bands / reduces exposure
+
+## Peg bands
+
+See [../config/peg-bands.json](../config/peg-bands.json) and [05-oracles.md](05-oracles.md). Summary:
+
+- **USD-pegged**: Normal ±10–25 bps; stress ±50–150 bps; circuit break >2%
+- **EUR-pegged**: Normal ±25–50 bps; stress ±100–250 bps; anchor via EURUSD oracle
+
+State machine and pseudo-code: [../spec/bot-state-machine.md](../spec/bot-state-machine.md), [../spec/bot-pseudo-code.md](../spec/bot-pseudo-code.md).

docs/05-oracles.md

@@ -0,0 +1,20 @@
+# Oracles (Non-Negotiable for PMM Pegged Systems)
+
+## Minimum viable
+
+- **USD tokens**: `P_oracle = 1.00` (with external sanity check)
+- **EUR tokens**: **EURUSD** feed
+- Optional: stablecoin health feeds (depeg detection)
+
+## Requirements
+
+- **Median of multiple sources** (or fallback hierarchy)
+- **Heartbeat + staleness checks**
+- **If oracle stale** → widen bands or pause active trades
+
+## Policy
+
+- Do not trade against a stale oracle; treat staleness as a risk trigger.
+- Document fallback order (e.g. primary chainlink, secondary Pyth, tertiary internal).
+
+Config and peg bands: [../config/peg-bands.json](../config/peg-bands.json).

docs/06-deployment-recipe.md

@@ -0,0 +1,33 @@
+# Deployment Recipe (Step-by-Step)
+
+## 1. Choose hub stable per chain
+
+- Typically **USDC** or **USDT** per chain. See [../config/chains.json](../config/chains.json).
+
+## 2. Per-chain deployment
+
+For each public chain:
+
+1. Deploy **cW\* / HUB** single-sided PMM pools (start here).
+2. Optionally expand to extra quote stables (DAI, BUSD, mUSD) where depth is needed.
+
+## 3. Launch bot v1
+
+- Deviation watcher
+- Simple buy/sell to compress δ
+- Inventory thresholds
+
+## 4. Bot v2
+
+- Cross-quote routing
+- Bridge-aware mint/burn management
+- Circuit-break risk controls
+
+## 5. Pool matrix and priority
+
+See [../config/pool-matrix.json](../config/pool-matrix.json). Fill for priority chain first (e.g. 1, 56, or 137), then replicate to others.
+
+## 6. Verification
+
+- Verify pool addresses and token addresses on each chain.
+- Confirm oracle feeds and staleness handling before enabling bot.

docs/07-mesh-reflexivity.md

@@ -0,0 +1,14 @@
+# Mesh Reflexivity (Risk Controls)
+
+If the bot is active across many pools, feedback loops can occur (e.g. bot buys in one pool, sells in another, churns fees, moves price).
+
+## Controls to prevent reflexivity
+
+1. **Global per-token trade budget** per time window — cap total volume per token across all pools.
+2. **Minimum improvement threshold** — do not trade unless δ improves by X bps net of fees.
+3. **Cooldowns per pool** after intervention — avoid rapid repeated trades on the same pool.
+4. **Priority order** — fix **HUB pool first**, then others; avoid circular arbitrage across quotes.
+
+## Policy memo
+
+These controls should be documented in operational playbooks and enforced in bot code (v2). See [../spec/bot-state-machine.md](../spec/bot-state-machine.md).