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

package/dist/utils/swap-delta-calculator.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Swap Delta Calculator
+ *
+ * Pure math functions that calculate how a swap affects pool state.
+ * Implements Uniswap V3 concentrated liquidity swap mechanics with tick crossing.
+ *
+ * This is a CALCULATION-ONLY utility with NO state management.
+ * All functions are pure and return new objects without mutating inputs.
+ *
+ * @packageDocumentation
+ */
+import type { Pool, TickData } from '@gala-chain/dex';
+import BigNumber from 'bignumber.js';
+import type { CompositePoolDataResult } from '../types/composite-pool.dto';
+import type { InternalSwapState, SwapDeltaResult, SwapEventData } from '../types/pool-state-delta.dto';
+/**
+ * Configuration for swap calculation behavior
+ *
+ * @category Pool State
+ */
+export interface SwapCalculationConfig {
+    /** Safety limit for maximum swap iterations (default: 100) */
+    maxIterations: number;
+    /** Use BigNumber cache for performance (default: true) */
+    enableBigNumberCache: boolean;
+    /** BigNumber rounding mode (default: ROUND_DOWN) */
+    roundingMode: BigNumber.RoundingMode;
+    /** Enable debug logging for swap calculations (default: false) */
+    debugLogging: boolean;
+}
+/**
+ * Result of the iterative swap loop calculation
+ *
+ * @internal
+ */
+interface SwapLoopResult {
+    /** Final internal state after all iterations */
+    state: InternalSwapState;
+    /** Array of tick indices that were crossed during the swap */
+    ticksCrossed: number[];
+    /** True if price reached limit before consuming all input */
+    priceHitLimit: boolean;
+    /** Number of iterations executed */
+    stepCount: number;
+    /** Updated tick data map (only changed ticks) */
+    updatedTicks: Record<string, TickData>;
+}
+/**
+ * Core swap calculation engine for applying swap deltas to pool state
+ *
+ * Implements Uniswap V3 concentrated liquidity mechanics:
+ * - Iterative swap execution across tick boundaries
+ * - Dynamic liquidity tracking as price crosses initialized ticks
+ * - Fee accumulation and protocol fee calculation
+ * - Exact input vs exact output handling
+ *
+ * @category Pool State
+ * @since 3.33.0
+ */
+export declare class SwapDeltaCalculator {
+    private static readonly logger;
+    /**
+     * Apply a single swap event to pool state
+     *
+     * Calculates new sqrtPrice, liquidity, tick, fees by simulating the swap execution.
+     * Returns complete updated state without modifying input poolData.
+     *
+     * **Performance**: 25-50ms for typical swaps (1-3 tick crossings)
+     *
+     * @param poolData Current composite pool data (not modified)
+     * @param swapEvent The swap to apply
+     * @param config Optional calculation configuration
+     * @returns Complete result with updated state and metadata
+     * @throws Error if swap calculation fails or pool data is invalid
+     *
+     * @example Simple swap calculation
+     * ```typescript
+     * const result = SwapDeltaCalculator.calculateSwapDelta(
+     *   compositePoolData,
+     *   {
+     *     transactionId: 'tx-123',
+     *     timestamp: Date.now(),
+     *     amountSpecified: '1000000000',
+     *     zeroForOne: true,
+     *     exactInput: true,
+     *   }
+     * );
+     *
+     * console.log(`New price: ${result.updatedPool.sqrtPrice}`);
+     * console.log(`Ticks crossed: ${result.ticksCrossed.length}`);
+     * console.log(`Amount0: ${result.amount0.toString()}`);
+     * console.log(`Amount1: ${result.amount1.toString()}`);
+     * ```
+     *
+     * @example With validation data
+     * ```typescript
+     * const result = SwapDeltaCalculator.calculateSwapDelta(
+     *   compositePoolData,
+     *   {
+     *     transactionId: 'tx-456',
+     *     timestamp: Date.now(),
+     *     amountSpecified: '5000000000',
+     *     zeroForOne: false,
+     *     exactInput: true,
+     *     actualAmount0: '4950000000',
+     *     actualAmount1: '-5000000000',
+     *     actualSqrtPrice: '79228162514264337593543950336',
+     *   }
+     * );
+     *
+     * if (result.metadata.driftPercentage) {
+     *   console.log(`Drift: ${result.metadata.driftPercentage.toFixed(4)}%`);
+     * }
+     * ```
+     */
+    static calculateSwapDelta(poolData: CompositePoolDataResult, swapEvent: SwapEventData, config?: Partial<SwapCalculationConfig>): SwapDeltaResult;
+    /**
+     * Initialize swap state from pool data and swap event
+     *
+     * Sets up the initial state for iterative swap calculation including:
+     * - Current price, liquidity, and tick
+     * - Amount remaining to swap
+     * - Fee growth and protocol fee accumulators
+     *
+     * @param poolData Current pool state
+     * @param swapEvent Swap event to process
+     * @param config Calculation configuration
+     * @returns Initialized swap state ready for loop execution
+     * @throws Error if pool data is invalid or inconsistent
+     *
+     * @internal
+     */
+    static initializeSwapState(poolData: CompositePoolDataResult, swapEvent: SwapEventData, config: SwapCalculationConfig): InternalSwapState;
+    /**
+     * Main iterative swap calculation loop
+     *
+     * Executes swap step-by-step, crossing tick boundaries as needed.
+     * Implements Uniswap V3 concentrated liquidity mechanics:
+     *
+     * 1. Find next initialized tick in swap direction
+     * 2. Calculate swap step to that tick boundary
+     * 3. Update state accumulators (amount, fees)
+     * 4. Handle tick crossing (liquidity changes)
+     * 5. Repeat until amount consumed or price limit reached
+     *
+     * **Performance**: 20-40ms for typical swaps (1-3 iterations)
+     *
+     * @param state Initial swap state to mutate during loop
+     * @param poolData Pool and tick data
+     * @param swapEvent Original swap information
+     * @param config Calculation configuration
+     * @returns Loop result with final state and metadata
+     * @throws Error if swap exceeds iteration limit or encounters invalid state
+     *
+     * @internal
+     */
+    static computeSwapLoop(state: InternalSwapState, poolData: CompositePoolDataResult, swapEvent: SwapEventData, config: SwapCalculationConfig): SwapLoopResult;
+    /**
+     * Create updated pool object with new state
+     *
+     * Returns a new Pool instance with updated sqrtPrice, liquidity, tick, and fees.
+     * Does NOT mutate the original pool object.
+     *
+     * @param originalPool Original pool state
+     * @param newState Updated swap state
+     * @param swapEvent Swap event that was applied
+     * @param config Calculation configuration
+     * @returns New Pool instance with updated state
+     *
+     * @internal
+     */
+    static createUpdatedPool(originalPool: Pool, newState: InternalSwapState, swapEvent: SwapEventData, _config: SwapCalculationConfig): Pool;
+    /**
+     * Calculate final token amounts from swap state
+     *
+     * Determines amount0 and amount1 based on swap direction and type (exact input vs exact output).
+     * Calculates fee amounts for each token.
+     *
+     * @param initialState State before swap
+     * @param finalState State after swap
+     * @param swapEvent Swap event details
+     * @returns Token amounts and fees (signed: negative = spent, positive = received)
+     *
+     * @internal
+     */
+    static calculateFinalAmounts(initialState: InternalSwapState, finalState: InternalSwapState, swapEvent: SwapEventData): {
+        amount0: BigNumber;
+        amount1: BigNumber;
+        feeAmount0: BigNumber;
+        feeAmount1: BigNumber;
+    };
+    /**
+     * Find next initialized tick in swap direction
+     *
+     * Scans tick data map to find the nearest initialized tick boundary.
+     * Uses pool's tick spacing to determine valid tick indices.
+     *
+     * @param tickDataMap Map of initialized ticks
+     * @param currentTick Current tick index
+     * @param tickSpacing Pool's tick spacing (e.g., 60 for 0.3% fee tier)
+     * @param zeroForOne Swap direction (true = decreasing price)
+     * @returns [nextTick, initialized] tuple
+     *
+     * @internal
+     */
+    private static findNextInitializedTick;
+    /**
+     * Execute a single swap step calculation
+     *
+     * Uses the production-ready Uniswap V3 swap math from @gala-chain/dex.
+     * Implements accurate constant-product pricing, fee calculations, and tick boundary handling.
+     *
+     * @param sqrtPriceCurrent Current sqrt price before swap
+     * @param sqrtPriceTarget Target sqrt price (next tick boundary or price limit)
+     * @param liquidity Active liquidity in current price range
+     * @param amountRemaining Tokens remaining to swap (positive value)
+     * @param feeTier Fee tier in basis points (3000 = 0.3%, 10000 = 1%)
+     * @param exactInput true=exact input amount, false=exact output amount
+     * @returns SwapStepResult with sqrtPriceNext, amountIn, amountOut, feeAmount
+     * @throws Error on invalid inputs or calculation failures
+     *
+     * @internal
+     */
+    private static executeSwapStep;
+}
+/**
+ * Default export for convenience
+ * @see {@link SwapDeltaCalculator}
+ */
+export default SwapDeltaCalculator;
+//# sourceMappingURL=swap-delta-calculator.d.ts.map

package/dist/utils/swap-delta-calculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swap-delta-calculator.d.ts","sourceRoot":"","sources":["../../src/utils/swap-delta-calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,SAAS,MAAM,cAAc,CAAC;AAErC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAC3E,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,aAAa,EAEd,MAAM,+BAA+B,CAAC;AAgBvC;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IAEtB,0DAA0D;IAC1D,oBAAoB,EAAE,OAAO,CAAC;IAE9B,oDAAoD;IACpD,YAAY,EAAE,SAAS,CAAC,YAAY,CAAC;IAErC,kEAAkE;IAClE,YAAY,EAAE,OAAO,CAAC;CACvB;AAYD;;;;GAIG;AACH,UAAU,cAAc;IACtB,gDAAgD;IAChD,KAAK,EAAE,iBAAiB,CAAC;IAEzB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB,6DAA6D;IAC7D,aAAa,EAAE,OAAO,CAAC;IAEvB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAElB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAG3B;IAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACH,MAAM,CAAC,kBAAkB,CACvB,QAAQ,EAAE,uBAAuB,EACjC,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,OAAO,CAAC,qBAAqB,CAAM,GAC1C,eAAe;IA4GlB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,mBAAmB,CACxB,QAAQ,EAAE,uBAAuB,EACjC,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,qBAAqB,GAC5B,iBAAiB;IAmEpB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,eAAe,CACpB,KAAK,EAAE,iBAAiB,EACxB,QAAQ,EAAE,uBAAuB,EACjC,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,qBAAqB,GAC5B,cAAc;IAiKjB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,iBAAiB,CACtB,YAAY,EAAE,IAAI,EAClB,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,qBAAqB,GAC7B,IAAI;IA4BP;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,qBAAqB,CAC1B,YAAY,EAAE,iBAAiB,EAC/B,UAAU,EAAE,iBAAiB,EAC7B,SAAS,EAAE,aAAa,GACvB;QACD,OAAO,EAAE,SAAS,CAAC;QACnB,OAAO,EAAE,SAAS,CAAC;QACnB,UAAU,EAAE,SAAS,CAAC;QACtB,UAAU,EAAE,SAAS,CAAC;KACvB;IAyDD;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IA0CtC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;CAqE/B;AAED;;;GAGG;AACH,eAAe,mBAAmB,CAAC"}

package/dist/utils/tick-crossing-handler.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Tick Crossing Handler
+ *
+ * Manages all tick boundary crossing logic during swap calculations.
+ * This is complex logic that reuses functions from @gala-chain/dex for:
+ * - Finding next initialized ticks in the bitmap
+ * - Applying liquidity and fee changes when crossing ticks
+ * - Validating tick ranges and boundaries
+ *
+ * @packageDocumentation
+ */
+import { TickData } from '@gala-chain/dex';
+import type BigNumber from 'bignumber.js';
+import type { TickCrossingEvent } from '../types/pool-state-delta.dto';
+/**
+ * Handler for tick boundary crossing during swaps
+ *
+ * Provides pure functions for navigating tick boundaries, applying liquidity changes,
+ * and managing tick data updates during swap calculations.
+ *
+ * @category Pool State
+ */
+export declare class TickCrossingHandler {
+    private static readonly logger;
+    /**
+     * Minimum valid tick index (-887272)
+     * Corresponds to minimum price = 1.0001^-887272
+     */
+    static readonly MIN_TICK: number;
+    /**
+     * Maximum valid tick index (887272)
+     * Corresponds to maximum price = 1.0001^887272
+     */
+    static readonly MAX_TICK: number;
+    /**
+     * Standard tick spacing for most pools
+     */
+    static readonly TICK_SPACING_STANDARD = 60;
+    /**
+     * Warning threshold for large tick crossing ranges
+     * Log warning if more than this many ticks are crossed
+     */
+    static readonly LARGE_TICK_RANGE_WARNING = 10;
+    /**
+     * Find the next initialized tick in the bitmap
+     *
+     * Uses bitmap navigation from @gala-chain/dex to efficiently locate
+     * the next tick boundary in the direction of price movement.
+     *
+     * @param bitmap - Pool's tick bitmap (map of tick index to initialization state)
+     * @param currentTick - Current tick position
+     * @param tickSpacing - Spacing between ticks (10, 60, 200, etc.)
+     * @param zeroForOne - True if moving toward negative ticks (price decreasing)
+     * @returns Tuple of [nextTick, isInitialized]
+     * @throws Error if tick is outside valid range
+     *
+     * @example
+     * ```typescript
+     * const [nextTick, initialized] = TickCrossingHandler.findNextInitializedTick(
+     *   pool.bitmap,
+     *   currentTick,
+     *   60,
+     *   true // swapping token0 for token1
+     * );
+     * ```
+     */
+    static findNextInitializedTick(bitmap: Record<string, string>, currentTick: number, tickSpacing: number, zeroForOne: boolean): [number, boolean];
+    /**
+     * Apply liquidity and fee changes when crossing a tick boundary
+     *
+     * When price crosses a tick, we need to:
+     * 1. Update the tick's fee growth outside values
+     * 2. Get the net liquidity change at this tick
+     * 3. Apply the liquidity change based on swap direction
+     *
+     * @param tickData - Tick data for the crossing tick
+     * @param feeGrowthGlobal0 - Current feeGrowthGlobal0 (for token0)
+     * @param feeGrowthGlobal1 - Current feeGrowthGlobal1 (for token1)
+     * @param zeroForOne - Direction of swap (true = selling token0)
+     * @returns liquidityNet - the net liquidity change at this tick
+     *
+     * @example
+     * ```typescript
+     * const liquidityNetChange = TickCrossingHandler.handleTickCrossing(
+     *   tickDataMap[tickNext],
+     *   state.feeGrowthGlobal0,
+     *   state.feeGrowthGlobal1,
+     *   true // swapping token0 for token1
+     * );
+     *
+     * // Apply based on direction:
+     * const newLiquidity = zeroForOne
+     *   ? state.liquidity.minus(liquidityNetChange)
+     *   : state.liquidity.plus(liquidityNetChange);
+     * ```
+     */
+    static handleTickCrossing(tickData: TickData, feeGrowthGlobal0: BigNumber, feeGrowthGlobal1: BigNumber, zeroForOne: boolean): BigNumber;
+    /**
+     * Update tick data in the map (without mutation)
+     *
+     * Creates a new tick data map with the updated tick.
+     * Does NOT mutate the original map.
+     *
+     * @param tickDataMap - Original tick map
+     * @param tick - Tick index to update
+     * @param updatedData - New tick data object
+     * @returns New map with updated tick
+     *
+     * @example
+     * ```typescript
+     * const newTickMap = TickCrossingHandler.updateTickData(
+     *   originalTickMap,
+     *   tickIndex,
+     *   updatedTickData
+     * );
+     * ```
+     */
+    static updateTickData(tickDataMap: Record<string, TickData>, tick: number, updatedData: TickData): Record<string, TickData>;
+    /**
+     * Get price boundaries for a tick
+     *
+     * Returns the sqrt price at this tick and the next tick.
+     * Useful for understanding the price range of a tick.
+     *
+     * @param tick - Tick number
+     * @returns Object with sqrtPriceLower and sqrtPriceUpper
+     *
+     * @example
+     * ```typescript
+     * const { sqrtPriceLower, sqrtPriceUpper } = TickCrossingHandler.getTickBoundaries(1000);
+     * console.log(`Price range: ${sqrtPriceLower} to ${sqrtPriceUpper}`);
+     * ```
+     */
+    static getTickBoundaries(tick: number): {
+        sqrtPriceLower: BigNumber;
+        sqrtPriceUpper: BigNumber;
+    };
+    /**
+     * Calculate which ticks are crossed during a swap
+     *
+     * Returns the range of ticks between start and end positions.
+     * Useful for analysis and logging.
+     *
+     * @param startTick - Starting tick
+     * @param endTick - Ending tick
+     * @param zeroForOne - Swap direction
+     * @returns Array of crossed ticks (sorted)
+     *
+     * @example
+     * ```typescript
+     * const crossedTicks = TickCrossingHandler.calculateTickRange(1000, 950, true);
+     * // Returns: [999, 998, 997, ..., 951, 950]
+     * ```
+     */
+    static calculateTickRange(startTick: number, endTick: number, zeroForOne: boolean): number[];
+    /**
+     * Validate tick is within valid range
+     *
+     * @param tick - Tick to validate
+     * @returns True if tick is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (!TickCrossingHandler.validateTick(tick)) {
+     *   throw new Error('Invalid tick');
+     * }
+     * ```
+     */
+    static validateTick(tick: number): boolean;
+    /**
+     * Create a tick crossing event for tracking
+     *
+     * Generates a TickCrossingEvent with complete metadata about the crossing.
+     * Useful for logging and analysis.
+     *
+     * @param tick - Tick that was crossed
+     * @param direction - Direction of crossing ('up' or 'down')
+     * @param liquidityNet - Net liquidity change at this tick
+     * @param liquidityBefore - Liquidity before crossing
+     * @param liquidityAfter - Liquidity after crossing
+     * @returns TickCrossingEvent object
+     *
+     * @example
+     * ```typescript
+     * const event = TickCrossingHandler.createTickCrossingEvent(
+     *   1000,
+     *   'down',
+     *   liquidityNet,
+     *   oldLiquidity,
+     *   newLiquidity
+     * );
+     * ticksCrossed.push(event);
+     * ```
+     */
+    static createTickCrossingEvent(tick: number, direction: 'up' | 'down', liquidityNet: BigNumber, liquidityBefore: BigNumber, liquidityAfter: BigNumber): TickCrossingEvent;
+    /**
+     * Validate bitmap structure
+     *
+     * Checks that the bitmap has the expected structure.
+     * Used for defensive validation before bitmap operations.
+     *
+     * @param bitmap - Bitmap to validate
+     * @returns True if bitmap is valid
+     *
+     * @example
+     * ```typescript
+     * if (!TickCrossingHandler.validateBitmap(pool.bitmap)) {
+     *   throw new Error('Invalid bitmap structure');
+     * }
+     * ```
+     */
+    static validateBitmap(bitmap: Record<string, string>): boolean;
+    /**
+     * Get tick data safely from map
+     *
+     * Returns tick data or undefined if not found.
+     * Logs warning if tick is expected but not found.
+     *
+     * @param tickDataMap - Tick data map
+     * @param tick - Tick to retrieve
+     * @param expectFound - Whether to log warning if not found
+     * @returns TickData or undefined
+     *
+     * @example
+     * ```typescript
+     * const tickData = TickCrossingHandler.getTickDataSafe(
+     *   tickDataMap,
+     *   tickIndex,
+     *   true // log warning if not found
+     * );
+     * ```
+     */
+    static getTickDataSafe(tickDataMap: Record<string, TickData>, tick: number, expectFound?: boolean): TickData | undefined;
+    /**
+     * Calculate performance metrics for tick crossing
+     *
+     * Estimates the expected time for crossing N ticks based on benchmarks.
+     *
+     * @param tickCount - Number of ticks to cross
+     * @returns Estimated time in milliseconds
+     *
+     * @example
+     * ```typescript
+     * const estimatedMs = TickCrossingHandler.estimateTickCrossingTime(5);
+     * console.log(`Expect ~${estimatedMs}ms for 5 tick crossings`);
+     * ```
+     */
+    static estimateTickCrossingTime(tickCount: number): number;
+}
+//# sourceMappingURL=tick-crossing-handler.d.ts.map

package/dist/utils/tick-crossing-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick-crossing-handler.d.ts","sourceRoot":"","sources":["../../src/utils/tick-crossing-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,QAAQ,EAET,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,SAAS,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAKvE;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAG3B;IAEH;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,SAAqB;IAE7C;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,SAAqB;IAE7C;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,qBAAqB,MAAM;IAE3C;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,wBAAwB,MAAM;IAE9C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,uBAAuB,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,OAAO,GAClB,CAAC,MAAM,EAAE,OAAO,CAAC;IA6CpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,MAAM,CAAC,kBAAkB,CACvB,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,SAAS,EAC3B,gBAAgB,EAAE,SAAS,EAC3B,UAAU,EAAE,OAAO,GAClB,SAAS;IAyBZ;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,cAAc,CACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EACrC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,QAAQ,GACpB,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;IAY3B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG;QACtC,cAAc,EAAE,SAAS,CAAC;QAC1B,cAAc,EAAE,SAAS,CAAC;KAC3B;IA2BD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,MAAM,EAAE;IA+B5F;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,uBAAuB,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,IAAI,GAAG,MAAM,EACxB,YAAY,EAAE,SAAS,EACvB,eAAe,EAAE,SAAS,EAC1B,cAAc,EAAE,SAAS,GACxB,iBAAiB;IAUpB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO;IAiB9D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,eAAe,CACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EACrC,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,OAAe,GAC3B,QAAQ,GAAG,SAAS;IAcvB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAa3D"}

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

@@ -0,0 +1,175 @@
+/**
+ * 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).
+ * Do NOT use for symbol extraction or metadata inference!
+ *
+ * ⚠️ BREAKING CHANGE (v5.0.0):
+ * Bare token symbols (e.g., "GALA") are NO LONGER accepted.
+ * You MUST use full tokenId format: "GALA|Unit|none|none"
+ * For launchpad bonding curve tokens, use tokenName: "anime"
+ *
+ * For symbol/metadata resolution:
+ * - Use GalaChainService.fetchTokenClassFromChain() to query real blockchain data
+ * - Use DexService.fetchTokenDetails() for complete token metadata
+ * - Use data from GSwap SDK responses directly (already contains correct symbols)
+ *
+ * Launchpad SDK uses: { collection, category, type, additionalKey }
+ * GSwap SDK uses: "GALA|Unit|none|none" (pipe-delimited string)
+ *
+ * @packageDocumentation
+ */
+import type { TokenClassKey } from '../types/common';
+import type { TokenClass } from '../types/gswap.dto';
+export declare class TokenFormatConverter {
+    /**
+     * Convert Launchpad token format to GSwap format (pipe-delimited string)
+     *
+     * ⚠️ BREAKING CHANGE (v5.0.0):
+     * Bare token symbols (e.g., "GALA") are NO LONGER accepted.
+     * You MUST use full tokenId format: "GALA|Unit|none|none"
+     *
+     * Input examples:
+     *   - "GALA|Unit|none|none" → "GALA|Unit|none|none" (valid)
+     *   - "Token|Unit|BENE|client:xxx" → "Token|Unit|BENE|client:xxx" (valid)
+     *   - { collection: "GALA", category: "Unit", type: "none", additionalKey: "none" } → "GALA|Unit|none|none" (valid)
+     *   - "GALA" → throws ValidationError (INVALID - use pipe-delimited format)
+     * Output: "GALA|Unit|none|none"
+     *
+     * @throws ValidationError if bare symbol is provided without pipe-delimited format
+     */
+    toLaunchpadFormat(token: string | TokenClass | any): string;
+    /**
+     * Convert GSwap format (pipe-delimited) to TokenClass object
+     *
+     * ⚠️ WARNING: For API format conversion ONLY
+     * This does NOT provide real symbol/metadata - it's structural only.
+     * USE parseToken() utility instead for proper token format handling (src/utils/token-parser.ts)
+     * For actual token data, use GalaChainService.fetchTokenClassFromChain()
+     *
+     * Input examples:
+     *   - "GALA|Unit|none|none" → { collection: "GALA", category: "Unit", type: "none", additionalKey: "none" }
+     *   - { type: "GALA", ... } → proper TokenClassKey
+     * Output: TokenClassKey with collection, category, type, additionalKey
+     */
+    toTokenClass(token: string | TokenClass | any): TokenClass;
+    /**
+     * INTERNAL USE ONLY: Normalize API response data that may contain bare symbols.
+     *
+     * This is specifically for normalizing data from GSwap API responses where
+     * tokens may come back as bare symbols or pipe-delimited format.
+     *
+     * ⚠️ DO NOT use this for user-facing input validation!
+     * For user input, use toLaunchpadFormat() which enforces proper format.
+     *
+     * Input: "GALA" → "GALA|Unit|none|none"
+     * Input: "GALA|Unit|none|none" → "GALA|Unit|none|none" (unchanged)
+     */
+    normalizeInternalApiResponse(token: string): string;
+    /**
+     * Normalize any token format to pipe-delimited GSwap format
+     *
+     * ⚠️ BREAKING CHANGE (v5.0.0):
+     * Bare token symbols (e.g., "GALA") are NO LONGER accepted.
+     * You MUST use full tokenId format: "GALA|Unit|none|none"
+     *
+     * Input: "GALA|Unit|none|none" or { collection: "GALA", category: "Unit", type: "none", additionalKey: "none" }
+     * Output: "GALA|Unit|none|none"
+     *
+     * @throws ValidationError if bare symbol is provided without pipe-delimited format
+     */
+    normalize(token: string | TokenClass): string;
+}
+/**
+ * Convert pipe-delimited token ID to dollar-delimited format for API
+ *
+ * @param pipeToken Pipe-delimited format: "GUSDC|Unit|none|eth:0x..."
+ * @returns Dollar-delimited format: "Token$Unit$GUSDC$eth:0x..."
+ * @throws Error if token is null or empty
+ *
+ * @example
+ * ```typescript
+ * pipeFormatToDollarFormat("GUSDC|Unit|none|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: "GUSDC|Unit|none|eth:0x..."
+ * @throws Error if token is null or empty
+ *
+ * @example
+ * ```typescript
+ * dollarFormatToPipeFormat("Token$Unit$GUSDC$eth:0x123")
+ * // Returns: "GUSDC|Unit|none|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 (LEFT-TO-RIGHT)
+ *
+ * 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 $.
+ *
+ * **WARNING:** This function parses LEFT-TO-RIGHT which does NOT handle the edge case
+ * where the collection name contains $ (e.g., "$MUSIC$Unit$none$none").
+ * For tokens that may have $ in the collection, use `parseDollarDelimitedTokenSafe`
+ * from `./token-parser.ts` which parses RIGHT-TO-LEFT.
+ *
+ * ## When to use which function:
+ *
+ * - **parseDollarDelimitedToken** (this function): When you're certain the collection
+ *   does NOT contain $ characters. Slightly simpler, parses left-to-right.
+ *
+ * - **parseDollarDelimitedTokenSafe** (from token-parser.ts): When you need to handle
+ *   the "$MUSIC" edge case where collection name starts with $. Parses right-to-left.
+ *
+ * @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('GUSDC$Unit$none$eth:0x...');
+ * // → { collection: "GUSDC", category: "Unit", type: "none", additionalKey: "eth:0x..." }
+ *
+ * // Handles additionalKey with $ characters
+ * const complex = parseDollarDelimitedToken('SYMBOL$Unit$none$eth:0x$1234$5678');
+ * // → { collection: "SYMBOL", category: "Unit", type: "none", additionalKey: "eth:0x$1234$5678" }
+ *
+ * // WARNING: Does NOT handle $ in collection correctly!
+ * // parseDollarDelimitedToken('$MUSIC$Unit$none$none')
+ * // → { collection: "", category: "MUSIC", type: "Unit", additionalKey: "none$none" } // WRONG!
+ * // Use parseDollarDelimitedTokenSafe for this case.
+ * ```
+ *
+ * @see parseDollarDelimitedTokenSafe - Handles $ in collection name (RIGHT-TO-LEFT parsing)
+ * @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

@@ -0,0 +1 @@
+{"version":3,"file":"token-format-converter.d.ts","sourceRoot":"","sources":["../../src/utils/token-format-converter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAOrD,qBAAa,oBAAoB;IAC/B;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,CAEf,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,GAAG,GAC/B,MAAM;IAyCT;;;;;;;;;;;;OAYG;IAEH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,GAAG,GAAG,UAAU;IA6B1D;;;;;;;;;;;OAWG;IACH,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAenD;;;;;;;;;;;OAWG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAG5E"}