@gala-chain/launchpad-sdk 3.31.0 → 4.0.0

package/dist/utils/token-parser.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Safe Token Parser - Comprehensive token format validation and parsing
+ *
+ * Handles STRICT parsing of token formats received from APIs:
+ * - Pipe-delimited: "GALA|Unit|none|none"
+ * - Dollar-delimited: "GALA$Unit$none$none"
+ * - Dollar with $ in collection: "$MUSIC$Unit$none$none" (parses from END)
+ *
+ * CRITICAL SECURITY NOTE:
+ * Plain strings like "GALA" are REJECTED by default - they are not valid token formats!
+ * Token formats MUST be explicitly delimited with | or $.
+ * This prevents dangerous assumptions about token structure.
+ *
+ * @packageDocumentation
+ */
+import type { TokenClassKey } from '../types/common';
+/**
+ * PERFORMANCE CHARACTERISTICS:
+ *
+ * Fast-path (O(n) where n = token length):
+ * - Pipe-delimited tokens: Direct split() call, minimal string operations
+ * - Dollar-delimited tokens: Reverse algorithm, ~2x string operations
+ *
+ * Slow-path (format detection):
+ * - Plain strings without delimiters: Requires fallback logic
+ * - Type validation: Object instanceof checks for already-parsed tokens
+ *
+ * Recommendation: Pre-detect format when parsing large token batches:
+ * ```typescript
+ * import { isPipeDelimited, isDollarDelimited } from './token-parser';
+ *
+ * if (isPipeDelimited(token)) {
+ *   return parsePipeDelimitedToken(token);  // Fastest path
+ * } else if (isDollarDelimited(token)) {
+ *   return parseDollarDelimitedTokenSafe(token);  // Fast path
+ * }
+ * ```
+ */
+/**
+ * Parse token from ANY format (pipe/dollar delimited) into TokenClassKey
+ *
+ * Accepts:
+ * - Pipe format: "GALA|Unit|none|none"
+ * - Dollar format: "GALA$Unit$none$none"
+ * - Dollar with $ in collection: "$MUSIC$Unit$none$none"
+ * - TokenClassKey objects: { collection, category, type, additionalKey }
+ *
+ * REJECTS:
+ * - Plain strings like "GALA" (DANGEROUS - no delimiters!)
+ * - Null/undefined values
+ * - Invalid formats
+ *
+ * ⚠️ SECURITY ENFORCEMENT (v3.33.0+):
+ * Plain token strings are NO LONGER accepted. All tokens must use explicit delimiters.
+ * This is a breaking change to enforce secure token format validation.
+ *
+ * @param token Token string to parse
+ * @returns TokenClassKey with { collection, category, type, additionalKey }
+ * @throws ValidationError if format is invalid or if plain string is provided
+ *
+ * @example
+ * ```typescript
+ * // Pipe-delimited (RECOMMENDED)
+ * parseToken("GALA|Unit|none|none")
+ * // → { collection: "GALA", category: "Unit", type: "none", additionalKey: "none" }
+ *
+ * // Dollar-delimited
+ * parseToken("GALA$Unit$none$none")
+ * // → { collection: "GALA", category: "Unit", type: "none", additionalKey: "none" }
+ *
+ * // Dollar with $ in collection (EDGE CASE)
+ * parseToken("$MUSIC$Unit$none$none")
+ * // → { collection: "$MUSIC", category: "Unit", type: "none", additionalKey: "none" }
+ *
+ * // TokenClassKey object
+ * parseToken({ collection: "GALA", category: "Unit", type: "none", additionalKey: "none" })
+ * // → { collection: "GALA", category: "Unit", type: "none", additionalKey: "none" }
+ *
+ * // Plain string - PERMANENTLY REJECTED
+ * parseToken("GALA")  // Throws ValidationError
+ * ```
+ *
+ * @since 3.32.0
+ * @updated 3.33.0 - Removed allowPlainStrings parameter, enforce strict delimiter-only parsing
+ */
+export declare function parseToken(token: string | TokenClassKey | undefined | null): TokenClassKey;
+/**
+ * Parse pipe-delimited token: "GALA|Unit|none|none"
+ *
+ * @internal Used by parseToken()
+ * @throws ValidationError if format is invalid
+ */
+export declare function parsePipeDelimitedToken(token: string): TokenClassKey;
+/**
+ * REVERSE-PARSING ALGORITHM FOR DOLLAR-DELIMITED TOKENS
+ *
+ * Problem: Tokens like "$MUSIC$Unit$none$none" contain $ in the collection name
+ * Standard left-to-right parsing fails because it can't distinguish where collection ends
+ *
+ * Solution: Parse from RIGHT-TO-LEFT
+ *
+ * ```
+ * Input token: "$MUSIC$Unit$none$none"
+ *              [   1  ][2  ][3  ][4  ]   ← parts array (5 elements)
+ *
+ * Step 1: Split by '$'
+ *   parts = ['', 'MUSIC', 'Unit', 'none', 'none']
+ *
+ * Step 2: Take last 3 parts (from right)
+ *   category = parts[2] = 'Unit'
+ *   type     = parts[3] = 'none'
+ *   additionalKey = parts[4] = 'none'
+ *
+ * Step 3: Everything BEFORE those 3 parts = collection (rejoin with '$')
+ *   collectionParts = parts[0:2] = ['', 'MUSIC']
+ *   collection = '$MUSIC' (rejoin with '$')
+ *
+ * Result: { collection: "$MUSIC", category: "Unit", type: "none", additionalKey: "none" } ✓
+ * ```
+ *
+ * Why this works:
+ * - Handles ANY number of $ characters in collection
+ * - Guarantees exactly 4 components (collection, category, type, additionalKey)
+ * - Clear error messages when format is invalid
+ *
+ * Edge cases handled:
+ * - "$MUSIC$Unit$none$none" → collection: "$MUSIC" ✓
+ * - "COLLECTION$WITH$DOLLARS$Unit$symbol$additionalKey" → works ✓
+ * - "NotEnoughParts$Unit$none" → throws ValidationError ✓
+ *
+ * Performance: O(n) where n = token length (single split + slice + rejoin operations)
+ */
+/**
+ * Parse dollar-delimited token: "GALA$Unit$none$none"
+ *
+ * ⚠️ CRITICAL: Handles edge case where $ is part of collection name
+ * Example: "$MUSIC$Unit$none$none" → { collection: "$MUSIC", ... }
+ *
+ * Solution: Parse from END backwards
+ * - Last 3 parts (from right): category, type, additionalKey
+ * - Everything else: collection
+ *
+ * @internal Used by parseToken()
+ * @throws ValidationError if format is invalid
+ */
+export declare function parseDollarDelimitedTokenSafe(token: string): TokenClassKey;
+/**
+ * Check if token string is in pipe-delimited format
+ *
+ * @example
+ * ```typescript
+ * isPipeDelimited("GALA|Unit|none|none") // → true
+ * isPipeDelimited("GALA") // → false
+ * ```
+ */
+export declare function isPipeDelimited(token: string): boolean;
+/**
+ * Check if token string is in dollar-delimited format
+ *
+ * @example
+ * ```typescript
+ * isDollarDelimited("GALA$Unit$none$none") // → true
+ * isDollarDelimited("$MUSIC$Unit$none$none") // → true
+ * isDollarDelimited("GALA") // → false
+ * ```
+ */
+export declare function isDollarDelimited(token: string): boolean;
+/**
+ * Check if token is in ANY valid delimited format (pipe or dollar)
+ *
+ * @example
+ * ```typescript
+ * isDelimited("GALA|Unit|none|none") // → true
+ * isDelimited("GALA$Unit$none$none") // → true
+ * isDelimited("GALA") // → false
+ * ```
+ */
+export declare function isDelimited(token: string): boolean;
+/**
+ * Check if a value is a valid token format (string OR TokenClassKey object)
+ *
+ * @param token Token to validate
+ * @returns true if token is valid format (pipe/dollar delimited OR TokenClassKey object)
+ *
+ * @example
+ * ```typescript
+ * isValidTokenFormat("GALA|Unit|none|none")  // → true
+ * isValidTokenFormat("GALA$Unit$none$none")  // → true
+ * isValidTokenFormat({ collection: "GALA", ... })  // → true
+ * isValidTokenFormat("GALA")  // → false (plain string, not delimited)
+ * ```
+ */
+export declare function isValidTokenFormat(token: unknown): boolean;
+/**
+ * Check if token is a plain symbol string (NOT a delimited format)
+ *
+ * Plain token symbols are simple strings like "GALA", "USDC", etc.
+ * These are REJECTED by default by parseToken() for security reasons.
+ * Use parseToken(symbol, true) to parse plain symbols.
+ *
+ * @param token Token to check
+ * @returns true if token is plain symbol (no delimiters)
+ *
+ * @example
+ * ```typescript
+ * isPlainTokenSymbol("GALA")  // → true
+ * isPlainTokenSymbol("GALA|Unit|none|none")  // → false
+ * isPlainTokenSymbol("GALA$Unit$none$none")  // → false
+ * ```
+ *
+ * @security WARNING: Plain tokens are inherently ambiguous!
+ * Always use delimited formats when possible.
+ */
+export declare function isPlainTokenSymbol(token: unknown): boolean;
+/**
+ * Type guard: Check if value is a TokenClassKey object
+ *
+ * @param token Value to check
+ * @returns true if token is a valid TokenClassKey object with all required properties
+ *
+ * @example
+ * ```typescript
+ * const value: string | TokenClassKey = getToken();
+ *
+ * if (isTokenClassKey(value)) {
+ *   // TypeScript now knows value is TokenClassKey
+ *   console.log(value.collection, value.category, value.type, value.additionalKey);
+ * } else {
+ *   // value is string
+ *   console.log(parseToken(value));
+ * }
+ * ```
+ */
+export declare function isTokenClassKey(token: unknown): token is TokenClassKey;
+//# sourceMappingURL=token-parser.d.ts.map

package/dist/utils/token-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-parser.d.ts","sourceRoot":"","sources":["../../src/utils/token-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,IAAI,GAC/C,aAAa,CAyCf;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CA6CpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CA8C1E;AA2DD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAe1D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAgBtE"}

package/dist/utils/tokenNormalizer.d.ts

@@ -108,4 +108,70 @@ export declare function tokenClassKeyToString(tokenClass: TokenClassKey): string
  * @throws ValidationError if validation fails
  */
 export declare function validateTokenId(tokenId: TokenId): void;
+/**
+ * Parses a vault address into a TokenClassKey
+ *
+ * Vault address format: "service|Token$Unit$SYMBOL$additionalKey$launchpad"
+ * This consolidates 5+ identical vault address parsing patterns scattered across services.
+ *
+ * Handles additionalKey that may contain $ characters by excluding the 'launchpad' suffix
+ * and joining all remaining parts.
+ *
+ * @param vaultAddress Vault address string to parse
+ * @returns TokenClassKey object
+ * @throws ValidationError if the vault address format is invalid
+ *
+ * @example
+ * ```typescript
+ * const tokenClass = parseVaultAddressToTokenClassKey(
+ *   "service|Token$Unit$DRAGNRKTI$eth:0x...$launchpad"
+ * );
+ * // → { collection: "Token", category: "Unit", type: "DRAGNRKTI", additionalKey: "eth:0x..." }
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function parseVaultAddressToTokenClassKey(vaultAddress: string): TokenClassKey;
+/**
+ * Parses a vault address into a TokenInstanceKey
+ *
+ * Vault address format: "service|Token$Unit$SYMBOL$eth:address$launchpad"
+ * Instance is defaulted to "0" if not provided in the vault address.
+ *
+ * @param vaultAddress Vault address string to parse
+ * @returns TokenInstanceKey object with instance defaulted to "0"
+ * @throws ValidationError if the vault address format is invalid
+ *
+ * @example
+ * ```typescript
+ * const tokenInstance = parseVaultAddressToTokenInstance(
+ *   "service|Token$Unit$DRAGNRKTI$eth:0x...$launchpad"
+ * );
+ * // → { collection: "Token", category: "Unit", type: "DRAGNRKTI", additionalKey: "eth:0x...", instance: "0" }
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function parseVaultAddressToTokenInstance(vaultAddress: string): TokenInstanceKey;
+/**
+ * Extracts the token symbol/type from a vault address
+ *
+ * Vault address format: "service|Token$Unit$SYMBOL$eth:address$launchpad"
+ * The symbol is the 3rd component (index 2) after splitting the token part by $.
+ *
+ * @param vaultAddress Vault address string to parse
+ * @returns Token symbol/type (e.g., "DRAGNRKTI", "GALA", "GUSDC")
+ * @throws ValidationError if the vault address format is invalid
+ *
+ * @example
+ * ```typescript
+ * const symbol = extractTokenSymbolFromVault(
+ *   "service|Token$Unit$DRAGNRKTI$eth:0x...$launchpad"
+ * );
+ * // → "DRAGNRKTI"
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function extractTokenSymbolFromVault(vaultAddress: string): string;
 //# sourceMappingURL=tokenNormalizer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tokenNormalizer.d.ts","sourceRoot":"","sources":["../../src/utils/tokenNormalizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CA2D9E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,gBAAgB,CAKhF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,aAAa,CAI1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,MAAM,CAEnE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,gBAAgB,GAAG,MAAM,CAEhF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,aAAa,GAAG,MAAM,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CActD"}
+{"version":3,"file":"tokenNormalizer.d.ts","sourceRoot":"","sources":["../../src/utils/tokenNormalizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CA2D9E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,gBAAgB,CAKhF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,aAAa,CAI1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,MAAM,CAEnE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,gBAAgB,GAAG,MAAM,CAEhF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,aAAa,GAAG,MAAM,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CActD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gCAAgC,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAyCpF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gCAAgC,CAAC,YAAY,EAAE,MAAM,GAAG,gBAAgB,CAMvF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAGxE"}

package/dist/utils/transfer-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-validation.d.ts","sourceRoot":"","sources":["../../src/utils/transfer-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;;GAKG;AACH,qBAAa,wBAAwB;IACnC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAc3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAqB9D"}
+{"version":3,"file":"transfer-validation.d.ts","sourceRoot":"","sources":["../../src/utils/transfer-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;;GAKG;AACH,qBAAa,wBAAwB;IACnC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAc3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAqB9D"}

package/dist/utils/validation-helpers.d.ts

@@ -366,4 +366,79 @@ export type TypeGuard<T> = (value: unknown) => value is T;
  * ```
  */
 export declare function createValidator<T>(typeGuard: TypeGuard<T>, dataTypeName: string, fieldName?: string, errorCode?: string): (value: unknown) => asserts value is T;
+/**
+ * Result of mutual exclusivity validation
+ */
+export interface MutualExclusivityResult {
+    /** Which field was provided (if valid) */
+    chosen: string;
+    /** Whether fieldA was provided */
+    hasA: boolean;
+    /** Whether fieldB was provided */
+    hasB: boolean;
+}
+/**
+ * Validates that exactly one of two parameters is provided (mutual exclusivity)
+ *
+ * Consolidates 12+ instances of identical validation logic found across services:
+ * - PriceHistoryService: tokenName XOR tokenId (lines 451-470)
+ * - DexService: Similar patterns with token identification
+ * - Other services: Scattered mutual exclusivity validation
+ *
+ * ## Use Cases
+ *
+ * ### Validate Token Identification (Highest Priority)
+ * ```typescript
+ * // In service methods receiving either tokenName or tokenId (but not both)
+ * const { chosen, hasA } = validateMutualExclusive(
+ *   options,
+ *   'tokenName',
+ *   'tokenId',
+ *   { description: 'token identifier' }
+ * );
+ *
+ * if (hasA) {
+ *   // Use tokenName
+ *   const resolved = await this.tokenResolver.resolve(options.tokenName!);
+ * } else {
+ *   // Use tokenId
+ *   const formatted = this.converter.toTokenClassKey(options.tokenId!);
+ * }
+ * ```
+ *
+ * ### Generic Parameter Validation
+ * ```typescript
+ * // Validate address or transaction ID (mutually exclusive)
+ * const { chosen } = validateMutualExclusive(
+ *   params,
+ *   'walletAddress',
+ *   'transactionId',
+ *   { description: 'transaction reference' }
+ * );
+ * ```
+ *
+ * @param obj The object containing the fields to validate
+ * @param fieldA First field name (mutual exclusive with fieldB)
+ * @param fieldB Second field name (mutual exclusive with fieldA)
+ * @param options Validation options
+ * @returns Result object with chosen field and validation flags
+ *
+ * @throws {ConfigurationError} If neither field is provided or both are provided
+ *
+ * @example Token identifier validation
+ * ```typescript
+ * // PriceHistoryService.fetchAllPriceHistory() - replaces 20-line validation method
+ * const { hasA } = validateMutualExclusive(options, 'tokenName', 'tokenId', {
+ *   description: 'token identifier'
+ * });
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function validateMutualExclusive(obj: Record<string, any>, fieldA: string, fieldB: string, options?: {
+    /** Human-readable description for error messages (e.g., "token identifier") */
+    description?: string;
+    /** Whether empty strings should count as "not provided" (default: true) */
+    treatEmptyAsNull?: boolean;
+}): MutualExclusivityResult;
 //# sourceMappingURL=validation-helpers.d.ts.map

package/dist/utils/validation-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/validation-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,qBAAqB,GACjC,IAAI,CAoBN;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;IAC3B,wEAAwE;;IAExE,yEAAyE;;CAEjE,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAe,EAC1B,SAAS,GAAE,MAAuB,GACjC,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,KAAK,IAAI,CAAC,CAUxC"}
+{"version":3,"file":"validation-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/validation-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,qBAAqB,GACjC,IAAI,CAoBN;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;IAC3B,wEAAwE;;IAExE,yEAAyE;;CAEjE,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAe,EAC1B,SAAS,GAAE,MAAuB,GACjC,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,KAAK,IAAI,CAAC,CAUxC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACxB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACvB,GACL,uBAAuB,CA8BzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gala-chain/launchpad-sdk",
-  "version": "3.31.0",
+  "version": "4.0.0",
   "description": "TypeScript SDK for Gala Launchpad Backend API - 72 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, DEX pool discovery, WebSocket event watchers, and comprehensive user operations. Multi-format output (ESM, CJS, UMD).",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
@@ -38,19 +38,39 @@
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "test:ci": "jest --coverage --ci --watchAll=false",
-    "demo": "tsx examples/complete-sdk-demo.ts",
-    "demo:read-only": "tsx examples/read-only-operations.ts",
-    "demo:authenticated": "tsx examples/authenticated-operations.ts",
-    "demo:privatekey-override": "tsx examples/privatekey-override-pattern.ts",
-    "demo:trades": "tsx examples/demo-trades.ts",
-    "demo:liquidity": "tsx examples/demo-liquidity-positions.ts",
-    "demo:liquidity:detailed": "tsx examples/demo-liquidity-detailed.ts",
-    "demo:cache": "tsx examples/demo-cache.ts",
-    "demo:fetch-all-pools": "tsx examples/demo-fetch-all-pools.ts",
-    "demo:dex-trades": "tsx examples/demo-dex-trades.ts",
-    "demo:dex-pool-discovery": "tsx examples/demo-dex-pool-discovery.ts",
-    "demo:watch-pools": "tsx examples/demo-watch-pools.ts",
-    "demo:watch-tokens": "tsx examples/demo-watch-tokens.ts",
+    "test:integration": "jest --config jest.integration.config.js --forceExit",
+    "demo": "tsx examples/core/complete-sdk-demo.ts",
+    "demo:read-only": "tsx examples/core/read-only-operations.ts",
+    "demo:authenticated": "tsx examples/core/authenticated-operations.ts",
+    "demo:privatekey-override": "tsx examples/core/privatekey-override-pattern.ts",
+    "demo:trades": "tsx examples/bonding-curve/basic-trading.ts",
+    "demo:liquidity": "tsx examples/liquidity/positions-cli.ts",
+    "demo:liquidity:all": "tsx examples/liquidity/orchestrator.ts",
+    "demo:liquidity:detailed": "tsx examples/liquidity/detailed.ts",
+    "demo:liquidity:ticks": "tsx examples/liquidity/ticks.ts",
+    "demo:liquidity:portfolio": "tsx examples/liquidity/multi-position.ts",
+    "demo:liquidity:apr": "tsx examples/liquidity/apr-calculator.ts",
+    "demo:liquidity:errors": "tsx examples/liquidity/errors.ts",
+    "demo:liquidity:fetch-all": "tsx examples/liquidity/demo-fetch-all-positions.ts",
+    "demo:liquidity:positions-with-prices": "tsx examples/liquidity/demo-positions-with-chunked-pricing.ts",
+    "demo:cache": "tsx examples/utilities/demo-cache.ts",
+    "demo:dex": "tsx examples/dex/swap-workflow.ts",
+    "demo:dex:pools": "tsx examples/dex/pool-discovery.ts",
+    "demo:dex:pricing": "tsx examples/dex/pools-with-pricing.ts",
+    "demo:dex:quotes": "tsx examples/dex/quote-comparison.ts",
+    "demo:dex:roundtrip": "tsx examples/dex/demo-roundtrip-liquidity.ts",
+    "demo:watch": "tsx examples/monitoring/demo-watch-pools.ts",
+    "demo:watch:tokens": "tsx examples/monitoring/demo-watch-tokens.ts",
+    "demo:fees": "tsx examples/fees/demo-fee-generation-and-collection.ts",
+    "demo:fees:high-volume": "tsx examples/fees/demo-fees-high-volume.ts",
+    "demo:fees:test": "tsx examples/fees/complete-fee-test.ts",
+    "demo:fees:trade-collect": "tsx examples/fees/trade-and-collect-fees.ts",
+    "demo:liquidity:bundler-test": "tsx examples/liquidity/test-bundler-operations.ts",
+    "demo:liquidity:roundtrip-remove": "tsx examples/liquidity/demo-roundtrip-remove.ts",
+    "demo:liquidity:direct": "tsx examples/liquidity/demo-position-direct.ts",
+    "demo:token-supply": "tsx examples/utilities/demo-token-supply.ts",
+    "debug:websocket:stage": "ENVIRONMENT=stage tsx examples/debug/websocket-monitor.ts",
+    "debug:websocket:prod": "ENVIRONMENT=prod tsx examples/debug/websocket-monitor.ts",
     "lint": "eslint src tests scripts --ext .ts,.tsx --fix",
     "lint:check": "eslint src tests scripts --ext .ts,.tsx",
     "typecheck": "tsc --noEmit",
@@ -139,6 +159,7 @@
   "peerDependencies": {
     "@gala-chain/api": "^2.4.3",
     "@gala-chain/connect": "^2.4.3",
+    "@gala-chain/dex": "^1.0.26",
     "axios": "^1.12.2",
     "bignumber.js": "^9.1.2",
     "ethers": "^6.15.0",
@@ -154,7 +175,7 @@
   "dependencies": {
     "@gala-chain/api": "^2.4.3",
     "@gala-chain/connect": "^2.4.3",
-    "@gala-chain/gswap-sdk": "^0.0.9",
+    "@gala-chain/dex": "^1.0.26",
     "@types/uuid": "^10.0.0",
     "axios": "^1.12.2",
     "bignumber.js": "^9.1.2",

package/dist/utils/tokenFormatConverter.d.ts

@@ -1,53 +0,0 @@
-/**
- * Token Format Conversion Utilities
- *
- * Converts between pipe-delimited and dollar-delimited token ID formats.
- * Used for translating between SDK format (pipe) and DEX Backend API format (dollar).
- *
- * @internal
- */
-/**
- * Convert pipe-delimited token ID to dollar-delimited format for API
- *
- * @param pipeToken Pipe-delimited format: "Token|Unit|GUSDC|eth:0x..."
- * @returns Dollar-delimited format: "Token$Unit$GUSDC$eth:0x..."
- * @throws Error if token is null or empty
- *
- * @example
- * ```typescript
- * pipeFormatToDollarFormat("Token|Unit|GUSDC|eth:0x123")
- * // Returns: "Token$Unit$GUSDC$eth:0x123"
- * ```
- */
-export declare function pipeFormatToDollarFormat(pipeToken: string): string;
-/**
- * Convert dollar-delimited API response to pipe-delimited format
- *
- * @param dollarToken Dollar-delimited format: "Token$Unit$GUSDC$eth:0x..."
- * @returns Pipe-delimited format: "Token|Unit|GUSDC|eth:0x..."
- * @throws Error if token is null or empty
- *
- * @example
- * ```typescript
- * dollarFormatToPipeFormat("Token$Unit$GUSDC$eth:0x123")
- * // Returns: "Token|Unit|GUSDC|eth:0x123"
- * ```
- */
-export declare function dollarFormatToPipeFormat(dollarToken: string): string;
-/**
- * Convert sort order from SDK format (uppercase) to API format (lowercase)
- *
- * @param sortOrder SDK sort order: 'ASC' | 'DESC'
- * @returns API sort order: 'asc' | 'desc' | undefined
- *
- * @example
- * ```typescript
- * convertSortOrderToApi('ASC')
- * // Returns: 'asc'
- *
- * convertSortOrderToApi(undefined)
- * // Returns: undefined
- * ```
- */
-export declare function convertSortOrderToApi(sortOrder?: 'ASC' | 'DESC'): 'asc' | 'desc' | undefined;
-//# sourceMappingURL=tokenFormatConverter.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"tokenFormatConverter.d.ts","sourceRoot":"","sources":["../../src/utils/tokenFormatConverter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAMlE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAM5F"}