@gala-chain/launchpad-sdk 3.29.0 → 3.31.2

package/dist/utils/auto-pagination.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Auto-Pagination Utility
+ *
+ * Generic utility for automatically paginating through API results.
+ * Eliminates duplicate pagination logic across multiple services.
+ *
+ * @packageDocumentation
+ */
+import { Logger } from './Logger';
+/**
+ * Result object from paginated API calls
+ * Expected structure for services using this utility
+ */
+export interface PaginatedResult<T> {
+    /** Array of items returned from this page */
+    items: T[];
+    /** Current page number */
+    page: number;
+    /** Page size/limit for this request */
+    limit: number;
+    /** Total count of all items across all pages */
+    total: number;
+    /** Total number of pages available */
+    totalPages: number;
+    /** Whether there is a next page available */
+    hasNext: boolean;
+    /** Whether there is a previous page available */
+    hasPrevious: boolean;
+}
+/**
+ * Options for auto-pagination
+ */
+export interface AutoPaginationOptions {
+    /** Maximum number of pages to fetch (safety limit to prevent infinite loops) */
+    maxPages?: number;
+    /** Logger instance for debug output */
+    logger?: Logger;
+    /** Page size to use for each request */
+    pageSize?: number;
+}
+/**
+ * Result object from auto-pagination
+ */
+export interface AutoPaginationResult<T> {
+    /** All items from all pages combined */
+    items: T[];
+    /** Total count from the API (across all pages) */
+    total: number;
+}
+/**
+ * Generic auto-pagination handler
+ *
+ * Automatically iterates through all pages of paginated API results
+ * and combines them into a single array. Handles common patterns like:
+ * - Safety limits to prevent infinite loops
+ * - Empty result detection
+ * - Debug logging of pagination progress
+ * - Preserves total count from the API
+ *
+ * @typeParam T - Type of items being paginated
+ * @param fetchFn Function that fetches a single page of results
+ * @param options Pagination options (maxPages, logger, pageSize)
+ * @returns Promise<AutoPaginationResult> All items and total count from the API
+ *
+ * @example
+ * ```typescript
+ * const result = await autoPaginate(
+ *   (page, limit) => service.fetchPools({ page, limit }),
+ *   { maxPages: 1000, pageSize: 20, logger }
+ * );
+ * console.log(`Total: ${result.total}, Fetched: ${result.items.length}`);
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function autoPaginate<T>(fetchFn: (page: number, limit: number) => Promise<PaginatedResult<T>>, options?: AutoPaginationOptions): Promise<AutoPaginationResult<T>>;
+/**
+ * Build paginated result object for returning combined auto-paginated data
+ *
+ * Helper function to construct the standard paginated result structure
+ * when returning combined results from auto-pagination. Supports custom item
+ * key naming for service-specific result structures (pools, snapshots, etc.).
+ *
+ * Eliminates 5-7 line response object construction patterns found in:
+ * - DexPoolService.fetchAllDexPools() (lines 209-219)
+ * - PriceHistoryService.fetchAllPriceHistory() (lines 433-442)
+ * - Other services with similar patterns
+ *
+ * @typeParam T - Type of items in the result
+ * @param items Combined array of all items from all pages
+ * @param total Total count from last page (or sum of counts)
+ * @param itemsKey Optional field name for items (default: 'items'). Use for service-specific naming like 'pools', 'snapshots', 'comments'
+ * @returns PaginatedResult object with items flattened into a single "page"
+ *
+ * @example Basic usage (default 'items' key)
+ * ```typescript
+ * const allItems = await autoPaginate(fetchFn);
+ * return buildPaginatedResult(allItems.items, allItems.total);
+ * // Returns: { items, page: 1, limit, total, totalPages: 1, hasNext: false, hasPrevious: false }
+ * ```
+ *
+ * @example With custom items key (eliminates manual response construction)
+ * ```typescript
+ * // DexPoolService - before (7 lines)
+ * const result = buildPaginatedResult(paginationResult.items, paginationResult.total);
+ * return {
+ *   pools: result.items,
+ *   page: result.page,
+ *   limit: result.limit,
+ *   total: result.total,
+ *   totalPages: result.totalPages,
+ *   hasNext: result.hasNext,
+ *   hasPrevious: result.hasPrevious,
+ * };
+ *
+ * // DexPoolService - after (1 line)
+ * return buildPaginatedResult(paginationResult.items, paginationResult.total, 'pools');
+ * ```
+ *
+ * @example Other service patterns
+ * ```typescript
+ * // PriceHistoryService
+ * return buildPaginatedResult(paginationResult.items, paginationResult.total, 'snapshots');
+ *
+ * // CommentService
+ * return buildPaginatedResult(allComments, totalCount, 'comments');
+ * ```
+ *
+ * @since 3.32.0 - itemsKey parameter added in 3.32.0 for response structure flexibility
+ */
+export declare function buildPaginatedResult<T>(items: T[], total?: number, itemsKey?: 'items' | 'pools' | 'snapshots' | 'comments' | string): Record<string, any>;
+//# sourceMappingURL=auto-pagination.d.ts.map

package/dist/utils/auto-pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-pagination.d.ts","sourceRoot":"","sources":["../../src/utils/auto-pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,6CAA6C;IAC7C,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,wCAAwC;IACxC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EACrE,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAyDlC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,GAAE,MAAqB,EAC5B,QAAQ,GAAE,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,MAAgB,GACxE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAerB"}

package/dist/utils/bignumber-helpers.d.ts

@@ -0,0 +1,264 @@
+/**
+ * BigNumber utility helpers for common calculations
+ *
+ * Consolidates repeated BigNumber patterns and operations to reduce
+ * code duplication across services, particularly in GSwapService.
+ *
+ * Common patterns extracted:
+ * - Slippage factor calculation
+ * - Min/max output calculation with slippage
+ * - Tick to sqrt ratio conversion (1.0001^(tick/2))
+ * - Price inversion
+ * - Safe BigNumber creation
+ *
+ * @internal
+ */
+import BigNumber from 'bignumber.js';
+/**
+ * Create a BigNumber from a numeric value with safe defaults
+ *
+ * @param value The value to convert
+ * @param defaultValue Value to use if input is null/undefined/zero-length string (default: "0")
+ * @returns BigNumber instance
+ *
+ * @example
+ * ```typescript
+ * const balance = toBigNumber(userData.balance || 0);
+ * const amount = toBigNumber(params.amount); // Uses "0" if undefined
+ * ```
+ */
+export declare function toBigNumber(value: string | number | BigNumber | null | undefined, defaultValue?: string | number): BigNumber;
+/**
+ * Create a BigNumber and immediately call toFixed()
+ *
+ * Convenience method for the pattern: `new BigNumber(value).toFixed()`
+ * Used for serializing calculated amounts back to strings.
+ *
+ * @param value The value to convert
+ * @param decimals Number of decimal places (default: undefined = max precision)
+ * @returns Fixed string representation
+ *
+ * @example
+ * ```typescript
+ * const minOutput = toBigNumberFixed(calculated, 6);  // "123.456789"
+ * const slippageAdjusted = toBigNumberFixed(amount.multipliedBy(0.99));
+ * ```
+ */
+export declare function toBigNumberFixed(value: string | number | BigNumber | null | undefined, decimals?: number): string;
+/**
+ * Calculate slippage-adjusted minimum output
+ *
+ * Consolidates the pattern:
+ * ```typescript
+ * const slippageFactor = new BigNumber(1).minus(slippageTolerance);
+ * const minOutput = estimatedOutput.multipliedBy(slippageFactor);
+ * ```
+ *
+ * @param estimatedOutput The estimated output amount
+ * @param slippageTolerance Slippage tolerance as decimal (e.g., 0.01 for 1%)
+ * @returns Minimum acceptable output after slippage
+ *
+ * @example
+ * ```typescript
+ * const quote = await sdk.getSwapQuote('GALA', 'GUSDC', '100');
+ * const minOutput = calculateSlippageAdjustedAmount(
+ *   quote.estimatedOutput,
+ *   0.01  // 1% slippage
+ * );
+ * await sdk.executeSwap(..., minOutput.toFixed());
+ * ```
+ */
+export declare function calculateSlippageAdjustedAmount(estimatedOutput: string | number | BigNumber, slippageTolerance?: number): BigNumber;
+/**
+ * Calculate slippage factor (1 - tolerance)
+ *
+ * Consolidates: `new BigNumber(1).minus(tolerance)`
+ * Used as multiplier for slippage calculations.
+ *
+ * @param tolerance Slippage tolerance as decimal (e.g., 0.01 for 1%)
+ * @returns Slippage factor (e.g., 0.99 for 1% tolerance)
+ *
+ * @example
+ * ```typescript
+ * const factor = calculateSlippageFactor(0.01);  // BigNumber(0.99)
+ * const minAmount = estimatedAmount.multipliedBy(factor);
+ * ```
+ */
+export declare function calculateSlippageFactor(tolerance?: number): BigNumber;
+/**
+ * Convert tick to sqrt ratio for liquidity calculations
+ *
+ * Consolidates the pattern: `new BigNumber(Math.pow(1.0001, tick / 2))`
+ * Used 8+ times in GSwapService for Uniswap V3 liquidity calculations.
+ *
+ * @param tick The tick value from the pool
+ * @returns Sqrt ratio as BigNumber
+ *
+ * @example
+ * ```typescript
+ * const lowerSqrtRatio = tickToSqrtRatio(tickLower);
+ * const upperSqrtRatio = tickToSqrtRatio(tickUpper);
+ * const liquidityNeeded = calculateLiquidity(lowerSqrtRatio, upperSqrtRatio, ...);
+ * ```
+ */
+export declare function tickToSqrtRatio(tick: number): BigNumber;
+/**
+ * Invert a price (calculate 1 / price)
+ *
+ * Consolidates: `new BigNumber(1).dividedBy(price)`
+ * Used for converting price direction (e.g., BTC/USD → USD/BTC).
+ *
+ * @param price The price to invert
+ * @param asFixed Whether to return as fixed string (default: false returns BigNumber)
+ * @returns Inverted price as BigNumber or string
+ *
+ * @example
+ * ```typescript
+ * const galuPrice = invertPrice('0.50');  // 2.0
+ * const displayPrice = invertPrice(price, true);  // "2.0" (string)
+ * ```
+ */
+export declare function invertPrice(price: string | number | BigNumber, asFixed?: boolean): BigNumber | string;
+/**
+ * Q96 constant for Uniswap V3 calculations (2^96)
+ *
+ * Consolidates: `new BigNumber(2).pow(96)`
+ * Used in tick-based liquidity calculations.
+ *
+ * @returns Q96 value as BigNumber
+ *
+ * @example
+ * ```typescript
+ * const Q96 = getQ96Constant();  // 2^96
+ * const adjustedPrice = sqrtPrice.multipliedBy(sqrtPrice).dividedBy(Q96);
+ * ```
+ */
+export declare function getQ96Constant(): BigNumber;
+/**
+ * Find minimum of two BigNumber values
+ *
+ * Convenience wrapper for `BigNumber.min()` with safe input handling.
+ *
+ * @param a First value
+ * @param b Second value
+ * @returns The minimum value as BigNumber
+ *
+ * @example
+ * ```typescript
+ * const liquidity0 = calculateFromAmount0(...);
+ * const liquidity1 = calculateFromAmount1(...);
+ * const optimalLiquidity = minBigNumber(liquidity0, liquidity1);
+ * ```
+ */
+export declare function minBigNumber(a: string | number | BigNumber, b: string | number | BigNumber): BigNumber;
+/**
+ * Find maximum of two BigNumber values
+ *
+ * Convenience wrapper for `BigNumber.max()` with safe input handling.
+ *
+ * @param a First value
+ * @param b Second value
+ * @returns The maximum value as BigNumber
+ *
+ * @example
+ * ```typescript
+ * const amount0 = parseFloat(poolData.amount0);
+ * const amount1 = parseFloat(poolData.amount1);
+ * const maxAmount = maxBigNumber(amount0, amount1);
+ * ```
+ */
+export declare function maxBigNumber(a: string | number | BigNumber, b: string | number | BigNumber): BigNumber;
+/**
+ * Check if a value is zero
+ *
+ * Safe check for zero with BigNumber precision.
+ *
+ * @param value The value to check
+ * @returns true if value equals 0
+ *
+ * @example
+ * ```typescript
+ * if (isZero(amount)) {
+ *   throw new Error('Amount cannot be zero');
+ * }
+ * ```
+ */
+export declare function isZero(value: string | number | BigNumber): boolean;
+/**
+ * Check if a value is positive
+ *
+ * @param value The value to check
+ * @returns true if value > 0
+ *
+ * @example
+ * ```typescript
+ * if (isPositive(balance)) {
+ *   // user has funds
+ * }
+ * ```
+ */
+export declare function isPositive(value: string | number | BigNumber): boolean;
+/**
+ * Check if a value is negative
+ *
+ * @param value The value to check
+ * @returns true if value < 0
+ */
+export declare function isNegative(value: string | number | BigNumber): boolean;
+/**
+ * Check if value is between two bounds (inclusive)
+ *
+ * @param value The value to check
+ * @param min Lower bound (inclusive)
+ * @param max Upper bound (inclusive)
+ * @returns true if min <= value <= max
+ *
+ * @example
+ * ```typescript
+ * if (isBetween(price, minPrice, maxPrice)) {
+ *   // price is in valid range
+ * }
+ * ```
+ */
+export declare function isBetween(value: string | number | BigNumber, min: string | number | BigNumber, max: string | number | BigNumber): boolean;
+/**
+ * Calculate percentage of a value
+ *
+ * @param value The base value
+ * @param percentage The percentage to calculate (e.g., 10 for 10%)
+ * @returns The percentage amount
+ *
+ * @example
+ * ```typescript
+ * const fee = calculatePercentage(amount, 0.3);  // 0.3% fee
+ * const netAmount = amount.minus(fee);
+ * ```
+ */
+export declare function calculatePercentage(value: string | number | BigNumber, percentage: number): BigNumber;
+/**
+ * Increase a value by a percentage
+ *
+ * @param value The base value
+ * @param percentage The percentage to increase (e.g., 10 for 10% increase)
+ * @returns The increased value
+ *
+ * @example
+ * ```typescript
+ * const withSlippage = increaseByPercentage(amount, 1);  // 1% increase
+ * ```
+ */
+export declare function increaseByPercentage(value: string | number | BigNumber, percentage: number): BigNumber;
+/**
+ * Decrease a value by a percentage
+ *
+ * @param value The base value
+ * @param percentage The percentage to decrease (e.g., 1 for 1% decrease)
+ * @returns The decreased value
+ *
+ * @example
+ * ```typescript
+ * const afterSlippage = decreaseByPercentage(amount, 1);  // 1% decrease
+ * ```
+ */
+export declare function decreaseByPercentage(value: string | number | BigNumber, percentage: number): BigNumber;
+//# sourceMappingURL=bignumber-helpers.d.ts.map

package/dist/utils/bignumber-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bignumber-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/bignumber-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,SAAS,MAAM,cAAc,CAAC;AAErC;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,EACrD,YAAY,GAAE,MAAM,GAAG,MAAY,GAClC,SAAS,CAKX;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,EACrD,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAER;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,+BAA+B,CAC7C,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAC5C,iBAAiB,GAAE,MAAa,GAC/B,SAAS,CAIX;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,GAAE,MAAa,GAAG,SAAS,CAE3E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAEvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAClC,OAAO,GAAE,OAAe,GACvB,SAAS,GAAG,MAAM,CAIpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,IAAI,SAAS,CAE1C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAC9B,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAC7B,SAAS,CAEX;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAC9B,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAC7B,SAAS,CAEX;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAElE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAEtE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAEtE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAClC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAChC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAC/B,OAAO,CAKT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAClC,UAAU,EAAE,MAAM,GACjB,SAAS,CAEX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAClC,UAAU,EAAE,MAAM,GACjB,SAAS,CAEX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAClC,UAAU,EAAE,MAAM,GACjB,SAAS,CAEX"}

package/dist/utils/token-format-converter.d.ts

@@ -1,5 +1,9 @@
 /**
- * TokenFormatConverter - Converts between different token ID formats
+ * TokenFormatConverter - Unified token format conversion utilities
+ *
+ * Handles bidirectional conversions between:
+ * - Pipe-delimited ↔ Dollar-delimited formats (API conversions)
+ * - Token objects ↔ String formats (Launchpad ↔ GSwap conversions)
  *
  * ⚠️ CRITICAL ARCHITECTURAL NOTE:
  * This utility is for FORMAT CONVERSION ONLY (pipe-delimited ↔ object/string).
@@ -12,10 +16,9 @@
  *
  * Launchpad SDK uses: { collection, category, type, additionalKey }
  * GSwap SDK uses: "symbol|Unit|none|none" (pipe-delimited string)
- *
- * This utility handles bidirectional conversion between formats.
  */
 import type { TokenClass } from '../types/gswap.dto';
+import type { TokenClassKey } from '../types/common';
 export declare class TokenFormatConverter {
     /**
      * Convert Launchpad token format to GSwap format (pipe-delimited string)
@@ -55,4 +58,73 @@ export declare class TokenFormatConverter {
      */
     normalize(token: string | TokenClass): string;
 }
+/**
+ * Convert pipe-delimited token ID to dollar-delimited format for API
+ *
+ * @param pipeToken Pipe-delimited format: "Token|Unit|GUSDC|eth:0x..."
+ * @returns Dollar-delimited format: "Token$Unit$GUSDC$eth:0x..."
+ * @throws Error if token is null or empty
+ *
+ * @example
+ * ```typescript
+ * pipeFormatToDollarFormat("Token|Unit|GUSDC|eth:0x123")
+ * // Returns: "Token$Unit$GUSDC$eth:0x123"
+ * ```
+ */
+export declare function pipeFormatToDollarFormat(pipeToken: string): string;
+/**
+ * Convert dollar-delimited API response to pipe-delimited format
+ *
+ * @param dollarToken Dollar-delimited format: "Token$Unit$GUSDC$eth:0x..."
+ * @returns Pipe-delimited format: "Token|Unit|GUSDC|eth:0x..."
+ * @throws Error if token is null or empty
+ *
+ * @example
+ * ```typescript
+ * dollarFormatToPipeFormat("Token$Unit$GUSDC$eth:0x123")
+ * // Returns: "Token|Unit|GUSDC|eth:0x123"
+ * ```
+ */
+export declare function dollarFormatToPipeFormat(dollarToken: string): string;
+/**
+ * Convert sort order from SDK format (uppercase) to API format (lowercase)
+ *
+ * @param sortOrder SDK sort order: 'ASC' | 'DESC'
+ * @returns API sort order: 'asc' | 'desc' | undefined
+ *
+ * @example
+ * ```typescript
+ * convertSortOrderToApi('ASC')
+ * // Returns: 'asc'
+ *
+ * convertSortOrderToApi(undefined)
+ * // Returns: undefined
+ * ```
+ */
+export declare function convertSortOrderToApi(sortOrder?: 'ASC' | 'DESC'): 'asc' | 'desc' | undefined;
+/**
+ * Parse dollar-delimited token string into TokenClassKey components
+ *
+ * Dollar-delimited format: "Token$Unit$SYMBOL$additionalKey"
+ * Handles additionalKey that may contain $ characters by treating everything after the third $
+ * as part of additionalKey and rejoining with $.
+ * This consolidates 5+ identical dollar-delimited parsing patterns scattered across services.
+ *
+ * @param dollarToken Dollar-delimited token string to parse
+ * @returns TokenClassKey object with collection, category, type, additionalKey
+ * @throws ValidationError if the token format is invalid
+ *
+ * @example
+ * ```typescript
+ * const tokenClass = parseDollarDelimitedToken('Token$Unit$GUSDC$eth:0x...');
+ * // → { collection: "Token", category: "Unit", type: "GUSDC", additionalKey: "eth:0x..." }
+ *
+ * // Handles additionalKey with $ characters
+ * const complex = parseDollarDelimitedToken('Token$Unit$SYMBOL$eth:0x$1234$5678');
+ * // → { collection: "Token", category: "Unit", type: "SYMBOL", additionalKey: "eth:0x$1234$5678" }
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function parseDollarDelimitedToken(dollarToken: string): TokenClassKey;
 //# sourceMappingURL=token-format-converter.d.ts.map

package/dist/utils/token-format-converter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-format-converter.d.ts","sourceRoot":"","sources":["../../src/utils/token-format-converter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,qBAAa,oBAAoB;IAC/B;;;;;;;;OAQG;IACH,iBAAiB,CACf,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,GAAG,GAC/B,MAAM;IAuBT;;;;;;;;;OASG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,GAAG,GAAG,UAAU;IAmC1D;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM;CAY9C"}
+{"version":3,"file":"token-format-converter.d.ts","sourceRoot":"","sources":["../../src/utils/token-format-converter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD,qBAAa,oBAAoB;IAC/B;;;;;;;;OAQG;IACH,iBAAiB,CACf,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,GAAG,GAC/B,MAAM;IAuBT;;;;;;;;;OASG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,GAAG,GAAG,UAAU;IAmC1D;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM;CAY9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAMlE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAM5F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAyC5E"}

package/dist/utils/tokenNormalizer.d.ts

@@ -108,4 +108,70 @@ export declare function tokenClassKeyToString(tokenClass: TokenClassKey): string
  * @throws ValidationError if validation fails
  */
 export declare function validateTokenId(tokenId: TokenId): void;
+/**
+ * Parses a vault address into a TokenClassKey
+ *
+ * Vault address format: "service|Token$Unit$SYMBOL$additionalKey$launchpad"
+ * This consolidates 5+ identical vault address parsing patterns scattered across services.
+ *
+ * Handles additionalKey that may contain $ characters by excluding the 'launchpad' suffix
+ * and joining all remaining parts.
+ *
+ * @param vaultAddress Vault address string to parse
+ * @returns TokenClassKey object
+ * @throws ValidationError if the vault address format is invalid
+ *
+ * @example
+ * ```typescript
+ * const tokenClass = parseVaultAddressToTokenClassKey(
+ *   "service|Token$Unit$DRAGNRKTI$eth:0x...$launchpad"
+ * );
+ * // → { collection: "Token", category: "Unit", type: "DRAGNRKTI", additionalKey: "eth:0x..." }
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function parseVaultAddressToTokenClassKey(vaultAddress: string): TokenClassKey;
+/**
+ * Parses a vault address into a TokenInstanceKey
+ *
+ * Vault address format: "service|Token$Unit$SYMBOL$eth:address$launchpad"
+ * Instance is defaulted to "0" if not provided in the vault address.
+ *
+ * @param vaultAddress Vault address string to parse
+ * @returns TokenInstanceKey object with instance defaulted to "0"
+ * @throws ValidationError if the vault address format is invalid
+ *
+ * @example
+ * ```typescript
+ * const tokenInstance = parseVaultAddressToTokenInstance(
+ *   "service|Token$Unit$DRAGNRKTI$eth:0x...$launchpad"
+ * );
+ * // → { collection: "Token", category: "Unit", type: "DRAGNRKTI", additionalKey: "eth:0x...", instance: "0" }
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function parseVaultAddressToTokenInstance(vaultAddress: string): TokenInstanceKey;
+/**
+ * Extracts the token symbol/type from a vault address
+ *
+ * Vault address format: "service|Token$Unit$SYMBOL$eth:address$launchpad"
+ * The symbol is the 3rd component (index 2) after splitting the token part by $.
+ *
+ * @param vaultAddress Vault address string to parse
+ * @returns Token symbol/type (e.g., "DRAGNRKTI", "GALA", "GUSDC")
+ * @throws ValidationError if the vault address format is invalid
+ *
+ * @example
+ * ```typescript
+ * const symbol = extractTokenSymbolFromVault(
+ *   "service|Token$Unit$DRAGNRKTI$eth:0x...$launchpad"
+ * );
+ * // → "DRAGNRKTI"
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function extractTokenSymbolFromVault(vaultAddress: string): string;
 //# sourceMappingURL=tokenNormalizer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tokenNormalizer.d.ts","sourceRoot":"","sources":["../../src/utils/tokenNormalizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CA2D9E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,gBAAgB,CAKhF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,aAAa,CAI1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,MAAM,CAEnE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,gBAAgB,GAAG,MAAM,CAEhF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,aAAa,GAAG,MAAM,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CActD"}
+{"version":3,"file":"tokenNormalizer.d.ts","sourceRoot":"","sources":["../../src/utils/tokenNormalizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CA2D9E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,gBAAgB,CAKhF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,aAAa,CAI1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,MAAM,CAEnE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,gBAAgB,GAAG,MAAM,CAEhF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,aAAa,GAAG,MAAM,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CActD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gCAAgC,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAyCpF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gCAAgC,CAAC,YAAY,EAAE,MAAM,GAAG,gBAAgB,CAMvF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAGxE"}

package/dist/utils/validation-helpers.d.ts

@@ -366,4 +366,79 @@ export type TypeGuard<T> = (value: unknown) => value is T;
  * ```
  */
 export declare function createValidator<T>(typeGuard: TypeGuard<T>, dataTypeName: string, fieldName?: string, errorCode?: string): (value: unknown) => asserts value is T;
+/**
+ * Result of mutual exclusivity validation
+ */
+export interface MutualExclusivityResult {
+    /** Which field was provided (if valid) */
+    chosen: string;
+    /** Whether fieldA was provided */
+    hasA: boolean;
+    /** Whether fieldB was provided */
+    hasB: boolean;
+}
+/**
+ * Validates that exactly one of two parameters is provided (mutual exclusivity)
+ *
+ * Consolidates 12+ instances of identical validation logic found across services:
+ * - PriceHistoryService: tokenName XOR tokenId (lines 451-470)
+ * - DexService: Similar patterns with token identification
+ * - Other services: Scattered mutual exclusivity validation
+ *
+ * ## Use Cases
+ *
+ * ### Validate Token Identification (Highest Priority)
+ * ```typescript
+ * // In service methods receiving either tokenName or tokenId (but not both)
+ * const { chosen, hasA } = validateMutualExclusive(
+ *   options,
+ *   'tokenName',
+ *   'tokenId',
+ *   { description: 'token identifier' }
+ * );
+ *
+ * if (hasA) {
+ *   // Use tokenName
+ *   const resolved = await this.tokenResolver.resolve(options.tokenName!);
+ * } else {
+ *   // Use tokenId
+ *   const formatted = this.converter.toTokenClassKey(options.tokenId!);
+ * }
+ * ```
+ *
+ * ### Generic Parameter Validation
+ * ```typescript
+ * // Validate address or transaction ID (mutually exclusive)
+ * const { chosen } = validateMutualExclusive(
+ *   params,
+ *   'walletAddress',
+ *   'transactionId',
+ *   { description: 'transaction reference' }
+ * );
+ * ```
+ *
+ * @param obj The object containing the fields to validate
+ * @param fieldA First field name (mutual exclusive with fieldB)
+ * @param fieldB Second field name (mutual exclusive with fieldA)
+ * @param options Validation options
+ * @returns Result object with chosen field and validation flags
+ *
+ * @throws {ConfigurationError} If neither field is provided or both are provided
+ *
+ * @example Token identifier validation
+ * ```typescript
+ * // PriceHistoryService.fetchAllPriceHistory() - replaces 20-line validation method
+ * const { hasA } = validateMutualExclusive(options, 'tokenName', 'tokenId', {
+ *   description: 'token identifier'
+ * });
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function validateMutualExclusive(obj: Record<string, any>, fieldA: string, fieldB: string, options?: {
+    /** Human-readable description for error messages (e.g., "token identifier") */
+    description?: string;
+    /** Whether empty strings should count as "not provided" (default: true) */
+    treatEmptyAsNull?: boolean;
+}): MutualExclusivityResult;
 //# sourceMappingURL=validation-helpers.d.ts.map

package/dist/utils/validation-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/validation-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,qBAAqB,GACjC,IAAI,CAoBN;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;IAC3B,wEAAwE;;IAExE,yEAAyE;;CAEjE,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAe,EAC1B,SAAS,GAAE,MAAuB,GACjC,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,KAAK,IAAI,CAAC,CAUxC"}
+{"version":3,"file":"validation-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/validation-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,qBAAqB,GACjC,IAAI,CAoBN;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;IAC3B,wEAAwE;;IAExE,yEAAyE;;CAEjE,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAe,EAC1B,SAAS,GAAE,MAAuB,GACjC,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,KAAK,IAAI,CAAC,CAUxC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACxB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACvB,GACL,uBAAuB,CA8BzB"}