@sundaeswap/math 0.5.0 → 0.6.0

package/src/PoolMath/StableSwapsPool.ts

@@ -396,32 +396,32 @@ export const getSwapOutput = (
 };
 
 /**
- * Calculates the current price (exchange rate) of asset A in terms of asset B for a Stableswaps pool.
- * The price is derived from the Stableswaps curve equation and takes into account the amplification factor.
+ * The pool's marginal price as raw units of asset A per raw unit of asset B,
+ * |dx/dy| at the current reserves. This is the "ideal" price that swap price
+ * impact is measured against.
  *
- * The calculation uses the formula:
+ * Derived from the Stableswaps invariant 4A(x + y) + D = 4AD + D^3 / (4xy):
  * price = (xpA + (dR * aReserve) / bReserve) / (xpA + dR)
- * where xpA = (Ann * aReserve) / A_PRECISION and dR is derived from the sum invariant
+ * where xpA = 4 * laf * aReserve and dR = D^3 / (4 * aReserve * bReserve)
  *
  * @param {bigint} aReserve - The current reserve amount of asset A in the pool.
  * @param {bigint} bReserve - The current reserve amount of asset B in the pool.
  * @param {bigint} laf - The linear amplification factor of the pool.
- * @returns {Fraction} The price of asset A in terms of asset B as a Fraction.
+ * @returns {Fraction} Raw A per raw B at the current reserves.
  */
 export function getPrice(
   aReserve: bigint,
   bReserve: bigint,
   laf: bigint,
 ): Fraction {
-  // dx_0 / dx_1 only, however can have any number of coins in pool
-  const ann = laf * 2n * A_PRECISION;
   const sumInvariant =
     getSumInvariant(laf, aReserve, bReserve) / RESERVE_PRECISION;
   // D / n^n with n = 2
   let dR = sumInvariant / 4n;
   dR = (dR * sumInvariant) / aReserve;
   dR = (dR * sumInvariant) / bReserve;
-  const xpA = (ann * aReserve) / A_PRECISION;
+  // 4A is the amplification term of the on-chain invariant, A = laf.
+  const xpA = 4n * laf * aReserve;
   const p = new Fraction(xpA + (dR * aReserve) / bReserve, xpA + dR);
   return p;
 }

package/src/PoolMath/__tests__/ConcentratedLiquidityPool.test.ts

@@ -1,225 +1,218 @@
 import { describe, expect, it } from "bun:test";
 import { IAssetAmountMetadata } from "@sundaeswap/asset";
-import { Fraction } from "@sundaeswap/fraction";
 
 import {
-  calculateLiquidity,
-  getSwapInput,
+  aSat,
+  bandOf,
+  bandOutput,
+  bandProof,
+  bandStates,
+  bandView,
+  buildIndex,
+  findWitness,
   getSwapOutput,
-  type TSqrtPrice,
+  indexLadder,
+  liquidityOf,
+  prefixes,
+  reservesAt,
+  shapedLadder,
+  swapSteps,
+  type TLadder,
+  uniformLadder,
 } from "../ConcentratedLiquidityPool.js";
 
-const tokenA: IAssetAmountMetadata = {
-  assetId: "09169bb6f5ff5b246d65d65935b2222cc53b5e677d7ed22771878972.744f4b454e41",
+const tokenB: IAssetAmountMetadata = {
+  assetId: "09169bb6f5ff5b246d65d65935b2222cc53b5e677d7ed22771878972.744f4b454e42",
   decimals: 0,
 };
 
-const threePct = new Fraction(3n, 1000n);
-const zeroFee = new Fraction(0n, 1n);
-
-// Range [0.5, 2.0] as sqrt-price rationals.
-const spa: TSqrtPrice = [1n, 2n];
-const spb: TSqrtPrice = [2n, 1n];
-
-/** Direct evaluation of the on-chain/scooper virtual-reserve swap formula. */
-const refOutput = (
-  dx: bigint,
-  a: bigint,
-  b: bigint,
-  l: bigint,
-  isAInput: boolean,
-  feeNum: bigint,
-  feeDen: bigint,
-): bigint => {
-  const fee = (dx * feeNum) / feeDen;
-  const dxEff = dx - fee;
-  const va0 = a * spb[0] + l * spb[1];
-  const vb0 = b * spa[1] + l * spa[0];
-  if (isAInput) {
-    const dvaEff = dxEff * spb[0];
-    return (vb0 * dvaEff) / ((va0 + dvaEff) * spa[1]);
-  }
-  const dvbEff = dxEff * spa[0];
-  return (va0 * dvbEff) / ((vb0 + dvbEff) * spb[0]);
+// The eight equal-weight ladder of sundae-v4's lib/tests/unit/cl_check_unit.ak
+// (edges 1.00..1.08 at 1e6, fee 3/1000).
+const fee = { num: 3n, den: 1000n };
+const den = 1_000_000n;
+const eq8: TLadder = {
+  bands: Array.from({ length: 8 }, (_, i) => ({
+    start: { num: 1_000_000n + 10_000n * BigInt(i), den },
+    weight: 1n,
+    curve: 0 as const,
+    feeBuy: fee,
+    feeSell: fee,
+  })),
+  closing: { num: 1_080_000n, den },
+  weightTotal: 8n,
 };
+const A = 8_637_368n;
+const B = 624_999n;
 
-describe("ConcentratedLiquidityPool.getSwapOutput", () => {
-  it("matches the hand-computed virtual-reserve formula (A→B, no fee)", () => {
-    // a=b=L=1000, range [0.5,2]: va0=vb0=3000, dvaEff=200,
-    // out = 3000·200 / ((3000+200)·2) = 600000/6400 = 93.75 -> 93.
-    const { output } = getSwapOutput(
-      tokenA,
-      100n,
-      1000n,
-      1000n,
-      1000n,
-      spa,
-      spb,
-      zeroFee,
-      true,
-    );
-    expect(output).toEqual(93n);
+describe("ConcentratedLiquidityPool: the on-chain vectors", () => {
+  it("finds the witness the Aiken test names", () => {
+    const w = findWitness(eq8, A, B)!;
+    expect(w.x).toBe(999_999_813n);
+    expect(w.k).toBe(0);
+    const l = indexLadder(eq8);
+    const p = prefixes(l, w.x, w.k);
+    expect(p.ca).toBe(8_021_634n);
+    expect(p.cb).toBe(0n);
+    expect(liquidityOf(l, w.x, w.k)).toBe(124_999_976n);
+    expect(aSat(l, w.x, w.k)).toBe(1_237_624n);
+    expect(bandProof(l, A, B, 999_999_813n, 0)).toBe(true);
+    expect(bandProof(l, A, B, 71_428_457n, 7)).toBe(false);
   });
 
-  it("matches the hand-computed formula (B→A, no fee)", () => {
-    // dvbEff=100, out = 3000·100 / ((3000+100)·2) = 300000/6200 = 48.38 -> 48.
-    const { output } = getSwapOutput(
-      tokenA,
-      100n,
-      1000n,
-      1000n,
-      1000n,
-      spa,
-      spb,
-      zeroFee,
-      false,
-    );
-    expect(output).toEqual(48n);
+  it("finds the post-swap witness", () => {
+    expect(findWitness(eq8, 8_636_752n, 625_623n)!.x).toBe(999_999_938n);
   });
 
-  it("agrees with the reference evaluator across sizes and fees", () => {
-    for (const isAInput of [true, false]) {
-      for (const dx of [1n, 7n, 100n, 5000n, 250000n]) {
-        const { output } = getSwapOutput(
-          tokenA,
-          dx,
-          1_000_000n,
-          1_000_000n,
-          1_000_000n,
-          spa,
-          spb,
-          threePct,
-          isAInput,
-        );
-        expect(output).toEqual(
-          refOutput(dx, 1_000_000n, 1_000_000n, 1_000_000n, isAInput, 3n, 1000n),
-        );
-      }
-    }
+  // sundae-v4 #228 (SV4-006): the band fee rounds UP, so 624 B pays a fee
+  // of ceil(624 * 3 / 1000) = 2 and the pair admits 615 A. With the floored
+  // fee of 1 it admitted 616. lib/tests/unit/cl_check_unit.ak.
+  it("pays 615 A for 624 B, the band fee rounded up to 2", () => {
+    const out = getSwapOutput(tokenB, 624n, A, B, eq8, false);
+    expect(out.output).toBe(615n);
+    expect(out.lpFee.amount).toBe(2n);
+    expect(out.steps.length).toBe(1);
+    expect(out.steps[0]!.after.x).toBe(1_000_000_062n);
+    expect(findWitness(eq8, A - 615n, B + 624n)!.x).toBe(1_000_000_062n);
   });
 
-  it("caps output at the output reserve", () => {
-    const { output } = getSwapOutput(
-      tokenA,
-      10_000_000n,
-      100n,
-      5n,
-      1_000_000n,
-      spa,
-      spb,
-      zeroFee,
-      true,
-    );
-    expect(output).toBeLessThanOrEqual(5n);
+  it("recovers from a stale hint", () => {
+    const out = getSwapOutput(tokenB, 624n, A, B, eq8, false, { x: 123n, k: 5 });
+    expect(out.output).toBe(615n);
   });
 
-  it("throws on non-positive input/reserves/liquidity", () => {
-    expect(() =>
-      getSwapOutput(tokenA, 0n, 10n, 10n, 10n, spa, spb, zeroFee, true),
-    ).toThrow();
-    expect(() =>
-      getSwapOutput(tokenA, 1n, 10n, 10n, 0n, spa, spb, zeroFee, true),
-    ).toThrow();
+  it("charges a fee of one unit on an input below den / num", () => {
+    const l = indexLadder(eq8);
+    const v = bandView(l, A, B, findWitness(l, A, B)!);
+    // ceil(1 * 3 / 1000) = 1, so one unit of input has no effective input.
+    expect(bandOutput(v, false, 1n)).toBe(0n);
+    // ceil(333 * 3 / 1000) = 1: dx_eff = 332.
+    const free = { ...v, feeBuy: { num: 0n, den: 1n } };
+    expect(bandOutput(v, false, 333n)).toBe(bandOutput(free, false, 332n));
+    // ceil(1000 * 3 / 1000) = 3 exactly: no extra unit when it divides.
+    expect(bandOutput(v, false, 1_000n)).toBe(bandOutput(free, false, 997n));
+    // A zero rate still charges nothing, whatever its denominator.
+    const zero = { ...v, feeBuy: { num: 0n, den: 1_000n } };
+    expect(bandOutput(zero, false, 1_000n)).toBe(bandOutput(free, false, 1_000n));
+  });
+
+  it("crosses bands for an input larger than the active band", () => {
+    const l = indexLadder(eq8);
+    const w = findWitness(l, A, B)!;
+    // Band 0 holds a_sat_0 of A; buying more than that crosses into band 1.
+    const steps = swapSteps(l, A, B, false, 2_000_000n, w)!;
+    expect(steps.length).toBeGreaterThan(1);
+    expect(steps[0]!.band).toBe(0);
+    expect(steps[1]!.band).toBe(1);
+    const total = steps.reduce((s, st) => s + st.output, 0n);
+    expect(total).toBeGreaterThan(1_237_624n);
+    expect(total).toBeLessThan(A);
   });
-});
 
-describe("ConcentratedLiquidityPool.getSwapInput", () => {
-  it("returns the minimal input whose forward swap clears the target", () => {
-    for (const isAInput of [true, false]) {
-      for (const targetOut of [1n, 40n, 93n, 1000n, 90_000n]) {
-        const { input } = getSwapInput(
-          tokenA,
-          targetOut,
-          1_000_000n,
-          1_000_000n,
-          1_000_000n,
-          spa,
-          spb,
-          threePct,
-          isAInput,
-        );
-        const got = getSwapOutput(
-          tokenA,
-          input,
-          1_000_000n,
-          1_000_000n,
-          1_000_000n,
-          spa,
-          spb,
-          threePct,
-          isAInput,
-        ).output;
-        // Reaches the target...
-        expect(got).toBeGreaterThanOrEqual(targetOut);
-        // ...and is minimal: one unit less falls short.
-        const less = getSwapOutput(
-          tokenA,
-          input - 1n,
-          1_000_000n,
-          1_000_000n,
-          1_000_000n,
-          spa,
-          spb,
-          threePct,
-          isAInput,
-        ).output;
-        expect(less).toBeLessThan(targetOut);
-      }
-    }
+  it("refuses an input the ladder cannot absorb", () => {
+    // The price sits in band 0: selling A pays out band 0's B residual and
+    // then has no band below to walk into.
+    const small = getSwapOutput(tokenB, 1_000n, A, B, eq8, true);
+    expect(small.output).toBeGreaterThan(0n);
+    expect(() => getSwapOutput(tokenB, 1_000_000_000n, A, B, eq8, true)).toThrow();
   });
 
-  it("throws when the output exceeds the reserve", () => {
-    expect(() =>
-      getSwapInput(tokenA, 200n, 1000n, 100n, 1000n, spa, spb, threePct, true),
-    ).toThrow();
+  it("splits the reserves across the bands exactly", () => {
+    const states = bandStates(eq8, A, B)!;
+    expect(states.length).toBe(8);
+    expect(states[0]!.active).toBe(true);
+    const sumA = states.reduce((s, b) => s + b.quantities[0], 0n);
+    const sumB = states.reduce((s, b) => s + b.quantities[1], 0n);
+    expect(sumA).toBe(A);
+    expect(sumB).toBe(B);
+    for (let i = 1; i < 8; i++) expect(states[i]!.quantities[1]).toBe(0n);
   });
 });
 
-describe("ConcentratedLiquidityPool.calculateLiquidity", () => {
-  // The on-chain CL non-swap invariant a proportional deposit must satisfy.
-  const invariantHolds = (
-    a0: bigint,
-    b0: bigint,
-    l0: bigint,
-    da: bigint,
-    db: bigint,
-    dl: bigint,
-  ): boolean => {
-    const va0 = a0 * spb[0] + l0 * spb[1];
-    const vb0 = b0 * spa[1] + l0 * spa[0];
-    const a1 = a0 + da;
-    const b1 = b0 + db;
-    const l1 = l0 + dl;
-    const va1 = a1 * spb[0] + l1 * spb[1];
-    const vb1 = b1 * spa[1] + l1 * spa[0];
-    return va1 * vb1 * l0 * l0 >= va0 * vb0 * l1 * l1;
-  };
-
-  it("mints proportionally and the fill satisfies the CL invariant", () => {
-    const cases: Array<[bigint, bigint, bigint, bigint, bigint]> = [
-      // [offeredA, offeredB, reserveA, reserveB, totalLp]
-      [100n, 100n, 1000n, 1000n, 1000n],
-      [100n, 250n, 1000n, 1000n, 1000n], // B surplus
-      [500n, 100n, 3333n, 991n, 1777n], // coprime-ish reserves
-      [12345n, 67890n, 1_000_000n, 5_000_000n, 2_000_000n],
-    ];
-    for (const [a, b, ra, rb, lp] of cases) {
-      const res = calculateLiquidity(a, b, ra, rb, lp);
-      expect(res.generatedLp).toBeGreaterThan(0n);
-      // Never consumes more than offered.
-      expect(res.actualDepositedA).toBeLessThanOrEqual(a);
-      expect(res.actualDepositedB).toBeLessThanOrEqual(b);
-      // The resulting deposit is chain-valid under the CL invariant.
-      expect(
-        invariantHolds(
-          ra,
-          rb,
-          lp,
-          res.actualDepositedA,
-          res.actualDepositedB,
-          res.generatedLp,
-        ),
-      ).toBe(true);
-    }
+describe("ConcentratedLiquidityPool: building a ladder", () => {
+  it("derives reserves at a launch price that the ladder then witnesses", () => {
+    const ladder = shapedLadder(8, { num: 95n, den: 100n }, { num: 105n, den: 100n }, fee, {
+      shape: "concentrated",
+    });
+    expect(ladder.weightTotal).toBe(ladder.bands.reduce((s, b) => s + b.weight, 0n));
+    const launch = { num: 1n, den: 1n };
+    const k = bandOf(ladder, launch);
+    const r = reservesAt(ladder, 1_000_000_000n, k, launch);
+    const w = findWitness(ladder, r.A, r.B)!;
+    expect(w).not.toBeNull();
+    // The reserves are floored, so the band the chain derives can sit one
+    // below the one asked for; a creator takes the witness's band.
+    expect(Math.abs(w.k - k)).toBeLessThanOrEqual(1);
+    expect(buildIndex(ladder).length).toBe(8);
+  });
+
+  it("keeps uniform edges in lowest terms and refuses an inverted range", () => {
+    const u = uniformLadder(4, { num: 1n, den: 2n }, { num: 2n, den: 1n }, fee);
+    expect(u.bands[0]!.start).toEqual({ num: 1n, den: 2n });
+    expect(u.closing).toEqual({ num: 2n, den: 1n });
+    expect(() => uniformLadder(4, { num: 2n, den: 1n }, { num: 1n, den: 2n }, fee)).toThrow();
   });
 });
+
+// The scaling bench of sundae-v4 validators/benches/scaling/cl.ak after #228
+// (the band fee rounded up): for N equal-weight bands with edges
+// 1.00 + 0.01*j and fee 3/1000, a B-in swap of 0.1% of the B reserve.
+// Each row is (N, A, B, X, k, A', B', X', budget); the chain admits A - A'.
+const benchRows: [number, bigint, bigint, bigint, bigint, bigint, bigint, bigint, bigint][] = [
+    [1, 4925865n, 4999999n, 999999826n, 0n, 4920931n, 5004998n, 1000001381n, 1555n],
+    [2, 2414759n, 7500000n, 999999999n, 1n, 2407502n, 7507500n, 1000002313n, 2314n],
+    [3, 4782629n, 5000000n, 999999899n, 1n, 4777791n, 5005000n, 1000001399n, 1500n],
+    [4, 3517823n, 6249999n, 999999799n, 2n, 3511894n, 6256248n, 1000001620n, 1821n],
+    [5, 4645760n, 4999999n, 999999749n, 2n, 4641017n, 5004998n, 1000001269n, 1520n],
+    [6, 3797891n, 5833333n, 999999799n, 3n, 3792463n, 5839166n, 1000001701n, 1902n],
+    [7, 4514876n, 5000000n, 999999766n, 3n, 4510223n, 5005000n, 1000001333n, 1567n],
+    [8, 3876484n, 5624999n, 999999799n, 4n, 3871350n, 5630623n, 1000001551n, 1752n],
+    [9, 4389622n, 4999999n, 999999674n, 4n, 4385059n, 5004998n, 1000001303n, 1629n],
+    [10, 3877638n, 5500000n, 999999786n, 5n, 3872713n, 5505500n, 1000001599n, 1813n],
+    [11, 4269672n, 5000000n, 999999879n, 5n, 4265194n, 5005000n, 1000001446n, 1567n],
+    [12, 3842499n, 5416666n, 999999799n, 6n, 3837740n, 5422082n, 1000001599n, 1800n],
+    [13, 4154721n, 4999999n, 999999649n, 6n, 4150328n, 5004998n, 1000001383n, 1734n],
+    [14, 3788541n, 5357142n, 999999799n, 7n, 3783921n, 5362499n, 1000001599n, 1800n],
+    [15, 4044489n, 5000000n, 999999848n, 7n, 4040176n, 5005000n, 1000001445n, 1597n],
+    [16, 3724376n, 5312499n, 999999799n, 8n, 3719878n, 5317811n, 1000001399n, 1600n],
+    [17, 3938713n, 4999999n, 999999712n, 8n, 3934480n, 5004998n, 1000001387n, 1675n],
+    [18, 3654687n, 5277777n, 999999643n, 9n, 3650300n, 5283054n, 1000001395n, 1752n],
+    [19, 3837151n, 5000000n, 999999903n, 9n, 3832994n, 5005000n, 1000001455n, 1552n],
+    [20, 3582202n, 5249999n, 999999799n, 10n, 3577917n, 5255248n, 1000001399n, 1600n],
+    [21, 3739575n, 4999999n, 999999692n, 10n, 3735494n, 5004998n, 1000001309n, 1617n],
+    [22, 3508584n, 5227272n, 999999799n, 11n, 3504393n, 5232499n, 1000001399n, 1600n],
+    [23, 3645776n, 5000000n, 999999854n, 11n, 3641767n, 5005000n, 1000001380n, 1526n],
+    [24, 3434886n, 5208333n, 999999754n, 12n, 3430785n, 5213541n, 1000001588n, 1834n],
+    [25, 3555555n, 5000000n, 999999791n, 12n, 3551617n, 5005000n, 1000001445n, 1654n],
+    [26, 3361787n, 5192307n, 999999655n, 13n, 3357770n, 5197499n, 1000001522n, 1867n],
+    [27, 3468729n, 4999999n, 999999792n, 13n, 3464861n, 5004998n, 1000001295n, 1503n],
+    [28, 3289730n, 5178571n, 999999799n, 14n, 3285794n, 5183749n, 1000001614n, 1815n],
+    [29, 3385125n, 4999999n, 999999735n, 14n, 3381324n, 5004998n, 1000001272n, 1537n],
+    [30, 3219003n, 5166666n, 999999799n, 15n, 3215144n, 5171832n, 1000001599n, 1800n],
+    [31, 3304583n, 4999999n, 999999653n, 15n, 3300848n, 5004998n, 1000001389n, 1736n],
+    [32, 3149791n, 5156250n, 999999799n, 16n, 3146005n, 5161406n, 1000001553n, 1754n],
+];
+
+const benchLadder = (n: number): TLadder => ({
+  bands: Array.from({ length: n }, (_, i) => ({
+    start: { num: 1_000_000n + 10_000n * BigInt(i), den },
+    weight: 1n,
+    curve: 0 as const,
+    feeBuy: fee,
+    feeSell: fee,
+  })),
+  closing: { num: 1_000_000n + 10_000n * BigInt(n), den },
+  weightTotal: BigInt(n),
+});
+
+describe("ConcentratedLiquidityPool: the scaling bench vectors", () => {
+  for (const [n, a, b, x, k, a1, b1] of benchRows) {
+    it(`pays ${a - a1} A for ${b1 - b} B on ${n} bands`, () => {
+      const ladder = benchLadder(n);
+      const w = findWitness(ladder, a, b)!;
+      expect(w.x).toBe(x);
+      expect(BigInt(w.k)).toBe(k);
+      const out = getSwapOutput(tokenB, b1 - b, a, b, ladder, false, w);
+      expect(out.output).toBe(a - a1);
+    });
+  }
+});