@sundaeswap/math 0.2.2 → 0.4.0

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

@@ -0,0 +1,225 @@
+import { describe, expect, it } from "bun:test";
+import { IAssetAmountMetadata } from "@sundaeswap/asset";
+import { Fraction } from "@sundaeswap/fraction";
+
+import {
+  calculateLiquidity,
+  getSwapInput,
+  getSwapOutput,
+  type TSqrtPrice,
+} from "../ConcentratedLiquidityPool.js";
+
+const tokenA: IAssetAmountMetadata = {
+  assetId: "09169bb6f5ff5b246d65d65935b2222cc53b5e677d7ed22771878972.744f4b454e41",
+  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]);
+};
+
+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);
+  });
+
+  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("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),
+        );
+      }
+    }
+  });
+
+  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("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();
+  });
+});
+
+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("throws when the output exceeds the reserve", () => {
+    expect(() =>
+      getSwapInput(tokenA, 200n, 1000n, 100n, 1000n, spa, spb, threePct, true),
+    ).toThrow();
+  });
+});
+
+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);
+    }
+  });
+});

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

@@ -0,0 +1,322 @@
+import { describe, expect, it } from "bun:test";
+import { AssetAmount, IAssetAmountMetadata } from "@sundaeswap/asset";
+import { Fraction } from "@sundaeswap/fraction";
+
+import {
+  calculateDepositN,
+  calculateLiquidity,
+  calculatePinnedDeposit,
+  getSwapInput,
+  getSwapOutput,
+  pinnedDepositFromAnchor,
+} from "../ConstantSumPool.js";
+
+const tokenA: IAssetAmountMetadata = {
+  assetId: "09169bb6f5ff5b246d65d65935b2222cc53b5e677d7ed22771878972.744f4b454e41",
+  decimals: 0,
+};
+
+const threePct = new Fraction(3n, 1000n);
+
+describe("ConstantSumPool.getSwapOutput", () => {
+  it("throws on non-positive input, reserves, or prices", () => {
+    expect(() =>
+      getSwapOutput(tokenA, -1n, 10n, 10n, 1n, 1n, threePct),
+    ).toThrow();
+    expect(() =>
+      getSwapOutput(tokenA, 1n, -10n, 10n, 1n, 1n, threePct),
+    ).toThrow();
+    expect(() =>
+      getSwapOutput(tokenA, 1n, 10n, 10n, 0n, 1n, threePct),
+    ).toThrow();
+  });
+
+  it("throws when the fee is out of [0,1]", () => {
+    expect(() =>
+      getSwapOutput(tokenA, 1n, 10n, 10n, 1n, 1n, Fraction.asFraction(1.1)),
+    ).toThrow();
+  });
+
+  // Vectors cross-checked against the scooper's cs_swap_result and the live
+  // pools.quote endpoint (sundae-protocol). out = floor((dx·priceIn −
+  // floor(dx·priceIn·fee)) / priceOut).
+  it("matches the scooper at par prices (equal prices, 0.3% fee)", () => {
+    // 10000 in, prices 1e6/1e6, fee 3/1000 -> 9970 out.
+    const { output } = getSwapOutput(
+      tokenA,
+      10_000n,
+      1_000_000_000n,
+      1_000_000_000n,
+      1_000_000n,
+      1_000_000n,
+      threePct,
+    );
+    expect(output).toEqual(9970n);
+  });
+
+  it("matches the live quote for skewed prices", () => {
+    // priceIn=7, priceOut=3, 1000 in -> 2326 (tOKENA->tOKENB on preview).
+    expect(
+      getSwapOutput(tokenA, 1_000n, 1_000_000n, 1_000_000n, 7n, 3n, threePct)
+        .output,
+    ).toEqual(2326n);
+    // priceIn=3, priceOut=5 -> 598 (tOKENB->ADAb).
+    expect(
+      getSwapOutput(tokenA, 1_000n, 1_000_000n, 1_000_000n, 3n, 5n, threePct)
+        .output,
+    ).toEqual(598n);
+    // priceIn=5, priceOut=3 -> 1661 (ADAb->tOKENB).
+    expect(
+      getSwapOutput(tokenA, 1_000n, 1_000_000n, 1_000_000n, 5n, 3n, threePct)
+        .output,
+    ).toEqual(1661n);
+  });
+
+  it("caps the output at the output reserve", () => {
+    const { output } = getSwapOutput(
+      tokenA,
+      1_000_000n,
+      10n,
+      5n, // tiny output reserve
+      1_000_000n,
+      1n,
+      threePct,
+    );
+    expect(output).toEqual(5n);
+  });
+
+  it("reports the lp fee in input-asset units", () => {
+    const { lpFee } = getSwapOutput(
+      tokenA,
+      10_000n,
+      1_000_000_000n,
+      1_000_000_000n,
+      1_000_000n,
+      1_000_000n,
+      threePct,
+    );
+    // 10000 * 3/1000 = 30 (input units).
+    expect(lpFee.amount).toEqual(30n);
+    expect(lpFee.metadata.assetId).toEqual(tokenA.assetId);
+  });
+});
+
+describe("ConstantSumPool.getSwapInput", () => {
+  it("throws on non-positive output, reserves, or prices", () => {
+    expect(() => getSwapInput(tokenA, 0n, 10n, 10n, 1n, 1n, threePct)).toThrow();
+    expect(() => getSwapInput(tokenA, 1n, 0n, 10n, 1n, 1n, threePct)).toThrow();
+    expect(() => getSwapInput(tokenA, 1n, 10n, 10n, 1n, 0n, threePct)).toThrow();
+  });
+
+  it("throws when the output exceeds the output reserve, but allows draining it", () => {
+    expect(() =>
+      getSwapInput(tokenA, 11n, 1_000n, 10n, 1n, 1n, threePct),
+    ).toThrow();
+    expect(
+      getSwapInput(tokenA, 10n, 1_000n, 10n, 1n, 1n, threePct).input,
+    ).toBeGreaterThan(0n);
+  });
+
+  it("throws when the fee is 1 or more", () => {
+    expect(() =>
+      getSwapInput(tokenA, 1n, 10n, 10n, 1n, 1n, Fraction.ONE),
+    ).toThrow();
+  });
+
+  it("inverts getSwapOutput at par prices", () => {
+    // Forward: 10000 in -> 9970 out. Inverse of 9970 must be minimal.
+    const { input } = getSwapInput(
+      tokenA,
+      9_970n,
+      1_000_000_000n,
+      1_000_000_000n,
+      1_000_000n,
+      1_000_000n,
+      threePct,
+    );
+    expect(
+      getSwapOutput(
+        tokenA,
+        input,
+        1_000_000_000n,
+        1_000_000_000n,
+        1_000_000n,
+        1_000_000n,
+        threePct,
+      ).output,
+    ).toBeGreaterThanOrEqual(9_970n);
+    expect(input).toBeLessThanOrEqual(10_000n);
+  });
+
+  it("returns the minimal input across skewed prices and fees", () => {
+    const vectors: Array<[bigint, bigint, bigint, Fraction]> = [
+      [2_326n, 7n, 3n, threePct],
+      [598n, 3n, 5n, threePct],
+      [1_661n, 5n, 3n, threePct],
+      [1_000n, 1n, 1n, Fraction.ZERO],
+      [12_345n, 1_000_000n, 999_000n, new Fraction(1n, 100n)],
+    ];
+    for (const [output, priceIn, priceOut, fee] of vectors) {
+      const { input } = getSwapInput(
+        tokenA,
+        output,
+        1_000_000_000n,
+        1_000_000_000n,
+        priceIn,
+        priceOut,
+        fee,
+      );
+      const forward = (candidate: bigint) =>
+        getSwapOutput(
+          tokenA,
+          candidate,
+          1_000_000_000n,
+          1_000_000_000n,
+          priceIn,
+          priceOut,
+          fee,
+        ).output;
+      // Sufficient: the computed input actually yields the requested output…
+      expect(forward(input)).toBeGreaterThanOrEqual(output);
+      // …and minimal: one unit less does not.
+      if (input > 1n) {
+        expect(forward(input - 1n)).toBeLessThan(output);
+      }
+    }
+  });
+});
+
+describe("ConstantSumPool.calculateLiquidity", () => {
+  // Target-pinned (the deployed validator's rule): the mint is capped by the
+  // scarcest offered asset; extra above the pinned deltas is refunded.
+  it("mints by the scarcest asset and refunds the excess", () => {
+    const result = calculateLiquidity(
+      100n,
+      50n,
+      1_000n,
+      2_000n,
+      5_000n,
+      3n,
+      5n,
+    );
+    // V_b = 3000 + 10000 = 13000; t = min(100·13000/1000, 50·13000/2000)
+    //     = min(1300, 325) = 325.
+    // deltas = [ceil(1000·325/13000), ceil(2000·325/13000)] = [25, 50].
+    // after_lp = floor(5000·13325/13000) = 5125 -> minted 125.
+    expect(result.generatedLp).toEqual(125n);
+    expect(result.nextTotalLp).toEqual(5_125n);
+    expect(result.actualDepositedA).toEqual(25n);
+    expect(result.actualDepositedB).toEqual(50n);
+    expect(result.aChange).toEqual(75n);
+    expect(result.bChange).toEqual(0n);
+  });
+
+  it("rejects single-sided deposits (asymmetric deposits can't validate)", () => {
+    expect(() =>
+      calculateLiquidity(0n, 100n, 1_000n, 1_000n, 2_000n, 1n, 1n),
+    ).toThrow(/every pool asset/);
+  });
+
+  it("N-asset: values the deposit against ALL reserves, not just the touched pair", () => {
+    // 3-asset pool, unit prices: totalValue = 1000 + 2000 + 7000 = 10000.
+    // Depositing 100 of asset0 only: lp = 100·5000/10000 = 50 — NOT the
+    // 100·5000/3000 = 166 a pair-only totalValue would claim.
+    const result = calculateDepositN(
+      [100n, 0n, 0n],
+      [1_000n, 2_000n, 7_000n],
+      [1n, 1n, 1n],
+      5_000n,
+    );
+    expect(result.generatedLp).toEqual(50n);
+    expect(result.nextTotalLp).toEqual(5_050n);
+  });
+
+  it("the 2-asset wrapper matches the pinned N-asset form", () => {
+    const viaWrapper = calculateLiquidity(
+      100n,
+      50n,
+      1_000n,
+      2_000n,
+      5_000n,
+      3n,
+      5n,
+    );
+    const viaPinned = calculatePinnedDeposit(
+      [100n, 50n],
+      [1_000n, 2_000n],
+      [3n, 5n],
+      5_000n,
+    );
+    expect(viaWrapper.generatedLp).toEqual(viaPinned.generatedLp);
+    expect(viaWrapper.nextTotalLp).toEqual(viaPinned.nextTotalLp);
+  });
+
+  it("N-asset: rejects misaligned arrays", () => {
+    expect(() =>
+      calculateDepositN([1n, 2n], [10n, 20n, 30n], [1n, 1n, 1n], 100n),
+    ).toThrow();
+  });
+
+  it("pinned: mints by the scarcest asset, deltas ceil-pinned, surplus implied", () => {
+    // Live preview c618 shape: coprime-ish reserves, unit prices.
+    const reserves = [26_018_415_418n, 1_997_073_427n, 2_000_535_565n];
+    const prices = [1n, 1n, 1n];
+    const totalLp = 30_016_024_410n;
+    // Equal offers: t capped by the LARGEST reserve's coverage (USDR-like).
+    const offered = [100_000_000n, 100_000_000n, 100_000_000n];
+    const result = calculatePinnedDeposit(offered, reserves, prices, totalLp);
+
+    const vB = reserves[0] + reserves[1] + reserves[2];
+    const expectedT = (offered[0] * vB) / reserves[0]; // scarcest coverage
+    expect(result.targetDeltaV).toEqual(expectedT);
+    // Deltas never exceed the offers, and match the validator's ceil pin.
+    result.deltas.forEach((delta, i) => {
+      expect(delta).toBeLessThanOrEqual(offered[i]);
+      expect(delta).toEqual(
+        (reserves[i] * result.targetDeltaV + vB - 1n) / vB,
+      );
+    });
+    expect(result.generatedLp).toEqual(
+      (totalLp * (vB + result.targetDeltaV)) / vB - totalLp,
+    );
+    // The plain value formula would overstate the mint for this offer.
+    const naive = calculateDepositN(offered, reserves, prices, totalLp);
+    expect(naive.generatedLp).toBeGreaterThan(result.generatedLp);
+  });
+
+  it("pinned: rejects a deposit missing any pool asset", () => {
+    expect(() =>
+      calculatePinnedDeposit(
+        [100n, 0n, 100n],
+        [1_000n, 2_000n, 3_000n],
+        [1n, 1n, 1n],
+        6_000n,
+      ),
+    ).toThrow(/every pool asset/);
+  });
+
+  it("pinned: anchor auto-fill produces amounts the pin accepts at full t", () => {
+    const reserves = [26_018_415_418n, 1_997_073_427n, 2_000_535_565n];
+    const prices = [1n, 1n, 1n];
+    const totalLp = 30_016_024_410n;
+    const anchor = 100_000_000n;
+    const filled = pinnedDepositFromAnchor(1, anchor, reserves, prices);
+    expect(filled[1]).toEqual(anchor);
+    // Depositing exactly the auto-filled amounts reaches (at least) the
+    // anchor's implied t — nothing is scarcer than the anchor.
+    const vB = reserves[0] + reserves[1] + reserves[2];
+    const anchorT = (anchor * vB) / reserves[1];
+    const result = calculatePinnedDeposit(filled, reserves, prices, totalLp);
+    expect(result.targetDeltaV).toBeGreaterThanOrEqual(anchorT);
+  });
+
+  it("throws on empty deposits, empty pools, or bad prices", () => {
+    expect(() =>
+      calculateLiquidity(0n, 0n, 1_000n, 1_000n, 2_000n, 1n, 1n),
+    ).toThrow();
+    expect(() => calculateLiquidity(1n, 1n, 0n, 0n, 0n, 1n, 1n)).toThrow();
+    expect(() =>
+      calculateLiquidity(1n, 1n, 1_000n, 1_000n, 2_000n, 0n, 1n),
+    ).toThrow();
+  });
+});