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

package/dist/services/SwapEventQueue.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Swap Event Queue
+ *
+ * Manages event queuing with backpressure handling and batch processing.
+ * Prevents memory overflow by dropping events when queue exceeds capacity.
+ *
+ * Features:
+ * - Configurable queue capacity
+ * - Batch processing for efficiency
+ * - Concurrency control
+ * - Automatic metrics tracking
+ * - Graceful shutdown
+ *
+ * @packageDocumentation
+ */
+import type { SwapEventData, SwapMonitorConfig } from '../types/swap-monitor.dto';
+import type { Logger } from '../utils/Logger';
+import type { MonitoringMetrics } from '../utils/MonitoringMetrics';
+import { LoggerBase } from './BaseService';
+/**
+ * Queue statistics
+ *
+ * @internal
+ */
+export interface QueueStats {
+    queueSize: number;
+    eventsProcessed: number;
+    eventsDropped: number;
+    currentConcurrent: number;
+    maxConcurrentReached: number;
+    averageBatchSize: number;
+    totalBatchesProcessed: number;
+}
+/**
+ * Manages event queue with backpressure and batch processing
+ *
+ * Provides reliable event queuing with overflow protection. Events are processed
+ * in batches to improve efficiency while maintaining concurrency limits.
+ *
+ * @internal
+ */
+export declare class SwapEventQueue extends LoggerBase {
+    private readonly queue;
+    private readonly config;
+    private readonly metrics;
+    private isShuttingDown;
+    private currentConcurrency;
+    private maxConcurrencyReached;
+    private eventsDropped;
+    private totalBatchesProcessed;
+    private totalBatchSize;
+    private eventsProcessedCount;
+    /** Processor function - called for each event */
+    private processor;
+    /** Processing loop control */
+    private processingScheduled;
+    /** Cross-platform scheduler */
+    private scheduleProcessing;
+    constructor(config: Required<SwapMonitorConfig>, metrics: MonitoringMetrics, logger?: Logger);
+    /**
+     * Register event processor callback function
+     *
+     * Sets the async function that will be called for each swap event. The processor
+     * is invoked with batch processing and concurrency control according to queue configuration.
+     *
+     * **Performance**: Processor should complete in <100ms for optimal throughput.
+     *
+     * @param processor Async function to process each swap event
+     * @category Event Processing
+     * @since 3.19.0
+     *
+     * @example Register event processor
+     * ```typescript
+     * queue.setProcessor(async (event) => {
+     *   console.log(`Processing swap: ${event.transactionId}`);
+     *   await database.saveSwap(event);
+     *   console.log('Swap saved successfully');
+     * });
+     * ```
+     */
+    setProcessor(processor: (event: SwapEventData) => Promise<void>): void;
+    /**
+     * Add swap event to processing queue with backpressure handling
+     *
+     * Attempts to enqueue a swap event for async processing. If the queue is at capacity,
+     * the event is dropped and false is returned (backpressure signal). Successfully
+     * enqueued events are processed in batches according to queue configuration.
+     *
+     * **Backpressure**: When queue is full, events are dropped to prevent memory overflow.
+     * Monitor `eventsDropped` metric to detect sustained backpressure conditions.
+     *
+     * **Performance**: O(1) enqueue time, automatic batch scheduling.
+     *
+     * @param event Swap event to enqueue for processing
+     * @returns true if successfully enqueued, false if dropped due to queue overflow
+     * @category Event Processing
+     * @since 3.19.0
+     *
+     * @example Enqueue with backpressure handling
+     * ```typescript
+     * const success = queue.enqueue({
+     *   transactionId: 'tx123',
+     *   poolKey: 'GALA-GUSDC-3000',
+     *   timestamp: Date.now(),
+     *   amount0: '1000',
+     *   amount1: '500',
+     *   exactInput: true
+     * });
+     *
+     * if (!success) {
+     *   console.warn('Queue full - event dropped!');
+     *   // Consider: reduce ingestion rate, increase queue size, scale workers
+     * }
+     * ```
+     */
+    enqueue(event: SwapEventData): boolean;
+    /**
+     * Get current number of pending events in queue
+     *
+     * Returns the count of events waiting to be processed. Useful for monitoring
+     * queue depth and detecting backlog buildup.
+     *
+     * @returns Number of events currently in queue (not yet processed)
+     * @category Monitoring
+     * @since 3.19.0
+     *
+     * @example Monitor queue depth
+     * ```typescript
+     * const depth = queue.getQueueSize();
+     * if (depth > 1000) {
+     *   console.warn(`Queue backlog: ${depth} events pending`);
+     * }
+     * ```
+     */
+    getQueueSize(): number;
+    /**
+     * Get comprehensive queue performance statistics
+     *
+     * Returns detailed metrics including queue size, processing counts, concurrency levels,
+     * and batch statistics. Use for monitoring, alerting, and capacity planning.
+     *
+     * @returns QueueStats object with current state and performance metrics
+     * @category Monitoring
+     * @since 3.19.0
+     *
+     * @example Monitor queue performance
+     * ```typescript
+     * const stats = queue.getStats();
+     * console.log(`Queue: ${stats.queueSize} pending, ${stats.eventsProcessed} processed`);
+     * console.log(`Dropped: ${stats.eventsDropped} (${(stats.eventsDropped / stats.eventsProcessed * 100).toFixed(2)}%)`);
+     * console.log(`Concurrency: ${stats.currentConcurrent}/${stats.maxConcurrentReached}`);
+     * console.log(`Avg batch size: ${stats.averageBatchSize}`);
+     * ```
+     */
+    getStats(): QueueStats;
+    /**
+     * Wait for queue to be empty
+     *
+     * @param timeoutMs - Maximum time to wait (default: no timeout)
+     * @returns Promise that resolves when queue is empty or timeout
+     */
+    waitForEmpty(timeoutMs?: number): Promise<void>;
+    /**
+     * Shutdown the queue gracefully
+     *
+     * Stops accepting new events and waits for processing to complete.
+     *
+     * @param timeoutMs - Maximum time to wait for processing to complete (default: 30s)
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /**
+     * Clear the queue without processing
+     *
+     * Use with caution - discards all pending events.
+     */
+    clear(): void;
+    /**
+     * Process next batch of events
+     *
+     * Respects concurrency limits and batch size configuration.
+     *
+     * @internal
+     */
+    private processNextBatch;
+    /**
+     * Process a single event
+     *
+     * @internal
+     */
+    private processEvent;
+}
+//# sourceMappingURL=SwapEventQueue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SwapEventQueue.d.ts","sourceRoot":"","sources":["../../src/services/SwapEventQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAElF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAE5C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,oBAAoB,CAAK;IAEjC,iDAAiD;IACjD,OAAO,CAAC,SAAS,CAA0D;IAE3E,8BAA8B;IAC9B,OAAO,CAAC,mBAAmB,CAAS;IAEpC,+BAA+B;IAC/B,OAAO,CAAC,kBAAkB,CAMxB;gBAGA,MAAM,EAAE,QAAQ,CAAC,iBAAiB,CAAC,EACnC,OAAO,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,MAAM;IAWjB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAItE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO;IAmCtC;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,IAAI,UAAU;IAYtB;;;;;OAKG;IACG,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBrD;;;;;;OAMG;IACG,QAAQ,CAAC,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBxD;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAQb;;;;;;OAMG;YACW,gBAAgB;IAyE9B;;;;OAIG;YACW,YAAY;CAiB3B"}

package/dist/services/TokenBanService.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Token Ban Service
+ *
+ * Handles platform-wide token ban operations for overseers.
+ * Banned tokens are hidden from all listings and have actions blocked.
+ *
+ * This is different from BanService which handles per-token user bans.
+ * TokenBanService bans entire tokens from the platform (overseer-only),
+ * while BanService bans specific users from specific tokens (owner/admin).
+ *
+ * @category Services
+ * @since 6.x.0
+ */
+import type { JwtAuth } from '../auth/JwtAuth';
+import type { BanTokenOptions, BanTokenResult, GetTokenBanOptions, ListTokenBansOptions, TokenBanListResult, TokenBanStatusResult, UnbanTokenOptions, UnbanTokenResult } from '../types/token-ban.dto';
+import type { HttpClient } from '../utils/http';
+import { StreamTokenServiceBase } from './StreamTokenServiceBase';
+/**
+ * Token Ban Service Class
+ *
+ * Provides methods for managing platform-wide token bans:
+ * - Banning tokens (hides from all listings)
+ * - Unbanning tokens (restores visibility)
+ * - Listing all banned tokens
+ * - Checking ban status for specific tokens
+ *
+ * **Access Control**: All endpoints require either:
+ * - Admin API key (server-to-server)
+ * - JWT with overseer status (authenticated overseer user)
+ *
+ * **Effects of Token Bans**:
+ * - Hidden from ALL pool listings (including creator's profile)
+ * - Comments blocked on banned tokens
+ * - Live streaming blocked on banned tokens
+ * - Chat messages blocked on banned tokens
+ * - Trading NOT blocked (GalaChain handles trading independently)
+ *
+ * @remarks
+ * **Case Normalization**: Token names are automatically normalized to lowercase
+ * in all requests and responses for consistency.
+ *
+ * **Permanent Bans**: Token bans do not expire. They remain in effect until
+ * explicitly removed by an overseer.
+ *
+ * @example
+ * ```typescript
+ * const tokenBanService = new TokenBanService(httpClient, 'admin-api-key', jwtAuth, true);
+ *
+ * // Ban a token
+ * await tokenBanService.banToken({
+ *   tokenName: 'scamtoken',
+ *   reason: 'Fraudulent project - reported by multiple users'
+ * });
+ *
+ * // Check if a token is banned
+ * const status = await tokenBanService.isTokenBanned({ tokenName: 'sometoken' });
+ * if (status.banned) {
+ *   console.log('Token is banned:', status.ban?.reason);
+ * }
+ *
+ * // List all banned tokens
+ * const bans = await tokenBanService.listTokenBans({ pageSize: 20 });
+ *
+ * // Unban a token
+ * await tokenBanService.unbanToken({ tokenName: 'scamtoken' });
+ * ```
+ */
+export declare class TokenBanService extends StreamTokenServiceBase {
+    constructor(http: HttpClient, adminApiKey?: string, jwtAuth?: JwtAuth, debugMode?: boolean, userApiKey?: string);
+    /**
+     * Ban a token from the platform
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (overseer) auth.
+     *
+     * When a token is banned:
+     * - Hidden from all pool listings
+     * - Hidden from creator's profile
+     * - Comments blocked
+     * - Live streaming blocked
+     * - Chat blocked
+     * - Trading still allowed (GalaChain handles)
+     *
+     * @param options - Ban options including tokenName and optional reason
+     * @returns Created ban data with token name
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     * @throws Error if token is already banned (409 Conflict)
+     *
+     * @example
+     * ```typescript
+     * // Ban with reason
+     * const result = await tokenBanService.banToken({
+     *   tokenName: 'scamtoken',
+     *   reason: 'Fraudulent project - reported by multiple users'
+     * });
+     * console.log('Banned:', result.tokenName);
+     * console.log('Ban ID:', result.ban.id);
+     *
+     * // Ban without reason
+     * await tokenBanService.banToken({ tokenName: 'problematictoken' });
+     * ```
+     */
+    banToken(options: BanTokenOptions): Promise<BanTokenResult>;
+    /**
+     * Remove a ban from a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (overseer) auth.
+     *
+     * When a token is unbanned:
+     * - Restored to all pool listings
+     * - Visible on creator's profile again
+     * - Comments re-enabled
+     * - Live streaming re-enabled
+     * - Chat re-enabled
+     *
+     * @param options - Unban options including tokenName
+     * @returns Removal confirmation with token name
+     * @throws ValidationError if token name is invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     * @throws Error if token is not banned (404 Not Found)
+     *
+     * @example
+     * ```typescript
+     * const result = await tokenBanService.unbanToken({ tokenName: 'scamtoken' });
+     * console.log('Removed ban:', result.removed); // true
+     * console.log('Token:', result.tokenName);
+     * ```
+     */
+    unbanToken(options: UnbanTokenOptions): Promise<UnbanTokenResult>;
+    /**
+     * List all banned tokens
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (overseer) auth.
+     * Returns paginated results with ban details.
+     *
+     * @param options - List options including optional cursor-based pagination and search
+     * @returns Paginated list of banned tokens
+     * @throws ValidationError if pagination parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     * @updated 8.1.0 - Migrated to cursor-based pagination
+     *
+     * @example
+     * ```typescript
+     * // Get first page (default limit 20)
+     * const page1 = await tokenBanService.listTokenBans({ pageSize: 20 });
+     * console.log('Total banned tokens:', page1.pageInfo.totalCount);
+     *
+     * // Search for specific tokens
+     * const searchResults = await tokenBanService.listTokenBans({
+     *   search: 'scam',
+     *   pageSize: 10
+     * });
+     *
+     * // Paginate through all results (cursor-based)
+     * let cursor: string | undefined;
+     * let hasMore = true;
+     * while (hasMore) {
+     *   const results = await tokenBanService.listTokenBans({
+     *     pageSize: 20,
+     *     cursor
+     *   });
+     *   console.log('Bans:', results.items);
+     *   hasMore = results.pageInfo.hasNextPage;
+     *   cursor = results.pageInfo.nextCursor;
+     * }
+     * ```
+     */
+    listTokenBans(options?: ListTokenBansOptions): Promise<TokenBanListResult>;
+    /**
+     * Get ban details for a specific token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (overseer) auth.
+     *
+     * Returns the ban record if the token is banned, or null if not banned.
+     * Use this to get full ban details including reason and who banned it.
+     *
+     * @param options - Options including tokenName
+     * @returns Ban data if banned, null if not banned
+     * @throws ValidationError if token name is invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * const status = await tokenBanService.getTokenBan({ tokenName: 'sometoken' });
+     * if (status.banned) {
+     *   console.log('Token is banned');
+     *   console.log('Reason:', status.ban?.reason);
+     *   console.log('Banned by:', status.ban?.bannedBy);
+     *   console.log('Banned at:', status.ban?.createdAt);
+     * } else {
+     *   console.log('Token is not banned');
+     * }
+     * ```
+     */
+    getTokenBan(options: GetTokenBanOptions): Promise<TokenBanStatusResult>;
+    /**
+     * Check if a token is banned (convenience method)
+     *
+     * Alias for getTokenBan() - provided for semantic clarity.
+     * Use when you just need to check if a token is banned.
+     *
+     * @param options - Options including tokenName
+     * @returns Ban status with full details if banned
+     * @throws ValidationError if token name is invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * const status = await tokenBanService.isTokenBanned({ tokenName: 'sometoken' });
+     * if (status.banned) {
+     *   console.log('Token is banned:', status.ban?.reason);
+     * }
+     * ```
+     */
+    isTokenBanned(options: GetTokenBanOptions): Promise<TokenBanStatusResult>;
+}
+//# sourceMappingURL=TokenBanService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TokenBanService.d.ts","sourceRoot":"","sources":["../../src/services/TokenBanService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAIe,oBAAoB,EACrD,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAOlD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,eAAgB,SAAQ,sBAAsB;gBAEvD,IAAI,EAAE,UAAU,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,EACjB,SAAS,GAAE,OAAe,EAC1B,UAAU,CAAC,EAAE,MAAM;IASrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAoCjE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqBvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAuBpF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAuB7E;;;;;;;;;;;;;;;;;;OAkBG;IACG,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAGhF"}

package/dist/services/TokenClassKeyService.d.ts

@@ -0,0 +1,162 @@
+/**
+ * TokenClassKey Service for String Instructions Generation
+ *
+ * This service handles the generation of stringsInstructions arrays
+ * for bundle transactions. It creates the proper resource tracking
+ * strings that match the exact format used by the frontend.
+ *
+ * ## String Instructions Format:
+ * 1. launchPadSalePreBuy: $service$[tokenKey]$launchpad
+ * 2. memetokenBalancePool: $tokenBalance$[tokenKey]$[vaultAddress]
+ * 3. memetokenBalanceUser: $tokenBalance$[tokenKey]$[vaultAddress]
+ * 4. poolNativeBalance: $tokenBalance$[galaKey]$[vaultAddress]
+ * 5. userNativeBalance: $tokenBalance$[galaKey]$[vaultAddress]
+ *
+ * ## TokenClassKey Structure:
+ * - collection: 'Token' (for launchpad tokens) or 'GALA' (for native)
+ * - category: 'Unit'
+ * - type: Token symbol or 'none'
+ * - additionalKey: 'none'
+ *
+ * @category Services
+ * @since 2.0.0
+ */
+import { TokenClassKey } from '@gala-chain/api';
+import { LoggerBase } from './BaseService';
+/**
+ * Service for generating TokenClassKey and stringsInstructions
+ */
+export declare class TokenClassKeyService extends LoggerBase {
+    constructor(debugMode?: boolean);
+    /**
+     * Generate stringsInstructions array for a vault address
+     *
+     * Creates the 5-element array required for bundle transactions:
+     * [launchPadSalePreBuy, memetokenBalancePool, memetokenBalanceUser, poolNativeBalance, userNativeBalance]
+     *
+     * @param vaultAddress - Vault address in format: service|Token$Unit$SYMBOL$eth:address$launchpad
+     * @returns Array of strings for resource tracking
+     *
+     * @example
+     * ```typescript
+     * const instructions = service.generateStringsInstructions(
+     *   'service|Token$Unit$ANIME$eth:1234567890$launchpad'
+     * );
+     * // Returns:
+     * // [
+     * //   '$service$Token$Unit$ANIME$none$launchpad',
+     * //   '$tokenBalance$Token$Unit$ANIME$none$service|Token$Unit$ANIME$eth:1234567890$launchpad',
+     * //   '$tokenBalance$Token$Unit$ANIME$none$service|Token$Unit$ANIME$eth:1234567890$launchpad',
+     * //   '$tokenBalance$GALA$Unit$none$none$service|Token$Unit$ANIME$eth:1234567890$launchpad',
+     * //   '$tokenBalance$GALA$Unit$none$none$service|Token$Unit$ANIME$eth:1234567890$launchpad'
+     * // ]
+     * ```
+     */
+    generateStringsInstructions(vaultAddress: string): string[];
+    /**
+     * Create TokenClassKey instance for launchpad token
+     *
+     * Constructs a properly formatted TokenClassKey for a launchpad token using its symbol.
+     * **Critical**: Always converts symbol to lowercase for collection field to match frontend
+     * format and ensure consistent string instruction generation.
+     *
+     * **Format**: `{ collection: lowercase_symbol, category: 'Unit', type: 'none', additionalKey: 'none' }`
+     *
+     * @param tokenSymbol Token symbol (e.g., 'ANIME', 'CLAUDE') - converted to lowercase internally
+     * @returns TokenClassKey instance with lowercase collection field
+     * @category Token Identification
+     * @since 2.0.0
+     *
+     * @example Create token instance
+     * ```typescript
+     * const tokenKey = service.createTokenInstance('ANIME');
+     * console.log(tokenKey.toStringKey());
+     * // Output: 'anime$Unit$none$none'
+     * ```
+     */
+    createTokenInstance(tokenSymbol: string): TokenClassKey;
+    /**
+     * Create TokenClassKey instance for GALA native token
+     *
+     * Constructs the standard TokenClassKey for GALA (GalaChain's native token).
+     * Used in bundle transactions for tracking GALA balance changes in pools and user wallets.
+     *
+     * **Format**: `{ collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' }`
+     *
+     * @returns TokenClassKey instance for GALA with uppercase collection field
+     * @category Token Identification
+     * @since 2.0.0
+     *
+     * @example Create GALA instance
+     * ```typescript
+     * const galaKey = service.createGalaInstance();
+     * console.log(galaKey.toStringKey());
+     * // Output: 'GALA$Unit$none$none'
+     * ```
+     */
+    createGalaInstance(): TokenClassKey;
+    /**
+     * Extract token symbol from vault address
+     *
+     * @param vaultAddress - Vault address in format: service|Token$Unit$SYMBOL$eth:address$launchpad
+     * @returns Token symbol
+     *
+     * @example
+     * ```typescript
+     * const symbol = service.extractTokenSymbolFromVault(
+     *   'service|Token$Unit$ANIME$eth:1234567890$launchpad'
+     * );
+     * // Returns: 'ANIME'
+     * ```
+     */
+    extractTokenSymbolFromVault(vaultAddress: string): string;
+    /**
+     * Validate vault address format for launchpad tokens
+     *
+     * Checks that a vault address conforms to the expected GalaChain launchpad format:
+     * - Starts with 'service|Token$Unit$'
+     * - Ends with '$launchpad'
+     * - Contains valid token symbol (1-10 letters, case insensitive)
+     * - Has at least 5 parts separated by '$'
+     *
+     * **Format**: `service|Token$Unit$SYMBOL$eth:address$launchpad`
+     *
+     * @param vaultAddress Vault address string to validate
+     * @returns true if valid (throws ValidationError if invalid)
+     * @throws ValidationError if format is invalid
+     * @category Token Identification
+     * @since 2.0.0
+     *
+     * @example Validate vault address
+     * ```typescript
+     * const isValid = service.validateVaultAddress(
+     *   'service|Token$Unit$ANIME$eth:1234567890$launchpad'
+     * );
+     * // Returns: true
+     * ```
+     */
+    validateVaultAddress(vaultAddress: string): boolean;
+    /**
+     * Generate TokenClassKey string representation
+     *
+     * @param collection - Collection name
+     * @param category - Category name
+     * @param type - Type name
+     * @param additionalKey - Additional key
+     * @returns String key in format: collection$category$type$additionalKey
+     */
+    generateTokenClassKeyString(collection: string, category: string, type: string, additionalKey: string): string;
+    /**
+     * Parse TokenClassKey from string representation
+     *
+     * @param stringKey - String key in format: collection$category$type$additionalKey
+     * @returns Parsed TokenClassKey components
+     */
+    parseTokenClassKeyString(stringKey: string): {
+        collection: string;
+        category: string;
+        type: string;
+        additionalKey: string;
+    };
+}
+//# sourceMappingURL=TokenClassKeyService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TokenClassKeyService.d.ts","sourceRoot":"","sources":["../../src/services/TokenClassKeyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAYhD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;gBACtC,SAAS,GAAE,OAAe;IAItC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE;IAwC3D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa;IAgBvD;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAAkB,IAAI,aAAa;IAcnC;;;;;;;;;;;;;OAaG;IACH,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IA0BzD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IA4CnD;;;;;;;;OAQG;IACH,2BAA2B,CACzB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,GACpB,MAAM;IAIT;;;;;OAKG;IACH,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG;QAC3C,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,EAAE,MAAM,CAAC;KACvB;CAcF"}