@liquid-af/sdk 0.1.0

package/src/instructions/program-cache.ts

@@ -0,0 +1,106 @@
+import { Program } from "@coral-xyz/anchor";
+import type { LiquidConfig } from "../config.js";
+import { createStubProvider } from "../provider.js";
+
+import liquidIdl from "../idl/liquid.json" with { type: "json" };
+import liquidSwapIdl from "../idl/liquid_swap.json" with { type: "json" };
+import liquidFeesIdl from "../idl/liquid_fees.json" with { type: "json" };
+import liquidStateIdl from "../idl/liquid_state.json" with { type: "json" };
+
+import type { Liquid } from "../idl/liquid.js";
+import type { LiquidSwap } from "../idl/liquid_swap.js";
+import type { LiquidFees } from "../idl/liquid_fees.js";
+import type { LiquidState } from "../idl/liquid_state.js";
+
+/**
+ * Cached stub Program instances for instruction building.
+ * Instruction building via `.instruction()` never hits the network,
+ * so these programs use a shared stub provider with no real Connection.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const cache = new Map<string, Program<any>>();
+
+/**
+ * Returns a cached Program instance or creates one if it doesn't exist.
+ *
+ * @param key - Cache key prefix (e.g., "liquid", "swap")
+ * @param idl - Raw IDL JSON object
+ * @param address - Program address as a base58 string
+ * @returns Cached or newly created Program instance
+ */
+function getOrCreate<T extends Liquid | LiquidSwap | LiquidFees | LiquidState>(
+	key: string,
+	idl: Record<string, unknown>,
+	address: string
+): Program<T> {
+	const cacheKey = `${key}:${address}`;
+	let prog = cache.get(cacheKey) as Program<T> | undefined;
+	if (!prog) {
+		const patchedIdl = { ...idl, address };
+		prog = new Program(patchedIdl as T, createStubProvider());
+		cache.set(cacheKey, prog);
+	}
+	return prog;
+}
+
+/**
+ * Returns a cached Liquid bonding curve program instance for instruction building.
+ *
+ * @param config - Liquid protocol configuration
+ * @returns Cached Program instance typed as Liquid
+ */
+export function getCachedLiquidProgram(config: LiquidConfig): Program<Liquid> {
+	return getOrCreate<Liquid>(
+		"liquid",
+		liquidIdl,
+		config.liquidProgramId.toBase58()
+	);
+}
+
+/**
+ * Returns a cached Liquid Swap AMM program instance for instruction building.
+ *
+ * @param config - Liquid protocol configuration
+ * @returns Cached Program instance typed as LiquidSwap
+ */
+export function getCachedSwapProgram(
+	config: LiquidConfig
+): Program<LiquidSwap> {
+	return getOrCreate<LiquidSwap>(
+		"swap",
+		liquidSwapIdl,
+		config.liquidSwapProgramId.toBase58()
+	);
+}
+
+/**
+ * Returns a cached Liquid Fees program instance for instruction building.
+ *
+ * @param config - Liquid protocol configuration
+ * @returns Cached Program instance typed as LiquidFees
+ */
+export function getCachedFeesProgram(
+	config: LiquidConfig
+): Program<LiquidFees> {
+	return getOrCreate<LiquidFees>(
+		"fees",
+		liquidFeesIdl,
+		config.liquidFeesProgramId.toBase58()
+	);
+}
+
+/**
+ * Returns a cached Liquid State program instance for instruction building.
+ *
+ * @param config - Liquid protocol configuration
+ * @returns Cached Program instance typed as LiquidState
+ */
+export function getCachedStateProgram(
+	config: LiquidConfig
+): Program<LiquidState> {
+	return getOrCreate<LiquidState>(
+		"state",
+		liquidStateIdl,
+		config.liquidStateProgramId.toBase58()
+	);
+}

package/src/math/amm.ts

@@ -0,0 +1,146 @@
+import BN from "bn.js";
+import { FEE_RATE_DENOMINATOR } from "./constants.js";
+import type { AmmSellOutput, AmmBuyInput, LpTokenAmounts } from "../types.js";
+
+/** AMM fee rates in basis points */
+export interface AmmFeeRates {
+	lpFeeRate: number;
+	creatorFeeRate: number;
+	protocolFeeRate: number;
+}
+
+/**
+ * Calculates expected output for selling base tokens on the AMM.
+ * Uses constant product formula: quoteOut = (amountIn * quoteVault) / (baseVault + amountIn)
+ *
+ * @param amountIn - Base tokens to sell
+ * @param baseVault - Current base vault balance
+ * @param quoteVault - Current quote vault balance
+ * @param fees - Fee rates in basis points
+ * @returns Sell output with gross/net quote amounts and fee breakdown
+ */
+export const calculateAmmSellOutput = (
+	amountIn: BN,
+	baseVault: BN,
+	quoteVault: BN,
+	fees: AmmFeeRates
+): AmmSellOutput => {
+	// Gross output: (amountIn * quoteVault) / (baseVault + amountIn)
+	const grossQuoteOut = amountIn.mul(quoteVault).div(baseVault.add(amountIn));
+
+	const denom = new BN(FEE_RATE_DENOMINATOR);
+	const lpFee = grossQuoteOut.mul(new BN(fees.lpFeeRate)).div(denom);
+	const creatorFee = grossQuoteOut
+		.mul(new BN(fees.creatorFeeRate))
+		.div(denom);
+	const protocolFee = grossQuoteOut
+		.mul(new BN(fees.protocolFeeRate))
+		.div(denom);
+	const totalFees = lpFee.add(creatorFee).add(protocolFee);
+
+	const quoteOutNet = grossQuoteOut.sub(totalFees);
+
+	return {
+		quoteOut: grossQuoteOut,
+		quoteOutNet,
+		lpFee,
+		creatorFee,
+		protocolFee,
+		totalFees,
+	};
+};
+
+/**
+ * Calculates required quote input for buying base tokens on the AMM.
+ * Reverse calculation: how much quote is needed for the desired base output.
+ *
+ * @param amountOut - Base tokens to buy
+ * @param baseVault - Current base vault balance
+ * @param quoteVault - Current quote vault balance
+ * @param fees - Fee rates in basis points
+ * @returns Buy input with gross/net quote amounts and fee breakdown
+ */
+export const calculateAmmBuyInput = (
+	amountOut: BN,
+	baseVault: BN,
+	quoteVault: BN,
+	fees: AmmFeeRates
+): AmmBuyInput => {
+	const denom = new BN(FEE_RATE_DENOMINATOR);
+
+	// Quote needed for swap (without fees), ceiling division
+	const quoteForSwap = quoteVault
+		.mul(amountOut)
+		.div(baseVault.sub(amountOut))
+		.add(new BN(1));
+
+	// Total fee rate
+	const totalFeeRate =
+		fees.lpFeeRate + fees.creatorFeeRate + fees.protocolFeeRate;
+
+	// Gross quote needed (including fees), ceiling division
+	const quoteInGross = quoteForSwap
+		.mul(denom)
+		.div(new BN(FEE_RATE_DENOMINATOR - totalFeeRate))
+		.add(new BN(1));
+
+	// Calculate individual fees
+	const lpFee = quoteInGross.mul(new BN(fees.lpFeeRate)).div(denom);
+	const creatorFee = quoteInGross.mul(new BN(fees.creatorFeeRate)).div(denom);
+	const protocolFee = quoteInGross
+		.mul(new BN(fees.protocolFeeRate))
+		.div(denom);
+	const totalFees = lpFee.add(creatorFee).add(protocolFee);
+
+	const quoteIn = quoteInGross.sub(totalFees);
+
+	return {
+		quoteIn,
+		quoteInGross,
+		lpFee,
+		creatorFee,
+		protocolFee,
+		totalFees,
+	};
+};
+
+/**
+ * Converts LP tokens to the equivalent base and quote token amounts.
+ *
+ * @param lpAmount - LP tokens to convert
+ * @param lpSupply - Total LP supply
+ * @param baseVault - Base vault balance
+ * @param quoteVault - Quote vault balance
+ * @param roundUp - Use ceiling division (for deposits) vs floor division (for withdrawals)
+ * @returns Equivalent base and quote token amounts for the given LP tokens
+ */
+export const calculateLpToTokens = (
+	lpAmount: BN,
+	lpSupply: BN,
+	baseVault: BN,
+	quoteVault: BN,
+	roundUp: boolean = false
+): LpTokenAmounts => {
+	let baseAmount: BN;
+	let quoteAmount: BN;
+
+	if (roundUp) {
+		// Ceiling division for deposits (require slightly more from user)
+		baseAmount = lpAmount
+			.mul(baseVault)
+			.add(lpSupply)
+			.sub(new BN(1))
+			.div(lpSupply);
+		quoteAmount = lpAmount
+			.mul(quoteVault)
+			.add(lpSupply)
+			.sub(new BN(1))
+			.div(lpSupply);
+	} else {
+		// Floor division for withdrawals (give slightly less to user)
+		baseAmount = lpAmount.mul(baseVault).div(lpSupply);
+		quoteAmount = lpAmount.mul(quoteVault).div(lpSupply);
+	}
+
+	return { baseAmount, quoteAmount };
+};

package/src/math/bonding-curve.ts

@@ -0,0 +1,122 @@
+import BN from "bn.js";
+import type { BondingCurveBuyResult, BondingCurveSellResult } from "../types.js";
+import { calculateFees, type FeeConfig } from "./fees.js";
+
+/**
+ * Calculates expected output for a buy transaction on the bonding curve.
+ * Uses constant product formula: k = virtualQuote * virtualToken
+ *
+ * @param amountInGross - Total quote amount the user is spending (before fees)
+ * @param curveState - Current curve reserves
+ * @param config - Fee configuration
+ * @param hasCreatorRef - Whether the creator has a referrer
+ * @param hasTraderRef - Whether the trader has a referrer
+ * @returns Buy result with tokens out, new reserves, net amount, and fee breakdown
+ */
+export const calculateBuyExpectation = (
+	amountInGross: BN,
+	curveState: { virtualQuoteReserves: BN; virtualTokenReserves: BN },
+	config: FeeConfig,
+	hasCreatorRef: boolean,
+	hasTraderRef: boolean
+): BondingCurveBuyResult => {
+	const fees = calculateFees(
+		amountInGross,
+		config,
+		hasCreatorRef,
+		hasTraderRef
+	);
+
+	// Net quote amount that goes into the curve after fees
+	const amountInNet = amountInGross.sub(fees.totalFees);
+
+	// Constant product: k = x * y
+	const k = curveState.virtualQuoteReserves.mul(
+		curveState.virtualTokenReserves
+	);
+
+	// New quote reserves after adding net amount
+	const newVirtualQuote = curveState.virtualQuoteReserves.add(amountInNet);
+
+	// Solve for new token reserves: newToken = k / newQuote + 1 (ceiling division)
+	const newVirtualToken = k.div(newVirtualQuote).add(new BN(1));
+
+	// Tokens out = difference in token reserves
+	const tokensOut = curveState.virtualTokenReserves.sub(newVirtualToken);
+
+	// On-chain, protocol fee is only reduced by referral amounts that are
+	// actually transferred. These helpers assume referrals succeed, so
+	// subtract them to match the expected on-chain protocol fee.
+	const effectiveProtocolFee = fees.protocolFee
+		.sub(fees.creatorReferralFee)
+		.sub(fees.traderReferralFee);
+
+	return {
+		...fees,
+		protocolFee: effectiveProtocolFee,
+		tokensOut,
+		newVirtualQuote,
+		newVirtualToken,
+		amountInNet,
+	};
+};
+
+/**
+ * Calculates expected output for a sell transaction on the bonding curve.
+ * Uses constant product formula: k = virtualQuote * virtualToken
+ *
+ * @param amountInTokens - Amount of tokens to sell
+ * @param curveState - Current curve reserves
+ * @param config - Fee configuration
+ * @param hasCreatorRef - Whether the creator has a referrer
+ * @param hasTraderRef - Whether the trader has a referrer
+ * @returns Sell result with quote out (gross/net), new reserves, and fee breakdown
+ */
+export const calculateSellExpectation = (
+	amountInTokens: BN,
+	curveState: { virtualQuoteReserves: BN; virtualTokenReserves: BN },
+	config: FeeConfig,
+	hasCreatorRef: boolean,
+	hasTraderRef: boolean
+): BondingCurveSellResult => {
+	// Constant product: k = x * y
+	const k = curveState.virtualQuoteReserves.mul(
+		curveState.virtualTokenReserves
+	);
+
+	// New token reserves after adding sold tokens
+	const newVirtualToken = curveState.virtualTokenReserves.add(amountInTokens);
+
+	// Solve for new quote reserves: newQuote = k / newToken + 1 (ceiling division)
+	const newVirtualQuote = k.div(newVirtualToken).add(new BN(1));
+
+	// Gross quote out (before fees)
+	const quoteOutGross = curveState.virtualQuoteReserves.sub(newVirtualQuote);
+
+	// Calculate fees on gross amount
+	const fees = calculateFees(
+		quoteOutGross,
+		config,
+		hasCreatorRef,
+		hasTraderRef
+	);
+
+	// Net quote amount user receives
+	const quoteOutNet = quoteOutGross.sub(fees.totalFees);
+
+	// On-chain, protocol fee is only reduced by referral amounts that are
+	// actually transferred. These helpers assume referrals succeed, so
+	// subtract them to match the expected on-chain protocol fee.
+	const effectiveProtocolFee = fees.protocolFee
+		.sub(fees.creatorReferralFee)
+		.sub(fees.traderReferralFee);
+
+	return {
+		...fees,
+		protocolFee: effectiveProtocolFee,
+		quoteOutGross,
+		quoteOutNet,
+		newVirtualQuote,
+		newVirtualToken,
+	};
+};

package/src/math/constants.ts

@@ -0,0 +1,19 @@
+import BN from "bn.js";
+
+/** Basis points denominator (10,000 = 100%) */
+export const BPS_DENOMINATOR = 10_000;
+
+/** Fee rate denominator for AMM (same as BPS) */
+export const FEE_RATE_DENOMINATOR = 10_000;
+
+/** Q32 constant for fixed-point oracle math (2^32) */
+export const Q32 = new BN(1).shln(32);
+
+/** Number of oracle observations stored */
+export const OBSERVATION_NUM = 100;
+
+/** Default oracle update duration in seconds */
+export const OBSERVATION_UPDATE_DURATION_DEFAULT = 15;
+
+/** Minimum rent-exempt balance for a 0-byte account */
+export const MIN_VAULT_BALANCE = 890_880;

package/src/math/fees.ts

@@ -0,0 +1,191 @@
+import BN from "bn.js";
+import type { PublicKey } from "@solana/web3.js";
+import { BPS_DENOMINATOR, MIN_VAULT_BALANCE } from "./constants.js";
+import type {
+	FeeDistribution,
+	FeeRecipient,
+	DistributionResult,
+} from "../types.js";
+
+/**
+ * Calculates basis points of an amount.
+ * result = (amount * bps) / 10000
+ *
+ * @param amount - The amount to calculate basis points of
+ * @param bps - Basis points (1 bps = 0.01%)
+ * @returns The calculated portion
+ */
+export const calcBps = (amount: BN, bps: number): BN =>
+	amount.mul(new BN(bps)).div(new BN(BPS_DENOMINATOR));
+
+/**
+ * Fee configuration for bonding curve trades.
+ */
+export interface FeeConfig {
+	protocolFeeBps: number;
+	creatorFeeBps: number;
+	creatorReferralBps: number;
+	traderReferralBps: number;
+}
+
+/**
+ * Calculates fee distribution for a given trade amount.
+ * Referral fees are carved from the protocol fee, not the trade amount.
+ *
+ * @param amount - Gross trade amount (before fees)
+ * @param config - Fee configuration in basis points
+ * @param hasCreatorRef - Whether the creator has a referrer
+ * @param hasTraderRef - Whether the trader has a referrer
+ * @returns Fee distribution breakdown
+ */
+export const calculateFees = (
+	amount: BN,
+	config: FeeConfig,
+	hasCreatorRef: boolean,
+	hasTraderRef: boolean
+): FeeDistribution => {
+	const baseProtocolFee = calcBps(amount, config.protocolFeeBps);
+	const creatorFee = calcBps(amount, config.creatorFeeBps);
+
+	// Referral amounts are BPS of the protocol fee (not trade amount)
+	const creatorReferralFee = hasCreatorRef
+		? calcBps(baseProtocolFee, config.creatorReferralBps)
+		: new BN(0);
+	const traderReferralFee = hasTraderRef
+		? calcBps(baseProtocolFee, config.traderReferralBps)
+		: new BN(0);
+
+	// Protocol fee starts at base amount. On-chain, it is only reduced
+	// when referral transfers actually succeed.
+	const protocolFee = baseProtocolFee;
+	// Referrals are carved from protocol fee (not additive), so total = protocol + creator.
+	const totalFees = protocolFee.add(creatorFee);
+
+	return {
+		protocolFee,
+		creatorFee,
+		creatorReferralFee,
+		traderReferralFee,
+		totalFees,
+	};
+};
+
+/**
+ * Calculates expected distribution amounts for each fee recipient.
+ * Distributable = vaultBalance - MIN_VAULT_BALANCE (rent).
+ *
+ * @param vaultBalance - Current vault balance in lamports
+ * @param recipients - Fee recipients with basis point allocations
+ * @returns Distribution amounts per recipient
+ */
+export const calculateDistribution = (
+	vaultBalance: number,
+	recipients: FeeRecipient[]
+): DistributionResult[] => {
+	const distributable = Math.max(0, vaultBalance - MIN_VAULT_BALANCE);
+	return recipients.map((r) => ({
+		pubkey: r.pubkey,
+		amount: Math.floor((distributable * r.basisPoints) / BPS_DENOMINATOR),
+	}));
+};
+
+/**
+ * Calculates total distribution (sum of all recipient amounts).
+ *
+ * @param vaultBalance - Current vault balance in lamports
+ * @param recipients - Fee recipients with basis point allocations
+ * @returns Total amount distributed across all recipients
+ */
+export const calculateTotalDistribution = (
+	vaultBalance: number,
+	recipients: FeeRecipient[]
+): number => {
+	return calculateDistribution(vaultBalance, recipients).reduce(
+		(sum, r) => sum + r.amount,
+		0
+	);
+};
+
+/**
+ * Calculates dust remaining after distribution (due to integer rounding).
+ *
+ * @param vaultBalance - Current vault balance in lamports
+ * @param recipients - Fee recipients with basis point allocations
+ * @returns Undistributed lamports remaining in the vault
+ */
+export const calculateDistributionDust = (
+	vaultBalance: number,
+	recipients: FeeRecipient[]
+): number => {
+	const distributable = Math.max(0, vaultBalance - MIN_VAULT_BALANCE);
+	const totalDistributed = calculateTotalDistribution(
+		vaultBalance,
+		recipients
+	);
+	return distributable - totalDistributed;
+};
+
+/**
+ * Creates a recipients array from pubkeys and basis points.
+ *
+ * @param pubkeys - Recipient public keys
+ * @param bpsArray - Basis point allocations (must match pubkeys length)
+ * @returns Array of fee recipients
+ */
+export const createRecipients = (
+	pubkeys: PublicKey[],
+	bpsArray: number[]
+): FeeRecipient[] => {
+	if (pubkeys.length !== bpsArray.length) {
+		throw new Error("pubkeys and bpsArray must have the same length");
+	}
+	return pubkeys.map((pubkey, i) => ({
+		pubkey,
+		basisPoints: bpsArray[i],
+	}));
+};
+
+/**
+ * Creates equal-share recipients (auto-calculates BPS to sum to 10,000).
+ *
+ * @param count - Number of recipients
+ * @param pubkeys - Recipient public keys (must have at least `count` entries)
+ * @returns Array of fee recipients with equal allocations
+ */
+export const createEqualRecipients = (
+	count: number,
+	pubkeys: PublicKey[]
+): FeeRecipient[] => {
+	if (pubkeys.length < count) {
+		throw new Error(
+			`Need at least ${count} pubkeys, got ${pubkeys.length}`
+		);
+	}
+	const bpsPerRecipient = Math.floor(BPS_DENOMINATOR / count);
+	const remainder = BPS_DENOMINATOR % count;
+	return pubkeys.slice(0, count).map((pubkey, i) => ({
+		pubkey,
+		basisPoints: i === 0 ? bpsPerRecipient + remainder : bpsPerRecipient,
+	}));
+};
+
+/**
+ * Creates a single recipient with 100% allocation.
+ *
+ * @param pubkey - Recipient public key
+ * @returns Array with a single fee recipient at 10,000 BPS
+ */
+export const createSingleRecipient = (pubkey: PublicKey): FeeRecipient[] => {
+	return [{ pubkey, basisPoints: BPS_DENOMINATOR }];
+};
+
+/**
+ * Validates that recipients sum to exactly 10,000 BPS.
+ *
+ * @param recipients - Fee recipients to validate
+ * @returns True if basis points sum to exactly 10,000
+ */
+export const validateRecipientsSum = (recipients: FeeRecipient[]): boolean => {
+	const sum = recipients.reduce((acc, r) => acc + r.basisPoints, 0);
+	return sum === BPS_DENOMINATOR;
+};

package/src/math/index.ts

@@ -0,0 +1,40 @@
+export {
+	BPS_DENOMINATOR,
+	FEE_RATE_DENOMINATOR,
+	Q32,
+	OBSERVATION_NUM,
+	OBSERVATION_UPDATE_DURATION_DEFAULT,
+	MIN_VAULT_BALANCE,
+} from "./constants.js";
+
+export {
+	calcBps,
+	calculateFees,
+	calculateDistribution,
+	calculateTotalDistribution,
+	calculateDistributionDust,
+	createRecipients,
+	createEqualRecipients,
+	createSingleRecipient,
+	validateRecipientsSum,
+} from "./fees.js";
+export type { FeeConfig } from "./fees.js";
+
+export {
+	calculateBuyExpectation,
+	calculateSellExpectation,
+} from "./bonding-curve.js";
+
+export {
+	calculateAmmSellOutput,
+	calculateAmmBuyInput,
+	calculateLpToTokens,
+} from "./amm.js";
+export type { AmmFeeRates } from "./amm.js";
+
+export {
+	calculatePoolMarketCap,
+	lookupFeeTier,
+	calculateFeesForPool,
+	WSOL_MINT,
+} from "./tiered-fees.js";