diff --git a/.claude/skills/reclamm-pair-onboarding/SKILL.md b/.claude/skills/reclamm-pair-onboarding/SKILL.md index 8b75f84..9f2ae7d 100644 --- a/.claude/skills/reclamm-pair-onboarding/SKILL.md +++ b/.claude/skills/reclamm-pair-onboarding/SKILL.md @@ -1,6 +1,6 @@ --- name: reclamm-pair-onboarding -description: Onboard a new token pair for reCLAMM simulations — fetch price data, run the Optuna parameter sweep, and produce final-sim CSVs/plots with candidate pool params. Use when asked to simulate a reCLAMM pool for a pair, gather candidate price_ratio/margin/shift params, or add a pair to run_final_sims.py. +description: Onboard a new token pair for reCLAMM simulations — fetch price data, run the Optuna parameter sweep, produce final-sim CSVs/plots with candidate pool params, and optionally build a Balancer AutoRange investor pitch deck. Use when asked to simulate a reCLAMM pool for a pair, gather candidate price_ratio/margin/shift params, add a pair to run_final_sims.py, or make a pitch/proposal deck for a pair. --- # reCLAMM pair onboarding @@ -101,6 +101,51 @@ Selection: best trial per TVL by OOS `returns_over_hodl` (override with themed plots `_{train,test}[_weights]_{light,dark}.png`, and `_sim_results.pkl`. The printed summary gives train/test RoH and fees. +## Step 5 — investor deck (optional) + +A ready-made Balancer-v3 "AutoRange" pitch deck lives at +`.claude/skills/reclamm-pair-onboarding/assets/autorange-deck-example.html` +(single self-contained HTML file, opens in any browser, has an **Export PDF** +button). To make a deck for a new pair, **duplicate that file** and edit only +the four things below. **No extra scripts are needed** — all numbers come +straight from the `run_final_sims.py` output you already produced (printed +train/test RoH + fees, and the `run_Value_*` CSVs normalised to 100). **Do not +change any simulation logic** to build a deck. + +Everything is driven by two JS objects near the bottom of the file +(`const CONFIG = {…}` and `const DECK_DATA = {…}`). Only touch: + +1. **Token images** — `CONFIG.tokenLogoUrl` and `CONFIG.tokenBLogoUrl` + (CoinGecko `image.large` URLs, e.g. + `https://api.coingecko.com/api/v3/coins/?...` → `.image.large`). + +2. **Token names / branding** — `CONFIG.tokenA`, `CONFIG.tokenB`, + `CONFIG.brandColor`, `CONFIG.date` (these auto-fill the page title, cover + logos and date). Then find-and-replace the hardcoded pair text: the cover + `

`, cover placeholder letters (e.g. `IN`/`DO`), the + `X / Y AutoRange - Balancer v3` footer labels, the proposal hero + `

`, the range-chart CoinGecko fetch id + + `' / USD'` label, and the `pdf.save('…')` filename. + +3. **Results slide** (`#slide-results`) — the graphs + LP-return comparison. + Fill `DECK_DATA.series` (`hodl`, `balancer` = the passive full-range + reference, `pr` = the simulated AutoRange configs — each an array + normalised to 100 from the `run_Value_*` CSVs) and `DECK_DATA.headline` + (`pr.roh_pct`, `pr.fee_yield_pct`, `balancer.roh_pct`) from the sim + summary. Also update the hardcoded `Backtest · ` eyebrow, the + `$ pool` chart title, and the results-note sentence. + +4. **Proposal slide** (`#slide-proposal`) — the recommendation. Set + `DECK_DATA.recommend.price_ratio` (controls which results row is starred) + and the four `` values (Price Ratio, + Margin, Shift Speed, Swap Fee). + +**Leave everything else as-is.** In particular the parameter-sweep slide +(`#slide-sweep`, the 3-D heat-map) is a **standard illustration** — it does +**not** need per-project data; keep `DECK_DATA.heatmap` and the sweep slide +unchanged. The "What is AutoRange", methodology, and security slides are also +generic and stay put. + ## Gotchas - `--method` on `run_final_sims.py` is currently a no-op. diff --git a/.claude/skills/reclamm-pair-onboarding/assets/autorange-deck-example.html b/.claude/skills/reclamm-pair-onboarding/assets/autorange-deck-example.html new file mode 100644 index 0000000..d294ca8 --- /dev/null +++ b/.claude/skills/reclamm-pair-onboarding/assets/autorange-deck-example.html @@ -0,0 +1,1763 @@ + + + + + + INV/DOLA AutoRange + + + + + + + + + +
+ +
+ + + +
+
+
+
+ +
+ + Proposal +
+ +
+
+
IN
+ + × +
DO
+ +
+ +

INV/DOLA AutoRange

+

Concentrated Liquidity — Fully Automated

+
+ +
+ Prepared by Balancer +
+ May 2026 +
+
+ + + +
+
+
+ +
+ + Overview +
+ +
+
+

What is AutoRange?

+

Concentrated liquidity
that manages itself

+
+
+
+
+ Higher capital efficiency +

Same underlying math as Uniswap v3. Earns more fees per dollar of TVL, + making every unit of liquidity more productive.

+
+
+
+
+
+ Automated management, fully on-chain +

The range shifts automatically as market price moves, with no external keeper or + third-party manager. All rebalancing logic lives in the smart contract (fully + transparent and auditable).

+
+
+
+
+
+ Fungible positions, easy to incentivize +

All LPs share a single position, making them easy to incentivize. + Ideal for tokens that need deep, sustained liquidity.

+
+
+
+
+ +
+ +
+
Price Range
+
Margin Zone
+
Market Price
+
+
+
+ +
+ INV / DOLA AutoRange - Balancer v3 +
+ 03 / 07 +
+
+ + +
+
+
+ +
+ + Parameters +
+ +
+

How does it work?

+
+ +
+
+
How wide is the liquidity range?
+
The Price Ratio (PR) defines the width - the ratio between the highest and lowest price the pool actively covers.
A higher PR means a wider range: fewer shifts, but less concentrated liquidity.
+
+
+
When does the range start shifting?
+
The Margin is a buffer zone at each edge of the range - once price enters it, the pool begins re-centering.
A tighter margin means fewer shifts, lower arb cost per adjustment, but less tolerance for fast moves.
+
+
+
How fast does it shift?
+
The Shift Speed is proportional to how off-center the pool is - faster when lagging, gentler when nearly aligned.
No oracle or keeper needed. Re-centering is continuous and fully on-chain.
+
+
+ +
+ INV / DOLA AutoRange - Balancer v3 +
+ 04 / 07 +
+
+ + +
+
+
+ +
+ + Methodology +
+ +
+
+
+

How do we calibrate this pool?

+
+

+ The three parameters interact in non-obvious ways - wrong combinations can erode LP performance. +

+

+ The QuantAMM simulator replays every configuration against real market data, giving a calibrated, defensible recommendation. +

+

+ Arb flow, organic swap volume, and competitor pool liquidity are all modelled from on-chain data. +

+ + + QuantAMMProtocol/quantammsim + +
+ +
+
+
1
+
+ Arb Simulation +

Price history replayed. Every arbitrage trade is computed from real price data with live gas costs.

+
+
+
+
2
+
+ Organic Volume Model +

A calibrated Michaelis-Menten routing model separates genuine swap-fee income from arb costs. Organic flow is anchored to the token's real traded volume and scales with how much of the pair's liquidity this pool actually holds.

+
+
+
+
3
+
+ Full Sensitivity Sweep +

1,000s of scenarios tested - 165 parameter combos across 5 rolling 2-month windows. Ranked by a blended POL score (HODL-return + fee yield), so the optimum reflects every market regime, not a best-case window.

+
+
+
+
+ +
+ AutoRange / Balancer v3 +
+ 05 / 07 +
+
+ + +
+
+
+ +
+ + Sweep +
+ +
+
+
+

Automated grid search

+
+

+ Every combination of parameters is tested by the simulator across 5 rolling 2-month windows over INV's last 6 months. +

+

+ Each cell is the median return vs HODL across the windows — greener is less divergence loss. The surface tilts green toward the wider right edge: on INV's one-way drawdown, looser ranges track HODL more closely. +

+

+ The top candidates are then reviewed manually - looking at consistency across regimes, robustness to INV's sharp drawdowns, and alignment with Inverse's risk appetite - before a final recommendation is made. +

+

+ For protocol-owned liquidity we balanced HODL performance and fee / volume generation - keeping the basket intact while making INV/DOLA liquidity productive. +

+
+
+ 5 + rolling windows +
+
+ 165 + param combos +
+
+ 1,000s + simulations run +
+
+
+ +
+
+
+
+
← wider price range / looser margin →
+
+
+ +
+ INV / DOLA AutoRange - Balancer v3 +
+ 06 / 09 +
+
+ + +
+
+
+
+ + Results +
+ +
+

Backtest · Dec 2025 → Jun 2026

+

Every parameter set, replayed on real prices

+
+ +
+
+
Portfolio value vs HODL (indexed to 100), $500k pool
+
+
+
+
+ Strategyvs HODLFee yr +
+
+
+ Concentration sells INV as it falls (divergence loss) and pays arb on every re-center, so it trails HODL more than a passive pool. Organic swap fees (4–7%) soften but don't erase that on a one-way year. +
+
+
+ +
+ INV / DOLA AutoRange - Balancer v3 +
+ 07 / 09 +
+
+ + + +
+
+
+ +
+ +
+ + + Audits Reports + + Security +
+
+ +
+

Audits & monitoring

+

Multiple layers of security review

+
+ +
+ + +
+
Code Audits
+
+ + Cantina +
+
+ + Certora +
+
+ + +
+
AI Reviews
+
+ + AgentArena +
+
+ + Olympix +
+
+ + FailSafe +
+
+ + Octane +
+
+ + +
+
Live Monitoring
+
+
+ + Hypernative +
Live
+
+
+ 24/7 threat detection + Continuous on-chain monitoring with real-time alerting across all pool activity. +
+
+ Immediate-pause capability + Automated circuit breaker can pause the pool in seconds if anomalous behavior is detected. +
+
+ Emergency subDAO + Dedicated team with on-call rotations that can act without the full governance latency. +
+
+
+ +
+ +
+ AutoRange / Balancer v3 +
+ 02 / 07 +
+
+ +
+
+
+ +
+ + Proposal +
+ +
+
+

Recommended configuration

+

INV/DOLA AutoRange

+
+ +
+
+
Parameters Mutable
+
+ Price Ratio + + 4.0 +
+
+ Margin + + 50% +
+
+ Shift Speed + + 2%/day +
+
+ Swap Fee + + 0.5% +
+
+ +
+
Next Steps
+
+ 1 + Deploy the pool +
+
+ 2 + Share LP pool page +
+
+ 3 + Align on comms & GTM +
+
+
+
+ +
+ AutoRange / Balancer v3 +
+ 07 / 07 +
+
+ +
+ +
+ + + + + + diff --git a/.gitignore b/.gitignore index c353486..1428d3d 100644 --- a/.gitignore +++ b/.gitignore @@ -152,6 +152,8 @@ instance/ # Sphinx documentation docs/_build/ *.html +# but keep the committed AutoRange pitch-deck example (a tracked skill asset) +!.claude/skills/reclamm-pair-onboarding/assets/autorange-deck-example.html *.doctree # PyBuilder diff --git a/quantammsim/utils/data_processing/coingecko_data.py b/quantammsim/utils/data_processing/coingecko_data.py index 4c8ca7c..4760cae 100644 --- a/quantammsim/utils/data_processing/coingecko_data.py +++ b/quantammsim/utils/data_processing/coingecko_data.py @@ -83,7 +83,9 @@ "QI": "benqi", "QNT": "quant-network", "RDNT": "radiant-capital", - # TREE not on CoinGecko — handled as fallback below + "TREE": "treehouse", + "HYPE": "hyperliquid", # Hyperliquid L1 native (underlying of tHYPE) + "wHYPE": "hyperliquid", # Wrapped HYPE — same underlying price "XAI": "xai-blockchain", # Wrapped aTokens — use underlying "waEthLidoWETH": "ethereum", diff --git a/scripts/run_final_sims.py b/scripts/run_final_sims.py index 31162f3..b2433cb 100644 --- a/scripts/run_final_sims.py +++ b/scripts/run_final_sims.py @@ -92,6 +92,22 @@ }, "train": ("2025-07-15 00:00:00", "2025-10-05 00:00:00"), }, + "treehype": { + # TREE / HYPE. The live pool is TREE/tHYPE, but a rate provider + # internalises tHYPE's rate, so we simulate against the underlying + # HYPE (== wHYPE) price. Not in the MM artifact → median-pool fallback + # noise. On HyperEVM (gas ~cents). TREE (CoinGecko) price data starts + # 2025-07-29, hence the shortened windows. + "tokens": ["HYPE", "TREE"], # alphabetical — runner price/reserve order + "pool_id": "treehype", + "gas_cost": 0.002, # HyperEVM: ~0.2 Gwei * ~200k gas * ~$45 HYPE ≈ $0.002/swap + "fees": 0.008, + "tvls": { + "20k": 20_000, + }, + "train": ("2025-08-15 00:00:00", "2026-01-15 00:00:00"), + "test": ("2026-01-15 00:00:00", "2026-07-01 00:00:00"), + }, }