@gala-chain/launchpad-sdk 4.0.0 → 4.0.1-beta.10

package/dist/{LaunchpadSDK.d.ts → src/LaunchpadSDK.d.ts}

@@ -1,9 +1,10 @@
 import { Wallet } from 'ethers';
 import { SDKConfig, AddressFormat, TokenClassKey, TokenId } from './types/common';
 import { PoolDetailsData } from './types/trade.dto';
-import { LaunchTokenData, TokenSpotPrice, FetchPoolsOptions, PoolsResult, GalaChainTokenDetails, PoolData, TokenClassWithSupply } from './types/launchpad.dto';
+import { LaunchTokenData, TokenSpotPrice, FetchPoolsOptions, PoolsResult, GalaChainTokenDetails, PoolData, TokenClassWithSupply, DexSeason, LeaderboardResult, DexAggregatedVolumeSummary } from './types/launchpad.dto';
 import { UpdateProfileData, UploadProfileImageOptions, FetchTokenBalanceOptions } from './types/user.dto';
 import { TransferGalaData, TransferTokenData } from './types/transfer.dto';
+import { LockTokenData, UnlockTokenData } from './types/lock.dto';
 import { TokenLaunchResult, TradeResult } from './types/result.types';
 import { WebSocketError, WebSocketTimeoutError, TransactionFailedError } from './utils/websocket-errors';
 export { WebSocketError, WebSocketTimeoutError, TransactionFailedError, };
@@ -12,6 +13,8 @@ import { FetchPriceHistoryOptions, PriceHistoryResult } from './types/priceHisto
 import { FetchDexPoolsOptions, DexPoolsResult, DexPoolData } from './types/dex-pool.dto';
 import { GSwapPosition, PoolPriceData, GetLiquidityPositionsOptions, GetLiquidityPositionsResult } from './types/gswap.dto';
 import type { FetchCompositePoolDataOptions, CompositePoolDataResult, CalculateDexPoolQuoteOptions, DexPoolQuoteResult } from './types/composite-pool.dto';
+import type { SubscribeSwapOptions, SwapMonitorConfig, CleanupFunction, SwapEventCallback } from './types/swap-monitor.dto';
+import type { LiquidityChangedCallback, LiquidityCleanupFunction, SubscribeLiquidityOptions } from './types/liquidity-monitor.dto';
 /**
  * Configuration for initializing the Launchpad SDK
  *
@@ -972,7 +975,7 @@ export declare class LaunchpadSDK {
      * and trading capabilities.
      *
      * Supports flexible token identification using either string or object format:
-     * - String: `'Token|Unit|GUSDC|eth:0x...'` (pipe-delimited)
+     * - String: `'GUSDC|Unit|none|eth:0x...'` (pipe-delimited)
      * - Object: `{ collection, category, type, additionalKey }`
      *
      * @param tokenId Token identifier in flexible format
@@ -980,7 +983,7 @@ export declare class LaunchpadSDK {
      *
      * @example String format
      * ```typescript
-     * const details = await sdk.fetchTokenDetails('Token|Unit|GUSDC|eth:0x...');
+     * const details = await sdk.fetchTokenDetails('GUSDC|Unit|none|none');
      * console.log(details.symbol);      // 'GUSDC'
      * console.log(details.decimals);    // 6
      * console.log(details.verified);    // true
@@ -990,10 +993,10 @@ export declare class LaunchpadSDK {
      * @example Object format
      * ```typescript
      * const details = await sdk.fetchTokenDetails({
-     *   collection: 'Token',
+     *   collection: 'GUSDC',
      *   category: 'Unit',
-     *   type: 'GUSDC',
-     *   additionalKey: 'eth:0x...'
+     *   type: 'none',
+     *   additionalKey: 'none'
      * });
      * ```
      *
@@ -1001,6 +1004,156 @@ export declare class LaunchpadSDK {
      * @throws {NetworkError} If API request fails or token not found
      */
     fetchTokenDetails(tokenId: TokenId): Promise<GalaChainTokenDetails>;
+    /**
+     * Fetch all available DEX leaderboard seasons
+     *
+     * Returns all season configurations with time ranges. Use season IDs
+     * to fetch specific leaderboards with `fetchDexLeaderboardBySeasonId()`.
+     *
+     * @category DEX Leaderboard
+     * @returns Promise<DexSeason[]> Array of all seasons
+     * @throws {NetworkError} If API request fails
+     * @since 3.X.0
+     *
+     * @example
+     * ```typescript
+     * const seasons = await sdk.fetchAllDexSeasons();
+     * console.log(`Found ${seasons.length} seasons`);
+     * seasons.forEach(s => {
+     *   console.log(`${s.name}: ${s.start} to ${s.end}`);
+     * });
+     * ```
+     */
+    fetchAllDexSeasons(): Promise<DexSeason[]>;
+    /**
+     * Find the currently active DEX leaderboard season
+     *
+     * Determines which season is active based on current time falling
+     * between season start and end dates. Returns null if no season
+     * is currently active.
+     *
+     * @category DEX Leaderboard
+     * @returns Promise<DexSeason | null> Current season or null
+     * @throws {NetworkError} If API request fails
+     * @since 3.X.0
+     *
+     * @example
+     * ```typescript
+     * const current = await sdk.fetchCurrentDexSeason();
+     * if (current) {
+     *   console.log(`Active: ${current.name} (ID: ${current.id})`);
+     * } else {
+     *   console.log('No active season');
+     * }
+     * ```
+     */
+    fetchCurrentDexSeason(): Promise<DexSeason | null>;
+    /**
+     * Fetch DEX leaderboard for a specific season
+     *
+     * Returns complete leaderboard rankings with XP metrics and achievement titles.
+     * Non-paginated response includes all entries (typically 100 participants).
+     *
+     * **XP Metrics:**
+     * - `totalXp`: Combined liquidity + trading XP
+     * - `liquidityXp`: Points from providing liquidity
+     * - `tradingXp`: Points from trading volume
+     *
+     * **Achievement Titles:**
+     * - Liquidity titles: Pool Explorer, Flow Enabler, Yield Artisan, etc.
+     * - Trading titles: Novice Trader, Rookie Trader, Elite Trader, etc.
+     * - Order indicates tier (1 = entry level, higher = more advanced)
+     *
+     * @category DEX Leaderboard
+     * @param seasonId Season identifier number (must be positive integer)
+     * @returns Promise<LeaderboardResult> Complete leaderboard with rankings and metrics
+     * @throws {RequiredFieldError} If seasonId is invalid
+     * @throws {NetworkError} If API request fails
+     * @since 3.X.0
+     *
+     * @example
+     * ```typescript
+     * // Fetch specific season leaderboard
+     * const leaderboard = await sdk.fetchDexLeaderboardBySeasonId(4);
+     *
+     * // Display top trader
+     * const topTrader = leaderboard.entries[0];
+     * console.log(`Rank 1: ${topTrader.wallet}`);
+     * console.log(`Total XP: ${topTrader.totalXp}`);
+     * console.log(`Distribution: ${topTrader.distributionPercent}%`);
+     *
+     * // Find users with specific titles
+     * const whales = leaderboard.entries.filter(entry =>
+     *   entry.masteryTitles.some(t => t.name === 'Protocol Whale')
+     * );
+     * ```
+     */
+    fetchDexLeaderboardBySeasonId(seasonId: number): Promise<LeaderboardResult>;
+    /**
+     * Fetch leaderboard for the currently active season
+     *
+     * Convenience method that automatically determines the current season
+     * and fetches its leaderboard. Returns null if no season is active.
+     *
+     * Equivalent to:
+     * ```typescript
+     * const season = await sdk.fetchCurrentDexSeason();
+     * return season ? sdk.fetchDexLeaderboardBySeasonId(season.id) : null;
+     * ```
+     *
+     * @category DEX Leaderboard
+     * @returns Promise<LeaderboardResult | null> Current leaderboard or null
+     * @throws {NetworkError} If API request fails
+     * @since 3.X.0
+     *
+     * @example
+     * ```typescript
+     * // Get current leaderboard in one call
+     * const leaderboard = await sdk.fetchCurrentDexLeaderboard();
+     *
+     * if (leaderboard) {
+     *   console.log(`Season ${leaderboard.seasonId} leaders:`);
+     *   leaderboard.entries.slice(0, 10).forEach(entry => {
+     *     console.log(`${entry.rank}. ${entry.wallet}: ${entry.totalXp} XP`);
+     *   });
+     * } else {
+     *   console.log('No active season');
+     * }
+     * ```
+     */
+    fetchCurrentDexLeaderboard(): Promise<LeaderboardResult | null>;
+    /**
+     * Fetch DEX aggregated volume summary with trend metrics
+     *
+     * Returns platform-wide trading volume statistics across all DEX pools with
+     * 1-day, 7-day, and 30-day comparisons and percentage changes.
+     *
+     * **Use Cases:**
+     * - Monitor overall DEX trading activity
+     * - Identify volume trends and patterns
+     * - Compare performance across time periods
+     * - Detect market changes (increases/decreases)
+     *
+     * @category DEX Analytics
+     * @returns Promise<DexAggregatedVolumeSummary> Volume metrics with deltas
+     * @throws {NetworkError} If API request fails
+     * @since 4.0.0
+     *
+     * @example
+     * ```typescript
+     * const summary = await sdk.fetchDexAggregatedVolumeSummary();
+     * console.log(`Today's volume: $${summary.volume1d.toFixed(2)}`);
+     * console.log(`7-day change: ${(summary.volume7dDelta * 100).toFixed(2)}%`);
+     *
+     * // Analyze trend direction
+     * if (summary.volume1dDelta > 0) {
+     *   console.log('✅ Volume increasing');
+     * } else {
+     *   console.log('📉 Volume decreasing');
+     * }
+     * ```
+     */
+    fetchDexAggregatedVolumeSummary(): Promise<DexAggregatedVolumeSummary>;
     /**
      * Fetch the current launchpad token launch fee
      *
@@ -1719,10 +1872,10 @@ export declare class LaunchpadSDK {
      * // Fetch price history for a DEX token
      * const history = await sdk.fetchPriceHistory({
      *   tokenClassKey: {
-     *     collection: 'Token',
+     *     collection: 'GUSDC',
      *     category: 'Unit',
-     *     type: 'GUSDC',
-     *     additionalKey: 'eth:...'
+     *     type: 'none',
+     *     additionalKey: 'none'
      *   },
      *   from: new Date('2024-01-01'),
      *   to: new Date('2024-01-31'),
@@ -1758,10 +1911,10 @@ export declare class LaunchpadSDK {
      * // Fetch all price history for a DEX token (automatic pagination)
      * const allHistory = await sdk.fetchAllPriceHistory({
      *   tokenId: {
-     *     collection: 'Token',
+     *     collection: 'GUSDC',
      *     category: 'Unit',
-     *     type: 'GUSDC',
-     *     additionalKey: 'eth:...'
+     *     type: 'none',
+     *     additionalKey: 'none'
      *   },
      *   from: new Date('2024-01-01'),
      *   to: new Date('2024-12-31')
@@ -1852,6 +2005,88 @@ export declare class LaunchpadSDK {
      * @throws {TransferError} When token name cannot be resolved
      */
     resolveTokenClassKey(tokenName: string): Promise<TokenClassKey>;
+    /**
+     * Lock tokens on GalaChain
+     *
+     * Places a hold on tokens, preventing them from being transferred until unlocked.
+     * Useful for staking, escrow, vesting, or other hold scenarios.
+     *
+     * The lock operation creates a hold that can only be released by the lock authority
+     * (defaults to the caller's address if not specified).
+     *
+     * @param data Lock token parameters
+     * @param data.tokenId Flexible token identifier (string, TokenClassKey, or TokenInstanceKey)
+     * @param data.tokenName Token name for lookup (used if tokenId not provided)
+     * @param data.amount Amount of tokens to lock in decimal format
+     * @param data.lockAuthority Address that can manage/unlock (defaults to caller)
+     * @param data.expires Optional expiration timestamp (epoch milliseconds)
+     * @param data.name Optional lock name/identifier for matching during unlock
+     * @param data.uniqueKey Optional unique key for idempotency
+     * @param data.privateKey Optional private key override for this operation
+     * @returns Transaction ID of the lock operation
+     *
+     * @example Lock tokens with default authority
+     * ```typescript
+     * const txId = await sdk.lockToken({
+     *   tokenName: 'anime',
+     *   amount: '1000'
+     * });
+     * console.log('Tokens locked, txId:', txId);
+     * ```
+     *
+     * @example Lock with expiration and custom authority
+     * ```typescript
+     * const txId = await sdk.lockToken({
+     *   tokenName: 'anime',
+     *   amount: '500',
+     *   lockAuthority: 'eth|OtherWalletAddress',
+     *   expires: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days
+     *   name: 'staking-lock-001'
+     * });
+     * ```
+     *
+     * @throws {TransferError} When token cannot be found or lock fails
+     * @throws {ValidationError} When wallet is not configured
+     */
+    lockToken(data: LockTokenData): Promise<string>;
+    /**
+     * Unlock previously locked tokens on GalaChain
+     *
+     * Releases a token hold, making the tokens available for transfer again.
+     * Must be signed by the lock authority (the address that locked the tokens
+     * or was designated as lock authority during the lock operation).
+     *
+     * @param data Unlock token parameters
+     * @param data.tokenId Flexible token identifier (string, TokenClassKey, or TokenInstanceKey)
+     * @param data.tokenName Token name for lookup (used if tokenId not provided)
+     * @param data.amount Amount of tokens to unlock in decimal format
+     * @param data.name Optional lock name to match (if used during lock)
+     * @param data.uniqueKey Optional unique key for idempotency
+     * @param data.privateKey Optional private key override for this operation
+     * @returns Transaction ID of the unlock operation
+     *
+     * @example Unlock tokens
+     * ```typescript
+     * const txId = await sdk.unlockToken({
+     *   tokenName: 'anime',
+     *   amount: '1000'
+     * });
+     * console.log('Tokens unlocked, txId:', txId);
+     * ```
+     *
+     * @example Unlock with lock name matching
+     * ```typescript
+     * const txId = await sdk.unlockToken({
+     *   tokenName: 'anime',
+     *   amount: '500',
+     *   name: 'staking-lock-001' // Match specific lock
+     * });
+     * ```
+     *
+     * @throws {TransferError} When token or lock cannot be found, or unlock fails
+     * @throws {ValidationError} When wallet is not configured
+     */
+    unlockToken(data: UnlockTokenData): Promise<string>;
     /**
      * Resolve vault address for a token name
      *
@@ -2284,23 +2519,34 @@ export declare class LaunchpadSDK {
      * Get liquidity position by position ID
      *
      * Retrieves a specific liquidity position by its unique identifier.
+     * Optionally accepts token information for more efficient compound key lookups.
      *
      * @category DEX Liquidity Management
      * @since 3.25.0
      *
      * @param ownerAddress - Wallet address
      * @param positionId - Unique position identifier
+     * @param token0 - Optional token0 for compound key lookup (improves lookup reliability)
+     * @param token1 - Optional token1 for compound key lookup (improves lookup reliability)
+     * @param feeTier - Optional fee tier for compound key lookup (improves lookup reliability)
+     * @param tickLower - Optional lower tick boundary for compound key lookup
+     * @param tickUpper - Optional upper tick boundary for compound key lookup
      * @returns Liquidity position details
      *
-     * @example Get position by ID
+     * @example Get position by ID with token information
      * ```typescript
      * const position = await sdk.getSwapLiquidityPositionById(
      *   'eth|0x123...',
-     *   'pos-abc123'
+     *   'pos-abc123',
+     *   'GALA',
+     *   'GUSDC',
+     *   3000,
+     *   -1080,  // tickLower
+     *   900     // tickUpper
      * );
      * ```
      */
-    getSwapLiquidityPositionById(ownerAddress: string, positionId: string): Promise<import("./types/gswap.dto").LiquidityPosition>;
+    getSwapLiquidityPositionById(ownerAddress: string, positionId: string, token0?: string | Record<string, any>, token1?: string | Record<string, any>, feeTier?: number, tickLower?: number, tickUpper?: number): Promise<import("./types/gswap.dto").LiquidityPosition>;
     /**
      * Fetch a single liquidity position using ONLY the compound key (most efficient)
      *
@@ -2378,7 +2624,7 @@ export declare class LaunchpadSDK {
         liquidity: string;
         tickLower: number;
         tickUpper: number;
-    }): Promise<any>;
+    }): Promise<import("./types/gswap-responses.types").GSwapEstimateRemoveLiquidityResult>;
     /**
      * Add liquidity using price range
      *
@@ -2408,7 +2654,10 @@ export declare class LaunchpadSDK {
      * console.log(`Position created: ${result.positionId}`);
      * ```
      */
-    addSwapLiquidityByPrice(args: any): Promise<any>;
+    addSwapLiquidityByPrice(args: any): Promise<import("./types/gswap-responses.types").GSwapAddLiquidityResult & {
+        timestamp?: Date;
+        wait?: (timeoutMs?: number) => Promise<void>;
+    }>;
     /**
      * Add liquidity using tick range
      *
@@ -2434,7 +2683,10 @@ export declare class LaunchpadSDK {
      * });
      * ```
      */
-    addSwapLiquidityByTicks(args: any): Promise<any>;
+    addSwapLiquidityByTicks(args: any): Promise<import("./types/gswap-responses.types").GSwapAddLiquidityResult & {
+        timestamp?: Date;
+        wait?: (timeoutMs?: number) => Promise<void>;
+    }>;
     /**
      * Remove liquidity from a position
      *
@@ -2459,7 +2711,7 @@ export declare class LaunchpadSDK {
      * });
      * ```
      */
-    removeSwapLiquidity(args: any): Promise<any>;
+    removeSwapLiquidity(args: any): Promise<import("./types/gswap-responses.types").GSwapAddLiquidityResult>;
     /**
      * Collect accumulated position fees
      *
@@ -2481,7 +2733,7 @@ export declare class LaunchpadSDK {
      * console.log(`Collected: ${result.amount0} token0, ${result.amount1} token1`);
      * ```
      */
-    collectSwapPositionFees(args: any): Promise<any>;
+    collectSwapPositionFees(args: any): Promise<import("./types/gswap-responses.types").GSwapAddLiquidityResult>;
     /**
      * Connect to WebSocket for real-time events
      *
@@ -2674,6 +2926,633 @@ export declare class LaunchpadSDK {
         intervalMs?: number;
         creatorAddress?: string;
     }): () => void;
+    private static readonly TOKEN_CREATION_SOCKET_WAIT_ATTEMPTS;
+    private static readonly TOKEN_CREATION_SOCKET_POLL_INTERVAL_MS;
+    private static readonly DEX_POOL_SOCKET_WAIT_ATTEMPTS;
+    private static readonly DEX_POOL_SOCKET_POLL_INTERVAL_MS;
+    /**
+     * Normalize fee tier to standard format (500, 3000, or 10000)
+     *
+     * Handles various fee formats: percentage strings ("0.3", "1"), basis points (500, 3000, 10000)
+     *
+     * @param value - Fee value in any format
+     * @returns Normalized fee tier (500, 3000, 10000) or null if invalid
+     * @private
+     */
+    private normalizeFee;
+    /**
+     * Extract a field from an object with multiple possible key names
+     *
+     * @param obj - Object to search
+     * @param keys - Possible key names to try in order
+     * @returns Value of first matching key or empty string
+     * @private
+     */
+    private extractField;
+    /**
+     * Check if a string looks like a pool pair format
+     *
+     * Format: "token0/token1/fee" or full format with class keys
+     *
+     * @param value - Value to check
+     * @returns Normalized pool pair string or null
+     * @private
+     */
+    private looksLikePoolPair;
+    /**
+     * Build pool pair from object with token and fee fields
+     *
+     * Tries multiple field name patterns to extract token0, token1, and fee
+     *
+     * @param obj - Object potentially containing pool data
+     * @returns Pool pair string or null
+     * @private
+     */
+    private buildPoolPairFromObject;
+    /**
+     * Parse pool pair string into token0, token1, and fee
+     *
+     * Format: "token0ClassKey/token1ClassKey/feeTier"
+     * Example: "GALA|Unit|none|none/GUSDC|Unit|none|none/10000"
+     *
+     * @param poolPairString - Pool pair string
+     * @returns Pool data or null if invalid
+     * @private
+     */
+    private parsePoolPairString;
+    /**
+     * Serialize balance token object to classKey format
+     * Used by buildPoolPairFromBalances to convert balance objects to token symbols
+     *
+     * Format: "collection|category|type|additionalKey"
+     * Example: "GALA|Unit|none|none"
+     *
+     * @param balance - Balance object with collection, category, type fields
+     * @returns Serialized token string or empty string if invalid
+     * @private
+     */
+    private serializeBalanceToken;
+    /**
+     * Build pool pair from balance delta objects
+     * Handles extraction from swap and liquidity events that include balance changes
+     *
+     * Looks for:
+     * - userBalanceDelta, balanceDelta, or delta objects
+     * - token0Balance/token0/baseBalance/primaryBalance fields
+     * - token1Balance/token1/quoteBalance/secondaryBalance fields
+     * - Fee from poolFee, feeTier, fee, feeTierBps, or liquidityFeeBps
+     *
+     * @param obj - Object that may contain balance delta data
+     * @returns Pool pair string or null if extraction failed
+     * @private
+     */
+    private buildPoolPairFromBalances;
+    /**
+     * Extract pool data from WebSocket event payload
+     *
+     * Tries multiple patterns in order to find pool data:
+     * 1. Direct poolPair string
+     * 2. Direct poolPair field
+     * 3. Balance delta patterns (from swap/liquidity events) - CRITICAL for event detection
+     * 4. Object fields (token0, token1, fee)
+     * 5. Nested pool object
+     *
+     * Order matches reference implementation (newPoolsWatch.js) for maximum compatibility
+     *
+     * @param payload - WebSocket event payload
+     * @returns Pool data or null if not found
+     * @private
+     */
+    private extractPoolDataFromPayload;
+    /**
+     * Check if a pool matches the optional filters
+     *
+     * Implements position-independent token matching:
+     * - tokenFilter matches if token appears in EITHER position (token0 OR token1)
+     * - pairTokens matches if BOTH tokens are present regardless of order
+     * - feeTierFilter matches the fee tier
+     *
+     * @param pool - Pool data to check
+     * @param options - Optional filters
+     * @returns true if pool matches all specified filters
+     * @private
+     */
+    private matchesPoolFilter;
+    /**
+     * Check if a token creation event matches the optional creator filter
+     *
+     * Extracted for testability and maintainability.
+     *
+     * @param token - Token data from event
+     * @param creatorFilter - Optional creator address filter
+     * @returns true if token matches filter (or no filter specified)
+     * @private
+     */
+    private matchesCreatorFilter;
+    /**
+     * Subscribe to real-time token creation broadcasts
+     *
+     * Listens to WebSocket broadcasts for ALL token creations globally.
+     * Provides real-time notifications with ~1-2 second latency (vs 15-30s polling).
+     *
+     * **Architecture:**
+     * The backend broadcasts transaction confirmation events to ALL connected Socket.IO clients.
+     * This listener captures "CreateSale" events which indicate token creation.
+     *
+     * **Key Difference from onLaunchpadTokenCreation():**
+     * - `subscribeToTokenCreations()` - WebSocket broadcasts (instant, <2s latency)
+     * - `onLaunchpadTokenCreation()` - REST API polling (slow, 15-30s latency)
+     *
+     * **Connection Management:**
+     * - If WebSocket is already connected, listener is registered immediately
+     * - If not connected, automatically initiates connection with 3-second timeout
+     * - Connection failures are logged and can be handled via error callback
+     *
+     * **Cleanup Function:**
+     * - Safe to call multiple times (idempotent)
+     * - Removes listener and cleans up tracking state
+     * - Returns immediately if listener was never registered
+     *
+     * @param callback - Called when any token is created
+     * @param options - Optional filtering and error handling
+     * @param options.creatorFilter - Only receive tokens from specific creator address
+     * @param options.onError - Called if WebSocket connection fails
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.1.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Basic usage - listen to all token creations
+     * ```typescript
+     * const cleanup = sdk.subscribeToTokenCreations((token) => {
+     *   console.log(`Token created: ${token.tokenName} by ${token.creatorAddress}`);
+     * });
+     *
+     * // Stop listening when done
+     * cleanup();
+     * ```
+     *
+     * @example Filter to specific creator
+     * ```typescript
+     * const cleanup = sdk.subscribeToTokenCreations(
+     *   (token) => console.log(`My token: ${token.tokenName}`),
+     *   {
+     *     creatorFilter: sdk.getAddress(),
+     *     onError: (error) => console.error('Connection failed:', error)
+     *   }
+     * );
+     * ```
+     *
+     * @example Monitor for competitor tokens with error handling
+     * ```typescript
+     * const cleanup = sdk.subscribeToTokenCreations(
+     *   (token) => {
+     *     console.log(`New token: ${token.tokenName} - ${token.symbol}`);
+     *     // Could trigger automatic buy/analysis
+     *   },
+     *   {
+     *     onError: (error) => {
+     *       console.error('Real-time monitoring failed:', error);
+     *       // Fallback to polling
+     *     }
+     *   }
+     * );
+     * ```
+     */
+    subscribeToTokenCreations(callback: (token: {
+        tokenName: string;
+        symbol: string;
+        creatorAddress: string;
+        description: string;
+        image: string;
+        vaultAddress: string;
+        tokenStringKey: string;
+        preBuyQuantity: string;
+        websiteUrl: string;
+        telegramUrl: string;
+        twitterUrl: string;
+        isFinalized: boolean;
+    }) => void, options?: {
+        creatorFilter?: string;
+        onError?: (error: Error) => void;
+    }): () => void;
+    /**
+     * Recursively walk WebSocket event payload to find all pools
+     *
+     * Exhaustively searches through entire payload tree, including nested objects.
+     * Matches reference implementation (newPoolsWatch.js walkPayload) for complete event coverage.
+     *
+     * Uses WeakSet to track visited objects and prevent infinite loops on circular references.
+     * Deduplicates pools using the provided seenPools Set.
+     *
+     * @param payload - Event payload to walk (can be string, object, or any value)
+     * @param seenPools - Set of already-seen pool pair strings (for deduplication)
+     * @param visited - WeakSet of visited objects (to prevent circular reference loops)
+     * @returns Array of newly discovered pool data objects
+     * @private
+     */
+    private walkPayloadForPools;
+    /**
+     * Subscribe to real-time DEX pool creation broadcasts
+     *
+     * Listens to WebSocket broadcasts for DEX pool creation events globally.
+     * Provides real-time notifications when new liquidity pools are added (~1-2 second latency).
+     *
+     * **Use Case:**
+     * Monitor for graduated tokens becoming swappable on the DEX. When a token graduates from
+     * bonding curve to DEX, a pool is created and this subscription notifies in real-time.
+     *
+     * **Position-Independent Token Matching:**
+     * Token filters work regardless of position (token0 vs token1):
+     * - `tokenFilter: 'GALA'` matches both GALA/USDC and USDC/GALA pools
+     * - `pairTokens: ['GALA', 'USDC']` matches the specific pair in any order
+     *
+     * **Connection Management:**
+     * - If WebSocket is already connected, listener is registered immediately
+     * - If not connected, automatically initiates connection with 3-second timeout
+     * - Connection failures are logged and can be handled via error callback
+     *
+     * **Cleanup Function:**
+     * - Safe to call multiple times (idempotent)
+     * - Removes listener and cleans up tracking state
+     * - Returns immediately if listener was never registered
+     *
+     * @param callback - Called when a new DEX pool is created
+     * @param options - Optional filtering and error handling
+     * @param options.tokenFilter - Only receive pools containing this token (in either position)
+     * @param options.pairTokens - Only receive pools with this specific token pair (order-independent)
+     * @param options.feeTierFilter - Only receive pools with this fee tier (500, 3000, or 10000)
+     * @param options.onError - Called if WebSocket connection fails
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.1.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Listen to all new pools
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexPoolAdded((pool) => {
+     *   console.log(`New pool: ${pool.token0}/${pool.token1} (${pool.fee}% fee)`);
+     * });
+     *
+     * // Stop listening when done
+     * cleanup();
+     * ```
+     *
+     * @example Listen for GALA pools only
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexPoolAdded(
+     *   (pool) => {
+     *     if (pool.token0 === 'GALA' || pool.token1 === 'GALA') {
+     *       console.log(`GALA pool created: ${pool.poolPair}`);
+     *     }
+     *   },
+     *   { tokenFilter: 'GALA' }
+     * );
+     * ```
+     *
+     * @example Monitor specific pair with fee tier
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexPoolAdded(
+     *   (pool) => {
+     *     console.log(`GALA/GUSDC 0.3% pool created!`);
+     *   },
+     *   {
+     *     pairTokens: ['GALA', 'GUSDC'],
+     *     feeTierFilter: 3000,  // 0.3%
+     *     onError: (error) => console.error('Connection failed:', error)
+     *   }
+     * );
+     * ```
+     *
+     * @example Monitor graduated tokens (all pools, real-time)
+     * ```typescript
+     * // Watch for ANY new pools - indicates graduated tokens
+     * const cleanup = sdk.subscribeToDexPoolAdded(
+     *   (pool) => {
+     *     console.log(`Graduated token detected: ${pool.token0}/${pool.token1}`);
+     *     // Could trigger automatic trading strategies
+     *   }
+     * );
+     * ```
+     */
+    subscribeToDexPoolAdded(callback: (pool: {
+        token0: string;
+        token1: string;
+        fee: string;
+        poolPair: string;
+    }) => void, options?: {
+        tokenFilter?: string;
+        pairTokens?: [string, string];
+        feeTierFilter?: string | number;
+        onError?: (error: Error) => void;
+    }): () => void;
+    /**
+     * Subscribe to real-time DEX swap execution events
+     *
+     * Monitors all completed swaps on the DEX globally with real-time notifications (~1-2 second latency).
+     * Provides offline price predictions and delta-based pool state updates for arbitrage bot use cases.
+     *
+     * **Architecture:**
+     * The backend broadcasts transaction confirmation events for completed swaps to ALL connected clients.
+     * This listener captures "ExecuteSwap" events and provides:
+     * - Real-time swap transaction data (tokens, amounts, fees)
+     * - Offline price quotes using cached pool state (~25-50ms vs network requests)
+     * - Delta-based pool updates (~15-25ms vs full refetch ~200-400ms)
+     * - Performance metrics (latency percentiles, cache hit rates, throughput)
+     *
+     * **Position-Independent Token Matching:**
+     * Token filters work regardless of position (token0 vs token1):
+     * - `tokenFilter: 'GALA'` matches both GALA/USDC and USDC/GALA swaps
+     * - `pairTokens: ['GALA', 'USDC']` matches the specific pair in any order
+     *
+     * **Connection Management:**
+     * - If WebSocket is already connected, listener is registered immediately
+     * - If not connected, automatically initiates connection with 3-second timeout
+     * - Connection failures are logged and can be handled via error callback
+     *
+     * **Cleanup Function:**
+     * - Safe to call multiple times (idempotent)
+     * - Removes listener and cleans up tracking state
+     * - Returns immediately if listener was never registered
+     *
+     * @param callback - Called when a swap completes with enriched swap data
+     * @param options - Optional filtering, configuration, and error handling
+     * @param options.tokenFilter - Only receive swaps containing this token (in either position)
+     * @param options.pairTokens - Only receive swaps with this specific token pair (order-independent)
+     * @param options.feeTierFilter - Only receive swaps with this fee tier (500, 3000, or 10000)
+     * @param options.userFilter - Only receive swaps from this wallet address
+     * @param options.memoryProfile - Cache memory profile: 'conservative' (55MB), 'moderate' (250MB), 'aggressive' (530MB)
+     * @param options.maxPools - Maximum pools to cache (default: 500)
+     * @param options.enableDeltaOptimization - Use delta updates instead of full refetch (default: true)
+     * @param options.enableOfflineQuotes - Calculate offline quotes for known pools (default: true)
+     * @param options.debug - Enable debug logging (default: false)
+     * @param options.onError - Called if WebSocket connection fails
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.2.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Listen to all swaps globally
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexSwapExecuted((swap) => {
+     *   console.log(`Swap: ${swap.token0} → ${swap.token1}`);
+     *   console.log(`Amount: ${swap.amount0} / ${swap.amount1}`);
+     *   if (swap.estimatedPrice) {
+     *     console.log(`Price: ${swap.estimatedPrice}`);
+     *   }
+     * });
+     *
+     * // Stop listening when done
+     * cleanup();
+     * ```
+     *
+     * @example Arbitrage bot - monitor GALA/GUSDC swaps with offline pricing
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexSwapExecuted(
+     *   async (swap) => {
+     *     if (swap.estimatedPrice && swap.poolStateUpdated) {
+     *       // Price calculated instantly using cached pool state
+     *       console.log(`Arbitrage opportunity: ${swap.estimatedPrice}`);
+     *
+     *       // Trigger trading logic
+     *       await executeArbitrageStrategy(swap);
+     *     }
+     *   },
+     *   {
+     *     pairTokens: ['GALA', 'GUSDC'],
+     *     memoryProfile: 'aggressive',    // Max cache for arbitrage
+     *     enableDeltaOptimization: true,  // Fast updates
+     *     enableOfflineQuotes: true,      // Instant pricing
+     *     onError: (error) => console.error('Swap monitoring failed:', error)
+     *   }
+     * );
+     * ```
+     *
+     * @example Monitor specific token with fee tier
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexSwapExecuted(
+     *   (swap) => {
+     *     console.log(`GALA 0.3% pool swap: ${swap.amount0}`);
+     *   },
+     *   {
+     *     tokenFilter: 'GALA',
+     *     feeTierFilter: 3000,  // 0.3% fee tier
+     *   }
+     * );
+     * ```
+     *
+     * @example Health monitoring for swap monitoring system
+     * ```typescript
+     * let swapMonitor: MultiPoolStateManager | null = null;
+     *
+     * const cleanup = sdk.subscribeToDexSwapExecuted(
+     *   (swap) => {
+     *     console.log(`Swap processed in <50ms:`, swap.poolStateUpdated);
+     *   },
+     *   {
+     *     memoryProfile: 'moderate',
+     *     onError: (error) => console.error('Connection failed:', error)
+     *   }
+     * );
+     *
+     * // Can get health metrics
+     * // const health = swapMonitor?.getHealth();
+     * // console.log(`Cache hit rate: ${health.metrics.cacheHitRate}%`);
+     * ```
+     */
+    subscribeToDexSwapExecuted(callback: SwapEventCallback, options?: SubscribeSwapOptions & SwapMonitorConfig): CleanupFunction;
+    /**
+     * Subscribe to real-time DEX liquidity addition events
+     *
+     * Monitors all liquidity additions on the DEX globally with real-time notifications.
+     * All liquidity events are broadcast to all connected clients - you can monitor
+     * market-wide liquidity activity, not just your own transactions.
+     *
+     * **Use Cases:**
+     * - LP position tracking: Monitor when users add liquidity to positions
+     * - Whale watching: Detect large liquidity additions
+     * - Market analysis: Track overall DEX liquidity growth
+     * - Position management: React to liquidity changes in pools you care about
+     *
+     * **Position-Independent Token Matching:**
+     * Token filters work regardless of position (token0 vs token1):
+     * - `tokenFilter: 'GALA'` matches liquidity additions to any GALA pool
+     * - `pairTokens: ['GALA', 'GUSDC']` matches the specific pair in any order
+     *
+     * @param callback - Called when liquidity is added with event data
+     * @param options - Optional filtering and error handling
+     * @param options.positionId - Only receive events for this LP position NFT
+     * @param options.poolHash - Only receive events for this pool
+     * @param options.tokenFilter - Only receive events containing this token (in either position)
+     * @param options.pairTokens - Only receive events with this specific token pair (order-independent)
+     * @param options.feeTierFilter - Only receive events with this fee tier (500, 3000, or 10000)
+     * @param options.userFilter - Only receive events from this wallet address
+     * @param options.minAmount - Only receive events where at least one amount exceeds this value
+     * @param options.onError - Called if WebSocket connection fails
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.3.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Listen to all liquidity additions
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityAdded((event) => {
+     *   console.log(`Liquidity added: ${event.amounts[0]} / ${event.amounts[1]}`);
+     *   console.log(`Position: ${event.positionId}`);
+     *   console.log(`Pool: ${event.poolHash}`);
+     * });
+     *
+     * // Stop listening when done
+     * await cleanup();
+     * ```
+     *
+     * @example Track specific pool liquidity
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityAdded(
+     *   (event) => {
+     *     console.log(`GALA/GUSDC liquidity: +${event.amounts[0]} GALA`);
+     *   },
+     *   {
+     *     pairTokens: ['GALA', 'GUSDC'],
+     *     feeTierFilter: 3000,  // 0.3% fee tier
+     *   }
+     * );
+     * ```
+     *
+     * @example Whale watching
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityAdded(
+     *   (event) => {
+     *     console.log(`🐋 Large liquidity add detected!`);
+     *     console.log(`Amount: ${event.amounts[0]} / ${event.amounts[1]}`);
+     *     console.log(`User: ${event.userAddress}`);
+     *   },
+     *   { minAmount: '10000' }  // Only large additions
+     * );
+     * ```
+     */
+    subscribeToDexLiquidityAdded(callback: LiquidityChangedCallback, options?: SubscribeLiquidityOptions): LiquidityCleanupFunction;
+    /**
+     * Subscribe to real-time DEX liquidity removal events
+     *
+     * Monitors all liquidity removals on the DEX globally with real-time notifications.
+     * All liquidity events are broadcast to all connected clients - you can monitor
+     * market-wide liquidity activity, not just your own transactions.
+     *
+     * **Use Cases:**
+     * - LP exit tracking: Monitor when users remove liquidity from positions
+     * - Whale watching: Detect large liquidity withdrawals
+     * - Market analysis: Track overall DEX liquidity changes
+     * - Risk management: React to liquidity decreases in pools you trade
+     *
+     * @param callback - Called when liquidity is removed with event data
+     * @param options - Optional filtering and error handling
+     * @param options.positionId - Only receive events for this LP position NFT
+     * @param options.poolHash - Only receive events for this pool
+     * @param options.tokenFilter - Only receive events containing this token (in either position)
+     * @param options.pairTokens - Only receive events with this specific token pair (order-independent)
+     * @param options.feeTierFilter - Only receive events with this fee tier (500, 3000, or 10000)
+     * @param options.userFilter - Only receive events from this wallet address
+     * @param options.minAmount - Only receive events where at least one amount exceeds this value
+     * @param options.onError - Called if WebSocket connection fails
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.3.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Listen to all liquidity removals
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityRemoved((event) => {
+     *   console.log(`Liquidity removed: ${event.amounts[0]} / ${event.amounts[1]}`);
+     *   console.log(`Position: ${event.positionId}`);
+     * });
+     *
+     * await cleanup();
+     * ```
+     *
+     * @example Track position exits
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityRemoved(
+     *   (event) => {
+     *     console.log(`Position ${event.positionId} reduced liquidity`);
+     *   },
+     *   { positionId: 'my-position-id' }
+     * );
+     * ```
+     */
+    subscribeToDexLiquidityRemoved(callback: LiquidityChangedCallback, options?: SubscribeLiquidityOptions): LiquidityCleanupFunction;
+    /**
+     * Subscribe to all DEX liquidity changes
+     *
+     * Monitors all liquidity operations on the DEX globally with real-time notifications.
+     * The backend broadcasts position change events without distinguishing between
+     * add and remove operations.
+     *
+     * **Use Cases:**
+     * - Complete liquidity tracking: Monitor all LP activity in a pool
+     * - Position monitoring: Track changes to specific positions
+     * - Dashboard displays: Show real-time liquidity activity feed
+     *
+     * @param callback - Called when liquidity changes with event data
+     * @param options - Optional filtering and error handling
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.3.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Monitor all liquidity activity
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityChanged((event) => {
+     *   console.log(`Liquidity changed: ${event.amounts[0]} / ${event.amounts[1]}`);
+     *   console.log(`Pool: ${event.poolHash}`);
+     *   console.log(`Position: ${event.positionId}`);
+     * });
+     *
+     * await cleanup();
+     * ```
+     *
+     * @example Track specific pool liquidity
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityChanged(
+     *   (event) => {
+     *     console.log(`Pool activity: ${event.amounts[0]} / ${event.amounts[1]}`);
+     *     console.log(`User: ${event.userAddress}`);
+     *   },
+     *   { pairTokens: ['GALA', 'GUSDC'] }
+     * );
+     * ```
+     */
+    subscribeToDexLiquidityChanged(callback: LiquidityChangedCallback, options?: SubscribeLiquidityOptions): LiquidityCleanupFunction;
+    /**
+     * Internal method for subscribing to liquidity events
+     *
+     * @internal
+     */
+    private subscribeToDexLiquidityEvents;
+    /**
+     * Check if a liquidity event matches the specified filters
+     *
+     * @internal
+     */
+    private matchesLiquidityFilter;
+    /**
+     * Normalize fee tier to basis points
+     *
+     * @internal
+     */
+    private normalizeFeeTier;
     /**
      * Cleanup SDK resources and connections
      *