@sundaeswap/math 0.2.2 → 0.3.0

package/src/PoolMath/ConcentratedLiquidityPool.ts

@@ -0,0 +1,275 @@
+import { AssetAmount, IAssetAmountMetadata } from "@sundaeswap/asset";
+import { Fraction, type TFractionLike } 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.
+ */
+export type TSwapOutcome = {
+  input: bigint;
+  output: bigint;
+  lpFee: AssetAmount<IAssetAmountMetadata>;
+  nextInputReserve: bigint;
+  nextOutputReserve: bigint;
+  priceImpact: Fraction;
+};
+
+/** A sqrt-price bound from the CL config, as an exact rational `[num, den]`. */
+export type TSqrtPrice = [bigint, bigint];
+
+/**
+ * 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:
+ *
+ *   VA = a·spbNum + L·spbDen
+ *   VB = b·spaDen + L·spaNum
+ *
+ * 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.
+ */
+
+const asFeeParts = (fee: TFractionLike): [bigint, bigint] => {
+  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 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.
+ */
+const rawSwapOutput = (
+  dx: bigint,
+  aReserve: bigint,
+  bReserve: bigint,
+  totalLp: bigint,
+  spaNum: bigint,
+  spaDen: bigint,
+  spbNum: bigint,
+  spbDen: bigint,
+  feeNum: bigint,
+  feeDen: bigint,
+  isAInput: boolean,
+): bigint => {
+  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;
+  }
+  const dvbEff = dxEff * spaNum;
+  const denom = (vb0 + dvbEff) * spbNum;
+  if (denom <= 0n) return 0n;
+  return (va0 * dvbEff) / denom;
+};
+
+/**
+ * Calculate the swap outcome for a concentrated-liquidity pool.
+ *
+ * @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.
+ */
+export const getSwapOutput = (
+  inputMetadata: IAssetAmountMetadata,
+  input: bigint,
+  aReserve: bigint,
+  bReserve: bigint,
+  totalLp: bigint,
+  sqrtPriceA: TSqrtPrice,
+  sqrtPriceB: TSqrtPrice,
+  fee: TFractionLike,
+  isAInput: boolean,
+): TSwapOutcome => {
+  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);
+
+  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;
+  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));
+  }
+
+  return {
+    input,
+    output,
+    lpFee: new AssetAmount(inputLpFee, inputMetadata),
+    nextInputReserve,
+    nextOutputReserve,
+    priceImpact,
+  };
+};
+
+/**
+ * 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`.
+ */
+export const getSwapInput = (
+  inputMetadata: IAssetAmountMetadata,
+  output: bigint,
+  aReserve: bigint,
+  bReserve: bigint,
+  totalLp: bigint,
+  sqrtPriceA: TSqrtPrice,
+  sqrtPriceB: TSqrtPrice,
+  fee: TFractionLike,
+  isAInput: boolean,
+): TSwapOutcome => {
+  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: bigint, d: bigint) => (n + d - 1n) / d;
+
+  // Closed-form minimal effective input, then gross up for the fee floor.
+  let effMin: bigint;
+  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);
+  }
+  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: bigint) =>
+    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));
+  }
+
+  return {
+    input,
+    output,
+    lpFee: new AssetAmount(inputLpFee, inputMetadata),
+    nextInputReserve,
+    nextOutputReserve,
+    priceImpact,
+  };
+};
+
+/**
+ * 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).
+ */
+export const calculateLiquidity = (
+  a: bigint,
+  b: bigint,
+  aReserve: bigint,
+  bReserve: bigint,
+  totalLp: bigint,
+) => ConstantProductPool.calculateLiquidity(a, b, aReserve, bReserve, totalLp);

package/src/PoolMath/ConstantSumPool.ts

@@ -0,0 +1,371 @@
+import { AssetAmount, IAssetAmountMetadata } from "@sundaeswap/asset";
+import { Fraction, type TFractionLike } from "@sundaeswap/fraction";
+import { SharedPoolMath } from "./index.js";
+
+/**
+ * Holds the calculated outcome of a constant-sum swap. Mirrors
+ * {@link ConstantProductPool.TSwapOutcome} so both can flow through the same
+ * generic swap-outcome consumers.
+ */
+export type TSwapOutcome = {
+  input: bigint;
+  output: bigint;
+  lpFee: AssetAmount<IAssetAmountMetadata>;
+  nextInputReserve: bigint;
+  nextOutputReserve: bigint;
+  priceImpact: Fraction;
+};
+
+/**
+ * Calculate the swap outcome for a constant-sum (fixed-price) pool — the
+ * invariant used by Sundae v4 stable/pegged pools. Unlike constant product,
+ * the exchange rate is fixed by the pool's per-asset `prices`: the input is
+ * converted to "value" at `priceIn`, the fee is taken off that value, and the
+ * remainder is converted to the output asset at `priceOut`. The result is
+ * capped at the output reserve (you can't take more than the pool holds).
+ *
+ * Matches the scooper's `cs_swap_result`:
+ *   output = floor((input·priceIn − floor(input·priceIn·fee)) / priceOut)
+ *
+ * @param inputMetadata Metadata for the supplied (input) asset — used for the fee AssetAmount.
+ * @param input The amount of the input asset being swapped.
+ * @param inputReserve The pool's reserve of the input asset.
+ * @param outputReserve The pool's reserve of the output asset.
+ * @param priceIn The pool's price for the input asset (from the constant-sum config).
+ * @param priceOut The pool's price for the output asset.
+ * @param fee The liquidity-provider fee (plus protocol fee) as a fraction.
+ * @param roundOutputUp When true, round the output up instead of flooring.
+ * @returns The swap details in the shared {@link TSwapOutcome} shape.
+ */
+export const getSwapOutput = (
+  inputMetadata: IAssetAmountMetadata,
+  input: bigint,
+  inputReserve: bigint,
+  outputReserve: bigint,
+  priceIn: bigint,
+  priceOut: bigint,
+  fee: TFractionLike,
+  roundOutputUp?: boolean,
+): TSwapOutcome => {
+  if (input <= 0n || inputReserve <= 0n || outputReserve <= 0n)
+    throw new Error("Input and reserves must be positive");
+  if (priceIn <= 0n || priceOut <= 0n)
+    throw new Error("Prices must be positive");
+
+  const feeFraction = Fraction.asFraction(fee);
+  if (feeFraction.lt(Fraction.ZERO) || feeFraction.gt(Fraction.ONE))
+    throw new Error("fee must be between 0 and 1");
+
+  const inputValue = input * priceIn;
+  const feeValue = new Fraction(
+    inputValue * BigInt(feeFraction.numerator),
+    BigInt(feeFraction.denominator),
+  ).quotient;
+  const outputValue = inputValue - feeValue;
+
+  let output = roundOutputUp
+    ? (outputValue + priceOut - 1n) / priceOut
+    : outputValue / priceOut;
+
+  // Can't take more than the pool holds.
+  if (output > outputReserve) {
+    output = outputReserve;
+  }
+
+  // LP fee expressed in input-asset units (value scales linearly with input,
+  // so the input-denominated fee is input·feeRate) — matching ConstantProductPool.
+  const inputLpFee = new Fraction(
+    input * BigInt(feeFraction.numerator),
+    BigInt(feeFraction.denominator),
+  ).quotient;
+
+  const nextInputReserve = inputReserve + input;
+  const nextOutputReserve = outputReserve - output;
+
+  // Price impact vs the pool's par price (priceOut/priceIn input-per-output);
+  // ~0 for a constant-sum pool aside from the fee. See ConstantProductPool.
+  let priceImpact = Fraction.ZERO;
+  if (output > 0n) {
+    const amountInLessFee = input - inputLpFee;
+    const idealPrice = new Fraction(priceOut, priceIn);
+    const actualPrice = new Fraction(amountInLessFee, output);
+    priceImpact = Fraction.ONE.subtract(idealPrice.divide(actualPrice));
+  }
+
+  return {
+    input,
+    output,
+    lpFee: new AssetAmount(inputLpFee, inputMetadata),
+    nextInputReserve,
+    nextOutputReserve,
+    priceImpact,
+  };
+};
+
+/**
+ * Calculate the minimal input required to receive a given output from a
+ * constant-sum pool — the exact inverse of {@link getSwapOutput}.
+ *
+ * The forward math floors the fee off the input value, which makes the
+ * post-fee value `ceil(input·priceIn·(1−fee))`; inverting that ceiling gives
+ * the smallest input whose forward swap yields at least `output`.
+ *
+ * Unlike constant product there is no asymptote, so an output equal to the
+ * full output reserve is attainable (the pool can be drained at par).
+ *
+ * @param inputMetadata Metadata for the supplied (input) asset — used for the fee AssetAmount.
+ * @param output The desired amount of the output asset.
+ * @param inputReserve The pool's reserve of the input asset.
+ * @param outputReserve The pool's reserve of the output asset.
+ * @param priceIn The pool's price for the input asset (from the constant-sum config).
+ * @param priceOut The pool's price for the output asset.
+ * @param fee The liquidity-provider fee (plus protocol fee) as a fraction.
+ * @returns The swap details in the shared {@link TSwapOutcome} shape.
+ */
+export const getSwapInput = (
+  inputMetadata: IAssetAmountMetadata,
+  output: bigint,
+  inputReserve: bigint,
+  outputReserve: bigint,
+  priceIn: bigint,
+  priceOut: bigint,
+  fee: TFractionLike,
+): TSwapOutcome => {
+  if (output <= 0n || inputReserve <= 0n || outputReserve <= 0n)
+    throw new Error("Output and reserves must be positive");
+  if (priceIn <= 0n || priceOut <= 0n)
+    throw new Error("Prices must be positive");
+  if (output > outputReserve)
+    throw new Error("Output must not exceed the output reserve");
+
+  const feeFraction = Fraction.asFraction(fee);
+  if (feeFraction.lt(Fraction.ZERO) || feeFraction.gte(Fraction.ONE))
+    throw new Error("fee must be [0,1)");
+
+  const feeNum = BigInt(feeFraction.numerator);
+  const feeDen = BigInt(feeFraction.denominator);
+  const feeDiff = feeDen - feeNum;
+
+  // Forward: outputValue = ceil(input·priceIn·feeDiff/feeDen), and the swap
+  // yields ≥ output iff outputValue ≥ output·priceOut. ceil(x/d) ≥ T for
+  // integer x iff x ≥ d·(T−1)+1, so the minimal input is the ceiling of
+  // (feeDen·(output·priceOut − 1) + 1) / (feeDiff·priceIn).
+  const targetValue = output * priceOut;
+  const numerator = feeDen * (targetValue - 1n) + 1n;
+  const denominator = feeDiff * priceIn;
+  const input = (numerator + denominator - 1n) / denominator;
+
+  const inputLpFee = new Fraction(input * feeNum, feeDen).quotient;
+  const nextInputReserve = inputReserve + input;
+  const nextOutputReserve = outputReserve - output;
+
+  // Same par-price impact definition as getSwapOutput.
+  const amountInLessFee = input - inputLpFee;
+  const idealPrice = new Fraction(priceOut, priceIn);
+  const actualPrice = new Fraction(amountInLessFee, output);
+  const priceImpact = Fraction.ONE.subtract(idealPrice.divide(actualPrice));
+
+  return {
+    input,
+    output,
+    lpFee: new AssetAmount(inputLpFee, inputMetadata),
+    nextInputReserve,
+    nextOutputReserve,
+    priceImpact,
+  };
+};
+
+/**
+ * Calculate the deposit parameters for a 2-asset constant-sum pool via the
+ * TARGET-PINNED rule the deployed validator enforces (see
+ * {@link calculatePinnedDeposit}): the mint is capped by the scarcest offered
+ * asset, both assets must be offered, and anything above the pinned deltas is
+ * refunded via aChange/bChange.
+ *
+ * @param {bigint} a - The amount of token A to deposit.
+ * @param {bigint} b - The amount of token B to deposit.
+ * @param {bigint} aReserve - The current reserve of token A in the pool.
+ * @param {bigint} bReserve - The current reserve of token B in the pool.
+ * @param {bigint} totalLp - The total lp tokens for the pool before the deposit.
+ * @param {bigint} priceA - The pool's price for token A (from the constant-sum config).
+ * @param {bigint} priceB - The pool's price for token B.
+ * @throws {Error} If the pool has no value or minted lp.
+ * @throws {Error} If both deposit amounts are zero, or either is negative.
+ * @throws {Error} If either price is non-positive.
+ */
+export const calculateLiquidity = (
+  a: bigint,
+  b: bigint,
+  aReserve: bigint,
+  bReserve: bigint,
+  totalLp: bigint,
+  priceA: bigint,
+  priceB: bigint,
+) => {
+  // Target-pinned (what the deployed validator accepts): mint by the
+  // scarcest offered asset; anything above the pinned deltas is refunded
+  // (aChange/bChange).
+  const { deltas, generatedLp, nextTotalLp, shareAfterDeposit } =
+    calculatePinnedDeposit(
+      [a, b],
+      [aReserve, bReserve],
+      [priceA, priceB],
+      totalLp,
+    );
+
+  return {
+    nextTotalLp,
+    generatedLp,
+    shareAfterDeposit,
+    aChange: a - deltas[0],
+    bChange: b - deltas[1],
+    actualDepositedA: deltas[0],
+    actualDepositedB: deltas[1],
+  };
+};
+
+/**
+ * The N-asset form of {@link calculateLiquidity}, mirroring the v4 contract's
+ * `compute_deposit_n` exactly: a deposit of any mix of the pool's assets is
+ * valued at the fixed prices against the value of ALL reserves —
+ *
+ *   generatedLp = Σ(amount_i·price_i) · totalLp / Σ(reserve_i·price_i)
+ *
+ * The three arrays must be aligned to the pool's canonical asset order (the
+ * API's `assets`/`quantities`/`prices`). Estimating an N-asset pool's deposit
+ * from just two of its reserves overstates the minted LP — the denominator is
+ * the whole pool's value — which is exactly the mistake this exists to
+ * prevent.
+ */
+/**
+ * The target-pinned deposit — what the deployed CS validator (cs_check tag 6)
+ * actually accepts, and what the scooper builds. Asymmetric deposits are
+ * disallowed on-chain: the fill declares a value delta `t` and every asset's
+ * contribution is ceil-pinned to `ceil(r_i·t/V_b)`, with total LP
+ * floor-pinned to `floor(lp_b·(V_b+t)/V_b)`. Given what the user offers, the
+ * largest fillable t is capped by the SCARCEST asset —
+ * `t = min_i floor(offered_i·V_b/r_i)` — and anything above the pinned
+ * deltas is returned as surplus. Every pool asset must be offered (> 0) or
+ * t is zero and the deposit can never fill.
+ *
+ * Contrast with `calculateDepositN`, which is the plain value formula:
+ * it matches the pin only for exactly proportional offers and OVERSTATES the
+ * mint otherwise — using it for `minReceived` makes non-proportional orders
+ * unfillable.
+ */
+export const calculatePinnedDeposit = (
+  offered: bigint[],
+  reserves: bigint[],
+  prices: bigint[],
+  totalLp: bigint,
+): {
+  targetDeltaV: bigint;
+  deltas: bigint[];
+  generatedLp: bigint;
+  nextTotalLp: bigint;
+  shareAfterDeposit: Fraction;
+} => {
+  if (offered.length !== reserves.length || reserves.length !== prices.length)
+    throw new Error("offered, reserves and prices must be aligned");
+  if (prices.some((p) => p <= 0n)) throw new Error("Prices must be positive");
+  if (totalLp <= 0n) throw new Error("Not enough pool liquidity");
+
+  let vB = 0n;
+  for (let i = 0; i < reserves.length; i++) {
+    vB += reserves[i] * prices[i];
+  }
+  if (vB <= 0n) throw new Error("Pool value is zero");
+
+  let t: bigint | undefined;
+  for (let i = 0; i < offered.length; i++) {
+    if (reserves[i] === 0n) continue;
+    const cap = (offered[i] * vB) / reserves[i];
+    t = t === undefined || cap < t ? cap : t;
+  }
+  if (t === undefined || t <= 0n) {
+    throw new Error(
+      "A constant-sum deposit must offer every pool asset in proportion (asymmetric deposits are disallowed on-chain)",
+    );
+  }
+
+  const deltas = reserves.map((r) => (r * t! + vB - 1n) / vB); // ceil
+  const nextTotalLp = (totalLp * (vB + t)) / vB; // floor
+  const generatedLp = nextTotalLp - totalLp;
+  if (generatedLp <= 0n) throw new Error("Deposit mints zero LP");
+
+  return {
+    targetDeltaV: t,
+    deltas,
+    generatedLp,
+    nextTotalLp,
+    shareAfterDeposit: SharedPoolMath.getShare(generatedLp, nextTotalLp),
+  };
+};
+
+/**
+ * The per-asset amounts a pinned deposit needs when the user anchors on one
+ * asset's amount: t from the anchor (`floor(anchor·V_b/r_anchor)`), every
+ * delta ceil-pinned to it. Drives proportional auto-fill in deposit forms.
+ */
+export const pinnedDepositFromAnchor = (
+  anchorIndex: number,
+  anchorAmount: bigint,
+  reserves: bigint[],
+  prices: bigint[],
+): bigint[] => {
+  if (reserves.length !== prices.length)
+    throw new Error("reserves and prices must be aligned");
+  if (
+    anchorIndex < 0 ||
+    anchorIndex >= reserves.length ||
+    reserves[anchorIndex] <= 0n
+  )
+    throw new Error("anchor asset has no reserve");
+  if (anchorAmount <= 0n) return reserves.map(() => 0n);
+
+  let vB = 0n;
+  for (let i = 0; i < reserves.length; i++) {
+    vB += reserves[i] * prices[i];
+  }
+  if (vB <= 0n) throw new Error("Pool value is zero");
+
+  const t = (anchorAmount * vB) / reserves[anchorIndex];
+  return reserves.map((r, i) =>
+    i === anchorIndex ? anchorAmount : (r * t + vB - 1n) / vB,
+  );
+};
+
+export const calculateDepositN = (
+  amounts: bigint[],
+  reserves: bigint[],
+  prices: bigint[],
+  totalLp: bigint,
+) => {
+  if (amounts.length !== reserves.length || reserves.length !== prices.length)
+    throw new Error("amounts, reserves and prices must be aligned");
+  if (prices.some((p) => p <= 0n)) throw new Error("Prices must be positive");
+  // Zeros in a MIX are fine — offering a subset is the point of the N-asset
+  // form. What's rejected is a negative amount, or offering nothing at all.
+  if (amounts.some((a) => a < 0n) || amounts.every((a) => a === 0n))
+    throw new Error(
+      "Deposit amounts must be non-negative, with at least one positive",
+    );
+
+  let totalValue = 0n;
+  let depositValue = 0n;
+  for (let i = 0; i < amounts.length; i++) {
+    totalValue += reserves[i] * prices[i];
+    depositValue += amounts[i] * prices[i];
+  }
+  if (totalValue <= 0n || totalLp <= 0n)
+    throw new Error("Not enough pool liquidity");
+
+  const generatedLp = (depositValue * totalLp) / totalValue;
+  const nextTotalLp = totalLp + generatedLp;
+
+  return {
+    nextTotalLp,
+    generatedLp,
+    shareAfterDeposit: SharedPoolMath.getShare(generatedLp, nextTotalLp),
+  };
+};