@gala-chain/launchpad-sdk 6.0.0 → 7.0.0-beta.2

package/dist/src/utils/bondingCurveCalculations.d.ts

@@ -1,144 +0,0 @@
-/**
- * Local Bonding Curve Calculation Utilities
- *
- * This module provides client-side bonding curve calculations that match the server-side
- * GalaChain formulas exactly. These calculations enable instant quotes without network calls.
- *
- * @category Utilities
- * @since 3.8.0
- *
- * @example Calculate buy amount locally
- * ```typescript
- * import { BondingCurveCalculator } from '@gala-chain/launchpad-sdk';
- *
- * // How much GALA to buy 1000 tokens?
- * const result = BondingCurveCalculator.calculateBuyWithExact('1000', '500000');
- * console.log('GALA needed:', result.amount);
- * console.log('Transaction fee:', result.transactionFee);
- * ```
- */
-import type { AmountCalculationResult } from '../types/launchpad.dto';
-/**
- * Local bonding curve calculation utilities
- *
- * Provides client-side calculations matching GalaChain server formulas exactly.
- * All calculations use the exponential bonding curve model with configurable parameters.
- *
- * @category Utilities
- */
-export declare class BondingCurveCalculator {
-    /**
-     * Calculate GALA needed to buy exact token amount
-     *
-     * Uses the exponential bonding curve formula to calculate how much GALA
-     * is required to purchase a specific number of tokens at current supply.
-     *
-     * Formula: ROUNDUP(BASE_PRICE * (EXP(targetAmount * SCALE) - EXP(currentSupply * SCALE)) / SCALE, 8)
-     *
-     * @param amountOfTokens - Number of tokens to buy (decimal string)
-     * @param currentSupply - Current token supply in circulation (decimal string)
-     * @returns Calculation result with GALA amount and fees
-     *
-     * @example
-     * ```typescript
-     * // Calculate cost to buy 1000 tokens when supply is 500,000
-     * const result = BondingCurveCalculator.calculateBuyWithExact('1000', '500000');
-     * console.log('GALA needed:', result.amount);
-     * console.log('Transaction fee:', result.transactionFee);
-     * console.log('Gas fee:', result.gasFee);
-     * ```
-     */
-    static calculateBuyWithExact(amountOfTokens: string, currentSupply: string): AmountCalculationResult;
-    /**
-     * Calculate tokens received for GALA amount
-     *
-     * Uses the inverse exponential bonding curve formula to calculate how many tokens
-     * will be received for a given GALA amount at current supply.
-     *
-     * Formula: LN(galaAmount * SCALE / BASE_PRICE + EXP(currentSupply * SCALE)) / SCALE - currentSupply
-     *
-     * @param amountOfGala - Amount of GALA to spend (decimal string)
-     * @param currentSupply - Current token supply in circulation (decimal string)
-     * @returns Calculation result with token amount and fees
-     *
-     * @example
-     * ```typescript
-     * // Calculate tokens received when spending 100 GALA
-     * const result = BondingCurveCalculator.calculateBuyWithNative('100', '500000');
-     * console.log('Tokens received:', result.amount);
-     * console.log('Transaction fee:', result.transactionFee);
-     * ```
-     */
-    static calculateBuyWithNative(amountOfGala: string, currentSupply: string): AmountCalculationResult;
-    /**
-     * Calculate GALA received when selling exact token amount
-     *
-     * Uses the exponential bonding curve formula to calculate how much GALA
-     * will be received when selling a specific number of tokens.
-     * Includes reverse bonding curve fee that scales linearly with supply from min to max.
-     *
-     * Formula: BASE_PRICE * (EXP(currentSupply * SCALE) - EXP((currentSupply - tokenAmount) * SCALE)) / SCALE
-     *
-     * Fee Formula: minFeePortion + ((supply / maxSupply) * netFeePortion)
-     * where netFeePortion = maxFeePortion - minFeePortion
-     *
-     * @param amountOfTokens - Number of tokens to sell (decimal string)
-     * @param currentSupply - Current token supply in circulation (decimal string)
-     * @param maxSupply - Maximum token supply for this specific token (decimal string)
-     * @param minFeePortion - Min reverse bonding curve fee factor (number, e.g., 0.0 for 0%)
-     * @param maxFeePortion - Max reverse bonding curve fee factor (number, e.g., 0.5 for 50%)
-     * @returns Calculation result with GALA amount and fees
-     *
-     * @example
-     * ```typescript
-     * // Calculate GALA received when selling 500 tokens
-     * const result = BondingCurveCalculator.calculateSellWithExact('500', '500000', '10000000', 0.0, 0.5);
-     * console.log('GALA received:', result.amount);
-     * console.log('Reverse bonding fee:', result.reverseBondingCurveFee);
-     * console.log('Transaction fee:', result.transactionFee);
-     * ```
-     */
-    static calculateSellWithExact(amountOfTokens: string, currentSupply: string, maxSupply: string, minFeePortion: number, maxFeePortion: number): AmountCalculationResult;
-    /**
-     * Calculate tokens needed to sell to receive target GALA amount
-     *
-     * Uses the inverse exponential bonding curve formula to calculate how many tokens
-     * must be sold to receive a specific GALA amount.
-     * Includes reverse bonding curve fee that scales linearly with supply from min to max.
-     *
-     * Formula: currentSupply - LN(EXP(currentSupply * SCALE) - galaAmount * SCALE / BASE_PRICE) / SCALE
-     *
-     * Fee Formula: minFeePortion + ((supply / maxSupply) * netFeePortion)
-     * where netFeePortion = maxFeePortion - minFeePortion
-     *
-     * @param amountOfGala - Target GALA amount to receive (decimal string)
-     * @param currentSupply - Current token supply in circulation (decimal string)
-     * @param maxSupply - Maximum token supply for this specific token (decimal string)
-     * @param minFeePortion - Min reverse bonding curve fee factor (number, e.g., 0.0 for 0%)
-     * @param maxFeePortion - Max reverse bonding curve fee factor (number, e.g., 0.5 for 50%)
-     * @returns Calculation result with token amount and fees
-     *
-     * @example
-     * ```typescript
-     * // Calculate tokens to sell to receive 50 GALA
-     * const result = BondingCurveCalculator.calculateSellWithNative('50', '500000', '10000000', 0.0, 0.5);
-     * console.log('Tokens to sell:', result.amount);
-     * console.log('Reverse bonding fee:', result.reverseBondingCurveFee);
-     * ```
-     */
-    static calculateSellWithNative(amountOfGala: string, currentSupply: string, maxSupply: string, minFeePortion: number, maxFeePortion: number): AmountCalculationResult;
-    /**
-     * Helper: Round up to N decimal places
-     *
-     * Uses ceil to round up, ensuring calculations always favor the bonding curve
-     * to prevent economic exploits.
-     *
-     * @param value - Number to round
-     * @param decimals - Number of decimal places
-     * @returns Rounded value
-     *
-     * @private
-     */
-    private static roundUp;
-}
-//# sourceMappingURL=bondingCurveCalculations.d.ts.map

package/dist/src/utils/bondingCurveCalculations.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bondingCurveCalculations.d.ts","sourceRoot":"","sources":["../../../src/utils/bondingCurveCalculations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAItE;;;;;;;GAOG;AACH,qBAAa,sBAAsB;IACjC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,qBAAqB,CAC1B,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,GACpB,uBAAuB;IA+B1B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,sBAAsB,CAC3B,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,uBAAuB;IA+B1B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,sBAAsB,CAC3B,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACpB,uBAAuB;IAqC1B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,MAAM,CAAC,uBAAuB,CAC5B,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACpB,uBAAuB;IAkE1B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,OAAO;CAIvB"}

package/dist/src/utils/cacheWarmingHelpers.d.ts

@@ -1,110 +0,0 @@
-/**
- * Cache Warming Helpers
- *
- * Shared utilities for extracting and caching token metadata from pool data.
- * This module provides type-safe, reusable logic for opportunistic cache warming
- * that can be used across the SDK codebase.
- *
- * @category Utilities
- * @since 3.9.2
- */
-import type { BondingCurveCacheEntry } from '../services/TokenMetadataCache';
-/**
- * Pool data fields relevant for cache warming
- *
- * This is a focused subset of PoolData containing only fields needed
- * for metadata extraction. Using a minimal interface keeps cache warming
- * logic decoupled from full pool data structure.
- */
-export interface PoolDataForCaching {
-    /** Token name (required for cache key) */
-    tokenName: string;
-    /** Vault address (GalaChain format) */
-    vaultAddress?: string;
-    /** Reverse bonding curve minimum fee portion (string representation) */
-    reverseBondingCurveMinFeePortion?: string;
-    /** Reverse bonding curve maximum fee portion (string representation) */
-    reverseBondingCurveMaxFeePortion?: string;
-}
-/**
- * Extract cacheable metadata from pool data
- *
- * Converts pool API response data into structured token metadata suitable
- * for caching. Handles string-to-number conversion, validation, and derived
- * calculations (net fee factor).
- *
- * This is a pure function with no side effects - it only extracts and transforms data.
- *
- * @param pool - Pool data from API (must have tokenName field)
- * @param logger - Optional logger for debugging invalid data
- * @returns Metadata object if any fields could be extracted, null otherwise
- *
- * @example Basic extraction
- * ```typescript
- * const pool = {
- *   tokenName: 'anime',
- *   vaultAddress: 'service|Token$Unit$ANIME$...',
- *   reverseBondingCurveMinFeePortion: '0.0',
- *   reverseBondingCurveMaxFeePortion: '0.5'
- * };
- *
- * const metadata = extractMetadataFromPoolData(pool);
- * // Returns:
- * // {
- * //   vaultAddress: 'service|Token$Unit$ANIME$...',
- * //   reverseBondingCurveMinFeeFactor: 0.0,
- * //   reverseBondingCurveMaxFeeFactor: 0.5,
- * //   reverseBondingCurveNetFeeFactor: 0.5
- * // }
- * ```
- *
- * @example With invalid data (graceful handling)
- * ```typescript
- * const pool = {
- *   tokenName: 'test',
- *   reverseBondingCurveMinFeePortion: 'invalid' // NaN after parseFloat
- * };
- *
- * const metadata = extractMetadataFromPoolData(pool, logger);
- * // Returns: null (no valid metadata)
- * // Logger outputs: "Skipping invalid reverseBondingCurveMinFeePortion for test: 'invalid'"
- * ```
- *
- * @example Partial metadata (some fields missing)
- * ```typescript
- * const pool = {
- *   tokenName: 'partial',
- *   vaultAddress: 'service|...'
- *   // No RBC fee data
- * };
- *
- * const metadata = extractMetadataFromPoolData(pool);
- * // Returns: { vaultAddress: 'service|...' }
- * ```
- */
-export declare function extractMetadataFromPoolData(pool: PoolDataForCaching, logger?: {
-    debug: (message: string) => void;
-}): Partial<BondingCurveCacheEntry> | null;
-/**
- * Validate pool data structure for cache warming
- *
- * Checks that pool data has required fields and correct types before attempting
- * metadata extraction. This prevents runtime errors from malformed API responses.
- *
- * @param pool - Pool data to validate
- * @returns True if pool data is valid for caching, false otherwise
- *
- * @example Valid pool data
- * ```typescript
- * const pool = { tokenName: 'anime', vaultAddress: '...' };
- * isValidPoolForCaching(pool); // true
- * ```
- *
- * @example Invalid pool data
- * ```typescript
- * const badPool = { vaultAddress: '...' }; // Missing tokenName
- * isValidPoolForCaching(badPool); // false
- * ```
- */
-export declare function isValidPoolForCaching(pool: unknown): pool is PoolDataForCaching;
-//# sourceMappingURL=cacheWarmingHelpers.d.ts.map

package/dist/src/utils/cacheWarmingHelpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cacheWarmingHelpers.d.ts","sourceRoot":"","sources":["../../../src/utils/cacheWarmingHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAG7E;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,gCAAgC,CAAC,EAAE,MAAM,CAAC;IAC1C,wEAAwE;IACxE,gCAAgC,CAAC,EAAE,MAAM,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,kBAAkB,EACxB,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC5C,OAAO,CAAC,sBAAsB,CAAC,GAAG,IAAI,CA6CxC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,kBAAkB,CAW/E"}

package/dist/src/utils/composite-pool-converter.d.ts

@@ -1,121 +0,0 @@
-/**
- * Composite Pool Data Converter
- *
- * Converts raw GalaChain GetCompositePool API responses into properly
- * typed objects with BigNumber conversions for offline calculations.
- *
- * Ported from offline-quote-example/quote-local.mjs createCompositePoolDtoFromResponse()
- *
- * ## Runtime Validation Strategy for Type Assertions
- *
- * This module uses strategic `as any` type assertions to work around dependency
- * version conflicts between @gala-chain/api and @gala-chain/dex. To mitigate
- * risks from type assertions, we employ the following validation strategy:
- *
- * ### Type Assertion Patterns Used
- * 1. **TokenBalance Construction** (lines 78-79, 82-83)
- *    - Assertion: `new TokenBalance(data as unknown)`
- *    - Reason: SDK may have different @gala-chain/api version than @gala-chain/dex
- *    - Runtime Validation: BigNumber.js validates numeric conversions on line 79
- *
- * 2. **TickData Property Assignment** (lines 67-72)
- *    - Assertion: `(tickDataInstance as unknown).propertyName = value`
- *    - Reason: TickData constructor only accepts 2 params; properties are set after
- *    - Runtime Validation: All values are either boolean or BigNumber conversions
- *
- * 3. **CompositePoolDto Construction** (lines 87-91)
- *    - Assertion: `token0Balance as unknown` and `token1Balance as unknown`
- *    - Reason: TokenBalance versions may differ between dependencies
- *    - Runtime Validation: BigNumber.js automatically validates during conversions
- *
- * ### Validation Guarantees
- * - **Numeric Conversions**: BigNumber.js throws when parsing invalid numbers (NaN checks)
- * - **Object Construction**: Pool, TickData, TokenBalance throw on constructor errors
- * - **Property Access**: Type assertions limited to isolated property assignments
- * - **API Contract**: Response structure validated via TypeScript type inference
- *
- * ### When This Strategy Breaks
- * If API response structure changes or contains unexpected data types, errors
- * will occur during BigNumber conversion or object construction with clear
- * error messages indicating what data was invalid.
- *
- * @packageDocumentation
- */
-import { CompositePoolDto } from '@gala-chain/dex';
-import type { CompositePoolDataResult, GetCompositePoolResponse } from '../types/composite-pool.dto';
-/**
- * Convert GetCompositePool API response to CompositePoolDto
- *
- * Critical conversions:
- * - All numeric string fields → BigNumber
- * - Raw tick data → TickData instances
- * - Raw balances → TokenBalance instances
- *
- * ## BigNumber Precision Strategy
- *
- * All numeric fields are converted to BigNumber.js for arbitrary precision arithmetic.
- * This is critical for DeFi operations where precision loss causes calculation errors.
- *
- * **Key Fields Converted:**
- * - Pool properties: sqrtPrice, grossPoolLiquidity, liquidity, feeGrowthGlobal0/1, protocolFees, maxLiquidityPerTick
- * - Tick data: liquidityNet, liquidityGross, feeGrowthOutside0/1
- * - Token balances: quantity field
- *
- * **Precision Characteristics:**
- * - BigNumber.js maintains arbitrary precision (no floating-point errors)
- * - Supports numbers beyond JavaScript's safe integer limit (2^53-1)
- * - Suitable for token amounts with 18+ decimals (GALA, GUSDC, etc.)
- * - No rounding errors in conversions between formats
- *
- * **Use Cases:**
- * - Bonding curve calculations (exponential formulas)
- * - Swap quote computations (multiplication/division intensive)
- * - Tick-based liquidity calculations (high precision required)
- * - Multi-step DeFi operations (error accumulation must be prevented)
- *
- * @param responseData Raw API response data
- * @returns Fully typed CompositePoolDto with BigNumber conversions
- * @throws Error if response data is invalid or missing required fields
- *
- * @example Offline quote calculation with BigNumber precision
- * ```typescript
- * const response = await axios.post(GCP_URL, getCompositePoolDto);
- * const compositePool = createCompositePoolDtoFromResponse(response.data.Data);
- *
- * // All numeric values are BigNumber instances
- * const sqrtPrice = compositePool.pool.sqrtPrice; // BigNumber - no precision loss
- * const liquidity = compositePool.pool.liquidity; // BigNumber - preserves full precision
- *
- * // Safe calculations without floating-point errors
- * const calculatedAmount = liquidity.times(sqrtPrice).dividedBy(someNumber);
- * // Result is still BigNumber with full precision
- * ```
- *
- * @example Accessing pool data safely
- * ```typescript
- * const pool = compositePool.pool;
- *
- * // All these are BigNumber instances - safe for math operations
- * console.log(pool.sqrtPrice.toString()); // Full precision string representation
- * console.log(pool.liquidity.toFixed(0)); // Fixed decimal format
- * console.log(pool.feeGrowthGlobal0.multipliedBy(2)); // Precise multiplication
- * ```
- */
-/**
- * RUNTIME VALIDATION NOTES:
- * This function uses `as any` type assertions only where necessary for dependency
- * compatibility. All type assertions are followed by runtime validation through:
- * - BigNumber construction (throws on NaN or invalid numbers)
- * - Object instantiation (Pool, TickData, TokenBalance throw on errors)
- * - Numeric field assignments (guaranteed via BigNumber.js precision)
- */
-export declare function createCompositePoolDtoFromResponse(responseData: GetCompositePoolResponse['Data']): CompositePoolDto;
-/**
- * Wrap CompositePoolDto with additional metadata
- *
- * @param compositePoolDto Converted CompositePoolDto
- * @param rawResponse Raw response data for reference
- * @returns CompositePoolDataResult with full metadata
- */
-export declare function wrapCompositePoolData(compositePoolDto: CompositePoolDto, _rawResponse: GetCompositePoolResponse['Data']): CompositePoolDataResult;
-//# sourceMappingURL=composite-pool-converter.d.ts.map

package/dist/src/utils/composite-pool-converter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"composite-pool-converter.d.ts","sourceRoot":"","sources":["../../../src/utils/composite-pool-converter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAKH,OAAO,EAAE,gBAAgB,EAAiB,MAAM,iBAAiB,CAAC;AAElE,OAAO,KAAK,EAAE,uBAAuB,EAAC,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAGpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,CAChD,YAAY,EAAE,wBAAwB,CAAC,MAAM,CAAC,GAC7C,gBAAgB,CAoIlB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,wBAAwB,CAAC,MAAM,CAAC,GAC7C,uBAAuB,CAczB"}

package/dist/src/utils/crypto-compat.d.ts

@@ -1,40 +0,0 @@
-/**
- * Crypto Compatibility Layer
- *
- * Provides browser-safe wrappers for Node.js crypto functions.
- * In Node.js: uses native crypto module
- * In Browser: uses fallback implementations (does NOT include crypto in bundle)
- *
- * Note: Crypto operations are tree-shaken in browser builds since
- * they're only used by Node.js-specific services (PoolStateManager, WrapService).
- *
- * @category Utilities
- * @since 3.6.3
- */
-/**
- * Generate a UUID v4 string
- * Works in both Node.js (via crypto.randomUUID) and browser (via fallback)
- *
- * @returns UUID v4 string (36 characters)
- * @example
- * ```typescript
- * const id = generateRandomUUID();
- * // Returns: "550e8400-e29b-41d4-a716-446655440000"
- * ```
- */
-export declare function generateRandomUUID(): string;
-/**
- * Create a SHA-256 hash and return first 16 characters as hex string
- * In Node.js: uses crypto.createHash for performance
- * In Browser: uses simple fallback (service tree-shaken in browser anyway)
- *
- * @param data - Data to hash
- * @returns First 16 characters of SHA-256 hash as hex string
- * @example
- * ```typescript
- * const hash = createHashString('pool-state-123');
- * // Returns: "a1b2c3d4e5f67890" (16-char hex string)
- * ```
- */
-export declare function createHashString(data: string): string;
-//# sourceMappingURL=crypto-compat.d.ts.map

package/dist/src/utils/crypto-compat.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"crypto-compat.d.ts","sourceRoot":"","sources":["../../../src/utils/crypto-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAqB3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAerD"}