@gala-chain/launchpad-sdk 3.31.0 → 4.0.0

package/dist/services/GSwapService.d.ts

@@ -1,31 +1,51 @@
-/**
- * GSwapService - Wraps @gala-chain/gswap-sdk for DEX trading integration
- *
- * Provides high-level interface to GalaSwap SDK for:
- * - Token swapping with slippage protection
- * - Quote generation (exact input/output)
- * - User asset queries
- * - Pool information
- * - Real-time transaction monitoring
- */
+import { LoggerBase } from './BaseService';
 import { WebSocketService } from './WebSocketService';
-import type { SwapQuoteParams, SwapQuoteResult, ExecuteSwapParams, ExecuteSwapResult, UserAsset, PoolInfo, GSwapServiceConfig, GSwapPosition } from '../types/gswap.dto';
-export declare class GSwapService {
-    private gswap;
+import { DexQuoteService } from './DexQuoteService';
+import type { SwapQuoteParams, SwapQuoteResult, ExecuteSwapParams, ExecuteSwapResult, UserAsset, PoolInfo, GSwapServiceConfig, GSwapPosition, PoolSlot0Data, PoolPriceData, GetLiquidityPositionsOptions, GetLiquidityPositionsResult } from '../types/gswap.dto';
+import type { TokenClassKey } from '../types/common';
+export declare class GSwapService extends LoggerBase {
+    private gatewayClient;
+    private dexBackendClient;
     private tokenConverter;
     private webSocketService;
-    private logger;
-    constructor(config: GSwapServiceConfig, webSocketService: WebSocketService);
+    private dexQuoteService;
+    private getWalletAddress;
+    private galaChainBaseUrl;
+    private bundlerBaseUrl;
+    private gatewayBaseUrl;
+    private privateKey;
+    private pricingConcurrency;
+    constructor(config: GSwapServiceConfig, webSocketService: WebSocketService, dexQuoteService?: DexQuoteService);
+    /**
+     * Set the pricing concurrency level for liquidity position pricing operations
+     * This is set once at SDK initialization and applies to all pricing operations
+     * @param concurrency Number of concurrent pricing requests (default: 5, max recommended: 20)
+     */
+    setPricingConcurrency(concurrency: number): void;
     /**
      * Get swap quote for exact input (spending known amount)
+     *
+     * Uses DexQuoteService with dynamic fee tier discovery ([3000, 500, 10000]).
+     * NEVER falls back - if all fee tiers fail, throws loudly to expose the real problem.
+     *
+     * Guarantees: All quotes are ALWAYS fresh (never cached) to prevent MEV in volatile markets.
+     *
      * @param params Quote request with fromToken, toToken, and input amount
-     * @returns Quote with estimated output and fees
+     * @returns Quote with estimated output, actual price impact, and fees
+     * @throws GSwapQuoteError if DexQuoteService not configured or all fee tiers fail
      */
     getSwapQuoteExactInput(params: SwapQuoteParams): Promise<SwapQuoteResult>;
     /**
      * Get swap quote for exact output (receive known amount)
+     *
+     * Uses DexQuoteService with dynamic fee tier discovery ([3000, 500, 10000]).
+     * NEVER falls back - if all fee tiers fail, throws loudly to expose the real problem.
+     *
+     * Guarantees: All quotes are ALWAYS fresh (never cached) to prevent MEV in volatile markets.
+     *
      * @param params Quote request with fromToken, toToken, and desired output
-     * @returns Quote with required input and fees
+     * @returns Quote with required input, actual price impact, and fees
+     * @throws GSwapQuoteError if DexQuoteService not configured or all fee tiers fail
      */
     getSwapQuoteExactOutput(params: SwapQuoteParams): Promise<SwapQuoteResult>;
     /**
@@ -37,17 +57,21 @@ export declare class GSwapService {
     /**
      * Get user's token assets/balances
      *
-     * Fetches all tokens held by a user from the GSwap API with strict validation.
+     * Fetches all tokens held by a user from the GSwap API with graceful handling
+     * of token conversion. Assets that cannot be converted are skipped with debug logging.
      *
      * @param walletAddress User's wallet address (e.g., "eth|0x1234...")
-     * @returns Array of user assets with balances
-     * @throws {GSwapAssetError} When encountering assets with invalid or missing token identifiers
-     *         This indicates a data quality issue from the upstream GSwap API.
-     *         Migration: Wrap in try/catch and handle gracefully.
-     *         See CHANGELOG v3.29.0 BREAKING CHANGES for migration guide.
-     * @since v3.29.0 Now throws on invalid tokens instead of silently filtering
+     * @returns Array of user assets with balances (skips unconvertible assets)
+     * @throws {GSwapAssetError} When the API call itself fails or wallet address is invalid
+     * @since v3.30.0 Now gracefully skips unconvertible assets instead of throwing
+     */
+    getUserAssets(walletAddress: string, page?: number, limit?: number): Promise<UserAsset[]>;
+    /**
+     * Get all user assets across all pages (auto-paginated)
+     * @param walletAddress Wallet address to fetch assets for
+     * @returns All user assets across all pages
      */
-    getUserAssets(walletAddress: string): Promise<UserAsset[]>;
+    getAllUserAssets(walletAddress: string): Promise<UserAsset[]>;
     /**
      * Get pool information for token pair
      * @param tokenA First token
@@ -62,7 +86,38 @@ export declare class GSwapService {
      * @param bookmark Pagination bookmark
      * @returns Array of liquidity positions with full type safety
      */
-    getUserLiquidityPositions(ownerAddress: string, limit?: number, bookmark?: string): Promise<GSwapPosition[]>;
+    /**
+     * Chunk array into smaller batches for concurrent processing
+     * @private
+     */
+    private chunkArray;
+    /**
+     * Fetch real-time pricing for liquidity positions
+     * Deduplicates pools and processes in chunks for optimal performance
+     * @private
+     */
+    private fetchPositionPrices;
+    /**
+     * Normalize GSwap API position response to match LiquidityPosition interface
+     * Handles different field naming conventions from the API
+     */
+    private normalizePositionResponse;
+    /**
+     * Parse token string flexibly - supports both delimited and simple formats
+     * @param tokenString Token in format "GALA" or "GALA|Unit|none|none"
+     * @returns TokenClassKey object
+     */
+    private parseTokenFlexible;
+    getUserLiquidityPositions(ownerAddress: string, limit?: number, bookmark?: string, options?: GetLiquidityPositionsOptions): Promise<GetLiquidityPositionsResult>;
+    /**
+     * Get ALL user liquidity positions with automatic pagination
+     * Automatically fetches all pages of liquidity positions for a wallet
+     * Uses bookmark-based cursor pagination internally
+     * @param ownerAddress User's wallet address
+     * @param options Optional configuration for pricing enrichment
+     * @returns All liquidity positions combined from all pages, optionally with pricing data
+     */
+    getAllSwapUserLiquidityPositions(ownerAddress: string, options?: GetLiquidityPositionsOptions): Promise<GSwapPosition[] | GetLiquidityPositionsResult>;
     /**
      * Get a specific liquidity position
      * @param ownerAddress User's wallet address
@@ -83,6 +138,25 @@ export declare class GSwapService {
      * @returns Detailed position information with full type safety
      */
     getLiquidityPositionById(ownerAddress: string, positionId: string): Promise<GSwapPosition>;
+    /**
+     * Fetch a single liquidity position using ONLY the compound key (direct HTTP call)
+     * Most efficient when you already have all position parameters
+     * @param params Position parameters - token0, token1, fee, tickLower, tickUpper, owner (ALL REQUIRED)
+     * @returns Detailed position information with full type safety
+     * @remarks
+     * - Does NOT use positionId (not needed or accepted)
+     * - Single direct HTTP call to GalaChain (no GSwap SDK)
+     * - Best for cases where caller has full position parameters
+     * - Requires: token0, token1, fee (500|3000|10000), tickLower, tickUpper, owner
+     */
+    fetchSwapPositionDirect(params: {
+        token0: string;
+        token1: string;
+        fee: number;
+        tickLower: number;
+        tickUpper: number;
+        owner: string;
+    }): Promise<GSwapPosition>;
     /**
      * Estimate tokens received from removing liquidity
      * @param args Removal estimation parameters
@@ -113,13 +187,75 @@ export declare class GSwapService {
         amount1Min?: string;
     }): Promise<any>;
     /**
-     * Add liquidity using tick ranges (advanced)
-     * @param args Liquidity addition parameters with tick ranges
-     * @returns Transaction result with position ID
+     * Add liquidity to GSwap pool using precise tick ranges (concentrated liquidity)
+     *
+     * **CRITICAL: WebSocket-First Pattern**
+     * This method ensures WebSocket connection is established BEFORE submitting the
+     * transaction to prevent race conditions where the transaction confirms before
+     * the listener becomes active. This is essential because:
+     *
+     * 1. WebSocket listener created IMMEDIATELY after transactionId received
+     * 2. Socket.IO buffers events for registered listeners
+     * 3. If listener not active when transaction confirms, confirmation is missed
+     * 4. Position discovery retry logic handles indexing delays (up to 11 seconds)
+     *
+     * **Position Discovery Flow**
+     * After bundler submits transaction:
+     * 1. WebSocket listener monitors for on-chain confirmation (~2-3 seconds)
+     * 2. Once confirmed, waits for backend position indexing (5-11 seconds)
+     * 3. Queries positions API up to 3 times with exponential backoff
+     * 4. Matches position by token pair + fee tier (handles multiple positions)
+     * 5. Fetches full position details for complete data
+     *
+     * **Token Format Support**
+     * - String tokens: 'GALA', 'GUSDC' → auto-converted to TokenClassKey
+     * - TokenClassKey: { collection, category, type, additionalKey }
+     * - Both formats normalized to TokenClassKey for bundler submission
+     *
+     * **Tick Range Details**
+     * - Supports negative ticks for full concentrated liquidity ranges
+     * - Example: tickLower: -1080, tickUpper: 900
+     * - Must be multiples of tickSpacing (determined by fee tier)
+     * - Fee 500bps: tickSpacing=10, Fee 3000bps: tickSpacing=60, Fee 10000bps: tickSpacing=200
+     *
+     * @param args Liquidity addition parameters
+     * @param args.token0 First token (string or TokenClassKey)
+     * @param args.token1 Second token (string or TokenClassKey)
+     * @param args.fee Fee tier in basis points (500, 3000, or 10000)
+     * @param args.tickLower Lower tick boundary (supports negative values)
+     * @param args.tickUpper Upper tick boundary
+     * @param args.amount0Desired Desired amount of token0
+     * @param args.amount1Desired Desired amount of token1
+     * @param args.amount0Min Optional minimum token0 (default: '0')
+     * @param args.amount1Min Optional minimum token1 (default: '0')
+     *
+     * @returns Promise<GSwapAddLiquidityResult> Transaction result with:
+     *   - transactionId: Bundler transaction ID
+     *   - positionId: GSwap position ID (discovered from on-chain data)
+     *   - status: Transaction status from WebSocket
+     *   - liquidity: Position liquidity amount
+     *   - amount0/amount1: Actual amounts added
+     *   - wait(): Async method to wait for confirmation
+     *
+     * @throws GSwapPositionError if private key unavailable or bundler submission fails
+     *
+     * @example
+     * // Add liquidity with explicit tick range
+     * const result = await sdk.addSwapLiquidityByTicks({
+     *   token0: 'GALA',
+     *   token1: 'GUSDC',
+     *   fee: 3000,
+     *   tickLower: -1080,  // Supports negative ticks
+     *   tickUpper: 900,
+     *   amount0Desired: '100',
+     *   amount1Desired: '100',
+     * });
+     * console.log('Position ID:', result.positionId);
+     * await result.wait();  // Wait for on-chain confirmation
      */
-    addLiquidityByTicks(args: {
-        token0: string;
-        token1: string;
+    addSwapLiquidityByTicks(args: {
+        token0: string | TokenClassKey;
+        token1: string | TokenClassKey;
         fee: number;
         tickLower: number;
         tickUpper: number;
@@ -129,31 +265,202 @@ export declare class GSwapService {
         amount1Min?: string;
     }): Promise<any>;
     /**
-     * Remove liquidity from a position
+     * Monitor a bundler transaction with graceful fallback on timeout
+     *
+     * **Pattern Overview**
+     * This helper consolidates the common error handling pattern used by all bundler-direct
+     * operations (removeSwapLiquidity, collectSwapPositionFees, etc.):
+     *
+     * 1. Set up WebSocket listener BEFORE bundler submission (already done by caller)
+     * 2. Try to await transaction confirmation via WebSocket
+     * 3. If timeout occurs: Return partial result with status: 'SUBMITTED'
+     * 4. If successful: Return confirmed result with on-chain status
+     * 5. Both cases include a .wait() method for retry/manual monitoring
+     *
+     * **Why This Pattern Matters**
+     * - Prevents race conditions (listener active before transaction confirmation)
+     * - Handles network timeouts gracefully (users still get transaction ID)
+     * - Provides flexibility (users can call .wait() again if needed)
+     * - Consistent error handling across all bundler operations
+     *
+     * @param transactionId Transaction ID from bundler submission
+     * @param transactionPromise WebSocket monitoring promise (already created before bundler call)
+     * @param operationName Operation name for logging context (e.g., 'liquidity removal')
+     * @returns Bundler operation result with status and wait() method
+     * @private
+     */
+    private monitorBundlerTransaction;
+    /**
+     * Remove liquidity from an existing concentrated liquidity position
+     *
+     * **CRITICAL: WebSocket-First Pattern**
+     * This method ensures WebSocket connection is established BEFORE submitting the
+     * transaction to prevent race conditions where the transaction confirms before
+     * the listener becomes active. This is essential because:
+     *
+     * 1. WebSocket listener created IMMEDIATELY after transactionId received
+     * 2. Socket.IO buffers events for registered listeners
+     * 3. If listener not active when transaction confirms, confirmation is missed
+     * 4. Graceful fallback returns partial result with transaction ID on timeout
+     *
+     * **Error Handling & Recovery**
+     * If WebSocket monitoring times out (after 60 seconds):
+     * - Returns `{ transactionId, status: 'SUBMITTED' }` indicating transaction was accepted
+     * - Transaction may still succeed on-chain even if monitoring fails
+     * - Users can call `.wait()` again to retry monitoring
+     * - Recommended: retry monitoring after waiting or check on-chain later
+     *
+     * **Partial vs Complete Removal**
+     * - Partial: Set liquidity to a fraction (e.g., 50% of current amount)
+     * - Complete: Set liquidity to the full amount to close the position
+     * - Retrieved from position details via `getSwapUserLiquidityPositions()`
+     *
+     * **Token Format Support**
+     * - String tokens: 'GALA', 'GUSDC' → auto-converted to TokenClassKey
+     * - TokenClassKey: { collection, category, type, additionalKey }
+     * - Both formats normalized to TokenClassKey for bundler submission
+     *
      * @param args Liquidity removal parameters
-     * @returns Transaction result
+     * @param args.token0 First token (string or TokenClassKey)
+     * @param args.token1 Second token (string or TokenClassKey)
+     * @param args.fee Fee tier in basis points (500, 3000, or 10000)
+     * @param args.tickLower Lower tick boundary of the position
+     * @param args.tickUpper Upper tick boundary of the position
+     * @param args.liquidity Amount of liquidity to remove (partial or complete)
+     * @param args.amount0Min Optional minimum token0 to accept (default: '0')
+     * @param args.amount1Min Optional minimum token1 to accept (default: '0')
+     * @param args.positionId Optional position ID for tracking/verification
+     *
+     * @returns Promise<GSwapRemoveLiquidityResult> Transaction result with:
+     *   - transactionId: Bundler transaction ID
+     *   - status: Transaction status from WebSocket (or 'SUBMITTED' if timeout)
+     *   - timestamp: When transaction was submitted
+     *   - wait(): Async method to monitor or retry confirmation
+     *
+     * @throws GSwapPositionError if private key unavailable or bundler submission fails
+     *
+     * @example
+     * // Get position first
+     * const positions = await sdk.getSwapUserLiquidityPositions(walletAddress);
+     * const position = positions[0];
+     *
+     * // Remove 50% of liquidity
+     * const liquidityToRemove = (parseFloat(position.liquidity) * 50) / 100;
+     * const result = await sdk.removeSwapLiquidity({
+     *   token0: 'GALA',
+     *   token1: 'GUSDC',
+     *   fee: 3000,
+     *   tickLower: position.tickLower,
+     *   tickUpper: position.tickUpper,
+     *   liquidity: liquidityToRemove.toString(),
+     *   amount0Min: '0',
+     *   amount1Min: '0',
+     *   positionId: position.positionId,
+     * });
+     *
+     * console.log('Removal submitted:', result.transactionId);
+     * await result.wait();  // Wait for on-chain confirmation
+     * console.log('Final status:', result.status);
      */
     removeLiquidity(args: {
-        token0: string;
-        token1: string;
+        token0: string | TokenClassKey;
+        token1: string | TokenClassKey;
         fee: number;
         tickLower: number;
         tickUpper: number;
         liquidity: string;
         amount0Min?: string;
         amount1Min?: string;
+        positionId?: string;
     }): Promise<any>;
     /**
-     * Collect fees from a liquidity position
+     * 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
-     * @returns Transaction result with collected amounts
+     * @param args.token0 First token (string or TokenClassKey)
+     * @param args.token1 Second token (string or TokenClassKey)
+     * @param args.fee Fee tier in basis points (500, 3000, or 10000)
+     * @param args.tickLower Lower tick boundary of the position
+     * @param args.tickUpper Upper tick boundary of the position
+     * @param args.amount0Requested Optional amount of token0 fees to collect (default: '0' = all)
+     * @param args.amount1Requested Optional amount of token1 fees to collect (default: '0' = all)
+     * @param args.positionId Optional position ID for tracking/verification
+     *
+     * @returns Promise<GSwapCollectFeesResult> Transaction result with:
+     *   - transactionId: Bundler transaction ID
+     *   - status: Transaction status from WebSocket (or 'SUBMITTED' if timeout)
+     *   - timestamp: When transaction was submitted
+     *   - wait(): Async method to monitor or retry confirmation
+     *
+     * @throws GSwapPositionError if private key unavailable or bundler submission fails
+     *
+     * @example
+     * // Get position with accumulated fees
+     * const positions = await sdk.getSwapUserLiquidityPositions(walletAddress);
+     * const position = positions[0];
+     *
+     * if (parseFloat(position.feeAmount0) > 0 || parseFloat(position.feeAmount1) > 0) {
+     *   // Collect all accumulated fees
+     *   const result = await sdk.collectSwapPositionFees({
+     *     token0: 'GALA',
+     *     token1: 'GUSDC',
+     *     fee: 3000,
+     *     tickLower: position.tickLower,
+     *     tickUpper: position.tickUpper,
+     *     amount0Requested: '0',  // Collect all token0 fees
+     *     amount1Requested: '0',  // Collect all token1 fees
+     *     positionId: position.positionId,
+     *   });
+     *
+     *   console.log('Fee collection submitted:', result.transactionId);
+     *   await result.wait();  // Wait for on-chain confirmation
+     *   console.log('Fees collected successfully');
+     * }
      */
     collectPositionFees(args: {
-        token0: string;
-        token1: string;
+        token0: string | TokenClassKey;
+        token1: string | TokenClassKey;
         fee: number;
         tickLower: number;
         tickUpper: number;
+        amount0Requested?: string;
+        amount1Requested?: string;
+        positionId?: string;
     }): Promise<any>;
     /**
      * Get real-time pool state with liquidity depth and current price
@@ -229,30 +536,176 @@ export declare class GSwapService {
      * @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)
-     * liquidity = amount0 * (sqrtRatioA * sqrtRatioB) / (sqrtRatioB - sqrtRatioA)
+     * Uses @gala-chain/dex liquidity0() function for production-accurate calculation
      * @private
      */
     private calculateLiquidityFromAmount0;
     /**
      * Calculate liquidity from amount1 (Uniswap v3 math)
-     * liquidity = amount1 / (sqrtRatioB - sqrtRatioA)
+     * Uses @gala-chain/dex liquidity1() function for production-accurate calculation
      * @private
      */
     private calculateLiquidityFromAmount1;
     /**
      * Calculate amount0 from liquidity (Uniswap v3 math)
-     * amount0 = liquidity * (sqrtRatioCurrent - sqrtRatioA) / (sqrtRatioA * sqrtRatioCurrent)
+     * Uses @gala-chain/dex getAmount0Delta() function for production-accurate calculation
      * @private
      */
     private calculateAmount0FromLiquidity;
     /**
      * Calculate amount1 from liquidity (Uniswap v3 math)
-     * amount1 = liquidity * (sqrtRatioB - sqrtRatioCurrent)
+     * Uses @gala-chain/dex getAmount1Delta() function for production-accurate calculation
      * @private
      */
     private calculateAmount1FromLiquidity;
+    /**
+     * Convert a token pair from Launchpad format to GSwap format
+     *
+     * Converts both tokens in a pair simultaneously for cleaner, more readable code
+     * when working with token swaps and pool queries.
+     *
+     * @param token0 - First token in any supported format
+     * @param token1 - Second token in any supported format
+     * @returns Object with converted tokens as gswapToken0 and gswapToken1
+     *
+     * @private
+     */
+    private convertTokenPair;
+    /**
+     * Send AddLiquidity transaction directly to bundler (bypassing gswap-sdk)
+     *
+     * Creates a liquidity position by signing a DTO and posting it directly to the
+     * GalaChain bundler. This method replaces the gswap-sdk wrapper with a direct
+     * implementation following the same pattern as CreateSale.
+     *
+     * @param params - AddLiquidity parameters including token pair, fee, tick range, and amounts
+     * @returns Transaction ID from bundler response
+     * @throws Error if not in full-access mode or if bundler request fails
+     *
+     * @private
+     */
+    private sendAddLiquidityToBundler;
+    /**
+     * Send RemoveLiquidity transaction directly to bundler
+     *
+     * Bypasses GSwap SDK and posts signed EIP-712 RemoveLiquidity DTO directly to bundler.
+     * Supports full tick ranges including negative values.
+     *
+     * @param tickLower Lower tick boundary (int256, supports negative)
+     * @param tickUpper Upper tick boundary (int256, supports negative)
+     * @param amount Liquidity amount to remove
+     * @param token0 First token class key
+     * @param token1 Second token class key
+     * @param fee Fee tier (500, 3000, or 10000)
+     * @param amount0Min Minimum amount0 to receive (slippage protection)
+     * @param amount1Min Minimum amount1 to receive (slippage protection)
+     * @param positionId Unique position identifier
+     * @returns Transaction ID from bundler response
+     *
+     * @private
+     * @throws Error if signing or bundler submission fails
+     */
+    private sendRemoveLiquidityToBundler;
+    /**
+     * Send CollectPositionFees transaction directly to bundler
+     *
+     * Bypasses GSwap SDK and posts signed EIP-712 CollectPositionFees DTO directly to bundler.
+     * Collects accumulated trading fees from a liquidity position independently of the position itself.
+     *
+     * @param token0 First token class key
+     * @param token1 Second token class key
+     * @param fee Fee tier (500, 3000, or 10000)
+     * @param amount0Requested Requested amount0 to collect (0 to collect all available)
+     * @param amount1Requested Requested amount1 to collect (0 to collect all available)
+     * @param tickLower Lower tick boundary (int256, supports negative)
+     * @param tickUpper Upper tick boundary (int256, supports negative)
+     * @param positionId Unique position identifier
+     * @returns Transaction ID from bundler response
+     *
+     * @private
+     * @throws Error if signing or bundler submission fails
+     */
+    private sendCollectPositionFeesToBundler;
+    /**
+     * Send Swap transaction directly to bundler
+     *
+     * Bypasses GSwap SDK and posts signed EIP-712 Swap DTO directly to bundler.
+     * Implements exact input swapping (sell exact amount of input token, receive output token).
+     *
+     * @param fromToken Input token (token being sold) in GSwap format
+     * @param toToken Output token (token being bought) in GSwap format
+     * @param inputAmount Amount of input token to sell
+     * @param minOutput Minimum amount of output token to receive (slippage protection)
+     * @param feeTier Fee tier (500, 3000, or 10000)
+     * @param walletAddress Wallet address executing the swap
+     * @returns Transaction ID from bundler response
+     *
+     * @private
+     * @throws Error if signing or bundler submission fails
+     */
+    private sendSwapToBundler;
+    /**
+     * Build strings instructions for AddLiquidity state locking
+     *
+     * Strings instructions are used by the bundler to lock the necessary state
+     * fields during transaction execution. This ensures atomicity of the operation.
+     *
+     * @param token0 First token class key
+     * @param token1 Second token class key
+     * @param fee Fee tier (500, 3000, or 10000 basis points)
+     * @param ownerAddress Wallet address creating the position
+     * @returns Array of strings instructions for state locking
+     *
+     * @private
+     */
+    private buildLiquidityStringsInstructions;
+    /**
+     * Handle GSwap SDK errors with consistent logging and error transformation
+     *
+     * Centralizes error handling for GSwap operations by:
+     * 1. Logging the error with context
+     * 2. Extracting error code from original error
+     * 3. Creating typed GSwap error with standardized message
+     *
+     * @param logMessage - Message to log when error occurs
+     * @param ErrorClass - Error constructor to throw (GSwapQuoteError, GSwapSwapError, etc.)
+     * @param originalError - Original error from GSwap SDK
+     * @param additionalFields - Optional additional context (e.g., { transactionHash: txHash })
+     * @throws Throws instance of provided ErrorClass with formatted message
+     *
+     * @private
+     */
+    private handleGSwapError;
     /**
      * Extract error code from GSwap SDK error
      *
@@ -266,5 +719,27 @@ export declare class GSwapService {
      * @private
      */
     private extractGSwapErrorCode;
+    /**
+     * Ensure WebSocket connection is established before transaction monitoring
+     *
+     * Checks if WebSocketService is already connected, and connects if needed.
+     * This prevents unnecessary connection attempts while ensuring transactions can be monitored.
+     *
+     * @private
+     * @throws Error if connection fails
+     */
+    private ensureWebSocketConnected;
+    /**
+     * Calculate personal sign prefix for GalaChain compatibility
+     *
+     * Builds the prefix string required by GalaChain for EIP-712 signing.
+     * This matches the format used in production working payloads.
+     *
+     * @param payload The payload being signed
+     * @returns Prefix string for signing
+     *
+     * @private
+     */
+    private calculatePersonalSignPrefix;
 }
 //# sourceMappingURL=GSwapService.d.ts.map