@gala-chain/launchpad-sdk 5.0.4-beta.6 → 5.0.4-beta.60

package/dist/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 type { Pool } from '@gala-chain/dex';
+import type BigNumber from 'bignumber.js';
+import type { CompositePoolDataResult } from '../types/composite-pool.dto';
+import type { PoolStateValidationResult, SwapEventData } from '../types/pool-state-delta.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/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,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,SAAS,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAC3E,OAAO,KAAK,EACV,yBAAyB,EACzB,aAAa,EACd,MAAM,+BAA+B,CAAC;AAMvC;;;;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;IAqHV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,MAAM,CAAC,kBAAkB,CACvB,WAAW,EAAE,IAAI,EACjB,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,yBAA6D,GACpE,yBAAyB;IA4E5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;WACU,cAAc,CACzB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,uBAAuB,EACvC,OAAO,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,GAC9C,OAAO,CAAC,yBAAyB,CAAC;IA4ErC;;;;;;;;;;;;;;;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/utils/position-filters.d.ts

@@ -0,0 +1,252 @@
+/**
+ * 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 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): 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/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,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAK5D;;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,GAC5B,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,CAIhG;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,CAKjG;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAE/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,CAK/F"}

package/dist/utils/primitives.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Primitive Type Guards and Constants
+ *
+ * Ultra-lightweight utilities with ZERO dependencies.
+ * Used to break circular dependency chains in the SDK.
+ *
+ * These are the foundational building blocks for all validation logic.
+ * They intentionally have no imports from other utility modules.
+ *
+ * @category Utilities
+ * @since 3.6.3
+ */
+/**
+ * Type guard to check if a value is a non-empty string
+ *
+ * @param value - Value to check
+ * @returns True if value is a string with non-whitespace content
+ *
+ * @example
+ * ```typescript
+ * isNonEmptyString('hello');     // true
+ * isNonEmptyString('  ');        // false (only whitespace)
+ * isNonEmptyString('');          // false (empty)
+ * isNonEmptyString(null);        // false
+ * isNonEmptyString(undefined);   // false
+ * ```
+ */
+export declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Type guard to check if a value is empty (null, undefined, or empty string)
+ *
+ * @param value - Value to check
+ * @returns True if value is null, undefined, or empty string
+ *
+ * @example
+ * ```typescript
+ * isEmptyValue(null);        // true
+ * isEmptyValue(undefined);   // true
+ * isEmptyValue('');          // true
+ * isEmptyValue('text');      // false
+ * isEmptyValue(0);           // false
+ * isEmptyValue(false);       // false
+ * ```
+ */
+export declare function isEmptyValue(value: unknown): value is null | undefined | '';
+/**
+ * Type guard to check if a value is null or undefined
+ *
+ * @param value - Value to check
+ * @returns True if value is null or undefined
+ *
+ * @example
+ * ```typescript
+ * isNullish(null);        // true
+ * isNullish(undefined);   // true
+ * isNullish('');          // false (empty string is not nullish)
+ * isNullish(0);           // false
+ * isNullish(false);       // false
+ * ```
+ */
+export declare function isNullish(value: unknown): value is null | undefined;
+/**
+ * Address format patterns - centralized regex for address validation
+ *
+ * Single source of truth for address validation across the SDK.
+ * These patterns support Ethereum and GalaChain backend address formats.
+ */
+export declare const ADDRESS_PATTERNS: {
+    /** Ethereum address format: 0x followed by 40 hexadecimal characters */
+    readonly ETH_ADDRESS: RegExp;
+    /** Backend address format: eth| followed by optional 0x and 40 hexadecimal characters */
+    readonly BACKEND_ADDRESS: RegExp;
+    /** Client address format: client| followed by alphanumeric characters, hyphens, underscores (variable length) */
+    readonly CLIENT_ADDRESS: RegExp;
+};
+//# sourceMappingURL=primitives.d.ts.map

package/dist/utils/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/utils/primitives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,SAAS,GAAG,EAAE,CAE3E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,SAAS,CAEnE;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;IAC3B,wEAAwE;;IAExE,yFAAyF;;IAEzF,iHAAiH;;CAEzG,CAAC"}

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

@@ -0,0 +1,89 @@
+/**
+ * Query Parameter Building Utilities
+ *
+ * Unified utilities for building backend query parameters.
+ * Replaces multiple duplicate query building methods with a single,
+ * type-safe, reusable utility.
+ *
+ * @category Utilities
+ * @since 3.6.0
+ */
+/**
+ * Configuration for field transformations
+ */
+export interface QueryParamConfig<T> {
+    /** Fields that should be converted to strings */
+    stringifyFields?: (keyof T)[];
+    /** Fields that should be excluded if undefined/empty */
+    optionalFields?: (keyof T)[];
+    /** Custom field name mappings (source -> backend) */
+    fieldMappings?: Partial<Record<keyof T, string>>;
+}
+/**
+ * Builds backend query parameters from typed options object
+ *
+ * This utility consolidates the logic from multiple query building methods:
+ * - buildTradeQueryParams
+ * - buildTokenListQueryParams
+ * - buildTokenHoldQueryParams
+ *
+ * @template T The type of the input options object
+ * @param options Input options to convert to query parameters
+ * @param config Configuration for field transformations
+ * @returns Query parameters ready for backend API
+ *
+ * @example
+ * ```typescript
+ * // Simple pagination
+ * const params = buildBackendQueryParams(
+ *   { page: 1, limit: 10 },
+ *   { stringifyFields: ['page', 'limit'] }
+ * );
+ * // Result: { page: '1', limit: '10' }
+ *
+ * // With optional fields
+ * const params = buildBackendQueryParams(
+ *   { page: 1, limit: 10, search: 'test', tokenName: undefined },
+ *   {
+ *     stringifyFields: ['page', 'limit'],
+ *     optionalFields: ['search', 'tokenName']
+ *   }
+ * );
+ * // Result: { page: '1', limit: '10', search: 'test' }
+ *
+ * // With field mappings
+ * const params = buildBackendQueryParams(
+ *   { walletAddress: 'eth|123', amount: '100' },
+ *   { fieldMappings: { walletAddress: 'userAddress' } }
+ * );
+ * // Result: { userAddress: 'eth|123', amount: '100' }
+ * ```
+ */
+export declare function buildBackendQueryParams<T extends Record<string, unknown>>(options: T, config?: QueryParamConfig<T>): Record<string, unknown>;
+/**
+ * Builds token query parameters with pagination
+ *
+ * Common pattern for token-related endpoints that support
+ * pagination plus optional filters.
+ *
+ * Converts offset-based pagination to page-based pagination for backend API.
+ * Formula: page = Math.floor(offset / limit) + 1
+ *
+ * @param tokenName Token name to query
+ * @param offset Offset for pagination (0-indexed: 0, 20, 40, etc.)
+ * @param limit Items per page
+ * @returns Query parameters ready for backend API with page-based pagination
+ *
+ * @example
+ * ```typescript
+ * // Get first page (offset 0 with limit 10)
+ * const params = buildTokenQueryParams('mytoken', 0, 10);
+ * // Result: { tokenName: 'mytoken', page: '1', pageSize: '10' }
+ *
+ * // Get second page (offset 20 with limit 10 → page = floor(20/10) + 1 = 3)
+ * const params = buildTokenQueryParams('mytoken', 20, 10);
+ * // Result: { tokenName: 'mytoken', page: '3', pageSize: '10' }
+ * ```
+ */
+export declare function buildTokenQueryParams(tokenName: string, offset: number, limit: number): Record<string, unknown>;
+//# sourceMappingURL=query-params.d.ts.map

package/dist/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;AAKH;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvE,OAAO,EAAE,CAAC,EACV,MAAM,GAAE,gBAAgB,CAAC,CAAC,CAAM,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuCzB;AAGD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB"}