d-bis/cross-chain-pmm-lps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clear local capital efficiency simulation gates

Browse Source
This commit is contained in:
defiQUG
2026-04-27 15:58:17 -07:00
parent 818e864d2b
commit fb4d86ae38
13 changed files with 195 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -22,7 +22,7 @@ Implementation-grade blueprint for the **home-minted M1 suite on ChainID 138**,
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).
10. **USD-wrapper support lane:** Gas-budgeted micro-trade policy for `cWUSDC` / `cWUSDT` and a runnable scenario: [docs/15-gas-budgeted-micro-trade-support.md](docs/15-gas-budgeted-micro-trade-support.md), [config/scenarios/micro_support_usd_wrappers_1_56_137.json](config/scenarios/micro_support_usd_wrappers_1_56_137.json).
11. **Capital efficiency risk simulation:** Simulation-only Monte Carlo overlay for treasury allocation, leverage, peg pressure, volatility throttles, liquidation probability, and parameter optimization: [docs/16-capital-efficiency-risk-simulation.md](docs/16-capital-efficiency-risk-simulation.md), [docs/17-capital-efficiency-contract-blueprint-gate.md](docs/17-capital-efficiency-contract-blueprint-gate.md), [config/capital-efficiency-policy.json](config/capital-efficiency-policy.json), stress scenarios under [config/scenarios/](config/scenarios/), and CI-style validation via `node scripts/validate-capital-efficiency.cjs`.
11. **Capital efficiency risk simulation:** Simulation-only Monte Carlo overlay for treasury allocation, leverage, peg pressure, volatility throttles, liquidation probability, and parameter optimization: [docs/16-capital-efficiency-risk-simulation.md](docs/16-capital-efficiency-risk-simulation.md), [docs/17-capital-efficiency-contract-blueprint-gate.md](docs/17-capital-efficiency-contract-blueprint-gate.md), [docs/18-capital-efficiency-risk-dashboard-and-runbook.md](docs/18-capital-efficiency-risk-dashboard-and-runbook.md), [docs/19-capital-efficiency-external-approval-evidence.md](docs/19-capital-efficiency-external-approval-evidence.md), [config/capital-efficiency-policy.json](config/capital-efficiency-policy.json), [config/treasury-liquidity-commitments.json](config/treasury-liquidity-commitments.json), stress scenarios under [config/scenarios/](config/scenarios/), and CI-style validation via `node scripts/validate-capital-efficiency.cjs`.
## Parent repo

9
config/capital-efficiency-policy.json
View File

@@ -19,6 +19,7 @@
"alphaBalanced": [0.65, 0.75],
"alphaYieldDominant": [0.75, 0.9],
"leverageSafe": [1, 1],
"leverageStressDeployable": [1, 1.5],
"leverageTarget": [2, 3],
"leverageUnstableAbove": 4,
"spreadCompetitiveBps": 10,
@@ -63,7 +64,7 @@
"bankRunRedemptionFeeBps": 100
},
"gates": {
"maxDeployableLeverage": 3,
"maxDeployableLeverage": 1.5,
"maxLiquidationProbability": 0.02,
"maxDrawdownP95": 0.25,
"maxPegDeviationFrequency": 0.05,
@@ -85,8 +86,8 @@
],
"auditEngagementEvidence": null,
"governanceApprovalEvidence": null,
"riskDashboardEvidence": null,
"operatorRunbookEvidence": null,
"treasuryLiquidityCommitmentEvidence": null
"riskDashboardEvidence": "docs/18-capital-efficiency-risk-dashboard-and-runbook.md",
"operatorRunbookEvidence": "docs/18-capital-efficiency-risk-dashboard-and-runbook.md",
"treasuryLiquidityCommitmentEvidence": "config/treasury-liquidity-commitments.json"
}
}

4
config/scenarios/bank_run_redemption_spike.json
View File

@@ -24,8 +24,8 @@
"epochs": 180,
"seed": 138403,
"initialCapital": 1000000,
"alpha": 0.68,
"leverage": 2,
"alpha": 0.65,
"leverage": 1.5,
"spreadBps": 45,
"volumeEfficiency": 2.5,
"stress": {

4
config/scenarios/crash_40pct_external_asset.json
View File

@@ -23,8 +23,8 @@
"epochs": 180,
"seed": 138401,
"initialCapital": 1000000,
"alpha": 0.7,
"leverage": 2.5,
"alpha": 0.65,
"leverage": 1.5,
"spreadBps": 40,
"volumeEfficiency": 2.5,
"stress": {

4
config/scenarios/high_vol_sigma_spike.json
View File

@@ -23,8 +23,8 @@
"epochs": 180,
"seed": 138402,
"initialCapital": 1000000,
"alpha": 0.72,
"leverage": 2.5,
"alpha": 0.65,
"leverage": 1.5,
"spreadBps": 40,
"volumeEfficiency": 3,
"stress": {

2
config/scenarios/leverage_sweep_1x_to_4x.json
View File

@@ -33,7 +33,7 @@
"topN": 12,
"grid": {
"alpha": [0.65, 0.7, 0.75, 0.8],
"leverage": [1, 2, 2.5, 3, 3.5, 4],
"leverage": [1, 1.25, 1.5, 2, 2.5, 3, 3.5, 4],
"spreadBps": [30, 40, 50],
"pmmK": [0.1, 0.15],
"liquidityTargetUnits": [500000, 1000000]

27
config/treasury-liquidity-commitments.json Normal file
View File

@@ -0,0 +1,27 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Simulation evidence file for treasury/liquidity commitments. Replace placeholder sources with signed commitments before any live leverage contract work.",
"version": "1.0.0",
"updated": "2026-04-27",
"status": "simulation_only",
"minimumExternalLiquidityPct": 0.2,
"bridgeBufferPolicy": {
"formula": "bridgeReserve >= peakBridgeOutflow * latency",
"safetyFactor": 3
},
"sources": [
{
"id": "SIM-POL-001",
"type": "policy_floor",
"description": "At least 20% of capital remains external/idle liquidity in every deployable profile.",
"evidence": "config/capital-efficiency-policy.json",
"signedCommitment": null
}
],
"emergencyAuthority": {
"multisig": null,
"operatorGroup": null,
"notes": "Must be populated with real authority evidence before live leverage deployment."
},
"liveDeploymentAllowed": false
}

2
docs/12-sim-scorecard.md
View File

@@ -96,7 +96,7 @@ Capital-efficiency scenarios also use `config/capital-efficiency-policy.json` ga
| p95 max drawdown | `<= 0.25` |
| Peg deviation frequency | `<= 0.05` |
| External liquidity floor violations | `0` |
| Deployable leverage | `<= 3x` |
| Deployable leverage | `<= 1.5x` |
| Hard leverage ceiling | `<= 4x` |
---

19
docs/16-capital-efficiency-risk-simulation.md
View File

@@ -94,8 +94,9 @@ Optimizer output ranks parameter candidates by ROI penalized for liquidation, dr
The default posture is conservative:
- external liquidity floor: 20% of capital
- target leverage: 2-3x
- deployable optimizer candidates capped at 3x
- 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%
@@ -111,16 +112,16 @@ 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. |
| `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 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.
- 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

9
docs/17-capital-efficiency-contract-blueprint-gate.md
View File

@@ -1,17 +1,16 @@
# Capital Efficiency Contract Blueprint Gate
Status: blocked by simulator gates and external institutional prerequisites.
Status: locally blocked only by 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.
This document is the handoff point for the requested contract blueprint. It intentionally does not define deployable Solidity yet because live leverage remains blocked until audit engagement and governance evidence exist. The current local deployable simulation posture caps leverage at `1.5x`.
## 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.
- Risk dashboard and alerting are specified in `docs/18-capital-efficiency-risk-dashboard-and-runbook.md` and operational before live deployment.
- Operator runbook covers deleverage, circuit breaker, redemption throttle, and treasury liquidity deployment.
- Treasury/liquidity commitments are documented.
@@ -25,4 +24,4 @@ This document is the handoff point for the requested contract blueprint. It inte
## 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.
Do not implement live leverage contracts. The local simulator gates can be satisfied at conservative leverage, but audit engagement and governance approval remain mandatory external prerequisites.

78
docs/18-capital-efficiency-risk-dashboard-and-runbook.md Normal file
View File

@@ -0,0 +1,78 @@
# Capital Efficiency Risk Dashboard And Operator Runbook
Status: simulation-only operational specification.
This document removes the local documentation blocker for dashboard and runbook requirements. It does not remove external approval blockers: audit engagement and governance approval still require signed evidence.
## Dashboard Metrics
Expose these metrics from the latest scorecards:
| Metric | Source field | Alert |
|---|---|---|
| ROI mean | `roi_mean` | Informational |
| ROI lower band | `roi_p05` | Alert if negative in deployable profile |
| ROI upper band | `roi_p95` | Informational |
| p95 drawdown | `max_drawdown_p95` | Critical if `> 0.25` |
| Liquidation probability | `liquidation_probability` | Critical if `> 0.02` |
| Peg deviation frequency | `peg_deviation_frequency` | Critical if `> 0.05` |
| External liquidity floor violations | `external_liquidity_floor_violations` | Critical if `> 0` |
| Volatility throttle events | `volatility_throttle_events` | Warning if rising versus baseline |
| Spread adjustment events | `spread_adjustment_events` | Warning if rising versus baseline |
| PMM capture | `capture_mean` | Warning if sustained above target corridor |
| Inventory churn | `churn_mean`, `churn_p95` | Warning if outside scorecard gates |
| Intervention cost | `intervention_cost_per_1M_volume` | Warning if nonlinear versus volume |
## Operator Procedures
### Deleverage
1. Stop new leverage increases.
2. Set deployable profile to `leverage <= 1.5`.
3. Reduce `alpha` to preserve the external liquidity floor.
4. Re-run:
```bash
node scripts/validate-capital-efficiency.cjs
```
5. Resume only when crash, high-volatility, and bank-run scenarios pass policy gates.
### Spread Widening
1. If volatility exceeds `sigmaCrit`, widen spread to `throttleSpreadBps`.
2. If peg deviation exceeds circuit-break threshold, widen to `circuitBreakerSpreadBps`.
3. Confirm `spread_adjustment_events` stabilizes and peg deviation frequency remains within gate.
### Redemption Throttle
1. Trigger when bank-run scorecard approaches drawdown gate.
2. Increase redemption fee according to policy.
3. Pause non-essential outflows.
4. Deploy treasury liquidity only from documented sources in `config/treasury-liquidity-commitments.json`.
### Treasury Liquidity Deployment
1. Confirm external liquidity remains at or above 20%.
2. Confirm bridge buffer satisfies `bridgeReserve >= peakBridgeOutflow * latency`.
3. Execute only through approved operator/multisig authority.
4. Record evidence before marking any live deployment gate complete.
### Peg Circuit Breaker
1. Stop adding public-routing liquidity to affected pools.
2. Prefer defense-only rebalancing.
3. Re-run deployed Chain 138 and stress scenarios.
4. Re-enable only when peg deviation frequency is within gate.
## Evidence Status
| Gate | Local status |
|---|---|
| Risk dashboard specification | Complete in this document |
| Operator runbook | Complete in this document |
| Treasury/liquidity commitment structure | Complete in `config/treasury-liquidity-commitments.json` |
| Audit engagement | External evidence required |
| Governance approval | External evidence required |
## Current Deployable Posture
Until audit and governance evidence exists, the only locally gate-passing posture is simulation-only with deployable optimizer leverage capped at `1.5x`.

31
docs/19-capital-efficiency-external-approval-evidence.md Normal file
View File

@@ -0,0 +1,31 @@
# Capital Efficiency External Approval Evidence
Status: external evidence required.
This file is the canonical evidence register for the remaining non-local blockers. Populate it with signed references before changing `liveExecutionGuard.status` away from `simulation_only`.
## Audit Engagement
| Field | Value |
|---|---|
| Firm | Pending external engagement |
| Engagement reference | Pending external engagement |
| Signed date | Pending external engagement |
| Scope | Treasury engine, liquidity engine, leverage engine, risk engine, keeper/deleverage flow, oracle/circuit breaker integration |
| Evidence URI | Pending external engagement |
## Governance Approval
| Field | Value |
|---|---|
| Body | Pending governance action |
| Resolution ID | Pending governance action |
| Approval date | Pending governance action |
| Approved policy cap | Simulation-only, max deployable leverage `1.5x` |
| Evidence URI | Pending governance action |
## Current Enforcement
- `config/capital-efficiency-policy.json` keeps `liveExecutionGuard.status = simulation_only`.
- `scripts/validate-capital-efficiency.cjs` requires dashboard, runbook, and liquidity commitment evidence paths.
- Live leverage contracts remain blocked until the pending audit and governance evidence is real, dated, and reviewable.

34
scripts/validate-capital-efficiency.cjs
View File

@@ -32,6 +32,12 @@ const REQUIRED_CAPITAL_FIELDS = [
'spread_adjustment_events',
];
const STRESS_SCENARIOS = [
'crash_40pct_external_asset',
'high_vol_sigma_spike',
'bank_run_redemption_spike',
];
function readJson(file) {
return JSON.parse(fs.readFileSync(file, 'utf8'));
}
@@ -67,21 +73,43 @@ function main() {
const policy = readJson(path.join(CONFIG_DIR, 'capital-efficiency-policy.json'));
const maxDeployableLeverage = Number(policy.gates?.maxDeployableLeverage ?? policy.risk?.hardMaxLeverage ?? 4);
const gates = policy.gates || {};
const maxLiquidationProbability = Number(gates.maxLiquidationProbability ?? 0.02);
const maxDrawdownP95 = Number(gates.maxDrawdownP95 ?? 0.25);
const maxPegDeviationFrequency = Number(gates.maxPegDeviationFrequency ?? 0.05);
const maxExternalLiquidityFloorViolations = Number(gates.maxExternalLiquidityFloorViolations ?? 0);
const guard = policy.liveExecutionGuard || {};
assert(guard.status === 'simulation_only', 'liveExecutionGuard.status must remain simulation_only until external approvals exist');
assert(guard.riskDashboardEvidence, 'risk dashboard evidence path is required');
assert(guard.operatorRunbookEvidence, 'operator runbook evidence path is required');
assert(guard.treasuryLiquidityCommitmentEvidence, 'treasury liquidity commitment evidence path is required');
for (const evidencePath of [
guard.riskDashboardEvidence,
guard.operatorRunbookEvidence,
guard.treasuryLiquidityCommitmentEvidence,
]) {
assert(fs.existsSync(path.join(ROOT, evidencePath)), `evidence path missing: ${evidencePath}`);
}
const baseline = runScenario('hub_only_11').json;
assert(baseline.capital_efficiency_enabled !== true, 'hub_only_11 unexpectedly enabled capital overlay');
for (const scenario of [
'chain138_deployed_capital_efficiency',
'crash_40pct_external_asset',
'high_vol_sigma_spike',
'bank_run_redemption_spike',
...STRESS_SCENARIOS,
]) {
const scorecard = runScenario(scenario).json;
assert(scorecard.capital_efficiency_enabled === true, `${scenario} did not emit capital overlay`);
for (const field of REQUIRED_CAPITAL_FIELDS) {
assert(Object.prototype.hasOwnProperty.call(scorecard, field), `${scenario} missing ${field}`);
}
if (STRESS_SCENARIOS.includes(scenario)) {
assert(scorecard.liquidation_probability <= maxLiquidationProbability, `${scenario} liquidation probability exceeds gate`);
assert(scorecard.max_drawdown_p95 <= maxDrawdownP95, `${scenario} p95 drawdown exceeds gate`);
assert(scorecard.peg_deviation_frequency <= maxPegDeviationFrequency, `${scenario} peg deviation frequency exceeds gate`);
assert(scorecard.external_liquidity_floor_violations <= maxExternalLiquidityFloorViolations, `${scenario} external liquidity floor violations exceed gate`);
}
}
const a = runScenario('crash_40pct_external_asset').raw;