@gala-chain/launchpad-sdk 3.23.0 → 3.24.1

package/dist/services/GSwapService.d.ts

@@ -0,0 +1,59 @@
+/**
+ * GSwapService - Wraps @gala-chain/gswap-sdk for DEX trading integration
+ *
+ * Provides high-level interface to GalaSwap SDK for:
+ * - Token swapping with slippage protection
+ * - Quote generation (exact input/output)
+ * - User asset queries
+ * - Pool information
+ * - Real-time transaction monitoring
+ */
+import { WebSocketService } from './WebSocketService';
+import type { SwapQuoteParams, SwapQuoteResult, ExecuteSwapParams, ExecuteSwapResult, UserAsset, PoolInfo, GSwapServiceConfig } from '../types/gswap.dto';
+export declare class GSwapService {
+    private gswap;
+    private tokenConverter;
+    private webSocketService;
+    private logger;
+    constructor(config: GSwapServiceConfig, webSocketService: WebSocketService);
+    /**
+     * Get swap quote for exact input (spending known amount)
+     * @param params Quote request with fromToken, toToken, and input amount
+     * @returns Quote with estimated output and fees
+     */
+    getSwapQuoteExactInput(params: SwapQuoteParams): Promise<SwapQuoteResult>;
+    /**
+     * Get swap quote for exact output (receive known amount)
+     * @param params Quote request with fromToken, toToken, and desired output
+     * @returns Quote with required input and fees
+     */
+    getSwapQuoteExactOutput(params: SwapQuoteParams): Promise<SwapQuoteResult>;
+    /**
+     * Execute a token swap with slippage protection
+     * @param params Swap execution parameters
+     * @returns Swap result with transaction details
+     */
+    executeSwap(params: ExecuteSwapParams): Promise<ExecuteSwapResult>;
+    /**
+     * Get user's token assets/balances
+     * @param walletAddress User's wallet address
+     * @returns Array of user assets with balances
+     */
+    getUserAssets(walletAddress: string): Promise<UserAsset[]>;
+    /**
+     * Get pool information for token pair
+     * @param tokenA First token
+     * @param tokenB Second token
+     * @returns Pool information
+     */
+    getPoolInfo(tokenA: string, tokenB: string): Promise<PoolInfo>;
+    /**
+     * Calculate price impact percentage
+     */
+    private calculatePriceImpact;
+    /**
+     * Calculate execution price (output per unit input)
+     */
+    private calculateExecutionPrice;
+}
+//# sourceMappingURL=GSwapService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GSwapService.d.ts","sourceRoot":"","sources":["../../src/services/GSwapService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAOtD,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,QAAQ,EACR,kBAAkB,EACnB,MAAM,oBAAoB,CAAC;AAE5B,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,gBAAgB;IA0C1E;;;;OAIG;IACG,sBAAsB,CAC1B,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,eAAe,CAAC;IAkD3B;;;;OAIG;IACG,uBAAuB,CAC3B,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,eAAe,CAAC;IAgD3B;;;;OAIG;IACG,WAAW,CACf,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,iBAAiB,CAAC;IAqF7B;;;;OAIG;IACG,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IA6ChE;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAmEpE;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAsB5B;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAehC"}

package/dist/services/TokenMetadataService.d.ts

@@ -0,0 +1,113 @@
+/**
+ * TokenMetadataService - Proper Token Metadata Resolution
+ *
+ * This service provides authoritative token metadata by querying the GalaChain network
+ * for real token data. It should be used instead of trying to infer metadata from
+ * token format strings.
+ *
+ * Key Responsibilities:
+ * - Query GalaChain for real token metadata via GalaChainService
+ * - Cache results to minimize network calls
+ * - Handle token resolution for both native and wrapped tokens
+ * - Provide clean interface for symbol, decimals, and other metadata
+ */
+import type { TokenClass } from '../types/gswap.dto';
+export interface TokenMetadata {
+    symbol: string;
+    name?: string;
+    decimals: number;
+    collection: string;
+    category: string;
+    type: string;
+    additionalKey: string;
+    verified: boolean;
+}
+export interface TokenMetadataCache {
+    [key: string]: {
+        data: TokenMetadata;
+        timestamp: number;
+    };
+}
+export declare class TokenMetadataService {
+    private cache;
+    private cacheExpiry;
+    private logger;
+    constructor();
+    /**
+     * Resolve token metadata from a token reference
+     *
+     * Supports multiple input formats:
+     * - Simple symbol: "GALA"
+     * - Pipe-delimited: "GALA|Unit|none|none"
+     * - TokenClass object: { type: "GALA", ... }
+     * - Full format: "Token|Unit|GUSDC|eth:0x..."
+     *
+     * ⚠️ CRITICAL NOTE: This method should be used when you need REAL token metadata
+     * from blockchain. For format conversion only, use TokenFormatConverter.
+     *
+     * @param token Token reference (symbol, format string, or TokenClass object)
+     * @returns Token metadata with verified symbol and decimals from blockchain
+     */
+    resolveTokenMetadata(token: string | TokenClass): Promise<TokenMetadata>;
+    /**
+     * Get symbol for a token
+     *
+     * ✅ This is the CORRECT way to get token symbols
+     * ❌ WRONG: Trying to infer from token format string
+     * ✅ CORRECT: Query GalaChain via fetchTokenClassFromChain()
+     *
+     * @param token Token reference
+     * @returns Real token symbol from blockchain
+     */
+    getTokenSymbol(token: string | TokenClass): Promise<string>;
+    /**
+     * Get decimals for a token
+     *
+     * @param token Token reference
+     * @returns Token decimals from blockchain
+     */
+    getTokenDecimals(token: string | TokenClass): Promise<number>;
+    /**
+     * Clear cache to force fresh queries
+     */
+    clearCache(tokenKey?: string): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        entries: string[];
+    };
+    /**
+     * Generate cache key from token reference
+     * @private
+     */
+    private getCacheKey;
+    /**
+     * Extract metadata from token reference
+     *
+     * ⚠️ IMPORTANT: This is a PLACEHOLDER implementation
+     * In production, this should query GalaChainService.fetchTokenClassFromChain()
+     * to get REAL metadata from the blockchain.
+     * @private
+     */
+    private extractMetadata;
+    /**
+     * Get known decimals for standard tokens
+     *
+     * ⚠️ HARDCODED VALUES - In production, query blockchain!
+     * @private
+     */
+    private getDecimalsForToken;
+    /**
+     * Check if cache entry has expired
+     * @private
+     */
+    private isCacheExpired;
+    /**
+     * Set cache expiry duration
+     * @param ms Milliseconds before cache expires (default: 1 hour)
+     */
+    setCacheExpiry(ms: number): void;
+}
+//# sourceMappingURL=TokenMetadataService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TokenMetadataService.d.ts","sourceRoot":"","sources":["../../src/services/TokenMetadataService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG;QACb,IAAI,EAAE,aAAa,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,MAAM,CAAS;;IAMvB;;;;;;;;;;;;;;OAcG;IACG,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAyB9E;;;;;;;;;OASG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAKjE;;;;;OAKG;IACG,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAKnE;;OAEG;IACH,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAUnC;;OAEG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE;IAQpD;;;OAGG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAqDvB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAItB;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAIjC"}

package/dist/setup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Jest setup file for test environment configuration
+ *
+ * This file is placed in src/ to satisfy TypeScript's rootDir configuration
+ * while remaining in the test environment setup pipeline via jest.config.js
+ */
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/types/gswap.dto.d.ts

@@ -0,0 +1,139 @@
+/**
+ * GSwap SDK Type Definitions and DTOs
+ *
+ * Interfaces for GalaSwap integration including:
+ * - Service configuration
+ * - Swap requests and responses
+ * - Asset and pool information
+ */
+/**
+ * Token class representation
+ * Used for identifying tokens in GSwap API
+ */
+export interface TokenClass {
+    collection: string;
+    category: string;
+    type: string;
+    additionalKey: string;
+}
+/**
+ * GSwapService configuration
+ * @agent Configuration for initializing GSwap trading service with optional wallet support and environment URLs
+ */
+export interface GSwapServiceConfig {
+    privateKey?: string | undefined;
+    walletAddress?: string | undefined;
+    gatewayBaseUrl?: string | undefined;
+    bundlerBaseUrl?: string | undefined;
+    dexBackendBaseUrl?: string | undefined;
+}
+/**
+ * Parameters for getting swap quotes
+ * @agent Use to request price quotes before executing swaps. Supports both exact-input (known spend) and exact-output (known receive) patterns
+ */
+export interface SwapQuoteParams {
+    fromToken: string;
+    toToken: string;
+    amount: string;
+}
+/**
+ * Result from swap quote
+ * @agent Contains price, impact, and fee information needed for executeSwap. Always get quote before executing swap
+ */
+export interface SwapQuoteResult {
+    fromToken: string;
+    toToken: string;
+    inputAmount: string;
+    estimatedOutput: string;
+    feeTier: number;
+    priceImpact: string;
+    executionPrice: string;
+}
+/**
+ * Parameters for executing a swap
+ * @agent Use to execute DEX trade with slippage protection. Must pass estimatedOutput and feeTier from quote result
+ */
+export interface ExecuteSwapParams {
+    fromToken: string;
+    toToken: string;
+    inputAmount: string;
+    estimatedOutput: string;
+    feeTier: number;
+    slippageTolerance?: number;
+}
+/**
+ * Result from executing a swap
+ * @agent Contains transaction details after swap execution. Monitor via transactionId for real-time status updates
+ */
+export interface ExecuteSwapResult {
+    transactionId: string;
+    status: string;
+    fromToken: string;
+    toToken: string;
+    inputAmount: string;
+    outputAmount: string;
+    feeTier: number;
+    slippageTolerance: number;
+    timestamp: Date;
+}
+/**
+ * User asset (token balance)
+ * @agent Represents a single token holding in user's DEX portfolio. Retrieved via getSwapUserAssets()
+ */
+export interface UserAsset {
+    tokenId: any;
+    symbol: string;
+    balance: string;
+    decimals: number;
+}
+/**
+ * Pool information for token pair
+ * @agent Provides liquidity and fee tier data for token pairs. Use to assess pool depth and fee structure before trading
+ */
+export interface PoolInfo {
+    tokenA: string;
+    tokenB: string;
+    liquidity: string;
+    feeTiers: number[];
+    swapCount: number;
+}
+/**
+ * GSwap API error response
+ */
+export interface GSwapError {
+    code: string;
+    message: string;
+    details?: any;
+}
+/**
+ * Options for swap execution
+ */
+export interface SwapExecutionOptions {
+    maxSlippage?: number;
+    timeout?: number;
+    waitForCompletion?: boolean;
+    feeMultiplier?: number;
+}
+/**
+ * Detailed quote with breakdown
+ */
+export interface DetailedQuote extends SwapQuoteResult {
+    fees: {
+        protocolFee: string;
+        liquidityProviderFee: string;
+        totalFee: string;
+        effectiveFeePercentage: string;
+    };
+    execution: {
+        minOutputWithSlippage: string;
+        maxInputWithSlippage?: string;
+        path: string[];
+        liquidityProviders: string[];
+    };
+    risk: {
+        highSlippage: boolean;
+        untrustedPools: boolean;
+        warnings: string[];
+    };
+}
+//# sourceMappingURL=gswap.dto.d.ts.map

package/dist/types/gswap.dto.d.ts.map

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

package/dist/utils/errors.d.ts

@@ -168,4 +168,181 @@ export declare class TransactionError extends Error {
      */
     constructor(message: string, transactionId?: string | undefined, code?: string | undefined);
 }
+/**
+ * Error thrown when GSwap SDK quote operations fail
+ *
+ * This error is thrown during quote generation (exact input or exact output).
+ * It preserves the original GSwap SDK error for detailed diagnostics.
+ *
+ * @example Quote generation failure
+ * ```typescript
+ * throw new GSwapQuoteError(
+ *   'Failed to get quote for GALA to GUSDC swap',
+ *   originalGSwapError,
+ *   'POOL_NOT_FOUND'
+ * );
+ * ```
+ *
+ * @example Catching quote errors
+ * ```typescript
+ * try {
+ *   const quote = await service.getSwapQuoteExactInput({ fromToken: 'GALA', toToken: 'GUSDC', amount: '100' });
+ * } catch (error) {
+ *   if (error instanceof GSwapQuoteError) {
+ *     console.log(`Quote failed: ${error.message}`);
+ *     console.log(`GSwap error: ${error.code}`);
+ *     // Implement user notification
+ *   }
+ * }
+ * ```
+ */
+export declare class GSwapQuoteError extends Error {
+    originalError: unknown;
+    code?: string | undefined;
+    /**
+     * Creates a new GSwapQuoteError
+     *
+     * @param message - Human-readable error message describing what failed
+     * @param originalError - The original error from GSwap SDK
+     * @param code - Optional error code from GSwap SDK for programmatic handling
+     */
+    constructor(message: string, originalError: unknown, code?: string | undefined);
+}
+/**
+ * Error thrown when GSwap SDK swap execution fails
+ *
+ * This error is thrown during token swap execution (buy/sell operations).
+ * It preserves the original GSwap SDK error and transaction details.
+ *
+ * @example Swap execution failure
+ * ```typescript
+ * throw new GSwapSwapError(
+ *   'Token swap failed: insufficient balance',
+ *   originalGSwapError,
+ *   'txHash123',
+ *   'INSUFFICIENT_BALANCE'
+ * );
+ * ```
+ *
+ * @example Catching swap errors
+ * ```typescript
+ * try {
+ *   const result = await service.executeSwap(swapParams);
+ * } catch (error) {
+ *   if (error instanceof GSwapSwapError) {
+ *     console.log(`Swap failed: ${error.message}`);
+ *     if (error.transactionHash) {
+ *       console.log(`TX: ${error.transactionHash}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class GSwapSwapError extends Error {
+    originalError: unknown;
+    transactionHash?: string | undefined;
+    code?: string | undefined;
+    /**
+     * Creates a new GSwapSwapError
+     *
+     * @param message - Human-readable error message describing what failed
+     * @param originalError - The original error from GSwap SDK
+     * @param transactionHash - Optional transaction hash for transaction tracking
+     * @param code - Optional error code from GSwap SDK for programmatic handling
+     */
+    constructor(message: string, originalError: unknown, transactionHash?: string | undefined, code?: string | undefined);
+}
+/**
+ * Error thrown when GSwap SDK pool operations fail
+ *
+ * This error is thrown when pool-related queries fail, including:
+ * - Pool information retrieval
+ * - Available token swaps querying
+ * - Pool data access errors
+ *
+ * @example Pool query failure
+ * ```typescript
+ * throw new GSwapPoolError(
+ *   'Pool not found for GALA/GUSDC pair',
+ *   originalGSwapError,
+ *   'GALA',
+ *   'GUSDC',
+ *   'POOL_NOT_FOUND'
+ * );
+ * ```
+ *
+ * @example Catching pool errors
+ * ```typescript
+ * try {
+ *   const poolInfo = await service.getPoolInfo('GALA', 'GUSDC');
+ * } catch (error) {
+ *   if (error instanceof GSwapPoolError) {
+ *     console.log(`Pool error: ${error.message}`);
+ *     if (error.code === 'POOL_NOT_FOUND') {
+ *       console.log(`No pool for ${error.tokenA}/${error.tokenB}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class GSwapPoolError extends Error {
+    originalError: unknown;
+    tokenA?: string | undefined;
+    tokenB?: string | undefined;
+    code?: string | undefined;
+    /**
+     * Creates a new GSwapPoolError
+     *
+     * @param message - Human-readable error message describing what failed
+     * @param originalError - The original error from GSwap SDK
+     * @param tokenA - Optional token A symbol in the pool pair
+     * @param tokenB - Optional token B symbol in the pool pair
+     * @param code - Optional error code from GSwap SDK for programmatic handling
+     */
+    constructor(message: string, originalError: unknown, tokenA?: string | undefined, tokenB?: string | undefined, code?: string | undefined);
+}
+/**
+ * Error thrown when GSwap SDK asset/balance operations fail
+ *
+ * This error is thrown when asset-related queries fail, including:
+ * - User asset/balance retrieval
+ * - Portfolio data access errors
+ * - Asset validation failures
+ *
+ * @example Asset query failure
+ * ```typescript
+ * throw new GSwapAssetError(
+ *   'Failed to fetch user assets',
+ *   originalGSwapError,
+ *   'userAddress123',
+ *   'NETWORK_ERROR'
+ * );
+ * ```
+ *
+ * @example Catching asset errors
+ * ```typescript
+ * try {
+ *   const assets = await service.getUserAssets(walletAddress);
+ * } catch (error) {
+ *   if (error instanceof GSwapAssetError) {
+ *     console.log(`Asset query failed: ${error.message}`);
+ *     console.log(`Wallet: ${error.walletAddress}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class GSwapAssetError extends Error {
+    originalError: unknown;
+    walletAddress?: string | undefined;
+    code?: string | undefined;
+    /**
+     * Creates a new GSwapAssetError
+     *
+     * @param message - Human-readable error message describing what failed
+     * @param originalError - The original error from GSwap SDK
+     * @param walletAddress - Optional wallet address being queried
+     * @param code - Optional error code from GSwap SDK for programmatic handling
+     */
+    constructor(message: string, originalError: unknown, walletAddress?: string | undefined, code?: string | undefined);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAU/B,KAAK,CAAC,EAAE,MAAM;IACd,IAAI,CAAC,EAAE,MAAM;IAVtB;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACR,KAAK,CAAC,EAAE,MAAM,YAAA,EACd,IAAI,CAAC,EAAE,MAAM,YAAA;CAKvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAU5B,UAAU,CAAC,EAAE,MAAM;IACnB,aAAa,CAAC,EAAE,KAAK;IAV9B;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACR,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,aAAa,CAAC,EAAE,KAAK,YAAA;CAK/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IASlC,KAAK,CAAC,EAAE,MAAM;IARvB;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACR,KAAK,CAAC,EAAE,MAAM,YAAA;CAKxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAUhC,aAAa,CAAC,EAAE,MAAM;IACtB,IAAI,CAAC,EAAE,MAAM;IAVtB;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACR,aAAa,CAAC,EAAE,MAAM,YAAA,EACtB,IAAI,CAAC,EAAE,MAAM,YAAA;CAKvB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAU/B,KAAK,CAAC,EAAE,MAAM;IACd,IAAI,CAAC,EAAE,MAAM;IAVtB;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACR,KAAK,CAAC,EAAE,MAAM,YAAA,EACd,IAAI,CAAC,EAAE,MAAM,YAAA;CAKvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAU5B,UAAU,CAAC,EAAE,MAAM;IACnB,aAAa,CAAC,EAAE,KAAK;IAV9B;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACR,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,aAAa,CAAC,EAAE,KAAK,YAAA;CAK/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IASlC,KAAK,CAAC,EAAE,MAAM;IARvB;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACR,KAAK,CAAC,EAAE,MAAM,YAAA;CAKxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAUhC,aAAa,CAAC,EAAE,MAAM;IACtB,IAAI,CAAC,EAAE,MAAM;IAVtB;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACR,aAAa,CAAC,EAAE,MAAM,YAAA,EACtB,IAAI,CAAC,EAAE,MAAM,YAAA;CAKvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAU/B,aAAa,EAAE,OAAO;IACtB,IAAI,CAAC,EAAE,MAAM;IAVtB;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACR,aAAa,EAAE,OAAO,EACtB,IAAI,CAAC,EAAE,MAAM,YAAA;CAKvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,cAAe,SAAQ,KAAK;IAW9B,aAAa,EAAE,OAAO;IACtB,eAAe,CAAC,EAAE,MAAM;IACxB,IAAI,CAAC,EAAE,MAAM;IAZtB;;;;;;;OAOG;gBAED,OAAO,EAAE,MAAM,EACR,aAAa,EAAE,OAAO,EACtB,eAAe,CAAC,EAAE,MAAM,YAAA,EACxB,IAAI,CAAC,EAAE,MAAM,YAAA;CAKvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,cAAe,SAAQ,KAAK;IAY9B,aAAa,EAAE,OAAO;IACtB,MAAM,CAAC,EAAE,MAAM;IACf,MAAM,CAAC,EAAE,MAAM;IACf,IAAI,CAAC,EAAE,MAAM;IAdtB;;;;;;;;OAQG;gBAED,OAAO,EAAE,MAAM,EACR,aAAa,EAAE,OAAO,EACtB,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,IAAI,CAAC,EAAE,MAAM,YAAA;CAKvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAW/B,aAAa,EAAE,OAAO;IACtB,aAAa,CAAC,EAAE,MAAM;IACtB,IAAI,CAAC,EAAE,MAAM;IAZtB;;;;;;;OAOG;gBAED,OAAO,EAAE,MAAM,EACR,aAAa,EAAE,OAAO,EACtB,aAAa,CAAC,EAAE,MAAM,YAAA,EACtB,IAAI,CAAC,EAAE,MAAM,YAAA;CAKvB"}

package/dist/utils/token-format-converter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * TokenFormatConverter - Converts between different token ID formats
+ *
+ * ⚠️ CRITICAL ARCHITECTURAL NOTE:
+ * This utility is for FORMAT CONVERSION ONLY (pipe-delimited ↔ object/string).
+ * Do NOT use for symbol extraction or metadata inference!
+ *
+ * For symbol/metadata resolution:
+ * - Use GalaChainService.fetchTokenClassFromChain() to query real blockchain data
+ * - Use DexService.fetchTokenDetails() for complete token metadata
+ * - Use data from GSwap SDK responses directly (already contains correct symbols)
+ *
+ * Launchpad SDK uses: { collection, category, type, additionalKey }
+ * GSwap SDK uses: "symbol|Unit|none|none" (pipe-delimited string)
+ *
+ * This utility handles bidirectional conversion between formats.
+ */
+import type { TokenClass } from '../types/gswap.dto';
+export declare class TokenFormatConverter {
+    /**
+     * Convert Launchpad token format to GSwap format (pipe-delimited string)
+     *
+     * ⚠️ WARNING: For API format conversion ONLY
+     * This does NOT validate or resolve token symbols - it's structural only.
+     *
+     * Input: "GALA" or "GALA|Unit|none|none" or { collection: "Token", category: "Unit", type: "GALA", additionalKey: "none" }
+     * Output: "GALA|Unit|none|none"
+     */
+    toLaunchpadFormat(token: string | TokenClass | any): string;
+    /**
+     * Convert GSwap format (pipe-delimited) to TokenClass object
+     *
+     * ⚠️ WARNING: For API format conversion ONLY
+     * This does NOT provide real symbol/metadata - it's structural only.
+     * For actual token data, use GalaChainService.fetchTokenClassFromChain()
+     *
+     * Input: "GALA|Unit|none|none" or { type: "GALA", ... }
+     * Output: { collection: "Token", category: "Unit", type: "GALA", additionalKey: "none" }
+     */
+    toTokenClass(token: string | TokenClass | any): TokenClass;
+    /**
+     * Check if token is in pipe-delimited format
+     * Input: "GALA|Unit|none|none" → true
+     * Input: "GALA" → false
+     */
+    isGSwapFormat(token: string): boolean;
+    /**
+     * Normalize any token format to pipe-delimited GSwap format
+     *
+     * ⚠️ WARNING: For API format conversion ONLY
+     * Does not validate or resolve symbols - structural conversion only.
+     *
+     * Input: "GALA" or "GALA|Unit|none|none" or { type: "GALA" }
+     * Output: "GALA|Unit|none|none"
+     */
+    normalize(token: string | TokenClass): string;
+}
+//# sourceMappingURL=token-format-converter.d.ts.map

package/dist/utils/token-format-converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-format-converter.d.ts","sourceRoot":"","sources":["../../src/utils/token-format-converter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,qBAAa,oBAAoB;IAC/B;;;;;;;;OAQG;IACH,iBAAiB,CACf,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,GAAG,GAC/B,MAAM;IAuBT;;;;;;;;;OASG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,GAAG,GAAG,UAAU;IAmC1D;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM;CAY9C"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gala-chain/launchpad-sdk",
-  "version": "3.23.0",
-  "description": "TypeScript SDK for Gala Launchpad Backend API - 59 methods supporting optional wallet (read-only and full-access modes). Production-ready DeFi token launchpad integration with AgentConfig setup, GalaChain trading, price history, token creation, and comprehensive user operations. Multi-format output (ESM, CJS, UMD).",
+  "version": "3.24.1",
+  "description": "TypeScript SDK for Gala Launchpad Backend API - 64 methods supporting optional wallet (read-only and full-access modes). Production-ready DeFi token launchpad integration with AgentConfig setup, GalaChain trading, GSwap DEX integration, price history, token creation, and comprehensive user operations. Multi-format output (ESM, CJS, UMD).",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
   "types": "dist/index.d.ts",
@@ -148,6 +148,7 @@
   "dependencies": {
     "@gala-chain/api": "^2.4.3",
     "@gala-chain/connect": "^2.4.3",
+    "@gala-chain/gswap-sdk": "^0.0.9",
     "@types/uuid": "^10.0.0",
     "axios": "^1.12.2",
     "bignumber.js": "^9.1.2",