146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
# 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.
|