@liquid-af/sdk 0.1.0

package/src/math/tiered-fees.ts

@@ -0,0 +1,165 @@
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import type { FeeTier } from "../types.js";
+
+/** WSOL mint address (native SOL wrapped as SPL token) */
+export const WSOL_MINT = new PublicKey(
+	"So11111111111111111111111111111111111111112"
+);
+
+/** Lamports per SOL constant */
+const LAMPORTS_PER_SOL = new BN(1_000_000_000);
+
+/**
+ * Calculate pool fully diluted market cap in USD.
+ *
+ * The market cap is calculated as:
+ * - Pool token price (in USD) × base token total supply
+ * - Pool token price = (quote vault value in USD) / base vault amount
+ *
+ * For WSOL pools, the quote vault is converted to USD using the oracle price.
+ * For USDC pools, the quote vault is already in USD (assumed 1:1 peg).
+ *
+ * @param quoteVaultAmount - Quote vault balance (lamports for WSOL, 6 decimals for USDC)
+ * @param baseVaultAmount - Base vault balance (token decimals)
+ * @param baseTotalSupply - Total supply of base token (token decimals)
+ * @param solPriceUsd - SOL/USD price from oracle (6 decimals)
+ * @param quoteMint - Quote mint pubkey (to detect WSOL vs stable)
+ * @returns Market cap in USD (6 decimals)
+ *
+ * @example
+ * ```typescript
+ * // Pool with 100 SOL and 1M tokens, SOL = $150, supply = 1B tokens
+ * // Token price = (100 SOL × $150) / 1M = $0.015 per token
+ * // Market cap = $0.015 × 1B = $15M
+ * const marketCap = calculatePoolMarketCap(
+ *   new BN(100_000_000_000),  // 100 SOL in lamports
+ *   new BN(1_000_000_000_000),  // 1M tokens (6 decimals)
+ *   new BN(1_000_000_000_000_000),  // 1B tokens (6 decimals)
+ *   new BN(150_000_000),  // $150 (6 decimals)
+ *   WSOL_MINT,
+ * );
+ * // Returns: 15_000_000_000_000 ($15M with 6 decimals)
+ * ```
+ */
+export function calculatePoolMarketCap(
+	quoteVaultAmount: BN,
+	baseVaultAmount: BN,
+	baseTotalSupply: BN,
+	solPriceUsd: BN,
+	quoteMint: PublicKey
+): BN {
+	// Prevent division by zero
+	if (baseVaultAmount.isZero()) {
+		throw new Error("Base vault amount cannot be zero");
+	}
+
+	if (quoteMint.equals(WSOL_MINT)) {
+		// For WSOL pools: convert quote reserves to USD, then compute market cap
+		// Formula: market_cap = (quote_lamports × sol_price_usd / 1e9) × base_supply / base_vault
+		//
+		// Combined to avoid intermediate truncation:
+		// market_cap = (quote_lamports × sol_price_usd × base_supply) / (1e9 × base_vault)
+		const marketCap = quoteVaultAmount
+			.mul(solPriceUsd)
+			.mul(baseTotalSupply)
+			.div(LAMPORTS_PER_SOL)
+			.div(baseVaultAmount);
+
+		return marketCap;
+	} else {
+		// For USDC and other stablecoins: assume 1:1 with USD
+		// quote_vault already in 6 decimals for USDC
+		// Formula: market_cap = (quote_amount × base_supply) / base_vault
+		const marketCap = quoteVaultAmount
+			.mul(baseTotalSupply)
+			.div(baseVaultAmount);
+
+		return marketCap;
+	}
+}
+
+/**
+ * Find appropriate fee tier for given market cap.
+ *
+ * Performs a linear scan through the active fee tiers to find the tier
+ * whose range contains the given market cap. If the market cap exceeds
+ * all tier ranges, returns the last tier.
+ *
+ * @param marketCapUsd - Pool market cap in USD (6 decimals)
+ * @param tiers - Array of active fee tiers (sorted, validated)
+ * @returns Tuple of [lpFeeRate, protocolFeeRate, creatorFeeRate] in basis points
+ *
+ * @example
+ * ```typescript
+ * const tiers = [
+ *   { rangeStartInclusive: new BN(0), rangeEndExclusive: new BN(1_000_000_000_000), lpFeeRate: 30, protocolFeeRate: 5, creatorFeeRate: 5 },
+ *   { rangeStartInclusive: new BN(1_000_000_000_000), rangeEndExclusive: new BN('18446744073709551615'), lpFeeRate: 20, protocolFeeRate: 3, creatorFeeRate: 3 },
+ * ];
+ *
+ * // Market cap = $500K -> uses first tier (high fees)
+ * const [lp, protocol, creator] = lookupFeeTier(new BN(500_000_000_000), tiers);
+ * // Returns: [30, 5, 5]
+ *
+ * // Market cap = $5M -> uses second tier (low fees)
+ * const [lp2, protocol2, creator2] = lookupFeeTier(new BN(5_000_000_000_000), tiers);
+ * // Returns: [20, 3, 3]
+ * ```
+ */
+export function lookupFeeTier(
+	marketCapUsd: BN,
+	tiers: FeeTier[]
+): [number, number, number] {
+	if (tiers.length === 0) {
+		throw new Error("No fee tiers configured");
+	}
+
+	// Linear scan to find matching tier
+	for (const tier of tiers) {
+		if (
+			marketCapUsd.gte(tier.rangeStartInclusive) &&
+			marketCapUsd.lt(tier.rangeEndExclusive)
+		) {
+			return [tier.lpFeeRate, tier.protocolFeeRate, tier.creatorFeeRate];
+		}
+	}
+
+	// If market cap exceeds all tiers, use the last tier
+	const lastTier = tiers[tiers.length - 1];
+	return [
+		lastTier.lpFeeRate,
+		lastTier.protocolFeeRate,
+		lastTier.creatorFeeRate,
+	];
+}
+
+/**
+ * Calculate the fee rates that would apply for a given pool state.
+ * Helper function that combines market cap calculation and tier lookup.
+ *
+ * @param quoteVaultAmount - Quote vault balance
+ * @param baseVaultAmount - Base vault balance
+ * @param baseTotalSupply - Total supply of base token
+ * @param solPriceUsd - SOL/USD price from oracle (6 decimals)
+ * @param quoteMint - Quote mint pubkey
+ * @param tiers - Array of active fee tiers
+ * @returns Tuple of [lpFeeRate, protocolFeeRate, creatorFeeRate] in basis points
+ */
+export function calculateFeesForPool(
+	quoteVaultAmount: BN,
+	baseVaultAmount: BN,
+	baseTotalSupply: BN,
+	solPriceUsd: BN,
+	quoteMint: PublicKey,
+	tiers: FeeTier[]
+): [number, number, number] {
+	const marketCap = calculatePoolMarketCap(
+		quoteVaultAmount,
+		baseVaultAmount,
+		baseTotalSupply,
+		solPriceUsd,
+		quoteMint
+	);
+
+	return lookupFeeTier(marketCap, tiers);
+}

package/src/oracle.ts

@@ -0,0 +1,97 @@
+/**
+ * SOL/USD feed ID from Pyth.
+ *
+ * This is a universal identifier for the SOL/USD price pair used across all networks
+ * (mainnet, devnet, testnet, and localnet). Feed IDs are asset pair identifiers,
+ * not account addresses. The actual price feed accounts differ per network, but all
+ * contain data for this feed ID.
+ *
+ * Must match the constant in programs/liquid/src/instructions/shared/oracle.rs
+ */
+export const SOL_USD_FEED_ID =
+	"0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d";
+
+/**
+ * Standard Pyth exponent for SOL/USD (8 decimals)
+ */
+export const PYTH_EXPONENT = -8;
+
+/**
+ * USD decimals used in the protocol
+ */
+export const USD_DECIMALS = 6;
+
+/**
+ * Calculates the expected virtual SOL reserves for a given virtual reserve value and SOL price.
+ * Matches the calculation in oracle.rs::calculate_virtual_sol_reserves
+ *
+ * @param initialVirtualReserveUsd - Initial virtual reserve value in USD (6 decimals)
+ * @param solPriceUsd - SOL price in USD (6 decimals)
+ * @returns Virtual SOL reserves in lamports
+ */
+export function calculateVirtualSolReserves(
+	initialVirtualReserveUsd: bigint,
+	solPriceUsd: bigint
+): bigint {
+	// virtual_sol (lamports) = initial_virtual_reserve_usd / sol_price_usd * 10^9
+	return (initialVirtualReserveUsd * BigInt(1_000_000_000)) / solPriceUsd;
+}
+
+/**
+ * Calculates the market cap of a token in USD for native curves.
+ * Matches the calculation in oracle.rs::calculate_market_cap_usd
+ *
+ * Market Cap = Token Price (in SOL) × Total Supply × SOL Price (in USD)
+ *
+ * @param virtualSolReserves - Virtual SOL reserves in lamports
+ * @param virtualTokenReserves - Virtual token reserves (6 decimals)
+ * @param tokenTotalSupply - Total supply of tokens (6 decimals)
+ * @param solPriceUsd - SOL price in USD (6 decimals)
+ * @returns Market cap in USD (6 decimals)
+ */
+export function calculateNativeMarketCapUsd(
+	virtualSolReserves: bigint,
+	virtualTokenReserves: bigint,
+	tokenTotalSupply: bigint,
+	solPriceUsd: bigint
+): bigint {
+	// Token price in lamports per token (scaled by 1e6 for precision)
+	const tokenPriceLamports =
+		(virtualSolReserves * BigInt(1_000_000)) / virtualTokenReserves;
+
+	// Market cap in lamports
+	const marketCapLamports =
+		(tokenPriceLamports * tokenTotalSupply) / BigInt(1_000_000);
+
+	// Convert to USD
+	const marketCapUsd =
+		(marketCapLamports * solPriceUsd) / BigInt(1_000_000_000);
+
+	return marketCapUsd;
+}
+
+/**
+ * Calculates the market cap of a token in USD for stable curves (USDC quote).
+ *
+ * Market Cap = Token Price (in USDC) × Total Supply
+ *
+ * @param virtualQuoteReserves - Virtual USDC reserves (6 decimals)
+ * @param virtualTokenReserves - Virtual token reserves (6 decimals)
+ * @param tokenTotalSupply - Total supply of tokens (6 decimals)
+ * @returns Market cap in USD (6 decimals)
+ */
+export function calculateTokenMarketCapUsd(
+	virtualQuoteReserves: bigint,
+	virtualTokenReserves: bigint,
+	tokenTotalSupply: bigint
+): bigint {
+	// Token price in USDC (scaled by 1e6 for precision)
+	const tokenPriceUsdc =
+		(virtualQuoteReserves * BigInt(1_000_000)) / virtualTokenReserves;
+
+	// Market cap = price * total_supply
+	const marketCapUsd =
+		(tokenPriceUsdc * tokenTotalSupply) / BigInt(1_000_000);
+
+	return marketCapUsd;
+}

package/src/pda/index.ts

@@ -0,0 +1,331 @@
+export {
+	getLiquidGlobalConfigPDA,
+	getBondingCurvePDA,
+	getBondingCurveSolVaultPDA,
+	getBondingCurveTokenAccount,
+	getReferralVaultPDA,
+	getReferralTokenVault,
+	getBuybackVaultPDA,
+	getStableBondingCurvePDA,
+} from "./liquid.js";
+
+export {
+	getSwapGlobalConfigPDA,
+	getSwapAuthorityPDA,
+	getPoolPDA,
+	getPoolLpMintPDA,
+	getPoolVaultPDA,
+	getObservationPDA,
+	getProtocolFeeVaultPDA,
+	getTempWsolPDA,
+	getSwapBuybackVaultPDA,
+} from "./liquid-swap.js";
+
+export {
+	getFeeConfigPDA,
+	getFeeVaultPDA,
+	getRecipientVaultPDA,
+} from "./liquid-fees.js";
+
+export {
+	getUserPropertiesPDA,
+	getGlobalCurveVolumePDA,
+	getGlobalAmmVolumePDA,
+	getTokenVolumePDA,
+	getCashbackConfigPDA,
+	getUserSnapshotPDA,
+	getDealPDA,
+} from "./liquid-state.js";
+
+import type { PublicKey } from "@solana/web3.js";
+import { MAINNET_CONFIG, WSOL_MINT, type LiquidConfig } from "../config.js";
+import {
+	getBondingCurvePDA,
+	getBondingCurveSolVaultPDA,
+	getReferralVaultPDA,
+	getBuybackVaultPDA,
+	getStableBondingCurvePDA,
+} from "./liquid.js";
+import {
+	getPoolPDA,
+	getPoolLpMintPDA,
+	getPoolVaultPDA,
+	getObservationPDA,
+	getSwapGlobalConfigPDA,
+	getSwapAuthorityPDA,
+	getSwapBuybackVaultPDA,
+} from "./liquid-swap.js";
+import { getFeeConfigPDA, getFeeVaultPDA } from "./liquid-fees.js";
+import { getUserPropertiesPDA, getTokenVolumePDA } from "./liquid-state.js";
+
+/** All PDAs associated with a bonding curve token */
+export interface BondingCurvePDAs {
+	bondingCurve: PublicKey;
+	bondingCurveSolVault: PublicKey;
+	referralVault: PublicKey;
+	buybackVault: PublicKey;
+	feeConfig: PublicKey;
+	feeVault: PublicKey;
+	userProperties: PublicKey;
+	tokenVolume: PublicKey;
+}
+
+/**
+ * Derives all PDAs associated with a bonding curve token.
+ *
+ * @param mint - Token mint address
+ * @param creator - Bonding curve creator public key
+ * @param config - Liquid protocol configuration
+ * @returns All bonding curve-related PDAs
+ */
+export const getAllBondingCurvePDAs = (
+	mint: PublicKey,
+	creator: PublicKey,
+	config: LiquidConfig
+): BondingCurvePDAs => {
+	const [bondingCurve] = getBondingCurvePDA(mint, config.liquidProgramId);
+	const [bondingCurveSolVault] = getBondingCurveSolVaultPDA(
+		bondingCurve,
+		config.liquidProgramId
+	);
+	const [referralVault] = getReferralVaultPDA(
+		creator,
+		config.liquidProgramId
+	);
+	const [buybackVault] = getBuybackVaultPDA(
+		bondingCurve,
+		config.liquidProgramId
+	);
+	const [feeConfig] = getFeeConfigPDA(mint, config.liquidFeesProgramId);
+	const [feeVault] = getFeeVaultPDA(feeConfig, config.liquidFeesProgramId);
+	const [userProperties] = getUserPropertiesPDA(
+		creator,
+		config.liquidStateProgramId
+	);
+	const [tokenVolume] = getTokenVolumePDA(mint, config.liquidStateProgramId);
+
+	return {
+		bondingCurve,
+		bondingCurveSolVault,
+		referralVault,
+		buybackVault,
+		feeConfig,
+		feeVault,
+		userProperties,
+		tokenVolume,
+	};
+};
+
+/** All PDAs associated with an AMM pool */
+export interface PoolPDAs {
+	poolState: PublicKey;
+	lpMint: PublicKey;
+	baseVault: PublicKey;
+	quoteVault: PublicKey;
+	observation: PublicKey;
+	ammConfig: PublicKey;
+	ammAuthority: PublicKey;
+	feeConfig: PublicKey;
+	tokenVolume: PublicKey;
+}
+
+/**
+ * Derives all PDAs associated with an AMM pool.
+ *
+ * @param baseMint - Base token mint address
+ * @param quoteMint - Quote token mint address
+ * @param config - Liquid protocol configuration
+ * @returns All pool-related PDAs
+ */
+export const getAllPoolPDAs = (
+	baseMint: PublicKey,
+	quoteMint: PublicKey,
+	config: LiquidConfig
+): PoolPDAs => {
+	const [poolState] = getPoolPDA(
+		baseMint,
+		quoteMint,
+		config.liquidSwapProgramId
+	);
+	const [lpMint] = getPoolLpMintPDA(poolState, config.liquidSwapProgramId);
+	const [baseVault] = getPoolVaultPDA(
+		poolState,
+		baseMint,
+		config.liquidSwapProgramId
+	);
+	const [quoteVault] = getPoolVaultPDA(
+		poolState,
+		quoteMint,
+		config.liquidSwapProgramId
+	);
+	const [observation] = getObservationPDA(
+		poolState,
+		config.liquidSwapProgramId
+	);
+	const [ammConfig] = getSwapGlobalConfigPDA(config.liquidSwapProgramId);
+	const [ammAuthority] = getSwapAuthorityPDA(config.liquidSwapProgramId);
+	const [feeConfig] = getFeeConfigPDA(baseMint, config.liquidFeesProgramId);
+	const [tokenVolume] = getTokenVolumePDA(
+		baseMint,
+		config.liquidStateProgramId
+	);
+
+	return {
+		poolState,
+		lpMint,
+		baseVault,
+		quoteVault,
+		observation,
+		ammConfig,
+		ammAuthority,
+		feeConfig,
+		tokenVolume,
+	};
+};
+
+/** All PDAs needed for bonding curve to AMM migration */
+export interface MigrationPDAs {
+	bondingCurve: PublicKey;
+	ammPoolState: PublicKey;
+	ammLpMint: PublicKey;
+	ammBaseVault: PublicKey;
+	ammQuoteVault: PublicKey;
+	ammObservation: PublicKey;
+	ammConfig: PublicKey;
+	ammAuthority: PublicKey;
+	ammBuybackVault: PublicKey;
+}
+
+/**
+ * Derives all PDAs needed for migration from bonding curve to AMM.
+ *
+ * @param tokenMint - Token mint address
+ * @param config - Liquid protocol configuration
+ * @returns All migration-related PDAs
+ */
+export const getMigrationPDAs = (
+	tokenMint: PublicKey,
+	config: LiquidConfig = MAINNET_CONFIG
+): MigrationPDAs => {
+	const [bondingCurve] = getBondingCurvePDA(
+		tokenMint,
+		config.liquidProgramId
+	);
+	const [ammPoolState] = getPoolPDA(
+		tokenMint,
+		WSOL_MINT,
+		config.liquidSwapProgramId
+	);
+	const [ammLpMint] = getPoolLpMintPDA(
+		ammPoolState,
+		config.liquidSwapProgramId
+	);
+	const [ammBaseVault] = getPoolVaultPDA(
+		ammPoolState,
+		tokenMint,
+		config.liquidSwapProgramId
+	);
+	const [ammQuoteVault] = getPoolVaultPDA(
+		ammPoolState,
+		WSOL_MINT,
+		config.liquidSwapProgramId
+	);
+	const [ammObservation] = getObservationPDA(
+		ammPoolState,
+		config.liquidSwapProgramId
+	);
+	const [ammConfig] = getSwapGlobalConfigPDA(config.liquidSwapProgramId);
+	const [ammAuthority] = getSwapAuthorityPDA(config.liquidSwapProgramId);
+	const [ammBuybackVault] = getSwapBuybackVaultPDA(
+		ammPoolState,
+		WSOL_MINT,
+		config.liquidSwapProgramId
+	);
+
+	return {
+		bondingCurve,
+		ammPoolState,
+		ammLpMint,
+		ammBaseVault,
+		ammQuoteVault,
+		ammObservation,
+		ammConfig,
+		ammAuthority,
+		ammBuybackVault,
+	};
+};
+
+/** All PDAs needed for token bonding curve to AMM migration */
+export interface TokenMigrationPDAs {
+	bondingCurve: PublicKey;
+	ammPoolState: PublicKey;
+	ammLpMint: PublicKey;
+	ammBaseVault: PublicKey;
+	ammQuoteVault: PublicKey;
+	ammObservation: PublicKey;
+	ammConfig: PublicKey;
+	ammAuthority: PublicKey;
+	ammBuybackVault: PublicKey;
+}
+
+/**
+ * Derives all PDAs needed for migration from token bonding curve to AMM.
+ *
+ * @param tokenMint - Token mint address
+ * @param quoteMint - Quote token mint address (e.g., USDC)
+ * @param config - Liquid protocol configuration
+ * @returns All migration-related PDAs
+ */
+export const getTokenMigrationPDAs = (
+	tokenMint: PublicKey,
+	quoteMint: PublicKey,
+	config: LiquidConfig
+): TokenMigrationPDAs => {
+	const [bondingCurve] = getStableBondingCurvePDA(
+		tokenMint,
+		quoteMint,
+		config.liquidProgramId
+	);
+	const [ammPoolState] = getPoolPDA(
+		tokenMint,
+		quoteMint,
+		config.liquidSwapProgramId
+	);
+	const [ammLpMint] = getPoolLpMintPDA(
+		ammPoolState,
+		config.liquidSwapProgramId
+	);
+	const [ammBaseVault] = getPoolVaultPDA(
+		ammPoolState,
+		tokenMint,
+		config.liquidSwapProgramId
+	);
+	const [ammQuoteVault] = getPoolVaultPDA(
+		ammPoolState,
+		quoteMint,
+		config.liquidSwapProgramId
+	);
+	const [ammObservation] = getObservationPDA(
+		ammPoolState,
+		config.liquidSwapProgramId
+	);
+	const [ammConfig] = getSwapGlobalConfigPDA(config.liquidSwapProgramId);
+	const [ammAuthority] = getSwapAuthorityPDA(config.liquidSwapProgramId);
+	const [ammBuybackVault] = getSwapBuybackVaultPDA(
+		ammPoolState,
+		quoteMint,
+		config.liquidSwapProgramId
+	);
+
+	return {
+		bondingCurve,
+		ammPoolState,
+		ammLpMint,
+		ammBaseVault,
+		ammQuoteVault,
+		ammObservation,
+		ammConfig,
+		ammAuthority,
+		ammBuybackVault,
+	};
+};

package/src/pda/liquid-fees.ts

@@ -0,0 +1,58 @@
+import { PublicKey } from "@solana/web3.js";
+
+const SEED_FEE_CONFIG = Buffer.from("fee_config");
+const SEED_FEE_VAULT = Buffer.from("fee_vault");
+const SEED_RECIPIENT_VAULT = Buffer.from("recipient_vault");
+
+/**
+ * Derives the fee config PDA for a token mint.
+ *
+ * @param tokenMint - Token mint address
+ * @param programId - Liquid Fees program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getFeeConfigPDA = (
+	tokenMint: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_FEE_CONFIG, tokenMint.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the fee vault PDA for a fee config.
+ *
+ * @param feeConfig - Fee config PDA address
+ * @param programId - Liquid Fees program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getFeeVaultPDA = (
+	feeConfig: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_FEE_VAULT, feeConfig.toBuffer()],
+		programId
+	);
+};
+
+/**
+ * Derives the recipient vault PDA for a specific recipient within a fee config.
+ *
+ * @param feeConfig - Fee config PDA address
+ * @param recipient - Recipient wallet address
+ * @param programId - Liquid Fees program ID
+ * @returns Tuple of [PDA address, bump seed]
+ */
+export const getRecipientVaultPDA = (
+	feeConfig: PublicKey,
+	recipient: PublicKey,
+	programId: PublicKey
+): [PublicKey, number] => {
+	return PublicKey.findProgramAddressSync(
+		[SEED_RECIPIENT_VAULT, feeConfig.toBuffer(), recipient.toBuffer()],
+		programId
+	);
+};