@sundaeswap/math 0.5.0 → 0.6.0

package/dist/esm/PoolMath/ConcentratedLiquidityPool.js

@@ -1,181 +1,649 @@
 import { AssetAmount } from "@sundaeswap/asset";
 import { Fraction } from "@sundaeswap/fraction";
-import * as ConstantProductPool from "./ConstantProductPool.js";
 
 /**
- * Holds the calculated outcome of a concentrated-liquidity swap. Mirrors
- * {@link ConstantProductPool.TSwapOutcome} so it flows through the same generic
- * swap-outcome consumers.
+ * Holds the calculated outcome of a concentrated-liquidity swap. It has the
+ * same shape as `ConstantProductPool.TSwapOutcome`, so the generic
+ * swap-outcome consumers accept it.
  */
 
-/** A sqrt-price bound from the CL config, as an exact rational `[num, den]`. */
-
 /**
- * Concentrated liquidity is Sundae v4's single-range invariant. Unlike Uniswap
- * v3 there are no per-position ranges or ticks: the whole pool shares ONE
- * immutable price range `[sqrtPriceA, sqrtPriceB]` (a < b) set at creation, and
- * LP is a single fungible token. Swaps run on *virtual* reserves that fold the
- * pool's liquidity `L` (its total LP supply) into each side:
+ * Concentrated liquidity: Sundae v4's ladder invariant.
+ *
+ * A pool is a ladder of bands in ascending sqrt-price order. Each band is a
+ * concentrated-liquidity arc (`curve` 0) or a constant-sum bin (`curve` 1)
+ * with its own share of the pool's liquidity (`weight / weightTotal`) and
+ * its own two fees. LP is one fungible token for the whole ladder; a
+ * deposit or withdrawal scales every band.
  *
- *   VA = a·spbNum + L·spbDen
- *   VB = b·spaDen + L·spaNum
+ * The chain never stores the price. It stores reserves, and the state is a
+ * WITNESS `(X, k)`: the ladder counter `X` (the pool's `total_lp`, spec V12)
+ * and the active band `k`, which the reserves must prove. Everything here
+ * mirrors `lib/modules/cl_check.ak` and the scooper's ladder
+ * math, rounding included; where they disagree the chain wins
+ * and the transaction fails. The rounding is not negotiable:
  *
- * where `a`/`b` are the raw assetA/assetB reserves. This is a direct port of the
- * scooper's `cl_swap_result` (scooper-v2/src/sundaev4/swap_math.rs) and the
- * on-chain `cl_check_swap` (sundae-v4/lib/modules/cl_check.ak) — those are the
- * source of truth; keep this in lockstep with them.
+ *   - `L_k` floors; saturation ceils, in ONE division;
+ *   - the band fee ceils, per step, on the step's real input;
+ *   - the prefix sums come from the LADDER INDEX (cumulative coefficients
+ *     in fixed point at 2^64, spec §2.3), multiplied by the counter and
+ *     ceiled ONCE. A per-band sum of ceilings is a different number and the
+ *     chain rejects it.
+ */
+
+/** An exact rational `num / den`. */
+
+/** One band of the ladder. */
+
+/** A ladder: bands, the top edge, and the sum of the weights. */
+
+/** The witness the chain checks: the ladder counter and the active band. */
+
+/** 2^64, the fixed-point scale of the ladder index. */
+export const FIXED_ONE = 1n << 64n;
+
+/**
+ * The least counter per unit of weight a ladder may be created with.
+ * Mirrors `cl_check.min_counter_per_weight` (sundae-v4 #229, SV4-007):
+ * Create requires `total_lp >= MIN_COUNTER_PER_WEIGHT * weightTotal`.
+ */
+export const MIN_COUNTER_PER_WEIGHT = 1000n;
+
+/** The least counter (initial `total_lp`) the chain accepts at Create for `ladder`. */
+export const minCreateCounter = ladder => MIN_COUNTER_PER_WEIGHT * ladder.weightTotal;
+const ceilDiv = (n, d) => (n + d - 1n) / d;
+
+/** Band i's upper sqrt-price edge. */
+export const upperEdge = (l, i) => i + 1 < l.bands.length ? l.bands[i + 1].start : l.closing;
+
+/** `D_i = hi.num·lo.den − lo.num·hi.den`: positive exactly when the edges increase. */
+export const delta = (lo, hi) => hi.num * lo.den - lo.num * hi.den;
+
+/** `a_sat_i = ceil(w_i·X·D_i / (W·lo.num·hi.num))`: the A a band above the price holds. */
+export const aSat = (l, x, i) => {
+  const lo = l.bands[i].start;
+  const hi = upperEdge(l, i);
+  return ceilDiv(l.bands[i].weight * x * delta(lo, hi), l.weightTotal * lo.num * hi.num);
+};
+
+/** `b_sat_i = ceil(w_i·X·D_i / (W·lo.den·hi.den))`: the B a band below the price holds. */
+export const bSat = (l, x, i) => {
+  const lo = l.bands[i].start;
+  const hi = upperEdge(l, i);
+  return ceilDiv(l.bands[i].weight * x * delta(lo, hi), l.weightTotal * lo.den * hi.den);
+};
+
+/** `L_k = floor(w_k·X / W)`. */
+export const liquidityOf = (l, x, k) => l.bands[k].weight * x / l.weightTotal;
+
+/** Band i's A-side saturation coefficient: the part of `a_sat_i` independent of X, rounded up. */
+export const coeffA = (l, i) => {
+  const lo = l.bands[i].start;
+  const hi = upperEdge(l, i);
+  return ceilDiv(l.bands[i].weight * delta(lo, hi) * FIXED_ONE, l.weightTotal * lo.num * hi.num);
+};
+
+/** The same on the B side. */
+export const coeffB = (l, i) => {
+  const lo = l.bands[i].start;
+  const hi = upperEdge(l, i);
+  return ceilDiv(l.bands[i].weight * delta(lo, hi) * FIXED_ONE, l.weightTotal * lo.den * hi.den);
+};
+
+/** One index entry: the cumulative coefficients above and below band k. */
+
+/**
+ * The ladder index `Create` pins and every spend reads: entry k is the pair
+ * of cumulative coefficients for the bands strictly above and strictly
+ * below band k. `cl_check.build_index`, to the digit.
  */
+export const buildIndex = l => {
+  const n = l.bands.length;
+  const a = Array.from({
+    length: n
+  }, (_, i) => coeffA(l, i));
+  const b = Array.from({
+    length: n
+  }, (_, i) => coeffB(l, i));
+  const out = [];
+  for (let k = 0; k < n; k++) {
+    let ca = 0n;
+    let cb = 0n;
+    for (let i = 0; i < n; i++) {
+      if (i > k) ca += a[i];
+      if (i < k) cb += b[i];
+    }
+    out.push({
+      ca,
+      cb
+    });
+  }
+  return out;
+};
+
+/**
+ * A ladder with its index built once. Every probe of the witness search
+ * reads the index for every band, and rebuilding it per probe is most of
+ * the cost of a quote.
+ */
+
+export const indexLadder = l => "index" in l && Array.isArray(l.index) ? l : {
+  ...l,
+  index: buildIndex(l)
+};
+
+/** `C_A`, `C_B` at (X, k) from the index: one ceiling after the multiply by X. */
+export const prefixes = (l, x, k) => {
+  const e = l.index[k];
+  return {
+    ca: ceilDiv(e.ca * x, FIXED_ONE),
+    cb: ceilDiv(e.cb * x, FIXED_ONE)
+  };
+};
+
+/** `cl_check.f_at_raw`: the CL arc, cross-multiplied. */
+const fAt = (a, b, L, lo, hi) => (a * hi.num + L * hi.den) * (b * lo.den + L * lo.num) - L * L * hi.num * lo.den;
+
+/** G at a witness, on whichever curve the active band carries. */
+const gAt = (l, A, B, x, k) => {
+  const {
+    ca,
+    cb
+  } = prefixes(l, x, k);
+  const lo = l.bands[k].start;
+  const hi = upperEdge(l, k);
+  const ra = A - ca;
+  const rb = B - cb;
+  const L = liquidityOf(l, x, k);
+  return l.bands[k].curve === 0 ? fAt(ra, rb, L, lo, hi) : ra * (lo.num * hi.num) + rb * (lo.den * hi.den) - L * delta(lo, hi);
+};
 
-const asFeeParts = fee => {
-  const f = Fraction.asFraction(fee);
-  if (f.lt(Fraction.ZERO) || f.gte(Fraction.ONE)) throw new Error("fee must be in [0, 1)");
-  return [BigInt(f.numerator), BigInt(f.denominator)];
+/** The band proof, P1 through P7. The chain runs exactly this. */
+export const bandProof = (l, A, B, x, k) => {
+  if (x < l.weightTotal) return false; // P1
+  const {
+    ca,
+    cb
+  } = prefixes(l, x, k);
+  const ra = A - ca;
+  const rb = B - cb;
+  if (ra < 0n || rb < 0n) return false; // P2, P3
+  if (ra > aSat(l, x, k) || rb > bSat(l, x, k)) return false; // P4, P5
+  if (gAt(l, A, B, x, k) < 0n) return false; // P6
+  return gAt(l, A, B, x + 1n, k) < 0n; // P7
 };
+const SCAN = 400n;
+const CAP = 1n << 80n;
 
 /**
- * The raw forward swap: given a pre-fee input `dx`, return the output amount.
- * A→B and B→A use different virtual-reserve scalings (see `cl_check_swap`).
- * All quantities are non-negative so integer division floors, matching chain.
+ * The witness in band k, seeded at `hint` when given: the counter only
+ * grows along a swap, so the doubling search starts from the previous
+ * witness. `lo` is the largest x with non-negative residuals and G ≥ 0,
+ * and a witness is such an x whose successor fails G, so the scan walks
+ * DOWN from `lo` first. Mirrors the scooper's `find_witness_in_band_from`.
  */
-const rawSwapOutput = (dx, aReserve, bReserve, totalLp, spaNum, spaDen, spbNum, spbDen, feeNum, feeDen, isAInput) => {
-  const fee = dx * feeNum / feeDen;
-  const dxEff = dx - fee;
-  const va0 = aReserve * spbNum + totalLp * spbDen;
-  const vb0 = bReserve * spaDen + totalLp * spaNum;
-  if (isAInput) {
-    const dvaEff = dxEff * spbNum;
-    const denom = (va0 + dvaEff) * spaDen;
-    if (denom <= 0n) return 0n;
-    return vb0 * dvaEff / denom;
+export const findWitnessInBand = (l, A, B, k, hint) => {
+  const ok = x => {
+    const {
+      ca,
+      cb
+    } = prefixes(l, x, k);
+    return A - ca >= 0n && B - cb >= 0n && gAt(l, A, B, x, k) >= 0n;
+  };
+  const search = start => {
+    let lo = start;
+    let span = 1n;
+    let hi = lo + span;
+    while (ok(hi) && hi < CAP) {
+      lo = hi;
+      span *= 2n;
+      hi = lo + span;
+    }
+    while (lo + 1n < hi) {
+      const m = (lo + hi) / 2n;
+      if (ok(m)) lo = m;else hi = m;
+    }
+    const from = lo > SCAN ? lo - SCAN : 1n;
+    for (let x = lo; x >= from; x--) {
+      if (bandProof(l, A, B, x, k)) return {
+        x,
+        k
+      };
+    }
+    for (let x = lo + 1n; x <= lo + SCAN; x++) {
+      if (bandProof(l, A, B, x, k)) return {
+        x,
+        k
+      };
+    }
+    return null;
+  };
+  if (hint !== undefined && hint > 0n && ok(hint)) {
+    const w = search(hint);
+    if (w) return w;
   }
-  const dvbEff = dxEff * spaNum;
-  const denom = (vb0 + dvbEff) * spbNum;
-  if (denom <= 0n) return 0n;
-  return va0 * dvbEff / denom;
+  if (!ok(1n)) return null;
+  return search(1n);
 };
 
 /**
- * Calculate the swap outcome for a concentrated-liquidity pool.
+ * The witness `(X, k)` for a pool's reserves. A hint (the indexed
+ * `bandCounter` / `activeBand`) is checked first and seeds the search in
+ * its band; a stale hint falls back to every band. Null when the reserves
+ * sit on no point of the ladder — the chain would reject them too.
+ */
+export const findWitness = (ladder, A, B, hint) => {
+  const l = indexLadder(ladder);
+  if (hint && hint.k >= 0 && hint.k < l.bands.length) {
+    if (bandProof(l, A, B, hint.x, hint.k)) return hint;
+    const w = findWitnessInBand(l, A, B, hint.k, hint.x);
+    if (w) return w;
+  }
+  for (let k = 0; k < l.bands.length; k++) {
+    const w = findWitnessInBand(l, A, B, k);
+    if (w) return w;
+  }
+  return null;
+};
+
+/** The active band's view at a witness: its residual reserves and liquidity. */
+
+export const bandView = (l, A, B, w) => {
+  const {
+    ca,
+    cb
+  } = prefixes(l, w.x, w.k);
+  const band = l.bands[w.k];
+  return {
+    ra: A - ca,
+    rb: B - cb,
+    l: liquidityOf(l, w.x, w.k),
+    lo: band.start,
+    hi: upperEdge(l, w.k),
+    curve: band.curve,
+    feeBuy: band.feeBuy,
+    feeSell: band.feeSell
+  };
+};
+
+/** The band's fee for a direction: `feeSell` when A is sold, `feeBuy` when A is bought. */
+export const feeFor = (v, isAInput) => isAInput ? v.feeSell : v.feeBuy;
+
+/**
+ * The band fee on a step's real input `dx`: `ceil(dx * num / den)`.
+ * Mirrors `cl_check.band_fee` (sundae-v4 #228, SV4-006). The chain charges
+ * it per transcript step and rounds it UP, so a step below `den / num`
+ * units still pays one unit. A zero rate charges nothing.
+ */
+export const bandFee = (dx, fee) => (dx * fee.num + fee.den - 1n) / fee.den;
+
+/** The output one band pays for `dx` within itself. Mirrors the scooper's `band_output`. */
+export const bandOutput = (v, isAInput, dx) => {
+  const fee = feeFor(v, isAInput);
+  if (fee.den <= 0n) return 0n;
+  const dxEff = dx - bandFee(dx, fee);
+  if (dxEff <= 0n) return 0n;
+  if (v.curve === 0) {
+    const va0 = v.ra * v.hi.num + v.l * v.hi.den;
+    const vb0 = v.rb * v.lo.den + v.l * v.lo.num;
+    if (isAInput) {
+      const dva = dxEff * v.hi.num;
+      const den = (va0 + dva) * v.lo.den;
+      return den === 0n ? 0n : vb0 * dva / den;
+    }
+    const dvb = dxEff * v.lo.den;
+    const den = (vb0 + dvb) * v.hi.num;
+    return den === 0n ? 0n : va0 * dvb / den;
+  }
+  const pn = v.lo.num * v.hi.num;
+  const pd = v.lo.den * v.hi.den;
+  return isAInput ? dxEff * pn / pd : dxEff * pd / pn;
+};
+
+/** What the band can pay out in a direction: its residual of the output asset. */
+export const bandCapacity = (v, isAInput) => isAInput ? v.rb : v.ra;
+
+/** The largest input whose output stays within the band. */
+export const maxDxInBand = (v, isAInput) => {
+  const cap = bandCapacity(v, isAInput);
+  if (cap <= 0n) return 0n;
+  const fits = dx => bandOutput(v, isAInput, dx) <= cap;
+  let hi = 1n;
+  for (let guard = 0; fits(hi); guard++) {
+    hi *= 2n;
+    if (guard > 200) return hi;
+  }
+  let lo = 0n;
+  while (lo + 1n < hi) {
+    const m = (lo + hi) / 2n;
+    if (fits(m)) lo = m;else hi = m;
+  }
+  return lo;
+};
+
+/** The next band a fill enters: selling A walks down the ladder, buying A walks up. */
+export const nextBand = (k, isAInput, n) => isAInput ? k === 0 ? null : k - 1 : k + 1 >= n ? null : k + 1;
+
+/** One band of a fill: what it paid, and the state it left. */
+
+/**
+ * Price `dx` across as many bands as it takes, as the scooper's
+ * `swap_steps` does: fill the active band, cross to the next, repeat.
+ * Returns the steps, or null when the ladder cannot absorb `dx` (the
+ * direction is exhausted, or the remainder pays nothing).
+ */
+export const swapSteps = (ladder, A, B, isAInput, dx, hint) => {
+  const l = indexLadder(ladder);
+  const n = l.bands.length;
+  let ca = A;
+  let cb = B;
+  let remaining = dx;
+  const steps = [];
+  let known = findWitness(l, A, B, hint);
+  if (!known) return null;
+  let prefer = null;
+  let hintX;
+  for (let guard = 0; remaining > 0n; guard++) {
+    if (guard > 2 * n + 2) return null;
+    let before = known;
+    known = null;
+    if (!before) {
+      if (prefer !== null) before = findWitnessInBand(l, ca, cb, prefer, hintX);
+      if (!before) before = findWitness(l, ca, cb);
+      if (!before) return null;
+    }
+    const view = bandView(l, ca, cb, before);
+    const capDx = maxDxInBand(view, isAInput);
+    const stepDx = capDx < remaining ? capDx : remaining;
+    const dy = stepDx > 0n ? bandOutput(view, isAInput, stepDx) : 0n;
+    if (dy <= 0n) {
+      const kNext = nextBand(before.k, isAInput, n);
+      if (kNext === null || prefer === kNext) return null;
+      prefer = kNext;
+      continue;
+    }
+    const na = isAInput ? ca + stepDx : ca - dy;
+    const nb = isAInput ? cb - dy : cb + stepDx;
+    const crossing = stepDx < remaining;
+    let after = null;
+    if (crossing) {
+      const kNext = nextBand(before.k, isAInput, n);
+      if (kNext !== null) after = findWitnessInBand(l, na, nb, kNext, before.x);
+    } else {
+      after = findWitnessInBand(l, na, nb, before.k, before.x);
+    }
+    if (!after) after = findWitness(l, na, nb);
+    if (!after || after.x < before.x) return null;
+    steps.push({
+      band: before.k,
+      input: stepDx,
+      output: dy,
+      after
+    });
+    remaining -= stepDx;
+    ca = na;
+    cb = nb;
+    prefer = after.k;
+    hintX = after.x;
+    known = after;
+  }
+  return steps;
+};
+
+/**
+ * The swap output of a concentrated-liquidity pool for `input` of one asset, crossing
+ * bands as needed. `aReserve`/`bReserve` are the pool's reserves in
+ * canonical order; `hint` is the indexed `bandCounter` / `activeBand`,
+ * which seeds the witness search and may be stale.
  *
- * @param inputMetadata Metadata for the supplied (input) asset — used for the fee AssetAmount.
- * @param input The pre-fee amount of the input asset being swapped.
- * @param aReserve The pool's raw reserve of asset A.
- * @param bReserve The pool's raw reserve of asset B.
- * @param totalLp The pool's total LP supply (the virtual liquidity `L`).
- * @param sqrtPriceA The lower sqrt-price bound `[num, den]` from the CL config.
- * @param sqrtPriceB The upper sqrt-price bound `[num, den]` from the CL config.
- * @param fee The liquidity-provider fee (plus protocol fee) as a fraction.
- * @param isAInput True when asset A is the supplied asset (A→B swap).
- * @returns The swap details in the shared {@link TSwapOutcome} shape.
+ * The `lpFee` is the fee the bands kept of the input, summed across the
+ * steps. `priceImpact` is against the active band's opening marginal
+ * price. Throws when the ladder cannot absorb the input.
  */
-export const getSwapOutput = (inputMetadata, input, aReserve, bReserve, totalLp, sqrtPriceA, sqrtPriceB, fee, isAInput) => {
-  if (input <= 0n || aReserve <= 0n || bReserve <= 0n || totalLp <= 0n) throw new Error("Input, reserves and liquidity must be positive");
-  const [spaNum, spaDen] = sqrtPriceA;
-  const [spbNum, spbDen] = sqrtPriceB;
-  if (spaNum <= 0n || spaDen <= 0n || spbNum <= 0n || spbDen <= 0n) throw new Error("sqrt prices must be positive");
-  const [feeNum, feeDen] = asFeeParts(fee);
+export const getSwapOutput = (inputMetadata, input, aReserve, bReserve, ladder, isAInput, hint) => {
+  if (input <= 0n || aReserve < 0n || bReserve < 0n) throw new Error("Input must be positive and reserves non-negative");
+  if (ladder.bands.length === 0 || ladder.weightTotal <= 0n) throw new Error("The ladder has no bands");
+  const l = indexLadder(ladder);
+  const steps = swapSteps(l, aReserve, bReserve, isAInput, input, hint);
+  if (!steps || steps.length === 0) throw new Error("The ladder cannot absorb this input in this direction");
+  let output = 0n;
+  let lpFee = 0n;
+  for (const s of steps) {
+    output += s.output;
+    const band = l.bands[s.band];
+    const fee = isAInput ? band.feeSell : band.feeBuy;
+    lpFee += bandFee(s.input, fee);
+  }
   const inputReserve = isAInput ? aReserve : bReserve;
   const outputReserve = isAInput ? bReserve : aReserve;
-  let output = rawSwapOutput(input, aReserve, bReserve, totalLp, spaNum, spaDen, spbNum, spbDen, feeNum, feeDen, isAInput);
-  // Can't take more than the pool actually holds (virtual reserves can
-  // otherwise let the formula exceed the real reserve near the boundary).
   if (output > outputReserve) output = outputReserve;
-  const inputLpFee = input * feeNum / feeDen;
-  const nextInputReserve = inputReserve + input;
-  const nextOutputReserve = outputReserve - output;
-
-  // Price impact vs the marginal (dx→0) rate. Marginal output-per-effective-
-  // input is vb0·spbNum/(va0·spaDen) for A→B (symmetric for B→A), so the ideal
-  // input-per-output is its reciprocal. Display-only.
-  const va0 = aReserve * spbNum + totalLp * spbDen;
-  const vb0 = bReserve * spaDen + totalLp * spaNum;
+  // Price impact against the opening marginal of the first band traded.
+  const w0 = findWitness(l, aReserve, bReserve, hint);
+  const v0 = bandView(l, aReserve, bReserve, w0);
   let priceImpact = Fraction.ZERO;
   if (output > 0n) {
-    const idealPrice = isAInput ? new Fraction(va0 * spaDen, vb0 * spbNum) : new Fraction(vb0 * spbNum, va0 * spaDen);
-    const actualPrice = new Fraction(input - inputLpFee, output);
-    priceImpact = Fraction.ONE.subtract(idealPrice.divide(actualPrice));
+    let ideal;
+    if (v0.curve === 1) {
+      const pn = v0.lo.num * v0.hi.num;
+      const pd = v0.lo.den * v0.hi.den;
+      ideal = isAInput ? new Fraction(pd, pn) : new Fraction(pn, pd);
+    } else {
+      const va0 = v0.ra * v0.hi.num + v0.l * v0.hi.den;
+      const vb0 = v0.rb * v0.lo.den + v0.l * v0.lo.num;
+      ideal = isAInput ? new Fraction(va0 * v0.lo.den, vb0 * v0.hi.num) : new Fraction(vb0 * v0.hi.num, va0 * v0.lo.den);
+    }
+    const actual = new Fraction(input - lpFee, output);
+    priceImpact = Fraction.ONE.subtract(ideal.divide(actual));
   }
   return {
     input,
     output,
-    lpFee: new AssetAmount(inputLpFee, inputMetadata),
-    nextInputReserve,
-    nextOutputReserve,
-    priceImpact
+    lpFee: new AssetAmount(lpFee, inputMetadata),
+    nextInputReserve: inputReserve + input,
+    nextOutputReserve: outputReserve - output,
+    priceImpact,
+    steps
   };
 };
 
+/** What each band holds at the pool's reserves. */
+
 /**
- * Calculate the minimal input required to receive a given output — the inverse
- * of {@link getSwapOutput}. The forward swap is linear-fractional in the
- * effective input, so it inverts in closed form; a short correction loop
- * absorbs the fee floor and integer rounding so the result is the exact minimal
- * input whose forward swap yields at least `output`.
+ * Every band's state at the pool's reserves: a band below the price holds
+ * only B, a band above it only A, the active band some of both. Null when
+ * the reserves sit on no point of the ladder.
  */
-export const getSwapInput = (inputMetadata, output, aReserve, bReserve, totalLp, sqrtPriceA, sqrtPriceB, fee, isAInput) => {
-  if (output <= 0n || aReserve <= 0n || bReserve <= 0n || totalLp <= 0n) throw new Error("Output, reserves and liquidity must be positive");
-  const [spaNum, spaDen] = sqrtPriceA;
-  const [spbNum, spbDen] = sqrtPriceB;
-  if (spaNum <= 0n || spaDen <= 0n || spbNum <= 0n || spbDen <= 0n) throw new Error("sqrt prices must be positive");
-  const outputReserve = isAInput ? bReserve : aReserve;
-  if (output > outputReserve) throw new Error("Output must not exceed the output reserve");
-  const [feeNum, feeDen] = asFeeParts(fee);
-  const feeDiff = feeDen - feeNum;
-  const va0 = aReserve * spbNum + totalLp * spbDen;
-  const vb0 = bReserve * spaDen + totalLp * spaNum;
-  const ceilDiv = (n, d) => (n + d - 1n) / d;
-
-  // Closed-form minimal effective input, then gross up for the fee floor.
-  let effMin;
-  if (isAInput) {
-    // dvaEff ≥ output·spaDen·va0 / (vb0 − output·spaDen)
-    const denom = vb0 - output * spaDen;
-    if (denom <= 0n) throw new Error("Output not reachable within the pool's range");
-    const dvaEffMin = ceilDiv(output * spaDen * va0, denom);
-    effMin = ceilDiv(dvaEffMin, spbNum);
-  } else {
-    const denom = va0 - output * spbNum;
-    if (denom <= 0n) throw new Error("Output not reachable within the pool's range");
-    const dvbEffMin = ceilDiv(output * spbNum * vb0, denom);
-    effMin = ceilDiv(dvbEffMin, spaNum);
+export const bandStates = (ladder, aReserve, bReserve, hint) => {
+  const l = indexLadder(ladder);
+  const w = findWitness(l, aReserve, bReserve, hint);
+  if (!w) return null;
+  const out = [];
+  let restA = 0n;
+  let restB = 0n;
+  for (let i = 0; i < l.bands.length; i++) {
+    const liquidity = liquidityOf(l, w.x, i);
+    if (i < w.k) {
+      const b = bSat(l, w.x, i);
+      restB += b;
+      out.push({
+        quantities: [0n, b],
+        liquidity,
+        active: false
+      });
+    } else if (i > w.k) {
+      const a = aSat(l, w.x, i);
+      restA += a;
+      out.push({
+        quantities: [a, 0n],
+        liquidity,
+        active: false
+      });
+    } else {
+      out.push({
+        quantities: [0n, 0n],
+        liquidity,
+        active: true
+      });
+    }
   }
-  let input = feeDiff > 0n ? ceilDiv(effMin * feeDen, feeDiff) : effMin;
-
-  // Correct for floor interactions: nudge up until the forward swap clears the
-  // target, then trim any over-shoot. Bounded — a couple of iterations at most.
-  const fwd = dx => rawSwapOutput(dx, aReserve, bReserve, totalLp, spaNum, spaDen, spbNum, spbDen, feeNum, feeDen, isAInput);
-  let guard = 0;
-  while (fwd(input) < output && guard++ < 64) input += 1n;
-  while (input > 1n && fwd(input - 1n) >= output) input -= 1n;
-  const inputLpFee = input * feeNum / feeDen;
-  const inputReserve = isAInput ? aReserve : bReserve;
-  const nextInputReserve = inputReserve + input;
-  const nextOutputReserve = outputReserve - output;
-  let priceImpact = Fraction.ZERO;
-  if (output > 0n) {
-    const idealPrice = isAInput ? new Fraction(va0 * spaDen, vb0 * spbNum) : new Fraction(vb0 * spbNum, va0 * spaDen);
-    const actualPrice = new Fraction(input - inputLpFee, output);
-    priceImpact = Fraction.ONE.subtract(idealPrice.divide(actualPrice));
+  const ra = aReserve - restA;
+  const rb = bReserve - restB;
+  out[w.k].quantities = [ra < 0n ? 0n : ra, rb < 0n ? 0n : rb];
+  return out;
+};
+
+/** Which band holds a sqrt-price. */
+export const bandOf = (l, s) => {
+  for (let i = 0; i < l.bands.length; i++) {
+    const hi = upperEdge(l, i);
+    if (s.num * hi.den < hi.num * s.den) return i;
+  }
+  return l.bands.length - 1;
+};
+
+/**
+ * The exact reserves a ladder holds at counter `x` with the price at
+ * sqrt-price `s`, which must lie in band `k`: what a pool creator deposits
+ * for a chosen shape, scale and launch price. The result is floored, so
+ * `findWitness` must still be run on it to learn the counter the chain
+ * derives — usually `x`, but rounding can move it.
+ */
+export const reservesAt = (l, x, k, s) => {
+  let A = 0n;
+  let B = 0n;
+  for (let i = 0; i < l.bands.length; i++) {
+    if (i > k) {
+      A += aSat(l, x, i);
+      continue;
+    }
+    if (i < k) {
+      B += bSat(l, x, i);
+      continue;
+    }
+    const lo = l.bands[i].start;
+    const hi = upperEdge(l, i);
+    const L = liquidityOf(l, x, i);
+    if (l.bands[i].curve === 1) {
+      // A constant-sum bin prices at the geometric mean; `s` only says how
+      // far through the bin the conversion has gone.
+      const K = L * delta(lo, hi);
+      const frac = (s.num * lo.den - lo.num * s.den) * hi.den;
+      const span = (hi.num * lo.den - lo.num * hi.den) * s.den;
+      const rb = K * frac / (span * (lo.den * hi.den));
+      A += (K - rb * (lo.den * hi.den)) / (lo.num * hi.num);
+      B += rb;
+    } else {
+      // a = L·(1/s − 1/hi), b = L·(s − lo), in exact rationals.
+      A += L * (s.den * hi.num - s.num * hi.den) / (s.num * hi.num);
+      B += L * (s.num * lo.den - lo.num * s.den) / (s.den * lo.den);
+    }
   }
   return {
-    input,
-    output,
-    lpFee: new AssetAmount(inputLpFee, inputMetadata),
-    nextInputReserve,
-    nextOutputReserve,
-    priceImpact
+    A,
+    B
   };
 };
 
+/** A fraction in lowest terms. */
+const reduceFrac = f => {
+  const gcd = (a, b) => b === 0n ? a : gcd(b, a % b);
+  const g = gcd(f.num < 0n ? -f.num : f.num, f.den);
+  return g > 1n ? {
+    num: f.num / g,
+    den: f.den / g
+  } : f;
+};
+
 /**
- * Deposit LP estimate for a concentrated-liquidity pool. CL deposits reuse the
- * constant-product *proportional* pinning: minting by the scarcest offered
- * asset and ceil-pinning the reserve deltas gives, per asset,
- * `a1·L0 ≥ a0·L1` and `b1·L0 ≥ b0·L1` — and those two bounds multiply to
- * exactly the on-chain CL non-swap invariant `va1·vb1·L0² ≥ va0·vb0·L1²`
- * (`cl_check.ak`). So the proportional deposit is always chain-valid; excess of
- * either asset is refunded via aChange/bChange. This mirrors the scooper's
- * `resolve_cl_deposit` (which likewise reuses the CP pinning).
+ * An equal-weight ladder of `n` bands from `lo` to `hi`, every band a CL
+ * arc at `fee` unless named in `curves`. The edges are built over a common
+ * denominator and reduced: every rational component of a concentrated-liquidity config
+ * must stay below 2^64 (spec V9).
  */
-export const calculateLiquidity = (a, b, aReserve, bReserve, totalLp) => ConstantProductPool.calculateLiquidity(a, b, aReserve, bReserve, totalLp);
+export const uniformLadder = (n, lo, hi, fee, curves = []) => {
+  if (n < 1) throw new Error("A ladder needs at least one band");
+  if (lo.num * hi.den >= hi.num * lo.den) throw new Error("The lower edge must be strictly below the upper edge");
+  const span = hi.num * lo.den - lo.num * hi.den;
+  const commonDen = lo.den * hi.den * BigInt(n);
+  const bands = [];
+  for (let i = 0; i < n; i++) {
+    bands.push({
+      start: reduceFrac({
+        num: lo.num * hi.den * BigInt(n) + span * BigInt(i),
+        den: commonDen
+      }),
+      weight: 1n,
+      curve: curves[i] ?? 0,
+      feeBuy: fee,
+      feeSell: fee
+    });
+  }
+  return {
+    bands,
+    closing: reduceFrac({
+      num: lo.num * hi.den * BigInt(n) + span * BigInt(n),
+      den: commonDen
+    }),
+    weightTotal: BigInt(n)
+  };
+};
+
+/** Band weight profiles. Every weight is at least 1, as `Create` demands. */
+
+export const bandWeights = (n, shape = "concentrated", opts = {}) => {
+  if (shape === "flat") return Array.from({
+    length: n
+  }, () => 1n);
+  const peak = Number(opts.peak ?? 64n);
+  const tail = Number(opts.tail ?? 1n);
+  const centre = opts.centre ?? (n - 1) / 2;
+  const sigma = Math.max(n / 5, 0.75);
+  const bell = (i, c) => Math.exp(-(((i - c) / sigma) ** 2));
+  const profile = i => {
+    switch (shape) {
+      case "concentrated":
+        return bell(i, centre);
+      case "skewed-low":
+        return Math.exp(-i / Math.max(n / 3, 1));
+      case "skewed-high":
+        return Math.exp(-(n - 1 - i) / Math.max(n / 3, 1));
+      case "bimodal":
+        return Math.max(bell(i, (n - 1) / 4), bell(i, 3 * (n - 1) / 4));
+      default:
+        return 1;
+    }
+  };
+  return Array.from({
+    length: n
+  }, (_, i) => {
+    const w = Math.round(tail + (peak - tail) * profile(i));
+    return BigInt(Math.max(1, w));
+  });
+};
+
+/**
+ * A ladder of `n` bands from `lo` to `hi` with a weight shape, optional
+ * constant-sum bins and an optional per-band fee. The edges are
+ * `uniformLadder`'s exactly; only the weights, curves and fees differ.
+ */
+export const shapedLadder = (n, lo, hi, fee, opts = {}) => {
+  const base = uniformLadder(n, lo, hi, fee);
+  const weights = bandWeights(n, opts.shape ?? "concentrated", opts);
+  const cs = new Set(opts.csBands ?? []);
+  const bands = base.bands.map((b, i) => {
+    const f = opts.feeAt ? opts.feeAt(i) : fee;
+    return {
+      ...b,
+      weight: weights[i],
+      curve: cs.has(i) ? 1 : 0,
+      feeBuy: f,
+      feeSell: f
+    };
+  });
+  return {
+    bands,
+    closing: base.closing,
+    weightTotal: weights.reduce((s, w) => s + w, 0n)
+  };
+};
 //# sourceMappingURL=ConcentratedLiquidityPool.js.map