clmm-backtest

/clmm-backtest

Backtests a concentrated liquidity range against historical price data, computing net P&L vs HODL and break-even fee-APR requirements.

Steps

1. Prepare inputs - you need: token pair, tick range, optional historical fee data. Set environment:

   export OWNER_ADDRESS="YourWallet111..."  # optional, for real position ticks
   

2. Run the backtest script (backtestRange is pure compute; you supply a price/volume series in quote-per-base terms):

   npx tsx -e "
   import { backtestRange } from './skill/templates/il-backtest';
   
   // series: { t: unixSeconds, price: quotePerBase, volume: inQuote }[]
   const series = [
     { t: 1_717_200_000, price: 150, volume: 0 },
     { t: 1_717_286_400, price: 158, volume: 2_000_000 },
     { t: 1_717_372_800, price: 162, volume: 1_800_000 },
   ];
   
   const result = backtestRange({
     series,
     pLow: 140,            // range lower price (quote per base)
     pHigh: 170,           // range upper price
     depositValue: 10000,  // initial value in quote (token B) units
     feeBps: 30,           // pool fee tier in basis points (0.30%)
     // Optional: this position's share of active in-range liquidity (0..1, default 1)
     // activeShare: 0.05,
   });
   
   console.log(JSON.stringify(result, null, 2));
   "
   

3. Interpret the output (BacktestResult):

   {
     "lpValue": 10180.2,
     "hodlValue": 10240.0,
     "feesEarned": 11.4,
     "ilFraction": -0.0058,
     "netVsHodl": -59.8,
     "feeApr": 0.21,
     "inRangeFraction": 1.0,
     "breakEvenWidth": 0.184
   }
   

   • ilFraction: LP principal vs HODL as a fraction (negative = underperforms HODL)
   • feesEarned / feeApr: fees in quote units, annualized over the series duration
   • netVsHodl: lpValue - hodlValue in quote units (fees included)
   • breakEvenWidth: symmetric half-width w (fraction of p0) where net P&L vs HODL crosses zero on this series; NaN if it never breaks even in the search bounds