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

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

@@ -0,0 +1,446 @@
+/**
+ * BigNumber utility helpers for common calculations
+ *
+ * Consolidates repeated BigNumber patterns and operations to reduce
+ * code duplication across services, particularly in GSwapService.
+ *
+ * Common patterns extracted:
+ * - Slippage factor calculation
+ * - Min/max output calculation with slippage
+ * - Tick to sqrt ratio conversion (1.0001^(tick/2))
+ * - Price inversion
+ * - Safe BigNumber creation
+ *
+ * @internal
+ */
+import BigNumber from 'bignumber.js';
+/**
+ * Create a BigNumber from a numeric value with safe defaults
+ *
+ * @param value The value to convert
+ * @param defaultValue Value to use if input is null/undefined/zero-length string (default: "0")
+ * @returns BigNumber instance
+ *
+ * @example
+ * ```typescript
+ * const balance = toBigNumber(userData.balance || 0);
+ * const amount = toBigNumber(params.amount); // Uses "0" if undefined
+ * ```
+ */
+export declare function toBigNumber(value: string | number | BigNumber | null | undefined, defaultValue?: string | number): BigNumber;
+/**
+ * Create a BigNumber and immediately call toFixed()
+ *
+ * Convenience method for the pattern: `new BigNumber(value).toFixed()`
+ * Used for serializing calculated amounts back to strings.
+ *
+ * @param value The value to convert
+ * @param decimals Number of decimal places (default: undefined = max precision)
+ * @returns Fixed string representation
+ *
+ * @example
+ * ```typescript
+ * const minOutput = toBigNumberFixed(calculated, 6);  // "123.456789"
+ * const slippageAdjusted = toBigNumberFixed(amount.multipliedBy(0.99));
+ * ```
+ */
+export declare function toBigNumberFixed(value: string | number | BigNumber | null | undefined, decimals?: number): string;
+/**
+ * Calculate slippage-adjusted minimum output
+ *
+ * Consolidates the pattern:
+ * ```typescript
+ * const slippageFactor = new BigNumber(1).minus(slippageTolerance);
+ * const minOutput = estimatedOutput.multipliedBy(slippageFactor);
+ * ```
+ *
+ * @param estimatedOutput The estimated output amount
+ * @param slippageTolerance Slippage tolerance as decimal (e.g., 0.01 for 1%)
+ * @returns Minimum acceptable output after slippage
+ *
+ * @example
+ * ```typescript
+ * const quote = await sdk.getSwapQuote('GALA', 'GUSDC', '100');
+ * const minOutput = calculateSlippageAdjustedAmount(
+ *   quote.estimatedOutput,
+ *   0.01  // 1% slippage
+ * );
+ * await sdk.executeSwap(..., minOutput.toFixed());
+ * ```
+ */
+export declare function calculateSlippageAdjustedAmount(estimatedOutput: string | number | BigNumber, slippageTolerance?: number): BigNumber;
+/**
+ * Calculate slippage factor (1 - tolerance)
+ *
+ * Consolidates: `new BigNumber(1).minus(tolerance)`
+ * Used as multiplier for slippage calculations.
+ *
+ * @param tolerance Slippage tolerance as decimal (e.g., 0.01 for 1%)
+ * @returns Slippage factor (e.g., 0.99 for 1% tolerance)
+ *
+ * @example
+ * ```typescript
+ * const factor = calculateSlippageFactor(0.01);  // BigNumber(0.99)
+ * const minAmount = estimatedAmount.multipliedBy(factor);
+ * ```
+ */
+export declare function calculateSlippageFactor(tolerance?: number): BigNumber;
+/**
+ * Calculate inverse slippage factor (1 + tolerance)
+ *
+ * Consolidates: `new BigNumber(1).plus(tolerance)`
+ * Used for upper bound slippage calculations (e.g., maximum acceptable price).
+ *
+ * @param tolerance Slippage tolerance as decimal (e.g., 0.01 for 1%)
+ * @returns Inverse slippage factor (e.g., 1.01 for 1% tolerance)
+ *
+ * @example
+ * ```typescript
+ * const upperFactor = calculateInverseSlippageFactor(0.01);  // BigNumber(1.01)
+ * const maxPrice = currentPrice.multipliedBy(upperFactor);
+ * ```
+ */
+export declare function calculateInverseSlippageFactor(tolerance?: number): BigNumber;
+/**
+ * Convert a price to tick (Uniswap V3 math)
+ *
+ * Calculates the tick index from a price using the Uniswap V3 formula.
+ * Formula: tick = log_1.0001(price)
+ *
+ * Converts a human-readable price (e.g., "0.95", "1.05") to its corresponding
+ * Uniswap V3 tick index. Uses logarithmic calculation directly, WITHOUT Q96
+ * scaling (Q96 is only used for on-chain sqrtPrice encoding, not for human prices).
+ *
+ * @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)
+ *
+ * Consolidates: `new BigNumber(1).dividedBy(price)`
+ * Used for converting price direction (e.g., BTC/USD → USD/BTC).
+ *
+ * @param price The price to invert
+ * @param asFixed Whether to return as fixed string (default: false returns BigNumber)
+ * @returns Inverted price as BigNumber or string
+ *
+ * @example
+ * ```typescript
+ * const galuPrice = invertPrice('0.50');  // 2.0
+ * const displayPrice = invertPrice(price, true);  // "2.0" (string)
+ * ```
+ */
+export declare function invertPrice(price: string | number | BigNumber, asFixed?: boolean): BigNumber | string;
+/**
+ * Q96 constant for Uniswap V3 calculations (2^96)
+ *
+ * Consolidates: `new BigNumber(2).pow(96)`
+ * Used in tick-based liquidity calculations.
+ *
+ * @returns Q96 value as BigNumber
+ *
+ * @example
+ * ```typescript
+ * const Q96 = getQ96Constant();  // 2^96
+ * const adjustedPrice = sqrtPrice.multipliedBy(sqrtPrice).dividedBy(Q96);
+ * ```
+ */
+export declare function getQ96Constant(): BigNumber;
+/**
+ * Find minimum of two BigNumber values
+ *
+ * Convenience wrapper for `BigNumber.min()` with safe input handling.
+ *
+ * @param a First value
+ * @param b Second value
+ * @returns The minimum value as BigNumber
+ *
+ * @example
+ * ```typescript
+ * const liquidity0 = calculateFromAmount0(...);
+ * const liquidity1 = calculateFromAmount1(...);
+ * const optimalLiquidity = minBigNumber(liquidity0, liquidity1);
+ * ```
+ */
+export declare function minBigNumber(a: string | number | BigNumber, b: string | number | BigNumber): BigNumber;
+/**
+ * Find maximum of two BigNumber values
+ *
+ * Convenience wrapper for `BigNumber.max()` with safe input handling.
+ *
+ * @param a First value
+ * @param b Second value
+ * @returns The maximum value as BigNumber
+ *
+ * @example
+ * ```typescript
+ * const amount0 = parseFloat(poolData.amount0);
+ * const amount1 = parseFloat(poolData.amount1);
+ * const maxAmount = maxBigNumber(amount0, amount1);
+ * ```
+ */
+export declare function maxBigNumber(a: string | number | BigNumber, b: string | number | BigNumber): BigNumber;
+/**
+ * Check if a value is zero
+ *
+ * Safe check for zero with BigNumber precision.
+ *
+ * @param value The value to check
+ * @returns true if value equals 0
+ *
+ * @example
+ * ```typescript
+ * if (isZero(amount)) {
+ *   throw new Error('Amount cannot be zero');
+ * }
+ * ```
+ */
+export declare function isZero(value: string | number | BigNumber): boolean;
+/**
+ * Check if a value is positive
+ *
+ * @param value The value to check
+ * @returns true if value > 0
+ *
+ * @example
+ * ```typescript
+ * if (isPositive(balance)) {
+ *   // user has funds
+ * }
+ * ```
+ */
+export declare function isPositive(value: string | number | BigNumber): boolean;
+/**
+ * Check if a value is negative
+ *
+ * @param value The value to check
+ * @returns true if value < 0
+ */
+export declare function isNegative(value: string | number | BigNumber): boolean;
+/**
+ * Check if a value is greater than a threshold
+ *
+ * @param value The value to check
+ * @param threshold The threshold to compare against
+ * @returns true if value > threshold
+ *
+ * @example
+ * ```typescript
+ * if (isGreaterThan(balance, '0')) {
+ *   // user has funds
+ * }
+ * ```
+ */
+export declare function isGreaterThan(value: string | number | BigNumber, threshold: string | number | BigNumber): boolean;
+/**
+ * Check if a value is less than a threshold
+ *
+ * @param value The value to check
+ * @param threshold The threshold to compare against
+ * @returns true if value < threshold
+ *
+ * @example
+ * ```typescript
+ * if (isLessThan(balance, minRequired)) {
+ *   throw new Error('Insufficient balance');
+ * }
+ * ```
+ */
+export declare function isLessThan(value: string | number | BigNumber, threshold: string | number | BigNumber): boolean;
+/**
+ * Check if value is between two bounds (inclusive)
+ *
+ * @param value The value to check
+ * @param min Lower bound (inclusive)
+ * @param max Upper bound (inclusive)
+ * @returns true if min <= value <= max
+ *
+ * @example
+ * ```typescript
+ * if (isBetween(price, minPrice, maxPrice)) {
+ *   // price is in valid range
+ * }
+ * ```
+ */
+export declare function isBetween(value: string | number | BigNumber, min: string | number | BigNumber, max: string | number | BigNumber): boolean;
+/**
+ * Calculate percentage of a value
+ *
+ * @param value The base value
+ * @param percentage The percentage to calculate (e.g., 10 for 10%)
+ * @returns The percentage amount
+ *
+ * @example
+ * ```typescript
+ * const fee = calculatePercentage(amount, 0.3);  // 0.3% fee
+ * const netAmount = amount.minus(fee);
+ * ```
+ */
+export declare function calculatePercentage(value: string | number | BigNumber, percentage: number): BigNumber;
+/**
+ * Increase a value by a percentage
+ *
+ * @param value The base value
+ * @param percentage The percentage to increase (e.g., 10 for 10% increase)
+ * @returns The increased value
+ *
+ * @example
+ * ```typescript
+ * const withSlippage = increaseByPercentage(amount, 1);  // 1% increase
+ * ```
+ */
+export declare function increaseByPercentage(value: string | number | BigNumber, percentage: number): BigNumber;
+/**
+ * Decrease a value by a percentage
+ *
+ * @param value The base value
+ * @param percentage The percentage to decrease (e.g., 1 for 1% decrease)
+ * @returns The decreased value
+ *
+ * @example
+ * ```typescript
+ * const afterSlippage = decreaseByPercentage(amount, 1);  // 1% decrease
+ * ```
+ */
+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
+ * @internal
+ *
+ * @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
+ * @internal
+ *
+ * @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
+ * @internal
+ *
+ * @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;
+/**
+ * Safe division with fallback for zero denominator
+ *
+ * Prevents division by zero errors by returning a fallback value when
+ * the denominator is zero. Replaces the common pattern:
+ * `isZero(denominator) ? fallback : numerator.dividedBy(denominator)`
+ *
+ * @param numerator The dividend
+ * @param denominator The divisor
+ * @param fallback Value to return if denominator is zero (default: "0")
+ * @returns The quotient, or fallback if denominator is zero
+ *
+ * @example
+ * ```typescript
+ * // Calculate ratio with fallback
+ * const ratio = safeDivide(token0Amount, token1Amount, toBigNumber(0));
+ *
+ * // Use in slippage calculations
+ * const slippage = safeDivide(difference, originalAmount);
+ *
+ * // Pool calculations with custom fallback
+ * const fee = safeDivide(feeAmount, totalVolume, toBigNumber('0.0001'));
+ * ```
+ */
+export declare function safeDivide(numerator: string | number | BigNumber, denominator: 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`
+ *
+ * @param tick The tick value to round
+ * @param tickSpacing The tick spacing (e.g., 1, 10, 60, 200)
+ * @returns The rounded tick (multiple of tickSpacing)
+ *
+ * @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
+ * 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)`
+ *
+ * @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)
+ *
+ * @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);
+ * ```
+ */
+export declare function calculateScaledFeeAmount(baseAmount: string | number | BigNumber, feeFactor: number): BigNumber;
+//# sourceMappingURL=bignumber-helpers.d.ts.map

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

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

package/dist/utils/bignumber-pool-cache.d.ts

@@ -0,0 +1,169 @@
+import BigNumber from 'bignumber.js';
+/**
+ * Singleton BigNumber cache for performance optimization.
+ *
+ * Caches BigNumber instances to avoid repeated parsing of the same values.
+ * Typical savings: 2-5ms per swap operation by reusing instances.
+ *
+ * @example
+ * ```typescript
+ * // Use pre-cached constants
+ * const zero = BigNumberPoolCache.ZERO;
+ * const minLimit = BigNumberPoolCache.MIN_SQRT_RATIO;
+ *
+ * // Cache dynamic values
+ * const amount = BigNumberPoolCache.getCached('1000000');
+ * const amount2 = BigNumberPoolCache.getCached('1000000'); // Same instance!
+ *
+ * // Memory management (call periodically in long-running processes)
+ * BigNumberPoolCache.trimCache(1000); // Keep 1000 most recent entries
+ * ```
+ *
+ * @remarks
+ * Thread-safe for read operations (Map is thread-safe for reads).
+ * Cache grows unbounded unless trimCache() is called periodically.
+ *
+ * @see {@link https://github.com/Uniswap/v3-core/blob/main/contracts/libraries/TickMath.sol | Uniswap V3 TickMath}
+ */
+export declare class BigNumberPoolCache {
+    /**
+     * Internal cache storage (string key → BigNumber instance)
+     * @internal
+     */
+    private static readonly CACHE;
+    /**
+     * Pre-cached zero constant (most frequently used value)
+     * @constant
+     */
+    static readonly ZERO: BigNumber;
+    /**
+     * Pre-cached one constant (used in arithmetic operations)
+     * @constant
+     */
+    static readonly ONE: BigNumber;
+    /**
+     * Fee denominator for Uniswap V3 (1,000,000 = 1,000,000 pips)
+     * Used for fee calculations: actualFee = feeAmount / FEE_PIPS
+     * @constant
+     * @example
+     * ```typescript
+     * // Calculate 0.3% fee (3000 fee tier)
+     * const fee = new BigNumber(3000).div(BigNumberPoolCache.FEE_PIPS);
+     * // fee = 0.003 (0.3%)
+     * ```
+     */
+    static readonly FEE_PIPS: BigNumber;
+    /**
+     * Minimum sqrt price ratio (corresponds to tick -887272)
+     * Uniswap V3 boundary: sqrtPriceX96 cannot go below this value
+     * @constant
+     * @see {@link https://github.com/Uniswap/v3-core/blob/main/contracts/libraries/TickMath.sol#L10 | Uniswap V3 MIN_TICK}
+     */
+    static readonly MIN_SQRT_RATIO: BigNumber;
+    /**
+     * Maximum sqrt price ratio (corresponds to tick 887272)
+     * Uniswap V3 boundary: sqrtPriceX96 cannot exceed this value
+     * @constant
+     * @see {@link https://github.com/Uniswap/v3-core/blob/main/contracts/libraries/TickMath.sol#L13 | Uniswap V3 MAX_TICK}
+     */
+    static readonly MAX_SQRT_RATIO: BigNumber;
+    /**
+     * Get or create cached BigNumber instance.
+     *
+     * Returns the same instance for identical values (referential equality).
+     * Avoids redundant parsing overhead for frequently used values.
+     *
+     * @param value - Numeric value (string or number)
+     * @returns Cached BigNumber instance
+     *
+     * @example
+     * ```typescript
+     * const a = BigNumberPoolCache.getCached('1000');
+     * const b = BigNumberPoolCache.getCached('1000');
+     * console.log(a === b); // true (same instance)
+     *
+     * const c = BigNumberPoolCache.getCached(1000);
+     * console.log(a === c); // true (number coerced to string key)
+     * ```
+     *
+     * @remarks
+     * - Keys are normalized to strings via `.toString()`
+     * - Cache grows unbounded unless `trimCache()` is called
+     * - O(1) lookup complexity (Map hash table)
+     */
+    static getCached(value: string | number): BigNumber;
+    /**
+     * Clear the entire cache (removes all entries).
+     *
+     * Pre-cached constants (ZERO, ONE, etc.) remain unaffected as they
+     * are static properties, not cache entries.
+     *
+     * @example
+     * ```typescript
+     * BigNumberPoolCache.clearCache();
+     * console.log(BigNumberPoolCache.getCacheStats().size); // 0
+     *
+     * // Constants still work
+     * console.log(BigNumberPoolCache.ZERO.toString()); // "0"
+     * ```
+     *
+     * @remarks
+     * Use sparingly as it discards all cached performance benefits.
+     * Prefer `trimCache()` for periodic memory management.
+     */
+    static clearCache(): void;
+    /**
+     * Get cache statistics for monitoring and debugging.
+     *
+     * @returns Object containing cache size and entry keys
+     *
+     * @example
+     * ```typescript
+     * const stats = BigNumberPoolCache.getCacheStats();
+     * console.log(`Cache size: ${stats.size}`);
+     * console.log(`Keys: ${stats.entries.join(', ')}`);
+     * ```
+     *
+     * @remarks
+     * Useful for performance profiling and memory leak detection.
+     */
+    static getCacheStats(): {
+        size: number;
+        entries: string[];
+    };
+    /**
+     * Trim cache to maximum size (FIFO eviction strategy).
+     *
+     * Keeps the N most recently inserted entries, removes oldest entries.
+     * Designed for long-running processes (arbitrage bots, market makers).
+     *
+     * @param maxSize - Maximum cache entries to retain (default: 1000)
+     *
+     * @example
+     * ```typescript
+     * // Arbitrage bot memory management pattern
+     * let swapCount = 0;
+     * async function executeSwap(params: SwapParams) {
+     *   // ... swap logic using cached BigNumbers ...
+     *
+     *   swapCount++;
+     *   if (swapCount % 100 === 0) {
+     *     BigNumberPoolCache.trimCache(1000); // Keep 1000 hot values
+     *   }
+     * }
+     * ```
+     *
+     * @remarks
+     * - Evicts oldest entries first (Map insertion order preserved)
+     * - Recommended maxSize: 500-2000 for typical trading bots
+     * - Call after every 100-500 operations in hot loops
+     * - Does not affect pre-cached constants
+     */
+    static trimCache(maxSize?: number): void;
+}
+/**
+ * Default export for convenience
+ * @see {@link BigNumberPoolCache}
+ */
+export default BigNumberPoolCache;
+//# sourceMappingURL=bignumber-pool-cache.d.ts.map

package/dist/utils/bignumber-pool-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bignumber-pool-cache.d.ts","sourceRoot":"","sources":["../../src/utils/bignumber-pool-cache.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,cAAc,CAAC;AAKrC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,kBAAkB;IAC7B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAElE;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,YAAyB;IAE7C;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,YAAyB;IAE5C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,YAA+B;IAEvD;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,cAAc,YAAoC;IAElE;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,cAAc,YAE5B;IAEF;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUnD;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,UAAU,IAAI,IAAI;IAIzB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE;IAO3D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,SAAS,CAAC,OAAO,GAAE,MAAa,GAAG,IAAI;CAU/C;AAED;;;GAGG;AACH,eAAe,kBAAkB,CAAC"}