Add capital efficiency risk simulation

2026-04-27 11:26:55 -07:00
parent 1cf845cb3a
commit 818e864d2b
15 changed files with 1111 additions and 13 deletions
--- a/docs/12-sim-scorecard.md
+++ b/docs/12-sim-scorecard.md
@@ -36,6 +36,15 @@ Every run (hub-only, full-quote, bridge shock) should produce a scorecard with a
 | `micro_trade_gas_cost_total` | number | Abstract gas budget consumed by support trades |
 | `scenario` | string | e.g. `hub_only_11`, `full_quote_1_56_137`, `bridge_shock_137_56` |
 | `runId` | string | Optional run identifier |
+| `roi_mean` | number | Mean capital-efficiency ROI when Monte Carlo is enabled |
+| `roi_p05` / `roi_p95` | number | 5th/95th percentile ROI band |
+| `pnl_distribution` | object | PnL percentiles `{p05,p50,p95}` |
+| `max_drawdown_p95` | number | 95th percentile max drawdown |
+| `liquidation_probability` | number | Fraction of Monte Carlo paths that liquidated |
+| `peg_deviation_frequency` | number | Fraction of path-epochs above peg circuit-break threshold |
+| `external_liquidity_floor_violations` | integer | Count of path-epochs below minimum external liquidity before clamp |
+| `volatility_throttle_events` | integer | Count of sigma-triggered deleverage/allocation throttle events |
+| `spread_adjustment_events` | integer | Count of volatility/liquidity/peg-driven spread adjustments |

 **Example (minimal):**

@@ -79,6 +88,17 @@ From [10-behavioral-stability-analysis.md](10-behavioral-stability-analysis.md):
 **Pass:** All gates satisfied for the scenario.  
 **Fail:** Any gate violated; do not treat scenario as deployable without parameter change or topology reduction.

+Capital-efficiency scenarios also use `config/capital-efficiency-policy.json` gates:
+
+| Gate | Default |
+|------|---------|
+| Liquidation probability | `<= 0.02` |
+| p95 max drawdown | `<= 0.25` |
+| Peg deviation frequency | `<= 0.05` |
+| External liquidity floor violations | `0` |
+| Deployable leverage | `<= 3x` |
+| Hard leverage ceiling | `<= 4x` |
+
 ---

 ## 3. Phase 0 comparison (three scenarios)
--- a/docs/16-capital-efficiency-risk-simulation.md
+++ b/docs/16-capital-efficiency-risk-simulation.md
@@ -0,0 +1,144 @@
+# Capital Efficiency Risk Simulation
+
+This module extends the existing PMM routing simulator with a simulation-only treasury/risk overlay. It evaluates capital allocation, leverage, spread policy, peg pressure, volatility throttles, external liquidity floors, and liquidation probability before any live contract work.
+
+The model is intentionally wired to the current ecosystem:
+
+- PMM routing, capture, churn, intervention cost, and peg deviation still come from `scripts/run-scenario.cjs`.
+- Risk defaults live in `config/capital-efficiency-policy.json`.
+- Scenario-specific capital assumptions live under `capitalEfficiency` in `config/scenarios/*.json`.
+- `deployment-status.json` remains the deployed-graph source when `graphMode = deployed`.
+
+This is not a live leverage configuration. Contract work remains gated by audit engagement evidence, governance approval, operational dashboards, and runbooks.
+
+## Model
+
+Each Monte Carlo path tracks:
+
+- `T`: total capital
+- `alpha`: treasury/yield allocation
+- `L`: leverage
+- `sigma`: mean-reverting volatility
+- `P`: peg price around 1.0
+- external liquidity floor
+- collateral/debt liquidation state
+
+Per epoch, capital updates with:
+
+```text
+T_next = T + T * (yield + market_making - volatility_drag - intervention_drag - redemption_drag)
+```
+
+Volatility follows:
+
+```text
+sigma_next = sigma + kappa * (sigma_bar - sigma) + eta * N(0, 1)
+```
+
+Peg dynamics follow a lightweight imbalance/arb model:
+
+```text
+P_next = P + beta * imbalance - arb_liquidity_coefficient * (P - 1)
+```
+
+If volatility exceeds `sigmaCrit`, the simulator reduces effective allocation/leverage and widens spread up to the configured ceiling. If external liquidity drops below the policy floor, the path records a violation and clamps allocation.
+
+## Run
+
+Baseline routing scenarios are unchanged:
+
+```bash
+node scripts/run-scenario.cjs hub_only_11
+node scripts/run-scenario.cjs bridge_shock_137_56
+```
+
+Capital stress scenarios:
+
+```bash
+node scripts/run-scenario.cjs crash_40pct_external_asset
+node scripts/run-scenario.cjs high_vol_sigma_spike
+node scripts/run-scenario.cjs bank_run_redemption_spike
+```
+
+Optimizer sweep:
+
+```bash
+node scripts/run-scenario.cjs --optimizer leverage_sweep_1x_to_4x
+```
+
+`leverage_sweep_1x_to_4x` also enables optimizer mode by default.
+
+CI-style validation:
+
+```bash
+node scripts/validate-capital-efficiency.cjs
+```
+
+## Scorecard Additions
+
+Capital-enabled scenarios emit:
+
+- `roi_mean`, `roi_p05`, `roi_p95`
+- `pnl_distribution`
+- `max_drawdown_p95`
+- `liquidation_probability`
+- `peg_deviation_frequency`
+- `external_liquidity_floor_violations`
+- `volatility_throttle_events`
+- `spread_adjustment_events`
+
+Optimizer output ranks parameter candidates by ROI penalized for liquidation, drawdown, and peg frequency. A candidate is deployable only if it passes the policy gates in `capital-efficiency-policy.json`.
+
+## Institutional Defaults
+
+The default posture is conservative:
+
+- external liquidity floor: 20% of capital
+- target leverage: 2-3x
+- deployable optimizer candidates capped at 3x
+- hard leverage rejection above 4x
+- default max LTV: 65%
+- hard LTV ceiling: 75%
+- target spread: 30-50 bps
+- public PMM remains peg support, not the primary profit engine
+
+Any later Solidity blueprint must consume the simulator outputs as evidence, not as authority to deploy leverage automatically.
+
+## Latest Local Run
+
+Generated on 2026-04-27 from the current configs:
+
+| Scenario | ROI mean | Liquidation probability | p95 drawdown | Notes |
+|---|---:|---:|---:|---|
+| `chain138_deployed_capital_efficiency` | `0.0542` | `0` | `0` | Base deployed Chain 138 graph survives under defaults. |
+| `crash_40pct_external_asset` | `-0.0646` | `1` | `0.08` | Crash scenario liquidates at the tested 2.5x leverage. |
+| `high_vol_sigma_spike` | `-0.0665` | `1` | `0.0841` | Volatility spike liquidates at the tested 2.5x leverage. |
+| `bank_run_redemption_spike` | `-0.1586` | `0` | `0.2177` | Redemption stress survives but consumes most drawdown budget. |
+| `leverage_sweep_1x_to_4x` | `0.1359` top deployable | `0` | `0` | Top deployable candidate is capped at 3x by policy. |
+
+Interpretation:
+
+- Crash/high-volatility profiles are not deployable at 2.5x without lower allocation, lower leverage, stronger collateral haircuts, or faster deleveraging assumptions.
+- Bank-run defense survives locally but should be treated as near-limit because p95 drawdown is close to the 25% default gate.
+- Optimizer may still simulate 3.5x/4x candidates, but policy prevents them from being marked deployable.
+
+## Dashboard And Runbook Requirements
+
+Before any live leverage contract work, operations must expose:
+
+- ROI band: `roi_mean`, `roi_p05`, `roi_p95`
+- Drawdown: `max_drawdown_p95`
+- Liquidation: `liquidation_probability`
+- Liquidity floor: `external_liquidity_floor_violations`
+- Peg defense: `peg_deviation_frequency`
+- Throttles: `volatility_throttle_events`
+- Spread changes: `spread_adjustment_events`
+- Existing PMM health: capture, churn, intervention cost, and worst-pool diagnostics
+
+Deployment remains blocked until:
+
+- Smart contract audit engagement evidence exists.
+- Governance approval is recorded.
+- Risk dashboard and alerting are live.
+- Operator runbook covers deleverage, circuit breaker, redemption throttle, and treasury liquidity deployment.
+- Treasury/liquidity commitments are documented.
--- a/docs/17-capital-efficiency-contract-blueprint-gate.md
+++ b/docs/17-capital-efficiency-contract-blueprint-gate.md
@@ -0,0 +1,28 @@
+# Capital Efficiency Contract Blueprint Gate
+
+Status: blocked by simulator gates and external institutional prerequisites.
+
+This document is the handoff point for the requested contract blueprint. It intentionally does not define deployable Solidity yet because current local stress results show liquidation under the `crash_40pct_external_asset` and `high_vol_sigma_spike` scenarios at the tested 2.5x leverage profile.
+
+## Required Before Blueprint
+
+- `node scripts/validate-capital-efficiency.cjs` passes.
+- Stress scenarios pass the policy gates in `config/capital-efficiency-policy.json`.
+- Crash and high-volatility scenarios no longer liquidate under the candidate profile.
+- Audit engagement evidence is recorded.
+- Governance approval evidence is recorded.
+- Risk dashboard and alerting are operational.
+- Operator runbook covers deleverage, circuit breaker, redemption throttle, and treasury liquidity deployment.
+- Treasury/liquidity commitments are documented.
+
+## Blueprint Scope Once Unblocked
+
+- Treasury engine: allocation caps, yield strategy adapter interface, idle/external liquidity floor.
+- Liquidity engine: PMM/DODO provider hooks, pool role separation, route exposure controls.
+- Leverage engine: LP-token collateral accounting, borrow/redeploy loop, max LTV checks.
+- Risk engine: volatility throttle, spread adjustment, peg circuit breaker, liquidation guard.
+- Keeper flow: rebalance, auto-deleverage, and dashboard event emission.
+
+## Current Decision
+
+Do not implement live leverage contracts. Continue tuning simulation policy and scenarios until deployable candidates pass crash, high-volatility, bank-run, and deployed Chain 138 graph checks.