@liquid-af/sdk 0.4.0 → 0.5.0

package/src/index.ts

@@ -90,15 +90,18 @@ export type {
 	LiquidSwap,
 	LiquidFees,
 	LiquidState,
+	LiquidEvents,
 } from "./idl/index.js";
 export {
 	getLiquidProgram,
 	getLiquidSwapProgram,
 	getLiquidFeesProgram,
 	getLiquidStateProgram,
+	getLiquidEventsProgram,
 	liquidIdl,
 	liquidSwapIdl,
 	liquidFeesIdl,
 	liquidStateIdl,
+	liquidEventsIdl,
 	patchIdl,
 } from "./idl/index.js";

package/src/instructions/index.ts

@@ -8,6 +8,7 @@ export {
 	buildMigrateNative,
 	buildInitializeNativeReferralVault,
 	buildWithdrawReferralRewards,
+	buildWithdrawReferralTokenRewards,
 	buildExecuteBuybackNative,
 	buildExecuteBuybackToken,
 	// Stable curve builders
@@ -28,6 +29,7 @@ export type {
 	BuildMigrateNativeParams,
 	BuildInitializeNativeReferralVaultParams,
 	BuildWithdrawReferralRewardsParams,
+	BuildWithdrawReferralTokenRewardsParams,
 	BuildExecuteBuybackNativeParams,
 	BuildExecuteBuybackTokenParams,
 	// Stable curve param types
@@ -57,6 +59,7 @@ export type {
 } from "./liquid-swap.js";
 
 export {
+	buildInitializeGlobalConfig,
 	buildUpdateFeeConfig,
 	buildRevokeFeeConfig,
 	buildDistributeFees,
@@ -66,6 +69,7 @@ export {
 	deriveRecipientVaultPairs,
 } from "./liquid-fees.js";
 export type {
+	BuildInitializeGlobalConfigParams,
 	BuildUpdateFeeConfigParams,
 	BuildRevokeFeeConfigParams,
 	BuildDistributeFeesParams,

package/src/instructions/liquid-fees.ts

@@ -260,6 +260,32 @@ export function buildClaimTokenFees(
 		.instruction();
 }
 
+export interface BuildInitializeGlobalConfigParams {
+	admin: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds an initializeGlobalConfig instruction.
+ * Creates the global configuration PDA for the liquid-fees program.
+ *
+ * @param params - {@link BuildInitializeGlobalConfigParams}
+ * @returns Transaction instruction
+ */
+export function buildInitializeGlobalConfig(
+	params: BuildInitializeGlobalConfigParams,
+): Promise<TransactionInstruction> {
+	const { admin, config } = params;
+	const program = getCachedFeesProgram(config);
+
+	return program.methods
+		.initializeGlobalConfig()
+		.accounts({
+			admin,
+		})
+		.instruction();
+}
+
 /**
  * Helper: derives recipient vault PDA pairs for use with buildDistributeTokenFees.
  *

package/src/instructions/liquid.ts

@@ -12,6 +12,7 @@ import { WSOL_MINT, type LiquidConfig } from "../config.js";
 import {
 	getBondingCurvePDA,
 	getBondingCurveTokenAccount,
+	getBuybackVaultPDA,
 	getStableBondingCurvePDA,
 } from "../pda/liquid.js";
 import {
@@ -404,6 +405,42 @@ export function buildWithdrawReferralRewards(
 		.instruction();
 }
 
+export interface BuildWithdrawReferralTokenRewardsParams {
+	user: PublicKey;
+	quoteMint: PublicKey;
+	config: LiquidConfig;
+}
+
+/**
+ * Builds a withdrawReferralTokenRewards instruction.
+ * Transfers all accrued token referral rewards from the PDA vault to the user's token account.
+ *
+ * @param params - {@link BuildWithdrawReferralTokenRewardsParams}
+ * @returns Transaction instruction
+ */
+export function buildWithdrawReferralTokenRewards(
+	params: BuildWithdrawReferralTokenRewardsParams,
+): Promise<TransactionInstruction> {
+	const { user, quoteMint, config } = params;
+	const program = getCachedLiquidProgram(config);
+
+	const userTokenAccount = getAssociatedTokenAddressSync(
+		quoteMint,
+		user,
+		false,
+		TOKEN_PROGRAM_ID,
+	);
+
+	return program.methods
+		.withdrawReferralTokenRewards()
+		.accounts({
+			user,
+			userTokenAccount,
+			quoteMint,
+		})
+		.instruction();
+}
+
 export interface BuildExecuteBuybackNativeParams {
 	payer: PublicKey;
 	mint: PublicKey;
@@ -454,12 +491,22 @@ export function buildExecuteBuybackToken(
 	const { payer, mint, quoteMint, config } = params;
 	const program = getCachedLiquidProgram(config);
 
+	const [bondingCurve] = getStableBondingCurvePDA(
+		mint,
+		config.liquidProgramId,
+	);
+	const [buybackVault] = getBuybackVaultPDA(
+		bondingCurve,
+		config.liquidProgramId,
+	);
+
 	return program.methods
 		.executeBuybackToken()
 		.accountsPartial({
 			payer,
 			mint,
 			quoteMint,
+			buybackVault,
 		})
 		.instruction();
 }
@@ -557,6 +604,15 @@ export function buildBuyStable(
 		config.liquidStateProgramId,
 	);
 
+	const [bondingCurve] = getStableBondingCurvePDA(
+		mint,
+		config.liquidProgramId,
+	);
+	const [buybackVault] = getBuybackVaultPDA(
+		bondingCurve,
+		config.liquidProgramId,
+	);
+
 	return program.methods
 		.buyStable(amountIn, minAmountOut)
 		.accountsPartial({
@@ -567,6 +623,7 @@ export function buildBuyStable(
 			creatorUserProperties,
 			creatorReferralVault: creatorReferralVault ?? null,
 			traderReferralVault: traderReferralVault ?? null,
+			buybackVault,
 			liquidState: {
 				user,
 				tokenMint: mint,
@@ -647,6 +704,15 @@ export function buildSellStable(
 		config.liquidStateProgramId,
 	);
 
+	const [bondingCurve] = getStableBondingCurvePDA(
+		mint,
+		config.liquidProgramId,
+	);
+	const [buybackVault] = getBuybackVaultPDA(
+		bondingCurve,
+		config.liquidProgramId,
+	);
+
 	return program.methods
 		.sellStable(amountIn, minAmountOut)
 		.accountsPartial({
@@ -657,6 +723,7 @@ export function buildSellStable(
 			creatorUserProperties,
 			creatorReferralVault: creatorReferralVault ?? null,
 			traderReferralVault: traderReferralVault ?? null,
+			buybackVault,
 			liquidState: {
 				user,
 				tokenMint: mint,
@@ -749,6 +816,7 @@ export function buildMigrateStable(
 		quoteMint,
 		config.liquidSwapProgramId,
 	);
+
 	return program.methods
 		.migrateStable()
 		.accounts({
@@ -820,9 +888,10 @@ export interface BuildInitializeReferralTokenVaultParams {
 
 /**
  * Builds an initializeReferralTokenVault instruction.
- * Creates a referral token vault (ATA) for the user for a specific quote mint.
+ * Creates a program-owned PDA token vault 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.
+ * This operation is idempotent — safe to call multiple times.
  *
  * @param params - {@link BuildInitializeReferralTokenVaultParams}
  * @returns Transaction instruction

package/src/pda/index.ts

@@ -5,6 +5,7 @@ export {
 	getBondingCurveTokenAccount,
 	getReferralVaultPDA,
 	getReferralTokenVault,
+	getReferralTokenVaultPDA,
 	getBuybackVaultPDA,
 	getStableBondingCurvePDA,
 } from "./liquid.js";
@@ -23,6 +24,7 @@ export {
 
 export {
 	getFeeConfigPDA,
+	getFeeGlobalConfigPDA,
 	getFeeVaultPDA,
 	getRecipientVaultPDA,
 } from "./liquid-fees.js";

package/src/pda/liquid-fees.ts

@@ -2,6 +2,7 @@ import { PublicKey } from "@solana/web3.js";
 
 const SEED_FEE_CONFIG = Buffer.from("fee_config");
 const SEED_FEE_VAULT = Buffer.from("fee_vault");
+const SEED_GLOBAL_CONFIG = Buffer.from("global_config");
 const SEED_RECIPIENT_VAULT = Buffer.from("recipient_vault");
 
 /**
@@ -21,6 +22,18 @@ export const getFeeConfigPDA = (
 	);
 };
 
+/**
+ * Derives the global config PDA for the liquid-fees program.
+ *
+ * @param programId - Liquid Fees program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getFeeGlobalConfigPDA = (
+	programId: PublicKey,
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync([SEED_GLOBAL_CONFIG], programId);
+};
+
 /**
  * Derives the fee vault PDA for a fee config.
  *

package/src/pda/liquid.ts

@@ -1,7 +1,6 @@
 import { PublicKey } from "@solana/web3.js";
 import {
 	getAssociatedTokenAddressSync,
-	TOKEN_PROGRAM_ID,
 	TOKEN_2022_PROGRAM_ID,
 } from "@solana/spl-token";
 
@@ -76,22 +75,35 @@ export const getReferralVaultPDA = (
 };
 
 /**
- * Derives the referral token vault (ATA) for stable curve referral rewards.
+ * Derives the referral token vault PDA for stable curve referral rewards.
+ * The vault is a program-owned PDA token account (not a user-owned ATA).
  *
  * @param referrer - Referrer's public key
  * @param quoteMint - Quote token mint address
- * @returns Associated token account address
+ * @param programId - Liquid program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getReferralTokenVaultPDA = (
+	referrer: PublicKey,
+	quoteMint: PublicKey,
+	programId: PublicKey,
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_REFERRAL_VAULT, referrer.toBuffer(), quoteMint.toBuffer()],
+		programId,
+	);
+};
+
+/**
+ * @deprecated Use {@link getReferralTokenVaultPDA} instead. Token referral vaults
+ * are now program-owned PDAs, not user-owned ATAs.
  */
 export const getReferralTokenVault = (
 	referrer: PublicKey,
 	quoteMint: PublicKey,
+	programId: PublicKey,
 ): PublicKey => {
-	return getAssociatedTokenAddressSync(
-		quoteMint,
-		referrer,
-		false,
-		TOKEN_PROGRAM_ID,
-	);
+	return getReferralTokenVaultPDA(referrer, quoteMint, programId)[0];
 };
 
 /**