@liquid-af/sdk 0.1.0

package/src/pda/liquid-state.ts

@@ -0,0 +1,123 @@
+import { PublicKey } from "@solana/web3.js";
+
+const SEED_USER_PROPERTIES = Buffer.from("user_properties");
+const SEED_GLOBAL_CURVE_VOLUME = Buffer.from("global_curve_volume");
+const SEED_GLOBAL_AMM_VOLUME = Buffer.from("global_amm_volume");
+const SEED_TOKEN_VOLUME = Buffer.from("token_volume");
+const SEED_CASHBACK_CONFIG = Buffer.from("cashback_config");
+const SEED_USER_SNAPSHOT = Buffer.from("user_snapshot");
+const SEED_DEAL = Buffer.from("deal");
+
+/**
+ * Derives the user properties PDA.
+ *
+ * @param user - User's public key
+ * @param programId - Liquid State program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getUserPropertiesPDA = (
+	user: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_USER_PROPERTIES, user.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the global curve volume accumulator PDA.
+ *
+ * @param programId - Liquid State program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getGlobalCurveVolumePDA = (
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_GLOBAL_CURVE_VOLUME],
+		programId
+	);
+};
+
+/**
+ * Derives the global AMM volume accumulator PDA.
+ *
+ * @param programId - Liquid State program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getGlobalAmmVolumePDA = (
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_GLOBAL_AMM_VOLUME],
+		programId
+	);
+};
+
+/**
+ * Derives the token volume accumulator PDA for a mint.
+ *
+ * @param mint - Token mint address
+ * @param programId - Liquid State program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getTokenVolumePDA = (
+	mint: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_TOKEN_VOLUME, mint.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the cashback config PDA.
+ *
+ * @param programId - Liquid State program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getCashbackConfigPDA = (
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync([SEED_CASHBACK_CONFIG], programId);
+};
+
+/**
+ * Derives the user snapshot PDA for a given user and index.
+ *
+ * @param user - User's public key
+ * @param index - Snapshot index (0-based)
+ * @param programId - Liquid State program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getUserSnapshotPDA = (
+	user: PublicKey,
+	index: number,
+	programId: PublicKey
+): [PublicKey, number] => {
+	const indexBuffer = Buffer.alloc(4);
+	indexBuffer.writeUInt32LE(index);
+	return PublicKey.findProgramAddressSync(
+		[SEED_USER_SNAPSHOT, user.toBuffer(), indexBuffer],
+		programId
+	);
+};
+
+/**
+ * Derives the deal PDA for a given owner.
+ *
+ * @param owner - Deal owner's public key
+ * @param programId - Liquid State program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getDealPDA = (
+	owner: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_DEAL, owner.toBuffer()],
+		programId
+	);
+};

package/src/pda/liquid-swap.ts

@@ -0,0 +1,162 @@
+import { PublicKey } from "@solana/web3.js";
+
+const SEED_GLOBAL_CONFIG = Buffer.from("global_config");
+const AUTH_SEED = Buffer.from("vault_and_lp_mint_auth_seed");
+const POOL_SEED = Buffer.from("pool");
+const POOL_LP_MINT_SEED = Buffer.from("pool_lp_mint");
+const POOL_VAULT_SEED = Buffer.from("pool_vault");
+const OBSERVATION_SEED = Buffer.from("observation");
+const GLOBAL_FEE_SEED = Buffer.from("global_fee");
+const SEED_TEMP_WSOL = Buffer.from("temp_wsol");
+const SEED_BUYBACK_VAULT = Buffer.from("buyback_vault");
+
+/**
+ * Derives the swap global configuration PDA.
+ *
+ * @param programId - Liquid Swap program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getSwapGlobalConfigPDA = (
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync([SEED_GLOBAL_CONFIG], programId);
+};
+
+/**
+ * Derives the swap authority PDA (for vaults and LP mint).
+ *
+ * @param programId - Liquid Swap program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getSwapAuthorityPDA = (
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync([AUTH_SEED], programId);
+};
+
+/**
+ * Derives the pool state PDA.
+ *
+ * @param baseMint - Base token mint address
+ * @param quoteMint - Quote token mint address
+ * @param programId - Liquid Swap program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getPoolPDA = (
+	baseMint: PublicKey,
+	quoteMint: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[POOL_SEED, baseMint.toBuffer(), quoteMint.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the LP mint PDA for a pool.
+ *
+ * @param poolState - Pool state PDA address
+ * @param programId - Liquid Swap program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getPoolLpMintPDA = (
+	poolState: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[POOL_LP_MINT_SEED, poolState.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the pool vault PDA for a specific token.
+ *
+ * @param poolState - Pool state PDA address
+ * @param mint - Token mint address for this vault
+ * @param programId - Liquid Swap program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getPoolVaultPDA = (
+	poolState: PublicKey,
+	mint: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[POOL_VAULT_SEED, poolState.toBuffer(), mint.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the observation state PDA (oracle data).
+ *
+ * @param poolState - Pool state PDA address
+ * @param programId - Liquid Swap program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getObservationPDA = (
+	poolState: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[OBSERVATION_SEED, poolState.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the protocol fee vault PDA.
+ *
+ * @param feeRecipient - Fee recipient's public key
+ * @param quoteMint - Quote token mint address
+ * @param programId - Liquid Swap program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getProtocolFeeVaultPDA = (
+	feeRecipient: PublicKey,
+	quoteMint: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[GLOBAL_FEE_SEED, feeRecipient.toBuffer(), quoteMint.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the temporary WSOL PDA (for unwrapping during swaps).
+ *
+ * @param poolState - Pool state PDA address
+ * @param programId - Liquid Swap program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getTempWsolPDA = (
+	poolState: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_TEMP_WSOL, poolState.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the buyback vault PDA for a pool.
+ *
+ * @param poolState - Pool state PDA address
+ * @param quoteMint - Quote token mint address
+ * @param programId - Liquid Swap program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getSwapBuybackVaultPDA = (
+	poolState: PublicKey,
+	quoteMint: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_BUYBACK_VAULT, poolState.toBuffer(), quoteMint.toBuffer()],
+		programId
+	);
+};

package/src/pda/liquid.ts

@@ -0,0 +1,152 @@
+import { PublicKey } from "@solana/web3.js";
+import {
+	getAssociatedTokenAddressSync,
+	TOKEN_PROGRAM_ID,
+	TOKEN_2022_PROGRAM_ID,
+} from "@solana/spl-token";
+
+const SEED_GLOBAL_CONFIG = Buffer.from("global_config");
+const SEED_BONDING_CURVE = Buffer.from("bonding_curve");
+const SEED_BONDING_CURVE_SOL_VAULT = Buffer.from("bonding_curve_sol_vault");
+const SEED_REFERRAL_VAULT = Buffer.from("referral_vault");
+const SEED_BUYBACK_VAULT = Buffer.from("buyback_vault");
+const SEED_TOKEN_BONDING_CURVE = Buffer.from("token_bonding_curve");
+
+/**
+ * Derives the global configuration PDA for the liquid program.
+ *
+ * @param programId - Liquid program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getLiquidGlobalConfigPDA = (
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync([SEED_GLOBAL_CONFIG], programId);
+};
+
+/**
+ * Derives the bonding curve PDA for a token mint.
+ *
+ * @param mint - Token mint address
+ * @param programId - Liquid program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getBondingCurvePDA = (
+	mint: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_BONDING_CURVE, mint.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the bonding curve SOL vault PDA.
+ *
+ * @param bondingCurve - Bonding curve PDA address
+ * @param programId - Liquid program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getBondingCurveSolVaultPDA = (
+	bondingCurve: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_BONDING_CURVE_SOL_VAULT, bondingCurve.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the referral vault PDA for referral rewards.
+ *
+ * @param referrer - Referrer's public key
+ * @param programId - Liquid program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getReferralVaultPDA = (
+	referrer: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_REFERRAL_VAULT, referrer.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the referral token vault (ATA) for stable curve referral rewards.
+ *
+ * @param referrer - Referrer's public key
+ * @param quoteMint - Quote token mint address
+ * @returns Associated token account address
+ */
+export const getReferralTokenVault = (
+	referrer: PublicKey,
+	quoteMint: PublicKey
+): PublicKey => {
+	return getAssociatedTokenAddressSync(
+		quoteMint,
+		referrer,
+		false,
+		TOKEN_PROGRAM_ID
+	);
+};
+
+/**
+ * Derives the buyback vault PDA for a bonding curve.
+ *
+ * @param bondingCurve - Bonding curve PDA address
+ * @param programId - Liquid program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getBuybackVaultPDA = (
+	bondingCurve: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_BUYBACK_VAULT, bondingCurve.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the token-based bonding curve PDA for a token mint and quote mint.
+ *
+ * @param mint - Token mint address
+ * @param quoteMint - Quote token mint address
+ * @param programId - Liquid program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getStableBondingCurvePDA = (
+	mint: PublicKey,
+	quoteMint: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_TOKEN_BONDING_CURVE, mint.toBuffer(), quoteMint.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the bonding curve's token account (ATA) for holding minted tokens.
+ * Uses Token-2022 since bonding curve mints use the Token-2022 program.
+ *
+ * @param mint - Token mint address
+ * @param programId - Liquid program ID
+ * @returns Associated token account address
+ */
+export const getBondingCurveTokenAccount = (
+	mint: PublicKey,
+	programId: PublicKey
+): PublicKey => {
+	const [bondingCurve] = getBondingCurvePDA(mint, programId);
+	return getAssociatedTokenAddressSync(
+		mint,
+		bondingCurve,
+		true,
+		TOKEN_2022_PROGRAM_ID
+	);
+};

package/src/provider.ts

@@ -0,0 +1,60 @@
+import { AnchorProvider } from "@coral-xyz/anchor";
+import {
+	Connection,
+	PublicKey,
+	type Transaction,
+	type VersionedTransaction,
+} from "@solana/web3.js";
+
+/**
+ * A wallet that satisfies Anchor's Wallet interface via structural typing,
+ * without requiring a Keypair. Used for read-only operations (account fetching)
+ * and instruction building where no actual signing is needed.
+ */
+export class ReadonlyWallet {
+	readonly publicKey = PublicKey.default;
+
+	/** @throws Always throws — signing is not supported on a read-only wallet. */
+	async signTransaction<T extends Transaction | VersionedTransaction>(
+		_tx: T
+	): Promise<T> {
+		throw new Error("Cannot sign with a readonly provider");
+	}
+
+	/** @throws Always throws — signing is not supported on a read-only wallet. */
+	async signAllTransactions<T extends Transaction | VersionedTransaction>(
+		_txs: T[]
+	): Promise<T[]> {
+		throw new Error("Cannot sign with a readonly provider");
+	}
+}
+
+const readonlyWallet = new ReadonlyWallet();
+
+/**
+ * Creates an AnchorProvider for read-only operations (account fetching).
+ * Uses a real Connection but a dummy wallet that throws on sign attempts.
+ */
+export function createReadonlyProvider(connection: Connection): AnchorProvider {
+	return new AnchorProvider(connection, readonlyWallet, {
+		commitment: "confirmed",
+		preflightCommitment: "confirmed",
+	});
+}
+
+let stubProvider: AnchorProvider | null = null;
+
+/**
+ * Returns a cached stub AnchorProvider for instruction building.
+ * Instruction building via `.instruction()` never hits the network,
+ * so no real Connection is needed.
+ */
+export function createStubProvider(): AnchorProvider {
+	if (!stubProvider) {
+		const stubConnection = new Connection("http://stub.invalid");
+		stubProvider = new AnchorProvider(stubConnection, readonlyWallet, {
+			commitment: "confirmed",
+		});
+	}
+	return stubProvider;
+}

package/src/transaction/builder.ts

@@ -0,0 +1,80 @@
+import {
+	ComputeBudgetProgram,
+	Transaction,
+	type Connection,
+	type PublicKey,
+	type TransactionInstruction,
+} from "@solana/web3.js";
+
+export interface BuildTransactionOptions {
+	/** The public key of the fee payer */
+	feePayer: PublicKey;
+	/** Compute unit limit (omit to let the runtime decide) */
+	computeUnits?: number;
+	/** Priority fee in micro-lamports per compute unit */
+	priorityFee?: number;
+}
+
+/**
+ * Prepends compute budget instructions to an instruction list.
+ * Returns a new array; does not mutate the input.
+ *
+ * @param instructions - Transaction instructions to prepend budget to
+ * @param options - Compute unit limit and/or priority fee
+ * @returns New instruction array with budget instructions prepended
+ */
+export function withComputeBudget(
+	instructions: TransactionInstruction[],
+	options: Pick<BuildTransactionOptions, "computeUnits" | "priorityFee">
+): TransactionInstruction[] {
+	const budget: TransactionInstruction[] = [];
+	if (options.computeUnits !== undefined) {
+		budget.push(
+			ComputeBudgetProgram.setComputeUnitLimit({
+				units: options.computeUnits,
+			})
+		);
+	}
+	if (options.priorityFee !== undefined) {
+		budget.push(
+			ComputeBudgetProgram.setComputeUnitPrice({
+				microLamports: options.priorityFee,
+			})
+		);
+	}
+	return [...budget, ...instructions];
+}
+
+/**
+ * Builds an unsigned Transaction from one or more instructions.
+ * Fetches a recent blockhash and sets the fee payer. The caller is
+ * responsible for signing.
+ *
+ * @param connection - Solana RPC connection
+ * @param instructions - Transaction instructions to include
+ * @param options - Fee payer and optional compute budget settings
+ * @returns Unsigned transaction ready for signing
+ */
+export async function buildTransaction(
+	connection: Connection,
+	instructions: TransactionInstruction[],
+	options: BuildTransactionOptions
+): Promise<Transaction> {
+	const { feePayer, ...budgetOptions } = options;
+	const allIxs =
+		budgetOptions.computeUnits !== undefined ||
+		budgetOptions.priorityFee !== undefined
+			? withComputeBudget(instructions, budgetOptions)
+			: instructions;
+
+	const { blockhash, lastValidBlockHeight } =
+		await connection.getLatestBlockhash();
+
+	const tx = new Transaction();
+	tx.add(...allIxs);
+	tx.recentBlockhash = blockhash;
+	tx.lastValidBlockHeight = lastValidBlockHeight;
+	tx.feePayer = feePayer;
+
+	return tx;
+}

package/src/transaction/index.ts

@@ -0,0 +1,6 @@
+export { confirmTx, sendAndConfirm } from "./send.js";
+export {
+	withComputeBudget,
+	buildTransaction,
+	type BuildTransactionOptions,
+} from "./builder.js";

package/src/transaction/send.ts

@@ -0,0 +1,72 @@
+import type { Connection } from "@solana/web3.js";
+
+/**
+ * Confirms a transaction with the given signature and blockhash info.
+ *
+ * @param connection - Solana RPC connection
+ * @param signature - Transaction signature to confirm
+ * @param blockhash - Recent blockhash used in the transaction
+ * @param lastValidBlockHeight - Block height after which the transaction expires
+ * @returns The confirmed transaction signature
+ */
+export const confirmTx = async (
+	connection: Connection,
+	signature: string,
+	blockhash: string,
+	lastValidBlockHeight: number
+): Promise<string> => {
+	await connection.confirmTransaction(
+		{ blockhash, lastValidBlockHeight, signature },
+		"confirmed"
+	);
+	return signature;
+};
+
+/**
+ * Executes an RPC call and confirms the transaction.
+ *
+ * Handles Anchor's legacy 30s confirmation timeout: if .rpc() throws a
+ * TransactionExpiredTimeoutError the transaction may still have landed.
+ * We extract the signature from the error and re-check status before
+ * propagating the failure.
+ *
+ * @param connection - Solana RPC connection
+ * @param rpcCall - Async function that sends the transaction and returns its signature
+ * @returns The confirmed transaction signature
+ */
+export const sendAndConfirm = async (
+	connection: Connection,
+	rpcCall: () => Promise<string>
+): Promise<string> => {
+	try {
+		const signature = await rpcCall();
+		const { blockhash, lastValidBlockHeight } =
+			await connection.getLatestBlockhash();
+		await confirmTx(connection, signature, blockhash, lastValidBlockHeight);
+		return signature;
+	} catch (err: unknown) {
+		if (
+			err &&
+			typeof err === "object" &&
+			"signature" in err &&
+			typeof (err as Record<string, unknown>).signature === "string"
+		) {
+			const sig = (err as Record<string, unknown>).signature as string;
+			await new Promise((r) => setTimeout(r, 2000));
+			try {
+				const { blockhash, lastValidBlockHeight } =
+					await connection.getLatestBlockhash();
+				await confirmTx(
+					connection,
+					sig,
+					blockhash,
+					lastValidBlockHeight
+				);
+				return sig;
+			} catch {
+				// Re-confirmation also failed - throw the original error
+			}
+		}
+		throw err;
+	}
+};