@shogun-sdk/intents-sdk 1.3.0 → 1.4.1

package/src/utils/quote/pricing/constants.ts

@@ -0,0 +1,33 @@
+import { ChainID } from '../../../chains.js';
+
+/**
+ * Solver commission in basis points. MUST equal the solver's COMMISSION env value
+ * (solver/src/config.rs). Update both together to avoid quote divergence.
+ */
+export const DEFAULT_COMMISSION_BPS = 50n; // 0.5% — placeholder, confirm against solver COMMISSION
+
+/** Single-chain divisor — mirrors evaluate.rs:130-131 (`commission / 10_000`). */
+export const SINGLE_CHAIN_COMMISSION_DENOMINATOR = 10_000n;
+
+/**
+ * Cross-chain divisor — mirrors cross_chain_estimation.rs:213-214 (`commission / 100_000`).
+ * The asymmetry with the single-chain divisor is intentional (verbatim solver mirror);
+ * confirm with the solver team whether this is a unit choice or a bug before relying on it.
+ */
+export const CROSS_CHAIN_COMMISSION_DENOMINATOR = 100_000n;
+
+/** EVM fulfillment gas units — mirrors solver/src/constants/chains.rs (EVM single-chain). */
+export const EVM_SINGLE_CHAIN_GAS_LIMIT = 3_000_000n;
+
+/** EVM cross-chain fulfillment gas units — mirrors solver/src/constants/chains.rs (EVM cross-chain). */
+export const EVM_CROSS_CHAIN_GAS_LIMIT = 2_000_000n;
+
+/**
+ * Fixed native-token gas cost for non-EVM chains, in the chain's smallest unit.
+ * Mirrors solver/src/constants/chains.rs: Sui = 20_000_000 MIST; Solana base = 200_000 lamports
+ * (single-receiver default; per-receiver ATA cost is not modeled at quote time).
+ */
+export const NON_EVM_FIXED_NATIVE_GAS_COST: Partial<Record<ChainID, bigint>> = {
+  [ChainID.Sui]: 20_000_000n,
+  [ChainID.Solana]: 200_000n,
+};

package/src/utils/quote/pricing/decimals.ts

@@ -0,0 +1,11 @@
+/**
+ * Integer decimal conversion between two tokens, mirroring solver cross_chain_estimation.rs:205-211.
+ * Uses BigInt powers of ten to avoid the float precision loss of `Math.floor(Number(...))`.
+ */
+export function convertDecimals(amount: bigint, fromDecimals: number, toDecimals: number): bigint {
+  const diff = toDecimals - fromDecimals;
+  if (diff >= 0) {
+    return amount * 10n ** BigInt(diff);
+  }
+  return amount / 10n ** BigInt(-diff);
+}

package/src/utils/quote/pricing/estimate-amount-out.ts

@@ -0,0 +1,36 @@
+/** Expense components, all expressed in the output token's smallest units. */
+export type Expenses = {
+  gasInTokenOut: bigint;
+  protocolFeeInTokenOut: bigint;
+  extraTransfersInTokenOut: bigint;
+};
+
+/** Thrown when total expenses meet or exceed the swap output, mirroring the solver's rejection. */
+export class IntentNotViableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'IntentNotViableError';
+  }
+}
+
+/**
+ * Ports solver_rust evaluate.rs: final amount = swapOutput − expenses − commission.
+ * `commissionBps` is basis points; `commissionDenominator` selects single-chain (10_000n)
+ * vs cross-chain (100_000n) semantics. Throws IntentNotViableError when nothing is left.
+ */
+export function estimateAmountOut(
+  swapOutput: bigint,
+  commissionBps: bigint,
+  expenses: Expenses,
+  commissionDenominator = 10_000n,
+): bigint {
+  const commissionFee = (swapOutput * commissionBps) / commissionDenominator;
+  const total =
+    expenses.gasInTokenOut + expenses.protocolFeeInTokenOut + expenses.extraTransfersInTokenOut + commissionFee;
+
+  if (total >= swapOutput) {
+    throw new IntentNotViableError(`Total expenses (${total}) meet or exceed swap output (${swapOutput})`);
+  }
+
+  return swapOutput - total;
+}

package/src/utils/quote/pricing/expenses.ts

@@ -0,0 +1,62 @@
+import { ChainID, type SupportedChain } from '../../../chains.js';
+import {
+  NATIVE_EVM_ETH_ADDRESSES,
+  NATIVE_SOLANA_TOKEN_ADDRESS,
+  NATIVE_SUI_TOKEN_ADDRESS,
+  isNativeEvmToken,
+} from '../../../constants.js';
+import { compareAddresses } from '../address.js';
+import type { Expenses } from './estimate-amount-out.js';
+import { getNativeGasCost } from './gas.js';
+
+/** Quotes a native->tokenOut swap on the given chain. Injected to keep this module a leaf (no dependency on the aggregator). */
+type GasQuoteFn = (params: {
+  chainId: SupportedChain;
+  amount: bigint;
+  tokenIn: string;
+  tokenOut: string;
+}) => Promise<{ amountOut: bigint }>;
+
+function nativeTokenAddressForChain(chainId: SupportedChain): string {
+  if (chainId === ChainID.Solana) return NATIVE_SOLANA_TOKEN_ADDRESS;
+  if (chainId === ChainID.Sui) return NATIVE_SUI_TOKEN_ADDRESS;
+  // EVM native sentinel addresses share the same 0xEee... value; use the first.
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  return NATIVE_EVM_ETH_ADDRESSES[0]!;
+}
+
+function isNativeToken(chainId: SupportedChain, address: string): boolean {
+  if (chainId === ChainID.Solana) return compareAddresses(address, NATIVE_SOLANA_TOKEN_ADDRESS);
+  if (chainId === ChainID.Sui) return compareAddresses(address, NATIVE_SUI_TOKEN_ADDRESS);
+  return isNativeEvmToken(address);
+}
+
+/**
+ * Builds the Expenses bundle in the output token. Gas is fetched in native units and
+ * swapped into tokenOut via the injected quote fn, mirroring how the solver converts
+ * expenses into the output token. protocolFee/extraTransfers are reserved (0n) for now.
+ */
+export async function estimateExpensesInTokenOut(params: {
+  chainId: SupportedChain;
+  tokenOut: string;
+  gasLimit: bigint;
+  getQuote: GasQuoteFn;
+  rpcProviderUrl?: string;
+}): Promise<Expenses> {
+  const { chainId, tokenOut, gasLimit, getQuote, rpcProviderUrl } = params;
+
+  const nativeGasCost = await getNativeGasCost({ chainId, gasLimit, rpcProviderUrl });
+
+  const gasInTokenOut = isNativeToken(chainId, tokenOut)
+    ? nativeGasCost
+    : (
+        await getQuote({
+          chainId,
+          amount: nativeGasCost,
+          tokenIn: nativeTokenAddressForChain(chainId),
+          tokenOut,
+        })
+      ).amountOut;
+
+  return { gasInTokenOut, protocolFeeInTokenOut: 0n, extraTransfersInTokenOut: 0n };
+}

package/src/utils/quote/pricing/gas.ts

@@ -0,0 +1,28 @@
+import { getGasPrice } from 'viem/actions';
+import { isEvmChain, type SupportedChain } from '../../../chains.js';
+import { ChainProvider } from '../../../core/evm/chain-provider.js';
+import { NON_EVM_FIXED_NATIVE_GAS_COST } from './constants.js';
+
+/**
+ * Gas cost in the chain's native smallest unit (wei / lamports / MIST).
+ * EVM: live gas price × gas limit. Non-EVM: solver-mirrored fixed cost.
+ */
+export async function getNativeGasCost(params: {
+  chainId: SupportedChain;
+  gasLimit: bigint;
+  rpcProviderUrl?: string;
+}): Promise<bigint> {
+  const { chainId, gasLimit, rpcProviderUrl } = params;
+
+  if (isEvmChain(chainId)) {
+    const client = ChainProvider.getClient(chainId, rpcProviderUrl);
+    const gasPrice = await getGasPrice(client);
+    return gasLimit * gasPrice;
+  }
+
+  const fixed = NON_EVM_FIXED_NATIVE_GAS_COST[chainId];
+  if (fixed === undefined) {
+    throw new Error(`No fixed native gas cost configured for chain ${chainId}`);
+  }
+  return fixed;
+}

package/src/utils/quote/pumpfun/estimations.ts

@@ -0,0 +1,206 @@
+import type { BondingCurve, GlobalAccount } from './models.js';
+
+export const BPS_DEN = 10000n;
+
+export enum PreBondedTradeType {
+  BuyExactIn = 'BuyExactIn',
+  BuyExactOut = 'BuyExactOut',
+  SellExactIn = 'SellExactIn',
+  SellExactOut = 'SellExactOut',
+}
+
+class PreBondingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PreBondingError';
+  }
+}
+
+/**
+ * Calculate output amount for constant product AMM: (amount_in * y_out) / (x_in + amount_in)
+ */
+function cpAmountOut(amountIn: bigint, xIn: bigint, yOut: bigint): bigint {
+  if (xIn === 0n || yOut === 0n) {
+    throw new PreBondingError('Zero value for reserve');
+  }
+
+  const num = amountIn * yOut;
+  const den = xIn + amountIn;
+
+  return num / den;
+}
+
+/**
+ * Buy exact SOL in, get tokens out.
+ * Fee is deducted from SOL before the swap calculation.
+ */
+export function buyExactIn(curve: BondingCurve, solIn: bigint, feeBps: bigint): bigint {
+  if (curve.complete) {
+    throw new PreBondingError(`Pool not in fundraising state: ${JSON.stringify(curve)}`);
+  }
+  if (solIn === 0n) {
+    return 0n;
+  }
+
+  const vSol = curve.virtualSolReserves;
+  const vTok = curve.virtualTokenReserves;
+
+  // Deduct protocol + creator fee from input SOL
+  const fee = (solIn * feeBps) / BPS_DEN;
+  const effectiveSolIn = solIn - fee;
+
+  let out = cpAmountOut(effectiveSolIn, vSol, vTok);
+
+  // Observed rounding in buy path (+1)
+  out = out + 1n;
+
+  // Cap by real tokens available
+  return out < curve.realTokenReserves ? out : curve.realTokenReserves;
+}
+
+/**
+ * Sell exact tokens in, get SOL out.
+ * Fee is deducted from SOL output.
+ */
+export function sellExactIn(curve: BondingCurve, tokensIn: bigint, feeBps: bigint): bigint {
+  if (curve.complete) {
+    throw new PreBondingError(`Pool not in fundraising state: ${JSON.stringify(curve)}`);
+  }
+  if (tokensIn === 0n) {
+    return 0n;
+  }
+
+  const vTok = curve.virtualTokenReserves;
+  const vSol = curve.virtualSolReserves;
+
+  const gross = cpAmountOut(tokensIn, vTok, vSol);
+
+  // Deduct protocol + creator fee from output SOL
+  const fee = (gross * feeBps) / BPS_DEN;
+  let net = gross - fee;
+
+  // Cap by real SOL available
+  net = net < curve.realSolReserves ? net : curve.realSolReserves;
+
+  return net;
+}
+
+/**
+ * Buy exact tokens out, calculate required SOL in.
+ * This calculates the EXACT amount needed, but doesn't account for slippage buffer.
+ */
+export function buyExactOut(curve: BondingCurve, tokensOut: bigint, feeBps: bigint): bigint {
+  if (curve.complete) {
+    throw new PreBondingError(`Pool not in fundraising state: ${JSON.stringify(curve)}`);
+  }
+  if (tokensOut === 0n) {
+    return 0n;
+  }
+  if (tokensOut > curve.realTokenReserves) {
+    throw new PreBondingError('Insufficient liquidity: real_token cap');
+  }
+
+  const vSol = curve.virtualSolReserves;
+  const vTok = curve.virtualTokenReserves;
+
+  if (tokensOut >= vTok) {
+    throw new PreBondingError('Insufficient liquidity: tokens_out >= v_tok');
+  }
+
+  // Calculate effective SOL needed before fees: ceil((vSol * tokensOut) / (vTok - tokensOut))
+  const num = vSol * tokensOut;
+  const den = vTok - tokensOut;
+  const effIn = (num + den - 1n) / den; // ceiling division
+
+  const feeNum = BPS_DEN - feeBps;
+  if (feeNum === 0n) {
+    throw new PreBondingError('Invalid fee configuration');
+  }
+
+  // Calculate gross SOL including fees: ceil((effIn * BPS_DEN) / feeNum)
+  const grossIn = (effIn * BPS_DEN + feeNum - 1n) / feeNum;
+
+  return grossIn;
+}
+
+/**
+ * Sell exact SOL out, calculate required tokens in.
+ * This calculates the EXACT amount needed, but doesn't account for slippage buffer.
+ */
+export function sellExactOut(curve: BondingCurve, solOut: bigint, feeBps: bigint): bigint {
+  if (curve.complete) {
+    throw new PreBondingError(`Pool not in fundraising state: ${JSON.stringify(curve)}`);
+  }
+  if (solOut === 0n) {
+    return 0n;
+  }
+  if (solOut > curve.realSolReserves) {
+    throw new PreBondingError('Insufficient liquidity: real_sol cap');
+  }
+
+  const vTok = curve.virtualTokenReserves;
+  const vSol = curve.virtualSolReserves;
+
+  // fee_num = BPS_DEN - fee_bps
+  const feeNum = BPS_DEN - feeBps;
+  if (feeNum === 0n) {
+    throw new PreBondingError('Invalid fee configuration');
+  }
+
+  // Upper bound via continuous formula: gross = ceil((solOut * BPS_DEN) / feeNum)
+  const gross = (solOut * BPS_DEN + feeNum - 1n) / feeNum; // ceil
+  if (gross >= vSol) {
+    throw new PreBondingError('Insufficient liquidity: gross >= v_sol');
+  }
+
+  // hi = ceil((vTok * gross) / (vSol - gross))
+  const num = vTok * gross;
+  const den = vSol - gross;
+  let hi = (num + den - 1n) / den; // ceil
+  if (hi === 0n) {
+    hi = 1n;
+  }
+
+  // Monotonic binary search on sellExactIn using forward path (with real floors)
+  let lo = 0n;
+  let ans = hi;
+  while (lo <= hi) {
+    const mid = lo + (hi - lo) / 2n;
+    const got = sellExactIn(curve, mid, feeBps);
+    if (got >= solOut) {
+      ans = mid;
+      if (mid === 0n) break;
+      hi = mid - 1n;
+    } else {
+      lo = mid + 1n;
+    }
+  }
+
+  return ans;
+}
+
+export function estimatePumpFunPrebonded(
+  bondingCurve: BondingCurve,
+  globalAccount: GlobalAccount,
+  amount: bigint,
+  tradeType: PreBondedTradeType,
+): bigint {
+  if (bondingCurve.complete) {
+    throw new PreBondingError(`Pool not in fundraising state: ${JSON.stringify(bondingCurve)}`);
+  }
+
+  const totalFeeBps = globalAccount.feeBasisPoints + globalAccount.creatorFeeBasisPoints;
+
+  switch (tradeType) {
+    case PreBondedTradeType.BuyExactIn:
+      return buyExactIn(bondingCurve, amount, totalFeeBps);
+    case PreBondedTradeType.BuyExactOut:
+      return buyExactOut(bondingCurve, amount, totalFeeBps);
+    case PreBondedTradeType.SellExactIn:
+      return sellExactIn(bondingCurve, amount, totalFeeBps);
+    case PreBondedTradeType.SellExactOut:
+      return sellExactOut(bondingCurve, amount, totalFeeBps);
+    default:
+      throw new PreBondingError(`Invalid trade type: ${tradeType}`);
+  }
+}

package/src/utils/quote/pumpfun/estimations_amm.ts

@@ -0,0 +1,165 @@
+import type { GlobalConfig, TokenAccount } from './models.js';
+import { BPS_DEN, PreBondedTradeType } from './estimations.js';
+
+/**
+ * Reserves structure for AMM calculations
+ * X = reserve of the token you pay (input side)
+ * Y = reserve of the token you receive (output side)
+ */
+interface Reserves {
+  xIn: bigint;
+  yOut: bigint;
+  feeBps: bigint;
+}
+
+/**
+ * Ceiling division for bigints
+ * Returns ceil(n / d)
+ */
+function ceilDiv(n: bigint, d: bigint): bigint {
+  if (d === 0n) {
+    throw new Error('Division by zero');
+  }
+  return (n + d - 1n) / d;
+}
+
+/**
+ * Calculate output amount for constant product AMM with exact input
+ * Formula: dy = (dx_effective * y_out) / (x_in + dx_effective)
+ * where dx_effective = dx * BPS_DEN / (BPS_DEN + fee_bps)
+ */
+function amountOutExactIn(dx: bigint, r: Reserves): bigint {
+  if (dx === 0n) {
+    return 0n;
+  }
+  if (r.xIn === 0n || r.yOut === 0n) {
+    throw new Error('Insufficient liquidity: empty reserves');
+  }
+
+  const denom = BPS_DEN + r.feeBps;
+  const dxEff = (dx * BPS_DEN) / denom;
+  const num = dxEff * r.yOut;
+  const den = r.xIn + dxEff;
+
+  return num / den; // floor division
+}
+
+/**
+ * Calculate input amount needed for exact output in constant product AMM
+ * Formula: dx = ceil(dx_effective * (BPS_DEN + fee_bps) / BPS_DEN)
+ * where dx_effective = ceil((x_in * dy) / (y_out - dy))
+ */
+function amountInExactOut(dy: bigint, r: Reserves): bigint {
+  if (dy === 0n) {
+    return 0n;
+  }
+  if (dy >= r.yOut || r.xIn === 0n) {
+    throw new Error('Insufficient liquidity: dy >= reserve or x_in is zero');
+  }
+
+  const dxEff = ceilDiv(r.xIn * dy, r.yOut - dy);
+  const denom = BPS_DEN + r.feeBps;
+
+  return ceilDiv(dxEff * denom, BPS_DEN);
+}
+
+/**
+ * Calculate base tokens received when buying with exact quote amount
+ * @param quoteIn Amount of quote tokens (SOL) to spend
+ * @param baseRes Base token reserve
+ * @param quoteRes Quote token reserve
+ * @param feeBps Fee in basis points
+ * @returns Amount of base tokens received
+ */
+export function buyBaseExactInQuote(quoteIn: bigint, baseRes: bigint, quoteRes: bigint, feeBps: bigint): bigint {
+  return amountOutExactIn(quoteIn, {
+    xIn: quoteRes,
+    yOut: baseRes,
+    feeBps,
+  });
+}
+
+/**
+ * Calculate quote tokens needed to buy exact base amount
+ * @param baseOut Desired amount of base tokens
+ * @param baseRes Base token reserve
+ * @param quoteRes Quote token reserve
+ * @param feeBps Fee in basis points
+ * @returns Amount of quote tokens needed
+ */
+export function buyBaseExactOutQuote(baseOut: bigint, baseRes: bigint, quoteRes: bigint, feeBps: bigint): bigint {
+  return amountInExactOut(baseOut, {
+    xIn: quoteRes,
+    yOut: baseRes,
+    feeBps,
+  });
+}
+
+/**
+ * Calculate quote tokens received when selling exact base amount
+ * @param baseIn Amount of base tokens to sell
+ * @param baseRes Base token reserve
+ * @param quoteRes Quote token reserve
+ * @param feeBps Fee in basis points
+ * @returns Amount of quote tokens received
+ */
+export function sellBaseExactInQuote(baseIn: bigint, baseRes: bigint, quoteRes: bigint, feeBps: bigint): bigint {
+  return amountOutExactIn(baseIn, {
+    xIn: baseRes,
+    yOut: quoteRes,
+    feeBps,
+  });
+}
+
+/**
+ * Calculate base tokens needed to receive exact quote amount
+ * @param quoteOut Desired amount of quote tokens
+ * @param baseRes Base token reserve
+ * @param quoteRes Quote token reserve
+ * @param feeBps Fee in basis points
+ * @returns Amount of base tokens needed
+ */
+export function sellBaseExactOutQuote(quoteOut: bigint, baseRes: bigint, quoteRes: bigint, feeBps: bigint): bigint {
+  return amountInExactOut(quoteOut, {
+    xIn: baseRes,
+    yOut: quoteRes,
+    feeBps,
+  });
+}
+
+/**
+ * Main estimation function for PumpFun AMM
+ * @param baseToken Base token account info
+ * @param quoteToken Quote token account info
+ * @param globalConfig Global configuration with fee settings
+ * @param amount Amount to trade
+ * @param tradeType Type of trade (BuyExactIn, BuyExactOut, SellExactIn, SellExactOut)
+ * @returns Estimated output/input amount
+ */
+export function estimatePumpFunAmm(
+  baseToken: TokenAccount,
+  quoteToken: TokenAccount,
+  globalConfig: GlobalConfig,
+  amount: bigint,
+  tradeType: PreBondedTradeType,
+): bigint {
+  const totalFeeBps =
+    globalConfig.lpFeeBasisPoints + globalConfig.protocolFeeBasisPoints + globalConfig.coinCreatorFeeBasisPoints;
+
+  switch (tradeType) {
+    case PreBondedTradeType.BuyExactIn:
+      return buyBaseExactInQuote(amount, baseToken.amount, quoteToken.amount, totalFeeBps);
+
+    case PreBondedTradeType.BuyExactOut:
+      return buyBaseExactOutQuote(amount, baseToken.amount, quoteToken.amount, totalFeeBps);
+
+    case PreBondedTradeType.SellExactIn:
+      return sellBaseExactInQuote(amount, baseToken.amount, quoteToken.amount, totalFeeBps);
+
+    case PreBondedTradeType.SellExactOut:
+      return sellBaseExactOutQuote(amount, baseToken.amount, quoteToken.amount, totalFeeBps);
+
+    default:
+      throw new Error(`Invalid trade type: ${tradeType}`);
+  }
+}