112 lines
6.3 KiB
Markdown
112 lines
6.3 KiB
Markdown
# Scripts
|
||
|
||
## size-inventory.cjs
|
||
|
||
Regenerates **I_T^*** (inventory target) and suggested **D_0** per chain per cW token from `config/simulation-params.json`. Output includes assumptions (σ, T_refill/T_epoch, β, γ). Keeps configs honest and PRs reviewable.
|
||
|
||
**Run from repo root (cross-chain-pmm-lps):**
|
||
|
||
```bash
|
||
node scripts/size-inventory.cjs
|
||
```
|
||
|
||
**Options:**
|
||
|
||
- `--sigma 1.8` — override USD stress multiplier (default 1.5)
|
||
- `--refill-ratio 0.33` — T_refill / T_epoch (default 0.33)
|
||
- `--depth-mult 0.75` — D_0 = depth_mult * I_T^* (default 0.75)
|
||
- `--v-epoch '{"1":100000,"56":80000,"137":60000}'` — per-chain V_epoch (JSON object)
|
||
|
||
**Environment:** `V_EPOCH_<chainId>` overrides V_epoch for that chain (e.g. `V_EPOCH_1=100000`).
|
||
|
||
**Output:** JSON with `assumptions` and per-chain per-token `I_T_star`, `D_0`, `V_epoch`, `sigma`, `beta`, `gamma`, and EUR stress flag where applicable.
|
||
|
||
---
|
||
|
||
## validate-deployment-status.cjs
|
||
|
||
Validates `config/deployment-status.json` for minimum viable deployed graph. Use in CI so deployment-realistic sim cannot run with half-filled state.
|
||
|
||
**Rules:**
|
||
|
||
- If `bridgeAvailable === true` on a chain, `cwTokens` must include at least **cWUSDT** and **cWUSDC** (phase 1).
|
||
- For each `pmmPool` and each `pmmPoolsVolatile[]` entry: `role` ∈ {defense, public_routing, truu_routing}; `feeBps` and `k` present; `base`/`quote` (or `tokenIn`/`tokenOut`) exist in `cwTokens` or `anchorAddresses` (e.g. mainnet **TRUU** under `anchorAddresses.TRUU`). Non-zero `poolAddress` must not be the zero address.
|
||
- For each `gasReferenceVenues[]` entry: `supported` must be explicit, `aggregatorOnly` is only valid for `1inch`, `supported=false` means the lane is explicitly unsupported (and can never be live), and `supported=true` with `live=false` / `routingVisible=false` means the lane is planned or staged.
|
||
- `aggregatorOnly=true` rows are routing overlays, not stand-alone live venues.
|
||
|
||
**Run:**
|
||
|
||
```bash
|
||
node scripts/validate-deployment-status.cjs
|
||
```
|
||
|
||
**Exit code:** 0 if valid, 1 if invalid (errors to stderr).
|
||
|
||
**Native protocol-only examples:**
|
||
|
||
```bash
|
||
node scripts/validate-deployment-status.cjs config/validation-examples/native-protocol-only.valid.json
|
||
node scripts/validate-deployment-status.cjs config/validation-examples/native-protocol-only.invalid.json
|
||
```
|
||
|
||
The invalid example intentionally includes a placeholder scaffold and a non-native live `1inch` row to exercise the rejection path.
|
||
|
||
**Parent proxmox repo:** live Mainnet cW/TRUU pool deploy and ratio-matched top-up scripts live under `scripts/deployment/` (`deploy-mainnet-pmm-cw-truu-pool.sh`, `add-mainnet-truu-pmm-topup.sh`); see `docs/03-deployment/MAINNET_PMM_TRUU_CWUSD_PEG_AND_BOT_RUNBOOK.md` §11.
|
||
|
||
---
|
||
|
||
## run-scenario.cjs
|
||
|
||
Builds the **real** routing graph from configs, runs epochs with PMM state updates, path enumeration + waterfilling, **arb step** (implied-price deviation, capped corrective trades, profit gate), **bot step** (inject/withdraw at 0.5×/1.5× I_T^* with intervention cost β/γ/ρ), and optional **bridge shock** trades. Emits a **real scorecard** (PR#2). Runs are **deterministic** when `scenario.seed` is set or derived from scenario name.
|
||
|
||
Scenarios may also include an optional **microTradePolicy** for gas-budgeted support trades in selected USD wrapper rails. This is meant to model tiny, controlled `cWUSDC` / `cWUSDT` turnover-seeding or inventory-corrective activity, not to turn the PMM into a venue.
|
||
|
||
**Configs used:** `simulation-params.json`, `token-map.json`, `routing-controls.json`; `deployment-status.json` only when `graphMode = deployed`. Pool topology from `pool-matrix.json` and scenario `topology` / `fullQuoteChains`.
|
||
|
||
**Tuning constants (in script):**
|
||
|
||
| Constant | Value | Purpose |
|
||
|----------|--------|---------|
|
||
| `PROBE_SIZE` | 1000 | Units for path cost probe (k-shortest by cost) |
|
||
| `K_PATHS` | 5 | Max candidate paths per trade for waterfilling |
|
||
| `CHUNK_FRACTION` | 0.05 | 5% of trade per chunk; marginal-equalization step size |
|
||
| `AMM_DEPTH_UNITS` | 10e6 | Background AMM depth (notional; infinite-depth approx in code) |
|
||
| `AMM_FEE_BPS` | 5 | Fee for anchor↔anchor stable swaps |
|
||
|
||
**Run:**
|
||
|
||
```bash
|
||
node scripts/run-scenario.cjs hub_only_11
|
||
node scripts/run-scenario.cjs --scenario full_quote_1_56_137
|
||
node scripts/run-scenario.cjs bridge_shock_137_56
|
||
node scripts/run-scenario.cjs micro_support_usd_wrappers_1_56_137
|
||
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
|
||
node scripts/run-scenario.cjs --optimizer leverage_sweep_1x_to_4x
|
||
```
|
||
|
||
**Output:** JSON scorecard including: `capture_mean`, `churn_mean`, `drain_half_life_epochs`, `path_concentration_index`; `intervention_cost_total` / `intervention_cost_inject_total` / `intervention_cost_withdraw_total` / `intervention_cost_by_chain` / `intervention_cost_per_1M_volume`; `micro_trade_count` / `micro_trade_volume_total` / `micro_trade_gas_cost_total`; `peak_deviation_bps` (post-arb), `peak_deviation_bps_pre_arb`, `peak_deviation_bps_post_arb`, `peak_deviation_bps_post_bot`; `arb_volume_total`, `arb_profit_total` (execution-based, not mid). See [docs/12-sim-scorecard.md](../docs/12-sim-scorecard.md) and [config/scorecard-schema.json](../config/scorecard-schema.json).
|
||
|
||
When `capitalEfficiency.enabled = true`, output also includes Monte Carlo capital-risk metrics: `roi_mean`, `roi_p05`, `roi_p95`, `pnl_distribution`, `max_drawdown_p95`, `liquidation_probability`, `peg_deviation_frequency`, `external_liquidity_floor_violations`, `volatility_throttle_events`, and `spread_adjustment_events`. Optimizer mode emits ranked parameter candidates and never treats leverage above the configured hard ceiling as deployable.
|
||
|
||
**Orderflow:** Trade sizes use `distribution: "uniform"` by default. Scenario schema supports `lognormal` / `pareto` for skewed (many small + occasional whale) flows; implement in `sampleTrade()` when needed.
|
||
|
||
---
|
||
|
||
## validate-capital-efficiency.cjs
|
||
|
||
Runs CI-style checks for the simulation-only capital efficiency overlay:
|
||
|
||
- JSON parse for policy, schemas, and scenarios
|
||
- Baseline scenario remains capital-overlay free
|
||
- Stress scenarios emit capital risk fields
|
||
- Deterministic repeat check
|
||
- Optimizer deployable candidates respect `maxDeployableLeverage`
|
||
|
||
**Run:**
|
||
|
||
```bash
|
||
node scripts/validate-capital-efficiency.cjs
|
||
```
|