cross-chain-pmm-lps/README.md

# cW M1 PMM Stabilization Mesh

Implementation-grade blueprint for the **home-minted M1 suite on ChainID 138**, bridged as **cW\*** wrappers onto public chains, and stabilized via a **bot-managed single-sided PMM mesh** that trades against native stables on each public chain.

## Purpose

- **Token map**: Canonical M1 on 138 (cUSDT, cUSDC, cAUSDT, cEURC, cEURT, cUSDW, WETH9/10, ETH); bridged **cW\*** representations on public chains; anchor stables per chain.
- **Pool topology**: Single-sided PMM edge pools per chain (`cW* / HUB` or multi-quote).
- **Bot-driven mesh**: Deviation watcher, inventory re-centering, cross-pool routing, bridge-aware throttling; peg bands; oracles; mesh reflexivity controls.

## Quick start

1. See [docs/01-token-map.md](docs/01-token-map.md) for canonical and cW* token mapping.
2. See [docs/02-pool-topology.md](docs/02-pool-topology.md) for edge pool design.
3. See [docs/06-deployment-recipe.md](docs/06-deployment-recipe.md) for step-by-step deployment.
4. Config: [config/token-map.json](config/token-map.json), [config/pool-matrix.json](config/pool-matrix.json), [config/peg-bands.json](config/peg-bands.json), [config/chains.json](config/chains.json).
5. **Simulation:** Two-layer model (design vs deployed graph), routing supergraph, PMM edge function, and scenario-based sim: [docs/08-simulation-model.md](docs/08-simulation-model.md). First-pass params: [config/simulation-params.json](config/simulation-params.json), [docs/09-simulation-params-sheet.md](docs/09-simulation-params-sheet.md). Deployment-realistic sim: fill [config/deployment-status.json](config/deployment-status.json).
6. **Behavioral stability:** What to simulate first, three metrics in economic terms, where it can break: [docs/10-behavioral-stability-analysis.md](docs/10-behavioral-stability-analysis.md). **Safe inventory sizing** (closed-form I_T^* per chain): [docs/11-safe-inventory-sizing.md](docs/11-safe-inventory-sizing.md).
7. **Tools:** [scripts/size-inventory.cjs](scripts/size-inventory.cjs) — regenerate I_T^*, D_0 from params (single command, deterministic; see [scripts/README.md](scripts/README.md)). [scripts/validate-deployment-status.cjs](scripts/validate-deployment-status.cjs) — CI validation for deployment-status (phase 1 tokens when bridge=true; pool role/fee/k/tokens).
8. **Sim scorecard:** Simulator output contract and pass/fail gates: [docs/12-sim-scorecard.md](docs/12-sim-scorecard.md), [config/scorecard-schema.json](config/scorecard-schema.json). Bridge edge with optional **latency risk** ρ(Δt): [docs/08-simulation-model.md](docs/08-simulation-model.md) §2.
9. **Scenario contract:** Formal scenario input schema and three Phase 0 scenarios: [config/scenario-schema.json](config/scenario-schema.json), [config/scenarios/](config/scenarios/). **Routing exposure controls:** [config/routing-controls.json](config/routing-controls.json) (maxTradeSize, cooldown, minImprovementBps, publicRoutingEnabled). **Real sim (PR#1):** `node scripts/run-scenario.cjs hub_only_11` — graph from configs, PMM state, path enumeration + waterfilling, real scorecard (drain half-life, path concentration, capture, churn); see [spec/13-minimal-router-sim.md](spec/13-minimal-router-sim.md).

## Parent repo

This repository is intended as a **submodule** of the [proxmox](https://github.com/Order-of-Hospitallers/proxmox) infrastructure repo. Canonical token addresses for Chain 138 and multi-chain mapping are in the parent:

- Parent: `config/token-mapping-multichain.json`, `docs/11-references/CHAIN138_TOKEN_ADDRESSES.md`
- This repo extends with cW* contract addresses per public chain and stabilization mesh config.

## Adding as submodule (parent repo)

From the proxmox repo root:

```bash
git submodule add https://gitea.d-bis.org/d-bis/cross-chain-pmm-lps.git cross-chain-pmm-lps
```