@liquid-af/sdk 0.1.0

package/src/helpers/preview.ts

@@ -0,0 +1,798 @@
+import type { Connection, PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import type { LiquidConfig } from "../config.js";
+import type { BuyCurvePreview, SellCurvePreview, SwapPreview } from "../types.js";
+import { fetchAmmConfig, fetchPoolState } from "../accounts/liquid-swap.js";
+import {
+	fetchLiquidGlobalConfig,
+	fetchNativeBondingCurve,
+	fetchStableBondingCurve,
+} from "../accounts/liquid.js";
+import {
+	calculateBuyExpectation,
+	calculateSellExpectation,
+} from "../math/bonding-curve.js";
+import { calculateAmmSellOutput, calculateAmmBuyInput } from "../math/amm.js";
+import { BPS_DENOMINATOR } from "../math/constants.js";
+import { calculateVirtualSolReserves } from "../oracle.js";
+import { getAccount, getMint } from "@solana/spl-token";
+import { calculateFeesForPool } from "../math/tiered-fees.js";
+
+/** State needed for bonding curve preview calculations (pure math, no I/O). */
+export interface CurvePreviewState {
+	globalConfig: {
+		protocolFeeBasisPoints: number;
+		creatorFeeBasisPoints: number;
+		creatorReferralRewardBasisPoints: number;
+		traderReferralRewardBasisPoints: number;
+	};
+	bondingCurve: {
+		virtualQuoteReserves: BN;
+		virtualTokenReserves: BN;
+		realTokenReserves: BN;
+	};
+}
+
+/** State needed for AMM swap preview calculations (pure math, no I/O). */
+export interface SwapPreviewState {
+	ammConfig: {
+		lpFeeRate: number;
+		creatorFeeRate: number;
+		protocolFeeRate: number;
+	};
+	baseVaultBalance: BN;
+	quoteVaultBalance: BN;
+}
+
+/** Referral options for curve previews. */
+export interface CurvePreviewOptions {
+	hasCreatorRef?: boolean;
+	hasTraderRef?: boolean;
+}
+
+/**
+ * Optional pre-fetched state for {@link previewBuyOnCurve} / {@link previewSellOnCurve}.
+ *
+ * Provide any subset to skip the corresponding RPC calls. Omitted fields are
+ * fetched automatically from chain.
+ */
+export interface CurvePrefetchedState {
+	/**
+	 * Fee configuration from the global config account.
+	 * Include `initialVirtualReserveUsd` when previewing native curves without
+	 * a prefetched `bondingCurve` (needed to compute virtual SOL reserves).
+	 */
+	globalConfig?: {
+		protocolFeeBasisPoints: number;
+		creatorFeeBasisPoints: number;
+		creatorReferralRewardBasisPoints: number;
+		traderReferralRewardBasisPoints: number;
+		initialVirtualReserveUsd?: BN;
+	};
+	/**
+	 * Bonding curve reserves.
+	 * For native curves, `virtualQuoteReserves` must already be oracle-adjusted
+	 * (i.e. computed via `calculateVirtualSolReserves`).
+	 */
+	bondingCurve?: {
+		virtualQuoteReserves: BN;
+		virtualTokenReserves: BN;
+		realTokenReserves: BN;
+	};
+}
+
+/** Shared options for async bonding curve preview functions. */
+interface CurveOptionsBase {
+	/** Pre-fetched state to skip RPC calls. */
+	prefetched?: CurvePrefetchedState;
+	/** Whether the token creator has an active referral. */
+	hasCreatorRef?: boolean;
+	/** Whether the trader has an active referral. */
+	hasTraderRef?: boolean;
+}
+
+/**
+ * Options for native SOL bonding curve previews.
+ *
+ * Requires `solPriceUsd` to compute virtual SOL reserves from the on-chain
+ * USD-denominated initial reserve value.
+ */
+export interface NativeCurveOptions extends CurveOptionsBase {
+	quoteMint?: never;
+	/** Current SOL price in USD (6 decimals, e.g. 150_000_000 = $150). */
+	solPriceUsd: BN;
+}
+
+/**
+ * Options for stable token (e.g. USDC) bonding curve previews.
+ *
+ * Virtual quote reserves are stored on-chain and fetched automatically.
+ */
+export interface StableCurveOptions extends CurveOptionsBase {
+	/** Quote token mint address (e.g. USDC mint). */
+	quoteMint: PublicKey;
+	solPriceUsd?: never;
+}
+
+/**
+ * Options for async bonding curve previews. Discriminated union:
+ * - {@link NativeCurveOptions} — native SOL curves (requires `solPriceUsd`)
+ * - {@link StableCurveOptions} — stable curves (requires `quoteMint`)
+ */
+export type CurveAsyncOptions = NativeCurveOptions | StableCurveOptions;
+
+/** Pre-fetched state for AMM swap async previews. */
+export interface SwapPrefetchedState {
+	/**
+	 * Pre-computed fee rates.
+	 * For tiered fee systems, use calculateFeesForPool() to determine the rates
+	 * before passing them here.
+	 */
+	feeRates?: {
+		lpFeeRate: number;
+		creatorFeeRate: number;
+		protocolFeeRate: number;
+	};
+	poolState?: {
+		baseVault: PublicKey;
+		quoteVault: PublicKey;
+		baseTokenProgram: PublicKey;
+		quoteTokenProgram: PublicKey;
+		baseMint: PublicKey;
+		quoteMint: PublicKey;
+	};
+	vaultBalances?: { baseVaultBalance: BN; quoteVaultBalance: BN };
+	baseTotalSupply?: BN;
+}
+
+/**
+ * Previews a buy on the bonding curve from pre-fetched state. The function executes offline using the state being passed in.
+ *
+ * @param amountInQuote - Quote token amount to spend (lamports for SOL, smallest unit for stables)
+ * @param state - Pre-fetched bonding curve and global config state
+ * @param options - Optional referral flags
+ * @returns Buy preview with tokens out, fees, price impact, and completion flag
+ */
+export function calculateBuyCurvePreview(
+	amountInQuote: BN,
+	state: CurvePreviewState,
+	options?: CurvePreviewOptions
+): BuyCurvePreview {
+	const { globalConfig, bondingCurve } = state;
+
+	const feeConfig = {
+		protocolFeeBps: globalConfig.protocolFeeBasisPoints,
+		creatorFeeBps: globalConfig.creatorFeeBasisPoints,
+		creatorReferralBps: globalConfig.creatorReferralRewardBasisPoints,
+		traderReferralBps: globalConfig.traderReferralRewardBasisPoints,
+	};
+
+	const result = calculateBuyExpectation(
+		amountInQuote,
+		bondingCurve,
+		feeConfig,
+		options?.hasCreatorRef ?? false,
+		options?.hasTraderRef ?? false
+	);
+
+	const priceBefore = bondingCurve.virtualQuoteReserves
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(bondingCurve.virtualTokenReserves);
+	const priceAfter = result.newVirtualQuote
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(result.newVirtualToken);
+	const priceImpactBps = priceAfter
+		.sub(priceBefore)
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(priceBefore)
+		.toNumber();
+
+	const willComplete = result.tokensOut.gte(bondingCurve.realTokenReserves);
+
+	return {
+		tokensOut: result.tokensOut,
+		fees: {
+			protocolFee: result.protocolFee,
+			creatorFee: result.creatorFee,
+			creatorReferralFee: result.creatorReferralFee,
+			traderReferralFee: result.traderReferralFee,
+			totalFees: result.totalFees,
+		},
+		priceImpactBps,
+		newReserves: {
+			virtualQuote: result.newVirtualQuote,
+			virtualToken: result.newVirtualToken,
+		},
+		willComplete,
+	};
+}
+
+/**
+ * Previews a sell on the bonding curve from pre-fetched state. The function executes offline using the state being passed in.
+ *
+ * @param amountInTokens - Token amount to sell
+ * @param state - Pre-fetched bonding curve and global config state
+ * @param options - Optional referral flags
+ * @returns Sell preview with quote out, fees, and price impact
+ */
+export function calculateSellCurvePreview(
+	amountInTokens: BN,
+	state: CurvePreviewState,
+	options?: CurvePreviewOptions
+): SellCurvePreview {
+	const { globalConfig, bondingCurve } = state;
+
+	const feeConfig = {
+		protocolFeeBps: globalConfig.protocolFeeBasisPoints,
+		creatorFeeBps: globalConfig.creatorFeeBasisPoints,
+		creatorReferralBps: globalConfig.creatorReferralRewardBasisPoints,
+		traderReferralBps: globalConfig.traderReferralRewardBasisPoints,
+	};
+
+	const result = calculateSellExpectation(
+		amountInTokens,
+		bondingCurve,
+		feeConfig,
+		options?.hasCreatorRef ?? false,
+		options?.hasTraderRef ?? false
+	);
+
+	const priceBefore = bondingCurve.virtualQuoteReserves
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(bondingCurve.virtualTokenReserves);
+	const priceAfter = result.newVirtualQuote
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(result.newVirtualToken);
+	const priceImpactBps = priceBefore
+		.sub(priceAfter)
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(priceBefore)
+		.toNumber();
+
+	return {
+		quoteOut: result.quoteOutGross,
+		quoteOutNet: result.quoteOutNet,
+		fees: {
+			protocolFee: result.protocolFee,
+			creatorFee: result.creatorFee,
+			creatorReferralFee: result.creatorReferralFee,
+			traderReferralFee: result.traderReferralFee,
+			totalFees: result.totalFees,
+		},
+		priceImpactBps,
+		newReserves: {
+			virtualQuote: result.newVirtualQuote,
+			virtualToken: result.newVirtualToken,
+		},
+	};
+}
+
+/**
+ * Previews a buy swap on the AMM (quote -> base) from pre-fetched state. The function executes offline using the state being passed in.
+ *
+ * @param amountOut - Desired base token amount out
+ * @param state - Pre-fetched AMM config and vault balances
+ * @returns Swap preview with quote in, fees, and price impact
+ */
+export function calculateSwapBuyPreview(
+	amountOut: BN,
+	state: SwapPreviewState
+): SwapPreview {
+	const { ammConfig, baseVaultBalance, quoteVaultBalance } = state;
+
+	const result = calculateAmmBuyInput(
+		amountOut,
+		baseVaultBalance,
+		quoteVaultBalance,
+		{
+			lpFeeRate: ammConfig.lpFeeRate,
+			creatorFeeRate: ammConfig.creatorFeeRate,
+			protocolFeeRate: ammConfig.protocolFeeRate,
+		}
+	);
+
+	const priceBefore = quoteVaultBalance
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(baseVaultBalance);
+	const newBaseVault = baseVaultBalance.sub(amountOut);
+	const newQuoteVault = quoteVaultBalance.add(result.quoteInGross);
+	const priceAfter = newQuoteVault
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(newBaseVault);
+	const priceImpactBps = priceAfter
+		.sub(priceBefore)
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(priceBefore)
+		.toNumber();
+
+	return {
+		amountOut: result.quoteInGross,
+		amountOutNet: result.quoteIn,
+		fees: {
+			lpFee: result.lpFee,
+			creatorFee: result.creatorFee,
+			protocolFee: result.protocolFee,
+			totalFees: result.totalFees,
+		},
+		priceImpactBps,
+	};
+}
+
+/**
+ * Previews a sell swap on the AMM (base -> quote) from pre-fetched state. The function executes offline using the state being passed in.
+ *
+ * @param amountIn - Base token amount to sell
+ * @param state - Pre-fetched AMM config and vault balances
+ * @returns Swap preview with quote out, fees, and price impact
+ */
+export function calculateSwapSellPreview(
+	amountIn: BN,
+	state: SwapPreviewState
+): SwapPreview {
+	const { ammConfig, baseVaultBalance, quoteVaultBalance } = state;
+
+	const result = calculateAmmSellOutput(
+		amountIn,
+		baseVaultBalance,
+		quoteVaultBalance,
+		{
+			lpFeeRate: ammConfig.lpFeeRate,
+			creatorFeeRate: ammConfig.creatorFeeRate,
+			protocolFeeRate: ammConfig.protocolFeeRate,
+		}
+	);
+
+	const priceBefore = quoteVaultBalance
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(baseVaultBalance);
+	const newBaseVault = baseVaultBalance.add(amountIn);
+	const newQuoteVault = quoteVaultBalance.sub(result.quoteOut);
+	const priceAfter = newQuoteVault
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(newBaseVault);
+	const priceImpactBps = priceBefore
+		.sub(priceAfter)
+		.mul(new BN(BPS_DENOMINATOR))
+		.div(priceBefore)
+		.toNumber();
+
+	return {
+		amountOut: result.quoteOut,
+		amountOutNet: result.quoteOutNet,
+		fees: {
+			lpFee: result.lpFee,
+			creatorFee: result.creatorFee,
+			protocolFee: result.protocolFee,
+			totalFees: result.totalFees,
+		},
+		priceImpactBps,
+	};
+}
+
+/**
+ * Fetches the on-chain global config and maps it to the fee/reserve fields
+ * required by {@link CurvePreviewState}.
+ *
+ * @param connection - Solana RPC connection
+ * @param config - Liquid protocol configuration (provides the program ID)
+ * @returns Fee basis-point fields plus `initialVirtualReserveUsd` for native reserve computation
+ */
+async function fetchCurveGlobalConfig(
+	connection: Connection,
+	config: LiquidConfig
+): Promise<
+	CurvePreviewState["globalConfig"] & { initialVirtualReserveUsd: BN }
+> {
+	const raw = await fetchLiquidGlobalConfig(connection, config);
+	return {
+		protocolFeeBasisPoints: raw.protocolFeeBasisPoints,
+		creatorFeeBasisPoints: raw.creatorFeeBasisPoints,
+		creatorReferralRewardBasisPoints: raw.creatorReferralRewardBasisPoints,
+		traderReferralRewardBasisPoints: raw.traderReferralRewardBasisPoints,
+		initialVirtualReserveUsd: raw.initialVirtualReserveUsd,
+	};
+}
+
+/**
+ * Resolves {@link CurvePreviewState} for native SOL curves.
+ *
+ * Fetches the global config and native bonding curve in parallel (skipping
+ * any that are prefetched), then computes `virtualQuoteReserves` from
+ * `initialVirtualReserveUsd` and `solPriceUsd`.
+ *
+ * @param connection - Solana RPC connection
+ * @param mint - Token mint address of the native bonding curve
+ * @param options - Native curve options containing `solPriceUsd` and optional `prefetched` state
+ * @param config - Liquid protocol configuration
+ * @returns Resolved curve preview state ready for pure-math preview calculations
+ */
+async function resolveNativeCurve(
+	connection: Connection,
+	mint: PublicKey,
+	options: NativeCurveOptions,
+	config: LiquidConfig
+): Promise<CurvePreviewState> {
+	const pre = options.prefetched;
+
+	const [globalConfig, nativeCurve] = await Promise.all([
+		pre?.globalConfig ?? fetchCurveGlobalConfig(connection, config),
+		pre?.bondingCurve
+			? null
+			: fetchNativeBondingCurve(connection, mint, config),
+	]);
+
+	const virtualSolReserves = calculateVirtualSolReserves(
+		BigInt(globalConfig.initialVirtualReserveUsd!.toString()),
+		BigInt(options.solPriceUsd.toString())
+	);
+
+	const bondingCurve = pre?.bondingCurve ?? {
+		virtualQuoteReserves: new BN(virtualSolReserves.toString()),
+		virtualTokenReserves: nativeCurve!.virtualTokenReserves,
+		realTokenReserves: nativeCurve!.realTokenReserves,
+	};
+
+	return { globalConfig, bondingCurve };
+}
+
+/**
+ * Resolves {@link CurvePreviewState} for stable (e.g. USDC) curves.
+ *
+ * Fetches the global config and stable bonding curve in parallel (skipping
+ * any that are prefetched). `virtualQuoteReserves` is read directly from
+ * the on-chain account.
+ *
+ * @param connection - Solana RPC connection
+ * @param mint - Token mint address of the stable bonding curve
+ * @param options - Stable curve options containing `quoteMint` and optional `prefetched` state
+ * @param config - Liquid protocol configuration
+ * @returns Resolved curve preview state ready for pure-math preview calculations
+ */
+async function resolveStableCurve(
+	connection: Connection,
+	mint: PublicKey,
+	options: StableCurveOptions,
+	config: LiquidConfig
+): Promise<CurvePreviewState> {
+	const pre = options.prefetched;
+
+	const [globalConfig, stableCurve] = await Promise.all([
+		pre?.globalConfig ?? fetchCurveGlobalConfig(connection, config),
+		pre?.bondingCurve
+			? null
+			: fetchStableBondingCurve(
+					connection,
+					mint,
+					options.quoteMint,
+					config
+			  ),
+	]);
+
+	const bondingCurve = pre?.bondingCurve ?? {
+		virtualQuoteReserves: stableCurve!.virtualQuoteReserves,
+		virtualTokenReserves: stableCurve!.virtualTokenReserves,
+		realTokenReserves: stableCurve!.realTokenReserves,
+	};
+
+	return { globalConfig, bondingCurve };
+}
+
+/**
+ * Dispatches to {@link resolveNativeCurve} or {@link resolveStableCurve}
+ * based on whether `options.quoteMint` is present.
+ *
+ * @param connection - Solana RPC connection
+ * @param mint - Token mint address
+ * @param config - Liquid protocol configuration
+ * @param options - Discriminated curve options (native or stable)
+ * @returns Resolved curve preview state ready for pure-math preview calculations
+ */
+function resolveCurveState(
+	connection: Connection,
+	mint: PublicKey,
+	config: LiquidConfig,
+	options: CurveAsyncOptions
+): Promise<CurvePreviewState> {
+	if (options.quoteMint) {
+		return resolveStableCurve(
+			connection,
+			mint,
+			options as StableCurveOptions,
+			config
+		);
+	}
+	return resolveNativeCurve(
+		connection,
+		mint,
+		options as NativeCurveOptions,
+		config
+	);
+}
+
+/**
+ * Previews a buy on the bonding curve.
+ *
+ * Auto-fetches the global config and bonding curve state from chain, then
+ * computes expected tokens out, fee breakdown, price impact, and whether the
+ * buy would complete the curve.
+ *
+ * @param connection - Solana RPC connection
+ * @param mint - Token mint address
+ * @param amountInQuote - Quote token amount to spend (lamports for SOL, smallest unit for stables)
+ * @param config - Liquid protocol configuration
+ * @param options - Native ({@link NativeCurveOptions}) or stable ({@link StableCurveOptions})
+ * @returns Buy preview with `tokensOut`, `fees`, `priceImpactBps`, `newReserves`, and `willComplete`
+ *
+ * @example Native SOL curve
+ * ```ts
+ * const preview = await previewBuyOnCurve(connection, mint, new BN(100_000_000), config, {
+ *   solPriceUsd: new BN(150_000_000), // $150
+ * });
+ * ```
+ *
+ * @example Stable (USDC) curve
+ * ```ts
+ * const preview = await previewBuyOnCurve(connection, mint, new BN(10_000_000), config, {
+ *   quoteMint: USDC_MINT,
+ * });
+ * ```
+ *
+ * @see {@link calculateBuyCurvePreview} for pure offline calculations with pre-built state
+ */
+export async function previewBuyOnCurve(
+	connection: Connection,
+	mint: PublicKey,
+	amountInQuote: BN,
+	config: LiquidConfig,
+	options: CurveAsyncOptions
+): Promise<BuyCurvePreview> {
+	const state = await resolveCurveState(connection, mint, config, options);
+	return calculateBuyCurvePreview(amountInQuote, state, {
+		hasCreatorRef: options?.hasCreatorRef,
+		hasTraderRef: options?.hasTraderRef,
+	});
+}
+
+/**
+ * Previews a sell on the bonding curve.
+ *
+ * Auto-fetches the global config and bonding curve state from chain, then
+ * computes expected quote out, fee breakdown, and price impact.
+ *
+ * @param connection - Solana RPC connection
+ * @param mint - Token mint address
+ * @param amountInTokens - Token amount to sell (smallest unit, 6 decimals)
+ * @param config - Liquid protocol configuration
+ * @param options - Native ({@link NativeCurveOptions}) or stable ({@link StableCurveOptions})
+ * @returns Sell preview with `quoteOut`, `quoteOutNet`, `fees`, `priceImpactBps`, and `newReserves`
+ *
+ * @example Native SOL curve
+ * ```ts
+ * const preview = await previewSellOnCurve(connection, mint, new BN(5_000_000), config, {
+ *   solPriceUsd: new BN(150_000_000),
+ * });
+ * ```
+ *
+ * @see {@link calculateSellCurvePreview} for pure offline calculations with pre-built state
+ */
+export async function previewSellOnCurve(
+	connection: Connection,
+	mint: PublicKey,
+	amountInTokens: BN,
+	config: LiquidConfig,
+	options: CurveAsyncOptions
+): Promise<SellCurvePreview> {
+	const state = await resolveCurveState(connection, mint, config, options);
+	return calculateSellCurvePreview(amountInTokens, state, {
+		hasCreatorRef: options?.hasCreatorRef,
+		hasTraderRef: options?.hasTraderRef,
+	});
+}
+
+/**
+ * Previews a sell swap on the AMM (base -> quote).
+ *
+ * Accepts optional pre-fetched state to avoid redundant RPC calls.
+ * For tiered fee systems, you must provide either:
+ * - `prefetched.feeRates` - pre-computed fee rates for the current market cap
+ * - `solPriceUsd` parameter - to calculate fee rates from on-chain tiered config
+ *
+ * @param connection - Solana RPC connection
+ * @param baseMint - Base token mint address
+ * @param quoteMint - Quote token mint address
+ * @param amountIn - Base token amount to sell
+ * @param config - Liquid protocol configuration
+ * @param options - Optional pre-fetched AMM state and solPriceUsd for tier calculation
+ * @returns Swap preview with quote out, fees, and price impact
+ *
+ * @throws Error if neither feeRates nor solPriceUsd is provided for tiered fee systems
+ */
+export async function previewSwapSell(
+	connection: Connection,
+	baseMint: PublicKey,
+	quoteMint: PublicKey,
+	amountIn: BN,
+	config: LiquidConfig,
+	options?: { prefetched?: SwapPrefetchedState; solPriceUsd?: BN }
+): Promise<SwapPreview> {
+	const pre = options?.prefetched;
+
+	// Fetch pool state if not provided
+	const poolState =
+		pre?.poolState ??
+		(await fetchPoolState(connection, baseMint, quoteMint, config));
+
+	// Get vault balances
+	let baseVaultBalance: BN;
+	let quoteVaultBalance: BN;
+
+	if (pre?.vaultBalances) {
+		({ baseVaultBalance, quoteVaultBalance } = pre.vaultBalances);
+	} else {
+		const [baseVaultAccount, quoteVaultAccount] = await Promise.all([
+			getAccount(
+				connection,
+				poolState.baseVault,
+				"confirmed",
+				poolState.baseTokenProgram
+			),
+			getAccount(
+				connection,
+				poolState.quoteVault,
+				"confirmed",
+				poolState.quoteTokenProgram
+			),
+		]);
+		baseVaultBalance = new BN(baseVaultAccount.amount.toString());
+		quoteVaultBalance = new BN(quoteVaultAccount.amount.toString());
+	}
+
+	// Get fee rates
+	let feeRates: {
+		lpFeeRate: number;
+		creatorFeeRate: number;
+		protocolFeeRate: number;
+	};
+
+	if (pre?.feeRates) {
+		// Use pre-computed fee rates
+		feeRates = pre.feeRates;
+	} else if (options?.solPriceUsd) {
+		// Calculate fee rates from tiered config
+		const ammConfig = await fetchAmmConfig(connection, config);
+		const baseMintAccount = await getMint(
+			connection,
+			poolState.baseMint,
+			"confirmed",
+			poolState.baseTokenProgram
+		);
+		const baseTotalSupply = new BN(baseMintAccount.supply.toString());
+
+		const tiers = ammConfig.feeTiers;
+		const [lpFeeRate, protocolFeeRate, creatorFeeRate] =
+			calculateFeesForPool(
+				quoteVaultBalance,
+				baseVaultBalance,
+				baseTotalSupply,
+				options.solPriceUsd,
+				poolState.quoteMint,
+				tiers
+			);
+
+		feeRates = { lpFeeRate, protocolFeeRate, creatorFeeRate };
+	} else {
+		throw new Error(
+			"Either prefetched.feeRates or solPriceUsd must be provided for tiered fee calculations"
+		);
+	}
+
+	return calculateSwapSellPreview(amountIn, {
+		ammConfig: feeRates,
+		baseVaultBalance,
+		quoteVaultBalance,
+	});
+}
+
+/**
+ * Previews a buy swap on the AMM (quote -> base).
+ *
+ * Accepts optional pre-fetched state to avoid redundant RPC calls.
+ * For tiered fee systems, you must provide either:
+ * - `prefetched.feeRates` - pre-computed fee rates for the current market cap
+ * - `solPriceUsd` parameter - to calculate fee rates from on-chain tiered config
+ *
+ * @param connection - Solana RPC connection
+ * @param baseMint - Base token mint address
+ * @param quoteMint - Quote token mint address
+ * @param amountOut - Desired base token amount out
+ * @param config - Liquid protocol configuration
+ * @param options - Optional pre-fetched AMM state and solPriceUsd for tier calculation
+ * @returns Swap preview with quote in, fees, and price impact
+ *
+ * @throws Error if neither feeRates nor solPriceUsd is provided for tiered fee systems
+ */
+export async function previewSwapBuy(
+	connection: Connection,
+	baseMint: PublicKey,
+	quoteMint: PublicKey,
+	amountOut: BN,
+	config: LiquidConfig,
+	options?: { prefetched?: SwapPrefetchedState; solPriceUsd?: BN }
+): Promise<SwapPreview> {
+	const pre = options?.prefetched;
+
+	// Fetch pool state if not provided
+	const poolState =
+		pre?.poolState ??
+		(await fetchPoolState(connection, baseMint, quoteMint, config));
+
+	// Get vault balances
+	let baseVaultBalance: BN;
+	let quoteVaultBalance: BN;
+
+	if (pre?.vaultBalances) {
+		({ baseVaultBalance, quoteVaultBalance } = pre.vaultBalances);
+	} else {
+		const [baseVaultAccount, quoteVaultAccount] = await Promise.all([
+			getAccount(
+				connection,
+				poolState.baseVault,
+				"confirmed",
+				poolState.baseTokenProgram
+			),
+			getAccount(
+				connection,
+				poolState.quoteVault,
+				"confirmed",
+				poolState.quoteTokenProgram
+			),
+		]);
+		baseVaultBalance = new BN(baseVaultAccount.amount.toString());
+		quoteVaultBalance = new BN(quoteVaultAccount.amount.toString());
+	}
+
+	// Get fee rates
+	let feeRates: {
+		lpFeeRate: number;
+		creatorFeeRate: number;
+		protocolFeeRate: number;
+	};
+
+	if (pre?.feeRates) {
+		// Use pre-computed fee rates
+		feeRates = pre.feeRates;
+	} else if (options?.solPriceUsd) {
+		// Calculate fee rates from tiered config
+		const ammConfig = await fetchAmmConfig(connection, config);
+		const baseMintAccount = await getMint(
+			connection,
+			poolState.baseMint,
+			"confirmed",
+			poolState.baseTokenProgram
+		);
+		const baseTotalSupply = new BN(baseMintAccount.supply.toString());
+
+		const tiers = ammConfig.feeTiers;
+		const [lpFeeRate, protocolFeeRate, creatorFeeRate] =
+			calculateFeesForPool(
+				quoteVaultBalance,
+				baseVaultBalance,
+				baseTotalSupply,
+				options.solPriceUsd,
+				poolState.quoteMint,
+				tiers
+			);
+
+		feeRates = { lpFeeRate, protocolFeeRate, creatorFeeRate };
+	} else {
+		throw new Error(
+			"Either prefetched.feeRates or solPriceUsd must be provided for tiered fee calculations"
+		);
+	}
+
+	return calculateSwapBuyPreview(amountOut, {
+		ammConfig: feeRates,
+		baseVaultBalance,
+		quoteVaultBalance,
+	});
+}