# AI Consilium Task: DEX CHECK/USDC capacity-aware LP tuner optimization ## 1. Ввідний текст для виконавця Claude Code / AI-консиліуму Ти працюєш над окремою DEX-гілкою проєкту `top_1`: `dex_platform`. Це дослідницьке середовище для тюну Concentrated Liquidity LP-стратегій на Aerodrome / Uniswap-v3-like пулах. Поточний pool: ```text base_CHECK_USDC_AERODROME_2PCT chain: Base pool: 0x5a7b4970b2610aee4776a6944d9f2171ee6060b0 token0: USDC token1: CHECK fee_rate conservative: 0.002515 period: 2026-02-01 → 2026-05-01 swap events: 133474 ``` Дані вже зібрані у fast NPZ: ```text DEX_DATA/fast_npz/base_CHECK_USDC_2PCT_2026_02_05_fee_replay_v2.npz DEX_DATA/fast_npz/base_CHECK_USDC_2PCT_2026_02_05_fee_replay_v2.meta.json ``` Важливо: `DEX_DATA/` не чіпати. Це вхідні дані. ## 2. Поточний стан Є v2 replay/backtester, який уже виправив головну помилку старого replay: ```python share = our_liquidity / (active_liquidity + our_liquidity) ``` Старий optimistic replay використовував: ```python share = our_liquidity / active_liquidity ``` Це завищувало fee share. Поточна проблема вже не у fee formula. Поточна проблема — **capacity**. Старий v2 tuner ганяв конфіги на фіксованому `initial_capital_usd = 1000`. Для цього CHECK/USDC pool-а це нереалістичний розмір: April-тести дають max liquidity share приблизно 70–82%, а avg share часто 5–7%. Такі результати не можна брати в live-рекомендацію. Локальний capacity-aware тест показав: ```text $25 — реалістичний стартовий розмір $50 — можливо, але треба перевіряти p95/p99 share $100 — верхня зона для обережного live/paper, не для всіх range $250+ — часто вже занадто багато $1000 — нереалістично для цього pool-а ``` Поточний v3 файл уже створено: ```text dex_platform/backtest/cl_fee_replay_fast_npz_v3.py ``` Поточні скрипти: ```text dex_platform/scripts/tune_check_2pct_capacity_v3.sh dex_platform/scripts/run_check_2pct_capacity_walkforward_v3.sh ``` ## 3. Поточні найкращі результати Квартальний тест `2026-02-01 → 2026-05-01`, capital `$25`, fee `0.002515`: ```text 1) periodic_60_5_336h return: +58.85% MDD: -32.40% profit: ~$14.71 p95 share: 1.68% p99 share: 6.40% max share: 11.27% score: 43.92 2) periodic_70_5_336h return: +47.85% MDD: -26.92% profit: ~$11.96 p95 share: 1.39% p99 share: 5.36% max share: 9.52% score: 43.90 3) periodic_80_5_336h return: +39.16% MDD: -22.42% profit: ~$9.79 p95 share: 1.15% p99 share: 4.49% max share: 8.03% score: 39.04 ``` Live/paper preference from current evidence: ```text Primary candidate: periodic_70_5_336h capital: $25 lower_pct: 70 upper_pct: 5 rebalance: periodic every 336h Conservative candidate: periodic_80_5_336h capital: $25 lower_pct: 80 upper_pct: 5 rebalance: periodic every 336h Aggressive candidate: periodic_60_5_336h capital: $25 lower_pct: 60 upper_pct: 5 rebalance: periodic every 336h ``` Do not blindly promote `periodic_60_5_336h`: it has the highest return, but MDD is above target. `periodic_70_5_336h` is the better practical candidate because its score is almost identical with lower MDD. ## 4. Головна ціль цієї задачі Оптимізувати DEX capacity tuner так, щоб він давав **live-ready recommendation**, а не красивий backtest на нереалістичному capital. Потрібно знайти: ```text strategy name lower_pct upper_pct rebalance mode rebalance_hours recommended capital expected monthly/quarterly return on deployed capital expected return on total capital MDD avg share p95 share p99 share max share time in range fees earned / reinvested / uncollected ``` Головний критерій: не max return, а **capacity-aware score + walk-forward sanity**. ## 5. Стратегія пошуку ### Stage 0. Sanity check Переконатися, що поточні файли запускаються: ```bash cd /var/www/vps2.happyuser.info/top/top_1 source /var/www/vps2.happyuser.info/top/backtest_SK/.venv38/bin/activate python3 dex_platform/backtest/cl_fee_replay_fast_npz_v3.py --help ``` Поточне середовище: NumPy 1.x. Не апгрейдити NumPy. Не витрачати час на NumPy 2 support. ### Stage 1. April capacity grid ```bash bash dex_platform/scripts/tune_check_2pct_capacity_v3.sh ``` Очікувані outputs: ```text DEX_REPORTS/check_2pct_capacity_tune_april_v3/summary.csv DEX_REPORTS/check_2pct_capacity_tune_april_v3/summary.json DEX_REPORTS/check_2pct_capacity_tune_april_v3/best_by_score.csv DEX_REPORTS/check_2pct_capacity_tune_april_v3/best_by_return.csv DEX_REPORTS/check_2pct_capacity_tune_april_v3/best_capacity_by_strategy.csv ``` ### Stage 2. Walk-forward / monthly sanity ```bash bash dex_platform/scripts/run_check_2pct_capacity_walkforward_v3.sh ``` Walk-forward windows: ```text Tune Feb → evaluate Mar Tune Mar → evaluate Apr Tune Feb+Mar → evaluate Apr ``` Month windows: ```text Feb: 2026-02-01 → 2026-03-01 Mar: 2026-03-01 → 2026-04-01 Apr: 2026-04-01 → 2026-05-01 Quarter: 2026-02-01 → 2026-05-01 ``` ### Stage 3. Focused tune around current champions Do not brute-force randomly. Continue from current candidate family: ```text periodic_60_5_336h periodic_70_5_336h periodic_80_5_336h periodic_95_1_168h wide_70_5 wide_80_5 wide_90_5 wide_95_2 ``` Focused search suggestions: ```text lower_pct: 55,60,65,70,75,80,85,90,95 upper_pct: 0.5,1,2,3,5,8,10,12 rebalance: none, periodic 168h, periodic 240h, periodic 336h, periodic 504h, oor 24h capital: 10,15,20,25,35,50,75,100,125,150 ``` Important: capital must be selected by avg/p95/p99 constraints, not by return. ### Stage 4. Capacity curve For every finalist, generate capital sensitivity: ```text capital → return_pct capital → profit_usd capital → avg_share capital → p95_share capital → p99_share capital → max_share capital → score ``` Reject any candidate where the only good result is a tiny capital artifact and does not generalize across neighboring capital values. ### Stage 5. Critic pass Critic must answer: 1. Is the result only April overfit? 2. Is the capital actually deployable? 3. Is the strategy earning from fees or only from holding-side mark-to-market luck? 4. Does `fees_uncollected_end` dominate result suspiciously? 5. Would live execution/rebalance costs destroy the edge? 6. Is the pool too small to matter without basket scaling? ## 6. Required scoring discipline Use capacity-aware score: ```text score = return_pct - w_mdd * max(0, abs(mdd_pct) - target_mdd_pct) - w_avg_share * max(0, avg_share - max_avg_share) - w_p95_share * max(0, p95_share - max_p95_share) - w_p99_share * max(0, p99_share - max_p99_share) - w_max_share * max(0, max_share - max_max_share) - w_rebalance * rebalances ``` Defaults: ```text target_mdd_pct = 25 max_avg_share = 3 max_p95_share = 5 max_p99_share = 10 max_max_share = 25 w_mdd = 2 w_avg_share = 5 w_p95_share = 10 w_p99_share = 3 w_max_share = 0.5 w_rebalance = 0.02 ``` Do not use hard cap only on absolute max share. Max share can be a one-swap liquidity spike. Main caps are avg, p95, p99. ## 7. What counts as success Good result: ```text quarter return on deployed capital > 30% quarter MDD <= 25–28% p95 share <= 5% p99 share <= 10% max share preferably <= 15–20%, but diagnostic only positive or tolerable Feb/Mar behavior not solely April hindsight capital recommendation: $25–100, with explicit caveat if pool cannot absorb more ``` Live-ready result must output: ```text strategy name lower_pct upper_pct rebalance mode/hours recommended capital expected April return expected quarter return monthly breakdown MDD avg/p95/p99/max share time in range fee accounting reason for promotion reason for rejection of alternatives ``` ## 8. What counts as failure Failure: ```text selecting $1000 because return is high ignoring p95/p99 share promoting candidate based only on April not reporting return_on_total_capital changing fee formula silently editing DEX_DATA touching old CEX files producing only plots without CSV/JSON ``` ## 9. Roles in AI-consilium ### Orchestrator Controls search waves. Tasks: ```text choose seed family choose data windows set search budget launch workers collect summary.csv / best files select finalists send finalists to critic promote one candidate only after quarter + monthly sanity ``` Must not: ```text change score mid-run without recording it promote highest-return candidate if capacity fails ignore small-pool limitation ``` ### Mutator / Research worker Creates candidate grids. Tasks: ```text mutate lower_pct / upper_pct / rebalance_hours / capital grid run fast NPZ v3 generate candidate CSVs explain why candidate should continue ``` ### Tester Runs validation windows. Tasks: ```text April-only quick test Feb, Mar, Apr monthly tests quarter test top-3 side-by-side comparison capacity curve for finalist ``` ### Critic Rejects overfit. Tasks: ```text check April hindsight check capacity realism check MDD vs return tradeoff check fee accounting realism check whether pool is too small for business value ``` ## 10. Files in this DEX overlay ```text dex_platform/backtest/cl_fee_replay_fast_npz_v3.py dex_platform/scripts/tune_check_2pct_capacity_v3.sh dex_platform/scripts/run_check_2pct_capacity_walkforward_v3.sh docs/NEW_CHAT_TASK_DEX_CAPACITY_TUNER_V3.md docs/AI_CONSILIUM_DEX_CAPACITY_TUNER_TASK.md ``` ## 11. Do not edit ```text DEX_DATA/ DEX_REPORTS/ except writing new report dirs .venv* .env old CEX backtest files obw_platform CEX strategy/backtester files UI/ ``` ## 12. Final deliverables from AI-consilium Return: ```text 1. top-10 configs by score 2. top-10 configs by return 3. top-3 quarter-tested finalists 4. capacity curve for the champion 5. monthly breakdown for the champion 6. live recommendation: strategy + capital + risk caveats 7. zip bundle if code changed ``` Final recommendation must be brutally clear: ```text Use this for live/paper: Do not use these: Pool capacity limit: <$X realistic deployed capital> Expected profit on $1000 total capital: <$Y, not just deployed %> ```