@liquid-af/sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,98 @@
+export { LiquidClient } from "./client.js";
+export type { LiquidClientConfig } from "./client.js";
+
+export {
+	ReadonlyWallet,
+	createReadonlyProvider,
+	createStubProvider,
+} from "./provider.js";
+
+export { LiquidError, LiquidErrorCode } from "./errors.js";
+
+export type { LiquidConfig } from "./config.js";
+export {
+	MAINNET_CONFIG,
+	DEVNET_CONFIG,
+	LOCALNET_CONFIG,
+	WSOL_MINT,
+	BPS_DENOMINATOR,
+	NUM_FEE_RECIPIENTS,
+	MAX_FEE_RECIPIENTS_FEES,
+	MAX_QUOTE_MINTS,
+	MAX_CASHBACK_RANGES,
+	MIN_MULTIPLIER_BPS,
+	MAX_MULTIPLIER_BPS,
+	MIN_VAULT_BALANCE,
+	LIMITS,
+} from "./config.js";
+
+export type {
+	GlobalConfiguration,
+	BondingCurveState,
+	AmmConfig,
+	FeeTier,
+	PoolState,
+	Observation,
+	ObservationState,
+	UnifiedFeeConfiguration,
+	UserProperties,
+	ReferrerInfo,
+	UserSnapshot,
+	Deal,
+	AdminUpdateUserArgs,
+	TokenVolumeAccumulator,
+	GlobalCurveVolume,
+	GlobalAmmVolume,
+	CashbackRange,
+	CashbackConfiguration,
+	FeeDistribution,
+	BondingCurveBuyResult,
+	BondingCurveSellResult,
+	SwapFees,
+	AmmSellOutput,
+	AmmBuyInput,
+	LpTokenAmounts,
+	DistributionResult,
+	PoolInfo,
+	BuyCurvePreview,
+	SellCurvePreview,
+	SwapPreview,
+	FeeRecipient,
+	FeeModeAnchor,
+	CurveStatusAnchor,
+} from "./types.js";
+export {
+	FeeMode,
+	toAnchorFeeMode,
+	feeModeEquals,
+	CurveStatus,
+	curveStatusEquals,
+} from "./types.js";
+
+export * from "./pda/index.js";
+
+export * from "./math/index.js";
+
+export * from "./accounts/index.js";
+
+export * from "./instructions/index.js";
+
+export * from "./helpers/index.js";
+
+export * from "./events/index.js";
+
+export * from "./transaction/index.js";
+
+export * from "./oracle.js";
+
+export type { Liquid, LiquidSwap, LiquidFees, LiquidState } from "./idl/index.js";
+export {
+	getLiquidProgram,
+	getLiquidSwapProgram,
+	getLiquidFeesProgram,
+	getLiquidStateProgram,
+	liquidIdl,
+	liquidSwapIdl,
+	liquidFeesIdl,
+	liquidStateIdl,
+} from "./idl/index.js";

package/src/instructions/index.ts

@@ -0,0 +1,109 @@
+export {
+	buildCreateNativeCurve,
+	buildBumpNative,
+	buildBuyNative,
+	buildBuyNativeAutoResolve,
+	buildSellNative,
+	buildSellNativeAutoResolve,
+	buildMigrateNative,
+	buildInitializeNativeReferralVault,
+	buildWithdrawReferralRewards,
+	buildExecuteBuybackNative,
+	buildExecuteBuybackToken,
+	// Stable curve builders
+	buildCreateStableCurve,
+	buildBuyStable,
+	buildBuyStableAutoResolve,
+	buildSellStable,
+	buildSellStableAutoResolve,
+	buildMigrateStable,
+	// Admin builders
+	buildSetFeeRecipients,
+	buildInitializeFeeRecipientVaults,
+	buildInitializeReferralTokenVault,
+} from "./liquid.js";
+export type {
+	BuildCreateNativeCurveParams,
+	BuildBumpNativeParams,
+	BuildBuyNativeParams,
+	BuildSellNativeParams,
+	BuildMigrateNativeParams,
+	BuildInitializeNativeReferralVaultParams,
+	BuildWithdrawReferralRewardsParams,
+	BuildExecuteBuybackNativeParams,
+	BuildExecuteBuybackTokenParams,
+	// Stable curve param types
+	BuildCreateStableCurveParams,
+	BuildBuyStableParams,
+	BuildSellStableParams,
+	BuildMigrateStableParams,
+	// Admin param types
+	BuildSetFeeRecipientsParams,
+	BuildInitializeFeeRecipientVaultsParams,
+	BuildInitializeReferralTokenVaultParams,
+} from "./liquid.js";
+
+export {
+	buildCreatePool,
+	buildSwapBuy,
+	buildSwapSell,
+	buildDeposit,
+	buildWithdraw,
+	buildSwapExecuteBuyback,
+} from "./liquid-swap.js";
+export type {
+	BuildCreatePoolParams,
+	BuildSwapBuyParams,
+	BuildSwapSellParams,
+	BuildDepositParams,
+	BuildWithdrawParams,
+	BuildSwapExecuteBuybackParams,
+} from "./liquid-swap.js";
+
+export {
+	buildUpdateFeeConfig,
+	buildRevokeFeeConfig,
+	buildDistributeFees,
+	buildDistributeTokenFees,
+	buildClaimFees,
+	buildClaimTokenFees,
+	deriveRecipientVaultPairs,
+} from "./liquid-fees.js";
+export type {
+	BuildUpdateFeeConfigParams,
+	BuildRevokeFeeConfigParams,
+	BuildDistributeFeesParams,
+	BuildDistributeTokenFeesParams,
+	BuildClaimFeesParams,
+	BuildClaimTokenFeesParams,
+	RecipientVaultPair,
+} from "./liquid-fees.js";
+
+export {
+	buildInitializeUser,
+	buildSetReferrer,
+	buildSetCashbackMode,
+	buildTransferAdmin,
+	buildAcceptAdmin,
+	buildCancelAdminTransfer,
+	buildCreateDeal,
+	buildUpdateDeal,
+	buildCloseDeal,
+	buildRedeemDeal,
+	buildTakeSnapshot,
+	buildAdminUpdateUser,
+} from "./liquid-state.js";
+export type {
+	BuildInitializeUserParams,
+	BuildSetReferrerParams,
+	BuildSetCashbackModeParams,
+	BuildTransferAdminParams,
+	BuildAcceptAdminParams,
+	BuildCancelAdminTransferParams,
+	BuildCreateDealParams,
+	BuildUpdateDealParams,
+	BuildCloseDealParams,
+	BuildRedeemDealParams,
+	BuildTakeSnapshotParams,
+	BuildAdminUpdateUserParams,
+} from "./liquid-state.js";

package/src/instructions/liquid-fees.ts

@@ -0,0 +1,289 @@
+import type { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import { getAssociatedTokenAddressSync } from "@solana/spl-token";
+import type { LiquidConfig } from "../config.js";
+import type { FeeRecipient } from "../types.js";
+import { getCachedFeesProgram } from "./program-cache.js";
+import {
+	getFeeConfigPDA,
+	getFeeVaultPDA,
+	getRecipientVaultPDA,
+} from "../pda/liquid-fees.js";
+
+export interface BuildUpdateFeeConfigParams {
+	authority: PublicKey;
+	tokenMint: PublicKey;
+	recipients?: FeeRecipient[] | null;
+	newUpdateAuthority?: PublicKey | null;
+	/** Required when changing recipients to verify token fee vault is drained. */
+	quoteMint?: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an updateFeeConfig instruction.
+ * Cannot change to Revoked mode (use revokeFeeConfig instead).
+ *
+ * @param params - {@link BuildUpdateFeeConfigParams}
+ * @returns Transaction instruction
+ */
+export function buildUpdateFeeConfig(
+	params: BuildUpdateFeeConfigParams
+): Promise<TransactionInstruction> {
+	const {
+		authority,
+		tokenMint,
+		recipients,
+		newUpdateAuthority,
+		quoteMint,
+		config,
+	} = params;
+	const program = getCachedFeesProgram(config);
+
+	const formattedRecipients =
+		recipients?.map((r) => ({
+			pubkey: r.pubkey,
+			basisPoints: r.basisPoints,
+		})) ?? null;
+
+	// When changing recipients, the token fee vault must be passed to verify it's drained
+	let tokenFeeVault: PublicKey | null = null;
+	if (recipients && quoteMint) {
+		const [feeConfig] = getFeeConfigPDA(
+			tokenMint,
+			config.liquidFeesProgramId
+		);
+		const [feeVault] = getFeeVaultPDA(feeConfig, config.liquidFeesProgramId);
+		tokenFeeVault = getAssociatedTokenAddressSync(
+			quoteMint,
+			feeVault,
+			true
+		);
+	}
+
+	return program.methods
+		.updateFeeConfig({
+			recipients: formattedRecipients,
+			newUpdateAuthority: newUpdateAuthority ?? null,
+		})
+		.accounts({
+			authority,
+			tokenMint,
+			tokenFeeVault
+		})
+		.instruction();
+}
+
+export interface BuildRevokeFeeConfigParams {
+	authority: PublicKey;
+	tokenMint: PublicKey;
+	/** Quote mint for token fee vault ATA derivation. */
+	quoteMint: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a revokeFeeConfig instruction.
+ * Permanently sets fee mode to Revoked (buyback-and-burn). Irreversible.
+ *
+ * @param params - {@link BuildRevokeFeeConfigParams}
+ * @returns Transaction instruction
+ */
+export function buildRevokeFeeConfig(
+	params: BuildRevokeFeeConfigParams
+): Promise<TransactionInstruction> {
+	const { authority, tokenMint, quoteMint, config } = params;
+	const program = getCachedFeesProgram(config);
+
+	// Derive token fee vault ATA (fee_vault's ATA for quote_mint)
+	const [feeConfig] = getFeeConfigPDA(tokenMint, config.liquidFeesProgramId);
+	const [feeVault] = getFeeVaultPDA(feeConfig, config.liquidFeesProgramId);
+	const tokenFeeVault = getAssociatedTokenAddressSync(
+		quoteMint,
+		feeVault,
+		true
+	);
+
+	return program.methods
+		.revokeFeeConfig()
+		.accounts({
+			authority,
+			tokenMint,
+			tokenFeeVault,
+		})
+		.instruction();
+}
+
+export interface BuildDistributeFeesParams {
+	payer: PublicKey;
+	tokenMint: PublicKey;
+	recipientVaults: PublicKey[];
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a distributeFees instruction.
+ * Permissionless — anyone can trigger fee distribution for Recipients tokens.
+ * Recipient vaults must be recipient vault PDAs (derived via getRecipientVaultPDA),
+ * passed in the same order as fee_config.recipients.
+ *
+ * @param params - {@link BuildDistributeFeesParams}
+ * @returns Transaction instruction
+ */
+export function buildDistributeFees(
+	params: BuildDistributeFeesParams
+): Promise<TransactionInstruction> {
+	const { payer, tokenMint, recipientVaults, config } = params;
+	const program = getCachedFeesProgram(config);
+
+	return program.methods
+		.distributeFees()
+		.accounts({
+			payer,
+			tokenMint,
+		})
+		.remainingAccounts(
+			recipientVaults.map((vault) => ({
+				pubkey: vault,
+				isSigner: false,
+				isWritable: true,
+			}))
+		)
+		.instruction();
+}
+
+export interface RecipientVaultPair {
+	vaultPda: PublicKey;
+	vaultAta: PublicKey;
+}
+
+export interface BuildDistributeTokenFeesParams {
+	payer: PublicKey;
+	tokenMint: PublicKey;
+	quoteMint: PublicKey;
+	recipientVaultPairs: RecipientVaultPair[];
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a distributeTokenFees instruction.
+ * Permissionless — anyone can trigger token fee distribution for Recipients tokens.
+ * Remaining accounts must be pairs of (recipient_vault_pda, recipient_vault_token_account)
+ * in the same order as fee_config.recipients.
+ *
+ * @param params - {@link BuildDistributeTokenFeesParams}
+ * @returns Transaction instruction
+ */
+export function buildDistributeTokenFees(
+	params: BuildDistributeTokenFeesParams
+): Promise<TransactionInstruction> {
+	const { payer, tokenMint, quoteMint, recipientVaultPairs, config } = params;
+	const program = getCachedFeesProgram(config);
+
+	// Flatten pairs into interleaved remaining accounts: [pda1, ata1, pda2, ata2, ...]
+	const remainingAccounts = recipientVaultPairs.flatMap((pair) => [
+		{ pubkey: pair.vaultPda, isSigner: false, isWritable: false },
+		{ pubkey: pair.vaultAta, isSigner: false, isWritable: true },
+	]);
+
+	return program.methods
+		.distributeTokenFees()
+		.accountsPartial({
+			payer,
+			tokenMint,
+			quoteMint
+		})
+		.remainingAccounts(remainingAccounts)
+		.instruction();
+}
+
+export interface BuildClaimFeesParams {
+	recipient: PublicKey;
+	tokenMint: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a claimFees instruction.
+ * Allows a recipient to claim accumulated SOL fees from their vault PDA.
+ *
+ * @param params - {@link BuildClaimFeesParams}
+ * @returns Transaction instruction
+ */
+export function buildClaimFees(
+	params: BuildClaimFeesParams
+): Promise<TransactionInstruction> {
+	const { recipient, tokenMint, config } = params;
+	const program = getCachedFeesProgram(config);
+	const [feeConfig] = getFeeConfigPDA(tokenMint, config.liquidFeesProgramId);
+
+	return program.methods
+		.claimFees()
+		.accounts({
+			recipient,
+			feeConfig,
+		})
+		.instruction();
+}
+
+export interface BuildClaimTokenFeesParams {
+	recipient: PublicKey;
+	tokenMint: PublicKey;
+	quoteMint: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a claimTokenFees instruction.
+ * Allows a recipient to claim accumulated token fees from their vault ATA.
+ * Closes the vault ATA after claiming to reclaim rent.
+ *
+ * @param params - {@link BuildClaimTokenFeesParams}
+ * @returns Transaction instruction
+ */
+export function buildClaimTokenFees(
+	params: BuildClaimTokenFeesParams
+): Promise<TransactionInstruction> {
+	const { recipient, tokenMint, quoteMint, config } = params;
+	const program = getCachedFeesProgram(config);
+	const [feeConfig] = getFeeConfigPDA(tokenMint, config.liquidFeesProgramId);
+
+	return program.methods
+		.claimTokenFees()
+		.accounts({
+			recipient,
+			feeConfig,
+			quoteMint,
+		})
+		.instruction();
+}
+
+/**
+ * Helper: derives recipient vault PDA pairs for use with buildDistributeTokenFees.
+ *
+ * @param tokenMint - Token mint address
+ * @param recipients - Array of recipient public keys in fee_config order
+ * @param quoteMint - Quote mint for ATA derivation
+ * @param config - Liquid protocol config
+ * @returns Array of RecipientVaultPair for remaining accounts
+ */
+export function deriveRecipientVaultPairs(
+	tokenMint: PublicKey,
+	recipients: PublicKey[],
+	quoteMint: PublicKey,
+	config: LiquidConfig
+): RecipientVaultPair[] {
+	const [feeConfig] = getFeeConfigPDA(tokenMint, config.liquidFeesProgramId);
+	return recipients.map((recipient) => {
+		const [vaultPda] = getRecipientVaultPDA(
+			feeConfig,
+			recipient,
+			config.liquidFeesProgramId
+		);
+		const vaultAta = getAssociatedTokenAddressSync(
+			quoteMint,
+			vaultPda,
+			true
+		);
+		return { vaultPda, vaultAta };
+	});
+}