@liquid-af/sdk 0.1.0

package/src/instructions/liquid.ts

@@ -0,0 +1,884 @@
+import type {
+	Connection,
+	PublicKey,
+	TransactionInstruction,
+} from "@solana/web3.js";
+import {
+	getAssociatedTokenAddressSync,
+	TOKEN_PROGRAM_ID,
+} from "@solana/spl-token";
+import type BN from "bn.js";
+import { WSOL_MINT, type LiquidConfig } from "../config.js";
+import {
+	getBondingCurvePDA,
+	getBondingCurveTokenAccount,
+	getStableBondingCurvePDA,
+} from "../pda/liquid.js";
+import { getUserPropertiesPDA, getTokenVolumePDA } from "../pda/liquid-state.js";
+import {
+	getPoolPDA,
+	getPoolLpMintPDA,
+	getPoolVaultPDA,
+	getObservationPDA,
+	getSwapGlobalConfigPDA,
+	getSwapAuthorityPDA,
+	getSwapBuybackVaultPDA,
+} from "../pda/liquid-swap.js";
+import { getCachedLiquidProgram } from "./program-cache.js";
+import {
+	fetchNativeBondingCurve,
+	fetchStableBondingCurve,
+} from "../accounts/liquid.js";
+export interface BuildCreateNativeCurveParams {
+	creator: PublicKey;
+	mint: PublicKey;
+	pythPriceFeed: PublicKey;
+	name: string;
+	symbol: string;
+	uri: string;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a createNativeCurve instruction.
+ * The mint Keypair must be passed as a signer when sending the transaction.
+ * Atomically initializes the fee configuration via CPI to liquid-fees
+ * with the creator as the sole recipient (100%). Use `buildUpdateFeeConfig`
+ * to set custom recipients afterward.
+ *
+ * @param params - {@link BuildCreateNativeCurveParams}
+ * @returns Transaction instruction
+ */
+export function buildCreateNativeCurve(
+	params: BuildCreateNativeCurveParams
+): Promise<TransactionInstruction> {
+	const { creator, mint, pythPriceFeed, name, symbol, uri, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	const bondingCurveTokenAccount = getBondingCurveTokenAccount(
+		mint,
+		config.liquidProgramId
+	);
+	return program.methods
+		.createNativeCurve({
+			name,
+			symbol,
+			uri,
+		})
+		.accounts({
+			creator,
+			mint,
+			pythPriceFeed,
+			bondingCurveTokenAccount,
+		})
+		.instruction();
+}
+
+export interface BuildBumpNativeParams {
+	mint: PublicKey;
+	pythPriceFeed: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a bumpNative instruction.
+ * Re-evaluates a native bonding curve's market cap against the current oracle price
+ * and marks it as complete if the threshold is exceeded. Permissionless.
+ *
+ * @param params - {@link BuildBumpNativeParams}
+ * @returns Transaction instruction
+ */
+export function buildBumpNative(
+	params: BuildBumpNativeParams
+): Promise<TransactionInstruction> {
+	const { mint, pythPriceFeed, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	return program.methods
+		.bumpNative()
+		.accounts({
+			mint,
+			pythPriceFeed,
+		})
+		.instruction();
+}
+
+export interface BuildBuyNativeParams {
+	user: PublicKey;
+	mint: PublicKey;
+	creator: PublicKey;
+	pythPriceFeed: PublicKey;
+	amountIn: BN;
+	minAmountOut: BN;
+	feeRecipient: PublicKey;
+	creatorReferralVault?: PublicKey | null;
+	traderReferralVault?: PublicKey | null;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a buyNative instruction.
+ * Requires the bonding curve creator and Pyth price feed to be known.
+ *
+ * @param params - {@link BuildBuyNativeParams}
+ * @returns Transaction instruction
+ */
+export function buildBuyNative(
+	params: BuildBuyNativeParams
+): Promise<TransactionInstruction> {
+	const {
+		user,
+		mint,
+		creator,
+		pythPriceFeed,
+		amountIn,
+		minAmountOut,
+		feeRecipient,
+		creatorReferralVault,
+		traderReferralVault,
+		config,
+	} = params;
+
+	const program = getCachedLiquidProgram(config);
+
+	// Derive creator-related accounts that Anchor can't auto-resolve
+	const [creatorUserProperties] = getUserPropertiesPDA(
+		creator,
+		config.liquidStateProgramId
+	);
+
+	return program.methods
+		.buyNative(amountIn, minAmountOut)
+		.accountsPartial({
+			user,
+			feeRecipient,
+			mint,
+			pythPriceFeed,
+			creatorUserProperties,
+			creatorReferralVault: creatorReferralVault ?? null,
+			traderReferralVault: traderReferralVault ?? null,
+			liquidState: {
+				user,
+				tokenMint: mint,
+			},
+		})
+		.instruction();
+}
+
+/**
+ * Builds a buyNative instruction, automatically fetching the bonding curve
+ * creator from chain. Convenience wrapper around `buildBuyNative`.
+ *
+ * @param connection - Solana RPC connection
+ * @param params - {@link BuildBuyNativeParams} without `creator`
+ * @returns Transaction instruction
+ */
+export async function buildBuyNativeAutoResolve(
+	connection: Connection,
+	params: Omit<BuildBuyNativeParams, "creator">
+): Promise<TransactionInstruction> {
+	const curve = await fetchNativeBondingCurve(
+		connection,
+		params.mint,
+		params.config
+	);
+	return buildBuyNative({
+		...params,
+		creator: curve.creator,
+		pythPriceFeed: params.pythPriceFeed,
+	});
+}
+
+export interface BuildSellNativeParams {
+	user: PublicKey;
+	mint: PublicKey;
+	creator: PublicKey;
+	pythPriceFeed: PublicKey;
+	amountIn: BN;
+	minAmountOut: BN;
+	feeRecipient: PublicKey;
+	creatorReferralVault?: PublicKey | null;
+	traderReferralVault?: PublicKey | null;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a sellNative instruction.
+ * Requires the bonding curve creator and Pyth price feed to be known.
+ *
+ * @param params - {@link BuildSellNativeParams}
+ * @returns Transaction instruction
+ */
+export function buildSellNative(
+	params: BuildSellNativeParams
+): Promise<TransactionInstruction> {
+	const {
+		user,
+		mint,
+		creator,
+		pythPriceFeed,
+		amountIn,
+		minAmountOut,
+		feeRecipient,
+		creatorReferralVault,
+		traderReferralVault,
+		config,
+	} = params;
+
+	const program = getCachedLiquidProgram(config);
+
+	// Derive creator-related accounts that Anchor can't auto-resolve
+	const [creatorUserProperties] = getUserPropertiesPDA(
+		creator,
+		config.liquidStateProgramId
+	);
+
+	return program.methods
+		.sellNative(amountIn, minAmountOut)
+		.accountsPartial({
+			user,
+			feeRecipient,
+			mint,
+			pythPriceFeed,
+			creatorUserProperties,
+			creatorReferralVault: creatorReferralVault ?? null,
+			traderReferralVault: traderReferralVault ?? null,
+			liquidState: {
+				user,
+				tokenMint: mint,
+			},
+		})
+		.instruction();
+}
+
+/**
+ * Builds a sellNative instruction, automatically fetching the bonding curve
+ * creator from chain. Convenience wrapper around `buildSellNative`.
+ *
+ * @param connection - Solana RPC connection
+ * @param params - {@link BuildSellNativeParams} without `creator`
+ * @returns Transaction instruction
+ */
+export async function buildSellNativeAutoResolve(
+	connection: Connection,
+	params: Omit<BuildSellNativeParams, "creator">
+): Promise<TransactionInstruction> {
+	const curve = await fetchNativeBondingCurve(
+		connection,
+		params.mint,
+		params.config
+	);
+	return buildSellNative({
+		...params,
+		creator: curve.creator,
+		pythPriceFeed: params.pythPriceFeed,
+	});
+}
+
+export interface BuildMigrateNativeParams {
+	migrator: PublicKey;
+	mint: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a migrate instruction (bonding curve -> AMM pool).
+ * Permissionless — anyone can trigger migration once the curve is complete.
+ *
+ * @param params - {@link BuildMigrateNativeParams}
+ * @returns Transaction instruction
+ */
+export function buildMigrateNative(
+	params: BuildMigrateNativeParams
+): Promise<TransactionInstruction> {
+	const { migrator, mint, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	// Derive AMM PDAs
+	const [bondingCurve] = getBondingCurvePDA(mint, config.liquidProgramId);
+	const [ammPoolState] = getPoolPDA(
+		mint,
+		WSOL_MINT,
+		config.liquidSwapProgramId
+	);
+	const [ammLpMint] = getPoolLpMintPDA(
+		ammPoolState,
+		config.liquidSwapProgramId
+	);
+	const [ammBaseVault] = getPoolVaultPDA(
+		ammPoolState,
+		mint,
+		config.liquidSwapProgramId
+	);
+	const [ammQuoteVault] = getPoolVaultPDA(
+		ammPoolState,
+		WSOL_MINT,
+		config.liquidSwapProgramId
+	);
+	const [ammObservationState] = getObservationPDA(
+		ammPoolState,
+		config.liquidSwapProgramId
+	);
+	const [ammGlobalConfig] = getSwapGlobalConfigPDA(
+		config.liquidSwapProgramId
+	);
+	const [ammAuthority] = getSwapAuthorityPDA(config.liquidSwapProgramId);
+	const [tokenVolume] = getTokenVolumePDA(mint, config.liquidStateProgramId);
+	const bondingCurveLpToken = getAssociatedTokenAddressSync(
+		ammLpMint,
+		bondingCurve,
+		true,
+		TOKEN_PROGRAM_ID
+	);
+	const [ammBuybackVault] = getSwapBuybackVaultPDA(
+		ammPoolState,
+		WSOL_MINT,
+		config.liquidSwapProgramId
+	);
+	return program.methods
+		.migrate()
+		.accounts({
+			signer: migrator,
+			mint,
+			ammPoolState,
+			ammLpMint,
+			ammBaseVault,
+			ammQuoteVault,
+			ammObservationState,
+			ammGlobalConfig,
+			ammAuthority,
+			bondingCurveLpToken,
+			tokenVolume,
+			ammBuybackVault,
+		})
+		.instruction();
+}
+
+export interface BuildInitializeNativeReferralVaultParams {
+	user: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an initializeNativeReferralVault instruction (creates native SOL referral vault).
+ *
+ * @param params - {@link BuildInitializeNativeReferralVaultParams}
+ * @returns Transaction instruction
+ */
+export function buildInitializeNativeReferralVault(
+	params: BuildInitializeNativeReferralVaultParams
+): Promise<TransactionInstruction> {
+	const { user, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	return program.methods
+		.initializeNativeReferralVault()
+		.accounts({ user })
+		.instruction();
+}
+
+export interface BuildWithdrawReferralRewardsParams {
+	user: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a withdrawReferralRewards instruction.
+ *
+ * @param params - {@link BuildWithdrawReferralRewardsParams}
+ * @returns Transaction instruction
+ */
+export function buildWithdrawReferralRewards(
+	params: BuildWithdrawReferralRewardsParams
+): Promise<TransactionInstruction> {
+	const { user, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	return program.methods
+		.withdrawReferralRewards()
+		.accounts({ user })
+		.instruction();
+}
+
+export interface BuildExecuteBuybackNativeParams {
+	payer: PublicKey;
+	mint: PublicKey;
+	pythPriceFeed: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an executeBuybackNative instruction for a native SOL bonding curve.
+ * Permissionless — anyone can trigger. Only works when fee config is Revoked.
+ *
+ * @param params - {@link BuildExecuteBuybackNativeParams}
+ * @returns Transaction instruction
+ */
+export function buildExecuteBuybackNative(
+	params: BuildExecuteBuybackNativeParams
+): Promise<TransactionInstruction> {
+	const { payer, mint, pythPriceFeed, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	return program.methods
+		.executeBuybackNative()
+		.accountsPartial({
+			payer,
+			mint,
+			pythPriceFeed,
+		})
+		.instruction();
+}
+
+export interface BuildExecuteBuybackTokenParams {
+	payer: PublicKey;
+	mint: PublicKey;
+	quoteMint: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an executeBuybackToken instruction for a token-based bonding curve.
+ * Permissionless — anyone can trigger. Only works when fee config is Revoked.
+ *
+ * @param params - {@link BuildExecuteBuybackTokenParams}
+ * @returns Transaction instruction
+ */
+export function buildExecuteBuybackToken(
+	params: BuildExecuteBuybackTokenParams
+): Promise<TransactionInstruction> {
+	const { payer, mint, quoteMint, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	return program.methods
+		.executeBuybackToken()
+		.accountsPartial({
+			payer,
+			mint,
+			quoteMint,
+		})
+		.instruction();
+}
+
+export interface BuildCreateStableCurveParams {
+	creator: PublicKey;
+	mint: PublicKey;
+	quoteMint: PublicKey;
+	name: string;
+	symbol: string;
+	uri: string;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a createStableCurve instruction.
+ * Creates a token-based bonding curve (e.g., using USDC as quote).
+ * The mint Keypair must be passed as a signer when sending the transaction.
+ * Atomically initializes the fee configuration via CPI to liquid-fees
+ * with the creator as the sole recipient (100%). Use `buildUpdateFeeConfig`
+ * to set custom recipients afterward.
+ *
+ * @param params - {@link BuildCreateStableCurveParams}
+ * @returns Transaction instruction
+ */
+export function buildCreateStableCurve(
+	params: BuildCreateStableCurveParams
+): Promise<TransactionInstruction> {
+	const { creator, mint, quoteMint, name, symbol, uri, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	return program.methods
+		.createStableCurve({
+			name,
+			symbol,
+			uri,
+		})
+		.accounts({
+			creator,
+			mint,
+			quoteMint,
+		})
+		.instruction();
+}
+
+export interface BuildBuyStableParams {
+	user: PublicKey;
+	mint: PublicKey;
+	quoteMint: PublicKey;
+	creator: PublicKey;
+	amountIn: BN;
+	minAmountOut: BN;
+	feeRecipient: PublicKey;
+	creatorReferralVault?: PublicKey | null;
+	traderReferralVault?: PublicKey | null;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a buyStable instruction.
+ * Buys tokens from a token-based bonding curve using quote tokens (e.g., USDC).
+ *
+ * @param params - {@link BuildBuyStableParams}
+ * @returns Transaction instruction
+ */
+export function buildBuyStable(
+	params: BuildBuyStableParams
+): Promise<TransactionInstruction> {
+	const {
+		user,
+		mint,
+		quoteMint,
+		creator,
+		amountIn,
+		minAmountOut,
+		feeRecipient,
+		creatorReferralVault,
+		traderReferralVault,
+		config,
+	} = params;
+
+	const program = getCachedLiquidProgram(config);
+
+	// Fee recipient quote token account
+	const feeRecipientQuoteAccount = getAssociatedTokenAddressSync(
+		quoteMint,
+		feeRecipient,
+		true,
+		TOKEN_PROGRAM_ID
+	);
+
+	// Derive creator-related accounts that Anchor can't auto-resolve
+	const [creatorUserProperties] = getUserPropertiesPDA(
+		creator,
+		config.liquidStateProgramId
+	);
+
+	return program.methods
+		.buyStable(amountIn, minAmountOut)
+		.accountsPartial({
+			user,
+			mint,
+			quoteMint,
+			feeRecipient: feeRecipientQuoteAccount,
+			creatorUserProperties,
+			creatorReferralVault: creatorReferralVault ?? null,
+			traderReferralVault: traderReferralVault ?? null,
+			liquidState: {
+				user,
+				tokenMint: mint,
+			},
+		})
+		.instruction();
+}
+
+/**
+ * Builds a buyStable instruction, automatically fetching the bonding curve
+ * creator from chain. Convenience wrapper around `buildBuyStable`.
+ *
+ * @param connection - Solana RPC connection
+ * @param params - {@link BuildBuyStableParams} without `creator`
+ * @returns Transaction instruction
+ */
+export async function buildBuyStableAutoResolve(
+	connection: Connection,
+	params: Omit<BuildBuyStableParams, "creator">
+): Promise<TransactionInstruction> {
+	const curve = await fetchStableBondingCurve(
+		connection,
+		params.mint,
+		params.quoteMint,
+		params.config
+	);
+	return buildBuyStable({ ...params, creator: curve.creator });
+}
+
+export interface BuildSellStableParams {
+	user: PublicKey;
+	mint: PublicKey;
+	quoteMint: PublicKey;
+	creator: PublicKey;
+	amountIn: BN;
+	minAmountOut: BN;
+	feeRecipient: PublicKey;
+	creatorReferralVault?: PublicKey | null;
+	traderReferralVault?: PublicKey | null;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a sellStable instruction.
+ * Sells tokens to a token-based bonding curve for quote tokens (e.g., USDC).
+ *
+ * @param params - {@link BuildSellStableParams}
+ * @returns Transaction instruction
+ */
+export function buildSellStable(
+	params: BuildSellStableParams
+): Promise<TransactionInstruction> {
+	const {
+		user,
+		mint,
+		quoteMint,
+		creator,
+		amountIn,
+		minAmountOut,
+		feeRecipient,
+		creatorReferralVault,
+		traderReferralVault,
+		config,
+	} = params;
+
+	const program = getCachedLiquidProgram(config);
+
+	// Fee recipient quote token account
+	const feeRecipientQuoteAccount = getAssociatedTokenAddressSync(
+		quoteMint,
+		feeRecipient,
+		true,
+		TOKEN_PROGRAM_ID
+	);
+
+	// Derive creator-related accounts that Anchor can't auto-resolve
+	const [creatorUserProperties] = getUserPropertiesPDA(
+		creator,
+		config.liquidStateProgramId
+	);
+
+	return program.methods
+		.sellStable(amountIn, minAmountOut)
+		.accountsPartial({
+			user,
+			mint,
+			quoteMint,
+			feeRecipient: feeRecipientQuoteAccount,
+			creatorUserProperties,
+			creatorReferralVault: creatorReferralVault ?? null,
+			traderReferralVault: traderReferralVault ?? null,
+			liquidState: {
+				user,
+				tokenMint: mint,
+			},
+		})
+		.instruction();
+}
+
+/**
+ * Builds a sellStable instruction, automatically fetching the bonding curve
+ * creator from chain. Convenience wrapper around `buildSellStable`.
+ *
+ * @param connection - Solana RPC connection
+ * @param params - {@link BuildSellStableParams} without `creator`
+ * @returns Transaction instruction
+ */
+export async function buildSellStableAutoResolve(
+	connection: Connection,
+	params: Omit<BuildSellStableParams, "creator">
+): Promise<TransactionInstruction> {
+	const curve = await fetchStableBondingCurve(
+		connection,
+		params.mint,
+		params.quoteMint,
+		params.config
+	);
+	return buildSellStable({ ...params, creator: curve.creator });
+}
+
+export interface BuildMigrateStableParams {
+	migrator: PublicKey;
+	mint: PublicKey;
+	quoteMint: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a migrateStable instruction (token bonding curve -> AMM pool).
+ * Permissionless — anyone can trigger migration once the curve is complete.
+ *
+ * @param params - {@link BuildMigrateStableParams}
+ * @returns Transaction instruction
+ */
+export function buildMigrateStable(
+	params: BuildMigrateStableParams
+): Promise<TransactionInstruction> {
+	const { migrator, mint, quoteMint, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	// Derive AMM PDAs
+	const [bondingCurve] = getStableBondingCurvePDA(
+		mint,
+		quoteMint,
+		config.liquidProgramId
+	);
+	const [ammPoolState] = getPoolPDA(
+		mint,
+		quoteMint,
+		config.liquidSwapProgramId
+	);
+	const [ammLpMint] = getPoolLpMintPDA(
+		ammPoolState,
+		config.liquidSwapProgramId
+	);
+	const [ammBaseVault] = getPoolVaultPDA(
+		ammPoolState,
+		mint,
+		config.liquidSwapProgramId
+	);
+	const [ammQuoteVault] = getPoolVaultPDA(
+		ammPoolState,
+		quoteMint,
+		config.liquidSwapProgramId
+	);
+	const [ammObservationState] = getObservationPDA(
+		ammPoolState,
+		config.liquidSwapProgramId
+	);
+	const [ammGlobalConfig] = getSwapGlobalConfigPDA(
+		config.liquidSwapProgramId
+	);
+	const [ammAuthority] = getSwapAuthorityPDA(config.liquidSwapProgramId);
+	const [tokenVolume] = getTokenVolumePDA(mint, config.liquidStateProgramId);
+	const bondingCurveLpToken = getAssociatedTokenAddressSync(
+		ammLpMint,
+		bondingCurve,
+		true,
+		TOKEN_PROGRAM_ID
+	);
+	const [ammBuybackVault] = getSwapBuybackVaultPDA(
+		ammPoolState,
+		quoteMint,
+		config.liquidSwapProgramId
+	);
+	return program.methods
+		.migrateStable()
+		.accounts({
+			signer: migrator,
+			mint,
+			quoteMint,
+			ammPoolState,
+			ammLpMint,
+			ammBaseVault,
+			ammQuoteVault,
+			ammObservationState,
+			ammGlobalConfig,
+			ammAuthority,
+			bondingCurveLpToken,
+			tokenVolume,
+			ammBuybackVault,
+		})
+		.instruction();
+}
+
+export interface BuildSetFeeRecipientsParams {
+	admin: PublicKey;
+	/** Array of 8 fee recipient pubkeys */
+	feeRecipients: PublicKey[];
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a setFeeRecipients instruction.
+ * Admin-only instruction to set/update the protocol fee recipients.
+ *
+ * @param params - {@link BuildSetFeeRecipientsParams}
+ * @returns Transaction instruction
+ */
+export function buildSetFeeRecipients(
+	params: BuildSetFeeRecipientsParams
+): Promise<TransactionInstruction> {
+	const { admin, feeRecipients, config } = params;
+
+	if (feeRecipients.length !== 8) {
+		throw new Error("feeRecipients must have exactly 8 elements");
+	}
+
+	const program = getCachedLiquidProgram(config);
+
+	return program.methods
+		.setFeeRecipients(feeRecipients)
+		.accounts({
+			admin,
+			feeRecipient1: feeRecipients[0],
+			feeRecipient2: feeRecipients[1],
+			feeRecipient3: feeRecipients[2],
+			feeRecipient4: feeRecipients[3],
+			feeRecipient5: feeRecipients[4],
+			feeRecipient6: feeRecipients[5],
+			feeRecipient7: feeRecipients[6],
+			feeRecipient8: feeRecipients[7],
+		})
+		.instruction();
+}
+
+export interface BuildInitializeFeeRecipientVaultsParams {
+	payer: PublicKey;
+	quoteMint: PublicKey;
+	/** Array of 8 fee recipient pubkeys (must match config) */
+	feeRecipients: PublicKey[];
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an initializeFeeRecipientVaults instruction.
+ * Permissionless instruction to create token accounts for all fee recipients
+ * for a given quote mint. Call this before trading stable curves.
+ *
+ * @param params - {@link BuildInitializeFeeRecipientVaultsParams}
+ * @returns Transaction instruction
+ */
+export function buildInitializeFeeRecipientVaults(
+	params: BuildInitializeFeeRecipientVaultsParams
+): Promise<TransactionInstruction> {
+	const { payer, quoteMint, feeRecipients, config } = params;
+
+	if (feeRecipients.length !== 8) {
+		throw new Error("feeRecipients must have exactly 8 elements");
+	}
+
+	const program = getCachedLiquidProgram(config);
+
+	return program.methods
+		.initializeFeeRecipientVaults()
+		.accounts({
+			payer,
+			quoteMint,
+			feeRecipient1: feeRecipients[0],
+			feeRecipient2: feeRecipients[1],
+			feeRecipient3: feeRecipients[2],
+			feeRecipient4: feeRecipients[3],
+			feeRecipient5: feeRecipients[4],
+			feeRecipient6: feeRecipients[5],
+			feeRecipient7: feeRecipients[6],
+			feeRecipient8: feeRecipients[7],
+		})
+		.instruction();
+}
+
+export interface BuildInitializeReferralTokenVaultParams {
+	user: PublicKey;
+	quoteMint: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an initializeReferralTokenVault instruction.
+ * Creates a referral token vault (ATA) for the user for a specific quote mint.
+ * Users must call this for each quote mint they want to receive referral rewards for.
+ * If not initialized, referral fees will be redirected to protocol fees.
+ *
+ * @param params - {@link BuildInitializeReferralTokenVaultParams}
+ * @returns Transaction instruction
+ */
+export function buildInitializeReferralTokenVault(
+	params: BuildInitializeReferralTokenVaultParams
+): Promise<TransactionInstruction> {
+	const { user, quoteMint, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	return program.methods
+		.initializeReferralTokenVault()
+		.accounts({
+			user,
+			quoteMint,
+		})
+		.instruction();
+}