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

package/dist/services/TokenResolverService.d.ts

@@ -0,0 +1,329 @@
+/**
+ * Token Resolver Service
+ *
+ * Centralized service for resolving token names to vault addresses and
+ * GalaChain token identifiers.
+ *
+ * ## CRITICAL: Never Guess TokenClassKey from TokenName!
+ *
+ * The relationship between token name and TokenClassKey is **NOT PREDICTABLE**:
+ *
+ * - `tokenName: "anime"` does NOT mean `type: "ANIME"` (could be "ANM", "ANIM", etc.)
+ * - The `additionalKey` contains the creator's ETH address - **impossible to guess**
+ * - The `type` is chosen by the token creator at launch time
+ *
+ * **ALWAYS use this service to resolve token names. Never construct TokenClassKey manually.**
+ *
+ * @example WRONG - Never do this:
+ * ```typescript
+ * // ❌ WRONG - This will FAIL for most tokens!
+ * const tokenClassKey = {
+ *   collection: "Token",
+ *   category: "Unit",
+ *   type: "ANIME",  // WRONG! Might be "ANM" or anything else
+ *   additionalKey: "???"  // IMPOSSIBLE to guess - it's an ETH address!
+ * };
+ * ```
+ *
+ * @example CORRECT - Always use the resolver:
+ * ```typescript
+ * // ✅ CORRECT - Use the resolver
+ * const tokenClassKey = await tokenResolver.resolveTokenClassKey('anime');
+ * // Returns: { collection: "Token", category: "Unit", type: "ANM", additionalKey: "eth:0x..." }
+ * ```
+ *
+ * Key Features:
+ * - Token name → vault address resolution
+ * - Token name → TokenClassKey resolution
+ * - Deep caching (both vault address AND parsed TokenClassKey)
+ * - LRU eviction to bound memory usage
+ * - Service-to-service dependency (depends on PoolService)
+ * - Single responsibility: all token resolution logic in one place
+ *
+ * @packageDocumentation
+ */
+import type { TokenClassKey } from '../types/common';
+import { LoggerBase } from './BaseService';
+import type { PoolService } from './PoolService';
+/**
+ * Cache entry for deep caching of token resolution results.
+ *
+ * Stores both the vault address AND the parsed TokenClassKey to avoid
+ * re-parsing on subsequent calls.
+ */
+export interface TokenResolutionEntry {
+    /** GalaChain vault address (immutable after token creation) */
+    vaultAddress: string;
+    /** Parsed TokenClassKey from the vault address */
+    tokenClassKey: TokenClassKey;
+    /** Unix timestamp (ms) when this entry was cached */
+    cachedAt: number;
+}
+/**
+ * Cache statistics for monitoring and debugging.
+ */
+export interface TokenCacheStats {
+    /** Number of entries currently in cache */
+    size: number;
+    /** All cached token names (normalized to lowercase) */
+    keys: string[];
+    /** Maximum cache size before LRU eviction */
+    maxSize: number;
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Cache hit rate (hits / total lookups) */
+    hitRate: number;
+    /** Oldest entry timestamp (ms), or null if empty */
+    oldestEntry: number | null;
+    /** Newest entry timestamp (ms), or null if empty */
+    newestEntry: number | null;
+}
+/**
+ * Service for resolving token names to vault addresses and GalaChain identifiers
+ *
+ * ## CRITICAL: TokenClassKey is NOT Derivable from TokenName!
+ *
+ * **NEVER guess or manually construct a TokenClassKey from a token name.**
+ *
+ * The relationship is NOT predictable because:
+ * - Token creators choose the `type` at launch time (e.g., "anime" might use "ANM")
+ * - The `additionalKey` contains the creator's ETH address (impossible to guess)
+ * - Only the backend knows the actual TokenClassKey for a given token name
+ *
+ * **ALWAYS use this service to resolve token names.**
+ *
+ * This service encapsulates all token resolution logic and provides
+ * intelligent deep caching to minimize API calls and avoid re-parsing.
+ * Since vault addresses are immutable after token creation, they can be
+ * safely cached indefinitely.
+ *
+ * @example
+ * ```typescript
+ * const poolService = new PoolService(httpClient);
+ * const tokenResolver = new TokenResolverService(poolService);
+ *
+ * // Resolve token name to vault address
+ * const vaultAddress = await tokenResolver.resolveTokenToVault('dragnrkti');
+ * console.log('Vault:', vaultAddress);
+ *
+ * // Resolve token name to GalaChain TokenClassKey
+ * const tokenClassKey = await tokenResolver.resolveTokenClassKey('dragnrkti');
+ * console.log('Token:', tokenClassKey);
+ *
+ * // Second call returns cached TokenClassKey (no re-parsing!)
+ * const sameKey = await tokenResolver.resolveTokenClassKey('dragnrkti');
+ * console.log(tokenClassKey === sameKey); // true (same reference!)
+ * ```
+ */
+export declare class TokenResolverService extends LoggerBase {
+    private readonly poolService;
+    /**
+     * Maximum number of entries in the cache before LRU eviction kicks in.
+     * Set to 10,000 which handles most production use cases while
+     * bounding memory usage to ~2-5MB.
+     */
+    private static readonly MAX_CACHE_SIZE;
+    /**
+     * Deep cache for token resolution results.
+     * Key: normalized (lowercase) token name
+     * Value: TokenResolutionEntry with both vault address and parsed TokenClassKey
+     */
+    private cache;
+    /**
+     * LRU tracking: ordered list of keys from oldest to newest access.
+     * When cache exceeds MAX_CACHE_SIZE, oldest entries are evicted.
+     */
+    private accessOrder;
+    /**
+     * Cache statistics for monitoring
+     */
+    private cacheHits;
+    private cacheMisses;
+    /**
+     * Creates a new TokenResolverService instance
+     *
+     * @param poolService PoolService instance for resolving token names to vault addresses
+     * @param debugMode Enable debug logging (default: false)
+     */
+    constructor(poolService: PoolService, debugMode?: boolean);
+    /**
+     * Resolves a token name to its vault address
+     *
+     * This method checks the deep cache first, and only makes an API call if needed.
+     * Since vault addresses never change after token creation, successful
+     * resolutions are cached indefinitely.
+     *
+     * @param tokenName Token name to resolve (case-insensitive)
+     * @returns Promise<string | null> Vault address if found, null if token doesn't exist
+     * @throws {ValidationError} If tokenName is invalid
+     *
+     * @example
+     * ```typescript
+     * const vaultAddress = await tokenResolver.resolveTokenToVault('dragnrkti');
+     * if (vaultAddress) {
+     *   console.log('Vault address:', vaultAddress);
+     * } else {
+     *   console.log('Token not found');
+     * }
+     * ```
+     */
+    resolveTokenToVault(tokenName: string): Promise<string | null>;
+    /**
+     * Resolves a token name to GalaChain TokenClassKey format
+     *
+     * ## CRITICAL: Never Guess TokenClassKey from TokenName!
+     *
+     * The relationship between token name and TokenClassKey is **NOT PREDICTABLE**:
+     * - `tokenName: "anime"` does NOT mean `type: "ANIME"` (could be "ANM", "ANIM", etc.)
+     * - The `additionalKey` contains the creator's ETH address - **impossible to guess**
+     *
+     * **ALWAYS use this method. Never construct TokenClassKey manually from a token name.**
+     *
+     * This method uses deep caching - the TokenClassKey is parsed once and cached,
+     * so subsequent calls return the exact same object reference (no re-parsing).
+     *
+     * @param tokenName Token name to resolve
+     * @returns Promise<TokenClassKey> GalaChain token identifier (cached - same reference on repeated calls)
+     * @throws {Error} If token cannot be resolved or vault address is invalid
+     *
+     * @example
+     * ```typescript
+     * // ✅ CORRECT - Always use this resolver
+     * const tokenClassKey = await tokenResolver.resolveTokenClassKey('anime');
+     * console.log('Collection:', tokenClassKey.collection);
+     * console.log('Category:', tokenClassKey.category);
+     * console.log('Type:', tokenClassKey.type);  // Might be "ANM", NOT "ANIME"!
+     * console.log('Additional Key:', tokenClassKey.additionalKey);  // eth:0x... (creator address)
+     *
+     * // Second call returns cached reference (no re-parsing, instant)
+     * const sameKey = await tokenResolver.resolveTokenClassKey('anime');
+     * console.log(tokenClassKey === sameKey);  // true - exact same object!
+     * ```
+     *
+     * @example WRONG - Never do this:
+     * ```typescript
+     * // ❌ WRONG - This will FAIL for most tokens!
+     * const tokenClassKey = {
+     *   collection: "Token",
+     *   category: "Unit",
+     *   type: "ANIME",        // WRONG! Might be "ANM" or anything
+     *   additionalKey: "???"  // IMPOSSIBLE to guess!
+     * };
+     * ```
+     */
+    resolveTokenClassKey(tokenName: string): Promise<TokenClassKey>;
+    /**
+     * Gets cached vault address for a token name
+     *
+     * @param tokenName Token name to lookup (case-insensitive)
+     * @returns Cached vault address or null if not in cache
+     */
+    get(tokenName: string): string | null;
+    /**
+     * Gets the full cache entry for a token name
+     *
+     * @param normalizedTokenName Normalized (lowercase) token name
+     * @returns Cached entry or null if not in cache
+     */
+    private getCacheEntry;
+    /**
+     * Sets a cache entry and manages LRU eviction
+     *
+     * @param normalizedTokenName Normalized (lowercase) token name
+     * @param entry Cache entry to store
+     */
+    private setCacheEntry;
+    /**
+     * Updates LRU access order for a key
+     *
+     * @param normalizedTokenName Key that was just accessed
+     */
+    private updateAccessOrder;
+    /**
+     * Evicts the least recently used entry from the cache
+     */
+    private evictOldestEntry;
+    /**
+     * Caches a vault address for a token name (legacy method, kept for backward compatibility)
+     *
+     * @param tokenName Token name to cache (will be normalized to lowercase)
+     * @param vaultAddress Vault address to cache
+     */
+    set(tokenName: string, vaultAddress: string): void;
+    /**
+     * Clears the entire cache and resets statistics
+     *
+     * Useful for testing or when you need to force fresh token resolution.
+     */
+    clear(): void;
+    /**
+     * Gets detailed cache statistics for monitoring and debugging
+     *
+     * @returns Object with cache size, keys, hit rate, and timing info
+     */
+    getStats(): TokenCacheStats;
+    /**
+     * Gets the cached TokenClassKey directly without re-resolving
+     *
+     * @param tokenName Token name to lookup (case-insensitive)
+     * @returns Cached TokenClassKey or null if not in cache
+     */
+    getCachedTokenClassKey(tokenName: string): TokenClassKey | null;
+    /**
+     * Pre-warms the cache with known tokenName → vaultAddress mappings
+     *
+     * Useful for batch operations or initialization when you already
+     * know vault addresses for certain tokens. This method will parse
+     * each vault address to also cache the TokenClassKey (deep caching).
+     *
+     * @param mappings Array of {tokenName, vaultAddress} objects
+     *
+     * @example
+     * ```typescript
+     * tokenResolver.preWarm([
+     *   { tokenName: 'dragnrkti', vaultAddress: 'service|Token$Unit$...' },
+     *   { tokenName: 'rocketri', vaultAddress: 'service|Token$Unit$...' }
+     * ]);
+     * ```
+     */
+    preWarm(mappings: Array<{
+        tokenName: string;
+        vaultAddress: string;
+    }>): void;
+    /**
+     * Pre-warms the cache with known tokenName → TokenClassKey mappings
+     *
+     * More direct than preWarm() when you already have the TokenClassKey.
+     * Avoids parsing the vault address when not needed.
+     *
+     * @param mappings Array of {tokenName, vaultAddress, tokenClassKey} objects
+     *
+     * @example
+     * ```typescript
+     * tokenResolver.preWarmWithTokenClassKey([
+     *   {
+     *     tokenName: 'dragnrkti',
+     *     vaultAddress: 'service|Token$Unit$DRG$eth:0x...$launchpad',
+     *     tokenClassKey: { collection: 'Token', category: 'Unit', type: 'DRG', additionalKey: 'eth:0x...' }
+     *   }
+     * ]);
+     * ```
+     */
+    preWarmWithTokenClassKey(mappings: Array<{
+        tokenName: string;
+        vaultAddress: string;
+        tokenClassKey: TokenClassKey;
+    }>): void;
+    /**
+     * Parses a vault address string to extract TokenClassKey components
+     *
+     * @private
+     * @param vaultAddress Vault address in format "service|Token$Unit$SYMBOL$eth:address$launchpad"
+     * @returns TokenClassKey object
+     * @throws {Error} If vault address format is invalid
+     */
+    private parseVaultAddressToTokenClassKey;
+}
+//# sourceMappingURL=TokenResolverService.d.ts.map

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

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

package/dist/services/TradeService.d.ts

@@ -0,0 +1,286 @@
+/**
+ * Trade Service
+ *
+ * Handles all trade-related operations including trade history queries.
+ *
+ * @category Services
+ * @since 3.6.0
+ */
+import type { FetchTradesOptions } from '../types/options.dto';
+import type { TradesResult } from '../types/trade.dto';
+import type { GetTradesOptions, TradesQueryResult } from '../types/trades-query.dto';
+import type { HttpClient } from '../utils/http';
+import { BaseService } from './BaseService';
+/**
+ * Trade Service Class
+ *
+ * Provides methods for:
+ * - Fetching trade history with pagination
+ * - Filtering trades by token, user, type, date range
+ * - Trade statistics and analysis
+ * - Buy/sell volume tracking
+ *
+ * @category Services
+ * @since 3.6.0
+ *
+ * @example Basic trade history
+ * ```typescript
+ * const tradeService = new TradeService(httpClient);
+ *
+ * // Get first page of trades for a token
+ * const trades = await tradeService.fetchTrades({ tokenName: "anime" });
+ * console.log(`Found ${trades.totalResults} trades across ${trades.totalPages} pages`);
+ * ```
+ *
+ * @example Cursor-based pagination
+ * ```typescript
+ * // Fetch next page using cursor
+ * const moreTrades = await tradeService.fetchTrades({
+ *   tokenName: "GDOG",
+ *   cursor: "next_page_cursor",
+ *   pageSize: 20
+ * });
+ *
+ * // Process trades
+ * moreTrades.items.forEach(trade => {
+ *   console.log(`${trade.type}: ${trade.amount} at ${trade.price}`);
+ * });
+ * ```
+ *
+ * @example Filter by trade type
+ * ```typescript
+ * // Get only buy trades
+ * const buys = await tradeService.fetchTrades({
+ *   tokenName: "GUSDC",
+ *   tradeType: "buy",
+ *   pageSize: 50
+ * });
+ *
+ * // Calculate total buy volume
+ * const totalBuyVolume = buys.items.reduce((sum, t) => sum + parseFloat(t.amount), 0);
+ * ```
+ */
+export declare class TradeService extends BaseService {
+    /**
+     * Creates a TradeService instance
+     *
+     * @param http Configured HttpClient with authentication
+     * @param debugMode Enable debug logging (default: false)
+     *
+     * @example
+     * ```typescript
+     * const httpClient = new HttpClient(config);
+     * const tradeService = new TradeService(httpClient, true);
+     * ```
+     */
+    constructor(http: HttpClient, debugMode?: boolean);
+    /**
+     * Gets trades for a token by its tokenName with pagination
+     *
+     * Fetches trade history for a specific token with comprehensive pagination
+     * support. Returns normalized trade data with metadata including price,
+     * amount, timestamp, and trader information.
+     *
+     * This method provides a clean, intuitive API for fetching token trades
+     * using the token name. Follows the same pattern as CommentAPI for consistency.
+     *
+     * Response includes:
+     * - Trade details (type, amount, price, timestamp)
+     * - Trader addresses and wallet information
+     * - Transaction hashes for verification
+     * - Full pagination metadata (page, totalPages, hasNext, hasPrevious)
+     *
+     * Filtering options (optional):
+     * - tradeType: Filter by 'buy' or 'sell'
+     * - userAddress: Filter by specific trader
+     * - startDate/endDate: Filter by date range
+     * - sortOrder: Sort by timestamp (asc/desc)
+     *
+     * @param options Trade fetching options
+     * @param options.tokenName Token name to fetch trades for (required)
+     * @param options.cursor Cursor for pagination (optional)
+     * @param options.pageSize Results per page (default: 10, max: 100)
+     * @param options.tradeType Filter by trade type ('buy' | 'sell')
+     * @param options.userAddress Filter by trader address
+     * @param options.startDate Filter by start date
+     * @param options.endDate Filter by end date
+     * @param options.sortOrder Sort order ('asc' | 'desc')
+     * @returns Promise resolving to trades with full pagination metadata
+     * @throws {ValidationError} If token name is invalid or empty
+     * @throws {ValidationError} If options object is invalid format
+     * @throws {ValidationError} If pagination parameters are invalid
+     * @throws {ValidationError} If no response from trade service
+     *
+     * @category Trade Operations
+     * @since 3.6.0
+     *
+     * @example Basic trade history
+     * ```typescript
+     * const result = await tradeService.fetchTrades({ tokenName: "anime" });
+     *
+     * console.log(`Page ${result.page} of ${result.totalPages}`);
+     * console.log(`Total trades: ${result.totalResults}`);
+     *
+     * result.trades.forEach(trade => {
+     *   console.log(`${trade.type}: ${trade.amount} @ ${trade.price} GALA`);
+     *   console.log(`Trader: ${trade.traderAddress}`);
+     *   console.log(`Time: ${new Date(trade.timestamp).toLocaleString()}`);
+     * });
+     * ```
+     *
+     * @example Paginated trade fetching
+     * ```typescript
+     * const pageSize = 20;
+     * let cursor: string | undefined;
+     * const allTrades = [];
+     *
+     * while (true) {
+     *   const result = await tradeService.fetchTrades({
+     *     tokenName: "GDOG",
+     *     cursor,
+     *     pageSize
+     *   });
+     *
+     *   allTrades.push(...result.trades);
+     *   if (!result.pageInfo.hasNextPage) break;
+     *   cursor = result.pageInfo.nextCursor;
+     * }
+     *
+     * console.log(`Fetched ${allTrades.length} total trades`);
+     * ```
+     *
+     * @example Filter by trade type
+     * ```typescript
+     * // Get only buy trades
+     * const buys = await tradeService.fetchTrades({
+     *   tokenName: "GUSDC",
+     *   tradeType: "buy",
+     *   limit: 50
+     * });
+     *
+     * // Calculate total buy volume
+     * const totalBuyVolume = buys.trades.reduce(
+     *   (sum, trade) => sum + parseFloat(trade.amount),
+     *   0
+     * );
+     * console.log(`Total buy volume: ${totalBuyVolume} GUSDC`);
+     * ```
+     *
+     * @example Filter by date range
+     * ```typescript
+     * const startDate = new Date('2025-01-01');
+     * const endDate = new Date('2025-01-31');
+     *
+     * const januaryTrades = await tradeService.fetchTrades({
+     *   tokenName: "anime",
+     *   startDate,
+     *   endDate,
+     *   limit: 100
+     * });
+     *
+     * console.log(`January trades: ${januaryTrades.totalResults}`);
+     * ```
+     *
+     * @example Filter by user address
+     * ```typescript
+     * const userTrades = await tradeService.fetchTrades({
+     *   tokenName: "GDOG",
+     *   userAddress: "eth|0x123...",
+     *   limit: 100
+     * });
+     *
+     * console.log(`User has ${userTrades.totalResults} trades`);
+     *
+     * // Calculate user P&L
+     * let totalSpent = 0;
+     * let totalReceived = 0;
+     *
+     * userTrades.trades.forEach(trade => {
+     *   const value = parseFloat(trade.amount) * parseFloat(trade.price);
+     *   if (trade.type === 'buy') {
+     *     totalSpent += value;
+     *   } else {
+     *     totalReceived += value;
+     *   }
+     * });
+     *
+     * console.log(`P&L: ${totalReceived - totalSpent} GALA`);
+     * ```
+     */
+    fetchTrades(options: FetchTradesOptions): Promise<TradesResult>;
+    /**
+     * Build query parameters for trades endpoint
+     * Uses offset-based pagination matching backend API contract.
+     */
+    private buildTradesQueryParams;
+    /**
+     * Get trades with flexible filtering (v6.2.0+)
+     *
+     * Public endpoint - no authentication required.
+     * Filter by tokenName, userAddress, or both.
+     * At least one filter is required.
+     *
+     * This is the unified trades endpoint that replaces the legacy
+     * token-only fetchTrades method for more flexible querying.
+     *
+     * @param options Query options with tokenName and/or userAddress, offset-based pagination
+     * @returns Paginated list of trades with metadata
+     * @throws ValidationError if neither tokenName nor userAddress provided
+     * @throws ValidationError if options contain invalid values
+     *
+     * @category Trade Operations
+     * @since 6.2.0
+     * @updated 7.0.0 - Migrated from page-based to offset-based pagination
+     *
+     * @example Get all trades for a token
+     * ```typescript
+     * const { trades, meta } = await tradeService.getTrades({
+     *   tokenName: 'anime'
+     * });
+     * console.log(`Found ${meta.totalItems} trades`);
+     * trades.forEach(trade => {
+     *   console.log(`${trade.txnType}: ${trade.inputAmount} -> ${trade.outputAmount}`);
+     * });
+     * ```
+     *
+     * @example Get all trades by a user
+     * ```typescript
+     * const { trades, meta } = await tradeService.getTrades({
+     *   userAddress: 'eth|1234567890abcdef...'
+     * });
+     * console.log(`User has ${meta.totalItems} trades across all tokens`);
+     * ```
+     *
+     * @example Get a user's trades on a specific token with pagination
+     * ```typescript
+     * const { trades, meta } = await tradeService.getTrades({
+     *   tokenName: 'anime',
+     *   userAddress: 'eth|1234567890abcdef...',
+     *   offset: 20,
+     *   limit: 20
+     * });
+     * console.log(`Offset ${meta.offset} with ${meta.totalPages} total pages`);
+     * ```
+     *
+     * @example Calculate trading volume for a user
+     * ```typescript
+     * const result = await tradeService.getTrades({
+     *   userAddress: 'eth|1234567890abcdef...',
+     *   limit: 50
+     * });
+     *
+     * let totalBought = 0;
+     * let totalSold = 0;
+     * for (const trade of result.trades) {
+     *   if (trade.txnType === 'BUY') {
+     *     totalBought += trade.outputAmount;
+     *   } else {
+     *     totalSold += trade.inputAmount;
+     *   }
+     * }
+     * console.log(`Bought: ${totalBought} tokens, Sold: ${totalSold} tokens`);
+     * ```
+     */
+    getTrades(options: GetTradesOptions): Promise<TradesQueryResult>;
+}
+//# sourceMappingURL=TradeService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TradeService.d.ts","sourceRoot":"","sources":["../../src/services/TradeService.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AAE9D,OAAO,KAAK,EAGV,YAAY,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,gBAAgB,EAEhB,iBAAiB,EAAC,MAAM,2BAA2B,CAAC;AAOtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAMhD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBAAa,YAAa,SAAQ,WAAW;IAC3C;;;;;;;;;;;OAWG;gBACS,IAAI,EAAE,UAAU,EAAE,SAAS,GAAE,OAAe;IAIxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoIG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAuErE;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAsD9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmEG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAgBvE"}