@gala-chain/launchpad-sdk 5.0.3 → 5.0.4-beta.0

package/dist/src/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;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;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAMjE"}
+{"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,OAAO,EACL,eAAe,IAAI,qBAAqB,EAGzC,MAAM,gBAAgB,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAmE9E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,gBAAgB,CAKhF;AAED;;;;;;;;GAQG;AACH,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,MAAM,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CActD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gCAAgC,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAGpF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gCAAgC,CAAC,YAAY,EAAE,MAAM,GAAG,gBAAgB,CAMvF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAMjE"}

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

@@ -34,7 +34,7 @@ export declare class TransferValidationHelper {
      * Validate unique key format and length
      *
      * Checks that uniqueKey (if provided) meets constraints:
-     * - Maximum length: TRANSFER_CONSTRAINTS.MAX_UNIQUE_KEY_LENGTH
+     * - Maximum length: UNIQUE_KEY_CONSTRAINT.MAX_LENGTH
      * - Format pattern: Must start with "galaswap-operation-" or "galaconnect-operation-"
      *
      * @param uniqueKey - Optional unique key to validate

package/dist/src/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;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"}
+{"version":3,"file":"transfer-validation.d.ts","sourceRoot":"","sources":["../../../src/utils/transfer-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;;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/src/utils/type-guard-factory.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Type Guard Factory
+ *
+ * Factory function for creating type guards that validate object shapes.
+ * Eliminates 50+ duplicate type guard implementations across DTOs by providing
+ * a declarative, configuration-based approach.
+ *
+ * ## Problem Solved
+ *
+ * Before this factory, every DTO file contained 5-15 nearly identical type guards:
+ *
+ * ```typescript
+ * // Repeated pattern in 50+ type guards
+ * export function isBuyTokensData(obj: unknown): obj is BuyTokensData {
+ *   if (!obj || typeof obj !== 'object') return false;
+ *   const o = obj as Record<string, unknown>;
+ *   return (
+ *     typeof o.tokenSymbol === 'string' &&
+ *     typeof o.nativeTokenQuantity === 'string' &&
+ *     typeof o.expectedToken === 'string' &&
+ *     (o.maxAcceptableReverseBondingCurveFee === undefined ||
+ *       typeof o.maxAcceptableReverseBondingCurveFee === 'string')
+ *   );
+ * }
+ * ```
+ *
+ * ## Solution
+ *
+ * ```typescript
+ * // Before: 10+ lines of boilerplate per type guard
+ * // After: 1-2 lines of declarative configuration
+ * const isBuyTokensData = createTypeGuard<BuyTokensData>({
+ *   tokenSymbol: 'string',
+ *   nativeTokenQuantity: 'string',
+ *   expectedToken: 'string',
+ *   maxAcceptableReverseBondingCurveFee: 'optional-string'
+ * });
+ * ```
+ *
+ * @category Utilities
+ * @since 3.33.0
+ */
+/**
+ * Type field specification - defines the expected type and optionality
+ * of a field in an object being validated.
+ *
+ * Examples:
+ * - 'string' - Required string field
+ * - 'number' - Required number field
+ * - 'boolean' - Required boolean field
+ * - 'object' - Required object field (nested object)
+ * - 'array' - Required array field
+ * - 'optional-string' - Optional string field (undefined allowed)
+ * - 'optional-number' - Optional number field (undefined allowed)
+ * - 'optional-boolean' - Optional boolean field (undefined allowed)
+ * - 'optional-object' - Optional object field (undefined allowed)
+ * - 'optional-array' - Optional array field (undefined allowed)
+ */
+export type FieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'optional-string' | 'optional-number' | 'optional-boolean' | 'optional-object' | 'optional-array';
+/**
+ * Field specification for type guard validation
+ *
+ * Maps field names to their expected types. Used to declare the shape
+ * of an object that the type guard will validate.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   id: 'string',
+ *   age: 'number',
+ *   active: 'boolean',
+ *   metadata: 'optional-object',
+ *   tags: 'optional-array'
+ * }
+ * ```
+ */
+export type FieldSpec = Record<string, FieldType>;
+/**
+ * Creates a type guard function from a field specification
+ *
+ * This factory generates reusable type guard functions that validate object shapes
+ * based on a declarative configuration. Eliminates the need for manual type guard
+ * implementations while maintaining full type safety.
+ *
+ * ## Key Features
+ *
+ * - **Declarative Configuration**: Define object shape once, type guard generated
+ * - **Optional Fields**: Handle optional/undefined fields with `optional-*` types
+ * - **Nested Objects**: Support for object and array fields
+ * - **Type Narrowing**: Generated guards properly narrow TypeScript types
+ * - **Reusable**: Create once, use in multiple validation contexts
+ *
+ * ## Usage Patterns
+ *
+ * ### Basic Usage (Simple Types)
+ * ```typescript
+ * interface CreateTradeData {
+ *   tradeType: string;
+ *   tokenAmount: string;
+ *   vaultAddress: string;
+ *   userAddress: string;
+ *   slippageTolerance?: string;
+ *   deadline?: number;
+ * }
+ *
+ * const isCreateTradeData = createTypeGuard<CreateTradeData>({
+ *   tradeType: 'string',
+ *   tokenAmount: 'string',
+ *   vaultAddress: 'string',
+ *   userAddress: 'string',
+ *   slippageTolerance: 'optional-string',
+ *   deadline: 'optional-number'
+ * });
+ *
+ * // Usage
+ * if (isCreateTradeData(data)) {
+ *   // data is typed as CreateTradeData
+ *   console.log(data.tradeType);
+ * }
+ * ```
+ *
+ * ### With Objects and Arrays
+ * ```typescript
+ * interface PoolData {
+ *   tokenName: string;
+ *   price: number;
+ *   metadata: {
+ *     tags: string[];
+ *   };
+ *   extra?: Record<string, unknown>;
+ * }
+ *
+ * const isPoolData = createTypeGuard<PoolData>({
+ *   tokenName: 'string',
+ *   price: 'number',
+ *   metadata: 'object',
+ *   extra: 'optional-object'
+ * });
+ * ```
+ *
+ * ### In Validation Workflows
+ * ```typescript
+ * import { createValidator } from './validation-helpers';
+ *
+ * const isCreateTradeData = createTypeGuard<CreateTradeData>({
+ *   tradeType: 'string',
+ *   tokenAmount: 'string',
+ *   vaultAddress: 'string',
+ *   userAddress: 'string'
+ * });
+ *
+ * // Create validator that throws on invalid data
+ * const validateCreateTradeData = createValidator(
+ *   isCreateTradeData,
+ *   'create trade data'
+ * );
+ *
+ * function createTrade(data: unknown) {
+ *   validateCreateTradeData(data); // Throws ValidationError if invalid
+ *   // data is now typed as CreateTradeData
+ *   return tradingService.create(data);
+ * }
+ * ```
+ *
+ * ## Migration from Manual Type Guards
+ *
+ * ### Before (Manual Implementation)
+ * ```typescript
+ * export function isBuyTokensData(obj: unknown): obj is BuyTokensData {
+ *   if (!obj || typeof obj !== 'object') return false;
+ *   const o = obj as Record<string, unknown>;
+ *   return (
+ *     typeof o.tokenSymbol === 'string' &&
+ *     typeof o.nativeTokenQuantity === 'string' &&
+ *     typeof o.expectedToken === 'string' &&
+ *     (o.maxAcceptableReverseBondingCurveFee === undefined ||
+ *       typeof o.maxAcceptableReverseBondingCurveFee === 'string')
+ *   );
+ * }
+ * ```
+ *
+ * ### After (Using Factory)
+ * ```typescript
+ * export const isBuyTokensData = createTypeGuard<BuyTokensData>({
+ *   tokenSymbol: 'string',
+ *   nativeTokenQuantity: 'string',
+ *   expectedToken: 'string',
+ *   maxAcceptableReverseBondingCurveFee: 'optional-string'
+ * });
+ * ```
+ *
+ * Benefits:
+ * - 50% less code (3 lines vs 10+ lines)
+ * - No manual type checking logic
+ * - Easier to maintain and update
+ * - Consistent pattern across all DTOs
+ * - Self-documenting (field spec shows exact contract)
+ *
+ * @template T - The interface type this guard validates
+ * @param fields - Field specification mapping field names to their expected types
+ * @returns A type guard function that checks if a value matches the field specification
+ *
+ * @throws Never - Type guards never throw, they return boolean
+ *
+ * @example Email configuration type guard
+ * ```typescript
+ * interface EmailConfig {
+ *   to: string;
+ *   subject: string;
+ *   body: string;
+ *   cc?: string;
+ *   bcc?: string;
+ *   attachments?: Array<unknown>;
+ * }
+ *
+ * const isEmailConfig = createTypeGuard<EmailConfig>({
+ *   to: 'string',
+ *   subject: 'string',
+ *   body: 'string',
+ *   cc: 'optional-string',
+ *   bcc: 'optional-string',
+ *   attachments: 'optional-array'
+ * });
+ *
+ * // Use in conditional
+ * if (isEmailConfig(config)) {
+ *   await sendEmail(config); // config is EmailConfig
+ * }
+ * ```
+ *
+ * @example Trade options type guard
+ * ```typescript
+ * interface TradeOptions {
+ *   tokenName: string;
+ *   amount: string;
+ *   slippage?: number;
+ *   deadline?: number;
+ * }
+ *
+ * const isTradeOptions = createTypeGuard<TradeOptions>({
+ *   tokenName: 'string',
+ *   amount: 'string',
+ *   slippage: 'optional-number',
+ *   deadline: 'optional-number'
+ * });
+ *
+ * // Use in validation function
+ * function executeTradeIfValid(options: unknown): void {
+ *   if (isTradeOptions(options)) {
+ *     executeTradeInternal(options);
+ *   } else {
+ *     throw new Error('Invalid trade options');
+ *   }
+ * }
+ * ```
+ *
+ * @since 3.33.0
+ */
+export declare function createTypeGuard<T>(fields: FieldSpec): (obj: unknown) => obj is T;
+//# sourceMappingURL=type-guard-factory.d.ts.map

package/dist/src/utils/type-guard-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guard-factory.d.ts","sourceRoot":"","sources":["../../../src/utils/type-guard-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,GACP,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,CAAC;AAErB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAuClD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoLG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,GAAG,IAAI,CAAC,CAqBhF"}

package/dist/src/utils/unique-key-generator.d.ts

@@ -0,0 +1,148 @@
+/**
+ * GalaChain Unique Operation Key Generator
+ *
+ * Generates unique identifiers for GalaChain bundle transactions and operations
+ * that require idempotency keys. Consolidated from 14+ duplicated patterns across
+ * transfer and lock/unlock operations.
+ *
+ * @category Utilities
+ * @since 6.14.0
+ */
+/**
+ * Generate a unique operation key for GalaChain bundle transactions.
+ *
+ * Creates a deterministic yet unique identifier combining:
+ * - Timestamp (millisecond precision)
+ * - Random suffix (base36 encoded for compact representation)
+ *
+ * Format: `galaconnect-operation-{timestamp}_{randomSuffix}`
+ *
+ * Used for idempotency across:
+ * - Token transfers (uniqueKey parameter)
+ * - Token locks/unlocks (uniqueKey parameter)
+ * - Token burns (uniqueKey parameter)
+ * - Any operation requiring request deduplication
+ *
+ * @returns Unique operation key in format `galaconnect-operation-{timestamp}_{randomSuffix}`
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { generateUniqueKey } from '@gala-chain/launchpad-sdk';
+ *
+ * const key = generateUniqueKey();
+ * console.log(key); // 'galaconnect-operation-1735857234567_abc123'
+ *
+ * // Use in transfer operation
+ * await sdk.transferGala({
+ *   recipientAddress: 'eth|0x...',
+ *   amount: '100',
+ *   uniqueKey: generateUniqueKey()
+ * });
+ * ```
+ *
+ * @example With explicit key
+ * ```typescript
+ * // For operations where you control the idempotency key
+ * const operationKey = `my-operation-${Date.now()}`;
+ * await sdk.transferToken({
+ *   to: 'eth|0x...',
+ *   tokenName: 'anime',
+ *   amount: '1000',
+ *   uniqueKey: operationKey
+ * });
+ * ```
+ *
+ * @see {@link https://docs.galachain.com/idempotency GalaChain Idempotency}
+ */
+export declare function generateUniqueKey(): string;
+/**
+ * Generate unique operation key with UUID, timestamp, and wallet address
+ *
+ * Creates a unique identifier for GalaSwap operations combining:
+ * - Prefix (customizable, defaults to 'galaswap-operation')
+ * - UUID v4 for global uniqueness
+ * - Timestamp (millisecond precision)
+ * - Wallet address for context
+ *
+ * Format: `{prefix}-${uuid}-${timestamp}-${walletAddress}`
+ *
+ * Used for idempotent GalaSwap operations including:
+ * - Liquidity additions (add/remove)
+ * - Swap executions
+ * - Fee collections
+ * - Bundle transactions
+ *
+ * @param walletAddress The wallet address associated with the operation (required)
+ * @param prefix Optional custom prefix (defaults to 'galaswap-operation')
+ * @returns Unique operation key combining UUID, timestamp, and wallet address
+ *
+ * @example Basic usage with default prefix
+ * ```typescript
+ * import { generateOperationKey } from '@gala-chain/launchpad-sdk';
+ *
+ * const operationKey = generateOperationKey('eth|0x1234567890abcdef...');
+ * console.log(operationKey);
+ * // 'galaswap-operation-550e8400-e29b-41d4-a716-446655440000-1735857234567-eth|0x1234...'
+ * ```
+ *
+ * @example With custom prefix
+ * ```typescript
+ * import { generateOperationKey } from '@gala-chain/launchpad-sdk';
+ *
+ * const operationKey = generateOperationKey(
+ *   'eth|0x1234567890abcdef...',
+ *   'custom-swap'
+ * );
+ * console.log(operationKey);
+ * // 'custom-swap-550e8400-e29b-41d4-a716-446655440000-1735857234567-eth|0x1234...'
+ * ```
+ *
+ * @example In GalaSwap operations
+ * ```typescript
+ * import { generateOperationKey } from '@gala-chain/launchpad-sdk';
+ *
+ * // Use in add liquidity operation
+ * const result = await sdk.addSwapLiquidityByPrice({
+ *   token0: 'GALA',
+ *   token1: 'GUSDC',
+ *   fee: 3000,
+ *   minPrice: '0.95',
+ *   maxPrice: '1.05',
+ *   amount0Desired: '100',
+ *   amount1Desired: '100',
+ *   uniqueKey: generateOperationKey(walletAddress)
+ * });
+ * ```
+ *
+ * @example Handling operation idempotency
+ * ```typescript
+ * import { generateOperationKey } from '@gala-chain/launchpad-sdk';
+ *
+ * // Store the key for retry scenarios
+ * const operationKey = generateOperationKey(userAddress);
+ * try {
+ *   await sdk.executeSwap({
+ *     fromToken: 'GALA',
+ *     toToken: 'GUSDC',
+ *     inputAmount: '100',
+ *     expectedOutput: '95',
+ *     feeTier: 3000,
+ *     uniqueKey: operationKey
+ *   });
+ * } catch (error) {
+ *   // Retry with same key - ensures idempotency
+ *   await sdk.executeSwap({
+ *     fromToken: 'GALA',
+ *     toToken: 'GUSDC',
+ *     inputAmount: '100',
+ *     expectedOutput: '95',
+ *     feeTier: 3000,
+ *     uniqueKey: operationKey // Same key prevents duplicate execution
+ *   });
+ * }
+ * ```
+ *
+ * @since 3.50.0
+ */
+export declare function generateOperationKey(walletAddress: string, prefix?: string): string;
+//# sourceMappingURL=unique-key-generator.d.ts.map

package/dist/src/utils/unique-key-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unique-key-generator.d.ts","sourceRoot":"","sources":["../../../src/utils/unique-key-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAI1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EACrB,MAAM,GAAE,MAA6B,GACpC,MAAM,CAIR"}