# Optimized Fast NPZ CL Fee Replay Tuner v3

This environment uses `dex_platform/backtest/cl_fee_replay_fast_npz_v3.py` as the capacity-aware concentrated-liquidity tuner.

## What Was Added

- Optional compiled C replay core: `dex_platform/backtest/cl_replay_fast_core.c`
- CLI flags:
  - `--fast-core` / `--no-fast-core`
  - `--jobs N`
- Fast CSV/JSON output path for regular tuning runs.
- Python fallback path if `gcc` or C loading is unavailable.

The fee share formula remains:

```text
our_liquidity / (active_liquidity + our_liquidity)
```

## Basic Sanity Check

```bash
python3 dex_platform/backtest/cl_fee_replay_fast_npz_v3.py --help
```

## Recommended CHECK Capacity Run

```bash
python3 dex_platform/backtest/cl_fee_replay_fast_npz_v3.py \
  --jobs 8 \
  --fast-core \
  --npz DEX_DATA/fast_npz/base_CHECK_USDC_2PCT_2026_02_05_scaled_may26.npz \
  --out-dir DEX_REPORTS/check_scaled_may26_capacity_optimized \
  --fee-rates metadata_0_2515:0.002515 \
  --walkforward \
  --capital-mode grid \
  --capital-grid 10,15,20,25,35,50,75,100 \
  --grid-lower 40,50,60,65,70,75,80,85,90 \
  --grid-upper 0.001,0.01,0.1,0.2,0.5,1,2,5 \
  --rebalance-grid periodic:168,periodic:312,periodic:336,periodic:504,periodic:672 \
  --target-mdd-pct 25 \
  --max-avg-liquidity-share-pct 3 \
  --max-p95-liquidity-share-pct 5 \
  --max-p99-liquidity-share-pct 10 \
  --max-liquidity-share-pct 25
```

## Recommended BIO/USDC Validation Run

```bash
python3 dex_platform/backtest/cl_fee_replay_fast_npz_v3.py \
  --jobs 8 \
  --fast-core \
  --npz DEX_DATA/fast_npz/bio_usdc_apr17_may2_full.npz \
  --out-dir DEX_REPORTS/bio_usdc_optimized_validation \
  --fee-rates aerodrome_0_3pct:0.003 \
  --time-from 2026-04-17T00:00:00Z \
  --time-to 2026-05-03T00:00:00Z \
  --capital-mode grid \
  --capital-grid 100,300,600,1000 \
  --grid-lower 30,40,50,60 \
  --grid-upper 10,20,30,40 \
  --rebalance-grid none:0,periodic:168,periodic:336,periodic:504 \
  --target-mdd-pct 20 \
  --max-p99-liquidity-share-pct 10
```

## Notes

- The compiled `.so` is generated in `/tmp` and is not committed.
- Use `--no-fast-core` for exact Python fallback/debugging.
- Do not treat high-return results as live-ready unless they pass MDD, p95/p99 share, and walk-forward checks.