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

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

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

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

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

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

@@ -0,0 +1,38 @@
+/**
+ * Multipart Form Data Helpers
+ *
+ * Shared utilities for handling multipart/form-data file uploads
+ * across browser and Node.js environments.
+ *
+ * @category Utilities
+ * @since 3.11.5
+ */
+/**
+ * Prepare multipart form data for image upload
+ *
+ * Handles both browser File objects and Node.js Buffer objects,
+ * automatically detecting the environment and creating appropriate
+ * FormData structure.
+ *
+ * @param file - Image file as File object (browser) or Buffer (Node.js)
+ * @param fieldName - Form field name for the file upload
+ * @param filename - Filename to use when uploading Buffer
+ * @returns FormData ready for multipart upload
+ * @throws Error if file is neither File nor Buffer
+ *
+ * @example Browser usage
+ * ```typescript
+ * const fileInput = document.querySelector('#upload') as HTMLInputElement;
+ * const file = fileInput.files?.[0];
+ * const formData = prepareImageFormData(file, 'image', 'avatar.png');
+ * ```
+ *
+ * @example Node.js usage
+ * ```typescript
+ * import * as fs from 'fs';
+ * const buffer = fs.readFileSync('./image.png');
+ * const formData = prepareImageFormData(buffer, 'image', 'token-image.png');
+ * ```
+ */
+export declare function prepareImageFormData(file: File | Buffer, fieldName: string | undefined, filename: string): FormData;
+//# sourceMappingURL=multipart-helpers.d.ts.map

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

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

package/dist/utils/multipart.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Utilities for handling multipart/form-data uploads
+ *
+ * This module provides cross-platform file upload support for both
+ * browser and Node.js environments.
+ *
+ * MIGRATION NOTE: This file now uses Zod schemas for validation while maintaining
+ * backward-compatible API through FileValidationError throwing functions.
+ */
+/**
+ * Error thrown when file validation fails
+ */
+export declare class FileValidationError extends Error {
+    filename?: string | undefined;
+    mimeType?: string | undefined;
+    constructor(message: string, filename?: string | undefined, mimeType?: string | undefined);
+}
+/**
+ * Validates a file against upload constraints using Zod schemas
+ *
+ * @param file File or Buffer to validate
+ * @param filename Original filename (required for Buffer validation)
+ * @param mimeType MIME type (required for Buffer validation)
+ * @throws FileValidationError if validation fails
+ */
+export declare function validateFile(file: File | Buffer, filename?: string, mimeType?: string): void;
+/**
+ * Gets the file extension from a filename
+ *
+ * @param filename The filename to extract extension from
+ * @returns File extension including the dot (e.g., '.png')
+ */
+export declare function getFileExtension(filename: string | null | undefined): string;
+/**
+ * Creates FormData for browser environments
+ *
+ * @param file File object to upload
+ * @param data Additional form fields
+ * @returns FormData object ready for upload
+ */
+export declare function createFormData(file: File, data?: Record<string, unknown>): FormData;
+/**
+ * Creates multipart form data for Node.js environments
+ *
+ * @param buffer Buffer containing file data
+ * @param filename Original filename
+ * @param mimeType MIME type of the file
+ * @param data Additional form fields
+ * @returns Object with data buffer and headers
+ */
+export declare function createMultipartFormData(buffer: Buffer, filename: string, mimeType: string, data?: Record<string, unknown>): {
+    data: Buffer;
+    headers: Record<string, string>;
+};
+/**
+ * Detects if this is a browser environment
+ */
+export declare function isBrowserEnvironment(): boolean;
+/**
+ * Detects if this is a Node.js environment
+ */
+export declare function isNodeEnvironment(): boolean;
+//# sourceMappingURL=multipart.d.ts.map

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

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

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

@@ -0,0 +1,62 @@
+/**
+ * NFT Utility Helper Functions
+ *
+ * Utilities for NFT operations including validation, formatting,
+ * and unique key generation for transactions.
+ */
+/**
+ * Generate unique key for NFT transactions
+ * Used for idempotency in GalaChain operations
+ *
+ * @param prefix - Operation type prefix: 'auth' (authorize), 'create' (token class), 'mint'
+ * @returns Unique key in format: {prefix}-{timestamp}-{random}
+ */
+export declare function generateNftUniqueKey(prefix: 'auth' | 'create' | 'mint'): string;
+/**
+ * Get DTO expiration timestamp
+ * GalaChain DTOs expire after 60 seconds
+ *
+ * @returns Current timestamp + 60 seconds in milliseconds
+ */
+export declare function getNftDtoExpiration(): number;
+/**
+ * Validate NFT collection name format
+ * Rules: alphanumeric (a-z, A-Z, 0-9), 3-50 characters
+ *
+ * @param name - Collection name to validate
+ * @returns True if name is valid format
+ */
+export declare function validateCollectionName(name: string): boolean;
+/**
+ * Validate token symbol format
+ * Rules: letters only (a-z, A-Z), 1-8 characters
+ *
+ * @param symbol - Token symbol to validate
+ * @returns True if symbol is valid format
+ */
+export declare function validateTokenSymbol(symbol: string): boolean;
+/**
+ * Format number as whole number string for GalaChain
+ * Truncates decimals and converts to string
+ *
+ * @param value - Number or string value to format
+ * @returns Whole number as string (e.g., "1000")
+ */
+export declare function formatWholeNumber(value: string | number): string;
+/**
+ * Check if string is valid hex
+ * Used for additionalKey validation
+ *
+ * @param str - String to check
+ * @returns True if string is valid hex
+ */
+export declare function isValidHex(str: string): boolean;
+/**
+ * Validate GalaChain address format
+ * Supports eth|{hex} format
+ *
+ * @param address - Address to validate
+ * @returns True if address is valid format
+ */
+export declare function validateGalaChainAddress(address: string): boolean;
+//# sourceMappingURL=nft-helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nft-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/nft-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAI/E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAK3D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAQhE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAK/C;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAKjE"}

package/dist/utils/numeric-patterns.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Numeric Calculation Patterns
+ *
+ * High-level numeric patterns for bonding curve fees, Uniswap V3 tick management,
+ * percentile calculations, and safe division with thresholds.
+ *
+ * Consolidates 20+ occurrences of repeated mathematical patterns across trading,
+ * liquidity, and portfolio services.
+ *
+ * @category Utilities
+ * @since 5.17.0
+ */
+import BigNumber from 'bignumber.js';
+/**
+ * Calculate linearly interpolated fee between min and max based on progress
+ *
+ * Maps a progress value (0 to 1) to a fee between minFee and maxFee using linear interpolation.
+ * This is the core pattern used in bonding curve calculations where fees scale from
+ * minFeePortion to maxFeePortion based on token supply progress (supply / maxSupply).
+ *
+ * Formula: minFee + (maxFee - minFee) * progress
+ *
+ * Consolidates 4 occurrences in bondingCurveCalculations and related services.
+ *
+ * @param progress - Progress ratio from 0 to 1 (e.g., currentSupply / maxSupply)
+ * @param minFee - Minimum fee value (as decimal, e.g., 0.1 for 10%)
+ * @param maxFee - Maximum fee value (as decimal, e.g., 0.5 for 50%)
+ * @returns Interpolated fee amount as BigNumber
+ *
+ * @throws Error if progress is outside [0, 1] or if maxFee < minFee
+ *
+ * @example
+ * ```typescript
+ * // Fee scales from 10% to 50% as supply increases
+ * const progress = toBigNumber('500000').dividedBy('10000000'); // 0.05 = 5%
+ * const fee = calculateLinearFeeInterpolation(progress, 0.1, 0.5);
+ * // Returns: 0.1 + (0.5 - 0.1) * 0.05 = 0.12 (12%)
+ *
+ * // At max supply (100%), fee reaches 50%
+ * const fee = calculateLinearFeeInterpolation(1, 0.1, 0.5);
+ * // Returns: 0.5
+ *
+ * // At zero supply (0%), fee is minimum
+ * const fee = calculateLinearFeeInterpolation(0, 0.1, 0.5);
+ * // Returns: 0.1
+ * ```
+ */
+export declare function calculateLinearFeeInterpolation(progress: number | BigNumber, minFee: number, maxFee: number): BigNumber;
+/**
+ * Round tick boundaries to valid Uniswap V3 spacing multiples
+ *
+ * Uniswap V3 ticks must be multiples of tickSpacing (1, 10, 60, 200, etc.).
+ * This utility rounds tickLower down and tickUpper up to valid boundaries.
+ *
+ * Consolidates 5 occurrences of inline Math.floor/Math.ceil logic in GSwap services.
+ *
+ * @param tickLower - Lower tick boundary (before rounding)
+ * @param tickUpper - Upper tick boundary (before rounding)
+ * @param tickSpacing - Tick spacing requirement (e.g., 60 for 0.3% fee tier)
+ * @returns Object with rounded tickLower (floor) and tickUpper (ceil)
+ *
+ * @throws Error if tickLower >= tickUpper or if tickSpacing <= 0
+ *
+ * @example
+ * ```typescript
+ * // Round to nearest 60-tick multiples
+ * const rounded = roundTickBoundaries(1234, 5678, 60);
+ * // Returns: { tickLower: 1200, tickUpper: 5700 }
+ * // (1234 rounds down to 1200, 5678 rounds up to 5700)
+ *
+ * // Handle negative ticks (below price 1.0)
+ * const rounded = roundTickBoundaries(-1234, -1000, 10);
+ * // Returns: { tickLower: -1240, tickUpper: -1000 }
+ *
+ * // Ticks already valid (multiples of spacing)
+ * const rounded = roundTickBoundaries(0, 60, 60);
+ * // Returns: { tickLower: 0, tickUpper: 60 }
+ * ```
+ */
+export declare function roundTickBoundaries(tickLower: number, tickUpper: number, tickSpacing: number): {
+    tickLower: number;
+    tickUpper: number;
+};
+/**
+ * Map price range to tick range and return both computed ticks and actual prices
+ *
+ * Converts a human-readable price range to Uniswap V3 ticks, then converts back
+ * to compute the actual prices those ticks represent (due to rounding effects).
+ *
+ * This bidirectional mapping is essential for liquidity position validation where
+ * users specify a price range but the actual executable range differs due to
+ * tick quantization.
+ *
+ * Consolidates 3 occurrences of price-tick conversion with validation logic.
+ *
+ * @param minPrice - Minimum price (human-readable, e.g., "0.95")
+ * @param maxPrice - Maximum price (human-readable, e.g., "1.05")
+ * @param tickSpacing - Tick spacing requirement (default: 60)
+ * @returns Object with computed ticks and the actual prices they represent
+ *
+ * @throws Error if minPrice >= maxPrice or if prices are non-positive
+ *
+ * @example
+ * ```typescript
+ * // Map price range [0.95, 1.05] to ticks with 60-tick spacing
+ * const mapping = priceTickRangeMapping('0.95', '1.05', 60);
+ * // Returns: {
+ * //   minTick: -2700,
+ * //   maxTick: 1320,
+ * //   actualMinPrice: BigNumber('0.949...'),  // Slightly lower due to rounding
+ * //   actualMaxPrice: BigNumber('1.050...')   // Slightly higher due to rounding
+ * // }
+ *
+ * // Confirms to user: "You requested [0.95, 1.05] but will get [0.949..., 1.050...]"
+ * ```
+ */
+export declare function priceTickRangeMapping(minPrice: string | number | BigNumber, maxPrice: string | number | BigNumber, tickSpacing?: number): {
+    minTick: number;
+    maxTick: number;
+    actualMinPrice: BigNumber;
+    actualMaxPrice: BigNumber;
+};
+/**
+ * Calculate percentile index in a sorted array
+ *
+ * Computes the array index corresponding to a given percentile (0-100).
+ * Uses linear interpolation for fractional positions.
+ *
+ * Consolidates 3 occurrences of percentile calculations in monitoring metrics.
+ *
+ * @param sortedArray - Array of numbers, must be sorted in ascending order
+ * @param percentile - Percentile value from 0 to 100 (e.g., 95 for 95th percentile)
+ * @returns The array index, or -1 if array is empty
+ *
+ * @throws Error if percentile is outside [0, 100] or array is not sorted
+ *
+ * @example
+ * ```typescript
+ * // Get 95th percentile from latency measurements
+ * const latencies = [10, 25, 50, 75, 100, 150, 200];
+ * const p95Index = percentileIndexCalculation(latencies, 95);
+ * // Returns index 6 (value 200, or interpolated between 150-200)
+ *
+ * // Median (50th percentile)
+ * const medianIndex = percentileIndexCalculation(latencies, 50);
+ * // Returns index 3 (value 75)
+ *
+ * // Min/Max
+ * const minIndex = percentileIndexCalculation(latencies, 0);   // 0
+ * const maxIndex = percentileIndexCalculation(latencies, 100); // 6
+ * ```
+ */
+export declare function percentileIndexCalculation(sortedArray: number[], percentile: number): number;
+/**
+ * Round decimal up to specified precision (ceiling rounding)
+ *
+ * Always rounds UP to the specified decimal places. This ensures system accuracy
+ * and prevents shortchanging calculations (e.g., fee calculations always round up
+ * to protect the fee recipient).
+ *
+ * Consolidates 3 occurrences of Math.ceil with decimal precision patterns.
+ *
+ * @param value - Value to round (string, number, or BigNumber)
+ * @param decimals - Number of decimal places to preserve
+ * @returns Rounded value as BigNumber
+ *
+ * @throws Error if decimals is negative
+ *
+ * @example
+ * ```typescript
+ * // Fee calculations that always round up
+ * const fee = decimalRoundingUp('1.234', 2);  // 1.24 (rounds up from 1.23)
+ *
+ * // Preserve more decimals
+ * const precise = decimalRoundingUp('1.23456', 4);  // 1.2346
+ *
+ * // Integer rounding
+ * const integer = decimalRoundingUp('1.1', 0);  // 2 (rounds up to next integer)
+ *
+ * // Very small values
+ * const tiny = decimalRoundingUp('0.00001', 4);  // 0.0001
+ * ```
+ */
+export declare function decimalRoundingUp(value: string | number | BigNumber, decimals: number): BigNumber;
+/**
+ * Divide with zero fallback AND minimum threshold check
+ *
+ * Performs safe division with two layers of protection:
+ * 1. Returns fallback if denominator is zero
+ * 2. Returns minimum threshold if computed result is less than minimum
+ *
+ * This prevents calculations from producing unrealistic micro-values (e.g., APR
+ * calculations that shouldn't return 0.0000001%).
+ *
+ * Consolidates 3 partial occurrences across APR and portfolio calculations.
+ *
+ * @param numerator - Dividend
+ * @param denominator - Divisor
+ * @param minimum - Minimum threshold (default: "0", meaning no minimum)
+ * @param fallback - Value to return if denominator is zero (default: "0")
+ * @returns The quotient, minimum threshold if result is too small, or fallback if denominator is zero
+ *
+ * @throws Error if minimum is negative or minimum > maximum representable value
+ *
+ * @example
+ * ```typescript
+ * // Safe division with zero fallback
+ * const ratio = safeDivideWithMinimum('100', '0', undefined, '0');
+ * // Returns: "0" (denominator is zero)
+ *
+ * // Enforce minimum APR (never report less than 0.01%)
+ * const apr = safeDivideWithMinimum(
+ *   feeAmount,
+ *   liquidityValue,
+ *   '0.0001'  // Minimum 0.01% APR
+ * );
+ *
+ * // Threshold prevents micro-values
+ * const tiny = safeDivideWithMinimum('1', '1000000', '0.001');
+ * // Result 0.000001 is < minimum 0.001, so returns 0.001
+ *
+ * // Normal division (result meets threshold)
+ * const normal = safeDivideWithMinimum('100', '10', '0.001');
+ * // Result 10 > minimum 0.001, so returns 10
+ * ```
+ */
+export declare function safeDivideWithMinimum(numerator: string | number | BigNumber, denominator: string | number | BigNumber, minimum?: string | number | BigNumber, fallback?: string | number | BigNumber): BigNumber;
+/**
+ * Round a Uniswap V3 tick to a valid spacing multiple
+ *
+ * Uniswap V3 ticks must be multiples of tickSpacing (e.g., 1, 10, 60, 200).
+ * This utility rounds down to the nearest valid tick spacing using integer arithmetic.
+ *
+ * Formula: `Math.floor(tick / tickSpacing) * tickSpacing`
+ *
+ * Consolidates 4 occurrences of inline tick rounding logic in GSwap services.
+ *
+ * @param tick - The tick value to round (can be negative for prices below 1.0)
+ * @param tickSpacing - The tick spacing requirement (e.g., 1, 10, 60, 200)
+ * @returns The rounded tick (multiple of tickSpacing)
+ *
+ * @throws Error if tickSpacing <= 0
+ *
+ * @example
+ * ```typescript
+ * // Round tick 1055 to nearest tick spacing of 10
+ * const rounded = roundTickToSpacing(1055, 10);  // 1050
+ *
+ * // Round tick 101 to spacing 60
+ * const rounded = roundTickToSpacing(101, 60);   // 60
+ *
+ * // Negative ticks are also supported (for prices below 1.0)
+ * const rounded = roundTickToSpacing(-1055, 10); // -1060
+ * ```
+ */
+export declare function roundTickToSpacing(tick: number, tickSpacing: number): number;
+/**
+ * Calculate reverse bonding curve fee amount with precision handling
+ *
+ * Consolidates the pattern of applying a fee factor to a base amount with
+ * integer rounding (down). Used extensively in bonding curve calculations
+ * for reverse fee computation and scaled amount operations.
+ *
+ * Formula: `new BigNumber(baseAmount).multipliedBy(feeFactor).integerValue(BigNumber.ROUND_DOWN)`
+ *
+ * Consolidates 3 occurrences of fee scaling patterns in trading services.
+ *
+ * @param baseAmount - The base amount to apply fee factor to (string, number, or BigNumber)
+ * @param feeFactor - The fee factor as decimal (e.g., 0.1 for 10%, 0.005 for 0.5%)
+ * @returns The scaled fee amount (rounded down to integer)
+ *
+ * @throws Error if feeFactor is negative
+ *
+ * @example
+ * ```typescript
+ * // Calculate 1% fee on 1000 GALA
+ * const baseAmount = new BigNumber('1000');
+ * const fee = calculateScaledFeeAmount(baseAmount, 0.01);  // BigNumber(10)
+ *
+ * // Calculate 0.5% reverse bonding curve fee
+ * const feeAmount = calculateScaledFeeAmount('5000', 0.005);  // BigNumber(25)
+ *
+ * // Fee factor from pool: reverseBondingCurveFee = 0.123456
+ * const reversed = calculateScaledFeeAmount(amount, reverseBondingCurveFee);
+ * // Returns: rounded-down result of amount * 0.123456
+ * ```
+ */
+export declare function calculateScaledFeeAmount(baseAmount: string | number | BigNumber, feeFactor: number): BigNumber;
+//# sourceMappingURL=numeric-patterns.d.ts.map

package/dist/utils/numeric-patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-patterns.d.ts","sourceRoot":"","sources":["../../src/utils/numeric-patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,SAAS,MAAM,cAAc,CAAC;AAIrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,SAAS,CAiBX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAmB1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACrC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACrC,WAAW,GAAE,MAAW,GACvB;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,SAAS,CAAC;IAC1B,cAAc,EAAE,SAAS,CAAC;CAC3B,CAiCA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EAAE,EACrB,UAAU,EAAE,MAAM,GACjB,MAAM,CAeR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAClC,QAAQ,EAAE,MAAM,GACf,SAAS,CAUX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACtC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACxC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACrC,QAAQ,GAAE,MAAM,GAAG,MAAM,GAAG,SAAe,GAC1C,SAAS,CA0BX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAM5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACvC,SAAS,EAAE,MAAM,GAChB,SAAS,CAMX"}

package/dist/utils/numeric-wrappers.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Numeric Utility Wrappers
+ *
+ * Semantic wrappers and helpers for common numeric operations.
+ * Consolidates 7 patterns found across 127+ occurrences in service files.
+ *
+ * @category Utilities
+ * @since 5.16.0
+ */
+import type BigNumber from 'bignumber.js';
+/**
+ * Convert decimal to percentage representation
+ *
+ * Multiplies by 100 to convert decimal to percentage.
+ * Consolidates 13+ occurrences across pool validators and metrics.
+ *
+ * @example
+ * ```typescript
+ * const percentageChange = toPercentageDecimal(0.025); // 2.5
+ * ```
+ */
+export declare function toPercentageDecimal(value: string | number | BigNumber): BigNumber;
+/**
+ * Convert percentage back to decimal representation
+ *
+ * Divides by 100 to convert percentage to decimal.
+ * Reverse of toPercentageDecimal.
+ *
+ * @example
+ * ```typescript
+ * const decimal = fromPercentageDecimal(2.5); // 0.025
+ * ```
+ */
+export declare function fromPercentageDecimal(value: string | number | BigNumber): BigNumber;
+/**
+ * Format value as display price (6 decimal places)
+ *
+ * Semantic wrapper for `.toFixed(6)` - standard price display format.
+ * Consolidates 20+ occurrences across GSwap services.
+ *
+ * @example
+ * ```typescript
+ * const displayPrice = toDisplayPrice(1.23456789); // "1.234568"
+ * ```
+ */
+export declare function toDisplayPrice(value: string | number | BigNumber, decimals?: number): string;
+/**
+ * Format value as pool price (8 decimal places)
+ *
+ * Semantic wrapper for `.toFixed(8)` - pool calculation format.
+ * Consolidates 10+ occurrences across pool calculation services.
+ *
+ * @example
+ * ```typescript
+ * const poolPrice = toPoolPrice(1.234567890); // "1.23456789"
+ * ```
+ */
+export declare function toPoolPrice(value: string | number | BigNumber): string;
+/**
+ * Format value as percentage display (2 decimal places)
+ *
+ * Semantic wrapper for `.toFixed(2)` - percentage display format.
+ * Consolidates 5+ occurrences for percentage formatting.
+ *
+ * @example
+ * ```typescript
+ * const percentage = toPercentage(0.025, 2); // "2.50"
+ * ```
+ */
+export declare function toPercentage(value: string | number | BigNumber, decimals?: number): string;
+/**
+ * Convert fee tier to basis points value
+ *
+ * Maps fee tier enum values (1, 0.3, 0.05) to basis points (10000, 3000, 500).
+ * Consolidates 8 occurrences and prevents hardcoded arrays.
+ *
+ * @example
+ * ```typescript
+ * const basisPoints = feeTierToBasisPoints(0.3); // 3000
+ * const basisPoints2 = feeTierToBasisPoints(3000); // 3000
+ * ```
+ */
+export declare function feeTierToBasisPoints(feeTier: number): number;
+/**
+ * Create a decimal scaler for token amount normalization
+ *
+ * Returns 10^decimals as BigNumber for token amount conversions.
+ * Consolidates 7 occurrences of Math.pow(10, decimals) pattern.
+ *
+ * @example
+ * ```typescript
+ * const scaler = createDecimalScaler(6);
+ * const normalized = amount.dividedBy(scaler); // Normalize 1M units to 1 token
+ * ```
+ */
+export declare function createDecimalScaler(decimals: number): BigNumber;
+/**
+ * Check if value is a valid number (not NaN, not infinite)
+ *
+ * Consolidates 40+ occurrences of `!isNaN() && isFinite()` checks.
+ * Used in safe-parsers and validation throughout.
+ *
+ * @example
+ * ```typescript
+ * if (!isValidNumber(parsed)) {
+ *   return fallback;
+ * }
+ * ```
+ */
+export declare function isValidNumber(value: unknown): value is number;
+/**
+ * Convert Uniswap V3 tick to price ratio
+ *
+ * Calculates: (1.0001)^tick for Uniswap V3 price calculations.
+ * Consolidates 6 occurrences of Math.pow(1.0001, tick) pattern.
+ *
+ * Uses logarithmic formula for efficiency: (1.0001)^tick = e^(tick * ln(1.0001))
+ * This avoids expensive BigNumber.pow operations with large exponents.
+ *
+ * @example
+ * ```typescript
+ * const price = tickToPrice(-1000);
+ * const inversePrice = tickToPrice(1000);
+ * ```
+ */
+export declare function tickToPrice(tick: number): BigNumber;
+/**
+ * Convert milliseconds to seconds
+ *
+ * Simple conversion helper for time unit handling.
+ *
+ * @example
+ * ```typescript
+ * const seconds = msToSeconds(5000); // 5
+ * ```
+ */
+export declare function msToSeconds(ms: number): number;
+/**
+ * Convert seconds to milliseconds
+ *
+ * Simple conversion helper for time unit handling.
+ *
+ * @example
+ * ```typescript
+ * const ms = secondsToMs(5); // 5000
+ * ```
+ */
+export declare function secondsToMs(seconds: number): number;
+//# sourceMappingURL=numeric-wrappers.d.ts.map

package/dist/utils/numeric-wrappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-wrappers.d.ts","sourceRoot":"","sources":["../../src/utils/numeric-wrappers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,SAAS,MAAM,cAAc,CAAC;AAI1C;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAEjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAEnF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAClC,QAAQ,GAAE,MAAU,GACnB,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAClC,QAAQ,GAAE,MAAU,GACnB,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAE/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAG7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAOnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD"}