@sundaeswap/math 0.4.0 → 0.5.1

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

@@ -6,13 +6,15 @@ import {
   calculateDepositN,
   calculateLiquidity,
   calculatePinnedDeposit,
+  calculateZap,
   getSwapInput,
   getSwapOutput,
   pinnedDepositFromAnchor,
 } from "../ConstantSumPool.js";
 
 const tokenA: IAssetAmountMetadata = {
-  assetId: "09169bb6f5ff5b246d65d65935b2222cc53b5e677d7ed22771878972.744f4b454e41",
+  assetId:
+    "09169bb6f5ff5b246d65d65935b2222cc53b5e677d7ed22771878972.744f4b454e41",
   decimals: 0,
 };
 
@@ -103,9 +105,13 @@ describe("ConstantSumPool.getSwapOutput", () => {
 
 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, 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();
+    expect(() =>
+      getSwapInput(tokenA, 1n, 10n, 10n, 1n, 0n, threePct),
+    ).toThrow();
   });
 
   it("throws when the output exceeds the output reserve, but allows draining it", () => {
@@ -272,9 +278,7 @@ describe("ConstantSumPool.calculateLiquidity", () => {
     // 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(delta).toEqual((reserves[i] * result.targetDeltaV + vB - 1n) / vB);
     });
     expect(result.generatedLp).toEqual(
       (totalLp * (vB + result.targetDeltaV)) / vB - totalLp,
@@ -320,3 +324,160 @@ describe("ConstantSumPool.calculateLiquidity", () => {
     ).toThrow();
   });
 });
+
+describe("ConstantSumPool.calculateZap", () => {
+  // ADA/MINT-shaped pool at prices [2, 5]: 1M A + 400k B = 4M value, balanced.
+  const prices = [2n, 5n];
+  const reserves = [1_000_000n, 400_000n];
+  const totalLp = 4_000_000n;
+  const fee = new Fraction(30n, 10_000n);
+
+  /** The scooper's fill for an arbitrary dx — reference for the optimality scan. */
+  const fillAt = (
+    dx: bigint,
+    offered: bigint[],
+    res: bigint[],
+    px: bigint[],
+    lp: bigint,
+    f: Fraction,
+  ): bigint => {
+    const [x, y] = [0, 1];
+    const inputValue = dx * px[x];
+    const feeValue = (inputValue * f.numerator) / f.denominator;
+    const dy = (inputValue - feeValue) / px[y];
+    const basket = [offered[x] - dx, offered[y] + dy];
+    const next = [res[x] + dx, res[y] - dy];
+    if (basket.some((a) => a <= 0n) || next.some((r) => r <= 0n)) return 0n;
+    try {
+      return calculatePinnedDeposit(basket, next, px, lp).generatedLp;
+    } catch {
+      return 0n;
+    }
+  };
+
+  it("rejects anything but two assets, bad prices or reserves, and empty or negative offers", () => {
+    expect(() =>
+      calculateZap([1n, 1n, 1n], [1n, 1n, 1n], [1n, 1n, 1n], 1n, fee),
+    ).toThrow("exactly two assets");
+    expect(() =>
+      calculateZap([1n, 0n], reserves, [0n, 5n], totalLp, fee),
+    ).toThrow("Prices");
+    expect(() =>
+      calculateZap([1n, 0n], [0n, 1n], prices, totalLp, fee),
+    ).toThrow("Reserves");
+    expect(() =>
+      calculateZap([0n, 0n], reserves, prices, totalLp, fee),
+    ).toThrow("at least one positive");
+    expect(() =>
+      calculateZap([-1n, 1n], reserves, prices, totalLp, fee),
+    ).toThrow();
+    expect(() => calculateZap([1n, 1n], reserves, prices, 0n, fee)).toThrow(
+      "liquidity",
+    );
+    expect(() =>
+      calculateZap([1n, 1n], reserves, prices, totalLp, Fraction.ONE),
+    ).toThrow("fee");
+  });
+
+  it("is a plain pinned deposit when the basket already matches the reserves", () => {
+    const offered = [100_000n, 40_000n];
+    const zap = calculateZap(offered, reserves, prices, totalLp, fee);
+    const pinned = calculatePinnedDeposit(offered, reserves, prices, totalLp);
+
+    expect(zap.swapIndex).toBeUndefined();
+    expect(zap.swapInput).toBe(0n);
+    expect(zap.swapOutput).toBe(0n);
+    expect(zap.nextReserves).toEqual(reserves);
+    expect(zap.depositBasket).toEqual(offered);
+    expect(zap.generatedLp).toBe(pinned.generatedLp);
+    expect(zap.change).toEqual([0n, 0n]);
+  });
+
+  it("single-sided A: swaps the closed-form dx, deposits the rest, leaves dust change", () => {
+    const zap = calculateZap([100_000n, 0n], reserves, prices, totalLp, fee);
+
+    // dx = (a_X·r_Y)·feeDen·p_Y / ((feeDen−feeNum)·p_X·(r_X+a_X) + feeDen·p_Y·r_Y)
+    //    = 2e15 / 41_934_000_000 = 47_693
+    expect(zap.swapIndex).toBe(0);
+    expect(zap.swapInput).toBe(47_693n);
+    // getSwapOutput semantics: floor((95_386 − floor(95_386·0.003)) / 5)
+    expect(zap.swapOutput).toBe(19_020n);
+    expect(zap.nextReserves).toEqual([1_047_693n, 380_980n]);
+    expect(zap.depositBasket).toEqual([52_307n, 19_020n]);
+
+    // The pin is the already-tested function applied to that basket.
+    const pinned = calculatePinnedDeposit(
+      zap.depositBasket,
+      zap.nextReserves,
+      prices,
+      totalLp,
+    );
+    expect(zap.deltas).toEqual(pinned.deltas);
+    expect(zap.generatedLp).toBe(pinned.generatedLp);
+    expect(zap.change).toEqual([
+      zap.depositBasket[0] - pinned.deltas[0],
+      zap.depositBasket[1] - pinned.deltas[1],
+    ]);
+    // Rounding leaves at most a unit or two behind.
+    expect(zap.change[0] + zap.change[1]).toBeLessThanOrEqual(2n);
+
+    // A 200k-value basket into a 4M pool with 4M LP is 200k LP before fees;
+    // half of it swaps at 0.3%, so the loss is ~0.15%.
+    expect(zap.generatedLp).toBeLessThan(200_000n);
+    expect(zap.generatedLp).toBeGreaterThan(199_400n);
+  });
+
+  it("swap leg agrees with getSwapOutput for the same dx", () => {
+    const zap = calculateZap([100_000n, 0n], reserves, prices, totalLp, fee);
+    const swap = getSwapOutput(
+      tokenA,
+      zap.swapInput,
+      reserves[0],
+      reserves[1],
+      prices[0],
+      prices[1],
+      fee,
+    );
+    expect(zap.swapOutput).toBe(swap.output);
+    expect(zap.nextReserves).toEqual([
+      swap.nextInputReserve,
+      swap.nextOutputReserve,
+    ]);
+  });
+
+  it("single-sided B swaps in the other direction", () => {
+    const zap = calculateZap([0n, 40_000n], reserves, prices, totalLp, fee);
+    expect(zap.swapIndex).toBe(1);
+    expect(zap.swapInput).toBeGreaterThan(0n);
+    expect(zap.depositBasket[0]).toBeGreaterThan(0n);
+    expect(zap.depositBasket[1]).toBeLessThan(40_000n);
+    expect(zap.nextReserves[0]).toBeLessThan(reserves[0]);
+    expect(zap.nextReserves[1]).toBeGreaterThan(reserves[1]);
+  });
+
+  it("closed-form dx maximizes minted LP over every integer dx", () => {
+    // Small enough to scan exhaustively; skewed prices and reserves so the
+    // ratio work is non-trivial.
+    const px = [3n, 7n];
+    const res = [5_000n, 2_000n];
+    const lp = 29_000n;
+    const f = new Fraction(25n, 10_000n);
+    const offered = [1_200n, 50n];
+
+    const zap = calculateZap(offered, res, px, lp, f);
+    expect(zap.swapIndex).toBe(0);
+
+    let best = 0n;
+    for (let dx = 0n; dx <= offered[0]; dx++) {
+      const got = fillAt(dx, offered, res, px, lp, f);
+      if (got > best) best = got;
+    }
+    expect(zap.generatedLp).toBe(best);
+  });
+
+  it("throws when the offer is too small to survive the swap", () => {
+    expect(() =>
+      calculateZap([1n, 0n], reserves, prices, totalLp, fee),
+    ).toThrow("too small");
+  });
+});

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

@@ -103,6 +103,59 @@ describe("getPrice()", () => {
       Math.abs(normalCppPrice.toNumber() - 1.0),
     );
   });
+
+  // |dx/dy| of the on-chain invariant 4A(x + y) + D = 4AD + D^3/(4xy), as an
+  // exact rational on the scaled reserves. Independent of getPrice's integer
+  // arithmetic, so it pins both the amplification term and the orientation.
+  const exactSpot = (aReserve: bigint, bReserve: bigint, laf: bigint) => {
+    const d = getSumInvariant(laf, aReserve, bReserve);
+    const x = aReserve * RESERVE_PRECISION;
+    const y = bReserve * RESERVE_PRECISION;
+    const dCubed = d * d * d;
+    return new Fraction(
+      x * (16n * laf * x * y * y + dCubed),
+      y * (16n * laf * x * x * y + dCubed),
+    );
+  };
+  const relativeError = (actual: Fraction, expected: Fraction) =>
+    Math.abs(actual.toNumber() / expected.toNumber() - 1);
+
+  const offParPools: [bigint, bigint, bigint][] = [
+    [250275094796n, 250515678047n, 500n],
+    [1_000_000_000n, 1_100_000_000n, 100n],
+    [2_000_000_000n, 1_000_000_000n, 50n],
+    [5_000_000_000n, 1_000_000_000n, 10n],
+    [1_010_000_000n, 990_000_250n, 200n],
+  ];
+
+  test.each(offParPools)(
+    "matches the derivative of the on-chain invariant (a=%s, b=%s, laf=%s)",
+    (aReserve, bReserve, laf) => {
+      const price = getPrice(aReserve, bReserve, laf);
+      expect(
+        relativeError(price, exactSpot(aReserve, bReserve, laf)),
+      ).toBeLessThan(1e-9);
+    },
+  );
+
+  test.each(offParPools)(
+    "agrees with a central finite difference of getNewY (a=%s, b=%s, laf=%s)",
+    (aReserve, bReserve, laf) => {
+      const dA = 1000n;
+      const d = getSumInvariant(laf, aReserve, bReserve);
+      const lowY = getNewY(aReserve + dA, laf, d);
+      const highY = getNewY(aReserve - dA, laf, d);
+      const slope = new Fraction(dA * 2n * RESERVE_PRECISION, highY - lowY);
+      expect(
+        relativeError(getPrice(aReserve, bReserve, laf), slope),
+      ).toBeLessThan(1e-9);
+    },
+  );
+
+  test("issue #172: preview pool 488fe776 at laf 500", () => {
+    const price = getPrice(250275094796n, 250515678047n, 500n);
+    expect(price.toNumber()).toBeCloseTo(0.999999040146, 11);
+  });
 });
 
 describe("getSwapOutput(usdc,)", () => {
@@ -199,7 +252,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 0n,
       outReserve: [3n, 2n],
       lpFee: 0n,
-      impact: new Fraction(0n, 0n),
+      impact: new Fraction(0n, 1n),
     },
     {
       id: 2,
@@ -209,7 +262,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 1n,
       outReserve: [3n, 2n],
       lpFee: 0n,
-      impact: new Fraction(249n, 1000000n),
+      impact: new Fraction(31n, 250000n),
     },
     {
       id: 3,
@@ -219,7 +272,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 2n,
       outReserve: [102n, 1n],
       lpFee: 0n,
-      impact: new Fraction(245001n, 250000n),
+      impact: new Fraction(490001n, 500000n),
     },
     {
       id: 4,
@@ -229,7 +282,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 99n,
       outReserve: [102n, 1n],
       lpFee: 0n,
-      impact: new Fraction(244453n, 1000000n),
+      impact: new Fraction(14333n, 100000n),
     },
     {
       id: 5,
@@ -260,7 +313,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 0n,
       outReserve: [3n, 2n],
       lpFee: 0n,
-      impact: new Fraction(0n, 0n),
+      impact: new Fraction(0n, 1n),
     },
     {
       id: 8,
@@ -270,7 +323,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 0n,
       outReserve: [3n, 3n],
       lpFee: 1n,
-      impact: new Fraction(249n, 1000000n),
+      impact: new Fraction(31n, 250000n),
     },
     {
       id: 9,
@@ -280,7 +333,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 0n,
       outReserve: [3n, 6n],
       lpFee: 1n,
-      impact: new Fraction(499n, 1000000n),
+      impact: new Fraction(249n, 1000000n),
     },
     {
       id: 10,
@@ -290,7 +343,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 1n,
       outReserve: [102n, 2n],
       lpFee: 1n,
-      impact: new Fraction(495001n, 500000n),
+      impact: new Fraction(990001n, 1000000n),
     },
     {
       id: 11,
@@ -300,7 +353,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 196n,
       outReserve: [202n, 3n],
       lpFee: 1n,
-      impact: new Fraction(559n, 1000n),
+      impact: new Fraction(393153n, 1000000n),
     },
     {
       id: 12,
@@ -332,7 +385,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 2139306697n,
       outReserve: [7044962984n, 670265463643n],
       lpFee: 21829661n,
-      impact: new Fraction(380983n, 1000000n),
+      impact: new Fraction(101761n, 1000000n),
     },
     {
       id: 15,
@@ -342,7 +395,7 @@ describe("getSwapOutput(usdc,)", () => {
       out: 1024031n,
       outReserve: [3696261028076n, 77871392800159n],
       lpFee: 3091n,
-      impact: new Fraction(34239n, 1000000n),
+      impact: new Fraction(6001n, 1000000n),
     },
   ] as {
     input: bigint;
@@ -466,31 +519,31 @@ describe("getSwapInput", () => {
       input: 1n,
       reserves: [1n, 2n],
       fee: zeroPct,
-      impact: new Fraction(0n, 2000n),
+      impact: new Fraction(0n, 4000n),
     },
     {
       input: 100n,
       reserves: [1n, 2n],
       fee: zeroPct,
-      impact: new Fraction(0n, 2000n),
+      impact: new Fraction(0n, 4000n),
     },
     {
       input: 100n,
       reserves: [1n, 100n],
       fee: zeroPct,
-      impact: new Fraction(245025n, 445500n),
+      impact: new Fraction(245025n, 643500n),
     },
     {
       input: 100n,
       reserves: [100n, 100n],
       fee: zeroPct,
-      impact: new Fraction(400400n, 20020000n),
+      impact: new Fraction(800400n, 40020000n),
     },
     {
       input: 50n,
       reserves: [100n, 100n],
       fee: zeroPct,
-      impact: new Fraction(200200n, 10010000n),
+      impact: new Fraction(400200n, 20010000n),
     },
 
     // Simple boundary cases
@@ -498,25 +551,25 @@ describe("getSwapInput", () => {
       input: 10n,
       reserves: [10n, 30n],
       fee: threePct,
-      impact: new Fraction(20315n, 200450n),
+      impact: new Fraction(40315n, 400450n),
     },
     {
       input: 100n,
       reserves: [1n, 100n],
       fee: threePct,
-      impact: new Fraction(251100n, 445500n),
+      impact: new Fraction(257100n, 643500n),
     },
     {
       input: 100n,
       reserves: [100n, 100n],
       fee: threePct,
-      impact: new Fraction(1001000n, 20020000n),
+      impact: new Fraction(2001000n, 40020000n),
     },
     {
       input: 50n,
       reserves: [100n, 100n],
       fee: threePct,
-      impact: new Fraction(600600n, 10010000n),
+      impact: new Fraction(1200600n, 20010000n),
     },
 
     // // Real world examples
@@ -524,19 +577,19 @@ describe("getSwapInput", () => {
       input: 5n,
       reserves: [84159832107n, 123172010729n],
       fee: fivePct,
-      impact: new Fraction(168806906319235n, 842673001141955n),
+      impact: new Fraction(337126570533235n, 1684271322211955n),
     },
     {
       input: 100n,
       reserves: [84159832107n, 123172010729n],
       fee: fivePct,
-      impact: new Fraction(849140270799500n, 16853460022839100n),
+      impact: new Fraction(1690738591869500n, 33685426444239100n),
     },
     {
       input: 1291591603n,
       reserves: [5753371381n, 672426600000n],
       fee: onePct,
-      impact: new Fraction(15118057654414078594677n, 40350603201831427592080n),
+      impact: new Fraction(5112429850089508046677n, 55212615531111655078080n),
     },
   ] as {
     input: bigint;