@gala-chain/launchpad-sdk 3.31.2 → 4.0.0

package/dist/types/pool-state-delta.dto.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Pool State Delta Type Definitions
+ *
+ * Contract definitions for pool state management and swap delta calculations.
+ * These types enable efficient tracking of pool state changes without full refetches.
+ *
+ * @packageDocumentation
+ */
+import type { Pool, TickData } from '@gala-chain/dex';
+/**
+ * Data extracted from GalaChain swap transaction events
+ *
+ * Represents the raw data available from a completed swap transaction on-chain.
+ * Used as input to calculate the delta changes to pool state.
+ *
+ * @category Pool State
+ */
+export interface SwapEventData {
+    /** Unique transaction identifier (UUID format) */
+    transactionId: string;
+    /** Transaction timestamp (milliseconds since epoch) */
+    timestamp: number;
+    /** Amount specified in the swap (can be negative for exactOutput swaps) */
+    amountSpecified: string;
+    /** True if swapping token0 for token1, false if swapping token1 for token0 */
+    zeroForOne: boolean;
+    /** True for exact input swaps, false for exact output swaps */
+    exactInput: boolean;
+    /**
+     * Optional: Actual amount0 from chain (for validation)
+     * Negative values indicate token0 was spent, positive indicates received
+     */
+    actualAmount0?: string;
+    /**
+     * Optional: Actual amount1 from chain (for validation)
+     * Negative values indicate token1 was spent, positive indicates received
+     */
+    actualAmount1?: string;
+    /**
+     * Optional: Final sqrtPrice from chain (for validation)
+     * Used to detect drift between calculated and actual pool state
+     */
+    actualSqrtPrice?: string;
+}
+/**
+ * Complete result of applying a swap delta to cached pool state
+ *
+ * Contains all state changes from processing a swap event, including updated
+ * pool parameters, tick data modifications, token amounts, fees, and metadata.
+ *
+ * @category Pool State
+ */
+export interface SwapDeltaResult {
+    /** Updated pool object with new sqrtPrice, liquidity, and tick */
+    updatedPool: Pool;
+    /**
+     * Only ticks that changed during the swap
+     * Record key is tick index as string, value is updated TickData
+     */
+    updatedTicks: Record<string, TickData>;
+    /**
+     * Token0 amount in the swap
+     * Negative if token0 was spent, positive if received
+     */
+    amount0: BigNumber;
+    /**
+     * Token1 amount in the swap
+     * Negative if token1 was spent, positive if received
+     */
+    amount1: BigNumber;
+    /** Fee collected in token0 during the swap */
+    feeAmount0: BigNumber;
+    /** Fee collected in token1 during the swap */
+    feeAmount1: BigNumber;
+    /**
+     * Array of tick indices that were crossed during the swap
+     * Ticks are crossed when price moves through a liquidity boundary
+     */
+    ticksCrossed: number[];
+    /** Calculation metadata and diagnostics */
+    metadata: {
+        /** Time taken to calculate applySwapDelta (milliseconds) */
+        calculationTimeMs: number;
+        /** Number of iterations through the swap calculation loop */
+        swapSteps: number;
+        /** True if price reached sqrtPriceLimit before consuming all input */
+        priceHitLimit: boolean;
+        /**
+         * Optional: Drift percentage from actual on-chain data
+         * Only present if validation data (actualAmount0/1, actualSqrtPrice) was provided
+         * Represents % difference between calculated and actual values
+         */
+        driftPercentage?: number;
+    };
+}
+/**
+ * Tracking information for cached pool state
+ *
+ * Maintains metadata about the pool cache state to determine when
+ * a full refetch is necessary vs. when delta updates are sufficient.
+ *
+ * @category Pool State
+ */
+export interface PoolStateMetadata {
+    /**
+     * Timestamp of last full fetchCompositePoolData call
+     * Milliseconds since epoch
+     */
+    lastFullRefetch: number;
+    /**
+     * Count of swap deltas applied since last refetch
+     * Used to trigger refetch after N swaps to prevent drift accumulation
+     */
+    swapsSinceRefetch: number;
+    /**
+     * Accumulated drift percentage across all swaps since refetch
+     * Sum of absolute drift values from validation checks
+     */
+    cumulativeDrift: number;
+    /**
+     * Transaction IDs we've already processed
+     * Prevents duplicate processing of the same swap event
+     */
+    processedTransactions: string[];
+    /**
+     * Hash of critical pool state for validation
+     * Used to detect external modifications to pool state
+     * Typically hash of: sqrtPrice + liquidity + tick + token0Balance + token1Balance
+     */
+    stateHash: string;
+}
+/**
+ * Result of pool state validation checks
+ *
+ * Indicates whether cached pool state is still reliable or if a refetch is needed.
+ * Provides diagnostic information about detected drift and validation failures.
+ *
+ * @category Pool State
+ */
+export interface PoolStateValidationResult {
+    /** True if cached pool state passes validation checks */
+    isValid: boolean;
+    /**
+     * Percentage difference detected between calculated and actual values
+     * 0.001 = 0.1% drift
+     */
+    driftPercentage: number;
+    /** True if a full refetch is recommended */
+    shouldRefetch: boolean;
+    /**
+     * Reason for refetch recommendation (if shouldRefetch is true)
+     * - 'drift': Accumulated drift exceeded threshold
+     * - 'swap-count': Too many swaps applied since refetch
+     * - 'time-elapsed': Too much time passed since refetch
+     * - 'tick-mismatch': Tick and price are inconsistent
+     * - 'manual': Manual validation failure
+     * - 'missing-tick-data': Required tick data not in cache
+     */
+    refetchReason?: 'drift' | 'swap-count' | 'time-elapsed' | 'tick-mismatch' | 'manual' | 'missing-tick-data';
+    /**
+     * List of specific validation failures detected
+     * Empty array if no failures
+     */
+    validationErrors: string[];
+}
+/**
+ * Internal state tracked during swap calculation
+ *
+ * Represents the mutable state that changes as the swap progresses
+ * through multiple tick boundaries.
+ *
+ * @internal
+ * @category Pool State
+ */
+export interface InternalSwapState {
+    /** Current square root price (Q64.96 format) */
+    sqrtPrice: BigNumber;
+    /** Current available liquidity */
+    liquidity: BigNumber;
+    /** Current tick index */
+    tick: number;
+    /**
+     * Remaining amount of the specified token to swap
+     * Decreases as swap progresses
+     */
+    amountSpecifiedRemaining: BigNumber;
+    /**
+     * Accumulated output amount calculated so far
+     * Increases as swap progresses
+     */
+    amountCalculated: BigNumber;
+    /** Global fee growth for token0 (or token1 depending on direction) */
+    feeGrowthGlobalX: BigNumber;
+    /** Accumulated protocol fees */
+    protocolFee: BigNumber;
+}
+/**
+ * Result of a single swap step calculation
+ *
+ * Represents the changes from moving from one tick boundary to the next
+ * (or to the target price if reached first).
+ *
+ * @internal
+ * @category Pool State
+ */
+export interface SwapStepResult {
+    /** Square root price at the start of this step */
+    sqrtPriceStart: BigNumber;
+    /** Next tick boundary index */
+    tickNext: number;
+    /** Square root price at the next tick (or target price) */
+    sqrtPriceNext: BigNumber;
+    /** True if the next tick boundary is initialized with liquidity */
+    initialised: boolean;
+    /** Output token amount for this step */
+    amountOut: BigNumber;
+    /** Input token amount for this step */
+    amountIn: BigNumber;
+    /** Fee amount collected in this step */
+    feeAmount: BigNumber;
+}
+/**
+ * Event data for crossing a tick boundary
+ *
+ * Tracks liquidity changes when price moves through a tick,
+ * which affects available liquidity for subsequent swap steps.
+ *
+ * @internal
+ * @category Pool State
+ */
+export interface TickCrossingEvent {
+    /** Tick index that was crossed */
+    tick: number;
+    /** Direction of crossing ('up' = price increased, 'down' = price decreased) */
+    direction: 'up' | 'down';
+    /**
+     * Net liquidity change at this tick
+     * Positive when crossing up, negative when crossing down
+     */
+    liquidityNet: BigNumber;
+    /** Liquidity before crossing this tick */
+    liquidityBefore: BigNumber;
+    /** Liquidity after crossing this tick */
+    liquidityAfter: BigNumber;
+}
+//# sourceMappingURL=pool-state-delta.dto.d.ts.map

package/dist/types/pool-state-delta.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-state-delta.dto.d.ts","sourceRoot":"","sources":["../../src/types/pool-state-delta.dto.ts"],"names":[],"mappings":"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"}

package/dist/types/pool-state-manager-config.dto.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Pool State Manager Configuration Type Definitions
+ *
+ * Configuration options for controlling PoolStateManager behavior,
+ * including drift thresholds, refetch triggers, and optimization flags.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Configuration for PoolStateManager behavior
+ *
+ * Controls when cached pool state should be refreshed vs. updated with deltas,
+ * and enables performance/debugging optimizations.
+ *
+ * @category Pool State
+ * @example
+ * ```typescript
+ * const config: PoolStateManagerConfig = {
+ *   maxDriftThreshold: 0.001,        // 0.1% max drift before refetch
+ *   refetchAfterSwaps: 20,            // Refetch every 20 swaps
+ *   refetchAfterMs: 120000,           // Refetch every 2 minutes
+ *   enableAggressiveValidation: true, // Validate on every swap
+ *   enableBigNumberCache: true,       // Cache BigNumber instances
+ *   logDriftWarnings: true            // Log when drift detected
+ * };
+ * ```
+ */
+export interface PoolStateManagerConfig {
+    /**
+     * Maximum allowable drift percentage before triggering refetch
+     *
+     * Drift is measured as the percentage difference between calculated
+     * pool state and actual on-chain state (when validation data is available).
+     *
+     * @example
+     * - 0.001 = 0.1% drift threshold (tight tolerance, frequent refetches)
+     * - 0.01 = 1.0% drift threshold (loose tolerance, fewer refetches)
+     *
+     * @default 0.001 (0.1%)
+     */
+    maxDriftThreshold: number;
+    /**
+     * Trigger full refetch after this many swap deltas applied
+     *
+     * Prevents unbounded drift accumulation by forcing periodic refetches
+     * even if drift threshold hasn't been exceeded.
+     *
+     * @example
+     * - 20 = refetch after 20 swaps
+     * - 100 = refetch after 100 swaps (less frequent, more drift risk)
+     *
+     * @default 20
+     */
+    refetchAfterSwaps: number;
+    /**
+     * Trigger full refetch after this many milliseconds elapsed
+     *
+     * Time-based refetch ensures cached data doesn't become stale
+     * even if swap volume is low.
+     *
+     * @example
+     * - 60000 = refetch every 1 minute
+     * - 120000 = refetch every 2 minutes
+     * - 300000 = refetch every 5 minutes
+     *
+     * @default 120000 (2 minutes)
+     */
+    refetchAfterMs: number;
+    /**
+     * Enable validation on every swap delta application
+     *
+     * When true, compares calculated state against actual on-chain data
+     * (if available) after every swap. Slower but provides early drift detection.
+     *
+     * When false, only validates when refetch conditions are met.
+     *
+     * @default false (validate only on refetch conditions)
+     */
+    enableAggressiveValidation: boolean;
+    /**
+     * Enable caching of BigNumber instances for performance
+     *
+     * When true, reuses BigNumber instances for common values (e.g., zero, one)
+     * to reduce garbage collection pressure in high-frequency trading scenarios.
+     *
+     * When false, creates new BigNumber instances every time.
+     *
+     * @default true
+     */
+    enableBigNumberCache: boolean;
+    /**
+     * Enable logging of drift warnings
+     *
+     * When true, logs warning messages when drift is detected but still
+     * below the refetch threshold. Useful for monitoring cache health.
+     *
+     * When false, only logs when refetch is triggered.
+     *
+     * @default true
+     */
+    logDriftWarnings: boolean;
+}
+//# sourceMappingURL=pool-state-manager-config.dto.d.ts.map

package/dist/types/pool-state-manager-config.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-state-manager-config.dto.d.ts","sourceRoot":"","sources":["../../src/types/pool-state-manager-config.dto.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;OAWG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;OAWG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;;OAYG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;OASG;IACH,0BAA0B,EAAE,OAAO,CAAC;IAEpC;;;;;;;;;OASG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAE9B;;;;;;;;;OASG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC3B"}

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

@@ -74,6 +74,80 @@ export interface AutoPaginationResult<T> {
  * @since 3.32.0
  */
 export declare function autoPaginate<T>(fetchFn: (page: number, limit: number) => Promise<PaginatedResult<T>>, options?: AutoPaginationOptions): Promise<AutoPaginationResult<T>>;
+/**
+ * Result object from bookmark-based API calls
+ * Returned by fetchFn in autoPaginateWithBookmark
+ */
+export interface BookmarkPaginationResult<T> {
+    /** Array of items returned from this page */
+    items: T[];
+    /** Bookmark/cursor for fetching the next page
+     *  - undefined: field was not present in API response
+     *  - empty string "": API signals last page reached
+     *  - non-empty string: bookmark to use for next request
+     */
+    nextBookmark: string | undefined;
+}
+/**
+ * Options for bookmark-based auto-pagination
+ * Used for APIs that use cursor-based pagination (bookmarks) instead of page numbers
+ */
+export interface AutoPaginationWithBookmarkOptions {
+    /** 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;
+}
+/**
+ * Bookmark-based auto-pagination handler
+ *
+ * Automatically iterates through all pages of bookmark-based paginated API results
+ * (cursor-based pagination) and combines them into a single array.
+ *
+ * Used for APIs that return bookmarks/cursors instead of page numbers (e.g., GSwap positions API).
+ * Handles common patterns like:
+ * - Safety limits to prevent infinite loops
+ * - Empty result detection
+ * - Debug logging of pagination progress
+ * - Proper bookmark extraction from API responses
+ * - Dual completion detection (no nextBookmark OR fewer items than requested)
+ *
+ * @typeParam T - Type of items being paginated
+ * @param fetchFn Function that fetches a single page and returns items with optional nextBookmark.
+ *                Should return { items: T[], nextBookmark?: string }.
+ *                If bookmark is undefined, fetches first page.
+ * @param options Pagination options (maxPages, logger, pageSize)
+ * @returns Promise<AutoPaginationResult> All items combined from all pages
+ *
+ * @example Basic usage with bookmark-returning API
+ * ```typescript
+ * const result = await autoPaginateWithBookmark(
+ *   async (bookmark, pageSize) => {
+ *     const response = await api.getPositions({ bookmark, limit: pageSize });
+ *     return {
+ *       items: response.positions,
+ *       nextBookmark: response.metadata?.nextBookmark
+ *     };
+ *   },
+ *   { maxPages: 1000, pageSize: 10, logger }
+ * );
+ * console.log(`Total fetched: ${result.items.length}`);
+ * ```
+ *
+ * @example Legacy: Returns items array directly (uses item count for completion)
+ * ```typescript
+ * const result = await autoPaginateWithBookmark(
+ *   (bookmark, pageSize) => service.getPositions(walletAddress, pageSize, bookmark),
+ *   { maxPages: 1000, pageSize: 10, logger }
+ * );
+ * ```
+ *
+ * @since 3.32.0
+ * @since 3.33.0 - Enhanced to support true bookmark-based pagination with BookmarkPaginationResult<T>
+ */
+export declare function autoPaginateWithBookmark<T>(fetchFn: (bookmark: string | undefined, pageSize: number) => Promise<BookmarkPaginationResult<T> | T[]>, options?: AutoPaginationWithBookmarkOptions): Promise<AutoPaginationResult<T>>;
 /**
  * Build paginated result object for returning combined auto-paginated data
  *

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

@@ -1 +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"}
+{"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;;;GAGG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,6CAA6C;IAC7C,KAAK,EAAE,CAAC,EAAE,CAAC;IACX;;;;OAIG;IACH,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,iCAAiC;IAChD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EACvG,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAqHlC;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

@@ -88,11 +88,11 @@ 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.
+ * Re-exports tickToSqrtPrice from @gala-chain/dex for Uniswap V3 liquidity calculations.
+ * Maintained as a wrapper for backward compatibility.
  *
  * @param tick The tick value from the pool
- * @returns Sqrt ratio as BigNumber
+ * @returns Sqrt price in Q64.96 format
  *
  * @example
  * ```typescript
@@ -100,8 +100,28 @@ export declare function calculateSlippageFactor(tolerance?: number): BigNumber;
  * const upperSqrtRatio = tickToSqrtRatio(tickUpper);
  * const liquidityNeeded = calculateLiquidity(lowerSqrtRatio, upperSqrtRatio, ...);
  * ```
+ *
+ * @deprecated This is a wrapper around @gala-chain/dex's tickToSqrtPrice.
+ * Consider importing tickToSqrtPrice directly for new code.
  */
 export declare function tickToSqrtRatio(tick: number): BigNumber;
+/**
+ * Convert a price to tick (Uniswap V3 math)
+ *
+ * Calculates the tick index from a price using production-grade @gala-chain/dex math.
+ * Formula: tick = log_1.0001(price)
+ *
+ * @param price The price value to convert to a tick
+ * @returns Tick index (can be negative or positive)
+ *
+ * @example
+ * ```typescript
+ * const tick = priceToTick('1.5');  // Convert price 1.5 to tick
+ * const tickFloor = Math.floor(priceToTick('0.99'));  // Round down for tickLower
+ * const tickCeil = Math.ceil(priceToTick('1.01'));   // Round up for tickUpper
+ * ```
+ */
+export declare function priceToTick(price: string | number | BigNumber): number;
 /**
  * Invert a price (calculate 1 / price)
  *
@@ -261,4 +281,56 @@ export declare function increaseByPercentage(value: string | number | BigNumber,
  * ```
  */
 export declare function decreaseByPercentage(value: string | number | BigNumber, percentage: number): BigNumber;
+/**
+ * Validates that BigNumber values are strictly positive (> 0).
+ *
+ * Throws an error if any value is zero or negative. Provides clear error messages
+ * with parameter indices for debugging.
+ *
+ * @param values The values to validate
+ * @throws Error if any value is not positive
+ *
+ * @example
+ * ```typescript
+ * requirePositive(liquidity, amountIn);  // Throws if either is <= 0
+ * requirePositive(amount);  // Single value validation
+ * ```
+ */
+export declare function requirePositive(...values: BigNumber[]): void;
+/**
+ * Validates that BigNumber values are non-negative (>= 0).
+ *
+ * Throws an error if any value is negative. Allows zero values, unlike requirePositive.
+ * Useful for optional amounts that default to zero.
+ *
+ * @param values The values to validate
+ * @throws Error if any value is negative
+ *
+ * @example
+ * ```typescript
+ * requireNonNegative(fees, collectedFees);  // Allows zero but not negative
+ * ```
+ */
+export declare function requireNonNegative(...values: BigNumber[]): void;
+/**
+ * Validates a BigNumber with a custom parameter name and optional context.
+ *
+ * Provides descriptive error messages for better debugging in specific use cases.
+ * Throws an error if value is not positive (> 0).
+ *
+ * @param value The value to validate
+ * @param paramName The parameter name for the error message
+ * @param context Optional additional context (e.g., "for swap operation")
+ * @throws Error with descriptive message if value is not positive
+ *
+ * @example
+ * ```typescript
+ * requirePositiveWithContext(amount, 'amountIn', 'for swap');
+ * // Throws: "amountIn must be positive for swap, got: 0"
+ *
+ * requirePositiveWithContext(liquidity, 'liquidity');
+ * // Throws: "liquidity must be positive, got: -1"
+ * ```
+ */
+export declare function requirePositiveWithContext(value: BigNumber, paramName: string, context?: string): void;
 //# sourceMappingURL=bignumber-helpers.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"bignumber-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/bignumber-helpers.ts"],"names":[],"mappings":"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"}