@liquid-af/sdk 0.1.0

package/dist/helpers/preview.d.ts

@@ -0,0 +1,259 @@
+import type { Connection, PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import type { LiquidConfig } from "../config.js";
+import type { BuyCurvePreview, SellCurvePreview, SwapPreview } from "../types.js";
+/** State needed for bonding curve preview calculations (pure math, no I/O). */
+export interface CurvePreviewState {
+    globalConfig: {
+        protocolFeeBasisPoints: number;
+        creatorFeeBasisPoints: number;
+        creatorReferralRewardBasisPoints: number;
+        traderReferralRewardBasisPoints: number;
+    };
+    bondingCurve: {
+        virtualQuoteReserves: BN;
+        virtualTokenReserves: BN;
+        realTokenReserves: BN;
+    };
+}
+/** State needed for AMM swap preview calculations (pure math, no I/O). */
+export interface SwapPreviewState {
+    ammConfig: {
+        lpFeeRate: number;
+        creatorFeeRate: number;
+        protocolFeeRate: number;
+    };
+    baseVaultBalance: BN;
+    quoteVaultBalance: BN;
+}
+/** Referral options for curve previews. */
+export interface CurvePreviewOptions {
+    hasCreatorRef?: boolean;
+    hasTraderRef?: boolean;
+}
+/**
+ * Optional pre-fetched state for {@link previewBuyOnCurve} / {@link previewSellOnCurve}.
+ *
+ * Provide any subset to skip the corresponding RPC calls. Omitted fields are
+ * fetched automatically from chain.
+ */
+export interface CurvePrefetchedState {
+    /**
+     * Fee configuration from the global config account.
+     * Include `initialVirtualReserveUsd` when previewing native curves without
+     * a prefetched `bondingCurve` (needed to compute virtual SOL reserves).
+     */
+    globalConfig?: {
+        protocolFeeBasisPoints: number;
+        creatorFeeBasisPoints: number;
+        creatorReferralRewardBasisPoints: number;
+        traderReferralRewardBasisPoints: number;
+        initialVirtualReserveUsd?: BN;
+    };
+    /**
+     * Bonding curve reserves.
+     * For native curves, `virtualQuoteReserves` must already be oracle-adjusted
+     * (i.e. computed via `calculateVirtualSolReserves`).
+     */
+    bondingCurve?: {
+        virtualQuoteReserves: BN;
+        virtualTokenReserves: BN;
+        realTokenReserves: BN;
+    };
+}
+/** Shared options for async bonding curve preview functions. */
+interface CurveOptionsBase {
+    /** Pre-fetched state to skip RPC calls. */
+    prefetched?: CurvePrefetchedState;
+    /** Whether the token creator has an active referral. */
+    hasCreatorRef?: boolean;
+    /** Whether the trader has an active referral. */
+    hasTraderRef?: boolean;
+}
+/**
+ * Options for native SOL bonding curve previews.
+ *
+ * Requires `solPriceUsd` to compute virtual SOL reserves from the on-chain
+ * USD-denominated initial reserve value.
+ */
+export interface NativeCurveOptions extends CurveOptionsBase {
+    quoteMint?: never;
+    /** Current SOL price in USD (6 decimals, e.g. 150_000_000 = $150). */
+    solPriceUsd: BN;
+}
+/**
+ * Options for stable token (e.g. USDC) bonding curve previews.
+ *
+ * Virtual quote reserves are stored on-chain and fetched automatically.
+ */
+export interface StableCurveOptions extends CurveOptionsBase {
+    /** Quote token mint address (e.g. USDC mint). */
+    quoteMint: PublicKey;
+    solPriceUsd?: never;
+}
+/**
+ * Options for async bonding curve previews. Discriminated union:
+ * - {@link NativeCurveOptions} — native SOL curves (requires `solPriceUsd`)
+ * - {@link StableCurveOptions} — stable curves (requires `quoteMint`)
+ */
+export type CurveAsyncOptions = NativeCurveOptions | StableCurveOptions;
+/** Pre-fetched state for AMM swap async previews. */
+export interface SwapPrefetchedState {
+    /**
+     * Pre-computed fee rates.
+     * For tiered fee systems, use calculateFeesForPool() to determine the rates
+     * before passing them here.
+     */
+    feeRates?: {
+        lpFeeRate: number;
+        creatorFeeRate: number;
+        protocolFeeRate: number;
+    };
+    poolState?: {
+        baseVault: PublicKey;
+        quoteVault: PublicKey;
+        baseTokenProgram: PublicKey;
+        quoteTokenProgram: PublicKey;
+        baseMint: PublicKey;
+        quoteMint: PublicKey;
+    };
+    vaultBalances?: {
+        baseVaultBalance: BN;
+        quoteVaultBalance: BN;
+    };
+    baseTotalSupply?: BN;
+}
+/**
+ * Previews a buy on the bonding curve from pre-fetched state. The function executes offline using the state being passed in.
+ *
+ * @param amountInQuote - Quote token amount to spend (lamports for SOL, smallest unit for stables)
+ * @param state - Pre-fetched bonding curve and global config state
+ * @param options - Optional referral flags
+ * @returns Buy preview with tokens out, fees, price impact, and completion flag
+ */
+export declare function calculateBuyCurvePreview(amountInQuote: BN, state: CurvePreviewState, options?: CurvePreviewOptions): BuyCurvePreview;
+/**
+ * Previews a sell on the bonding curve from pre-fetched state. The function executes offline using the state being passed in.
+ *
+ * @param amountInTokens - Token amount to sell
+ * @param state - Pre-fetched bonding curve and global config state
+ * @param options - Optional referral flags
+ * @returns Sell preview with quote out, fees, and price impact
+ */
+export declare function calculateSellCurvePreview(amountInTokens: BN, state: CurvePreviewState, options?: CurvePreviewOptions): SellCurvePreview;
+/**
+ * Previews a buy swap on the AMM (quote -> base) from pre-fetched state. The function executes offline using the state being passed in.
+ *
+ * @param amountOut - Desired base token amount out
+ * @param state - Pre-fetched AMM config and vault balances
+ * @returns Swap preview with quote in, fees, and price impact
+ */
+export declare function calculateSwapBuyPreview(amountOut: BN, state: SwapPreviewState): SwapPreview;
+/**
+ * Previews a sell swap on the AMM (base -> quote) from pre-fetched state. The function executes offline using the state being passed in.
+ *
+ * @param amountIn - Base token amount to sell
+ * @param state - Pre-fetched AMM config and vault balances
+ * @returns Swap preview with quote out, fees, and price impact
+ */
+export declare function calculateSwapSellPreview(amountIn: BN, state: SwapPreviewState): SwapPreview;
+/**
+ * Previews a buy on the bonding curve.
+ *
+ * Auto-fetches the global config and bonding curve state from chain, then
+ * computes expected tokens out, fee breakdown, price impact, and whether the
+ * buy would complete the curve.
+ *
+ * @param connection - Solana RPC connection
+ * @param mint - Token mint address
+ * @param amountInQuote - Quote token amount to spend (lamports for SOL, smallest unit for stables)
+ * @param config - Liquid protocol configuration
+ * @param options - Native ({@link NativeCurveOptions}) or stable ({@link StableCurveOptions})
+ * @returns Buy preview with `tokensOut`, `fees`, `priceImpactBps`, `newReserves`, and `willComplete`
+ *
+ * @example Native SOL curve
+ * ```ts
+ * const preview = await previewBuyOnCurve(connection, mint, new BN(100_000_000), config, {
+ *   solPriceUsd: new BN(150_000_000), // $150
+ * });
+ * ```
+ *
+ * @example Stable (USDC) curve
+ * ```ts
+ * const preview = await previewBuyOnCurve(connection, mint, new BN(10_000_000), config, {
+ *   quoteMint: USDC_MINT,
+ * });
+ * ```
+ *
+ * @see {@link calculateBuyCurvePreview} for pure offline calculations with pre-built state
+ */
+export declare function previewBuyOnCurve(connection: Connection, mint: PublicKey, amountInQuote: BN, config: LiquidConfig, options: CurveAsyncOptions): Promise<BuyCurvePreview>;
+/**
+ * Previews a sell on the bonding curve.
+ *
+ * Auto-fetches the global config and bonding curve state from chain, then
+ * computes expected quote out, fee breakdown, and price impact.
+ *
+ * @param connection - Solana RPC connection
+ * @param mint - Token mint address
+ * @param amountInTokens - Token amount to sell (smallest unit, 6 decimals)
+ * @param config - Liquid protocol configuration
+ * @param options - Native ({@link NativeCurveOptions}) or stable ({@link StableCurveOptions})
+ * @returns Sell preview with `quoteOut`, `quoteOutNet`, `fees`, `priceImpactBps`, and `newReserves`
+ *
+ * @example Native SOL curve
+ * ```ts
+ * const preview = await previewSellOnCurve(connection, mint, new BN(5_000_000), config, {
+ *   solPriceUsd: new BN(150_000_000),
+ * });
+ * ```
+ *
+ * @see {@link calculateSellCurvePreview} for pure offline calculations with pre-built state
+ */
+export declare function previewSellOnCurve(connection: Connection, mint: PublicKey, amountInTokens: BN, config: LiquidConfig, options: CurveAsyncOptions): Promise<SellCurvePreview>;
+/**
+ * Previews a sell swap on the AMM (base -> quote).
+ *
+ * Accepts optional pre-fetched state to avoid redundant RPC calls.
+ * For tiered fee systems, you must provide either:
+ * - `prefetched.feeRates` - pre-computed fee rates for the current market cap
+ * - `solPriceUsd` parameter - to calculate fee rates from on-chain tiered config
+ *
+ * @param connection - Solana RPC connection
+ * @param baseMint - Base token mint address
+ * @param quoteMint - Quote token mint address
+ * @param amountIn - Base token amount to sell
+ * @param config - Liquid protocol configuration
+ * @param options - Optional pre-fetched AMM state and solPriceUsd for tier calculation
+ * @returns Swap preview with quote out, fees, and price impact
+ *
+ * @throws Error if neither feeRates nor solPriceUsd is provided for tiered fee systems
+ */
+export declare function previewSwapSell(connection: Connection, baseMint: PublicKey, quoteMint: PublicKey, amountIn: BN, config: LiquidConfig, options?: {
+    prefetched?: SwapPrefetchedState;
+    solPriceUsd?: BN;
+}): Promise<SwapPreview>;
+/**
+ * Previews a buy swap on the AMM (quote -> base).
+ *
+ * Accepts optional pre-fetched state to avoid redundant RPC calls.
+ * For tiered fee systems, you must provide either:
+ * - `prefetched.feeRates` - pre-computed fee rates for the current market cap
+ * - `solPriceUsd` parameter - to calculate fee rates from on-chain tiered config
+ *
+ * @param connection - Solana RPC connection
+ * @param baseMint - Base token mint address
+ * @param quoteMint - Quote token mint address
+ * @param amountOut - Desired base token amount out
+ * @param config - Liquid protocol configuration
+ * @param options - Optional pre-fetched AMM state and solPriceUsd for tier calculation
+ * @returns Swap preview with quote in, fees, and price impact
+ *
+ * @throws Error if neither feeRates nor solPriceUsd is provided for tiered fee systems
+ */
+export declare function previewSwapBuy(connection: Connection, baseMint: PublicKey, quoteMint: PublicKey, amountOut: BN, config: LiquidConfig, options?: {
+    prefetched?: SwapPrefetchedState;
+    solPriceUsd?: BN;
+}): Promise<SwapPreview>;
+export {};
+//# sourceMappingURL=preview.d.ts.map

package/dist/helpers/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/helpers/preview.ts"],"names":[],"mappings":"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"}