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

package/dist/services/TokenMetadataCache.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Token Metadata Cache Service
+ *
+ * High-performance in-memory cache for immutable token metadata, optimized for
+ * local bonding curve calculations. Eliminates redundant API calls by caching:
+ * - Reverse bonding curve fee factors (from fetchPools)
+ * - Custom maxSupply values (auto-detected, defaults to 10M constant)
+ * - Vault addresses (via TokenResolverService)
+ *
+ * Cache persistence: Entire MCP server lifetime (survives across conversations)
+ *
+ * @category Services
+ * @since 3.9.2
+ */
+import { AbstractCacheService, type BaseCacheStats } from './AbstractCacheService';
+/**
+ * Bonding curve cache entry
+ *
+ * Stores immutable token properties needed for local bonding curve calculations.
+ * All properties are optional - cache can be partially populated.
+ *
+ * @since 6.10.0 - Renamed from TokenMetadata for clarity (distinct from blockchain metadata)
+ */
+export interface BondingCurveCacheEntry {
+    /** Minimum reverse bonding curve fee factor (0.0 - 1.0) */
+    reverseBondingCurveMinFeeFactor?: number;
+    /** Maximum reverse bonding curve fee factor (0.0 - 1.0) */
+    reverseBondingCurveMaxFeeFactor?: number;
+    /** Net reverse bonding curve fee factor (max - min) */
+    reverseBondingCurveNetFeeFactor?: number;
+    /** Vault address for this token (GalaChain format) */
+    vaultAddress?: string;
+    /** Custom maximum supply (only cached if != default 10M) */
+    maxSupply?: string;
+    /** Token symbol (immutable, cached from DEX API metadata) */
+    symbol?: string;
+    /** Timestamp when this cache entry was last updated */
+    lastUpdated: number;
+}
+/**
+ * Cache statistics for monitoring and debugging
+ */
+export interface CacheStats extends BaseCacheStats {
+    /** Total number of tokens in cache */
+    totalTokens: number;
+    /** Approximate cache size in bytes */
+    cacheSize: number;
+    /** Timestamp of oldest cache entry */
+    oldestEntry: number;
+}
+/**
+ * Token Metadata Cache
+ *
+ * High-performance in-memory cache for immutable token properties used in local calculations.
+ *
+ * ## Cache Lifecycle
+ * - **Persistence**: Entire MCP server lifetime (survives across conversations)
+ * - **Bounded Size**: Maximum 10,000 tokens (~2.5MB max memory)
+ * - **Eviction Strategy**: LRU (Least Recently Updated) with O(1) eviction time
+ *
+ * ## Warming Strategy (Opportunistic Caching)
+ * Cache is automatically warmed during normal SDK operations:
+ * - `fetchPools()` - Caches RBC fees and vault addresses for all returned pools
+ * - `fetchPoolDetailsForCalculation()` - Caches maxSupply and RBC fees (including defaults)
+ * - `fetchCurrentSupply()` - Caches maxSupply when fetched
+ * - `fetchTokenDistribution()` - Caches vault address when resolved
+ *
+ * ## Performance Characteristics
+ * - **Get/Set**: O(1) average time complexity
+ * - **Eviction**: O(1) time (uses Map insertion order)
+ * - **Normalization**: Handles unicode, case-insensitive, whitespace cleanup
+ * - **Memory**: ~250-400 bytes per entry (depends on string field lengths)
+ *
+ * ## Smart Defaults
+ * - **maxSupply**: Returns constant 10M for uncached tokens (99%+ hit rate)
+ * - **RBC Fees**: Defensive defaults (0.0 min, 0.5 max) when API data missing
+ *
+ * @example Basic usage
+ * ```typescript
+ * const cache = new TokenMetadataCache();
+ *
+ * // Warm cache from pool data
+ * cache.warmFromPoolData('anime', {
+ *   reverseBondingCurveMinFeeFactor: 0.0,
+ *   reverseBondingCurveMaxFeeFactor: 0.5
+ * });
+ *
+ * // Retrieve cached data
+ * const metadata = cache.get('anime');
+ * const maxSupply = cache.getMaxSupply('anime'); // Returns '10000000' (default)
+ * ```
+ *
+ * @category Services
+ * @since 3.9.2
+ */
+export declare class TokenMetadataCache extends AbstractCacheService<string, BondingCurveCacheEntry, CacheStats> {
+    /** Maximum cache size (10,000 tokens ≈ 2.5MB max memory) */
+    private static readonly MAX_CACHE_SIZE;
+    constructor(debugMode?: boolean);
+    /**
+     * Normalize token name for consistent cache keys
+     *
+     * Handles edge cases: unicode control chars, multiple spaces, case insensitivity.
+     *
+     * @param tokenName Raw token name
+     * @returns Normalized token name (lowercase, trimmed, cleaned)
+     */
+    protected normalizeKey(tokenName: string): string;
+    /**
+     * Get least recently updated entry for LRU eviction
+     *
+     * Leverages Map's insertion order: the first key is the oldest.
+     * O(1) time complexity vs O(n) scanning.
+     *
+     * @returns Token name of oldest entry, or null if cache is empty
+     * @private
+     */
+    private getLRUKey;
+    /**
+     * Update cache entry with LRU management
+     *
+     * Internal helper that handles the common cache update pattern:
+     * 1. Delete existing entry (maintains insertion order)
+     * 2. LRU eviction if cache is full
+     * 3. Add updated entry at end (most recently updated)
+     *
+     * @param normalized Normalized token name (lowercase)
+     * @param metadata Metadata to store (merged with existing if present)
+     * @private
+     */
+    private updateCacheEntry;
+    /**
+     * Warm cache from pool data (opportunistic caching from fetchPools)
+     *
+     * Partially populates cache with reverse bonding curve fees and vault address
+     * from fetchPools response. This provides zero-cost cache warming during normal
+     * pool browsing operations.
+     *
+     * @param tokenName Token name (normalized to lowercase)
+     * @param poolData Partial metadata from pool data
+     *
+     * @example Warming from fetchPools
+     * ```typescript
+     * pools.forEach(pool => {
+     *   cache.warmFromPoolData(pool.tokenName, {
+     *     reverseBondingCurveMinFeeFactor: parseFloat(pool.reverseBondingCurveMinFeePortion),
+     *     reverseBondingCurveMaxFeeFactor: parseFloat(pool.reverseBondingCurveMaxFeePortion),
+     *     vaultAddress: pool.vaultAddress
+     *   });
+     * });
+     * ```
+     */
+    warmFromPoolData(tokenName: string, poolData: Partial<BondingCurveCacheEntry>): void;
+    /**
+     * Set or update cache entry for a token
+     *
+     * Updates cache with partial or complete metadata. Merges with existing data.
+     *
+     * @param tokenName Token name (normalized to lowercase)
+     * @param metadata Partial or complete metadata to cache
+     *
+     * @example Caching custom maxSupply
+     * ```typescript
+     * cache.set('customtoken', {
+     *   maxSupply: '50000000' // Custom max supply detected
+     * });
+     * ```
+     */
+    set(tokenName: string, metadata: Partial<BondingCurveCacheEntry>): void;
+    /**
+     * Get cached metadata for a token
+     *
+     * @param tokenName Token name (normalized to lowercase)
+     * @returns Cached metadata or undefined if not cached
+     *
+     * @example Retrieving cached data
+     * ```typescript
+     * const metadata = cache.getByName('anime');
+     * if (metadata?.reverseBondingCurveMaxFeeFactor) {
+     *   console.log('RBC max fee:', metadata.reverseBondingCurveMaxFeeFactor);
+     * }
+     * ```
+     */
+    getByName(tokenName: string): BondingCurveCacheEntry | undefined;
+    /**
+     * Get maxSupply for a token (returns cached or default constant)
+     *
+     * Returns cached custom maxSupply if available, otherwise returns the
+     * default constant (10,000,000). This eliminates the need to fetch maxSupply
+     * for 99%+ of tokens that use the default value.
+     *
+     * @param tokenName Token name (normalized to lowercase)
+     * @returns maxSupply as decimal string (cached or default '10000000')
+     *
+     * @example Getting maxSupply with fallback
+     * ```typescript
+     * const maxSupply = cache.getMaxSupply('anime'); // '10000000' (default)
+     * const customSupply = cache.getMaxSupply('customtoken'); // '50000000' (cached custom)
+     * ```
+     */
+    getMaxSupply(tokenName: string): string;
+    /**
+     * Check if a token exists in cache
+     *
+     * @param tokenName Token name (normalized to lowercase)
+     * @returns True if token has any cached metadata
+     */
+    has(tokenName: string): boolean;
+    /**
+     * Clear cache (all tokens or specific token)
+     *
+     * @param tokenName Optional token name to clear (clears all if not provided)
+     *
+     * @example Clear specific token
+     * ```typescript
+     * cache.clear('anime'); // Clear only anime token
+     * ```
+     *
+     * @example Clear entire cache
+     * ```typescript
+     * cache.clear(); // Clear all tokens
+     * ```
+     */
+    clear(tokenName?: string): void;
+    /**
+     * Export entire cache as plain object
+     *
+     * Useful for debugging, monitoring, and cache inspection.
+     *
+     * @returns Cache contents as plain object (tokenName -> metadata)
+     *
+     * @example Dump cache for debugging
+     * ```typescript
+     * const cacheData = cache.dumpAsObject();
+     * console.log('Cached tokens:', Object.keys(cacheData));
+     * console.log('Cache contents:', JSON.stringify(cacheData, null, 2));
+     * ```
+     */
+    dumpAsObject(): Record<string, BondingCurveCacheEntry>;
+    /**
+     * Get cache statistics
+     *
+     * Returns statistics about cache size and age for monitoring performance.
+     *
+     * ⚠️ **Performance**: O(n) - iterates over all cache entries to calculate size.
+     * Do not call in hot paths or frequently.
+     *
+     * @returns Cache statistics
+     *
+     * @example Get cache stats
+     * ```typescript
+     * const stats = cache.stats();
+     * console.log(`Cached ${stats.totalTokens} tokens (${stats.cacheSize} bytes)`);
+     * console.log(`Oldest entry: ${new Date(stats.oldestEntry).toISOString()}`);
+     * ```
+     */
+    getStats(): CacheStats;
+    /**
+     * Calculate cache size in bytes and find oldest entry
+     *
+     * Helper method for getStats() - O(n) iteration over all entries.
+     *
+     * @returns Object with cacheSize (bytes) and oldestEntry (timestamp)
+     * @private
+     */
+    private calculateCacheSizeAndAge;
+    /**
+     * Get cached metadata by tokenId (DEX token format)
+     *
+     * Retrieves cached metadata for a DEX token identified by tokenId (pipe-delimited format).
+     * This method is specifically designed for DEX token symbol caching from API responses.
+     *
+     * @param tokenId Token ID in pipe-delimited format (e.g., 'GUSDC|Unit|none|eth:0x...')
+     * @returns Cached metadata or null if not cached
+     *
+     * @example Retrieving cached DEX token symbol
+     * ```typescript
+     * const metadata = cache.getByTokenId('GUSDC|Unit|none|eth:0x...');
+     * if (metadata?.symbol) {
+     *   console.log(`Symbol: ${metadata.symbol}`);
+     * }
+     * ```
+     */
+    getByTokenId(tokenId: string): BondingCurveCacheEntry | null;
+    /**
+     * Set or update cache entry by tokenId (DEX token format)
+     *
+     * Caches metadata for a DEX token identified by tokenId (pipe-delimited format).
+     * Useful for caching token symbols and other DEX metadata from API responses.
+     *
+     * @param tokenId Token ID in pipe-delimited format (e.g., 'GUSDC|Unit|none|eth:0x...')
+     * @param metadata Partial or complete metadata to cache (merged with existing data)
+     *
+     * @example Caching DEX token symbol
+     * ```typescript
+     * cache.setByTokenId('GUSDC|Unit|none|eth:0x...', {
+     *   symbol: 'GUSDC'
+     * });
+     * ```
+     */
+    setByTokenId(tokenId: string, metadata: Partial<BondingCurveCacheEntry>): void;
+    /**
+     * Check if a tokenId exists in cache (DEX token format)
+     *
+     * @param tokenId Token ID in pipe-delimited format (e.g., 'GUSDC|Unit|none|eth:0x...')
+     * @returns True if tokenId has any cached metadata
+     */
+    hasByTokenId(tokenId: string): boolean;
+}
+//# sourceMappingURL=TokenMetadataCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TokenMetadataCache.d.ts","sourceRoot":"","sources":["../../src/services/TokenMetadataCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,+BAA+B,CAAC,EAAE,MAAM,CAAC;IACzC,2DAA2D;IAC3D,+BAA+B,CAAC,EAAE,MAAM,CAAC;IACzC,uDAAuD;IACvD,+BAA+B,CAAC,EAAE,MAAM,CAAC;IACzC,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,kBAAmB,SAAQ,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,EAAE,UAAU,CAAC;IACtG,4DAA4D;IAC5D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAEnC,SAAS,GAAE,OAAe;IAItC;;;;;;;OAOG;IACH,SAAS,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAOjD;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IAMjB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,gBAAgB;IAyBxB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,IAAI;IAKpF;;;;;;;;;;;;;;OAcG;IACI,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,IAAI;IAK9E;;;;;;;;;;;;;OAaG;IACI,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS;IAKvE;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAQvC;;;;;OAKG;IACI,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAKtC;;;;;;;;;;;;;;OAcG;IACI,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAStC;;;;;;;;;;;;;OAaG;IACI,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC;IAQ7D;;;;;;;;;;;;;;;;OAgBG;IACI,QAAQ,IAAI,UAAU;IAY7B;;;;;;;OAOG;IACH,OAAO,CAAC,wBAAwB;IAuChC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI;IAK5D;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,IAAI;IAK9E;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CAIvC"}