@gala-chain/launchpad-sdk 4.0.3 → 4.0.4-beta.1

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

@@ -24,35 +24,111 @@ export declare class GSwapService extends LoggerBase {
      */
     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.
+     * 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'
+     * });
      *
-     * @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
+     * 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 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.
+     * 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'
+     * });
      *
-     * @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
+     * 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
-     * @param params Swap execution parameters
-     * @returns Swap result with transaction details
+     * 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>;
     /**
@@ -109,21 +185,152 @@ export declare class GSwapService extends LoggerBase {
      * @returns TokenClassKey object
      */
     private parseTokenFlexible;
+    /**
+     * 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>;
     /**
-     * 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
+     * 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>;
     /**
-     * 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
+     * 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;
@@ -133,15 +340,51 @@ export declare class GSwapService extends LoggerBase {
         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
+     * 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>;
     /**
@@ -164,9 +407,59 @@ export declare class GSwapService extends LoggerBase {
         owner: string;
     }): Promise<GSwapPosition>;
     /**
-     * Estimate tokens received from removing liquidity
-     * @param args Removal estimation parameters including owner address
-     * @returns Estimated token amounts
+     * 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;
@@ -178,9 +471,51 @@ export declare class GSwapService extends LoggerBase {
         owner: string;
     }): Promise<GSwapEstimateRemoveLiquidityResult>;
     /**
-     * Add liquidity using price ranges (user-friendly)
-     * @param args Liquidity addition parameters with price ranges
-     * @returns Transaction result with position ID
+     * 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;
@@ -197,71 +532,63 @@ export declare class GSwapService extends LoggerBase {
         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',
+     * 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 ID:', result.positionId);
-     * await result.wait();  // Wait for on-chain confirmation
+     *
+     * 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;
@@ -304,76 +631,70 @@ export declare class GSwapService extends LoggerBase {
      */
     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,
+     * 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: liquidityToRemove.toString(),
-     *   amount0Min: '0',
+     *   liquidity: halfLiquidity,
+     *   amount0Min: '0',  // Accept any amount (consider slippage for production)
      *   amount1Min: '0',
-     *   positionId: position.positionId,
+     *   positionId: position.positionId
      * });
      *
-     * console.log('Removal submitted:', result.transactionId);
-     * await result.wait();  // Wait for on-chain confirmation
-     * console.log('Final status:', result.status);
+     * 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;
@@ -387,83 +708,71 @@ export declare class GSwapService extends LoggerBase {
         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];
-     *
+     * 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) {
-     *   // Collect all accumulated fees
-     *   const result = await sdk.collectSwapPositionFees({
-     *     token0: 'GALA',
-     *     token1: 'GUSDC',
-     *     fee: 3000,
+     *   const result = await gswapService.collectPositionFees({
+     *     token0: position.token0,
+     *     token1: position.token1,
+     *     fee: position.feeTier,
      *     tickLower: position.tickLower,
      *     tickUpper: position.tickUpper,
-     *     amount0Requested: '0',  // Collect all token0 fees
-     *     amount1Requested: '0',  // Collect all token1 fees
-     *     positionId: position.positionId,
+     *     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();  // Wait for on-chain confirmation
-     *   console.log('Fees collected successfully');
+     *   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;