@liquid-af/sdk 0.1.0

package/src/client.ts

@@ -0,0 +1,1001 @@
+import type {
+	Connection,
+	PublicKey,
+	Transaction,
+	TransactionInstruction,
+} from "@solana/web3.js";
+import type BN from "bn.js";
+import { MAINNET_CONFIG, WSOL_MINT, type LiquidConfig } from "./config.js";
+import type {
+	BuyCurvePreview,
+	SellCurvePreview,
+	SwapPreview,
+	FeeRecipient,
+} from "./types.js";
+import {
+	buildTransaction as buildTransactionFn,
+	type BuildTransactionOptions,
+} from "./transaction/builder.js";
+
+// Instruction builders
+import {
+	buildCreateNativeCurve,
+	buildBuyNative,
+	buildBuyNativeAutoResolve,
+	buildSellNative,
+	buildSellNativeAutoResolve,
+	buildMigrateNative,
+	buildInitializeNativeReferralVault,
+	buildWithdrawReferralRewards,
+	buildExecuteBuybackNative,
+	buildExecuteBuybackToken,
+} from "./instructions/liquid.js";
+import {
+	buildCreatePool,
+	buildSwapBuy,
+	buildSwapSell,
+	buildDeposit,
+	buildWithdraw,
+	buildSwapExecuteBuyback,
+} from "./instructions/liquid-swap.js";
+import {
+	buildUpdateFeeConfig,
+	buildRevokeFeeConfig,
+	buildDistributeFees,
+	buildDistributeTokenFees,
+	buildClaimFees,
+	buildClaimTokenFees,
+	type RecipientVaultPair,
+} from "./instructions/liquid-fees.js";
+import {
+	buildInitializeUser,
+	buildSetReferrer,
+	buildSetCashbackMode,
+	buildTransferAdmin,
+	buildAcceptAdmin,
+	buildCancelAdminTransfer,
+	buildCreateDeal,
+	buildUpdateDeal,
+	buildCloseDeal,
+	buildRedeemDeal,
+	buildTakeSnapshot,
+	buildAdminUpdateUser,
+} from "./instructions/liquid-state.js";
+
+// Account fetchers
+import {
+	fetchLiquidGlobalConfig as fetchLiquidGlobalConfigFn,
+	fetchNativeBondingCurve as fetchNativeBondingCurveFn,
+	fetchNativeBondingCurveByAddress as fetchNativeBondingCurveByAddressFn,
+} from "./accounts/liquid.js";
+import {
+	fetchAmmConfig as fetchAmmConfigFn,
+	fetchPoolState as fetchPoolStateFn,
+	fetchPoolStateByAddress as fetchPoolStateByAddressFn,
+	fetchObservationState as fetchObservationStateFn,
+} from "./accounts/liquid-swap.js";
+import {
+	fetchFeeConfig as fetchFeeConfigFn,
+	fetchFeeConfigByAddress as fetchFeeConfigByAddressFn,
+} from "./accounts/liquid-fees.js";
+import {
+	fetchUserProperties as fetchUserPropertiesFn,
+	fetchTokenVolume as fetchTokenVolumeFn,
+	fetchGlobalCurveVolume as fetchGlobalCurveVolumeFn,
+	fetchGlobalAmmVolume as fetchGlobalAmmVolumeFn,
+	fetchCashbackConfig as fetchCashbackConfigFn,
+	fetchUserSnapshot as fetchUserSnapshotFn,
+	fetchDeal as fetchDealFn,
+} from "./accounts/liquid-state.js";
+
+// Preview helpers
+import {
+	previewBuyOnCurve as previewBuyOnCurveFn,
+	previewSellOnCurve as previewSellOnCurveFn,
+	previewSwapSell as previewSwapSellFn,
+	previewSwapBuy as previewSwapBuyFn,
+	type CurveAsyncOptions,
+	type SwapPrefetchedState,
+} from "./helpers/preview.js";
+
+// PDA helpers
+import {
+	getBondingCurvePDA,
+	getBondingCurveSolVaultPDA,
+	getReferralVaultPDA,
+	getBuybackVaultPDA,
+	getPoolPDA,
+	getPoolLpMintPDA,
+	getPoolVaultPDA,
+	getObservationPDA,
+	getFeeConfigPDA,
+	getFeeVaultPDA,
+	getRecipientVaultPDA,
+	getUserPropertiesPDA,
+	getTokenVolumePDA,
+	getUserSnapshotPDA,
+	getDealPDA,
+	getAllBondingCurvePDAs,
+	getAllPoolPDAs,
+	getMigrationPDAs,
+} from "./pda/index.js";
+
+// Utility
+import { resolveTokenProgram as resolveTokenProgramFn } from "./helpers/user.js";
+
+export interface LiquidClientConfig {
+	connection: Connection;
+	config?: LiquidConfig;
+}
+
+/**
+ * Unified entry point for the Liquid protocol SDK.
+ *
+ * Holds a `Connection` and `LiquidConfig`, removing the need to pass them
+ * to every function call. Auto-resolves token programs and pool PDAs for
+ * AMM operations. All instruction-building methods return unsigned
+ * `TransactionInstruction`s — the caller is responsible for signing.
+ */
+export class LiquidClient {
+	readonly connection: Connection;
+	readonly config: LiquidConfig;
+
+	/**
+	 * @param options - Client configuration with connection and optional protocol config
+	 */
+	constructor({ connection, config = MAINNET_CONFIG }: LiquidClientConfig) {
+		this.connection = connection;
+		this.config = config;
+	}
+
+	/** Builds a createCurve instruction for launching a new token on the bonding curve. */
+	buildCreateCurve(params: {
+		creator: PublicKey;
+		mint: PublicKey;
+		pythPriceFeed: PublicKey;
+		name: string;
+		symbol: string;
+		uri: string;
+	}): Promise<TransactionInstruction> {
+		return buildCreateNativeCurve({ ...params, config: this.config });
+	}
+
+	/** Builds a buyOnCurve instruction. Requires the creator address and Pyth price feed. */
+	buildBuyOnCurve(params: {
+		user: PublicKey;
+		mint: PublicKey;
+		creator: PublicKey;
+		pythPriceFeed: PublicKey;
+		amountIn: BN;
+		minAmountOut: BN;
+		feeRecipient: PublicKey;
+		creatorReferralVault?: PublicKey | null;
+		traderReferralVault?: PublicKey | null;
+	}): Promise<TransactionInstruction> {
+		return buildBuyNative({ ...params, config: this.config });
+	}
+
+	/**
+	 * Like `buildBuyOnCurve` but auto-fetches the bonding curve creator.
+	 */
+	buildBuyOnCurveAutoResolve(params: {
+		user: PublicKey;
+		mint: PublicKey;
+		pythPriceFeed: PublicKey;
+		amountIn: BN;
+		minAmountOut: BN;
+		feeRecipient: PublicKey;
+		creatorReferralVault?: PublicKey | null;
+		traderReferralVault?: PublicKey | null;
+	}): Promise<TransactionInstruction> {
+		return buildBuyNativeAutoResolve(this.connection, {
+			...params,
+			config: this.config,
+		});
+	}
+
+	/** Builds a sellOnCurve instruction. Requires the creator address and Pyth price feed. */
+	buildSellOnCurve(params: {
+		user: PublicKey;
+		mint: PublicKey;
+		creator: PublicKey;
+		pythPriceFeed: PublicKey;
+		amountIn: BN;
+		minAmountOut: BN;
+		feeRecipient: PublicKey;
+		creatorReferralVault?: PublicKey | null;
+		traderReferralVault?: PublicKey | null;
+	}): Promise<TransactionInstruction> {
+		return buildSellNative({ ...params, config: this.config });
+	}
+
+	/**
+	 * Like `buildSellOnCurve` but auto-fetches the bonding curve creator.
+	 */
+	buildSellOnCurveAutoResolve(params: {
+		user: PublicKey;
+		mint: PublicKey;
+		pythPriceFeed: PublicKey;
+		amountIn: BN;
+		minAmountOut: BN;
+		feeRecipient: PublicKey;
+		creatorReferralVault?: PublicKey | null;
+		traderReferralVault?: PublicKey | null;
+	}): Promise<TransactionInstruction> {
+		return buildSellNativeAutoResolve(this.connection, {
+			...params,
+			config: this.config,
+		});
+	}
+
+	/** Builds a migrate instruction (bonding curve → AMM pool). Permissionless once the curve completes. */
+	buildMigrateNative(params: {
+		migrator: PublicKey;
+		mint: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildMigrateNative({ ...params, config: this.config });
+	}
+
+	/** Builds an initializeNativeReferralVault instruction (creates native SOL referral vault). */
+	buildInitializeNativeReferralVault(params: {
+		user: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildInitializeNativeReferralVault({
+			...params,
+			config: this.config,
+		});
+	}
+
+	/** Builds a withdrawReferralRewards instruction. */
+	buildWithdrawReferralRewards(params: {
+		user: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildWithdrawReferralRewards({ ...params, config: this.config });
+	}
+
+	/** Builds an executeBuybackNative instruction for native SOL curves. Permissionless; requires revoked fee config. */
+	buildExecuteBuybackNative(params: {
+		payer: PublicKey;
+		mint: PublicKey;
+		pythPriceFeed: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildExecuteBuybackNative({ ...params, config: this.config });
+	}
+
+	/** Builds an executeBuybackToken instruction for token-based curves. Permissionless; requires revoked fee config. */
+	buildExecuteBuybackToken(params: {
+		payer: PublicKey;
+		mint: PublicKey;
+		quoteMint: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildExecuteBuybackToken({ ...params, config: this.config });
+	}
+
+	/**
+	 * Builds a create pool instruction. Auto-resolves token programs if not provided.
+	 */
+	async buildCreatePool(params: {
+		signer: PublicKey;
+		baseMint: PublicKey;
+		quoteMint?: PublicKey;
+		initAmountBase: BN;
+		initAmountQuote: BN;
+		baseTokenProgram?: PublicKey;
+		quoteTokenProgram?: PublicKey;
+	}): Promise<TransactionInstruction> {
+		const quoteMint = params.quoteMint ?? WSOL_MINT;
+		const [baseTokenProgram, quoteTokenProgram] = await Promise.all([
+			params.baseTokenProgram
+				? Promise.resolve(params.baseTokenProgram)
+				: resolveTokenProgramFn(this.connection, params.baseMint),
+			params.quoteTokenProgram
+				? Promise.resolve(params.quoteTokenProgram)
+				: resolveTokenProgramFn(this.connection, quoteMint),
+		]);
+
+		return buildCreatePool({
+			signer: params.signer,
+			baseMint: params.baseMint,
+			quoteMint,
+			baseTokenProgram,
+			quoteTokenProgram,
+			initAmountBase: params.initAmountBase,
+			initAmountQuote: params.initAmountQuote,
+			config: this.config,
+		});
+	}
+
+	/**
+	 * Builds a buy swap instruction (quote -> base).
+	 * Auto-resolves token programs if not provided. Defaults quoteMint to WSOL.
+	 */
+	async buildSwapBuy(params: {
+		payer: PublicKey;
+		creator: PublicKey;
+		baseMint: PublicKey;
+		quoteMint?: PublicKey;
+		maxAmountIn: BN;
+		amountOut: BN;
+		feeRecipient: PublicKey;
+		baseTokenProgram?: PublicKey;
+		quoteTokenProgram?: PublicKey;
+	}): Promise<TransactionInstruction> {
+		const quoteMint = params.quoteMint ?? WSOL_MINT;
+		const [baseTokenProgram, quoteTokenProgram] = await Promise.all([
+			params.baseTokenProgram
+				? Promise.resolve(params.baseTokenProgram)
+				: resolveTokenProgramFn(this.connection, params.baseMint),
+			params.quoteTokenProgram
+				? Promise.resolve(params.quoteTokenProgram)
+				: resolveTokenProgramFn(this.connection, quoteMint),
+		]);
+
+		return buildSwapBuy({
+			payer: params.payer,
+			creator: params.creator,
+			baseMint: params.baseMint,
+			quoteMint,
+			baseTokenProgram,
+			quoteTokenProgram,
+			maxAmountIn: params.maxAmountIn,
+			amountOut: params.amountOut,
+			feeRecipient: params.feeRecipient,
+			config: this.config,
+		});
+	}
+
+	/**
+	 * Builds a sell swap instruction (base -> quote).
+	 * Auto-resolves token programs if not provided. Defaults quoteMint to WSOL.
+	 */
+	async buildSwapSell(params: {
+		payer: PublicKey;
+		creator: PublicKey;
+		baseMint: PublicKey;
+		quoteMint?: PublicKey;
+		amountIn: BN;
+		minimumAmountOut: BN;
+		feeRecipient: PublicKey;
+		baseTokenProgram?: PublicKey;
+		quoteTokenProgram?: PublicKey;
+	}): Promise<TransactionInstruction> {
+		const quoteMint = params.quoteMint ?? WSOL_MINT;
+		const [baseTokenProgram, quoteTokenProgram] = await Promise.all([
+			params.baseTokenProgram
+				? Promise.resolve(params.baseTokenProgram)
+				: resolveTokenProgramFn(this.connection, params.baseMint),
+			params.quoteTokenProgram
+				? Promise.resolve(params.quoteTokenProgram)
+				: resolveTokenProgramFn(this.connection, quoteMint),
+		]);
+
+		return buildSwapSell({
+			payer: params.payer,
+			creator: params.creator,
+			baseMint: params.baseMint,
+			quoteMint,
+			baseTokenProgram,
+			quoteTokenProgram,
+			amountIn: params.amountIn,
+			minimumAmountOut: params.minimumAmountOut,
+			feeRecipient: params.feeRecipient,
+			config: this.config,
+		});
+	}
+
+	/**
+	 * Builds a deposit (add liquidity) instruction.
+	 * Auto-resolves pool PDAs, vaults, LP mint, and token programs.
+	 * Defaults quoteMint to WSOL.
+	 */
+	async buildDeposit(params: {
+		owner: PublicKey;
+		baseMint: PublicKey;
+		quoteMint?: PublicKey;
+		lpTokenAmount: BN;
+		maximumBaseAmount: BN;
+		maximumQuoteAmount: BN;
+		baseTokenProgram?: PublicKey;
+		quoteTokenProgram?: PublicKey;
+	}): Promise<TransactionInstruction> {
+		const quoteMint = params.quoteMint ?? WSOL_MINT;
+		const [poolAddress] = getPoolPDA(
+			params.baseMint,
+			quoteMint,
+			this.config.liquidSwapProgramId
+		);
+		const [lpMint] = getPoolLpMintPDA(
+			poolAddress,
+			this.config.liquidSwapProgramId
+		);
+		const [baseVault] = getPoolVaultPDA(
+			poolAddress,
+			params.baseMint,
+			this.config.liquidSwapProgramId
+		);
+		const [quoteVault] = getPoolVaultPDA(
+			poolAddress,
+			quoteMint,
+			this.config.liquidSwapProgramId
+		);
+
+		const [baseTokenProgram, quoteTokenProgram] = await Promise.all([
+			params.baseTokenProgram
+				? Promise.resolve(params.baseTokenProgram)
+				: resolveTokenProgramFn(this.connection, params.baseMint),
+			params.quoteTokenProgram
+				? Promise.resolve(params.quoteTokenProgram)
+				: resolveTokenProgramFn(this.connection, quoteMint),
+		]);
+
+		return buildDeposit({
+			owner: params.owner,
+			poolAddress,
+			baseMint: params.baseMint,
+			quoteMint,
+			baseTokenProgram,
+			quoteTokenProgram,
+			baseVault,
+			quoteVault,
+			lpMint,
+			lpTokenAmount: params.lpTokenAmount,
+			maximumBaseAmount: params.maximumBaseAmount,
+			maximumQuoteAmount: params.maximumQuoteAmount,
+			config: this.config,
+		});
+	}
+
+	/**
+	 * Builds a withdraw (remove liquidity) instruction.
+	 * Auto-resolves pool PDAs, vaults, LP mint, and token programs.
+	 * Defaults quoteMint to WSOL.
+	 */
+	async buildWithdraw(params: {
+		owner: PublicKey;
+		baseMint: PublicKey;
+		quoteMint?: PublicKey;
+		lpTokenAmount: BN;
+		minimumBaseAmount: BN;
+		minimumQuoteAmount: BN;
+		baseTokenProgram?: PublicKey;
+		quoteTokenProgram?: PublicKey;
+	}): Promise<TransactionInstruction> {
+		const quoteMint = params.quoteMint ?? WSOL_MINT;
+		const [poolAddress] = getPoolPDA(
+			params.baseMint,
+			quoteMint,
+			this.config.liquidSwapProgramId
+		);
+		const [lpMint] = getPoolLpMintPDA(
+			poolAddress,
+			this.config.liquidSwapProgramId
+		);
+		const [baseVault] = getPoolVaultPDA(
+			poolAddress,
+			params.baseMint,
+			this.config.liquidSwapProgramId
+		);
+		const [quoteVault] = getPoolVaultPDA(
+			poolAddress,
+			quoteMint,
+			this.config.liquidSwapProgramId
+		);
+
+		const [baseTokenProgram, quoteTokenProgram] = await Promise.all([
+			params.baseTokenProgram
+				? Promise.resolve(params.baseTokenProgram)
+				: resolveTokenProgramFn(this.connection, params.baseMint),
+			params.quoteTokenProgram
+				? Promise.resolve(params.quoteTokenProgram)
+				: resolveTokenProgramFn(this.connection, quoteMint),
+		]);
+
+		return buildWithdraw({
+			owner: params.owner,
+			poolAddress,
+			baseMint: params.baseMint,
+			quoteMint,
+			baseTokenProgram,
+			quoteTokenProgram,
+			baseVault,
+			quoteVault,
+			lpMint,
+			lpTokenAmount: params.lpTokenAmount,
+			minimumBaseAmount: params.minimumBaseAmount,
+			minimumQuoteAmount: params.minimumQuoteAmount,
+			config: this.config,
+		});
+	}
+
+	/**
+	 * Builds an executeBuyback instruction for an AMM pool.
+	 * Auto-resolves token programs if not provided. Defaults quoteMint to WSOL.
+	 */
+	async buildSwapExecuteBuyback(params: {
+		payer: PublicKey;
+		baseMint: PublicKey;
+		quoteMint?: PublicKey;
+		baseTokenProgram?: PublicKey;
+		quoteTokenProgram?: PublicKey;
+	}): Promise<TransactionInstruction> {
+		const quoteMint = params.quoteMint ?? WSOL_MINT;
+		const [baseTokenProgram, quoteTokenProgram] = await Promise.all([
+			params.baseTokenProgram
+				? Promise.resolve(params.baseTokenProgram)
+				: resolveTokenProgramFn(this.connection, params.baseMint),
+			params.quoteTokenProgram
+				? Promise.resolve(params.quoteTokenProgram)
+				: resolveTokenProgramFn(this.connection, quoteMint),
+		]);
+
+		return buildSwapExecuteBuyback({
+			payer: params.payer,
+			baseMint: params.baseMint,
+			quoteMint,
+			baseTokenProgram,
+			quoteTokenProgram,
+			config: this.config,
+		});
+	}
+
+	/** Builds an updateFeeConfig instruction. Cannot be called on revoked configs. */
+	buildUpdateFeeConfig(params: {
+		authority: PublicKey;
+		tokenMint: PublicKey;
+		recipients?: FeeRecipient[] | null;
+		newUpdateAuthority?: PublicKey | null;
+		/** Required when changing recipients to verify token fee vault is drained. */
+		quoteMint?: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildUpdateFeeConfig({ ...params, config: this.config });
+	}
+
+	/** Builds a revokeFeeConfig instruction. Permanently sets fee mode to Revoked. Irreversible. */
+	buildRevokeFeeConfig(params: {
+		authority: PublicKey;
+		tokenMint: PublicKey;
+		quoteMint: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildRevokeFeeConfig({ ...params, config: this.config });
+	}
+
+	/** Builds a permissionless distributeFees instruction (SOL fees). */
+	buildDistributeFees(params: {
+		payer: PublicKey;
+		tokenMint: PublicKey;
+		recipientVaults: PublicKey[];
+	}): Promise<TransactionInstruction> {
+		return buildDistributeFees({ ...params, config: this.config });
+	}
+
+	/** Builds a permissionless distributeTokenFees instruction (SPL token fees). */
+	buildDistributeTokenFees(params: {
+		payer: PublicKey;
+		tokenMint: PublicKey;
+		quoteMint: PublicKey;
+		recipientVaultPairs: RecipientVaultPair[];
+	}): Promise<TransactionInstruction> {
+		return buildDistributeTokenFees({ ...params, config: this.config });
+	}
+
+	/** Builds a claimFees instruction. Recipient claims accumulated SOL from their vault PDA. */
+	buildClaimFees(params: {
+		recipient: PublicKey;
+		tokenMint: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildClaimFees({ ...params, config: this.config });
+	}
+
+	/** Builds a claimTokenFees instruction. Recipient claims accumulated tokens from their vault ATA. */
+	buildClaimTokenFees(params: {
+		recipient: PublicKey;
+		tokenMint: PublicKey;
+		quoteMint: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildClaimTokenFees({ ...params, config: this.config });
+	}
+
+	/** Builds an initializeUser instruction. Creates the user properties account. */
+	buildInitializeUser(params: {
+		user: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildInitializeUser({ ...params, config: this.config });
+	}
+
+	/** Builds a setReferrer instruction. One-time operation — referrer cannot be changed. */
+	buildSetReferrer(params: {
+		user: PublicKey;
+		referrer: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildSetReferrer({ ...params, config: this.config });
+	}
+
+	/** Builds a setCashbackMode instruction. Toggles between earning and spending mode. */
+	buildSetCashbackMode(params: {
+		user: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildSetCashbackMode({ ...params, config: this.config });
+	}
+
+	/** Builds a transferAdmin instruction. Proposes admin transfer to a new pubkey (two-step). */
+	buildTransferAdmin(params: {
+		admin: PublicKey;
+		newAdmin: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildTransferAdmin({ ...params, config: this.config });
+	}
+
+	/** Builds an acceptAdmin instruction. Completes a pending admin transfer. */
+	buildAcceptAdmin(params: {
+		newAdmin: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildAcceptAdmin({ ...params, config: this.config });
+	}
+
+	/** Builds a cancelAdminTransfer instruction. Cancels a pending admin transfer. */
+	buildCancelAdminTransfer(params: {
+		authority: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildCancelAdminTransfer({ ...params, config: this.config });
+	}
+
+	/** Builds a createDeal instruction. Admin creates an exclusive deal for a pubkey. */
+	buildCreateDeal(params: {
+		admin: PublicKey;
+		owner: PublicKey;
+		cashbackMultiplierBps: number;
+		payer: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildCreateDeal({ ...params, config: this.config });
+	}
+
+	/** Builds an updateDeal instruction. Admin updates a deal's cashback multiplier. */
+	buildUpdateDeal(params: {
+		admin: PublicKey;
+		dealOwner: PublicKey;
+		newCashbackMultiplierBps: number;
+	}): Promise<TransactionInstruction> {
+		return buildUpdateDeal({ ...params, config: this.config });
+	}
+
+	/** Builds a closeDeal instruction. Admin closes/deletes a deal, returning rent. */
+	buildCloseDeal(params: {
+		admin: PublicKey;
+		dealOwner: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildCloseDeal({ ...params, config: this.config });
+	}
+
+	/** Builds a redeemDeal instruction. User redeems their referrer's deal. */
+	buildRedeemDeal(params: {
+		user: PublicKey;
+		dealOwner: PublicKey;
+	}): Promise<TransactionInstruction> {
+		return buildRedeemDeal({ ...params, config: this.config });
+	}
+
+	/** Builds a takeSnapshot instruction. Admin takes a snapshot of a user's volume. */
+	buildTakeSnapshot(params: {
+		admin: PublicKey;
+		user: PublicKey;
+		payer: PublicKey;
+		snapshotIndex: number;
+	}): Promise<TransactionInstruction> {
+		return buildTakeSnapshot({ ...params, config: this.config });
+	}
+
+	/** Builds an adminUpdateUser instruction. Admin updates a user's referrer/multiplier and takes a snapshot. */
+	buildAdminUpdateUser(params: {
+		admin: PublicKey;
+		user: PublicKey;
+		payer: PublicKey;
+		newReferrer: PublicKey | null;
+		newCashbackMultiplierBps: number | null;
+		snapshotIndex: number;
+	}): Promise<TransactionInstruction> {
+		return buildAdminUpdateUser({ ...params, config: this.config });
+	}
+
+	/** Fetches the global configuration for the bonding curve program. */
+	fetchLiquidGlobalConfig() {
+		return fetchLiquidGlobalConfigFn(this.connection, this.config);
+	}
+
+	/** Fetches a bonding curve account by token mint. */
+	fetchNativeBondingCurve(mint: PublicKey) {
+		return fetchNativeBondingCurveFn(this.connection, mint, this.config);
+	}
+
+	/** Fetches a bonding curve account by its PDA address directly. */
+	fetchNativeBondingCurveByAddress(address: PublicKey) {
+		return fetchNativeBondingCurveByAddressFn(
+			this.connection,
+			address,
+			this.config
+		);
+	}
+
+	/** Fetches the AMM global configuration. */
+	fetchAmmConfig() {
+		return fetchAmmConfigFn(this.connection, this.config);
+	}
+
+	/** Fetches an AMM pool state by base and quote mint. */
+	fetchPoolState(baseMint: PublicKey, quoteMint: PublicKey = WSOL_MINT) {
+		return fetchPoolStateFn(
+			this.connection,
+			baseMint,
+			quoteMint,
+			this.config
+		);
+	}
+
+	/** Fetches a pool state by its PDA address directly. */
+	fetchPoolStateByAddress(address: PublicKey) {
+		return fetchPoolStateByAddressFn(this.connection, address, this.config);
+	}
+
+	/** Fetches the observation state (oracle data) for a pool. */
+	fetchObservationState(poolAddress: PublicKey) {
+		return fetchObservationStateFn(
+			this.connection,
+			poolAddress,
+			this.config
+		);
+	}
+
+	/** Fetches the fee configuration for a token mint. */
+	fetchFeeConfig(tokenMint: PublicKey) {
+		return fetchFeeConfigFn(this.connection, tokenMint, this.config);
+	}
+
+	/** Fetches a fee configuration by its PDA address directly. */
+	fetchFeeConfigByAddress(address: PublicKey) {
+		return fetchFeeConfigByAddressFn(this.connection, address, this.config);
+	}
+
+	/** Fetches a user's properties (referrer, volumes, cashback state). */
+	fetchUserProperties(user: PublicKey) {
+		return fetchUserPropertiesFn(this.connection, user, this.config);
+	}
+
+	/** Fetches the token volume accumulator for a mint. */
+	fetchTokenVolume(mint: PublicKey) {
+		return fetchTokenVolumeFn(this.connection, mint, this.config);
+	}
+
+	/** Fetches the global curve volume accumulator. */
+	fetchGlobalCurveVolume() {
+		return fetchGlobalCurveVolumeFn(this.connection, this.config);
+	}
+
+	/** Fetches the global AMM volume accumulator. */
+	fetchGlobalAmmVolume() {
+		return fetchGlobalAmmVolumeFn(this.connection, this.config);
+	}
+
+	/** Fetches the cashback configuration. */
+	fetchCashbackConfig() {
+		return fetchCashbackConfigFn(this.connection, this.config);
+	}
+
+	/** Fetches a user snapshot by user and index. */
+	fetchUserSnapshot(user: PublicKey, index: number) {
+		return fetchUserSnapshotFn(this.connection, user, index, this.config);
+	}
+
+	/** Fetches a deal account by its owner. */
+	fetchDeal(owner: PublicKey) {
+		return fetchDealFn(this.connection, owner, this.config);
+	}
+
+	/**
+	 * Previews a buy on the bonding curve. Auto-fetches state from chain.
+	 *
+	 * @param mint - Token mint address
+	 * @param amountInQuote - Quote token amount to spend (lamports for SOL, smallest unit for stables)
+	 * @param options - Native (`{ solPriceUsd }`) or stable (`{ quoteMint }`) curve options
+	 * @returns Buy preview with `tokensOut`, `fees`, `priceImpactBps`, `newReserves`, and `willComplete`
+	 */
+	previewBuyOnCurve(
+		mint: PublicKey,
+		amountInQuote: BN,
+		options: CurveAsyncOptions
+	): Promise<BuyCurvePreview> {
+		return previewBuyOnCurveFn(
+			this.connection,
+			mint,
+			amountInQuote,
+			this.config,
+			options
+		);
+	}
+
+	/**
+	 * Previews a sell on the bonding curve. Auto-fetches state from chain.
+	 *
+	 * @param mint - Token mint address
+	 * @param amountInTokens - Token amount to sell (smallest unit, 6 decimals)
+	 * @param options - Native (`{ solPriceUsd }`) or stable (`{ quoteMint }`) curve options
+	 * @returns Sell preview with `quoteOut`, `quoteOutNet`, `fees`, `priceImpactBps`, and `newReserves`
+	 */
+	previewSellOnCurve(
+		mint: PublicKey,
+		amountInTokens: BN,
+		options: CurveAsyncOptions
+	): Promise<SellCurvePreview> {
+		return previewSellOnCurveFn(
+			this.connection,
+			mint,
+			amountInTokens,
+			this.config,
+			options
+		);
+	}
+
+	/** Previews a sell swap on the AMM (base → quote). Accepts optional pre-fetched state. */
+	previewSwapSell(
+		baseMint: PublicKey,
+		quoteMint: PublicKey,
+		amountIn: BN,
+		options?: { prefetched?: SwapPrefetchedState }
+	): Promise<SwapPreview> {
+		return previewSwapSellFn(
+			this.connection,
+			baseMint,
+			quoteMint,
+			amountIn,
+			this.config,
+			options
+		);
+	}
+
+	/** Previews a buy swap on the AMM (quote → base). Accepts optional pre-fetched state. */
+	previewSwapBuy(
+		baseMint: PublicKey,
+		quoteMint: PublicKey,
+		amountOut: BN,
+		options?: { prefetched?: SwapPrefetchedState }
+	): Promise<SwapPreview> {
+		return previewSwapBuyFn(
+			this.connection,
+			baseMint,
+			quoteMint,
+			amountOut,
+			this.config,
+			options
+		);
+	}
+
+	/** Derives the bonding curve PDA for a token mint. */
+	getBondingCurvePDA(mint: PublicKey): [PublicKey, number] {
+		return getBondingCurvePDA(mint, this.config.liquidProgramId);
+	}
+
+	/** Derives the SOL vault PDA for a bonding curve. */
+	getBondingCurveSolVaultPDA(bondingCurve: PublicKey): [PublicKey, number] {
+		return getBondingCurveSolVaultPDA(
+			bondingCurve,
+			this.config.liquidProgramId
+		);
+	}
+
+	/** Derives the referral vault PDA. */
+	getReferralVaultPDA(referrer: PublicKey): [PublicKey, number] {
+		return getReferralVaultPDA(referrer, this.config.liquidProgramId);
+	}
+
+	/** Derives the buyback vault PDA for a bonding curve. */
+	getBuybackVaultPDA(bondingCurve: PublicKey): [PublicKey, number] {
+		return getBuybackVaultPDA(bondingCurve, this.config.liquidProgramId);
+	}
+
+	/** Derives the pool state PDA for a token pair. */
+	getPoolPDA(
+		baseMint: PublicKey,
+		quoteMint: PublicKey = WSOL_MINT
+	): [PublicKey, number] {
+		return getPoolPDA(baseMint, quoteMint, this.config.liquidSwapProgramId);
+	}
+
+	/** Derives the LP mint PDA for a pool. */
+	getPoolLpMintPDA(poolState: PublicKey): [PublicKey, number] {
+		return getPoolLpMintPDA(poolState, this.config.liquidSwapProgramId);
+	}
+
+	/** Derives the pool vault PDA for a specific token. */
+	getPoolVaultPDA(
+		poolState: PublicKey,
+		mint: PublicKey
+	): [PublicKey, number] {
+		return getPoolVaultPDA(
+			poolState,
+			mint,
+			this.config.liquidSwapProgramId
+		);
+	}
+
+	/** Derives the observation state PDA (oracle data) for a pool. */
+	getObservationPDA(poolState: PublicKey): [PublicKey, number] {
+		return getObservationPDA(poolState, this.config.liquidSwapProgramId);
+	}
+
+	/** Derives the fee configuration PDA for a token mint. */
+	getFeeConfigPDA(tokenMint: PublicKey): [PublicKey, number] {
+		return getFeeConfigPDA(tokenMint, this.config.liquidFeesProgramId);
+	}
+
+	/** Derives the fee vault PDA for a fee configuration. */
+	getFeeVaultPDA(feeConfig: PublicKey): [PublicKey, number] {
+		return getFeeVaultPDA(feeConfig, this.config.liquidFeesProgramId);
+	}
+
+	/** Derives the recipient vault PDA for a specific recipient within a fee config. */
+	getRecipientVaultPDA(
+		feeConfig: PublicKey,
+		recipient: PublicKey
+	): [PublicKey, number] {
+		return getRecipientVaultPDA(
+			feeConfig,
+			recipient,
+			this.config.liquidFeesProgramId
+		);
+	}
+
+	/** Derives the user properties PDA. */
+	getUserPropertiesPDA(user: PublicKey): [PublicKey, number] {
+		return getUserPropertiesPDA(user, this.config.liquidStateProgramId);
+	}
+
+	/** Derives the token volume accumulator PDA. */
+	getTokenVolumePDA(mint: PublicKey): [PublicKey, number] {
+		return getTokenVolumePDA(mint, this.config.liquidStateProgramId);
+	}
+
+	/** Derives the user snapshot PDA for a given user and index. */
+	getUserSnapshotPDA(user: PublicKey, index: number): [PublicKey, number] {
+		return getUserSnapshotPDA(
+			user,
+			index,
+			this.config.liquidStateProgramId
+		);
+	}
+
+	/** Derives the deal PDA for a given owner. */
+	getDealPDA(owner: PublicKey): [PublicKey, number] {
+		return getDealPDA(owner, this.config.liquidStateProgramId);
+	}
+
+	/** Derives all PDAs associated with a bonding curve token. */
+	getAllBondingCurvePDAs(mint: PublicKey, creator: PublicKey) {
+		return getAllBondingCurvePDAs(mint, creator, this.config);
+	}
+
+	/** Derives all PDAs associated with an AMM pool. */
+	getAllPoolPDAs(baseMint: PublicKey, quoteMint: PublicKey = WSOL_MINT) {
+		return getAllPoolPDAs(baseMint, quoteMint, this.config);
+	}
+
+	/** Derives all PDAs needed for bonding curve to AMM migration. */
+	getMigrationPDAs(tokenMint: PublicKey) {
+		return getMigrationPDAs(tokenMint, this.config);
+	}
+
+	/**
+	 * Builds an unsigned Transaction from instructions, with optional compute
+	 * budget. Fetches a recent blockhash. Caller is responsible for signing.
+	 */
+	buildTransaction(
+		instructions: TransactionInstruction[],
+		options: BuildTransactionOptions
+	): Promise<Transaction> {
+		return buildTransactionFn(this.connection, instructions, options);
+	}
+
+	/**
+	 * Resolves the token program (SPL Token or Token-2022) for a mint.
+	 */
+	resolveTokenProgram(mint: PublicKey): Promise<PublicKey> {
+		return resolveTokenProgramFn(this.connection, mint);
+	}
+}