@gala-chain/launchpad-sdk 3.31.2 → 4.0.1-beta.0

package/dist/src/services/GSwapService.d.ts

@@ -0,0 +1,817 @@
+import { LoggerBase } from './BaseService';
+import { WebSocketService } from './WebSocketService';
+import { DexQuoteService } from './DexQuoteService';
+import type { SwapQuoteParams, SwapQuoteResult, ExecuteSwapParams, ExecuteSwapResult, UserAsset, PoolInfo, GSwapServiceConfig, GSwapPosition, PoolSlot0Data, PoolPriceData, GetLiquidityPositionsOptions, GetLiquidityPositionsResult } from '../types/gswap.dto';
+import type { GSwapEstimateRemoveLiquidityResult, GSwapAddLiquidityResult } from '../types/gswap-responses.types';
+import type { TokenClassKey } from '../types/common';
+export declare class GSwapService extends LoggerBase {
+    private gatewayClient;
+    private dexBackendClient;
+    private tokenConverter;
+    private webSocketService;
+    private dexQuoteService;
+    private getWalletAddress;
+    private galaChainBaseUrl;
+    private bundlerBaseUrl;
+    private gatewayBaseUrl;
+    private privateKey;
+    private pricingConcurrency;
+    constructor(config: GSwapServiceConfig, webSocketService: WebSocketService, dexQuoteService?: DexQuoteService);
+    /**
+     * Set the pricing concurrency level for liquidity position pricing operations
+     * This is set once at SDK initialization and applies to all pricing operations
+     * @param concurrency Number of concurrent pricing requests (default: 5, max recommended: 20)
+     */
+    setPricingConcurrency(concurrency: number): void;
+    /**
+     * Get swap quote for exact input (spending known amount)
+     *
+     * Uses DexQuoteService with dynamic fee tier discovery ([3000, 500, 10000]).
+     * NEVER falls back - if all fee tiers fail, throws loudly to expose the real problem.
+     *
+     * Guarantees: All quotes are ALWAYS fresh (never cached) to prevent MEV in volatile markets.
+     *
+     * @param params Quote request with fromToken, toToken, and input amount
+     * @returns Quote with estimated output, actual price impact, and fees
+     * @throws GSwapQuoteError if DexQuoteService not configured or all fee tiers fail
+     */
+    getSwapQuoteExactInput(params: SwapQuoteParams): Promise<SwapQuoteResult>;
+    /**
+     * Get swap quote for exact output (receive known amount)
+     *
+     * Uses DexQuoteService with dynamic fee tier discovery ([3000, 500, 10000]).
+     * NEVER falls back - if all fee tiers fail, throws loudly to expose the real problem.
+     *
+     * Guarantees: All quotes are ALWAYS fresh (never cached) to prevent MEV in volatile markets.
+     *
+     * @param params Quote request with fromToken, toToken, and desired output
+     * @returns Quote with required input, actual price impact, and fees
+     * @throws GSwapQuoteError if DexQuoteService not configured or all fee tiers fail
+     */
+    getSwapQuoteExactOutput(params: SwapQuoteParams): Promise<SwapQuoteResult>;
+    /**
+     * Execute a token swap with slippage protection
+     * @param params Swap execution parameters
+     * @returns Swap result with transaction details
+     */
+    executeSwap(params: ExecuteSwapParams): Promise<ExecuteSwapResult>;
+    /**
+     * Get user's token assets/balances
+     *
+     * Fetches all tokens held by a user from the GSwap API with graceful handling
+     * of token conversion. Assets that cannot be converted are skipped with debug logging.
+     *
+     * @param walletAddress User's wallet address (e.g., "eth|0x1234...")
+     * @returns Array of user assets with balances (skips unconvertible assets)
+     * @throws {GSwapAssetError} When the API call itself fails or wallet address is invalid
+     * @since v3.30.0 Now gracefully skips unconvertible assets instead of throwing
+     */
+    getUserAssets(walletAddress: string, page?: number, limit?: number): Promise<UserAsset[]>;
+    /**
+     * Get all user assets across all pages (auto-paginated)
+     * @param walletAddress Wallet address to fetch assets for
+     * @returns All user assets across all pages
+     */
+    getAllUserAssets(walletAddress: string): Promise<UserAsset[]>;
+    /**
+     * Get pool information for token pair
+     * @param tokenA First token
+     * @param tokenB Second token
+     * @returns Pool information
+     */
+    getPoolInfo(tokenA: string, tokenB: string): Promise<PoolInfo>;
+    /**
+     * Get all liquidity positions for a wallet
+     * @param ownerAddress User's wallet address
+     * @param limit Maximum number of positions to return (default 100)
+     * @param bookmark Pagination bookmark
+     * @returns Array of liquidity positions with full type safety
+     */
+    /**
+     * Chunk array into smaller batches for concurrent processing
+     * @private
+     */
+    private chunkArray;
+    /**
+     * Fetch real-time pricing for liquidity positions
+     * Deduplicates pools and processes in chunks for optimal performance
+     * @private
+     */
+    private fetchPositionPrices;
+    /**
+     * Normalize GSwap API position response to match LiquidityPosition interface
+     * Handles different field naming conventions from the API
+     */
+    private normalizePositionResponse;
+    /**
+     * Parse token string flexibly - supports both delimited and simple formats
+     * @param tokenString Token in format "GALA" or "GALA|Unit|none|none"
+     * @returns TokenClassKey object
+     */
+    private parseTokenFlexible;
+    getUserLiquidityPositions(ownerAddress: string, limit?: number, bookmark?: string, options?: GetLiquidityPositionsOptions): Promise<GetLiquidityPositionsResult>;
+    /**
+     * Get ALL user liquidity positions with automatic pagination
+     * Automatically fetches all pages of liquidity positions for a wallet
+     * Uses bookmark-based cursor pagination internally
+     * @param ownerAddress User's wallet address
+     * @param options Optional configuration for pricing enrichment
+     * @returns All liquidity positions combined from all pages, optionally with pricing data
+     */
+    getAllSwapUserLiquidityPositions(ownerAddress: string, options?: GetLiquidityPositionsOptions): Promise<GSwapPosition[] | GetLiquidityPositionsResult>;
+    /**
+     * Get a specific liquidity position
+     * @param ownerAddress User's wallet address
+     * @param position Position details (token0, token1, fee, tickLower, tickUpper)
+     * @returns Detailed position information with full type safety
+     */
+    getLiquidityPosition(ownerAddress: string, position: {
+        token0: string;
+        token1: string;
+        fee: number;
+        tickLower: number;
+        tickUpper: number;
+    }): Promise<GSwapPosition>;
+    /**
+     * Get a liquidity position by its ID
+     * @param ownerAddress User's wallet address
+     * @param positionId Position UUID
+     * @param token0 Optional first token for compound key lookup (token0)
+     * @param token1 Optional second token for compound key lookup (token1)
+     * @param feeTier Optional fee tier for compound key lookup (500, 3000, or 10000)
+     * @param tickLower Optional lower tick boundary for compound key lookup
+     * @param tickUpper Optional upper tick boundary for compound key lookup
+     * @returns Detailed position information with full type safety
+     */
+    getLiquidityPositionById(ownerAddress: string, positionId: string, token0?: string | Record<string, unknown>, token1?: string | Record<string, unknown>, feeTier?: number, tickLower?: number, tickUpper?: number): Promise<GSwapPosition>;
+    /**
+     * Fetch a single liquidity position using ONLY the compound key (direct HTTP call)
+     * Most efficient when you already have all position parameters
+     * @param params Position parameters - token0, token1, fee, tickLower, tickUpper, owner (ALL REQUIRED)
+     * @returns Detailed position information with full type safety
+     * @remarks
+     * - Does NOT use positionId (not needed or accepted)
+     * - Single direct HTTP call to GalaChain (no GSwap SDK)
+     * - Best for cases where caller has full position parameters
+     * - Requires: token0, token1, fee (500|3000|10000), tickLower, tickUpper, owner
+     */
+    fetchSwapPositionDirect(params: {
+        token0: string;
+        token1: string;
+        fee: number;
+        tickLower: number;
+        tickUpper: number;
+        owner: string;
+    }): Promise<GSwapPosition>;
+    /**
+     * Estimate tokens received from removing liquidity
+     * @param args Removal estimation parameters
+     * @returns Estimated token amounts
+     */
+    estimateRemoveLiquidity(args: {
+        token0: string;
+        token1: string;
+        fee: number;
+        liquidity: string;
+        tickLower: number;
+        tickUpper: number;
+    }): Promise<GSwapEstimateRemoveLiquidityResult>;
+    /**
+     * Add liquidity using price ranges (user-friendly)
+     * @param args Liquidity addition parameters with price ranges
+     * @returns Transaction result with position ID
+     */
+    addLiquidityByPrice(args: {
+        token0: string;
+        token1: string;
+        fee: number;
+        minPrice: string;
+        maxPrice: string;
+        amount0Desired: string;
+        amount1Desired: string;
+        amount0Min?: string;
+        amount1Min?: string;
+    }): Promise<GSwapAddLiquidityResult & {
+        timestamp?: Date;
+        wait?: (timeoutMs?: number) => Promise<void>;
+    }>;
+    /**
+     * Add liquidity to GSwap pool using precise tick ranges (concentrated liquidity)
+     *
+     * **CRITICAL: WebSocket-First Pattern**
+     * This method ensures WebSocket connection is established BEFORE submitting the
+     * transaction to prevent race conditions where the transaction confirms before
+     * the listener becomes active. This is essential because:
+     *
+     * 1. WebSocket listener created IMMEDIATELY after transactionId received
+     * 2. Socket.IO buffers events for registered listeners
+     * 3. If listener not active when transaction confirms, confirmation is missed
+     * 4. Position discovery retry logic handles indexing delays (up to 11 seconds)
+     *
+     * **Position Discovery Flow**
+     * After bundler submits transaction:
+     * 1. WebSocket listener monitors for on-chain confirmation (~2-3 seconds)
+     * 2. Once confirmed, waits for backend position indexing (5-11 seconds)
+     * 3. Queries positions API up to 3 times with exponential backoff
+     * 4. Matches position by token pair + fee tier (handles multiple positions)
+     * 5. Fetches full position details for complete data
+     *
+     * **Token Format Support**
+     * - String tokens: 'GALA', 'GUSDC' → auto-converted to TokenClassKey
+     * - TokenClassKey: { collection, category, type, additionalKey }
+     * - Both formats normalized to TokenClassKey for bundler submission
+     *
+     * **Tick Range Details**
+     * - Supports negative ticks for full concentrated liquidity ranges
+     * - Example: tickLower: -1080, tickUpper: 900
+     * - Must be multiples of tickSpacing (determined by fee tier)
+     * - Fee 500bps: tickSpacing=10, Fee 3000bps: tickSpacing=60, Fee 10000bps: tickSpacing=200
+     *
+     * @param args Liquidity addition parameters
+     * @param args.token0 First token (string or TokenClassKey)
+     * @param args.token1 Second token (string or TokenClassKey)
+     * @param args.fee Fee tier in basis points (500, 3000, or 10000)
+     * @param args.tickLower Lower tick boundary (supports negative values)
+     * @param args.tickUpper Upper tick boundary
+     * @param args.amount0Desired Desired amount of token0
+     * @param args.amount1Desired Desired amount of token1
+     * @param args.amount0Min Optional minimum token0 (default: '0')
+     * @param args.amount1Min Optional minimum token1 (default: '0')
+     *
+     * @returns Promise<GSwapAddLiquidityResult> Transaction result with:
+     *   - transactionId: Bundler transaction ID
+     *   - positionId: GSwap position ID (discovered from on-chain data)
+     *   - status: Transaction status from WebSocket
+     *   - liquidity: Position liquidity amount
+     *   - amount0/amount1: Actual amounts added
+     *   - wait(): Async method to wait for confirmation
+     *
+     * @throws GSwapPositionError if private key unavailable or bundler submission fails
+     *
+     * @example
+     * // Add liquidity with explicit tick range
+     * const result = await sdk.addSwapLiquidityByTicks({
+     *   token0: 'GALA',
+     *   token1: 'GUSDC',
+     *   fee: 3000,
+     *   tickLower: -1080,  // Supports negative ticks
+     *   tickUpper: 900,
+     *   amount0Desired: '100',
+     *   amount1Desired: '100',
+     * });
+     * console.log('Position ID:', result.positionId);
+     * await result.wait();  // Wait for on-chain confirmation
+     */
+    addSwapLiquidityByTicks(args: {
+        token0: string | TokenClassKey;
+        token1: string | TokenClassKey;
+        fee: number;
+        tickLower: number;
+        tickUpper: number;
+        amount0Desired: string;
+        amount1Desired: string;
+        amount0Min?: string;
+        amount1Min?: string;
+    }): Promise<GSwapAddLiquidityResult & {
+        timestamp?: Date;
+        wait?: (timeoutMs?: number) => Promise<void>;
+    }>;
+    /**
+     * Monitor a bundler transaction with graceful fallback on timeout
+     *
+     * **Pattern Overview**
+     * This helper consolidates the common error handling pattern used by all bundler-direct
+     * operations (removeSwapLiquidity, collectSwapPositionFees, etc.):
+     *
+     * 1. Set up WebSocket listener BEFORE bundler submission (already done by caller)
+     * 2. Try to await transaction confirmation via WebSocket
+     * 3. If timeout occurs: Return partial result with status: 'SUBMITTED'
+     * 4. If successful: Return confirmed result with on-chain status
+     * 5. Both cases include a .wait() method for retry/manual monitoring
+     *
+     * **Why This Pattern Matters**
+     * - Prevents race conditions (listener active before transaction confirmation)
+     * - Handles network timeouts gracefully (users still get transaction ID)
+     * - Provides flexibility (users can call .wait() again if needed)
+     * - Consistent error handling across all bundler operations
+     *
+     * @param transactionId Transaction ID from bundler submission
+     * @param transactionPromise WebSocket monitoring promise (already created before bundler call)
+     * @param operationName Operation name for logging context (e.g., 'liquidity removal')
+     * @returns Bundler operation result with status and wait() method
+     * @private
+     */
+    private monitorBundlerTransaction;
+    /**
+     * Remove liquidity from an existing concentrated liquidity position
+     *
+     * **CRITICAL: WebSocket-First Pattern**
+     * This method ensures WebSocket connection is established BEFORE submitting the
+     * transaction to prevent race conditions where the transaction confirms before
+     * the listener becomes active. This is essential because:
+     *
+     * 1. WebSocket listener created IMMEDIATELY after transactionId received
+     * 2. Socket.IO buffers events for registered listeners
+     * 3. If listener not active when transaction confirms, confirmation is missed
+     * 4. Graceful fallback returns partial result with transaction ID on timeout
+     *
+     * **Error Handling & Recovery**
+     * If WebSocket monitoring times out (after 60 seconds):
+     * - Returns `{ transactionId, status: 'SUBMITTED' }` indicating transaction was accepted
+     * - Transaction may still succeed on-chain even if monitoring fails
+     * - Users can call `.wait()` again to retry monitoring
+     * - Recommended: retry monitoring after waiting or check on-chain later
+     *
+     * **Partial vs Complete Removal**
+     * - Partial: Set liquidity to a fraction (e.g., 50% of current amount)
+     * - Complete: Set liquidity to the full amount to close the position
+     * - Retrieved from position details via `getSwapUserLiquidityPositions()`
+     *
+     * **Token Format Support**
+     * - String tokens: 'GALA', 'GUSDC' → auto-converted to TokenClassKey
+     * - TokenClassKey: { collection, category, type, additionalKey }
+     * - Both formats normalized to TokenClassKey for bundler submission
+     *
+     * @param args Liquidity removal parameters
+     * @param args.token0 First token (string or TokenClassKey)
+     * @param args.token1 Second token (string or TokenClassKey)
+     * @param args.fee Fee tier in basis points (500, 3000, or 10000)
+     * @param args.tickLower Lower tick boundary of the position
+     * @param args.tickUpper Upper tick boundary of the position
+     * @param args.liquidity Amount of liquidity to remove (partial or complete)
+     * @param args.amount0Min Optional minimum token0 to accept (default: '0')
+     * @param args.amount1Min Optional minimum token1 to accept (default: '0')
+     * @param args.positionId Optional position ID for tracking/verification
+     *
+     * @returns Promise<GSwapRemoveLiquidityResult> Transaction result with:
+     *   - transactionId: Bundler transaction ID
+     *   - status: Transaction status from WebSocket (or 'SUBMITTED' if timeout)
+     *   - timestamp: When transaction was submitted
+     *   - wait(): Async method to monitor or retry confirmation
+     *
+     * @throws GSwapPositionError if private key unavailable or bundler submission fails
+     *
+     * @example
+     * // Get position first
+     * const positions = await sdk.getSwapUserLiquidityPositions(walletAddress);
+     * const position = positions[0];
+     *
+     * // Remove 50% of liquidity
+     * const liquidityToRemove = (parseFloat(position.liquidity) * 50) / 100;
+     * const result = await sdk.removeSwapLiquidity({
+     *   token0: 'GALA',
+     *   token1: 'GUSDC',
+     *   fee: 3000,
+     *   tickLower: position.tickLower,
+     *   tickUpper: position.tickUpper,
+     *   liquidity: liquidityToRemove.toString(),
+     *   amount0Min: '0',
+     *   amount1Min: '0',
+     *   positionId: position.positionId,
+     * });
+     *
+     * console.log('Removal submitted:', result.transactionId);
+     * await result.wait();  // Wait for on-chain confirmation
+     * console.log('Final status:', result.status);
+     */
+    removeLiquidity(args: {
+        token0: string | TokenClassKey;
+        token1: string | TokenClassKey;
+        fee: number;
+        tickLower: number;
+        tickUpper: number;
+        liquidity: string;
+        amount0Min?: string;
+        amount1Min?: string;
+        positionId?: string;
+    }): Promise<GSwapAddLiquidityResult>;
+    /**
+     * Collect accumulated trading fees from a concentrated liquidity position
+     *
+     * **CRITICAL: WebSocket-First Pattern**
+     * This method ensures WebSocket connection is established BEFORE submitting the
+     * transaction to prevent race conditions where the transaction confirms before
+     * the listener becomes active. This is essential because:
+     *
+     * 1. WebSocket listener created IMMEDIATELY after transactionId received
+     * 2. Socket.IO buffers events for registered listeners
+     * 3. If listener not active when transaction confirms, confirmation is missed
+     * 4. Graceful fallback returns partial result with transaction ID on timeout
+     *
+     * **Error Handling & Recovery**
+     * If WebSocket monitoring times out (after 60 seconds):
+     * - Returns `{ transactionId, status: 'SUBMITTED' }` indicating transaction was accepted
+     * - Transaction may still succeed on-chain even if monitoring fails
+     * - Users can call `.wait()` again to retry monitoring
+     * - Recommended: retry monitoring after waiting or check position fees on-chain later
+     *
+     * **Fee Accumulation**
+     * Fees accumulate when your position is in-range and trades execute within your price range.
+     * - In-range fees: Actively accumulating (trading happens in your range)
+     * - Out-of-range fees: Not accumulating (current price outside your range)
+     * - Collect periodically for optimal capital efficiency (fees don't compound)
+     * - Fees are denominated in the two tokens of the pair (token0 and token1)
+     *
+     * **Partial vs Complete Collection**
+     * - Collect all: Set amount0Requested='0' and amount1Requested='0' (default)
+     * - Collect specific amount: Set amount0Requested/amount1Requested to desired amounts
+     * - Partial collection doesn't affect the position's liquidity
+     * - Current fees visible in position details via `getSwapUserLiquidityPositions()`
+     *
+     * **Token Format Support**
+     * - String tokens: 'GALA', 'GUSDC' → auto-converted to TokenClassKey
+     * - TokenClassKey: { collection, category, type, additionalKey }
+     * - Both formats normalized to TokenClassKey for bundler submission
+     *
+     * @param args Fee collection parameters
+     * @param args.token0 First token (string or TokenClassKey)
+     * @param args.token1 Second token (string or TokenClassKey)
+     * @param args.fee Fee tier in basis points (500, 3000, or 10000)
+     * @param args.tickLower Lower tick boundary of the position
+     * @param args.tickUpper Upper tick boundary of the position
+     * @param args.amount0Requested Optional amount of token0 fees to collect (default: '0' = all)
+     * @param args.amount1Requested Optional amount of token1 fees to collect (default: '0' = all)
+     * @param args.positionId Optional position ID for tracking/verification
+     *
+     * @returns Promise<GSwapCollectFeesResult> Transaction result with:
+     *   - transactionId: Bundler transaction ID
+     *   - status: Transaction status from WebSocket (or 'SUBMITTED' if timeout)
+     *   - timestamp: When transaction was submitted
+     *   - wait(): Async method to monitor or retry confirmation
+     *
+     * @throws GSwapPositionError if private key unavailable or bundler submission fails
+     *
+     * @example
+     * // Get position with accumulated fees
+     * const positions = await sdk.getSwapUserLiquidityPositions(walletAddress);
+     * const position = positions[0];
+     *
+     * if (parseFloat(position.feeAmount0) > 0 || parseFloat(position.feeAmount1) > 0) {
+     *   // Collect all accumulated fees
+     *   const result = await sdk.collectSwapPositionFees({
+     *     token0: 'GALA',
+     *     token1: 'GUSDC',
+     *     fee: 3000,
+     *     tickLower: position.tickLower,
+     *     tickUpper: position.tickUpper,
+     *     amount0Requested: '0',  // Collect all token0 fees
+     *     amount1Requested: '0',  // Collect all token1 fees
+     *     positionId: position.positionId,
+     *   });
+     *
+     *   console.log('Fee collection submitted:', result.transactionId);
+     *   await result.wait();  // Wait for on-chain confirmation
+     *   console.log('Fees collected successfully');
+     * }
+     */
+    collectPositionFees(args: {
+        token0: string | TokenClassKey;
+        token1: string | TokenClassKey;
+        fee: number;
+        tickLower: number;
+        tickUpper: number;
+        amount0Requested?: string;
+        amount1Requested?: string;
+        positionId?: string;
+    }): Promise<GSwapAddLiquidityResult>;
+    /**
+     * Get real-time pool state with liquidity depth and current price
+     * @param tokenA First token symbol (e.g., 'GALA')
+     * @param tokenB Second token symbol (e.g., 'GUSDC')
+     * @param feeTier Fee tier (500, 3000, or 10000 basis points)
+     * @returns Pool data with liquidity, current tick, and price
+     */
+    getPoolData(tokenA: string, tokenB: string, feeTier: number): Promise<{
+        tokenA: string;
+        tokenB: string;
+        feeTier: number;
+        liquidity: string;
+        sqrtPriceX96: string;
+        tick: number;
+        feeGrowthGlobal0X128: string;
+        feeGrowthGlobal1X128: string;
+        currentPrice: string;
+    }>;
+    /**
+     * Calculate current market price for a token pair from DEX pool
+     * @param tokenA First token symbol
+     * @param tokenB Second token symbol
+     * @param feeTier Fee tier (500, 3000, or 10000 basis points)
+     * @returns Current spot price without executing trade
+     */
+    calculateDexPoolSpotPrice(tokenA: string, tokenB: string, feeTier: number): Promise<{
+        tokenA: string;
+        tokenB: string;
+        feeTier: number;
+        price: string;
+        invertedPrice: string;
+        tick: number;
+        liquidity: string;
+    }>;
+    /**
+     * Calculate optimal token amounts for concentrated liquidity position
+     * @param tokenA First token symbol
+     * @param tokenB Second token symbol
+     * @param feeTier Fee tier (500, 3000, or 10000 basis points)
+     * @param desiredAmount0 Desired amount of token A
+     * @param desiredAmount1 Desired amount of token B
+     * @param tickLower Lower tick boundary
+     * @param tickUpper Upper tick boundary
+     * @returns Optimal amounts and utilization percentages
+     */
+    calculateOptimalPositionSize(tokenA: string, tokenB: string, feeTier: number, desiredAmount0: string, desiredAmount1: string, tickLower: number, tickUpper: number): Promise<{
+        amount0: string;
+        amount1: string;
+        liquidity: string;
+        ratio: string;
+        utilizationPercent: {
+            amount0: string;
+            amount1: string;
+        };
+    }>;
+    /**
+     * Validate liquidity position parameters before creation
+     * @param tokenA First token symbol
+     * @param tokenB Second token symbol
+     * @param feeTier Fee tier (500, 3000, or 10000 basis points)
+     * @param tickLower Lower tick boundary
+     * @param tickUpper Upper tick boundary
+     * @param amount0 Token A amount
+     * @param amount1 Token B amount
+     * @returns Validation result with errors and warnings
+     */
+    validatePositionParameters(tokenA: string, tokenB: string, feeTier: number, tickLower: number, tickUpper: number, amount0: string, amount1: string): Promise<{
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+        gasEstimate: number;
+        tickSpacing?: number;
+        currentTick?: number;
+        poolLiquidity?: string;
+    }>;
+    /**
+     * Convert human-readable price range to tick boundaries
+     * @param tokenA First token symbol
+     * @param tokenB Second token symbol
+     * @param minPrice Minimum price boundary
+     * @param maxPrice Maximum price boundary
+     * @param feeTier Fee tier (500, 3000, or 10000 basis points)
+     * @returns Calculated tick boundaries and price deviations
+     */
+    calculateTicksForPrice(tokenA: string, tokenB: string, minPrice: string, maxPrice: string, feeTier: number): Promise<{
+        tokenA: string;
+        tokenB: string;
+        feeTier: number;
+        tickLower: number;
+        tickUpper: number;
+        tickSpacing: number;
+        requestedMinPrice: string;
+        requestedMaxPrice: string;
+        actualMinPrice: string;
+        actualMaxPrice: string;
+        priceDeviation: {
+            minPriceDeviation: string;
+            maxPriceDeviation: string;
+        };
+    }>;
+    /**
+     * Convert tick boundaries back to human-readable prices
+     * @param tokenA First token symbol
+     * @param tokenB Second token symbol
+     * @param tickLower Lower tick boundary
+     * @param tickUpper Upper tick boundary
+     * @returns Price range and current price
+     */
+    calculatePriceForTicks(tokenA: string, tokenB: string, tickLower: number, tickUpper: number): Promise<{
+        tokenA: string;
+        tokenB: string;
+        tickLower: number;
+        tickUpper: number;
+        minPrice: string;
+        maxPrice: string;
+        currentPrice?: string;
+        priceRange?: string;
+        tickSpread?: number;
+    }>;
+    /**
+     * Calculate execution price (output per unit input)
+     */
+    private calculateExecutionPrice;
+    /**
+     * Get tick spacing for a given fee tier (Uniswap v3 standard)
+     * @private
+     */
+    private getTickSpacing;
+    /**
+     * Calculate price from sqrtPriceX96 format (Uniswap v3 standard)
+     * price = (sqrtPriceX96 / 2^96)^2
+     * @private
+     */
+    private calculatePriceFromSqrtPriceX96;
+    /**
+     * Calculate price from sqrtPrice in decimal format (GetSlot0 API)
+     * Different from sqrtPriceX96 - GetSlot0 returns already-decoded decimal
+     * Formula: price = sqrtPrice²
+     * @private
+     */
+    private calculatePriceFromSqrtPriceDecimal;
+    /**
+     * Get current pool state (slot0 data) for a token pair
+     * Fetches sqrtPrice, tick, and liquidity from GalaChain Gateway
+     * @param token0 First token symbol or TokenClassKey
+     *   Accepts: "GALA" (plain), "GALA|Unit|none|none" (pipe), "GALA$Unit$none$none" (dollar)
+     * @param token1 Second token symbol or TokenClassKey
+     *   Accepts: "GALA" (plain), "GALA|Unit|none|none" (pipe), "GALA$Unit$none$none" (dollar)
+     * @param fee Fee tier in basis points (500, 3000, 10000)
+     * @returns PoolSlot0Data with current sqrtPrice, tick, liquidity, and feeGrowth
+     */
+    getPoolSlot0(token0: string | TokenClassKey, token1: string | TokenClassKey, fee: number): Promise<PoolSlot0Data>;
+    /**
+     * Get current price for a liquidity position's pool
+     * Fetches slot0 data and calculates token0/token1 price ratio
+     * @param position Position token pair and fee tier
+     */
+    getPositionCurrentPrice(position: {
+        token0: string;
+        token1: string;
+        feeTier: number;
+    }): Promise<PoolPriceData>;
+    /**
+     * Calculate liquidity from amount0 (Uniswap v3 math)
+     * Uses @gala-chain/dex liquidity0() function for production-accurate calculation
+     * @private
+     */
+    private calculateLiquidityFromAmount0;
+    /**
+     * Calculate liquidity from amount1 (Uniswap v3 math)
+     * Uses @gala-chain/dex liquidity1() function for production-accurate calculation
+     * @private
+     */
+    private calculateLiquidityFromAmount1;
+    /**
+     * Calculate amount0 from liquidity (Uniswap v3 math)
+     * Uses @gala-chain/dex getAmount0Delta() function for production-accurate calculation
+     * @private
+     */
+    private calculateAmount0FromLiquidity;
+    /**
+     * Calculate amount1 from liquidity (Uniswap v3 math)
+     * Uses @gala-chain/dex getAmount1Delta() function for production-accurate calculation
+     * @private
+     */
+    private calculateAmount1FromLiquidity;
+    /**
+     * Convert a token pair from Launchpad format to GSwap format
+     *
+     * Converts both tokens in a pair simultaneously for cleaner, more readable code
+     * when working with token swaps and pool queries.
+     *
+     * @param token0 - First token in any supported format
+     * @param token1 - Second token in any supported format
+     * @returns Object with converted tokens as gswapToken0 and gswapToken1
+     *
+     * @private
+     */
+    private convertTokenPair;
+    /**
+     * Send AddLiquidity transaction directly to bundler (bypassing gswap-sdk)
+     *
+     * Creates a liquidity position by signing a DTO and posting it directly to the
+     * GalaChain bundler. This method replaces the gswap-sdk wrapper with a direct
+     * implementation following the same pattern as CreateSale.
+     *
+     * @param params - AddLiquidity parameters including token pair, fee, tick range, and amounts
+     * @returns Transaction ID from bundler response
+     * @throws Error if not in full-access mode or if bundler request fails
+     *
+     * @private
+     */
+    private sendAddLiquidityToBundler;
+    /**
+     * Send RemoveLiquidity transaction directly to bundler
+     *
+     * Bypasses GSwap SDK and posts signed EIP-712 RemoveLiquidity DTO directly to bundler.
+     * Supports full tick ranges including negative values.
+     *
+     * @param tickLower Lower tick boundary (int256, supports negative)
+     * @param tickUpper Upper tick boundary (int256, supports negative)
+     * @param amount Liquidity amount to remove
+     * @param token0 First token class key
+     * @param token1 Second token class key
+     * @param fee Fee tier (500, 3000, or 10000)
+     * @param amount0Min Minimum amount0 to receive (slippage protection)
+     * @param amount1Min Minimum amount1 to receive (slippage protection)
+     * @param positionId Unique position identifier
+     * @returns Transaction ID from bundler response
+     *
+     * @private
+     * @throws Error if signing or bundler submission fails
+     */
+    private sendRemoveLiquidityToBundler;
+    /**
+     * Send CollectPositionFees transaction directly to bundler
+     *
+     * Bypasses GSwap SDK and posts signed EIP-712 CollectPositionFees DTO directly to bundler.
+     * Collects accumulated trading fees from a liquidity position independently of the position itself.
+     *
+     * @param token0 First token class key
+     * @param token1 Second token class key
+     * @param fee Fee tier (500, 3000, or 10000)
+     * @param amount0Requested Requested amount0 to collect (0 to collect all available)
+     * @param amount1Requested Requested amount1 to collect (0 to collect all available)
+     * @param tickLower Lower tick boundary (int256, supports negative)
+     * @param tickUpper Upper tick boundary (int256, supports negative)
+     * @param positionId Unique position identifier
+     * @returns Transaction ID from bundler response
+     *
+     * @private
+     * @throws Error if signing or bundler submission fails
+     */
+    private sendCollectPositionFeesToBundler;
+    /**
+     * Send Swap transaction directly to bundler
+     *
+     * Bypasses GSwap SDK and posts signed EIP-712 Swap DTO directly to bundler.
+     * Implements exact input swapping (sell exact amount of input token, receive output token).
+     *
+     * @param fromToken Input token (token being sold) in GSwap format
+     * @param toToken Output token (token being bought) in GSwap format
+     * @param inputAmount Amount of input token to sell
+     * @param minOutput Minimum amount of output token to receive (slippage protection)
+     * @param feeTier Fee tier (500, 3000, or 10000)
+     * @param walletAddress Wallet address executing the swap
+     * @returns Transaction ID from bundler response
+     *
+     * @private
+     * @throws Error if signing or bundler submission fails
+     */
+    private sendSwapToBundler;
+    /**
+     * Build strings instructions for AddLiquidity state locking
+     *
+     * Strings instructions are used by the bundler to lock the necessary state
+     * fields during transaction execution. This ensures atomicity of the operation.
+     *
+     * @param token0 First token class key
+     * @param token1 Second token class key
+     * @param fee Fee tier (500, 3000, or 10000 basis points)
+     * @param ownerAddress Wallet address creating the position
+     * @returns Array of strings instructions for state locking
+     *
+     * @private
+     */
+    private buildLiquidityStringsInstructions;
+    /**
+     * Handle GSwap SDK errors with consistent logging and error transformation
+     *
+     * Centralizes error handling for GSwap operations by:
+     * 1. Logging the error with context
+     * 2. Extracting error code from original error
+     * 3. Creating typed GSwap error with standardized message
+     *
+     * @param logMessage - Message to log when error occurs
+     * @param ErrorClass - Error constructor to throw (GSwapQuoteError, GSwapSwapError, etc.)
+     * @param originalError - Original error from GSwap SDK
+     * @param additionalFields - Optional additional context (e.g., { transactionHash: txHash })
+     * @throws Throws instance of provided ErrorClass with formatted message
+     *
+     * @private
+     */
+    private handleGSwapError;
+    /**
+     * Extract error code from GSwap SDK error
+     *
+     * Maps GSwapSDKError instances to standard error codes for consistent
+     * error handling across SDK operations. Preserves error code information
+     * from the original GSwap SDK error.
+     *
+     * @param error - Error thrown by GSwap SDK operations
+     * @returns Error code string if available, undefined otherwise
+     *
+     * @private
+     */
+    private extractGSwapErrorCode;
+    /**
+     * Ensure WebSocket connection is established before transaction monitoring
+     *
+     * Checks if WebSocketService is already connected, and connects if needed.
+     * This prevents unnecessary connection attempts while ensuring transactions can be monitored.
+     *
+     * @private
+     * @throws Error if connection fails
+     */
+    private ensureWebSocketConnected;
+    /**
+     * Calculate personal sign prefix for GalaChain compatibility
+     *
+     * Builds the prefix string required by GalaChain for EIP-712 signing.
+     * This matches the format used in production working payloads.
+     *
+     * @param payload The payload being signed
+     * @returns Prefix string for signing
+     *
+     * @private
+     */
+    private calculatePersonalSignPrefix;
+}
+//# sourceMappingURL=GSwapService.d.ts.map