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

package/dist/services/WebSocketService.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Socket.IO Service for Real-time Transaction Monitoring
+ *
+ * This service provides real-time monitoring of bundle transactions
+ * using Socket.IO connections to track transaction completion status.
+ *
+ * @category Services
+ * @since 2.0.0
+ */
+import type { Socket } from 'socket.io-client';
+import { SDKTransactionStatus } from '../types/websocket.types';
+import { LoggerBase } from './BaseService';
+export interface TransactionStatus {
+    transactionId: string;
+    status: SDKTransactionStatus;
+    message?: string;
+    timestamp: number;
+    blockHash?: string;
+    gasUsed?: string;
+    /**
+     * Raw transaction data from bundler response
+     * Contains actual swap/buy/sell amounts and other transaction details
+     * @since v3.32.0 - Added to capture actual transaction output
+     */
+    data?: Record<string, unknown>;
+}
+/**
+ * WebSocket service configuration with timeout customization
+ *
+ * **Timeout Configuration**
+ * Control how long the SDK waits for WebSocket transaction confirmation:
+ * - Default: 300000ms (5 minutes) - suitable for typical blockchain finalization
+ * - Minimum: 10000ms (10 seconds) - for fast-finality blockchains
+ * - Custom: Set to any millisecond value matching your blockchain requirements
+ *
+ * **When Timeout Occurs**
+ * If no transaction confirmation is received within the timeout period:
+ * - WebSocket monitoring is terminated
+ * - Operation returns with `status: 'SUBMITTED'` indicating transaction was accepted
+ * - Transaction may still succeed on-chain even if monitoring times out
+ * - Users can call `.wait()` again to retry monitoring
+ * - Recommended: retry monitoring after waiting or check on-chain later
+ *
+ * **Use Cases for Custom Timeouts**
+ * - **Slow Blockchains** (5+ min finality): Increase to 600000+ ms
+ * - **Fast Blockchains** (Solana, Polygon): Reduce to 30000-60000 ms
+ * - **High Network Congestion**: Increase timeout tolerance
+ * - **Mobile Networks**: Increase to handle intermittent connectivity
+ *
+ * @example
+ * ```typescript
+ * // Initialize SDK with custom WebSocket timeout
+ * const sdk = await createLaunchpadSDK({
+ *   wallet: privateKey,
+ *   config: {
+ *     // Custom 2-minute timeout for faster networks
+ *     websocket: {
+ *       timeout: 120000  // 120 seconds instead of default 5 minutes
+ *     }
+ *   }
+ * });
+ *
+ * // Or for slow networks
+ * const sdk = await createLaunchpadSDK({
+ *   wallet: privateKey,
+ *   config: {
+ *     websocket: {
+ *       timeout: 600000  // 10 minutes for very slow finality
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export interface WebSocketConfig {
+    /** WebSocket server URL for transaction monitoring */
+    url: string;
+    /** Maximum reconnection attempts on connection loss (default: 5) */
+    reconnectAttempts?: number;
+    /** Delay between reconnection attempts in milliseconds (default: 2000) */
+    reconnectDelay?: number;
+    /**
+     * Maximum time to wait for transaction confirmation in milliseconds (default: 300000 / 5 minutes)
+     *
+     * Configure based on blockchain finality time:
+     * - Ethereum/GalaChain: 300000ms (5 minutes) ✅ Default
+     * - Polygon: 120000ms (2 minutes)
+     * - Solana: 30000ms (30 seconds)
+     * - Custom: Adjust to match your blockchain's block time + finality buffer
+     */
+    timeout?: number;
+}
+export declare class WebSocketService extends LoggerBase {
+    private static instances;
+    private socket;
+    private config;
+    private listeners;
+    private timeouts;
+    private reconnectionManager;
+    private debug;
+    private isSocketIOAvailable;
+    private hasOnAnyListener;
+    /**
+     * CRITICAL FIX FOR RACE CONDITION:
+     * Buffers bundler events that arrive before their listeners are registered.
+     *
+     * **The Problem:**
+     * 1. SDK sends HTTP request to bundler
+     * 2. Bundler processes synchronously and sends "PROCESSED" event immediately
+     * 3. Event arrives over WebSocket before SDK registers listener
+     * 4. Event is lost forever, SDK hangs waiting for confirmation
+     *
+     * **The Solution:**
+     * Use SimpleCache with 30s TTL to auto-clean orphaned events.
+     * Buffers ALL bundler events via catch-all listener, regardless of
+     * when the specific transactionId listener is registered. This ensures
+     * no events are ever lost, even if they arrive milliseconds early.
+     */
+    private eventBuffer;
+    private readonly MAX_BUFFER_SIZE;
+    constructor(config: WebSocketConfig, debug?: boolean);
+    /**
+     * Check if Socket.IO is available in the current environment
+     * Handles both browser and Node.js environments gracefully
+     */
+    private checkSocketIOAvailability;
+    /**
+     * Connect to Socket.IO endpoint
+     */
+    connect(): Promise<void>;
+    /**
+     * Monitor a specific transaction
+     *
+     * CRITICAL: This method checks for buffered events first.
+     * If an event arrived before this listener was registered,
+     * it will be delivered immediately from the buffer.
+     * This prevents transactions from hanging due to race conditions.
+     */
+    monitorTransaction(transactionId: string, callback: (status: TransactionStatus) => void): Promise<void>;
+    /**
+     * CRITICAL: Shared event processing logic for both real-time and buffered events
+     * Extracts common parsing and status mapping from socket listener
+     * Allows both paths (live events + buffered events) to use identical logic
+     *
+     * @param transactionId - The transaction to process
+     * @param data - The raw event data
+     * @param callback - The listener callback to invoke
+     */
+    private processTransactionEvent;
+    /**
+     * Wait for transaction completion
+     */
+    waitForTransaction(transactionId: string): Promise<TransactionStatus>;
+    /**
+     * Map Socket.IO status to our standard status
+     */
+    private mapSocketStatus;
+    /**
+     * Handle Socket.IO reconnection
+     */
+    private handleReconnect;
+    /**
+     * Disconnect Socket.IO
+     */
+    disconnect(): void;
+    /**
+     * Disconnects and cleans up all WebSocketService instances globally.
+     * Useful for page unload, test teardown, or when calling LaunchpadSDK.cleanupAll().
+     */
+    static cleanupAll(_debug?: boolean): void;
+    /**
+     * Check connection status
+     */
+    isConnected(): boolean;
+    /**
+     * Get the underlying Socket.IO socket instance for custom event subscriptions
+     *
+     * @returns The Socket.IO socket instance, or null if not connected
+     *
+     * @example
+     * const socket = webSocketService.getSocket();
+     * if (socket) {
+     *   socket.on('custom-event', (data) => {
+     *     console.log('Event received:', data);
+     *   });
+     * }
+     */
+    getSocket(): Socket | null;
+}
+//# sourceMappingURL=WebSocketService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketService.d.ts","sourceRoot":"","sources":["../../src/services/WebSocketService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAEL,oBAAoB,EAErB,MAAM,0BAA0B,CAAC;AAKlC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,OAAO,CAAC,MAAM,CAAC,SAAS,CAA+B;IAEvD,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,SAAS,CACL;IACZ,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,mBAAmB,CAAU;IACrC,OAAO,CAAC,gBAAgB,CAAS;IACjC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;gBAE5B,MAAM,EAAE,eAAe,EAAE,KAAK,GAAE,OAAe;IA0B3D;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAkBjC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkH9B;;;;;;;OAOG;IAEG,kBAAkB,CACtB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAC5C,OAAO,CAAC,IAAI,CAAC;IAwFhB;;;;;;;;OAQG;IACH,OAAO,CAAC,uBAAuB;IAkG/B;;OAEG;IACG,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAa3E;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;OAEG;YAEW,eAAe;IAmB7B;;OAEG;IACH,UAAU,IAAI,IAAI;IAoClB;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,GAAE,OAAe,GAAG,IAAI;IAOhD;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;;;;;;OAYG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;CAG3B"}

package/dist/services/WeeklyChallengeService.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Weekly Challenge Service
+ *
+ * Handles the weekly challenge leaderboard feature that tracks token market cap
+ * increases week-over-week. The challenge runs Saturday to Friday, with Saturday
+ * being the baseline for calculating gains.
+ *
+ * @category Services
+ * @since 9.0.0
+ */
+import type { GetTokenWeeklyHistoryOptions, GetTokenWeeklyHistoryResult, GetWeeklyChallengeOptions, GetWeeklyChallengeResult } from '../types/weekly-challenge.dto';
+import type { HttpClient } from '../utils/http';
+import { BaseService } from './BaseService';
+/**
+ * Weekly Challenge Service Class
+ *
+ * Provides methods for accessing the weekly challenge leaderboard:
+ * - Get current week's leaderboard (tokens ranked by market cap increase)
+ * - Get historical weekly snapshots for a specific token
+ *
+ * **Challenge Rules:**
+ * - Week runs Saturday to Friday
+ * - Baseline is Saturday's snapshot
+ * - Ranking is by market cap increase (current - baseline)
+ * - Tokens with no baseline data (new this week) use previous week's latest snapshot
+ *
+ * **Public endpoint** - no authentication required.
+ *
+ * @example
+ * ```typescript
+ * const wcService = new WeeklyChallengeService(httpClient, true);
+ *
+ * // Get top 10 tokens in weekly challenge
+ * const { leaderboard } = await wcService.getLeaderboard({ limit: 10 });
+ * console.log(`Week: ${leaderboard.weekStart} to ${leaderboard.weekEnd}`);
+ * for (const token of leaderboard.tokens) {
+ *   console.log(`#${token.rank} ${token.tokenName}: +${token.marketCapIncreaseGala} GALA`);
+ * }
+ *
+ * // Get historical data for a specific token
+ * const { snapshots } = await wcService.getTokenHistory({
+ *   vaultAddress: 'eth|0x123...'
+ * });
+ * for (const snap of snapshots) {
+ *   console.log(`${snap.snapshotDate}: ${snap.marketCapGala} GALA`);
+ * }
+ * ```
+ */
+export declare class WeeklyChallengeService extends BaseService {
+    constructor(http: HttpClient, debugMode?: boolean);
+    /**
+     * Extract data from API response wrapper
+     * @throws Error if response indicates failure or has no data
+     */
+    private extractData;
+    /**
+     * Get weekly challenge leaderboard
+     *
+     * Returns tokens ranked by market cap increase for the current week.
+     * Week runs Saturday to Friday.
+     *
+     * @param options - Optional parameters
+     * @returns Leaderboard with ranked tokens
+     *
+     * @example
+     * ```typescript
+     * // Get top 20 tokens
+     * const { leaderboard } = await wcService.getLeaderboard({ limit: 20 });
+     *
+     * // Display results
+     * console.log(`Challenge week: ${leaderboard.weekStart} - ${leaderboard.weekEnd}`);
+     * console.log(`Snapshot: ${leaderboard.snapshotDate}`);
+     * console.log(`Total tokens: ${leaderboard.count}`);
+     *
+     * for (const token of leaderboard.tokens) {
+     *   const increase = token.marketCapIncreaseGala.toLocaleString();
+     *   console.log(`${token.rank}. ${token.symbol} (+${increase} GALA)`);
+     * }
+     * ```
+     */
+    getLeaderboard(options?: GetWeeklyChallengeOptions): Promise<GetWeeklyChallengeResult>;
+    /**
+     * Get token weekly history
+     *
+     * Returns the last 4 weeks of snapshot data for a specific token.
+     * Useful for tracking a token's performance over time.
+     *
+     * @param options - Options with vault address
+     * @returns Array of weekly snapshots
+     *
+     * @example
+     * ```typescript
+     * const { snapshots } = await wcService.getTokenHistory({
+     *   vaultAddress: 'eth|0xabc123...'
+     * });
+     *
+     * // Show weekly performance
+     * for (const snap of snapshots) {
+     *   const date = new Date(snap.snapshotDate).toLocaleDateString();
+     *   console.log(`${date}: $${snap.marketCapUsd} (${snap.marketCapGala} GALA)`);
+     * }
+     *
+     * // Calculate week-over-week change
+     * if (snapshots.length >= 2) {
+     *   const current = parseFloat(snapshots[0].marketCapGala);
+     *   const previous = parseFloat(snapshots[1].marketCapGala);
+     *   const change = ((current - previous) / previous * 100).toFixed(2);
+     *   console.log(`Week-over-week change: ${change}%`);
+     * }
+     * ```
+     */
+    getTokenHistory(options: GetTokenWeeklyHistoryOptions): Promise<GetTokenWeeklyHistoryResult>;
+}
+//# sourceMappingURL=WeeklyChallengeService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WeeklyChallengeService.d.ts","sourceRoot":"","sources":["../../src/services/WeeklyChallengeService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EACV,4BAA4B,EAC5B,2BAA2B,EAC3B,yBAAyB,EACzB,wBAAwB,EAGzB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,sBAAuB,SAAQ,WAAW;gBACzC,IAAI,EAAE,UAAU,EAAE,SAAS,GAAE,OAAe;IAIxD;;;OAGG;IACH,OAAO,CAAC,WAAW;IAQnB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,cAAc,CAAC,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAyBhG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,eAAe,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,2BAA2B,CAAC;CAsBnG"}

package/dist/services/WrapService.d.ts

@@ -0,0 +1,172 @@
+/**
+ * WrapService - Cross-channel token wrapping/unwrapping
+ *
+ * Handles internal GalaChain channel bridges:
+ * - Wrap: MUSIC (music channel) → GMUSIC (asset channel)
+ * - Unwrap: GMUSIC (asset channel) → MUSIC (music channel)
+ *
+ * This is different from external bridges (Ethereum/Solana) - wrap/unwrap
+ * operates entirely within GalaChain across different channels.
+ *
+ * @category Services
+ * @since 4.0.18
+ */
+import type { Wallet } from 'ethers';
+import type { GalaConnectClient } from '../bridge/GalaConnectClient.js';
+import type { TokenId } from '../types/common.js';
+import type { UnwrapTokenOptions, WrapTokenOptions, WrapUnwrapFeeEstimate, WrapUnwrapResult, WrapUnwrapStatusResult } from '../types/wrappable-token.dto.js';
+import type { Logger } from '../utils/Logger.js';
+import { LoggerBase } from './BaseService.js';
+import type { WrappableTokenService } from './WrappableTokenService.js';
+/**
+ * Configuration for WrapService
+ */
+export interface WrapServiceConfig {
+    /** GalaConnect client for DEX API platform (same as bridge operations) */
+    galaConnectClient: GalaConnectClient;
+    /** WrappableTokenService for token metadata */
+    wrappableTokenService: WrappableTokenService;
+    /** Wallet for EIP-712 signing (same pattern as bridge) */
+    wallet?: Wallet;
+    /** Wallet address (for sender) */
+    walletAddress?: string;
+    /** Logger instance */
+    logger?: Logger;
+}
+/**
+ * WrapService - Cross-channel token wrapping/unwrapping
+ *
+ * Provides methods to wrap tokens from their native channel to the asset channel
+ * (e.g., MUSIC → GMUSIC) and unwrap them back (GMUSIC → MUSIC).
+ *
+ * @example
+ * ```typescript
+ * // Wrap MUSIC to GMUSIC for DEX trading
+ * const wrapResult = await wrapService.wrapToken({
+ *   tokenId: 'MUSIC',
+ *   amount: '100',
+ * });
+ *
+ * // Unwrap GMUSIC back to MUSIC
+ * const unwrapResult = await wrapService.unwrapToken({
+ *   tokenId: 'GMUSIC',
+ *   amount: '50',
+ * });
+ * ```
+ */
+export declare class WrapService extends LoggerBase {
+    private readonly galaConnectClient;
+    private readonly wrappableTokenService;
+    private readonly wallet;
+    private readonly walletAddress;
+    constructor(config: WrapServiceConfig);
+    /**
+     * Wrap a token to its asset-channel counterpart
+     *
+     * Transfers a token from its native channel to the asset channel.
+     * Example: MUSIC (music channel) → GMUSIC (asset channel)
+     *
+     * @param options - Wrap options including tokenId and amount
+     * @returns Promise<WrapUnwrapResult> - Transaction result
+     *
+     * @example
+     * ```typescript
+     * const result = await wrapService.wrapToken({
+     *   tokenId: 'MUSIC',
+     *   amount: '100',
+     * });
+     * console.log(`Wrapped ${result.amount} ${result.fromToken} → ${result.toToken}`);
+     * ```
+     *
+     * @throws {ValidationError} If token is not wrappable or already on asset channel
+     */
+    wrapToken(options: WrapTokenOptions): Promise<WrapUnwrapResult>;
+    /**
+     * Unwrap a token back to its native channel
+     *
+     * Transfers a token from the asset channel back to its native channel.
+     * Example: GMUSIC (asset channel) → MUSIC (music channel)
+     *
+     * @param options - Unwrap options including tokenId and amount
+     * @returns Promise<WrapUnwrapResult> - Transaction result
+     *
+     * @example
+     * ```typescript
+     * const result = await wrapService.unwrapToken({
+     *   tokenId: 'GMUSIC',
+     *   amount: '50',
+     * });
+     * console.log(`Unwrapped ${result.amount} ${result.fromToken} → ${result.toToken}`);
+     * ```
+     *
+     * @throws {ValidationError} If token is not unwrappable or not on asset channel
+     */
+    unwrapToken(options: UnwrapTokenOptions): Promise<WrapUnwrapResult>;
+    /**
+     * Estimate fees for a wrap operation
+     *
+     * @param tokenId - Token to wrap
+     * @param amount - Amount to wrap
+     * @returns Promise<WrapUnwrapFeeEstimate> - Fee estimate
+     * @throws ValidationError if tokenId or amount is required but not provided
+     */
+    estimateWrapFee(tokenId: TokenId, _amount: string): Promise<WrapUnwrapFeeEstimate>;
+    /**
+     * Estimate fees for an unwrap operation
+     *
+     * @param tokenId - Token to unwrap
+     * @param amount - Amount to unwrap
+     * @returns Promise<WrapUnwrapFeeEstimate> - Fee estimate
+     * @throws ValidationError if tokenId or amount is required but not provided
+     */
+    estimateUnwrapFee(tokenId: TokenId, _amount: string): Promise<WrapUnwrapFeeEstimate>;
+    /**
+     * Get status of a wrap/unwrap transaction
+     *
+     * Cross-channel wrapping completes immediately (synchronous on-chain).
+     * This method returns the completed status for the given transaction ID.
+     *
+     * @param transactionId - Transaction ID to check
+     * @returns WrapUnwrapStatusResult - Current status (always completed for wrap/unwrap)
+     * @throws ValidationError if transactionId is required but not provided
+     */
+    getWrapStatus(transactionId: string): WrapUnwrapStatusResult;
+    /**
+     * Execute a cross-channel bridge (wrap or unwrap)
+     *
+     * Uses EIP-712 signing for GalaChain authentication.
+     * Uses WRAP_TYPED_DATA_TYPES which is DIFFERENT from external bridge types.
+     *
+     * Key insight: Wrap/unwrap uses simpler EIP-712 types with `wrap: bool`
+     * instead of the complex `destinationChainTxFee` structure used by external bridges.
+     *
+     * @see docs/api-calls/swapBridgeOut.txt for working payload example
+     */
+    private executeChannelBridge;
+    /**
+     * Execute wrap bridge request with comprehensive error handling
+     *
+     * Uses direct try-catch (not withErrorHandling wrapper) because this method
+     * returns structured error responses (WrapUnwrapResult with success: false)
+     * rather than throwing. This is appropriate for a private helper method that
+     * normalizes errors into the return type.
+     */
+    private executeWrapBridgeRequest;
+    /**
+     * Determine channel routing for wrap/unwrap operation
+     *
+     * The destinationChannelId determines where tokens go:
+     * - Wrap: native channel → asset channel (destinationChannelId = ASSET = 1)
+     * - Unwrap: asset channel → native channel (destinationChannelId = MUSIC = 3)
+     */
+    private determineChannelRouting;
+    /**
+     * Validate that a wallet is available for signing
+     */
+    private requireWallet;
+    /**
+     * Format tokenId for error messages using centralized stringification
+     */
+    private formatTokenId;
+}
+//# sourceMappingURL=WrapService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WrapService.d.ts","sourceRoot":"","sources":["../../src/services/WrapService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIrC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAKxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EACV,kBAAkB,EAElB,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AAKzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAcxE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,+CAA+C;IAC/C,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA4CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAY,SAAQ,UAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoB;IACtD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAwB;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAEvC,MAAM,EAAE,iBAAiB;IAYrC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAgDrE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAgDzE;;;;;;;OAOG;IACG,eAAe,CACnB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,qBAAqB,CAAC;IAqCjC;;;;;;;OAOG;IACG,iBAAiB,CACrB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,qBAAqB,CAAC;IAqCjC;;;;;;;;;OASG;IACH,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,sBAAsB;IAsB5D;;;;;;;;;;OAUG;YACW,oBAAoB;IA+ElC;;;;;;;OAOG;YACW,wBAAwB;IAgKtC;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAwB/B;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,aAAa;CAMtB"}

package/dist/services/WrappableTokenCache.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Wrappable Token Cache Service
+ *
+ * Permanent in-memory cache for wrappable tokens fetched from DEX API.
+ * Wrappable tokens are GalaChain-internal token pairs that can be
+ * wrapped/unwrapped into each other (e.g., MUSIC <-> GMUSIC).
+ *
+ * ## Cache Architecture
+ * - **Primary Index**: Map<tokenId, token> - O(1) by stringifiedTokenClassKey
+ * - **Persistence**: Entire SDK lifetime (never expires)
+ * - **Memory**: ~500-800 bytes per token (plus ~50 bytes per index entry)
+ *
+ * ## Caching Strategy
+ * - Metadata always cached by fetchWrappableTokens/fetchAllWrappableTokens
+ * - Balance methods preheat cache while returning user-specific data
+ * - No network separation (wrapping is GalaChain-internal)
+ *
+ * @category Services
+ * @since 4.0.18
+ */
+import type { WrappableToken, WrappableTokenCacheStats } from '../types/wrappable-token.dto.js';
+import { BatchedCacheService } from './BatchedCacheService.js';
+/**
+ * Wrappable Token Cache
+ *
+ * High-performance permanent cache for wrappable token data.
+ * Tokens are indexed by their stringifiedTokenClassKey for O(1) lookups.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const cache = new WrappableTokenCache();
+ *
+ * // Cache all tokens
+ * cache.setAll(wrappableTokens);
+ *
+ * // Check if cached
+ * if (cache.has()) {
+ *   const tokens = cache.getAll();
+ * }
+ *
+ * // Get specific token by tokenId
+ * const music = cache.getByTokenId('$MUSIC|Unit|none|none');
+ * ```
+ */
+export declare class WrappableTokenCache extends BatchedCacheService<WrappableToken, WrappableTokenCacheStats> {
+    constructor(debugMode?: boolean);
+    /**
+     * Extract the cache key from a wrappable token
+     *
+     * @param token - Wrappable token
+     * @returns The stringifiedTokenClassKey as the key
+     */
+    protected extractKey(token: WrappableToken): string;
+    /**
+     * Check if cache is populated
+     *
+     * @returns True if cache has tokens
+     */
+    has(): boolean;
+    /**
+     * Get all cached tokens
+     *
+     * @returns Array of wrappable tokens (empty if not cached)
+     */
+    getAll(): WrappableToken[];
+    /**
+     * Get a specific token by stringifiedTokenClassKey (tokenId)
+     *
+     * @param tokenId - Stringified TokenClassKey (e.g., "$MUSIC|Unit|none|none")
+     * @returns Wrappable token or undefined if not found
+     */
+    getByTokenId(tokenId: string): WrappableToken | undefined;
+    /**
+     * Get cache statistics
+     *
+     * @returns Cache statistics including token count and timestamp
+     */
+    getStats(): WrappableTokenCacheStats;
+    /**
+     * Get number of cached tokens
+     *
+     * @returns Number of cached tokens
+     */
+    size(): number;
+    /**
+     * Check if a token is wrappable (exists in cache)
+     *
+     * @param tokenId - Stringified TokenClassKey
+     * @returns True if token is cached
+     */
+    isTokenWrappable(tokenId: string): boolean;
+    /**
+     * Get wrap counterpart for a token
+     *
+     * @param tokenId - Stringified TokenClassKey
+     * @returns Counterpart token or undefined if not found
+     */
+    getWrapCounterpart(tokenId: string): WrappableToken | undefined;
+}
+//# sourceMappingURL=WrappableTokenCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WrappableTokenCache.d.ts","sourceRoot":"","sources":["../../src/services/WrappableTokenCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAChG,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,mBAAoB,SAAQ,mBAAmB,CAAC,cAAc,EAAE,wBAAwB,CAAC;gBACxF,SAAS,GAAE,OAAe;IAItC;;;;;OAKG;IACH,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM;IAInD;;;;OAIG;IACH,GAAG,IAAI,OAAO;IAId;;;;OAIG;IACH,MAAM,IAAI,cAAc,EAAE;IAI1B;;;;;OAKG;IACI,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIhE;;;;OAIG;IACI,QAAQ,IAAI,wBAAwB;IAQ3C;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;;;;OAKG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI1C;;;;;OAKG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;CAMhE"}