From 9bb286c85dad71bc373f4320e7b0bceb312400fe Mon Sep 17 00:00:00 2001 From: tiago-hansen Date: Fri, 10 Jul 2026 17:17:58 -0300 Subject: [PATCH 1/6] feat: add CoinGecko IDs for TREE and HYPE tokens --- quantammsim/utils/data_processing/coingecko_data.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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", From 0878ce1f2e1c8d0c9d70c84bee4cd6a2a13a4967 Mon Sep 17 00:00:00 2001 From: tiago-hansen Date: Fri, 10 Jul 2026 17:20:20 -0300 Subject: [PATCH 2/6] feat: add TREE/HYPE pool configuration --- scripts/run_final_sims.py | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/scripts/run_final_sims.py b/scripts/run_final_sims.py index 31162f3..70088d6 100644 --- a/scripts/run_final_sims.py +++ b/scripts/run_final_sims.py @@ -92,6 +92,41 @@ }, "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. Absent from the MM artifact → median-fallback + # noise, re-anchored to a target daily captured volume with a + # saturating competitor K (so fee income doesn't compound explosively). + # + # Volume sensitivity (the dominant driver; TVL is ~scale-invariant): + # the existing ETH weighted pool does ~$68k/30d ≈ $2k/day, and the two + # legs diverged ~26x over the window, so vs-HODL returns are structurally + # hard. Optimal price_ratio and OOS RoH vs assumed daily volume: + # $1k/day -> PR~28 test RoH -36% (fees ~$0.7k) [realistic today] + # $5k/day -> PR~9 test RoH ~-25% + # $20k/day -> PR~4 test RoH -6% (fees ~$30k) [near break-even] + # $50k/day -> PR~2.3 test RoH +53% (fees ~$84k) [needs ~25x today] + # Tighter-than-optimal bands overfit train and do worse OOS. Set + # daily_volume to the volume you actually expect this pool to capture. + # TREE (CoinGecko) starts 2025-07-29, hence the shortened windows. + "tokens": ["HYPE", "TREE"], # alphabetical — runner price/reserve order + "pool_id": "treehype", + "gas_cost": 0.1, # HyperEVM gas is ~cents, not the $1 Ethereum default + "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"), + # ~$2k/day captured volume on a $20k pool → turnover ~0.10 (a smaller + # pool sees the same $ volume, so fees are a bigger fraction of TVL). + "reanchor": { + "daily_volume": 2_000, + "ref_tvl": 20_000, + "competitor_k": 20_000, + }, + }, } From 7d7ab32a5dc5858ed7672444938d453fc006c534 Mon Sep 17 00:00:00 2001 From: tiago-hansen Date: Fri, 10 Jul 2026 17:22:21 -0300 Subject: [PATCH 3/6] refactor: simplify comments and configuration for TREE/HYPE pool --- scripts/run_final_sims.py | 25 +++---------------------- 1 file changed, 3 insertions(+), 22 deletions(-) diff --git a/scripts/run_final_sims.py b/scripts/run_final_sims.py index 70088d6..1586b08 100644 --- a/scripts/run_final_sims.py +++ b/scripts/run_final_sims.py @@ -95,21 +95,9 @@ "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. Absent from the MM artifact → median-fallback - # noise, re-anchored to a target daily captured volume with a - # saturating competitor K (so fee income doesn't compound explosively). - # - # Volume sensitivity (the dominant driver; TVL is ~scale-invariant): - # the existing ETH weighted pool does ~$68k/30d ≈ $2k/day, and the two - # legs diverged ~26x over the window, so vs-HODL returns are structurally - # hard. Optimal price_ratio and OOS RoH vs assumed daily volume: - # $1k/day -> PR~28 test RoH -36% (fees ~$0.7k) [realistic today] - # $5k/day -> PR~9 test RoH ~-25% - # $20k/day -> PR~4 test RoH -6% (fees ~$30k) [near break-even] - # $50k/day -> PR~2.3 test RoH +53% (fees ~$84k) [needs ~25x today] - # Tighter-than-optimal bands overfit train and do worse OOS. Set - # daily_volume to the volume you actually expect this pool to capture. - # TREE (CoinGecko) starts 2025-07-29, hence the shortened windows. + # 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.1, # HyperEVM gas is ~cents, not the $1 Ethereum default @@ -119,13 +107,6 @@ }, "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"), - # ~$2k/day captured volume on a $20k pool → turnover ~0.10 (a smaller - # pool sees the same $ volume, so fees are a bigger fraction of TVL). - "reanchor": { - "daily_volume": 2_000, - "ref_tvl": 20_000, - "competitor_k": 20_000, - }, }, } From 83d9d18dd2f92084e35b524399ea464cced81a80 Mon Sep 17 00:00:00 2001 From: tiago-hansen Date: Wed, 15 Jul 2026 15:14:28 -0300 Subject: [PATCH 4/6] docs(skill): add AutoRange deck example + adaptation instructions Commit one reference investor deck for the reclamm-pair-onboarding skill and document how to duplicate/adapt it: only token images, token names/branding, the results slide (DECK_DATA.series/headline from run_final_sims output), and the proposal slide (recommend + param values) change per pair. The sweep heat-map is a standard illustration and stays fixed; no extra scripts and no simulation-logic changes are needed to build a deck. Co-Authored-By: Claude Opus 4.8 --- .../skills/reclamm-pair-onboarding/SKILL.md | 47 +- .../assets/autorange-deck-example.html | 1763 +++++++++++++++++ 2 files changed, 1809 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/reclamm-pair-onboarding/assets/autorange-deck-example.html 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 +
+
+ +
+ +
+ + + + + + From a59d39c7de009232ccd26016d93f2b32e1ad8ec2 Mon Sep 17 00:00:00 2001 From: tiago-hansen Date: Wed, 15 Jul 2026 15:20:29 -0300 Subject: [PATCH 5/6] chore: unignore the tracked AutoRange deck example Blanket *.html gitignore made the committed skill deck show as ignored/grayed in editors. Add a negation so the tracked example displays normally; per-pair deck copies elsewhere stay ignored. Co-Authored-By: Claude Opus 4.8 --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) 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 From dfe5159dbef084150fe82af5f2408505e48cf2af Mon Sep 17 00:00:00 2001 From: tiago-hansen Date: Tue, 21 Jul 2026 15:39:13 -0300 Subject: [PATCH 6/6] fix: update gas cost for TREE/HYPE pool configuration --- scripts/run_final_sims.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/run_final_sims.py b/scripts/run_final_sims.py index 1586b08..b2433cb 100644 --- a/scripts/run_final_sims.py +++ b/scripts/run_final_sims.py @@ -100,7 +100,7 @@ # 2025-07-29, hence the shortened windows. "tokens": ["HYPE", "TREE"], # alphabetical — runner price/reserve order "pool_id": "treehype", - "gas_cost": 0.1, # HyperEVM gas is ~cents, not the $1 Ethereum default + "gas_cost": 0.002, # HyperEVM: ~0.2 Gwei * ~200k gas * ~$45 HYPE ≈ $0.002/swap "fees": 0.008, "tvls": { "20k": 20_000,