@cubee_ee/sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Endgame AMM DEX Foundation.
+// See LICENSE at the repository root.
+
+/**
+ * @cube/sdk — client library for the Cubic Pool AMM on Solana.
+ *
+ * Entry point barrel. Most consumers will want to import from this root:
+ *
+ * ```ts
+ * import { CubicPoolClient, CubeBackendClient, getConfig } from "@cube/sdk";
+ *
+ * const cfg = getConfig("mainnet", { backendEndpoint: "https://api.cube.fi" });
+ * const pool = new CubicPoolClient({ config: cfg, poolAddress, rpc: { endpoint: cfg.defaults.rpcEndpoint } });
+ * const info = await pool.sync();
+ * if (info.ok) console.log(info.data.tokens.map(t => t.metadata?.symbol));
+ * ```
+ */
+
+export * from "./config";
+export * from "./types";
+export * from "./utils";
+export * from "./math";
+export * from "./parsers";
+export * from "./clients";
+export * from "./idl";
+
+// Explicit runtime re-exports keep CommonJS output statically discoverable for
+// Vite/Rollup consumers that import named exports from the package root.
+export {
+  getConfig,
+  programId,
+  CUBIC_POOL_SEED,
+  BPT_MINT_SEED,
+  STLD_HELPER_SEED,
+  TREASURY_SEED,
+  WEIGHT_SCALE,
+  MIN_WEIGHT,
+  MAX_WEIGHT,
+  MIN_TOKENS,
+  MAX_TOKENS,
+  BPT_DECIMALS,
+  SWAP_FEE_PRECISION,
+  PROTOCOL_FEE_PRECISION,
+  MAX_SWAP_FEE_RATE,
+  MAX_PROTOCOL_FEE_RATE,
+  MINIMUM_INITIAL_BPT,
+  SLIPPAGE_PRECISION,
+  MIN_SLIPPAGE_HBPS,
+} from "./config";
+export { NETWORK_PROGRAMS, DEFAULT_RPC_ENDPOINT } from "./config/networks";
+export { KNOWN_TOKENS, resolveKnownToken } from "./config/tokens";
+export { ok, err } from "./types/result";
+export {
+  ONE,
+  mulDown,
+  mulUp,
+  divDown,
+  divUp,
+  complement,
+  weightToFp,
+} from "./math/fixedPoint";
+export { lnFp, expFp, powFp } from "./math/logExp";
+export {
+  calcOutGivenIn,
+  calcBptOutGivenExactTokensIn,
+  calcTokensOutGivenBptIn,
+  calcSpotOut,
+} from "./math/cubicMath";
+export { validateWeights, calcSpotPrice } from "./math/weightedMath";
+export {
+  capDepositAmountsToLpRatio,
+  computeAllocations,
+  computeTwoTokenOptimalAllocations,
+} from "./math/singleToken";
+export { applySlippage, applySwapFee, lpBalances, priceImpactHbps } from "./math/slippage";
+export { RpcClient } from "./clients/RpcClient";
+export { CubeBackendClient } from "./clients/CubeBackendClient";
+export { CubicPoolClient } from "./clients/CubicPoolClient";
+export { SingleTokenDepositClient } from "./clients/SingleTokenDepositClient";
+export { PoolFactoryClient } from "./clients/PoolFactoryClient";
+export { AdminClient } from "./clients/AdminClient";
+export {
+  buildSwapIx,
+  buildSwapTx,
+  buildAddLiquidityIx,
+  buildAddLiquidityTx,
+  buildRemoveLiquidityIx,
+  buildRemoveLiquidityTx,
+  buildSingleTokenDepositIx,
+  buildSingleTokenDepositTx,
+  buildInitializeConfigIx,
+  buildInitializeCubicPoolIx,
+  buildDeployPoolTx,
+} from "./clients/tx-builders";
+export { decodePoolAccount, POOL_DISCRIMINATOR_LEN } from "./parsers/poolAccount";
+export { decodeMintAccount } from "./parsers/mintAccount";
+export { parseCubicPoolEvents } from "./parsers/events";
+export { BorshReader } from "./parsers/borsh";
+
+export type {
+  CubeConfig,
+  CubeConfigOverrides,
+  ProgramIdKind,
+  Network,
+  NetworkPrograms,
+  TokenInfo,
+} from "./config";
+export type {
+  SdkResult,
+  SdkError,
+  SdkErrorCode,
+  PoolTokenInfo,
+  PoolInfo,
+  PoolSummary,
+  SwapParams,
+  SwapQuote,
+  AddLiquidityParams,
+  RemoveLiquidityParams,
+  SingleTokenDepositParams,
+  SingleTokenDepositQuote,
+  BuiltTx,
+  DeployPoolParams,
+  CubicPoolEvent,
+  PoolInitializedEvent,
+  SwapEvent,
+  LiquidityAddedEvent,
+  LiquidityRemovedEvent,
+  ProtocolFeesCollectedEvent,
+  PoolEnabledUpdatedEvent,
+  SwapsEnabledUpdatedEvent,
+  SingleTokenDepositEvent,
+  UnknownEvent,
+} from "./types";
+export type {
+  AllocationResult,
+} from "./math/singleToken";
+export type {
+  RawPoolAccount,
+  RawMintAccount,
+} from "./parsers";
+export type {
+  RpcClientParams,
+  CubeBackendClientParams,
+  StatsKind,
+  StatsWindow,
+  StatsSeriesPoint,
+  StatsSeries,
+  PriceMap,
+  CubicPoolClientParams,
+  SingleTokenDepositClientParams,
+  PoolFactoryClientParams,
+  InitializeConfigParams,
+} from "./clients";

package/src/math/cubicMath.ts

@@ -0,0 +1,89 @@
+import { complement, divDown, divUp, mulDown, ONE, weightToFp } from "./fixedPoint";
+import { powFp } from "./logExp";
+
+/**
+ * Port of `CubicMath::calc_out_given_in` from
+ * `contracts/programs/cubic-pool/src/math/cubic_math.rs`.
+ *
+ * Formula:   aO = bO * (1 - (bI / (bI + aI))^(wI / wO))
+ *
+ * Inputs are u64 raw amounts (bigint here to avoid overflow). Decimals
+ * cancel in the ratio bI/(bI+aI), so no scaling needed.
+ */
+export function calcOutGivenIn(params: {
+  virtualBalanceIn: bigint;
+  weightInBps: bigint;
+  virtualBalanceOut: bigint;
+  weightOutBps: bigint;
+  amountIn: bigint;
+  actualBalanceOut: bigint;
+}): bigint {
+  const { virtualBalanceIn, weightInBps, virtualBalanceOut, weightOutBps, amountIn, actualBalanceOut } =
+    params;
+  const denom = virtualBalanceIn + amountIn;
+  const base = divUp(virtualBalanceIn, denom);
+  const exp = divDown(weightToFp(weightInBps), weightToFp(weightOutBps));
+  let power = powFp(base, exp);
+  // Match Rust's +1 bias + clamp to ONE.
+  power = power + 1n;
+  if (power > ONE) power = ONE;
+  const comp = complement(power);
+  const out = mulDown(virtualBalanceOut, comp);
+  if (out > actualBalanceOut) {
+    throw new Error("cubicMath: amount out exceeds actual balance");
+  }
+  return out;
+}
+
+/**
+ * Port of `CubicMath::calc_bpt_out_given_exact_tokens_in`.
+ * Proportional join: `bpt = total_supply * min(amount_i / actual_balance_i)`
+ * across tokens with `actual_balance_i > 0`.
+ */
+export function calcBptOutGivenExactTokensIn(
+  actualBalances: bigint[],
+  amountsIn: bigint[],
+  bptTotalSupply: bigint
+): bigint {
+  if (actualBalances.length !== amountsIn.length) {
+    throw new Error("cubicMath: balances/amounts length mismatch");
+  }
+  let ratioMin: bigint | null = null;
+  for (let i = 0; i < actualBalances.length; i++) {
+    if (actualBalances[i] === 0n) continue;
+    const ratio = divDown(amountsIn[i], actualBalances[i]);
+    ratioMin = ratioMin === null || ratio < ratioMin ? ratio : ratioMin;
+  }
+  if (ratioMin === null) throw new Error("cubicMath: no live tokens");
+  return (bptTotalSupply * ratioMin) / ONE;
+}
+
+/**
+ * Port of `CubicMath::calc_tokens_out_given_bpt_in`. Proportional exit.
+ */
+export function calcTokensOutGivenBptIn(
+  actualBalances: bigint[],
+  bptAmount: bigint,
+  bptTotalSupply: bigint
+): bigint[] {
+  if (bptTotalSupply === 0n) throw new Error("cubicMath: zero total supply");
+  const ratio = divDown(bptAmount, bptTotalSupply);
+  return actualBalances.map((bal) => mulDown(bal, ratio));
+}
+
+/**
+ * Spot amount-out: aO = aI * (bO * wI) / (bI * wO). Always ≥
+ * `calcOutGivenIn` for the same inputs (curve slippage drags the real
+ * value below spot). Useful for UI "price impact" calculations.
+ */
+export function calcSpotOut(params: {
+  virtualBalanceIn: bigint;
+  weightInBps: bigint;
+  virtualBalanceOut: bigint;
+  weightOutBps: bigint;
+  amountIn: bigint;
+}): bigint {
+  const { virtualBalanceIn, weightInBps, virtualBalanceOut, weightOutBps, amountIn } = params;
+  if (virtualBalanceIn === 0n || weightOutBps === 0n) return 0n;
+  return (amountIn * virtualBalanceOut * weightInBps) / (virtualBalanceIn * weightOutBps);
+}

package/src/math/fixedPoint.ts

@@ -0,0 +1,39 @@
+/**
+ * Fixed-point arithmetic with 1e18 precision. Port of
+ * `contracts/programs/cubic-pool/src/math/fixed_point.rs`. All functions
+ * operate on bigint to match the Rust u128/i128 semantics exactly.
+ */
+
+export const ONE = 1_000_000_000_000_000_000n; // 1e18
+
+export function mulDown(a: bigint, b: bigint): bigint {
+  const product = a * b;
+  return product / ONE;
+}
+
+export function mulUp(a: bigint, b: bigint): bigint {
+  const product = a * b;
+  if (product === 0n) return 0n;
+  return (product - 1n) / ONE + 1n;
+}
+
+export function divDown(a: bigint, b: bigint): bigint {
+  if (b === 0n) throw new Error("fixedPoint.divDown: divide by zero");
+  return (a * ONE) / b;
+}
+
+export function divUp(a: bigint, b: bigint): bigint {
+  if (b === 0n) throw new Error("fixedPoint.divUp: divide by zero");
+  if (a === 0n) return 0n;
+  return (a * ONE - 1n) / b + 1n;
+}
+
+export function complement(x: bigint): bigint {
+  return x < ONE ? ONE - x : 0n;
+}
+
+/** Convert bps → 1e18 fixed point. 5000 bps → 5e17. */
+export function weightToFp(weightBps: bigint | number): bigint {
+  const w = typeof weightBps === "number" ? BigInt(weightBps) : weightBps;
+  return (w * ONE) / 10_000n;
+}

package/src/math/index.ts

@@ -0,0 +1,6 @@
+export * from "./fixedPoint";
+export * from "./logExp";
+export * from "./cubicMath";
+export * from "./weightedMath";
+export * from "./singleToken";
+export * from "./slippage";

package/src/math/logExp.ts

@@ -0,0 +1,82 @@
+/**
+ * Fixed-point ln/exp/pow over 1e18 precision. Port of
+ * `contracts/programs/cubic-pool/src/math/log_exp_math.rs` via bigint —
+ * results match the Rust version modulo identical rounding.
+ *
+ * Intended for off-chain quoting; on-chain calls go through cubic-pool's
+ * own implementation.
+ */
+
+const ONE = 1_000_000_000_000_000_000n;
+const TWO = 2n * ONE;
+const LN2 = 693_147_180_559_945_309n; // ln(2) * 1e18
+
+/** Natural logarithm. Accepts x > 0 in 1e18 fp, returns signed i128 in 1e18 fp. */
+export function lnFp(x: bigint): bigint {
+  if (x <= 0n) throw new Error("logExp.ln: x must be positive");
+  if (x === ONE) return 0n;
+  if (x < ONE) {
+    const inv = (ONE * ONE + x - 1n) / x;
+    return -lnPos(inv);
+  }
+  return lnPos(x);
+}
+
+function lnPos(x: bigint): bigint {
+  let val = x;
+  let acc = 0n;
+  while (val >= TWO) {
+    acc += LN2;
+    val /= 2n;
+  }
+  const y = val - ONE;
+  if (y === 0n) return acc;
+
+  // Taylor series: ln(1+y) = y - y^2/2 + y^3/3 - ...
+  let term = y;
+  let sum = y;
+  let sign = -1n;
+  for (let k = 2n; k <= 30n; k++) {
+    term = (term * y) / ONE;
+    const tk = term / k;
+    sum = sign < 0n ? sum - tk : sum + tk;
+    sign = -sign;
+    if (tk === 0n) break;
+  }
+  return acc + sum;
+}
+
+/** e^x. Accepts signed i128 1e18 fp, returns u128 1e18 fp. */
+export function expFp(x: bigint): bigint {
+  if (x === 0n) return ONE;
+  if (x < 0n) {
+    const pos = expFp(-x);
+    return (ONE * ONE) / pos;
+  }
+  let ux = x;
+  let k = 0n;
+  while (ux >= LN2) {
+    ux -= LN2;
+    k += 1n;
+  }
+  // Taylor series: e^r = 1 + r + r^2/2! + ...
+  let sum = ONE;
+  let term = ONE;
+  for (let i = 1n; i <= 30n; i++) {
+    term = (term * ux) / ONE;
+    term = term / i;
+    sum += term;
+    if (term === 0n) break;
+  }
+  return sum << BigInt(k);
+}
+
+/** Fixed-point pow: x^y where both are 1e18 fp. */
+export function powFp(base: bigint, exponent: bigint): bigint {
+  if (exponent === 0n) return ONE;
+  if (base === ONE) return ONE;
+  if (base === 0n) return 0n;
+  const l = lnFp(base);
+  const prod = (exponent * (l < 0n ? -l : l)) / ONE;
+  return l < 0n ? expFp(-prod) : expFp(prod);
+}

package/src/math/singleToken.ts

@@ -0,0 +1,250 @@
+import { ONE } from "./fixedPoint";
+import { calcOutGivenIn } from "./cubicMath";
+import { lpBalances } from "./slippage";
+import { PROTOCOL_FEE_PRECISION, SWAP_FEE_PRECISION } from "../config";
+
+export interface AllocationResult {
+  /** Per-token integer amount allocations; sum = amountIn. */
+  allocations: bigint[];
+  /** Scaled W values, for inspection/debugging. */
+  wScaled: bigint[];
+  /** Sum of wScaled. */
+  sumW: bigint;
+}
+
+/**
+ * Port of stld `compute_allocations` from
+ * `contracts/programs/single-token-liquidity/src/math.rs`.
+ *
+ * W_i = weight_i * factBalance_i / virtBalance_i (dimensionless concentration).
+ * share_i = W_i / ΣW. amount_alloc[i] = amountIn * share_i.
+ *
+ * Integer truncation of per-token amounts routes the remainder to the
+ * input-token slot so Σ allocations == amountIn exactly.
+ */
+export function computeAllocations(params: {
+  actualBalances: bigint[];
+  virtualBalances: bigint[];
+  weightsBps: number[];
+  amountIn: bigint;
+  tokenInIndex: number;
+}): AllocationResult {
+  const { actualBalances, virtualBalances, weightsBps, amountIn, tokenInIndex } = params;
+  const n = actualBalances.length;
+  if (n !== virtualBalances.length || n !== weightsBps.length) {
+    throw new Error("computeAllocations: length mismatch");
+  }
+  if (tokenInIndex < 0 || tokenInIndex >= n) {
+    throw new Error("computeAllocations: tokenInIndex out of range");
+  }
+  const wScaled: bigint[] = [];
+  for (let i = 0; i < n; i++) {
+    if (virtualBalances[i] <= 0n) {
+      throw new Error(`computeAllocations: virtualBalance[${i}] must be positive`);
+    }
+    const w = (BigInt(weightsBps[i]) * actualBalances[i] * ONE) / (virtualBalances[i] * 10_000n);
+    wScaled.push(w);
+  }
+  const sumW = wScaled.reduce((a, b) => a + b, 0n);
+  if (sumW === 0n) {
+    throw new Error("computeAllocations: pool not seeded (ΣW = 0)");
+  }
+  const allocations: bigint[] = wScaled.map((w) => (amountIn * w) / sumW);
+  const sumAlloc = allocations.reduce((a, b) => a + b, 0n);
+  if (sumAlloc < amountIn) {
+    allocations[tokenInIndex] += amountIn - sumAlloc;
+  }
+  return { allocations, wScaled, sumW };
+}
+
+function swapFeeAmount(amount: bigint, swapFeeRate: number): bigint {
+  return (amount * BigInt(swapFeeRate)) / BigInt(SWAP_FEE_PRECISION);
+}
+
+function amountAfterSwapFee(amount: bigint, swapFeeRate: number): bigint {
+  const fee = swapFeeAmount(amount, swapFeeRate);
+  if (swapFeeRate > 0 && fee === 0n) {
+    throw new Error("computeTwoTokenOptimalAllocations: swap amount too small, fee rounds to zero");
+  }
+  return amount - fee;
+}
+
+function protocolFeeAmount(swapFee: bigint, protocolFeeRate: number): bigint {
+  return (swapFee * BigInt(protocolFeeRate)) / BigInt(PROTOCOL_FEE_PRECISION);
+}
+
+function scoreTwoTokenSwap(params: {
+  actualBalances: [bigint, bigint];
+  virtualBalances: [bigint, bigint];
+  protocolFeesOwed: [bigint, bigint];
+  weightsBps: [number, number];
+  amountIn: bigint;
+  tokenInIndex: 0 | 1;
+  swapToOther: bigint;
+  swapFeeRate: number;
+  protocolFeeRate: number;
+}): { score: bigint; amountOut: bigint } {
+  const {
+    actualBalances,
+    virtualBalances,
+    protocolFeesOwed,
+    weightsBps,
+    amountIn,
+    tokenInIndex,
+    swapToOther,
+    swapFeeRate,
+    protocolFeeRate,
+  } = params;
+  const other = tokenInIndex === 0 ? 1 : 0;
+  const remainingInput = amountIn - swapToOther;
+  if (swapToOther <= 0n || remainingInput <= 0n) return { score: 0n, amountOut: 0n };
+
+  let afterFee: bigint;
+  try {
+    afterFee = amountAfterSwapFee(swapToOther, swapFeeRate);
+  } catch {
+    return { score: 0n, amountOut: 0n };
+  }
+  const swapFee = swapToOther - afterFee;
+  const protocolFee = protocolFeeAmount(swapFee, protocolFeeRate);
+
+  const inLp = lpBalances(
+    actualBalances[tokenInIndex],
+    virtualBalances[tokenInIndex],
+    protocolFeesOwed[tokenInIndex]
+  );
+  const outLp = lpBalances(
+    actualBalances[other],
+    virtualBalances[other],
+    protocolFeesOwed[other]
+  );
+
+  let amountOut: bigint;
+  try {
+    amountOut = calcOutGivenIn({
+      virtualBalanceIn: inLp.lpVirtual,
+      weightInBps: BigInt(weightsBps[tokenInIndex]),
+      virtualBalanceOut: outLp.lpVirtual,
+      weightOutBps: BigInt(weightsBps[other]),
+      amountIn: afterFee,
+      actualBalanceOut: outLp.lpActual,
+    });
+  } catch {
+    return { score: 0n, amountOut: 0n };
+  }
+  if (amountOut <= 0n || amountOut >= outLp.lpActual) return { score: 0n, amountOut };
+
+  const lpInAfter = inLp.lpActual + swapToOther - protocolFee;
+  const lpOutAfter = outLp.lpActual - amountOut;
+  if (lpInAfter <= 0n || lpOutAfter <= 0n) return { score: 0n, amountOut };
+
+  const ratioIn = (remainingInput * ONE) / lpInAfter;
+  const ratioOut = (amountOut * ONE) / lpOutAfter;
+  return { score: ratioIn < ratioOut ? ratioIn : ratioOut, amountOut };
+}
+
+export function computeTwoTokenOptimalAllocations(params: {
+  actualBalances: [bigint, bigint];
+  virtualBalances: [bigint, bigint];
+  protocolFeesOwed: [bigint, bigint];
+  weightsBps: [number, number];
+  amountIn: bigint;
+  tokenInIndex: 0 | 1;
+  swapFeeRate: number;
+  protocolFeeRate: number;
+}): AllocationResult {
+  const { amountIn, tokenInIndex } = params;
+  if (amountIn <= 1n) {
+    throw new Error("computeTwoTokenOptimalAllocations: amountIn too small");
+  }
+
+  let low = 1n;
+  let high = amountIn - 1n;
+  for (let i = 0; i < 32 && low < high; i++) {
+    const mid = low + (high - low) / 2n;
+    const current = scoreTwoTokenSwap({ ...params, swapToOther: mid }).score;
+    const next = scoreTwoTokenSwap({
+      ...params,
+      swapToOther: mid + 1n < amountIn ? mid + 1n : amountIn - 1n,
+    }).score;
+    if (next >= current) low = mid + 1n;
+    else high = mid;
+  }
+
+  const center = low < 1n ? 1n : low >= amountIn ? amountIn - 1n : low;
+  let bestSwap = center;
+  let bestScore = 0n;
+  const start = center > 8n ? center - 8n : 1n;
+  const end = center + 8n < amountIn ? center + 8n : amountIn - 1n;
+  for (let swapToOther = start; swapToOther <= end; swapToOther++) {
+    const { score, amountOut } = scoreTwoTokenSwap({ ...params, swapToOther });
+    if (amountOut > 0n && score > bestScore) {
+      bestScore = score;
+      bestSwap = swapToOther;
+    }
+  }
+  if (bestScore === 0n) {
+    throw new Error("computeTwoTokenOptimalAllocations: amount too small");
+  }
+
+  const allocations: [bigint, bigint] = [0n, 0n];
+  const other = tokenInIndex === 0 ? 1 : 0;
+  allocations[tokenInIndex] = amountIn - bestSwap;
+  allocations[other] = bestSwap;
+  return { allocations, wScaled: [], sumW: bestScore };
+}
+
+/**
+ * Mirror of stld `cap_deposit_amounts_to_lp_ratio`.
+ *
+ * `add_liquidity` mints BPT from the minimum ratio against LP-accessible
+ * balances (`actual - protocolFeesOwed`). Any helper-held amount above that
+ * common ratio would be donated, so the helper deposits the capped basket and
+ * refunds the rest.
+ */
+export function capDepositAmountsToLpRatio(params: {
+  helperBalances: bigint[];
+  actualBalances: bigint[];
+  protocolFeesOwed: bigint[];
+}): { depositAmounts: bigint[]; refundAmounts: bigint[]; lpBalancesForAdd: bigint[] } {
+  const { helperBalances, actualBalances, protocolFeesOwed } = params;
+  const n = helperBalances.length;
+  if (n !== actualBalances.length || n !== protocolFeesOwed.length) {
+    throw new Error("capDepositAmountsToLpRatio: length mismatch");
+  }
+
+  const lpBalancesForAdd = actualBalances.map((actual, i) =>
+    actual > protocolFeesOwed[i] ? actual - protocolFeesOwed[i] : 0n
+  );
+  let ratioMin: bigint | null = null;
+
+  for (let i = 0; i < n; i++) {
+    if (actualBalances[i] > 0n && lpBalancesForAdd[i] === 0n) {
+      throw new Error("capDepositAmountsToLpRatio: live token has no LP claim");
+    }
+    if (lpBalancesForAdd[i] === 0n) continue;
+    if (helperBalances[i] <= 0n) {
+      throw new Error("capDepositAmountsToLpRatio: amount too small");
+    }
+    const ratio = (helperBalances[i] * ONE) / lpBalancesForAdd[i];
+    ratioMin = ratioMin === null || ratio < ratioMin ? ratio : ratioMin;
+  }
+
+  if (ratioMin === null || ratioMin === 0n) {
+    throw new Error("capDepositAmountsToLpRatio: amount too small");
+  }
+
+  const depositAmounts = lpBalancesForAdd.map((lp, i) => {
+    if (lp === 0n) return 0n;
+    const amount = (lp * ratioMin!) / ONE;
+    if (amount <= 0n) {
+      throw new Error("capDepositAmountsToLpRatio: amount too small");
+    }
+    return amount > helperBalances[i] ? helperBalances[i] : amount;
+  });
+  const refundAmounts = helperBalances.map((balance, i) =>
+    balance > depositAmounts[i] ? balance - depositAmounts[i] : 0n
+  );
+
+  return { depositAmounts, refundAmounts, lpBalancesForAdd };
+}

package/src/math/slippage.ts

@@ -0,0 +1,49 @@
+import { SLIPPAGE_PRECISION, SWAP_FEE_PRECISION } from "../config";
+
+/**
+ * min_out = expected * (SLIPPAGE_PRECISION - slippage_hbps) / SLIPPAGE_PRECISION.
+ * Matches `apply_slippage` in stld's math.rs.
+ */
+export function applySlippage(expected: bigint, slippageHbps: number): bigint {
+  if (slippageHbps < 0 || slippageHbps > SLIPPAGE_PRECISION) {
+    throw new Error(`slippage: ${slippageHbps} out of [0, ${SLIPPAGE_PRECISION}]`);
+  }
+  const keep = BigInt(SLIPPAGE_PRECISION - slippageHbps);
+  return (expected * keep) / BigInt(SLIPPAGE_PRECISION);
+}
+
+/**
+ * fee = amount * rate / SWAP_FEE_PRECISION. Returns amount - fee.
+ * Matches `apply_swap_fee`.
+ */
+export function applySwapFee(amount: bigint, swapFeeRate: number): bigint {
+  if (swapFeeRate < 0) throw new Error("swapFee: negative rate");
+  const fee = (amount * BigInt(swapFeeRate)) / BigInt(SWAP_FEE_PRECISION);
+  if (swapFeeRate > 0 && fee === 0n) {
+    throw new Error("swapFee: amount too small, fee rounds to zero");
+  }
+  return amount - fee;
+}
+
+/**
+ * LP-accessible balances: lp_actual = actual - pfo; lp_virtual scaled to
+ * match. Used by the off-chain single-token quote in `math/singleToken`.
+ */
+export function lpBalances(actual: bigint, virtualBal: bigint, pfo: bigint): { lpActual: bigint; lpVirtual: bigint } {
+  const lpActual = actual >= pfo ? actual - pfo : 0n;
+  const lpVirtual =
+    actual > 0n ? (virtualBal * lpActual) / actual : virtualBal;
+  return { lpActual, lpVirtual };
+}
+
+/**
+ * Price impact in hundredths of basis point: (spot - actual) / spot × 1_000_000.
+ * 0 if spot is 0.
+ */
+export function priceImpactHbps(spot: bigint, actual: bigint): number {
+  if (spot <= 0n) return 0;
+  if (actual >= spot) return 0;
+  const diff = spot - actual;
+  const hbps = (diff * BigInt(SLIPPAGE_PRECISION)) / spot;
+  return Number(hbps);
+}