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

package/dist/src/utils/load-env.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Environment variable loader that checks both root and local .env files
+ * Useful for demo scripts and CLI tools that need wallet configuration
+ */
+/**
+ * Load environment variables from root .env and local .env files
+ * Root .env is loaded first, then local .env (local overrides root)
+ *
+ * Usage in demo scripts:
+ * ```typescript
+ * import { loadEnvWithFallback } from '../src/utils/load-env';
+ *
+ * loadEnvWithFallback();
+ *
+ * const privateKey = process.env.WALLET_PRIVATE_KEY;
+ * if (!privateKey) {
+ *   throw new Error('WALLET_PRIVATE_KEY not set in root or local .env');
+ * }
+ * ```
+ */
+export declare function loadEnvWithFallback(): void;
+/**
+ * Get a specific environment variable with detailed error message
+ * Checks both root and local .env files
+ */
+export declare function getEnvOrThrow(varName: string, context?: string): string;
+/**
+ * Get environment variable with optional default
+ */
+export declare function getEnv(varName: string, defaultValue?: string): string | undefined;
+//# sourceMappingURL=load-env.d.ts.map

package/dist/src/utils/load-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-env.d.ts","sourceRoot":"","sources":["../../../src/utils/load-env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAY1C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CASvE;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjF"}

package/dist/src/utils/multipart-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart-helpers.d.ts","sourceRoot":"","sources":["../../../src/utils/multipart-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,SAAS,EAAE,MAAM,YAAU,EAC3B,QAAQ,EAAE,MAAM,GACf,QAAQ,CAiBV"}

package/dist/{utils → src/utils}/multipart.d.ts

@@ -38,7 +38,7 @@ export declare function getFileExtension(filename: string): string;
  * @param data Additional form fields
  * @returns FormData object ready for upload
  */
-export declare function createFormData(file: File, data?: Record<string, any>): FormData;
+export declare function createFormData(file: File, data?: Record<string, unknown>): FormData;
 /**
  * Creates multipart form data for Node.js environments
  *
@@ -48,7 +48,7 @@ export declare function createFormData(file: File, data?: Record<string, any>):
  * @param data Additional form fields
  * @returns Object with data buffer and headers
  */
-export declare function createMultipartFormData(buffer: Buffer, filename: string, mimeType: string, data?: Record<string, any>): {
+export declare function createMultipartFormData(buffer: Buffer, filename: string, mimeType: string, data?: Record<string, unknown>): {
     data: Buffer;
     headers: Record<string, string>;
 };

package/dist/src/utils/multipart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../../src/utils/multipart.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAcH;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAGnC,QAAQ,CAAC,EAAE,MAAM;IACjB,QAAQ,CAAC,EAAE,MAAM;gBAFxB,OAAO,EAAE,MAAM,EACR,QAAQ,CAAC,EAAE,MAAM,YAAA,EACjB,QAAQ,CAAC,EAAE,MAAM,YAAA;CAK3B;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CAiGN;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CASzD;AA0BD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,QAAQ,CAiBV;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA0CnD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAwB9C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAM3C"}

package/dist/src/utils/number-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"number-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/number-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,QAAQ,EAAE,MAAM,GACf,MAAM,CAuBR;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,QAAQ,EAAE,MAAM,GACf,MAAM,CAmBR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GACxC,OAAO,CAWT;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,MAAM,CA0BR;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAiC,GAAG,MAAM,CAO7F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/src/utils/pool-pair-parser.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Pool Pair Parser
+ *
+ * Utilities for parsing poolPair strings from DEX pool discovery into components
+ * and converting pipe-delimited token formats to TypeClass objects.
+ *
+ * @packageDocumentation
+ */
+import type { TokenClassKey } from '../types/common';
+/**
+ * Parse poolPair string from fetchDexPools() into token0, token1, and fee components
+ *
+ * Format: "token0/token1/fee"
+ * Example: "GALA|Unit|none|none/Token|Unit|BENE|client:5c806869e7fd0e2384461ce9/3000"
+ *
+ * Each token is in pipe-delimited format: "collection|category|type|additionalKey"
+ *
+ * @param poolPair Pool pair string from fetchDexPools() result
+ * @returns Object with token0, token1 (both in pipe-delimited format), and fee tier
+ * @throws Error if poolPair format is invalid
+ *
+ * @example
+ * ```typescript
+ * const { token0, token1, fee } = parsePoolPair(
+ *   'GALA|Unit|none|none/Token|Unit|BENE|client:123/3000'
+ * );
+ * // → { token0: 'GALA|Unit|none|none', token1: 'Token|Unit|BENE|client:123', fee: 3000 }
+ * ```
+ */
+export declare function parsePoolPair(poolPair: string): {
+    token0: string;
+    token1: string;
+    fee: number;
+};
+/**
+ * Convert pipe-delimited token string to TokenClassKey object
+ *
+ * Format: "collection|category|type|additionalKey"
+ * Example: "GALA|Unit|none|none" or "Token|Unit|BENE|client:5c806869e7fd0e2384461ce9"
+ *
+ * @param pipeDelimitedToken Token string in pipe-delimited format
+ * @returns TokenClassKey object with all components
+ * @throws Error if token format is invalid
+ *
+ * @example
+ * ```typescript
+ * const tokenClass = pipeDelimitedToTokenClassKey('GALA|Unit|none|none');
+ * // → { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' }
+ *
+ * const tokenClass2 = pipeDelimitedToTokenClassKey('Token|Unit|BENE|client:123');
+ * // → { collection: 'Token', category: 'Unit', type: 'BENE', additionalKey: 'client:123' }
+ * ```
+ */
+export declare function pipeDelimitedToTokenClassKey(pipeDelimitedToken: string): TokenClassKey;
+//# sourceMappingURL=pool-pair-parser.d.ts.map

package/dist/src/utils/pool-pair-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-pair-parser.d.ts","sourceRoot":"","sources":["../../../src/utils/pool-pair-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb,CA2CA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,CAAC,kBAAkB,EAAE,MAAM,GAAG,aAAa,CAyCtF"}

package/dist/src/utils/pool-state-validator.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Pool State Validator
+ *
+ * Multi-tier validation system for detecting state drift and triggering refetches.
+ * Implements three validation levels:
+ * - Tier 1: Fast validation (<5ms) - Always run on every swap delta
+ * - Tier 2: Moderate validation (~10-15ms) - Run periodically with chain data comparison
+ * - Tier 3: Full validation (~50-100ms) - Compare cached state with fresh network fetch
+ *
+ * @packageDocumentation
+ */
+import { Pool } from '@gala-chain/dex';
+import BigNumber from 'bignumber.js';
+import type { SwapEventData, PoolStateValidationResult } from '../types/pool-state-delta.dto';
+import type { CompositePoolDataResult } from '../types/composite-pool.dto';
+/**
+ * Configuration for pool state validation
+ *
+ * @category Pool State
+ */
+export interface PoolStateValidationConfig {
+    /**
+     * Maximum acceptable drift percentage before triggering refetch
+     * @default 0.001 (0.1%)
+     */
+    maxDriftThreshold: number;
+    /**
+     * Maximum liquidity change percentage allowed in single swap
+     * @default 0.5 (50%)
+     */
+    maxLiquidityChangePct: number;
+    /**
+     * Maximum tick drift allowed between tick and calculated tick from sqrtPrice
+     * @default 1 (allow 1 tick rounding error)
+     */
+    maxTickDrift: number;
+    /**
+     * Maximum tick count difference percentage for full validation
+     * @default 0.1 (10%)
+     */
+    maxTickCountDriftPct: number;
+    /**
+     * Maximum price drift percentage for full validation
+     * @default 0.001 (0.1%)
+     */
+    maxPriceDriftPct: number;
+    /**
+     * Maximum liquidity drift percentage for full validation
+     * @default 0.01 (1.0%)
+     */
+    maxLiquidityDriftPct: number;
+}
+/**
+ * Three-tier pool state validation system
+ *
+ * Provides fast, moderate, and full validation strategies for detecting
+ * state drift in cached DEX pool data.
+ *
+ * @category Pool State
+ */
+export declare class PoolStateValidator {
+    private static readonly logger;
+    /**
+     * Default validation configuration
+     */
+    static readonly DEFAULT_CONFIG: PoolStateValidationConfig;
+    /**
+     * Tier 1: Fast validation (<5ms)
+     *
+     * Quick sanity checks run on EVERY swap delta application.
+     * Detects obvious calculation errors immediately without expensive operations.
+     *
+     * Checks:
+     * 1. Price moved in correct direction based on swap direction
+     * 2. Liquidity didn't change drastically (>50% in one swap)
+     * 3. Fee growth never decreased (monotonically increasing)
+     * 4. Protocol fees only increased
+     *
+     * @param originalPool Original pool state before swap
+     * @param updatedPool Pool state after applying swap delta
+     * @param swapEvent The swap event that was applied
+     * @param config Optional validation configuration
+     * @returns true if all critical checks pass, false if errors detected
+     *
+     * @example
+     * ```typescript
+     * const isValid = PoolStateValidator.fastValidation(
+     *   originalPool,
+     *   updatedPool,
+     *   swapEvent
+     * );
+     *
+     * if (!isValid) {
+     *   console.error('Fast validation failed - immediate refetch recommended');
+     * }
+     * ```
+     */
+    static fastValidation(originalPool: Pool, updatedPool: Pool, swapEvent: SwapEventData, config?: PoolStateValidationConfig): boolean;
+    /**
+     * Tier 2: Moderate validation (~10-15ms)
+     *
+     * More expensive validation with actual value comparisons.
+     * Run periodically (e.g., every 10 swaps) or manually.
+     * Compares calculated state with actual chain data when available.
+     *
+     * Checks:
+     * 1. Compare calculated sqrtPrice with actual chain data (if provided)
+     * 2. Verify tick/price consistency
+     * 3. Ensure fee growth is monotonic
+     * 4. Validate liquidity is positive
+     *
+     * @param updatedPool Pool state from calculation
+     * @param swapEvent Original swap event (may contain actual chain data)
+     * @param config Optional validation configuration
+     * @returns Detailed validation result with drift detection
+     *
+     * @example
+     * ```typescript
+     * const result = PoolStateValidator.moderateValidation(
+     *   updatedPool,
+     *   swapEvent,
+     *   { maxDriftThreshold: 0.001 }
+     * );
+     *
+     * if (result.shouldRefetch) {
+     *   console.log(`Refetch recommended: ${result.refetchReason}`);
+     *   console.log(`Drift: ${result.driftPercentage}%`);
+     * }
+     * ```
+     */
+    static moderateValidation(updatedPool: Pool, swapEvent: SwapEventData, config?: PoolStateValidationConfig): PoolStateValidationResult;
+    /**
+     * Tier 3: Full validation (~50-100ms)
+     *
+     * Complete validation by fetching fresh chain data and comparing.
+     * Only run when other validations suggest drift or on-demand.
+     * This is expensive (~50-100ms) so use sparingly.
+     *
+     * Compares:
+     * 1. Price drift between cached and fresh data
+     * 2. Liquidity drift between cached and fresh data
+     * 3. Tick data completeness (missing ticks in cache)
+     *
+     * @param poolKey Pool identifier for logging
+     * @param cachedPoolData Current cached pool state
+     * @param fetchFn Async function that fetches fresh pool data from chain
+     * @returns Detailed validation result with drift analysis
+     *
+     * @example
+     * ```typescript
+     * const result = await PoolStateValidator.fullValidation(
+     *   'GALA-BENE-3000',
+     *   cachedPoolData,
+     *   async () => await sdk.fetchCompositePoolData({
+     *     token0: 'GALA|Unit|none|none',
+     *     token1: 'Token|Unit|BENE|client:123',
+     *     fee: 3000
+     *   })
+     * );
+     *
+     * if (result.shouldRefetch) {
+     *   // Use fresh data from fetchFn result
+     *   console.log(`Validation errors: ${result.validationErrors}`);
+     * }
+     * ```
+     */
+    static fullValidation(poolKey: string, cachedPoolData: CompositePoolDataResult, fetchFn: () => Promise<CompositePoolDataResult>): Promise<PoolStateValidationResult>;
+    /**
+     * Calculate percentage difference between two values
+     *
+     * @param calculated Calculated/cached value
+     * @param actual Actual chain value
+     * @returns Percentage difference (0.5 = 0.5%)
+     *
+     * @example
+     * ```typescript
+     * const drift = PoolStateValidator.calculateDriftPercentage(
+     *   new BigNumber('1000'),
+     *   new BigNumber('1005')
+     * );
+     * console.log(`Drift: ${drift}%`); // "Drift: 0.5%"
+     * ```
+     */
+    static calculateDriftPercentage(calculated: BigNumber, actual: BigNumber): number;
+    /**
+     * Build a PoolStateValidationResult object
+     *
+     * @param isValid Whether validation passed
+     * @param driftPercentage Drift detected (as percentage)
+     * @param shouldRefetch Whether refetch is recommended
+     * @param errors Array of error messages
+     * @returns Structured validation result
+     *
+     * @example
+     * ```typescript
+     * const result = PoolStateValidator.buildValidationResult(
+     *   false,
+     *   1.5,
+     *   true,
+     *   ['Price drift exceeded threshold']
+     * );
+     * console.log(result.refetchReason); // 'drift'
+     * ```
+     */
+    static buildValidationResult(isValid: boolean, driftPercentage: number, shouldRefetch: boolean, errors?: string[]): PoolStateValidationResult;
+}
+//# sourceMappingURL=pool-state-validator.d.ts.map

package/dist/src/utils/pool-state-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-state-validator.d.ts","sourceRoot":"","sources":["../../../src/utils/pool-state-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC,OAAO,SAAS,MAAM,cAAc,CAAC;AAErC,OAAO,KAAK,EACV,aAAa,EACb,yBAAyB,EAC1B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAG3E;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAG3B;IAEH;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,yBAAyB,CAOvD;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,cAAc,CACnB,YAAY,EAAE,IAAI,EAClB,WAAW,EAAE,IAAI,EACjB,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,yBAA6D,GACpE,OAAO;IAmHV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,MAAM,CAAC,kBAAkB,CACvB,WAAW,EAAE,IAAI,EACjB,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,yBAA6D,GACpE,yBAAyB;IA6E5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;WACU,cAAc,CACzB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,uBAAuB,EACvC,OAAO,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,GAC9C,OAAO,CAAC,yBAAyB,CAAC;IA6ErC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,wBAAwB,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,MAAM;IAYjF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,qBAAqB,CAC1B,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,OAAO,EACtB,MAAM,GAAE,MAAM,EAAO,GACpB,yBAAyB;CAsC7B"}

package/dist/src/utils/position-filters.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Liquidity position filter utilities
+ *
+ * Helper functions for filtering and grouping liquidity positions by various criteria:
+ * - Liquidity amount and thresholds
+ * - Token pairs and individual tokens
+ * - Fee tiers
+ * - Pool identifiers (token0|token1|feeTier)
+ *
+ * All functions are pure and return new arrays/maps without mutating input.
+ *
+ * @example
+ * ```typescript
+ * import { filterByLiquidity, groupByTokenPair } from '@gala-chain/launchpad-sdk';
+ *
+ * const positions = await sdk.getAllSwapUserLiquidityPositions(address);
+ * const active = filterByLiquidity(positions);  // Remove zero-liquidity positions
+ * const grouped = groupByTokenPair(active);     // Organize by GALA/GUSDC, etc.
+ * ```
+ */
+import BigNumber from 'bignumber.js';
+import type { LiquidityPosition } from '../types/gswap.dto';
+/**
+ * Sort order for position arrays
+ */
+export type SortOrder = 'asc' | 'desc';
+/**
+ * Predicate function for filtering positions
+ */
+export type PositionFilter = (position: LiquidityPosition) => boolean;
+/**
+ * Options for position filtering operations
+ */
+export interface PositionFilterOptions {
+    /** Minimum liquidity threshold */
+    minLiquidity?: string;
+    /** Fee tier to filter by (500, 3000, or 10000) */
+    feeTier?: number;
+    /** Token symbol to filter by (either token0 or token1) */
+    token?: string;
+}
+/**
+ * Filter positions to only those with non-zero liquidity
+ *
+ * Removes positions with `liquidity === '0'`, typically indicating
+ * closed or inactive positions.
+ *
+ * @param positions Array of liquidity positions
+ * @returns Filtered array with only positions that have liquidity > 0
+ *
+ * @example
+ * ```typescript
+ * const allPositions = await sdk.getAllSwapUserLiquidityPositions(address);
+ * const activePositions = filterByLiquidity(allPositions);
+ * console.log(`Active positions: ${activePositions.length}`);
+ * ```
+ */
+export declare function filterByLiquidity(positions: LiquidityPosition[]): LiquidityPosition[];
+/**
+ * Filter positions by minimum liquidity threshold
+ *
+ * Keeps only positions with `liquidity >= minLiquidity`. Useful for
+ * finding significant positions or filtering out dust positions.
+ *
+ * @param positions Array of liquidity positions
+ * @param minLiquidity Minimum liquidity amount (as string for precision)
+ * @returns Filtered array with positions >= minLiquidity
+ *
+ * @example
+ * ```typescript
+ * const largePositions = filterByMinLiquidity(positions, '1000');
+ * // Only positions with liquidity >= 1000
+ *
+ * const hugePositions = filterByMinLiquidity(positions, '100000');
+ * // Find whale positions
+ * ```
+ */
+export declare function filterByMinLiquidity(positions: LiquidityPosition[], minLiquidity: string | number | BigNumber): LiquidityPosition[];
+/**
+ * Sort positions by liquidity amount
+ *
+ * @param positions Array of liquidity positions
+ * @param order Sort order: 'desc' (default, highest first) or 'asc' (lowest first)
+ * @returns Sorted array (creates new array, doesn't mutate input)
+ *
+ * @example
+ * ```typescript
+ * const sorted = sortByLiquidity(positions, 'desc');
+ * const topPosition = sorted[0];  // Largest liquidity position
+ *
+ * const lowest = sortByLiquidity(positions, 'asc');
+ * const smallest = lowest[0];    // Smallest liquidity position
+ * ```
+ */
+export declare function sortByLiquidity(positions: LiquidityPosition[], order?: SortOrder): LiquidityPosition[];
+/**
+ * Filter positions by exact token pair match
+ *
+ * Matches token0 and token1 in either order. Comparison is case-insensitive.
+ *
+ * @param positions Array of liquidity positions
+ * @param token0 First token symbol (e.g., "GALA")
+ * @param token1 Second token symbol (e.g., "GUSDC")
+ * @returns Positions matching the token pair
+ *
+ * @example
+ * ```typescript
+ * const galaPositions = filterByTokenPair(positions, 'GALA', 'GUSDC');
+ * // Returns positions for GALA/GUSDC pair (in either order)
+ *
+ * const reverseMatch = filterByTokenPair(positions, 'GUSDC', 'GALA');
+ * // Also returns GALA/GUSDC positions (same result as above)
+ * ```
+ */
+export declare function filterByTokenPair(positions: LiquidityPosition[], token0: string, token1: string): LiquidityPosition[];
+/**
+ * Filter positions by a single token (either side of the pair)
+ *
+ * Finds all positions where the token appears as either token0 or token1.
+ * Comparison is case-insensitive.
+ *
+ * @param positions Array of liquidity positions
+ * @param token Token symbol to search for (e.g., "GALA")
+ * @returns Positions containing the specified token
+ *
+ * @example
+ * ```typescript
+ * const galaPositions = filterByToken(positions, 'GALA');
+ * // Returns GALA/GUSDC, GALA/ETH, ETH/GALA, etc.
+ *
+ * const stablecoinPositions = filterByToken(positions, 'GUSDC');
+ * // Any position with GUSDC on either side
+ * ```
+ */
+export declare function filterByToken(positions: LiquidityPosition[], token: string): LiquidityPosition[];
+/**
+ * Filter positions by fee tier
+ *
+ * Finds positions using a specific fee tier (0.05%, 0.30%, or 1.00%).
+ *
+ * @param positions Array of liquidity positions
+ * @param feeTier Fee tier in basis points (500 = 0.05%, 3000 = 0.30%, 10000 = 1.00%)
+ * @returns Positions with the specified fee tier
+ *
+ * @example
+ * ```typescript
+ * const lowFee = filterByFeeTier(positions, 500);     // 0.05% - Best for stablecoins
+ * const mid = filterByFeeTier(positions, 3000);       // 0.30% - Standard
+ * const highFee = filterByFeeTier(positions, 10000);  // 1.00% - Volatile pairs
+ * ```
+ */
+export declare function filterByFeeTier(positions: LiquidityPosition[], feeTier: number): LiquidityPosition[];
+/**
+ * Group positions by token pair
+ *
+ * Creates a Map keyed by "TOKEN0/TOKEN1" containing arrays of positions
+ * for that pair. The pair key format is always uppercase with "/" separator.
+ *
+ * @param positions Array of liquidity positions
+ * @returns Map<pair_string, positions[]> where pair_string is "TOKEN0/TOKEN1"
+ *
+ * @example
+ * ```typescript
+ * const grouped = groupByTokenPair(positions);
+ *
+ * // Access positions for specific pairs
+ * const galusdcPos = grouped.get('GALA/GUSDC');
+ * const galaethPos = grouped.get('GALA/ETH');
+ *
+ * // Iterate over all pairs
+ * grouped.forEach((positions, pair) => {
+ *   console.log(`${pair}: ${positions.length} positions`);
+ * });
+ * ```
+ */
+export declare function groupByTokenPair(positions: LiquidityPosition[]): Map<string, LiquidityPosition[]>;
+/**
+ * Group positions by fee tier
+ *
+ * Creates a Map keyed by fee tier (500, 3000, 10000) containing arrays
+ * of positions using that fee tier.
+ *
+ * @param positions Array of liquidity positions
+ * @returns Map<feeTier, positions[]>
+ *
+ * @example
+ * ```typescript
+ * const byFee = groupByFeeTier(positions);
+ *
+ * const stablecoinPos = byFee.get(500);   // 0.05% fee tier
+ * const standardPos = byFee.get(3000);    // 0.30% fee tier
+ * const volatilePos = byFee.get(10000);   // 1.00% fee tier
+ *
+ * // Fee tier statistics
+ * byFee.forEach((positions, feeTier) => {
+ *   const feePercent = feeTier / 100;
+ *   console.log(`${feePercent}%: ${positions.length} positions`);
+ * });
+ * ```
+ */
+export declare function groupByFeeTier(positions: LiquidityPosition[]): Map<number, LiquidityPosition[]>;
+/**
+ * Filter positions by complete pool identifier
+ *
+ * Matches positions that belong to a specific pool identified by
+ * token0, token1, and fee tier. Comparison is case-insensitive for tokens.
+ *
+ * @param positions Array of liquidity positions
+ * @param token0 First token symbol
+ * @param token1 Second token symbol
+ * @param feeTier Fee tier (500, 3000, or 10000)
+ * @returns Positions matching the specific pool
+ *
+ * @example
+ * ```typescript
+ * // Find all positions in the GALA/GUSDC 0.30% pool
+ * const poolPositions = filterByPoolKey(positions, 'GALA', 'GUSDC', 3000);
+ *
+ * // Calculate total liquidity in a specific pool
+ * const totalLiq = poolPositions
+ *   .reduce((sum, pos) => sum + BigInt(pos.liquidity), 0n);
+ * ```
+ */
+export declare function filterByPoolKey(positions: LiquidityPosition[], token0: string, token1: string, feeTier: number): LiquidityPosition[];
+/**
+ * Group positions by pool identifier (token pair + fee tier)
+ *
+ * Creates a Map keyed by "token0|token1|feeTier" containing arrays of
+ * positions in that specific pool. Useful for analyzing pool-specific metrics.
+ *
+ * @param positions Array of liquidity positions
+ * @returns Map<pool_key, positions[]> where pool_key is "TOKEN0|TOKEN1|FEETIER"
+ *
+ * @example
+ * ```typescript
+ * const byPool = groupByPoolKey(positions);
+ *
+ * // Access positions in specific pool
+ * const galusdcStandard = byPool.get('GALA|GUSDC|3000');
+ *
+ * // Calculate pool statistics
+ * byPool.forEach((positions, poolKey) => {
+ *   const [token0, token1, feeTier] = poolKey.split('|');
+ *   const total = positions.reduce(
+ *     (sum, pos) => sum.plus(pos.liquidity),
+ *     new BigNumber(0)
+ *   );
+ *   console.log(`${poolKey}: ${positions.length} LPs, ${total} total liquidity`);
+ * });
+ * ```
+ */
+export declare function groupByPoolKey(positions: LiquidityPosition[]): Map<string, LiquidityPosition[]>;
+//# sourceMappingURL=position-filters.d.ts.map

package/dist/src/utils/position-filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position-filters.d.ts","sourceRoot":"","sources":["../../../src/utils/position-filters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,SAAS,MAAM,cAAc,CAAC;AACrC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC;AAEvC;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAErF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,iBAAiB,EAAE,EAC9B,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GACxC,iBAAiB,EAAE,CAGrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,iBAAiB,EAAE,EAC9B,KAAK,GAAE,SAAkB,GACxB,iBAAiB,EAAE,CAOrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,iBAAiB,EAAE,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,iBAAiB,EAAE,CASrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,iBAAiB,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAGhG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,iBAAiB,EAAE,EAC9B,OAAO,EAAE,MAAM,GACd,iBAAiB,EAAE,CAErB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAYjG;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAW/F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,iBAAiB,EAAE,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,iBAAiB,EAAE,CAUrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAY/F"}

package/dist/src/utils/precision-math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precision-math.d.ts","sourceRoot":"","sources":["../../../src/utils/precision-math.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,OAAO,GAChB,MAAM,CA6BR;AAkFD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcpD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAuBrD"}

package/dist/{utils → src/utils}/query-params.d.ts

@@ -60,7 +60,7 @@ export interface QueryParamConfig<T> {
  * // Result: { userAddress: 'eth|123', amount: '100' }
  * ```
  */
-export declare function buildBackendQueryParams<T extends Record<string, any>>(options: T, config?: QueryParamConfig<T>): Record<string, any>;
+export declare function buildBackendQueryParams<T extends Record<string, any>>(options: T, config?: QueryParamConfig<T>): Record<string, unknown>;
 /**
  * Builds pagination query parameters (common pattern)
  *
@@ -94,5 +94,5 @@ export declare function buildPaginationParams(page: number, limit: number): Reco
  * // Result: { tokenName: 'mytoken', page: '1', limit: '10' }
  * ```
  */
-export declare function buildTokenQueryParams(tokenName: string, page: number, limit: number): Record<string, any>;
+export declare function buildTokenQueryParams(tokenName: string, page: number, limit: number): Record<string, unknown>;
 //# sourceMappingURL=query-params.d.ts.map

package/dist/src/utils/query-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-params.d.ts","sourceRoot":"","sources":["../../../src/utils/query-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,iDAAiD;IACjD,eAAe,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;IAC9B,wDAAwD;IACxD,cAAc,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;IAC7B,qDAAqD;IACrD,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACnE,OAAO,EAAE,CAAC,EACV,MAAM,GAAE,gBAAgB,CAAC,CAAC,CAAM,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyCzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB"}

package/dist/src/utils/response-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-handlers.d.ts","sourceRoot":"","sources":["../../../src/utils/response-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,UAAU,eAAe,CAAC,CAAC,GAAG,OAAO;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;CACV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EAC/C,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,EAC5B,mBAAmB,EAAE,MAAM,EAC3B,WAAW,GAAE,OAAe,GAC3B,IAAI,CAQN"}

package/dist/src/utils/response-normalizers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-normalizers.d.ts","sourceRoot":"","sources":["../../../src/utils/response-normalizers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,EAAE,CAiC9F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,EAAE,CAGjG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,EAAE,CAG7G;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxC;IACD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CASA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB;IACD,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB,CAKA"}

package/dist/src/utils/slippage-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slippage-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/slippage-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,WAAW,GAAG,YAAY,GAAG,aAAa,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,MAAM,EACtB,uBAAuB,EAAE,MAAM,EAC/B,aAAa,EAAE,qBAAqB,GACnC,MAAM,CAuDR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,GACrB,MAAM,CAYR"}