# 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
- stress-deployable leverage: 1-1.5x
- target leverage for future audited optimization: 2-3x
- deployable optimizer candidates capped at 1.5x until external approvals exist
- 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.0577` | `0` | `0` | Uses conservative 1.5x stress-deployable leverage. |
| `high_vol_sigma_spike` | `0.0409` | `0` | `0.0002` | Uses conservative 1.5x stress-deployable leverage. |
| `bank_run_redemption_spike` | `-0.1762` | `0` | `0.2186` | Redemption stress survives below the 25% drawdown gate. |
| `leverage_sweep_1x_to_4x` | `0.0679` top deployable | `0` | `0` | Top deployable candidate is capped at 1.5x by policy. |

Interpretation:

- Crash/high-volatility profiles require conservative leverage under current assumptions.
- Bank-run defense must remain below the 25% p95 drawdown gate.
- Optimizer may still simulate 2x-4x candidates, but policy prevents them from being marked deployable until governance/audit evidence changes the cap.

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