@gala-chain/launchpad-sdk 5.0.4-beta.7 → 5.1.0

package/dist/services/GSwapService.d.ts

@@ -0,0 +1,1207 @@
+import type { TokenClassKey } from '../types/common';
+import type { AvailableDexTokensResult, DexToken, ExecuteSwapParams, ExecuteSwapResult, FetchAvailableDexTokensOptions, GetLiquidityPositionsOptions, GetLiquidityPositionsResult, GSwapPosition, GSwapServiceConfig as BaseGSwapServiceConfig, PoolInfo, PoolPriceData, PoolSlot0Data, SwapQuoteParams, SwapQuoteResult, UserAsset } from '../types/gswap.dto';
+import type { GSwapAddLiquidityResult, GSwapEstimateRemoveLiquidityResult } from '../types/gswap-responses.types';
+import { LoggerBase } from './BaseService';
+import type { DexQuoteService } from './DexQuoteService';
+import type { WebSocketService } from './WebSocketService';
+type GSwapServiceConfig = Omit<BaseGSwapServiceConfig, 'gatewayBaseUrl' | 'galaChainBaseUrl'>;
+export declare class GSwapService extends LoggerBase {
+    private tradeClient;
+    private dexBackendClient;
+    private tokenConverter;
+    private webSocketService;
+    private dexQuoteService;
+    private getWalletAddress;
+    private bundlerBaseUrl;
+    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 spending a known input amount (exact input swap quote)
+     *
+     * Calculates how much of the destination token you will receive when spending a specific amount
+     * of the source token. Uses dynamic fee tier discovery to find the best available liquidity pool,
+     * trying fee tiers in order of typical liquidity: 3000 (0.30%), 500 (0.05%), then 10000 (1.00%).
+     * All quotes are always fresh (never cached) to prevent MEV vulnerabilities in volatile markets.
+     *
+     * @param params - Quote request parameters
+     * @param params.fromToken - Source token identifier (pipe-delimited format: 'GALA|Unit|none|none')
+     * @param params.toToken - Destination token identifier (pipe-delimited format)
+     * @param params.amount - Input amount to spend (must be positive number string)
+     * @returns Promise<SwapQuoteResult> Quote with estimated output amount, fee tier, price impact, and execution price
+     * @throws {GSwapQuoteError} If DexQuoteService not configured or all fee tiers fail to provide a quote
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Get quote for buying tokens with 100 GALA
+     * ```typescript
+     * const quote = await gswapService.getSwapQuoteExactInput({
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '100'
+     * });
+     *
+     * console.log(`Spending ${quote.inputAmount} GALA`);
+     * console.log(`Receiving ~${quote.estimatedOutput} BENE tokens`);
+     * console.log(`Fee tier: ${quote.feeTier / 100}%`);
+     * console.log(`Price impact: ${(parseFloat(quote.priceImpact) * 100).toFixed(4)}%`);
+     * ```
+     */
+    getSwapQuoteExactInput(params: SwapQuoteParams): Promise<SwapQuoteResult>;
+    /**
+     * Get swap quote for receiving a known output amount (exact output swap quote)
+     *
+     * Calculates how much of the source token you need to spend to receive a specific amount
+     * of the destination token. Uses dynamic fee tier discovery to find the best available liquidity pool,
+     * trying fee tiers in order of typical liquidity: 3000 (0.30%), 500 (0.05%), then 10000 (1.00%).
+     * All quotes are always fresh (never cached) to prevent MEV vulnerabilities in volatile markets.
+     *
+     * @param params - Quote request parameters
+     * @param params.fromToken - Source token identifier (pipe-delimited format: 'GALA|Unit|none|none')
+     * @param params.toToken - Destination token identifier (pipe-delimited format)
+     * @param params.amount - Desired output amount to receive (must be positive number string)
+     * @returns Promise<SwapQuoteResult> Quote with required input amount, fee tier, price impact, and execution price
+     * @throws {GSwapQuoteError} If DexQuoteService not configured or all fee tiers fail to provide a quote
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Get quote for receiving exactly 50 tokens
+     * ```typescript
+     * const quote = await gswapService.getSwapQuoteExactOutput({
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'GUSDC|Unit|none|none',
+     *   amount: '50'
+     * });
+     *
+     * console.log(`Need to spend ${quote.inputAmount} GALA`);
+     * console.log(`To receive exactly ${quote.estimatedOutput} GUSDC`);
+     * console.log(`Fee tier: ${quote.feeTier / 100}%`);
+     * console.log(`Price impact: ${(parseFloat(quote.priceImpact) * 100).toFixed(4)}%`);
+     * ```
+     */
+    getSwapQuoteExactOutput(params: SwapQuoteParams): Promise<SwapQuoteResult>;
+    /**
+     * Execute a token swap with slippage protection on GalaSwap DEX
+     *
+     * Performs a direct swap transaction between two tokens using the specified fee tier pool.
+     * Automatically calculates slippage-adjusted minimum output to protect against price movement,
+     * submits the transaction via the bundler, and monitors confirmation via WebSocket. Always get
+     * a fresh quote before executing to ensure accurate pricing and appropriate fee tier selection.
+     *
+     * @param params - Swap execution parameters
+     * @param params.fromToken - Source token to swap from (pipe-delimited format: 'GALA|Unit|none|none')
+     * @param params.toToken - Destination token to swap to (pipe-delimited format)
+     * @param params.inputAmount - Amount of source token to spend (string number)
+     * @param params.estimatedOutput - Expected output amount from quote (used for slippage calculation)
+     * @param params.feeTier - Pool fee tier in basis points (500 = 0.05%, 3000 = 0.30%, 10000 = 1.00%)
+     * @param params.slippageTolerance - Maximum acceptable slippage (default: 0.01 = 1%)
+     * @returns Promise<ExecuteSwapResult> Transaction result with status, amounts, and monitoring details
+     * @throws {Error} If private key not available, wallet address missing, or transaction fails
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Complete swap workflow with quote and execution
+     * ```typescript
+     * // Step 1: Get fresh quote
+     * const quote = await gswapService.getSwapQuoteExactInput({
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'GUSDC|Unit|none|none',
+     *   amount: '100'
+     * });
+     *
+     * // Step 2: Execute swap with 1% slippage tolerance
+     * const result = await gswapService.executeSwap({
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'GUSDC|Unit|none|none',
+     *   inputAmount: '100',
+     *   estimatedOutput: quote.estimatedOutput,
+     *   feeTier: quote.feeTier,  // Use fee tier from quote
+     *   slippageTolerance: 0.01  // 1% max slippage
+     * });
+     *
+     * console.log(`Swap ${result.status}: ${result.transactionId}`);
+     * console.log(`Spent ${result.inputAmount} → Received ${result.outputAmount}`);
+     * ```
+     */
+    executeSwap(params: ExecuteSwapParams): Promise<ExecuteSwapResult>;
+    /**
+     * Get user's token assets/balances with rich metadata
+     *
+     * Fetches all tokens held by a user from the DEX API via /user/token-list endpoint.
+     * Returns enriched data including image, name, description, verification status.
+     * Only returns tokens where balance > 0.
+     *
+     * @param walletAddress User's wallet address (e.g., "eth|0x1234...")
+     * @param page Page number (1-based, default: 1)
+     * @param limit Results per page (max 20, default: 20)
+     * @returns Array of user assets with balances and rich metadata
+     * @throws {GSwapAssetError} When the API call itself fails or wallet address is invalid
+     * @since v4.1.0 Now returns rich metadata (image, name, description, verified)
+     */
+    getUserAssets(walletAddress: string, page?: number, limit?: number): Promise<UserAsset[]>;
+    /**
+     * Get all user assets across all pages (auto-paginated with optimization)
+     *
+     * Fetches all tokens held by a user with automatic pagination.
+     * Optimization: Stops fetching when quantity=0 is encountered (results are ordered by quantity desc).
+     *
+     * @param walletAddress Wallet address to fetch assets for
+     * @returns All user assets with balances > 0
+     * @since v4.1.0 Now returns rich metadata and uses smart pagination optimization
+     */
+    getAllUserAssets(walletAddress: string): Promise<UserAsset[]>;
+    /**
+     * Fetch available DEX tokens (token discovery)
+     *
+     * Fetches all tokens available on the DEX without requiring a wallet address.
+     * Use for token discovery, listings, and market analysis.
+     *
+     * @param options Fetch options (search, limit, page)
+     * @returns Paginated result with token metadata
+     * @throws {GSwapAssetError} When the API call fails
+     * @since v4.1.0
+     */
+    fetchAvailableDexTokens(options?: FetchAvailableDexTokensOptions): Promise<AvailableDexTokensResult>;
+    /**
+     * Fetch all available DEX tokens (auto-paginated)
+     *
+     * Fetches ALL tokens available on the DEX with automatic pagination.
+     * Use for complete token listings and comprehensive market analysis.
+     *
+     * @param options Fetch options (search filter)
+     * @returns All available tokens on the DEX
+     * @throws {GSwapAssetError} When the API call fails
+     * @since v4.1.0
+     */
+    fetchAllAvailableDexTokens(options?: Omit<FetchAvailableDexTokensOptions, 'page' | 'limit'>): Promise<DexToken[]>;
+    /**
+     * 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
+     *
+     * @param rawPosition - Raw API response with varying field names (see RawPositionData docs)
+     * @param ownerAddress - Optional owner address to include in normalized result
+     */
+    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;
+    /**
+     * Transform a raw token from API response to DexToken format
+     *
+     * Centralizes the transformation logic used by both getUserAssets and fetchAvailableDexTokens.
+     * Handles type coercion (decimals string to number, verify to verified).
+     *
+     * @param token Raw token from DEX Backend API
+     * @returns Transformed DexToken with proper types
+     * @since v4.1.0
+     */
+    private transformRawTokenToDexToken;
+    /**
+     * Transform a raw token from API response to UserAsset format
+     *
+     * Extends the base DexToken transformation with tokenId parsing and balance formatting.
+     * Returns null if the token cannot be processed (parsing errors).
+     *
+     * @param token Raw token from DEX Backend API
+     * @returns Transformed UserAsset or null if processing fails
+     * @since v4.1.0
+     */
+    private transformRawTokenToUserAsset;
+    /**
+     * Fetch user's liquidity positions with pagination and optional price enrichment
+     *
+     * Retrieves concentrated liquidity positions for a specific wallet address using bookmark-based
+     * cursor pagination. Supports optional real-time price enrichment to include current token prices
+     * and position value calculations. Use this method when you need manual pagination control or
+     * want to fetch positions incrementally.
+     *
+     * @param ownerAddress - Wallet address to query positions for (format: 'eth|0x...' or 'client|...')
+     * @param limit - Maximum positions per page (default: GSWAP_LIQUIDITY_POSITIONS_PAGE_SIZE)
+     * @param bookmark - Optional pagination cursor from previous result's nextBookmark field
+     * @param options - Optional configuration for price enrichment and additional data
+     * @param options.withPrices - If true, enriches positions with current token prices and USD values
+     * @returns Promise<GetLiquidityPositionsResult> Paginated positions with optional nextBookmark and prices
+     * @throws {GSwapPositionError} If API request fails or position normalization errors occur
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Manual pagination without price enrichment
+     * ```typescript
+     * // Fetch first page
+     * const page1 = await gswapService.getUserLiquidityPositions(
+     *   'eth|0x1234...',
+     *   10
+     * );
+     *
+     * console.log(`Found ${page1.items.length} positions`);
+     *
+     * // Fetch next page if available
+     * if (page1.nextBookmark) {
+     *   const page2 = await gswapService.getUserLiquidityPositions(
+     *     'eth|0x1234...',
+     *     10,
+     *     page1.nextBookmark
+     *   );
+     * }
+     * ```
+     *
+     * @example Fetch positions with real-time price enrichment
+     * ```typescript
+     * const positions = await gswapService.getUserLiquidityPositions(
+     *   'eth|0x1234...',
+     *   20,
+     *   undefined,
+     *   { withPrices: true }
+     * );
+     *
+     * // Prices map available at result.prices
+     * positions.items.forEach(pos => {
+     *   const poolKey = `${pos.token0}/${pos.token1}`;
+     *   const prices = positions.prices?.get(poolKey);
+     *   if (prices) {
+     *     console.log(`${poolKey}: Token0=$${prices.token0PriceUsd}, Token1=$${prices.token1PriceUsd}`);
+     *   }
+     * });
+     * ```
+     */
+    getUserLiquidityPositions(ownerAddress: string, limit?: number, bookmark?: string, options?: GetLiquidityPositionsOptions): Promise<GetLiquidityPositionsResult>;
+    /**
+     * Fetch ALL user liquidity positions with automatic pagination and optional price enrichment
+     *
+     * Convenience method that automatically handles bookmark-based pagination to retrieve all
+     * concentrated liquidity positions for a wallet in a single call. Uses maximum page size
+     * internally for efficiency and combines results from all pages. Optionally enriches positions
+     * with real-time token prices and USD value calculations.
+     *
+     * @param ownerAddress - Wallet address to query positions for (format: 'eth|0x...' or 'client|...')
+     * @param options - Optional configuration for price enrichment and additional data
+     * @param options.withPrices - If true, enriches all positions with current token prices and USD values
+     * @returns Promise<GSwapPosition[] | GetLiquidityPositionsResult> All positions (array if no prices, result with prices if requested)
+     * @throws {GSwapPositionError} If API request fails or position normalization errors occur
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Fetch all positions without prices (simple array)
+     * ```typescript
+     * const allPositions = await gswapService.getAllSwapUserLiquidityPositions(
+     *   'eth|0x1234...'
+     * );
+     *
+     * console.log(`Total positions: ${allPositions.length}`);
+     * allPositions.forEach(pos => {
+     *   console.log(`Position ${pos.positionId}: ${pos.token0}/${pos.token1}`);
+     *   console.log(`  Liquidity: ${pos.liquidity}, Range: ${pos.tickLower}-${pos.tickUpper}`);
+     * });
+     * ```
+     *
+     * @example Fetch all positions with price enrichment (full result object)
+     * ```typescript
+     * const result = await gswapService.getAllSwapUserLiquidityPositions(
+     *   'eth|0x1234...',
+     *   { withPrices: true }
+     * );
+     *
+     * // When withPrices=true, returns GetLiquidityPositionsResult with prices Map
+     * if ('prices' in result) {
+     *   result.items.forEach(pos => {
+     *     const poolKey = `${pos.token0}/${pos.token1}`;
+     *     const prices = result.prices?.get(poolKey);
+     *     if (prices) {
+     *       console.log(`${poolKey}: $${prices.token0PriceUsd} / $${prices.token1PriceUsd}`);
+     *     }
+     *   });
+     * }
+     * ```
+     */
+    getAllSwapUserLiquidityPositions(ownerAddress: string, options?: GetLiquidityPositionsOptions): Promise<GSwapPosition[] | GetLiquidityPositionsResult>;
+    /**
+     * Fetch a specific liquidity position by its compound key (token pair, fee tier, and tick range)
+     *
+     * Retrieves detailed information about a single concentrated liquidity position using its
+     * compound key consisting of the token pair, fee tier, and tick boundaries. This method
+     * validates tick spacing for the given fee tier before making the API call to ensure the
+     * position parameters are valid for the specified pool.
+     *
+     * @param ownerAddress - Wallet address that owns the position (format: 'eth|0x...' or 'client|...')
+     * @param position - Compound key identifying the specific position
+     * @param position.token0 - First token identifier (pipe-delimited format: 'GALA|Unit|none|none')
+     * @param position.token1 - Second token identifier (pipe-delimited format)
+     * @param position.fee - Pool fee tier in basis points (500, 3000, or 10000)
+     * @param position.tickLower - Lower tick boundary of the position's price range
+     * @param position.tickUpper - Upper tick boundary of the position's price range
+     * @returns Promise<GSwapPosition> Complete position details with liquidity, amounts, and fees
+     * @throws {GSwapPositionError} If position not found, tick spacing invalid, or API request fails
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Fetch position by compound key
+     * ```typescript
+     * const position = await gswapService.getLiquidityPosition(
+     *   'eth|0x1234...',
+     *   {
+     *     token0: 'GALA|Unit|none|none',
+     *     token1: 'GUSDC|Unit|none|none',
+     *     fee: 3000,        // 0.30% fee tier
+     *     tickLower: -276330,
+     *     tickUpper: -276270
+     *   }
+     * );
+     *
+     * console.log(`Position ID: ${position.positionId}`);
+     * console.log(`Liquidity: ${position.liquidity}`);
+     * console.log(`Token0 amount: ${position.amount0}`);
+     * console.log(`Token1 amount: ${position.amount1}`);
+     * console.log(`Uncollected fees: ${position.feeAmount0} / ${position.feeAmount1}`);
+     * ```
+     */
+    getLiquidityPosition(ownerAddress: string, position: {
+        token0: string;
+        token1: string;
+        fee: number;
+        tickLower: number;
+        tickUpper: number;
+    }): Promise<GSwapPosition>;
+    /**
+     * Fetch a liquidity position by its unique position ID with automatic retry logic
+     *
+     * Retrieves detailed information about a concentrated liquidity position using its unique position ID.
+     * Includes automatic retry logic (5 attempts with 2-second delays) for newly created positions that
+     * may not be immediately indexed. Optionally accepts compound key parameters (token pair, fee tier,
+     * tick range) for faster compound key lookup instead of iterating through all positions.
+     *
+     * @param ownerAddress - Wallet address that owns the position (format: 'eth|0x...' or 'client|...')
+     * @param positionId - Unique position UUID returned when position was created
+     * @param token0 - Optional first token for compound key lookup (faster than ID scan)
+     * @param token1 - Optional second token for compound key lookup (faster than ID scan)
+     * @param feeTier - Optional fee tier in basis points 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 Promise<GSwapPosition> Complete position details with liquidity, amounts, fees, and metadata
+     * @throws {GSwapPositionError} If position not found after retries or API request fails
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Fetch position by ID only (with automatic retry)
+     * ```typescript
+     * const position = await gswapService.getLiquidityPositionById(
+     *   'eth|0x1234...',
+     *   'abc123-position-uuid'
+     * );
+     *
+     * console.log(`Found position: ${position.token0}/${position.token1}`);
+     * console.log(`Liquidity: ${position.liquidity}`);
+     * ```
+     *
+     * @example Fetch position by ID with compound key for faster lookup
+     * ```typescript
+     * // Providing compound key parameters enables direct lookup (much faster)
+     * const position = await gswapService.getLiquidityPositionById(
+     *   'eth|0x1234...',
+     *   'abc123-position-uuid',
+     *   'GALA|Unit|none|none',
+     *   'GUSDC|Unit|none|none',
+     *   3000,        // 0.30% fee tier
+     *   -276330,     // tickLower
+     *   -276270      // tickUpper
+     * );
+     *
+     * console.log(`Position ${position.positionId} found via compound key`);
+     * ```
+     */
+    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
+     * 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 backend request
+     * - 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 token amounts that will be received when removing liquidity from a position
+     *
+     * Calculates the expected token0 and token1 amounts that will be returned when removing a
+     * specific amount of liquidity from a concentrated liquidity position. This is useful for
+     * previewing the outcome before executing the actual removal transaction. Validates tick
+     * spacing for the given fee tier before making the API call to ensure valid parameters.
+     *
+     * @param args - Liquidity removal estimation parameters
+     * @param args.token0 - First token identifier (pipe-delimited format: 'GALA|Unit|none|none')
+     * @param args.token1 - Second token identifier (pipe-delimited format)
+     * @param args.fee - Pool fee tier in basis points (500, 3000, or 10000)
+     * @param args.liquidity - Amount of liquidity to remove (string number from position.liquidity)
+     * @param args.tickLower - Lower tick boundary of the position
+     * @param args.tickUpper - Upper tick boundary of the position
+     * @param args.owner - Wallet address that owns the position (format: 'eth|0x...' or 'client|...')
+     * @returns Promise<GSwapEstimateRemoveLiquidityResult> Estimated token0 and token1 amounts to be received
+     * @throws {GSwapPositionError} If tick spacing invalid, parameters incorrect, or API request fails
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Estimate removal before executing
+     * ```typescript
+     * // First, get the position details
+     * const position = await gswapService.getLiquidityPositionById(
+     *   'eth|0x1234...',
+     *   'position-uuid'
+     * );
+     *
+     * // Estimate what you'll receive from removing all liquidity
+     * const estimate = await gswapService.estimateRemoveLiquidity({
+     *   token0: position.token0,
+     *   token1: position.token1,
+     *   fee: position.feeTier,
+     *   liquidity: position.liquidity,  // Remove all liquidity
+     *   tickLower: position.tickLower,
+     *   tickUpper: position.tickUpper,
+     *   owner: 'eth|0x1234...'
+     * });
+     *
+     * console.log(`Removing liquidity will return:`);
+     * console.log(`  Token0: ${estimate.amount0}`);
+     * console.log(`  Token1: ${estimate.amount1}`);
+     *
+     * // Then execute actual removal if amounts look good
+     * const result = await gswapService.removeLiquidity({
+     *   token0: position.token0,
+     *   token1: position.token1,
+     *   fee: position.feeTier,
+     *   liquidity: position.liquidity,
+     *   tickLower: position.tickLower,
+     *   tickUpper: position.tickUpper
+     * });
+     * ```
+     */
+    estimateRemoveLiquidity(args: {
+        token0: string;
+        token1: string;
+        fee: number;
+        liquidity: string;
+        tickLower: number;
+        tickUpper: number;
+        owner: string;
+    }): Promise<GSwapEstimateRemoveLiquidityResult>;
+    /**
+     * Add concentrated liquidity to a DEX pool using user-friendly price ranges
+     *
+     * Creates a new liquidity position in a GalaSwap concentrated liquidity pool by specifying minimum
+     * and maximum prices instead of raw tick values. Automatically converts price ranges to tick boundaries
+     * using the pool's tick spacing, submits the transaction via bundler, and monitors confirmation via
+     * WebSocket. Returns a result object with transaction details and an optional wait() method for
+     * tracking on-chain confirmation.
+     *
+     * @param args - Liquidity addition parameters with price range
+     * @param args.token0 - First token identifier (pipe-delimited format: 'GALA|Unit|none|none')
+     * @param args.token1 - Second token identifier (pipe-delimited format)
+     * @param args.fee - Pool fee tier in basis points (500 = 0.05%, 3000 = 0.30%, 10000 = 1.00%)
+     * @param args.minPrice - Minimum price for the liquidity range (string number, token1 per token0)
+     * @param args.maxPrice - Maximum price for the liquidity range (string number, token1 per token0)
+     * @param args.amount0Desired - Desired amount of token0 to deposit (string number)
+     * @param args.amount1Desired - Desired amount of token1 to deposit (string number)
+     * @param args.amount0Min - Optional minimum amount0 to accept (default: '0')
+     * @param args.amount1Min - Optional minimum amount1 to accept (default: '0')
+     * @returns Promise<GSwapAddLiquidityResult> Transaction result with positionId, liquidity amounts, status, and wait() helper
+     * @throws {Error} If private key not available, wallet address missing, or transaction fails
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Add liquidity with price range (user-friendly approach)
+     * ```typescript
+     * // Add liquidity to GALA/GUSDC pool with price range $0.025 to $0.035
+     * const result = await gswapService.addLiquidityByPrice({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'GUSDC|Unit|none|none',
+     *   fee: 3000,           // 0.30% fee tier
+     *   minPrice: '0.025',   // Minimum price: $0.025 per GALA
+     *   maxPrice: '0.035',   // Maximum price: $0.035 per GALA
+     *   amount0Desired: '1000',  // Deposit up to 1000 GALA
+     *   amount1Desired: '30',    // Deposit up to 30 GUSDC
+     *   amount0Min: '900',       // Accept minimum 900 GALA
+     *   amount1Min: '25'         // Accept minimum 25 GUSDC
+     * });
+     *
+     * console.log(`Position created: ${result.positionId}`);
+     * console.log(`Transaction: ${result.transactionId}`);
+     *
+     * // Wait for on-chain confirmation
+     * await result.wait?.();
+     * console.log(`Position confirmed with liquidity: ${result.liquidity}`);
+     * ```
+     */
+    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 concentrated liquidity to a DEX pool using precise tick boundaries (advanced)
+     *
+     * Creates a new liquidity position in a GalaSwap concentrated liquidity pool using raw tick
+     * boundaries instead of price ranges. This advanced method gives precise control over position
+     * range but requires understanding of Uniswap V3 tick mechanics and tick spacing constraints.
+     * Automatically connects WebSocket before transaction submission to prevent missed confirmations,
+     * then monitors position discovery with retry logic to handle indexing delays.
+     *
+     * @param args - Liquidity addition parameters with tick boundaries
+     * @param args.token0 - First token (pipe-delimited string or TokenClassKey object)
+     * @param args.token1 - Second token (pipe-delimited string or TokenClassKey object)
+     * @param args.fee - Pool fee tier in basis points (500 = 0.05%, 3000 = 0.30%, 10000 = 1.00%)
+     * @param args.tickLower - Lower tick boundary (must be multiple of tickSpacing, supports negative values)
+     * @param args.tickUpper - Upper tick boundary (must be multiple of tickSpacing)
+     * @param args.amount0Desired - Desired amount of token0 to deposit (string number)
+     * @param args.amount1Desired - Desired amount of token1 to deposit (string number)
+     * @param args.amount0Min - Optional minimum amount0 to accept (default: '0')
+     * @param args.amount1Min - Optional minimum amount1 to accept (default: '0')
+     * @returns Promise<GSwapAddLiquidityResult> Transaction result with positionId, liquidity amounts, status, and wait() helper
+     * @throws {Error} If private key not available, wallet address missing, tick spacing invalid, or transaction fails
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Add liquidity with precise tick range (advanced users)
+     * ```typescript
+     * // Add liquidity to GALA/GUSDC pool with exact tick boundaries
+     * // Tick spacing for fee=3000 (0.30%) is 60, so ticks must be multiples of 60
+     * const result = await gswapService.addSwapLiquidityByTicks({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'GUSDC|Unit|none|none',
+     *   fee: 3000,           // 0.30% fee tier → tickSpacing=60
+     *   tickLower: -276360,  // Must be multiple of 60
+     *   tickUpper: -276240,  // Must be multiple of 60
+     *   amount0Desired: '1000',
+     *   amount1Desired: '30',
+     *   amount0Min: '900',
+     *   amount1Min: '25'
+     * });
+     *
+     * console.log(`Position ${result.positionId} created`);
+     * console.log(`Liquidity: ${result.liquidity}`);
+     *
+     * // Wait for on-chain confirmation
+     * await result.wait?.();
+     * console.log(`Position confirmed: ${result.status}`);
+     * ```
+     *
+     * @example Tick spacing constraints by fee tier
+     * ```typescript
+     * // Fee tier determines required tick spacing:
+     * // - Fee 500 (0.05%):  tickSpacing = 10
+     * // - Fee 3000 (0.30%): tickSpacing = 60
+     * // - Fee 10000 (1.00%): tickSpacing = 200
+     *
+     * // Valid ticks for fee=3000: -276360, -276300, -276240, etc.
+     * // Invalid: -276350 (not multiple of 60)
+     * ```
+     */
+    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 (partial or complete)
+     *
+     * Withdraws liquidity from a GalaSwap concentrated liquidity position, returning the underlying
+     * token0 and token1 amounts to your wallet. Supports both partial removal (reduce position size)
+     * and complete removal (close position). Validates liquidity amount to prevent zero-value removals
+     * that would waste gas fees. Automatically connects WebSocket before transaction submission to
+     * monitor confirmation, with graceful timeout handling if monitoring fails.
+     *
+     * @param args - Liquidity removal parameters
+     * @param args.token0 - First token (pipe-delimited string or TokenClassKey object)
+     * @param args.token1 - Second token (pipe-delimited string or TokenClassKey object)
+     * @param args.fee - Pool fee tier in basis points (500 = 0.05%, 3000 = 0.30%, 10000 = 1.00%)
+     * @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 (must be > 0, use position.liquidity for full removal)
+     * @param args.amount0Min - Optional minimum token0 to accept for slippage protection (default: '0')
+     * @param args.amount1Min - Optional minimum token1 to accept for slippage protection (default: '0')
+     * @param args.positionId - Optional position ID for tracking and error messaging
+     * @returns Promise<GSwapAddLiquidityResult> Transaction result with transactionId, status, timestamp, and wait() helper
+     * @throws {Error} If private key not available, liquidity is zero, or transaction fails
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Remove 50% of liquidity from a position (partial removal)
+     * ```typescript
+     * // Step 1: Get position details
+     * const positions = await gswapService.getUserLiquidityPositions('eth|0x1234...');
+     * const position = positions.items[0];
+     *
+     * // Step 2: Calculate 50% of liquidity to remove
+     * const halfLiquidity = (parseFloat(position.liquidity) * 0.5).toString();
+     *
+     * // Step 3: Remove partial liquidity
+     * const result = await gswapService.removeLiquidity({
+     *   token0: position.token0,
+     *   token1: position.token1,
+     *   fee: position.feeTier,
+     *   tickLower: position.tickLower,
+     *   tickUpper: position.tickUpper,
+     *   liquidity: halfLiquidity,
+     *   amount0Min: '0',  // Accept any amount (consider slippage for production)
+     *   amount1Min: '0',
+     *   positionId: position.positionId
+     * });
+     *
+     * console.log(`Removed half liquidity: ${result.transactionId}`);
+     * await result.wait?.();
+     * ```
+     *
+     * @example Remove all liquidity to close position (complete removal)
+     * ```typescript
+     * // Close position completely by removing all liquidity
+     * const result = await gswapService.removeLiquidity({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'GUSDC|Unit|none|none',
+     *   fee: 3000,
+     *   tickLower: -276360,
+     *   tickUpper: -276240,
+     *   liquidity: position.liquidity,  // Remove ALL liquidity
+     *   positionId: position.positionId
+     * });
+     *
+     * console.log(`Position closed: ${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 (partial or complete)
+     *
+     * Claims trading fees that have accumulated in your liquidity position without affecting the
+     * position's liquidity. Fees only accumulate when your position is in-range (current price within
+     * your tick boundaries) and trades execute in that range. Supports collecting all fees at once
+     * (default with '0' amounts) or specific amounts for capital management strategies. Automatically
+     * connects WebSocket before transaction submission to monitor confirmation.
+     *
+     * @param args - Fee collection parameters (supports two patterns: direct parameters or position lookup)
+     * @param args.token0 - First token (pipe-delimited string or TokenClassKey, required unless using ownerAddress pattern)
+     * @param args.token1 - Second token (pipe-delimited string or TokenClassKey, required unless using ownerAddress pattern)
+     * @param args.fee - Pool fee tier in basis points (500, 3000, or 10000, required unless using ownerAddress pattern)
+     * @param args.tickLower - Lower tick boundary of the position (required unless using ownerAddress pattern)
+     * @param args.tickUpper - Upper tick boundary of the position (required unless using ownerAddress pattern)
+     * @param args.amount0Requested - Optional token0 fee amount to collect (default: '0' = collect all)
+     * @param args.amount1Requested - Optional token1 fee amount to collect (default: '0' = collect all)
+     * @param args.positionId - Optional position ID for tracking and verification
+     * @param args.ownerAddress - Alternative pattern: fetch position details first using this address and positionId
+     * @param args.amount0Max - Alternative naming for amount0Requested (MCP tool compatibility)
+     * @param args.amount1Max - Alternative naming for amount1Requested (MCP tool compatibility)
+     * @returns Promise<GSwapAddLiquidityResult> Transaction result with transactionId, status, timestamp, and wait() helper
+     * @throws {Error} If private key not available, position not found, or transaction fails
+     * @since 4.0.4-beta.0
+     * @category Services
+     *
+     * @example Collect all accumulated fees from a position
+     * ```typescript
+     * // Step 1: Get position details to check accumulated fees
+     * const positions = await gswapService.getUserLiquidityPositions('eth|0x1234...');
+     * const position = positions.items[0];
+     *
+     * console.log(`Token0 fees: ${position.feeAmount0}`);
+     * console.log(`Token1 fees: ${position.feeAmount1}`);
+     *
+     * // Step 2: Collect all fees if there are any
+     * if (parseFloat(position.feeAmount0) > 0 || parseFloat(position.feeAmount1) > 0) {
+     *   const result = await gswapService.collectPositionFees({
+     *     token0: position.token0,
+     *     token1: position.token1,
+     *     fee: position.feeTier,
+     *     tickLower: position.tickLower,
+     *     tickUpper: position.tickUpper,
+     *     amount0Requested: '0',  // '0' means collect ALL token0 fees
+     *     amount1Requested: '0',  // '0' means collect ALL token1 fees
+     *     positionId: position.positionId
+     *   });
+     *
+     *   console.log(`Fee collection submitted: ${result.transactionId}`);
+     *   await result.wait?.();
+     *   console.log('All fees collected successfully');
+     * }
+     * ```
+     *
+     * @example Collect fees using position lookup pattern (MCP tool compatible)
+     * ```typescript
+     * // Alternative pattern that fetches position details automatically
+     * const result = await gswapService.collectPositionFees({
+     *   ownerAddress: 'eth|0x1234...',
+     *   positionId: 'position-uuid',
+     *   amount0Max: '0',  // Collect all token0 fees (MCP naming)
+     *   amount1Max: '0'   // Collect all token1 fees (MCP naming)
+     * });
+     *
+     * console.log(`Fees collected: ${result.status}`);
+     * ```
+     */
+    collectPositionFees(args: {
+        token0?: string | TokenClassKey;
+        token1?: string | TokenClassKey;
+        fee?: number;
+        tickLower?: number;
+        tickUpper?: number;
+        amount0Requested?: string;
+        amount1Requested?: string;
+        positionId?: string;
+        ownerAddress?: string;
+        amount0Max?: string;
+        amount1Max?: 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): {
+        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;
+    /**
+     * Validate that tick values are valid multiples of the tick spacing for the given fee tier
+     * @param tickLower - Lower tick boundary
+     * @param tickUpper - Upper tick boundary
+     * @param feeTier - Fee tier (500, 3000, or 10000)
+     * @throws Error if ticks are not valid multiples of tick spacing
+     * @private
+     */
+    private validateTickSpacing;
+    /**
+     * 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;
+    /**
+     * Create error handler for withErrorHandling wrapper
+     * Provides a reusable error handler that logs and throws GSwap-specific errors
+     *
+     * @param ErrorClass - Error constructor (GSwapQuoteError, GSwapAssetError, etc.)
+     * @param additionalFields - Optional context for error message
+     * @returns Function that logs and throws appropriate error
+     *
+     * @private
+     */
+    private createGSwapErrorHandler;
+    /**
+     * 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;
+}
+export {};
+//# sourceMappingURL=GSwapService.d.ts.map