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

package/dist/services/DexQuoteService.d.ts

@@ -0,0 +1,446 @@
+/**
+ * DEX Quote Service
+ *
+ * Handles offline and online DEX quote calculations using composite pool data.
+ * Provides three calculation modes:
+ * - LOCAL: Client-side calculation (instant, no network)
+ * - EXTERNAL: GalaChain network calculation (real-time, slower)
+ * - HYBRID: Local with external validation (best of both)
+ *
+ * @packageDocumentation
+ */
+import type { CalculateDexPoolQuoteOptions, CompositePoolDataResult, DexPoolQuoteResult, FetchCompositePoolDataOptions } from '../types/composite-pool.dto';
+import type { HttpClient } from '../utils/http';
+import { BaseService } from './BaseService';
+/**
+ * Concurrency constant for parallel composite pool fetching
+ */
+export declare const COMPOSITE_POOL_FETCH_CONCURRENCY = 5;
+/**
+ * Service for DEX quote calculations with composite pool data
+ *
+ * Provides offline and online quote calculations using composite pool state from GalaChain.
+ * Handles dependency version conflicts between @gala-chain/api and @gala-chain/dex through
+ * strategic type assertions validated by BigNumber.js runtime conversions.
+ *
+ * ## Dependency Version Management
+ *
+ * **Version Conflicts:**
+ * - `@gala-chain/api`: Used for TokenBalance class (imported from this package)
+ * - `@gala-chain/dex`: Used for Pool, TickData, CompositePoolDto classes
+ * - **Issue**: SDK may depend on different versions of @gala-chain/api than @gala-chain/dex
+ * - **Solution**: Type assertions with runtime validation via BigNumber.js
+ *
+ * **Current Dependency Stack:**
+ * ```
+ * SDK
+ * ├── @gala-chain/api@X.Y.Z (TokenBalance)
+ * ├── @gala-chain/dex@A.B.C (Pool, TickData, CompositePoolDto)
+ * ├── @gala-chain/connect (GalaChain client)
+ * └── axios (HTTP requests)
+ *
+ * Potential Conflict: @gala-chain/dex depends on different @gala-chain/api version
+ * ```
+ *
+ * **Type Assertion Patterns:**
+ * 1. **TokenBalance Construction** - `new TokenBalance(data as unknown)`
+ *    - Reason: TokenBalance class definition may differ between versions
+ *    - Validation: Constructor throws on invalid data
+ *
+ * 2. **Property Assignment** - `(instance as unknown).propertyName = value`
+ *    - Reason: TickData constructor only accepts 2 params; properties set after
+ *    - Validation: All assignments use BigNumber.js conversion or primitives
+ *
+ * 3. **CompositePoolDto Construction** - Passing TokenBalance instances
+ *    - Reason: TokenBalance types may not match exactly between versions
+ *    - Validation: BigNumber.js validates all numeric conversions
+ *
+ * **Risk Mitigation:**
+ * - ✓ BigNumber.js throws immediately on invalid numbers (NaN, non-numeric strings)
+ * - ✓ Pool, TickData, TokenBalance constructors throw on structural errors
+ * - ✓ All numeric fields converted to BigNumber before use
+ * - ✓ String-to-number conversions validated at instantiation time
+ *
+ * @category GSwap
+ * @since 3.32.0
+ * @architecture Uses composition and dependency injection for testability
+ * @note Type assertions are isolated to conversion functions; business logic uses proper types
+ */
+export declare class DexQuoteService extends BaseService {
+    private readonly galaChainBaseUrl;
+    private compositePoolFetchConcurrency;
+    /**
+     * Initialize DEX Quote Service
+     *
+     * @param http HttpClient for GalaChain requests
+     * @param galaChainBaseUrl Base URL for GalaChain gateway
+     * @param debugMode Enable debug logging
+     * @param networkTimeout Network timeout in milliseconds (default: 30000ms)
+     * @example
+     * ```typescript
+     * // Use default 30-second timeout
+     * const service = new DexQuoteService(http, galaChainBaseUrl, false);
+     *
+     * // Use custom 60-second timeout for rate-limited APIs
+     * const service = new DexQuoteService(http, galaChainBaseUrl, false, 60000);
+     * ```
+     */
+    constructor(http: HttpClient, galaChainBaseUrl: string, debugMode?: boolean, _networkTimeout?: number);
+    /**
+     * Validate input parameters for fetchCompositePoolData
+     *
+     * Ensures tokens follow pipe-delimited format (collection|category|type|additionalKey)
+     * and fee tier is one of the three supported values.
+     *
+     * @private
+     * @param token0 First token in pipe-delimited format
+     * @param token1 Second token in pipe-delimited format
+     * @param fee Fee tier (500, 3000, or 10000)
+     * @throws DexQuoteError if validation fails
+     * @category Validation
+     * @since 3.32.0
+     */
+    private validateFetchCompositePoolDataInput;
+    /**
+     * Validate input parameters for quote calculation methods
+     *
+     * Ensures amount is a positive numeric string suitable for BigNumber conversion.
+     * Rejects NaN, Infinity, negative values, and non-numeric strings.
+     *
+     * @private
+     * @param amount Amount to validate (should be positive numeric string)
+     * @throws DexQuoteError if validation fails
+     * @category Validation
+     * @since 3.32.0
+     */
+    private validateQuoteAmount;
+    /**
+     * Convert SDK TokenClassKey to DexTokenClassKey for @gala-chain/dex
+     *
+     * Bridges dependency version conflicts between @gala-chain/api and @gala-chain/dex
+     * by creating a new DexTokenClassKey instance with copied field values.
+     *
+     * @private
+     * @param tokenKey SDK TokenClassKey
+     * @returns DexTokenClassKey for use with @gala-chain/dex
+     * @category Type Conversion
+     * @since 3.32.0
+     */
+    private convertTokenClassKey;
+    /**
+     * Set concurrency level for parallel composite pool fetching
+     *
+     * Controls how many composite pool data requests can be in-flight simultaneously.
+     * Higher values fetch pools faster but use more network connections. Lower values
+     * use fewer connections but take longer to fetch multiple pools.
+     *
+     * **Default**: 5 concurrent requests
+     * **Valid Range**: 1-20 (values outside this range are clamped)
+     *
+     * @param concurrency Number of concurrent requests (automatically clamped to 1-20)
+     *
+     * @example Default usage
+     * ```typescript
+     * // Fetch 3 pools with default concurrency (5)
+     * const pools = await Promise.all([
+     *   sdk.fetchCompositePoolData({ token0: 'GALA|Unit|none|none', token1: 'Token|Unit|BENE|client:123', fee: 3000 }),
+     *   sdk.fetchCompositePoolData({ token0: 'GALA|Unit|none|none', token1: 'Token|Unit|USDC|eth:0x...', fee: 500 }),
+     *   sdk.fetchCompositePoolData({ token0: 'Token|Unit|BENE|client:123', token1: 'Token|Unit|USDC|eth:0x...', fee: 3000 }),
+     * ]);
+     * ```
+     *
+     * @example Increase concurrency for faster bulk fetching
+     * ```typescript
+     * // Optimize for fetching many pools (trading bot scenario)
+     * service.setCompositePoolFetchConcurrency(15);
+     *
+     * const pools = await Promise.all(
+     *   tokenPairs.map(pair => sdk.fetchCompositePoolData(pair))
+     * );
+     * ```
+     *
+     * @example Decrease concurrency for rate-limited APIs
+     * ```typescript
+     * // Optimize for rate-limited GalaChain gateways
+     * service.setCompositePoolFetchConcurrency(2);
+     *
+     * // Fetch pools one-by-one (slow but respects rate limits)
+     * for (const pair of tokenPairs) {
+     *   const composite = await sdk.fetchCompositePoolData(pair);
+     *   processPool(composite);
+     * }
+     * ```
+     *
+     * @example Reset to default
+     * ```typescript
+     * // Reset concurrency back to default (5)
+     * service.setCompositePoolFetchConcurrency(5);
+     * ```
+     */
+    setCompositePoolFetchConcurrency(concurrency: number): void;
+    /**
+     * Fetch composite pool data from GalaChain
+     *
+     * Retrieves complete pool state including liquidity, price, tick data, and token balances.
+     * This data enables instant LOCAL quote calculations without additional network calls.
+     *
+     * **Performance Strategy:**
+     * - Fetch once → calculate 100+ quotes locally (instant, no network latency)
+     * - Network cost: ~100-500ms per fetch
+     * - Local quote cost: <1ms per calculation
+     *
+     * **Returned Data:**
+     * - Pool: liquidity, sqrtPriceX96, tick, feeGrowth
+     * - Ticks: liquidity deltas at each price point
+     * - Token balances: decimals, balances for fee calculations
+     * - Metadata: fee tier, token addresses
+     *
+     * @param options Composite pool fetch options (token0/token1 in pipe-delimited format)
+     * @returns Complete composite pool data for offline quote calculations
+     * @throws DexPoolNotFoundError if pool does not exist
+     * @throws DexQuoteError on API or conversion errors
+     * @category Pool Data
+     * @since 3.32.0
+     *
+     * @example Basic fetch
+     * ```typescript
+     * const compositePool = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:123',
+     *   fee: 3000  // 0.30%
+     * });
+     * console.log('Pool liquidity:', compositePool.pool.liquidity.toString());
+     * ```
+     *
+     * @example Reuse for multiple quotes (recommended pattern)
+     * ```typescript
+     * // Fetch once
+     * const composite = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:123',
+     *   fee: 3000
+     * });
+     *
+     * // Calculate many quotes locally (instant!)
+     * const quotes = await Promise.all([
+     *   sdk.calculateDexPoolQuoteExactAmountLocal({ compositePoolData: composite, amount: '100', ... }),
+     *   sdk.calculateDexPoolQuoteExactAmountLocal({ compositePoolData: composite, amount: '500', ... }),
+     *   sdk.calculateDexPoolQuoteExactAmountLocal({ compositePoolData: composite, amount: '1000', ... }),
+     * ]);
+     * ```
+     */
+    fetchCompositePoolData(options: FetchCompositePoolDataOptions): Promise<CompositePoolDataResult>;
+    /**
+     * Calculate DEX pool quote using LOCAL client-side calculation (instant, offline)
+     *
+     * Uses concentrated liquidity mathematics with pre-fetched composite pool data for
+     * instant quote calculations without network calls. Based on Uniswap V3 concentrated
+     * liquidity model with tick-based ranges.
+     *
+     * **Calculation Mode: LOCAL (Offline)**
+     * - Speed: <1ms per quote (instant)
+     * - Network: Zero network calls
+     * - Accuracy: Based on cached pool state (may be seconds stale)
+     * - Use case: UI quotes, bulk pricing, simulations
+     *
+     * **How Concentrated Liquidity Works:**
+     * Unlike constant product (x × y = k), concentrated liquidity allows:
+     * - Liquidity providers to set price ranges (via ticks)
+     * - Higher capital efficiency within active ranges
+     * - Price moves through discrete ticks, not smooth curve
+     * - Each tick has liquidity delta (added/removed at that price)
+     *
+     * **Quote Calculation Process:**
+     * 1. Determine swap direction (zeroForOne: token0 → token1 or reverse)
+     * 2. Traverse ticks from current price based on amount
+     * 3. Calculate output using sqrtPriceX96 (Q64.96 fixed-point)
+     * 4. Apply fee tier (0.05%, 0.30%, or 1.00%)
+     * 5. Return amounts and new price after swap
+     *
+     * **Result Fields:**
+     * - amount0: Input token amount (if zeroForOne) or output (if !zeroForOne)
+     * - amount1: Output token amount (if zeroForOne) or input (if !zeroForOne)
+     * - currentSqrtPrice: Current pool price (sqrt(price) × 2^96)
+     * - newSqrtPrice: Pool price after swap
+     *
+     * @param options Quote calculation options (must include compositePoolData)
+     * @returns Quote result with amounts and price data
+     * @throws DexQuoteError on calculation errors
+     * @category Quote Calculation
+     * @since 3.32.0
+     *
+     * @example Basic LOCAL quote
+     * ```typescript
+     * // Step 1: Fetch composite data (one network call)
+     * const composite = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:123',
+     *   fee: 3000
+     * });
+     *
+     * // Step 2: Calculate quote (instant, local)
+     * const quote = await sdk.calculateDexPoolQuoteExactAmountLocal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * });
+     * console.log(`Spend: ${quote.amount0} GALA`);
+     * console.log(`Receive: ${quote.amount1} BENE`);
+     * ```
+     *
+     * @example Reuse composite data for multiple quotes (recommended)
+     * ```typescript
+     * // Fetch once
+     * const composite = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:123',
+     *   fee: 3000
+     * });
+     *
+     * // Calculate many quotes locally (instant!)
+     * const quote1 = await sdk.calculateDexPoolQuoteExactAmountLocal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '100'
+     * });
+     *
+     * const quote2 = await sdk.calculateDexPoolQuoteExactAmountLocal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '5000'
+     * });
+     * // Both quotes calculated instantly using same cached pool state
+     * ```
+     */
+    calculateDexPoolQuoteExactAmountLocal(options: CalculateDexPoolQuoteOptions): Promise<DexPoolQuoteResult>;
+    /**
+     * Calculate DEX pool quote using EXTERNAL GalaChain network call (real-time, accurate)
+     *
+     * Fetches real-time quote from GalaChain using current pool state from the blockchain.
+     * Always accurate but adds network latency. Best for final verification before trading.
+     *
+     * **Calculation Mode: EXTERNAL (Real-time)**
+     * - Speed: 100-500ms per quote (network latency)
+     * - Network: One network call per quote
+     * - Accuracy: Current blockchain state (always fresh)
+     * - Use case: Final verification, trading execution, critical accuracy
+     *
+     * **When to Use EXTERNAL vs LOCAL:**
+     * - EXTERNAL: Before trade execution, when pool changes rapidly
+     * - LOCAL: UI quotes, bulk pricing, trading simulations
+     * - HYBRID: LOCAL for display, EXTERNAL for final confirmation
+     *
+     * **Network Call Details:**
+     * - Endpoint: `/api/asset/dexv3-contract/QuoteExactAmount`
+     * - Authentication: Requires wallet signature
+     * - Response: Direct quote from GalaChain concentrated liquidity math
+     *
+     * **Accuracy Trade-off:**
+     * - EXTERNAL: 100% accurate but slower (network roundtrip)
+     * - LOCAL: ~99.9% accurate but instant (pool state may be seconds old)
+     * - For most use cases: LOCAL is sufficient and significantly faster
+     *
+     * @param options Quote calculation options (must include compositePoolData for token info)
+     * @returns Quote result from chain
+     * @throws DexQuoteError on network or calculation errors
+     * @category Quote Calculation
+     * @since 3.32.0
+     *
+     * @example Real-time quote before trade
+     * ```typescript
+     * // Fetch composite data to get token ClassKeys
+     * const composite = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:123',
+     *   fee: 3000
+     * });
+     *
+     * // Get real-time quote from chain (100-500ms)
+     * const quote = await sdk.calculateDexPoolQuoteExactAmountExternal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * });
+     * console.log(`Real-time quote: ${quote.amount1} BENE`);
+     * ```
+     *
+     * @example HYBRID strategy (recommended for trading UIs)
+     * ```typescript
+     * // Fetch once
+     * const composite = await sdk.fetchCompositePoolData({ ... });
+     *
+     * // Display LOCAL quote to user (instant)
+     * const localQuote = await sdk.calculateDexPoolQuoteExactAmountLocal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: userInput
+     * });
+     * displayToUser(localQuote); // Instant feedback
+     *
+     * // Before executing trade, verify with EXTERNAL quote (accurate)
+     * const externalQuote = await sdk.calculateDexPoolQuoteExactAmountExternal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: userInput
+     * });
+     * executeTrade(externalQuote); // Final accuracy
+     * ```
+     */
+    calculateDexPoolQuoteExactAmountExternal(options: CalculateDexPoolQuoteOptions): Promise<DexPoolQuoteResult>;
+    /**
+     * Calculate DEX pool quote with automatic mode selection (LOCAL or EXTERNAL)
+     *
+     * Convenience method that delegates to local or external quote calculation based on
+     * mode parameter. Defaults to LOCAL (instant) for optimal performance.
+     *
+     * **Mode Comparison:**
+     * ```
+     * | Mode     | Speed  | Network | Accuracy | Use Case                |
+     * |----------|--------|---------|----------|-------------------------|
+     * | LOCAL    | <1ms   | None    | 99.9%    | UI, simulations, bulk   |
+     * | EXTERNAL | 100ms+ | Yes     | 100%     | Trade execution, verify |
+     * ```
+     *
+     * **Recommended Patterns:**
+     * - Default (no mode): Uses LOCAL for instant quotes
+     * - Trading UI: LOCAL for display, EXTERNAL before execution
+     * - Bulk pricing: Always use LOCAL (no reason for network calls)
+     * - Critical accuracy: Always use EXTERNAL
+     *
+     * @param options Quote calculation options
+     * @param mode 'local' (instant, default) or 'external' (real-time) - defaults to 'local'
+     * @returns Quote result
+     * @category Quote Calculation
+     * @since 3.32.0
+     *
+     * @example Default LOCAL mode
+     * ```typescript
+     * const quote = await sdk.calculateDexPoolQuoteExactAmount({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * });
+     * // Uses local calculation by default (instant)
+     * ```
+     *
+     * @example Explicit EXTERNAL mode for critical accuracy
+     * ```typescript
+     * const quote = await sdk.calculateDexPoolQuoteExactAmount({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * }, 'external');
+     * // Fetches real-time quote from chain
+     * ```
+     */
+    calculateDexPoolQuoteExactAmount(options: CalculateDexPoolQuoteOptions, mode?: 'local' | 'external'): Promise<DexPoolQuoteResult>;
+}
+//# sourceMappingURL=DexQuoteService.d.ts.map

package/dist/services/DexQuoteService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DexQuoteService.d.ts","sourceRoot":"","sources":["../../src/services/DexQuoteService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,KAAK,EACV,4BAA4B,EAC5B,uBAAuB,EACvB,kBAAkB,EAClB,6BAA6B,EAE9B,MAAM,6BAA6B,CAAC;AAQrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKhD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,6BAA6B,CAA4C;IAEjF;;;;;;;;;;;;;;;OAeG;gBAED,IAAI,EAAE,UAAU,EAChB,gBAAgB,EAAE,MAAM,EACxB,SAAS,GAAE,OAAe,EAC1B,eAAe,GAAE,MAAc;IAMjC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,mCAAmC;IA4C3C;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;;;;;;;;;;OAWG;IAEH,OAAO,CAAC,oBAAoB;IAU5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAO3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACG,sBAAsB,CAC1B,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC;IAkEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoFG;IACG,qCAAqC,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,kBAAkB,CAAC;IAmE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2EG;IACG,wCAAwC,CAC5C,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,kBAAkB,CAAC;IA+E9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+CG;IACG,gCAAgC,CACpC,OAAO,EAAE,4BAA4B,EACrC,IAAI,GAAE,OAAO,GAAG,UAAoB,GACnC,OAAO,CAAC,kBAAkB,CAAC;CAM/B"}