@stabbleorg/mclmm-sdk 0.1.14 → 0.2.0

package/lib/swap.d.ts

@@ -1,6 +1,836 @@
+import type { Account, Address, Instruction, TransactionSigner } from "@solana/kit";
+import { type PoolState, type TickArrayState, type AmmConfig } from "./generated";
+import { ClmmSdkConfig, SwapParams, SwapQuote } from "./types";
+import { type PriceApiConfig } from "./managers";
+import BN from "bn.js";
+import Decimal from "decimal.js";
+/** Swap Math Engine class for performing mathematical operations related to swaps
+ *
+ * Why this exists as a separate class: Separates pure mathematical calculations from
+ * orchestration logic. This allows the math to be:
+ * 1. Tested in isolation without mocking RPC calls
+ * 2. Reused across different swap implementations
+ * 3. Easily audited for correctness without business logic noise
+ */
+export interface DetailedSwapQuote extends SwapQuote {
+    crossedTicks?: number;
+    endPrice?: Decimal;
+    priceImpactBreakdown?: {
+        fees: number;
+        slippage: number;
+    };
+}
+export interface SwapCalculationParams {
+    pool: PoolState;
+    ammConfig: AmmConfig;
+    amountIn: BN;
+    zeroForOne: boolean;
+    slippageTolerance: number;
+    poolAddress: Address;
+}
+export interface AccurateSwapParams extends SwapCalculationParams {
+    tickArrayCache: {
+        [key: string]: Account<TickArrayState>;
+    };
+}
+export declare class SwapMathEngine {
+    /**
+     * Simple swap calculation using current pool state only
+     *
+     * Why "simple": This method trades accuracy for speed. Instead of fetching and
+     * traversing potentially dozens of tick arrays from RPC, it assumes liquidity
+     * is concentrated at the current price. This is accurate for small swaps where
+     * the price doesn't move much, but becomes less accurate for large swaps that
+     * would cross multiple ticks.
+     *
+     * When to use: For UI quote displays, small swaps (<1% of liquidity), or when
+     * you need sub-second response times. The caching layer makes this very fast
+     * for repeated quotes.
+     *
+     * When NOT to use: For building actual swap instructions. Use calculateAccurateSwap
+     * instead to ensure the on-chain execution matches your quote.
+     */
+    calculateSimpleSwap(params: SwapCalculationParams): Promise<SwapQuote>;
+    /**
+     * Calculate swap using full tick traversal
+     *
+     * Why this is necessary: In CLMM (Uniswap V3 style) pools, liquidity is not
+     * uniformly distributed. It's concentrated in specific price ranges (ticks).
+     * A large swap may cross multiple ticks, each with different liquidity depths.
+     *
+     * To get an accurate quote, we must:
+     * 1. Fetch all tick arrays the swap might touch
+     * 2. Simulate walking through each tick, consuming liquidity
+     * 3. Track price impact as we cross tick boundaries
+     *
+     * Why not always use this: It requires multiple RPC calls to fetch tick arrays,
+     * making it slower and more expensive than simple calculation. Use it when
+     * accuracy matters more than speed (e.g., before executing large swaps).
+     *
+     * Trade-off: 3-5 RPC calls for accuracy vs. 2 RPC calls for speed.
+     */
+    calculateAccurateSwap(params: AccurateSwapParams): Promise<DetailedSwapQuote>;
+    /**
+     * Calculates the square root price limit for a swap based on slippage tolerance
+     *
+     * Why sqrt price: CLMM pools store price as sqrt(price) * 2^64 for mathematical
+     * efficiency. Computing swaps in sqrt space avoids expensive square root operations.
+     *
+     * Why we need limits: On-chain swaps need a price boundary to prevent front-running.
+     * If a swap would move the price beyond this limit, it reverts, protecting users
+     * from MEV attacks and unexpected price movement.
+     *
+     * Why apply slippage here: Rather than using arbitrary limits (like ±1%), we use
+     * the user's actual slippage tolerance. This respects their risk preference while
+     * providing protection.
+     *
+     * Why the min/max clamping: Solana programs panic on overflow. We must ensure the
+     * calculated limit stays within valid price bounds to prevent transaction failures.
+     */
+    calculateSqrtPriceLimit(sqrtPriceX64: BN, zeroForOne: boolean, slippageTolerance: number): BN;
+}
 /**
+ * Swap Manager implementation
+ *
+ * Why this wrapper class: SwapQuoteResult provides a clean interface over the raw
+ * quote data. Instead of forcing users to manually convert between base units and
+ * human-readable decimals, or calculate price impact percentages, we provide getters
+ * that handle these conversions automatically.
+ *
+ * Why getters instead of upfront calculation: Lazy evaluation. Not every consumer
+ * needs every metric (some just need amountOut, others need full impact analysis).
+ * Getters let consumers pay only for what they use.
+ */
+export declare class SwapQuoteResult {
+    readonly quote: SwapQuote;
+    private readonly decIn;
+    private readonly decOut;
+    private readonly zeroForOne;
+    constructor(quote: SwapQuote, decIn: number, decOut: number, zeroForOne: boolean);
+    /**
+     * Gets the execution price (output per input)
+     *
+     * Why this conversion: Token amounts are stored in base units (e.g., lamports for SOL),
+     * but users think in decimal units (SOL, USDC). We convert both sides to human-readable
+     * before calculating the rate to avoid precision loss from integer division.
+     */
+    get executionPrice(): Decimal;
+    priceUnitsLabel(inputSymbol: string, outputSymbol: string): string;
+    get isZeroForOne(): boolean;
+    get priceImpactPercent(): number;
+    get minOutput(): BN;
+    get totalFee(): BN;
+    get feePercent(): number;
+    get hasAcceptableImpact(): boolean;
+    get hasHighImpact(): boolean;
+    get hasCriticalImpact(): boolean;
+    /**
+     * Estimates compute units needed for the swap transaction
+     *
+     * Why we estimate this: Solana transactions have compute budgets. Underestimating
+     * causes transaction failures. Overestimating wastes priority fees. We provide a
+     * reasonable estimate based on swap complexity.
+     *
+     * Why 50k base + 20k per hop: Empirically derived from on-chain program measurements.
+     * Simple swaps use ~50k CU. Multi-hop routing adds ~20k per additional pool.
+     *
+     * Why this matters: Users can use this to calculate priority fees before sending
+     * transactions, improving UX and reducing failed transactions.
+     */
+    get estimatedComputeUnits(): number;
+    toJSON(): SwapQuote;
+}
+export interface SwapSimulation {
+    quote: SwapQuote;
+    willSucceed: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export interface DetailedPriceImpact {
+    totalImpact: number;
+    breakdown: {
+        fees: number;
+        slippage: number;
+        crossedTicks: number;
+    };
+    comparison: {
+        marketPrice: Decimal;
+        executionPrice: Decimal;
+        difference: number;
+    };
+    priceSnapshots: {
+        priceBefore: Decimal;
+        priceAfter: Decimal;
+    };
+}
+export interface SwapManagerConfig {
+    /**
+     * Price API configuration
+     *
+     * Configuration for REST API price fetching from team's infrastructure.
+     * This avoids exposing RPC URIs and handles rate limiting centrally.
+     *
+     * Configuration:
+     * - baseUrl
+     * - timeout: Optional request timeout (default: 5000ms)
+     *
+     * When enabled, provides:
+     * - Pre-swap price validation against market prices
+     * - Price staleness detection
+     * - Batch price fetching for multi-pool operations
+     * - Automatic retry with concurrency control
+     */
+    priceApiConfig?: PriceApiConfig;
+    /**
+     * Enable market price validation before swaps (requires priceApiConfig)
+     *
+     * When enabled, SwapManager will fetch current market prices from the REST API
+     * and compare them against on-chain pool state. Useful for:
+     * - Detecting stale pool data
+     * - Identifying potential MEV opportunities
+     * - Validating quote accuracy
+     *
+     * Default: false (to maintain backward compatibility)
+     */
+    enablePriceValidation?: boolean;
+}
+/**
+ * SwapManager - Orchestrates swap operations for CLMM pools
+ *
+ * Why this architecture: We separate concerns into layers:
+ * 1. SwapMathEngine: Pure calculations (testable, auditable)
+ * 2. PoolDataManager: Data fetching and caching (optimizes RPC calls)
+ * 3. PriceApiClient: REST API price fetching (team's infrastructure)
+ * 4. SwapManager: Orchestration (combines everything into simple APIs)
+ *
+ * This separation allows:
+ * - Testing math independently of RPC infrastructure
+ * - Reusing pool data across multiple quotes
+ * - Optional price validation via REST API
+ * - Swapping out implementations without changing interfaces
+ *
+ * Why caching is critical: RPC calls are slow (100-500ms) and rate-limited.
+ * Without caching, getting a quote for UI display would block for half a second.
+ * With caching, subsequent quotes for the same pool are instant (< 1ms).
+ *
+ * Why 2-second cache TTL: Per team spec, this balances freshness with RPC efficiency
+ * for low-traffic applications similar to app.stabble.org. More aggressive than
+ * traditional 5-10s caching but appropriate for current expected usage patterns.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (no price API)
+ * const swapManager = new SwapManager(config);
  *
- * NOTE: Work in progress
+ * // With REST API for price validation
+ * const swapManager = new SwapManager(config, {
+ *   priceApiConfig: {
+ *     baseUrl: 'https://mclmm-api.stabble.org', // or dev URL
+ *     timeout: 5000
+ *   },
+ *   enablePriceValidation: true
+ * });
  *
-*/
+ * const quote = await swapManager.getSwapQuote(poolAddress, {
+ *   tokenIn: tokenAAddress,
+ *   tokenOut: tokenBAddress,
+ *   amountIn: new BN(1000000),
+ *   slippageTolerance: 0.01
+ * });
+ * ```
+ */
+export declare class SwapManager {
+    private readonly config;
+    private readonly managerConfig?;
+    private readonly poolDataManager;
+    private readonly mathEngine;
+    private readonly priceApiClient?;
+    private readonly quoteCache;
+    private readonly quoteCacheTTL;
+    private readonly maxCacheSize;
+    /**
+     * Creates a new SwapManager instance
+     *
+     * @param config - SDK configuration with RPC client and logging
+     * @param managerConfig - Optional swap manager configuration
+     * @param managerConfig.priceApiConfig - REST API config for price validation
+     * @param managerConfig.enablePriceValidation - Enable price validation before swaps
+     */
+    constructor(config: ClmmSdkConfig, managerConfig?: SwapManagerConfig | undefined);
+    private log;
+    /**
+     * Clears the quote cache
+     *
+     * Why you'd call this: After major market events (e.g., oracle updates, large trades),
+     * cached quotes may no longer reflect reality. Manual clearing lets you force fresh
+     * calculations without waiting for TTL expiry.
+     *
+     * Why not clear automatically more often: Caching exists because RPC calls are slow.
+     * Over-clearing defeats the purpose and makes the UI feel sluggish.
+     */
+    clearQuoteCache(): void;
+    /**
+     * Clears all caches (quotes and pool data)
+     *
+     * Removes all cached data including swap quotes and pool states.
+     * Use this for a complete cache reset.
+     */
+    clearAllCaches(): void;
+    /**
+     * Get comprehensive cache metrics for observability
+     *
+     * Provides detailed metrics about cache performance including:
+     * - Hit/miss rates for pool and config data
+     * - Current cache sizes
+     * - In-flight request counts
+     * - Error cache statistics
+     *
+     * Use this to monitor cache effectiveness and diagnose performance issues.
+     *
+     * @returns Detailed cache metrics
+     *
+     * @example
+     * ```typescript
+     * const metrics = swapManager.getCacheMetrics();
+     *
+     * console.log('Pool cache hit rate:', metrics.poolData.pool.hitRate);
+     * console.log('Config cache hit rate:', metrics.poolData.config.hitRate);
+     * console.log('Quote cache size:', metrics.quoteCache.size);
+     * console.log('In-flight requests:', metrics.poolData.pool.inFlight);
+     * ```
+     */
+    getCacheMetrics(): {
+        poolData: {
+            pool: {
+                hits: number;
+                misses: number;
+                errors: number;
+                hitRate: number;
+                cacheSize: number;
+                inFlight: number;
+                errorCacheSize: number;
+            };
+            config: {
+                hits: number;
+                misses: number;
+                errors: number;
+                hitRate: number;
+                cacheSize: number;
+                inFlight: number;
+                errorCacheSize: number;
+            };
+        };
+        quoteCache: {
+            size: number;
+            maxSize: number;
+            ttl: number;
+        };
+    };
+    /**
+     * Reset all cache metrics to zero
+     *
+     * Clears metric counters without clearing cached data.
+     * Useful for starting fresh metric collection after configuration changes
+     * or for periodic metric reporting.
+     */
+    resetCacheMetrics(): void;
+    getAtaAddresses(owner: Address, mints: Address[]): Promise<Address[]>;
+    /**
+     * Estimates compute units and calculates priority fees for a swap transaction
+     *
+     * Why this exists: Solana's fee market is complex. Users need to:
+     * 1. Set compute budget (too low = failure, too high = wasted CU)
+     * 2. Set priority fee (too low = slow confirmation, too high = wasted SOL)
+     *
+     * Why three priority levels: Different users have different urgency needs.
+     * - Low: Batch operations where speed doesn't matter (100 microLamports/CU)
+     * - Medium: Normal trades where reasonable speed is expected (1,000 microLamports/CU)
+     * - High: Time-sensitive arbitrage or MEV protection (10,000 microLamports/CU)
+     *
+     * Why these specific microLamport values: Derived from observing Solana fee markets.
+     * These values provide reasonable service levels without overpaying.
+     *
+     * Priority fee calculation: `totalFee = (computeUnits × microLamportsPerCU) / 1,000,000`
+     * This converts from microLamports (1/1,000,000 of a lamport) to lamports.
+     *
+     * @param quote - Swap quote result containing estimated compute units
+     * @param priorityLevel - Priority level for transaction confirmation (default: "medium")
+     *   - "low": 100 microLamports/CU (~0.05-5 lamports for typical swaps)
+     *   - "medium": 1,000 microLamports/CU (~0.5-50 lamports for typical swaps)
+     *   - "high": 10,000 microLamports/CU (~5-500 lamports for typical swaps)
+     *
+     * @returns Object containing:
+     *   - computeUnits: Estimated compute units needed (50k base + 20k per hop)
+     *   - microLamportsPerCU: Price per compute unit in microLamports
+     *   - totalPriorityFeeLamports: Total priority fee in lamports
+     *
+     * @example
+     * ```typescript
+     * const quote = await swapManager.getSwapQuote(poolAddress, {
+     *   tokenIn: usdcAddress,
+     *   tokenOut: solAddress,
+     *   amountIn: new BN(1_000_000),
+     * });
+     *
+     * // Estimate with medium priority (default)
+     * const budget = swapManager.estimateComputeBudget(quote);
+     * console.log(`Compute units: ${budget.computeUnits}`);
+     * console.log(`Priority fee: ${budget.totalPriorityFeeLamports} lamports`);
+     *
+     * // High priority for time-sensitive trades
+     * const urgentBudget = swapManager.estimateComputeBudget(quote, "high");
+     *
+     * // Use in transaction
+     * import { ComputeBudgetProgram } from "@solana/web3.js";
+     *
+     * const tx = new Transaction()
+     *   .add(
+     *     ComputeBudgetProgram.setComputeUnitLimit({
+     *       units: budget.computeUnits
+     *     })
+     *   )
+     *   .add(
+     *     ComputeBudgetProgram.setComputeUnitPrice({
+     *       microLamports: budget.microLamportsPerCU
+     *     })
+     *   )
+     *   .add(swapInstruction);
+     * ```
+     */
+    estimateComputeBudget(quote: SwapQuoteResult, priorityLevel?: "low" | "medium" | "high"): {
+        computeUnits: number;
+        microLamportsPerCU: number;
+        totalPriorityFeeLamports: number;
+    };
+    /**
+     * Determines if a cached quote is still valid
+     *
+     * Uses time-based TTL (2 seconds per team spec). This balances freshness
+     * (quotes aren't too stale) with performance (enough caching to avoid RPC spam)
+     * for low-traffic applications.
+     *
+     * Why 2 seconds: Team spec recommends 2-second polling/caching to match
+     * app.stabble.org traffic patterns. More aggressive than traditional 5-10s
+     * but appropriate for current expected usage.
+     */
+    private isCacheValid;
+    /**
+     * Evicts oldest entry when cache is full (LRU eviction)
+     *
+     * Why LRU (Least Recently Used): Simple and effective. The oldest entries are
+     * least likely to be requested again. More sophisticated strategies (LFU, ARC)
+     * add complexity for minimal benefit in this use case.
+     *
+     * Why 1000 max size: Balances memory usage with hit rate. Each entry is ~500 bytes,
+     * so 1000 entries = ~500KB. This is negligible memory-wise but large enough to
+     * cover most active pools in a session.
+     *
+     * Why we need a cap at all: Without limits, cache could grow unbounded if someone
+     * queries many different pools or amounts. This would cause memory leaks in
+     * long-running applications.
+     */
+    private evictOldestCacheEntry;
+    /**
+     * Gets a swap quote using simple calculation (no tick traversal)
+     *
+     * Why this is the default: For 90% of swaps (small amounts, liquid pools), simple
+     * calculation is accurate enough and 3-5x faster than accurate calculation. Users
+     * get instant feedback in UIs without sacrificing meaningful accuracy.
+     *
+     * Why caching matters here: UI components often request quotes repeatedly as users
+     * type amounts. Without caching, each keystroke would trigger RPC calls. With
+     * caching, only the first request hits RPC; subsequent requests are instant.
+     *
+     * Cache behavior:
+     * - Quotes are cached for 5 seconds by default (balances freshness with performance)
+     * - If price streaming is enabled, cache is invalidated immediately on price changes
+     * - Cache uses LRU eviction with a max size of 1000 entries (prevents memory leaks)
+     *
+     * @param poolAddress - Address of the CLMM pool
+     * @param params - Swap parameters including tokens and amount
+     * @param params.tokenIn - Address of the input token
+     * @param params.tokenOut - Address of the output token
+     * @param params.amountIn - Amount of input token to swap (in base units)
+     * @param params.slippageTolerance - Optional slippage tolerance (0-1, default: 0.01 = 1%)
+     * @param params.poolState - Optional: Pre-fetched pool state to avoid RPC call (optimization for frontends with API data)
+     * @param params.ammConfig - Optional: Pre-fetched AMM config to avoid RPC call
+     * @param options - Optional fetch configuration
+     * @param options.signal - AbortSignal to cancel the request if needed
+     * @param options.allowStale - Return stale data immediately and refresh in background
+     *
+     * @returns Swap quote result with execution price, impact, fees, and minimum output
+     *
+     * @throws {ClmmError} PRICE_SLIPPAGE if slippage tolerance is invalid
+     * @throws {ClmmError} SWAP_AMOUNT_CANNOT_BE_ZERO if amount is <= 0
+     * @throws {ClmmError} POOL_NOT_FOUND if pool doesn't contain the token pair
+     *
+     * @example
+     * ```typescript
+     * // Basic usage (SDK fetches pool state via RPC)
+     * const quote = await swapManager.getSwapQuote(poolAddress, {
+     *   tokenIn: usdcAddress,
+     *   tokenOut: solAddress,
+     *   amountIn: new BN(1_000_000), // 1 USDC (6 decimals)
+     *   slippageTolerance: 0.005 // 0.5%
+     * });
+     *
+     * // Optimized for frontend with API data (avoids redundant RPC calls)
+     * const poolData = await fetch('/api/pools/' + poolAddress).then(r => r.json());
+     * const quote = await swapManager.getSwapQuote(poolAddress, {
+     *   tokenIn: usdcAddress,
+     *   tokenOut: solAddress,
+     *   amountIn: new BN(1_000_000),
+     *   poolState: poolData.state, // Pass pre-fetched data
+     *   ammConfig: poolData.ammConfig
+     * });
+     *
+     * // With abort signal for cancellable requests
+     * const controller = new AbortController();
+     * const quote = await swapManager.getSwapQuote(poolAddress, {
+     *   tokenIn: usdcAddress,
+     *   tokenOut: solAddress,
+     *   amountIn: new BN(1_000_000),
+     * }, {
+     *   signal: controller.signal
+     * });
+     *
+     * // With stale-while-revalidate for better UX
+     * const quote = await swapManager.getSwapQuote(poolAddress, {
+     *   tokenIn: usdcAddress,
+     *   tokenOut: solAddress,
+     *   amountIn: new BN(1_000_000),
+     * }, {
+     *   allowStale: true // Returns immediately, refreshes in background
+     * });
+     *
+     * console.log(`Price: ${quote.executionPrice}`);
+     * console.log(`Impact: ${quote.priceImpactPercent}%`);
+     * console.log(`Min output: ${quote.minimumAmountOut}`);
+     * ```
+     */
+    getSwapQuote(poolAddress: Address, params: Omit<SwapParams, "wallet"> & {
+        tokenIn: Address;
+        tokenOut: Address;
+        poolState?: PoolState;
+        ammConfig?: AmmConfig;
+    }, options?: {
+        signal?: AbortSignal;
+        allowStale?: boolean;
+    }): Promise<SwapQuoteResult>;
+    /**
+     * Gets a swap quote using accurate calculation (with tick array traversal)
+     *
+     * Why this exists alongside getSwapQuote: Simple calculation assumes liquidity is
+     * concentrated at current price. For small swaps this is fine. But large swaps cross
+     * many ticks, each with different liquidity. Without traversing ticks, we'd
+     * underestimate price impact and users would get less than quoted.
+     *
+     * When to use this over getSwapQuote:
+     * 1. Large swaps (>5% of pool liquidity) - price impact is non-linear
+     * 2. Before building swap instructions - ensures on-chain result matches quote
+     * 3. When users demand precision - some use cases can't tolerate estimation error
+     *
+     * Cost trade-off: 2-5 additional RPC calls to fetch tick arrays, adding 200-500ms
+     * latency. Worth it for accuracy when executing valuable swaps.
+     *
+     * The method:
+     * 1. Fetches required tick arrays based on swap size estimation
+     * 2. Simulates tick-by-tick swap execution
+     * 3. Returns detailed quote with crossed ticks and price impact breakdown
+     *
+     * @param poolAddress - Address of the CLMM pool
+     * @param params - Swap parameters including tokens and amount
+     * @param params.tokenIn - Address of the input token
+     * @param params.tokenOut - Address of the output token
+     * @param params.amountIn - Amount of input token to swap (in base units)
+     * @param params.slippageTolerance - Optional slippage tolerance (0-1, default: 0.01 = 1%)
+     * @param params.tickArrayCount - Optional override for number of tick arrays to fetch
+     * @param options - Optional fetch configuration
+     * @param options.signal - AbortSignal to cancel the request if needed
+     * @param options.allowStale - Return stale data immediately and refresh in background
+     *
+     * @returns Detailed swap quote with tick information and price breakdown
+     *
+     * @throws {ClmmError} PRICE_SLIPPAGE if slippage tolerance is invalid
+     * @throws {ClmmError} SWAP_AMOUNT_CANNOT_BE_ZERO if amount is <= 0
+     * @throws {ClmmError} POOL_NOT_FOUND if pool doesn't contain the token pair
+     *
+     * @example
+     * ```typescript
+     * const quote = await swapManager.getAccurateSwapQuote(poolAddress, {
+     *   tokenIn: usdcAddress,
+     *   tokenOut: solAddress,
+     *   amountIn: new BN(10_000_000_000), // 10,000 USDC (large swap)
+     *   slippageTolerance: 0.02 // 2%
+     * });
+     *
+     * console.log(`Crossed ${quote.crossedTicks} ticks`);
+     * console.log(`End price: ${quote.endPrice}`);
+     * console.log(`Price impact breakdown:`, quote.priceImpactBreakdown);
+     * ```
+     */
+    getAccurateSwapQuote(poolAddress: Address, params: Omit<SwapParams, "wallet"> & {
+        tokenIn: Address;
+        tokenOut: Address;
+        tickArrayCount?: number;
+    }, options?: {
+        signal?: AbortSignal;
+        allowStale?: boolean;
+    }): Promise<DetailedSwapQuote>;
+    private fetchTickArraysForSwap;
+    /**
+     * Estimates the number of tick arrays needed for a swap.
+     * Uses a conservative approach with safety buffers to prevent mid-swap failures.
+     *
+     * Why estimation is necessary: We need to know which tick arrays to fetch before
+     * we can calculate the accurate swap. But we can't know exactly how many ticks
+     * we'll cross without doing the calculation. Chicken-and-egg problem.
+     *
+     * Solution: Conservative estimation. We estimate based on swap size relative to
+     * liquidity, then add a safety buffer. Better to fetch extra arrays (slight
+     * performance cost) than to fetch too few and have the swap fail on-chain.
+     *
+     * Why the +3 buffer: In sparse liquidity situations, the swap might skip over
+     * initialized ticks faster than expected. The buffer ensures we have enough
+     * arrays even in worst-case scenarios. Orca and Uniswap use similar buffers.
+     *
+     * Why cap at 20: Prevents pathological cases (e.g., nearly empty pools) from
+     * fetching dozens of arrays, while still covering very large swaps or sparse
+     * liquidity scenarios. 20 arrays cover ~400 ticks, enough for most edge cases.
+     *
+     * @param pool - Current pool state
+     * @param amountIn - Amount being swapped
+     * @returns Number of tick arrays to fetch (includes safety buffer)
+     */
+    private estimateTickArrayCount;
+    private getRequiredTickArrays;
+    getBatchQuotes(poolAddress: Address, params: Omit<SwapParams, "wallet"> & {
+        amounts: BN[];
+        tokenIn: Address;
+        tokenOut: Address;
+    }, options?: {
+        signal?: AbortSignal;
+        allowStale?: boolean;
+    }): Promise<Map<string, SwapQuoteResult>>;
+    calculateOptimalSlippage(quote: SwapQuote, options?: {
+        riskTolerance?: "low" | "medium" | "high";
+        maxSlippage?: number;
+    }): number;
+    getDetailedPriceImpact(poolAddress: Address, params: Omit<SwapParams, "wallet">, options?: {
+        signal?: AbortSignal;
+        allowStale?: boolean;
+    }): Promise<DetailedPriceImpact>;
+    /**
+     * Simulates a swap to validate it will succeed and identify potential issues
+     *
+     * Why simulation matters: On-chain transactions cost money and can't be undone.
+     * Running a simulation first catches problems before they cost users SOL in
+     * transaction fees. This is especially important for swaps that might fail due to:
+     * - Excessive slippage (price moved since quote)
+     * - Insufficient output (amount too small after fees)
+     * - Math errors (overflow, underflow)
+     *
+     * Why we check price impact thresholds: Different impact levels warrant different
+     * user warnings:
+     * - < 5%: Normal, no warning
+     * - 5-15%: High impact, warn user they might get sandwich attacked
+     * - > 15%: Critical, likely to fail or result in terrible execution
+     *
+     * Why we validate output amount: Some swaps result in fractional output amounts
+     * that round to zero. Better to catch this in simulation than discover it after
+     * the transaction succeeds but user got nothing.
+     *
+     * Use this before building instructions to catch problems early and provide
+     * better user feedback.
+     *
+     * @param poolAddress - Address of the CLMM pool
+     * @param params - Swap parameters to simulate
+     * @param options - Optional fetch configuration
+     * @param options.signal - AbortSignal to cancel the request if needed
+     * @param options.allowStale - Return stale data immediately and refresh in background
+     *
+     * @returns Simulation result with success flag, quote, errors, and warnings
+     *
+     * @example
+     * ```typescript
+     * const simulation = await swapManager.simulateSwap(poolAddress, {
+     *   tokenIn: usdcAddress,
+     *   tokenOut: solAddress,
+     *   amountIn: new BN(100_000_000_000), // Large amount
+     *   slippageTolerance: 0.01
+     * });
+     *
+     * if (!simulation.willSucceed) {
+     *   console.error('Swap will fail:', simulation.errors);
+     *   return;
+     * }
+     *
+     * if (simulation.warnings.length > 0) {
+     *   console.warn('Warnings:', simulation.warnings);
+     *   // Show user confirmation dialog
+     * }
+     *
+     * // Proceed with swap
+     * const instruction = await swapManager.buildSwapInstruction(
+     *   poolAddress,
+     *   wallet,
+     *   params,
+     *   simulation.quote
+     * );
+     * ```
+     */
+    simulateSwap(poolAddress: Address, params: SwapParams, options?: {
+        signal?: AbortSignal;
+        allowStale?: boolean;
+    }): Promise<SwapSimulation>;
+    /**
+     * Builds a Solana instruction for executing a swap
+     *
+     * Why this is complex: A swap instruction needs many accounts and parameters:
+     * - Pool and config accounts (state to read)
+     * - Token vaults (where tokens are held)
+     * - User token accounts (where tokens come from/go to)
+     * - Observation account (for TWAP oracle)
+     * - Price limits (for MEV protection)
+     *
+     * This method handles all that complexity so users just provide tokens and amounts.
+     *
+     * Why we accept priorQuote: Common pattern is to show a quote to the user, get
+     * confirmation, then execute. If we re-ran simulation here, the price might have
+     * changed between display and execution. Accepting priorQuote lets users execute
+     * exactly what they confirmed, with slippage protection handling price movement.
+     *
+     * Why we simulate if no quote provided: Catch-all safety net. If someone builds
+     * an instruction without checking first, we prevent obviously broken swaps from
+     * being sent on-chain.
+     *
+     * The instruction is ready to be added to a transaction and sent to the network.
+     *
+     * @param poolAddress - Address of the CLMM pool
+     * @param payer - Transaction signer (wallet that will execute the swap)
+     * @param params - Swap parameters
+     * @param params.tokenIn - Input token address
+     * @param params.tokenOut - Output token address
+     * @param params.amountIn - Amount to swap (in base units)
+     * @param params.slippageTolerance - Optional slippage tolerance (0-1)
+     * @param params.sqrtPriceLimitX64 - Optional custom price limit (advanced)
+     * @param priorQuote - Optional pre-computed quote (skips simulation if provided)
+     *
+     * @returns Solana instruction ready to be executed
+     *
+     * @throws {ClmmError} SWAP_SIMULATION_FAILED if pre-execution simulation fails
+     *
+     * @example
+     * ```typescript
+     * // Get quote first (recommended for displaying to user)
+     * const quote = await swapManager.getAccurateSwapQuote(poolAddress, {
+     *   tokenIn: usdcAddress,
+     *   tokenOut: solAddress,
+     *   amountIn: new BN(1_000_000),
+     *   slippageTolerance: 0.01
+     * });
+     *
+     * // Build instruction using the quote
+     * const instruction = await swapManager.buildSwapInstruction(
+     *   poolAddress,
+     *   wallet,
+     *   {
+     *     tokenIn: usdcAddress,
+     *     tokenOut: solAddress,
+     *     amountIn: new BN(1_000_000),
+     *     slippageTolerance: 0.01
+     *   },
+     *   quote // Reuse quote to avoid re-simulation
+     * );
+     *
+     * // Add to transaction and send
+     * const tx = new Transaction().add(instruction);
+     * ```
+     */
+    buildSwapInstruction(poolAddress: Address, payer: TransactionSigner, params: SwapParams & {
+        sqrtPriceLimitX64?: BN;
+    }, priorQuote?: SwapQuote, options?: {
+        signal?: AbortSignal;
+    }): Promise<Instruction>;
+    getCurrentPrice(poolAddress: Address, options?: {
+        signal?: AbortSignal;
+        allowStale?: boolean;
+    }): Promise<Decimal>;
+    /**
+     * Validates pool price against market price from REST API
+     *
+     * Why this matters: On-chain pool state can become stale between blocks or lag
+     * behind market prices due to arbitrage delays. Comparing against the REST API
+     * helps detect:
+     * - Stale pool data (price hasn't updated recently)
+     * - Arbitrage opportunities (on-chain price differs from market)
+     * - Potential MEV risks (large price discrepancies)
+     *
+     * This uses the enhanced PriceApiClient with:
+     * - Automatic retry on failures
+     * - Concurrency control
+     * - Abort signal support
+     * - Staleness detection
+     *
+     * @param poolAddress - Pool to validate
+     * @param opts - Optional configuration
+     * @param opts.signal - AbortSignal to cancel the request
+     * @param opts.maxDivergence - Maximum acceptable price divergence (0-1, default: 0.05 = 5%)
+     * @returns Validation result with price comparison
+     *
+     * @throws {Error} If priceApiConfig is not configured
+     *
+     * @example
+     * ```typescript
+     * const validation = await swapManager.validatePoolPrice(poolAddress, {
+     *   maxDivergence: 0.02 // 2% tolerance
+     * });
+     *
+     * if (!validation.isValid) {
+     *   console.warn('Pool price diverges from market:', validation);
+     *   // Maybe increase slippage or wait for arbitrage
+     * }
+     * ```
+     */
+    validatePoolPrice(poolAddress: Address, opts?: {
+        signal?: AbortSignal;
+        maxDivergence?: number;
+    }): Promise<{
+        isValid: boolean;
+        onChainPrice: Decimal;
+        marketPrice?: Decimal;
+        divergence?: number;
+        divergencePercent?: number;
+        warning?: string;
+    }>;
+    /**
+     * Gets swap quote with optional market price validation
+     *
+     * Enhanced version of getSwapQuote that validates pool price against market
+     * prices when enablePriceValidation is enabled in config.
+     *
+     * @param poolAddress - Pool address
+     * @param params - Swap parameters
+     * @param opts - Optional configuration
+     * @param opts.signal - AbortSignal to cancel the request
+     * @param opts.skipValidation - Skip validation even if enabled (for performance)
+     * @returns Swap quote result with optional validation info
+     */
+    getValidatedSwapQuote(poolAddress: Address, params: Omit<SwapParams, "wallet"> & {
+        tokenIn: Address;
+        tokenOut: Address;
+    }, opts?: {
+        signal?: AbortSignal;
+        skipValidation?: boolean;
+    }): Promise<{
+        quote: SwapQuoteResult;
+        validation?: {
+            isValid: boolean;
+            onChainPrice: Decimal;
+            marketPrice?: Decimal;
+            divergencePercent?: number;
+            warning?: string;
+        };
+    }>;
+}
 //# sourceMappingURL=swap.d.ts.map