@coffer_so/sdk 1.0.0

package/src/index.ts

@@ -0,0 +1,262 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Endgame AMM DEX Foundation.
+// See LICENSE at the repository root.
+
+/**
+ * @coffer_so/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, CofferBackendClient, getConfig } from "@coffer_so/sdk";
+ *
+ * const cfg = getConfig("mainnet", { backendEndpoint: "https://api.coffer.so" });
+ * const pool = new CubicPoolClient({ config: cfg, poolAddress });
+ * 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,
+  PERCENT_SCALE,
+  MAX_SWAP_FEE_RATE,
+  MAX_PROTOCOL_FEE_RATE,
+  MINIMUM_INITIAL_BPT,
+  SLIPPAGE_PRECISION,
+  MIN_SLIPPAGE_HBPS,
+} from "./config";
+export {
+  NETWORK_PROGRAMS,
+  DEFAULT_RPC_ENDPOINT,
+  DEFAULT_RPC_ENDPOINTS,
+  DEFAULT_RPC_TIMEOUT_MS,
+} 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 {
+  computeSelloffWindow,
+  projectSelloffWindow,
+  calcSurgeFeePct,
+  calcSurgeFeeAmount,
+  calcSegmentedSurgeFeeAmount,
+  SURGE_FEE_SEGMENTS,
+} from "./math/maxSelloff";
+export { RpcClient } from "./clients/RpcClient";
+export { CofferBackendClient } from "./clients/CofferBackendClient";
+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,
+  buildSingleTokenDepositTxs,
+  buildSingleTokenDepositAtaIxs,
+  buildInitializeConfigIx,
+  buildPoolInitializeConfigIx,
+  buildInitializeCubicPoolIx,
+  buildDeployPoolTx,
+  buildInitializePoolAltIx,
+  buildInitializePoolAltTx,
+  buildSetRangeManagerIx,
+  buildSetRangeManagerConfigIx,
+  buildRangeManagerUpdateIx,
+  deriveAltAddress,
+  STLD_MAX_TOKENS,
+  STLD_DEPOSIT_CU_LIMIT,
+} from "./clients/tx-builders";
+export { buildVersionedTx, compileBuiltTx } from "./clients/versioned";
+export type { InitializePoolAltParams } from "./clients/tx-builders";
+export { decodePoolAccount, POOL_DISCRIMINATOR_LEN, POOL_LEN, POOL_V4_LEN } from "./parsers/poolAccount";
+export { toSdkError, describeProgramError } from "./utils/errors";
+export { decodeMintAccount } from "./parsers/mintAccount";
+export { parseCubicPoolEvents } from "./parsers/events";
+export { BorshReader } from "./parsers/borsh";
+
+export type {
+  CofferConfig,
+  CofferConfigOverrides,
+  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,
+  PoolStateLogEvent,
+  MaxSelloffWindowAdvancedEvent,
+  BannedExtensionsUpdatedEvent,
+  UnknownEvent,
+  TokenChange,
+  RangeManagerUpdateParams,
+  SetRangeManagerParams,
+  SetRangeManagerConfigParams,
+} from "./types";
+export type { CofferProgram } from "./utils/errors";
+export type {
+  AllocationResult,
+} from "./math/singleToken";
+export type {
+  SelloffWindowInputs,
+  SelloffWindowStatus,
+  WindowProjection,
+} from "./math/maxSelloff";
+export type {
+  RawPoolAccount,
+  RawMintAccount,
+} from "./parsers";
+export type {
+  RpcClientParams,
+  CofferBackendClientParams,
+  StatsKind,
+  StatsWindow,
+  StatsSeriesPoint,
+  StatsSeries,
+  PriceMap,
+  LeaderboardEntry,
+  LeaderboardResponse,
+  LeaderboardUserStats,
+  XpAccrualHistoryEntry,
+  XpAccrualHistoryResponse,
+  EpochHistoryEntry,
+  LeaderboardEpochResponse,
+  CampaignStatusResponse,
+  CampaignInfoResponse,
+  CampaignPrizeTier,
+  CampaignRankResponse,
+  CampaignTopEntry,
+  CampaignTopResponse,
+  PortfolioChartMetric,
+  PortfolioChartRange,
+  PortfolioChartResponse,
+  PairChartRange,
+  TokenPairChartResponse,
+  PortfolioActivityType,
+  PortfolioActivityFilter,
+  ActivityTokenInfo,
+  PortfolioActivityItem,
+  PortfolioActivityResponse,
+  SortOrder,
+  PortfolioActivitySortField,
+  PortfolioHoldingsSortField,
+  PortfolioHoldingItem,
+  PortfolioHoldingsResponse,
+  PortfolioPositionsSortField,
+  PortfolioPositionItem,
+  PortfolioPositionsResponse,
+  NonceResponse,
+  TxChallengeResponse,
+  AuthTokens,
+  SwapRouteEntry,
+  SwapRouteResponse,
+  CubicPoolClientParams,
+  SingleTokenDepositClientParams,
+  PoolFactoryClientParams,
+  InitializeConfigParams,
+} from "./clients";
+
+export { buildContractInstruction } from "./clients/contract-instructions";
+export { decodeContractAccount, decodeContractEvent, parseContractEvents } from "./parsers/contracts";
+export type { ContractEvent } from "./parsers/contracts";
+export type { ContractInstructionArgs, ContractInstructionAccounts } from "./clients/contract-instructions";
+export type { ContractProgram, ContractInstructionMap, ContractAccountMap, ContractEventMap, ContractTypes } from "./types/contracts";
+export { buildSetSwapFeeRateIx, buildSetMaxSelloffIx, buildInitiatePoolAdminTransferIx, buildAcceptPoolAdminTransferIx, buildCancelPoolAdminTransferIx, buildDisablePoolAdminIx, buildGetPoolInfoIx } from "./clients/tx-builders";
+export type { SelloffParams, AddLiquidityQuote } from "./types/tx";
+export { calculateSwapFee, calculateProtocolFee } from "./math/slippage";
+export { checkAndAdvanceSelloff, rescaleSelloffWindow } from "./math/maxSelloff";
+export type { SelloffState, SelloffResult } from "./math/maxSelloff";
+export type { SurgeCurve } from "./math/surgeFee";
+export { calculateInvariant } from "./math/weightedMath";
+
+export { MintExtension, MAX_KNOWN_MINT_EXTENSION, HARD_UNSUPPORTED_MINT_EXTENSIONS, DEFAULT_BANNED_EXTENSIONS, mintExtensionName, parseMintExtensions, unsupportedMintExtensions, bannedMintExtensions, describeUnsupportedToken, assertTokensSupported } from "./utils/extensions";
+
+// ── Legacy aliases (pre-rebrand identifiers) ────────────────────────────
+// The package was renamed @cubee_ee/sdk → @coffer_so/sdk. These aliases
+// keep old import names compiling so migration is just a package-name
+// swap. New code should use the Coffer* names.
+/** @deprecated Use `CofferBackendClient`. */
+export { CofferBackendClient as CubeBackendClient } from "./clients/CofferBackendClient";
+/** @deprecated Use `CofferConfig` / `CofferConfigOverrides`. */
+export type {
+  CofferConfig as CubeConfig,
+  CofferConfigOverrides as CubeConfigOverrides,
+} from "./config";
+/** @deprecated Use `CofferProgram`. */
+export type { CofferProgram as CubeProgram } from "./utils/errors";
+/** @deprecated Use `CofferBackendClientParams`. */
+export type { CofferBackendClientParams as CubeBackendClientParams } from "./clients";

package/src/math/cubicMath.ts

@@ -0,0 +1,92 @@
+import { complement, divDown, divUp, mulDown, ONE, weightToFp, assertU64, assertU128 } 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;
+  [virtualBalanceIn, weightInBps, virtualBalanceOut, weightOutBps, amountIn, actualBalanceOut].forEach((v) => assertU64(v));
+  const denom = assertU128(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 assertU64(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");
+  }
+  assertU64(bptTotalSupply); actualBalances.forEach((v) => assertU64(v)); amountsIn.forEach((v) => assertU64(v));
+  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 assertU64(assertU128(bptTotalSupply * ratioMin) / ONE);
+}
+
+/**
+ * Port of `CubicMath::calc_tokens_out_given_bpt_in`. Proportional exit.
+ */
+export function calcTokensOutGivenBptIn(
+  actualBalances: bigint[],
+  bptAmount: bigint,
+  bptTotalSupply: bigint
+): bigint[] {
+  assertU64(bptAmount); assertU64(bptTotalSupply); actualBalances.forEach((v) => assertU64(v));
+  if (bptTotalSupply === 0n) throw new Error("cubicMath: zero total supply");
+  const ratio = divDown(bptAmount, bptTotalSupply);
+  return actualBalances.map((bal) => assertU64(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,71 @@
+/** Fixed-point primitives matching cubic-pool's checked u128 operations. */
+export const ONE = 1000000000000000000n;
+export const U64_MAX = (1n << 64n) - 1n;
+export const U128_MAX = (1n << 128n) - 1n;
+export const I128_MIN = -(1n << 127n);
+export const I128_MAX = (1n << 127n) - 1n;
+export function assertU64(value: bigint, label = "value"): bigint {
+    if (value < 0n || value > U64_MAX)
+        throw new Error(`${label}: outside u64`);
+    return value;
+}
+export function assertU128(value: bigint, label = "value"): bigint {
+    if (value < 0n || value > U128_MAX)
+        throw new Error(`${label}: outside u128`);
+    return value;
+}
+export function assertI128(value: bigint, label = "value"): bigint {
+    if (value < I128_MIN || value > I128_MAX)
+        throw new Error(`${label}: outside i128`);
+    return value;
+}
+export function assertInteger(value: number, min: number, max: number, label: string): number {
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        throw new Error(`${label}: invalid integer`);
+    return value;
+}
+/** Rust mul_div_down permits a 256-bit product, but a u128 quotient. */
+export function mulDivDown(a: bigint, b: bigint, denominator: bigint): bigint {
+    assertU128(a);
+    assertU128(b);
+    assertU128(denominator);
+    if (denominator === 0n)
+        throw new Error("mulDivDown: divide by zero");
+    return assertU128(a * b / denominator);
+}
+export function mulDown(a: bigint, b: bigint): bigint {
+    assertU128(a);
+    assertU128(b);
+    return assertU128(a * b) / ONE;
+}
+export function mulUp(a: bigint, b: bigint): bigint {
+    assertU128(a);
+    assertU128(b);
+    const product = assertU128(a * b);
+    return product === 0n ? 0n : (product - 1n) / ONE + 1n;
+}
+export function divDown(a: bigint, b: bigint): bigint {
+    assertU128(a);
+    assertU128(b);
+    if (b === 0n)
+        throw new Error("fixedPoint.divDown: divide by zero");
+    return assertU128(a * ONE) / b;
+}
+export function divUp(a: bigint, b: bigint): bigint {
+    assertU128(a);
+    assertU128(b);
+    if (b === 0n)
+        throw new Error("fixedPoint.divUp: divide by zero");
+    const numerator = assertU128(a * ONE);
+    return numerator === 0n ? 0n : (numerator - 1n) / b + 1n;
+}
+export function complement(x: bigint): bigint {
+    assertU128(x);
+    if (x > ONE)
+        throw new Error("fixedPoint.complement: greater than ONE");
+    return ONE - x;
+}
+export function weightToFp(weightBps: bigint | number): bigint {
+    const w = typeof weightBps === "number" ? BigInt(assertInteger(weightBps, 0, 10000, "weight")) : assertU64(weightBps);
+    return w * ONE / 10000n;
+}

package/src/math/index.ts

@@ -0,0 +1,13 @@
+export * from "./fixedPoint";
+export * from "./logExp";
+export * from "./cubicMath";
+export * from "./weightedMath";
+export * from "./singleToken";
+export * from "./slippage";
+export * from "./maxSelloff";
+export * from "./lpLoss";
+// NOTE: "./surgeFee" is deliberately NOT star-exported — its
+// calcSurgeFeePct/calcSurgeFeeAmount would shadow the same-named maxSelloff
+// exports (an ambiguous star re-export silently drops the name, breaking
+// existing consumers). The quote engine imports it by path; only the
+// SurgeCurve type is re-exported from the package root.

package/src/math/logExp.ts

@@ -0,0 +1,61 @@
+/** Exact integer port of cubic-pool log_exp_math.rs (audit-fixes-excluded-SF). */
+import { ONE, assertI128, assertU128, mulDivDown } from "./fixedPoint";
+export const MAX_NATURAL_EXPONENT = 46000000000000000000n;
+export const MIN_NATURAL_EXPONENT = -41000000000000000000n;
+const X = [32000000000000000000n, 16000000000000000000n, 8000000000000000000n, 4000000000000000000n, 2000000000000000000n, 1000000000000000000n, 500000000000000000n, 250000000000000000n, 125000000000000000n, 62500000000000000n];
+const A = [78962960182680695161000000000000n, 8886110520507872636760000n, 2980957987041728274740n, 54598150033144239078n, 7389056098930650227n, 2718281828459045235n, 1648721270700128146n, 1284025416687741484n, 1133148453066826316n, 1064494458917859429n];
+function lnPositive(a: bigint): bigint {
+    let sum = 0n;
+    for (let i = 0; i < X.length; i++)
+        if (a >= A[i]) {
+            a = mulDivDown(a, ONE, A[i]);
+            sum += X[i];
+        }
+    const z = mulDivDown(a - ONE, ONE, assertU128(a + ONE));
+    const zSq = assertI128(z * z) / ONE;
+    let num = z, seriesSum = z;
+    for (let k = 1n; k < 6n; k++) {
+        num = assertI128(num * zSq) / ONE;
+        seriesSum = assertI128(seriesSum + num / (2n * k + 1n));
+    }
+    return assertI128(sum + assertI128(seriesSum * 2n));
+}
+export function lnFp(a: bigint): bigint {
+    assertU128(a);
+    if (a === 0n)
+        throw new Error("logExp.ln: divide by zero");
+    return a < ONE ? -lnPositive(mulDivDown(ONE, ONE, a)) : lnPositive(a);
+}
+export function expFp(x: bigint): bigint {
+    assertI128(x);
+    if (x < MIN_NATURAL_EXPONENT || x > MAX_NATURAL_EXPONENT)
+        throw new Error("logExp.exp: exponent out of range");
+    if (x < 0n)
+        return mulDivDown(ONE, ONE, expFp(-x));
+    let product = ONE;
+    for (let i = 0; i < X.length; i++)
+        if (x >= X[i]) {
+            x -= X[i];
+            product = mulDivDown(product, A[i], ONE);
+        }
+    let sum = assertU128(ONE + x), term = x;
+    for (let n = 2n; n <= 12n; n++) {
+        term = mulDivDown(term, x, ONE) / n;
+        sum = assertU128(sum + term);
+    }
+    return mulDivDown(product, sum, ONE);
+}
+export function powFp(base: bigint, exponent: bigint): bigint {
+    assertU128(base);
+    assertU128(exponent);
+    if (exponent === 0n || base === ONE)
+        return ONE;
+    if (base === 0n)
+        return 0n;
+    const logarithm = lnFp(base);
+    // Rust casts u128 to i128 here. Valid pool weights are far below i128::MAX.
+    const y = BigInt.asIntN(128, exponent);
+    const whole = assertI128((logarithm / ONE) * y);
+    const fraction = assertI128((logarithm % ONE) * y) / ONE;
+    return expFp(assertI128(whole + fraction));
+}

package/src/math/lpLoss.ts

@@ -0,0 +1,160 @@
+import {
+  PROTOCOL_FEE_PRECISION,
+  SWAP_FEE_PRECISION,
+  WEIGHT_SCALE,
+} from "../config";
+
+export interface PredictLpLossParams {
+  /** Normalized weights in bps (sum = WEIGHT_SCALE). */
+  weightsBps: number[];
+  virtualBalances: bigint[];
+  /** LP-accessible balances: actual − protocolFeesOwed. */
+  lpActualBalances: bigint[];
+  decimals: number[];
+  bptTotalSupply: bigint;
+  swapFeeRate: number;
+  protocolFeeRate: number;
+  tokenInIndex: number;
+  amountIn: bigint;
+  /** Per-token input allocations from the quote (sum = amountIn). */
+  allocations: bigint[];
+  /** Per-leg expected swap outputs (0 for the input token / sidelined). */
+  expectedOuts: bigint[];
+  /** Amounts passed to add_liquidity after proportional capping. */
+  depositedAmounts: bigint[];
+  /** Helper-held excess refunded to the user. */
+  refundAmounts: bigint[];
+  estimatedBpt: bigint;
+  /**
+   * External per-token prices in any common unit. When omitted or incomplete
+   * the pool-spot-implied prices (w_i / V_i) are used instead.
+   */
+  prices?: Array<number | null | undefined>;
+}
+
+const toWhole = (raw: bigint, decimals: number): number =>
+  Number(raw) / 10 ** decimals;
+
+/**
+ * Predicted total value loss of the LP position minted by a single-token
+ * deposit, as a percent of the deposited value, measured AFTER arbitrageurs
+ * rebalance the pool back to external prices — the slippage-proof cost the
+ * depositor actually bears.
+ *
+ * Replays the quote's swap legs and join onto the pool state, then values
+ * the position at the closed-form zero-fee-arb equilibrium: with the
+ * invariant ∏V_i^w_i preserved, equilibrium virtuals are V'_i = λ·w_i/p_i
+ * and actual balances move by the same deltas. Validated against a full
+ * profit-maximizing arbitrage simulation of the contract math (±0.03 pp,
+ * slightly conservative). Float math — ample for percent-level output.
+ *
+ * Returns `null` when the pool is empty or inputs cannot price.
+ */
+export function predictLpLoss(params: PredictLpLossParams): number | null {
+  const {
+    weightsBps,
+    virtualBalances,
+    lpActualBalances,
+    decimals,
+    bptTotalSupply,
+    swapFeeRate,
+    protocolFeeRate,
+    tokenInIndex,
+    amountIn,
+    allocations,
+    expectedOuts,
+    depositedAmounts,
+    refundAmounts,
+    estimatedBpt,
+    prices: externalPrices,
+  } = params;
+
+  const n = weightsBps.length;
+  if (
+    virtualBalances.length !== n ||
+    lpActualBalances.length !== n ||
+    decimals.length !== n
+  ) {
+    throw new Error("predictLpLoss: length mismatch");
+  }
+  if (tokenInIndex < 0 || tokenInIndex >= n) {
+    throw new Error("predictLpLoss: tokenInIndex out of range");
+  }
+
+  const supply = Number(bptTotalSupply);
+  const estBpt = Number(estimatedBpt);
+  const amountInWhole = toWhole(amountIn, decimals[tokenInIndex]);
+  if (supply <= 0 || estBpt <= 0 || amountInWhole <= 0) return null;
+
+  const weights: number[] = [];
+  const virtuals: number[] = [];
+  const actuals: number[] = [];
+  for (let i = 0; i < n; i++) {
+    weights.push(weightsBps[i] / WEIGHT_SCALE);
+    virtuals.push(toWhole(virtualBalances[i], decimals[i]));
+    actuals.push(toWhole(lpActualBalances[i], decimals[i]));
+  }
+
+  const externalComplete =
+    externalPrices !== undefined &&
+    externalPrices.length === n &&
+    externalPrices.every((p) => typeof p === "number" && p > 0);
+  const prices: number[] = [];
+  for (let i = 0; i < n; i++) {
+    const price = externalComplete
+      ? (externalPrices![i] as number)
+      : weights[i] / virtuals[i];
+    if (!Number.isFinite(price) || price <= 0) return null;
+    prices.push(price);
+  }
+
+  const feeRate = swapFeeRate / SWAP_FEE_PRECISION;
+  const protoRate = protocolFeeRate / PROTOCOL_FEE_PRECISION;
+  for (let i = 0; i < n; i++) {
+    if (i === tokenInIndex) continue;
+    const alloc = toWhole(allocations[i] ?? 0n, decimals[tokenInIndex]);
+    const out = toWhole(expectedOuts[i] ?? 0n, decimals[i]);
+    if (alloc <= 0 || out <= 0) continue;
+    const protoFee = alloc * feeRate * protoRate;
+    virtuals[tokenInIndex] += alloc - protoFee;
+    actuals[tokenInIndex] += alloc - protoFee;
+    virtuals[i] -= out;
+    actuals[i] -= out;
+  }
+
+  const mintRatio = estBpt / supply;
+  for (let i = 0; i < n; i++) {
+    actuals[i] += toWhole(depositedAmounts[i] ?? 0n, decimals[i]);
+    virtuals[i] *= 1 + mintRatio;
+  }
+
+  let logInvariant = 0;
+  let logTarget = 0;
+  for (let i = 0; i < n; i++) {
+    if (weights[i] <= 0 || virtuals[i] <= 0) return null;
+    logInvariant += weights[i] * Math.log(virtuals[i]);
+    logTarget += weights[i] * Math.log(weights[i] / prices[i]);
+  }
+  const lambda = Math.exp(logInvariant - logTarget);
+
+  let equilibriumPoolValue = 0;
+  for (let i = 0; i < n; i++) {
+    const equilibriumVirtual = (lambda * weights[i]) / prices[i];
+    const equilibriumActual = Math.max(
+      0,
+      actuals[i] - (virtuals[i] - equilibriumVirtual)
+    );
+    equilibriumPoolValue += equilibriumActual * prices[i];
+  }
+
+  const lpValue = (mintRatio / (1 + mintRatio)) * equilibriumPoolValue;
+  let refundValue = 0;
+  for (let i = 0; i < n; i++) {
+    refundValue += toWhole(refundAmounts[i] ?? 0n, decimals[i]) * prices[i];
+  }
+  const depositValue = amountInWhole * prices[tokenInIndex];
+  if (depositValue <= 0) return null;
+
+  const loss = 1 - (lpValue + refundValue) / depositValue;
+  return Math.min(100, Math.max(0, loss * 100));
+}