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

package/dist/src/bridge/utils/balanceHelpers.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Balance Query Helpers
+ *
+ * Consolidated utilities for building ExternalChainBalance and BridgeTransaction response objects.
+ * Eliminates DRY violations across BridgeService and bridge strategy methods.
+ *
+ * @module bridge/utils/balanceHelpers
+ */
+import type { ExternalChainBalance, BridgeTransaction, ExternalNetwork, BridgeRequestDto, DestinationChainTxFee } from '../types/index.js';
+import type { EthereumTokenConfig, SolanaTokenConfig } from '../types/index.js';
+/**
+ * Build an ExternalChainBalance for a native token (ETH or SOL).
+ *
+ * @param symbol - Native token symbol ('ETH' or 'SOL')
+ * @param quantity - Balance as decimal string
+ * @param decimals - Token decimals (18 for ETH, 9 for SOL)
+ * @returns ExternalChainBalance with isNative: true, contractAddress: null
+ *
+ * @example
+ * ```typescript
+ * const ethBalance = buildNativeBalance('ETH', '1.5', 18);
+ * // { symbol: 'ETH', quantity: '1.5', decimals: 18, contractAddress: null, isNative: true }
+ * ```
+ */
+export declare function buildNativeBalance(symbol: 'ETH' | 'SOL', quantity: string, decimals: number): ExternalChainBalance;
+/**
+ * Build an ExternalChainBalance for an Ethereum ERC-20 token.
+ *
+ * @param tokenConfig - Ethereum token configuration
+ * @param quantity - Balance as decimal string
+ * @returns ExternalChainBalance with contractAddress and isNative: false
+ *
+ * @example
+ * ```typescript
+ * const galaBalance = buildEthereumTokenBalance(
+ *   { symbol: 'GALA', contractAddress: '0x15D4...', decimals: 8 },
+ *   '1000.00000000'
+ * );
+ * ```
+ */
+export declare function buildEthereumTokenBalance(tokenConfig: EthereumTokenConfig, quantity: string): ExternalChainBalance;
+/**
+ * Build an ExternalChainBalance for a Solana SPL token.
+ *
+ * @param tokenConfig - Solana token configuration
+ * @param quantity - Balance as decimal string
+ * @returns ExternalChainBalance with mintAddress as contractAddress
+ *
+ * @example
+ * ```typescript
+ * const galaBalance = buildSolanaTokenBalance(
+ *   { symbol: 'GALA', mintAddress: 'GALAxw...', decimals: 8 },
+ *   '500.00000000'
+ * );
+ * ```
+ */
+export declare function buildSolanaTokenBalance(tokenConfig: SolanaTokenConfig, quantity: string): ExternalChainBalance;
+/**
+ * Find and validate a token config from an array.
+ *
+ * @param tokens - Array of token configurations
+ * @param symbol - Token symbol to find
+ * @param network - Network name for error message ('Ethereum' or 'Solana')
+ * @returns Token config or throws if not found
+ *
+ * @example
+ * ```typescript
+ * const config = findTokenConfigOrThrow(ethereumTokens, 'GALA', 'Ethereum');
+ * ```
+ */
+export declare function findTokenConfigOrThrow<T extends {
+    symbol: string;
+}>(tokens: T[], symbol: string, network: string): T;
+/**
+ * Error messages for strategy not configured.
+ */
+export declare const STRATEGY_NOT_CONFIGURED_ERRORS: {
+    readonly Ethereum: "Ethereum bridging not configured. Provide ethereumPrivateKey in config.";
+    readonly Solana: "Solana bridging not configured. Provide solanaPrivateKey in config.";
+};
+/**
+ * Assert that a strategy exists and return it typed.
+ *
+ * @param strategy - Strategy from map (may be undefined)
+ * @param network - Network type ('Ethereum' or 'Solana')
+ * @param customError - Optional custom error message (overrides default)
+ * @returns The strategy (type-narrowed to non-undefined)
+ * @throws Error if strategy is undefined
+ *
+ * @example
+ * ```typescript
+ * const strategy = this.strategies.get('Ethereum');
+ * const ethStrategy = assertStrategyExists(strategy, 'Ethereum') as EthereumBridgeStrategy;
+ *
+ * // With custom error message:
+ * const ethStrategy = assertStrategyExists(strategy, 'Ethereum',
+ *   'Ethereum bridge strategy not configured. Initialize SDK with ethereumPrivateKey.'
+ * ) as EthereumBridgeStrategy;
+ * ```
+ */
+export declare function assertStrategyExists<T>(strategy: T | undefined, network: 'Ethereum' | 'Solana', customError?: string): T;
+/**
+ * Parameters for building a bridge outbound transaction response.
+ */
+export interface BridgeOutboundTransactionParams {
+    /** Destination chain ('Ethereum' | 'Solana') */
+    toChain: ExternalNetwork;
+    /** Transaction hash */
+    transactionHash: string;
+    /** Token symbol (e.g., 'GALA', 'GWETH') */
+    tokenSymbol: string;
+    /** Amount transferred (decimal string) */
+    amount: string;
+    /** Fee paid in GALA */
+    feePaid: string;
+    /** Base URL for status endpoint */
+    baseUrl: string;
+}
+/**
+ * Build a BridgeTransaction response for outbound transfers (GalaChain -> External).
+ *
+ * Eliminates duplicate response construction in EthereumBridgeStrategy and SolanaBridgeStrategy.
+ *
+ * @param params - Transaction parameters
+ * @returns Complete BridgeTransaction object
+ *
+ * @example
+ * ```typescript
+ * return buildBridgeOutboundTransaction({
+ *   toChain: 'Ethereum',
+ *   transactionHash: '0x123...',
+ *   tokenSymbol: 'GALA',
+ *   amount: '100',
+ *   feePaid: '0.5',
+ *   baseUrl: 'https://api.gala.com',
+ * });
+ * ```
+ */
+export declare function buildBridgeOutboundTransaction(params: BridgeOutboundTransactionParams): BridgeTransaction;
+/**
+ * Parameters for building a bridge inbound transaction response.
+ */
+export interface BridgeInboundTransactionParams {
+    /** Source chain ('Ethereum' | 'Solana') */
+    fromChain: ExternalNetwork;
+    /** Transaction hash */
+    transactionHash: string;
+    /** Token symbol (e.g., 'GALA', 'GWETH') */
+    tokenSymbol: string;
+    /** Amount transferred (decimal string) */
+    amount: string;
+    /** Base URL for status endpoint */
+    baseUrl: string;
+}
+/**
+ * Build a BridgeTransaction response for inbound transfers (External -> GalaChain).
+ *
+ * Eliminates duplicate response construction in EthereumBridgeStrategy and SolanaBridgeStrategy.
+ *
+ * @param params - Transaction parameters
+ * @returns Complete BridgeTransaction object
+ *
+ * @example
+ * ```typescript
+ * return buildBridgeInboundTransaction({
+ *   fromChain: 'Ethereum',
+ *   transactionHash: '0x123...',
+ *   tokenSymbol: 'GALA',
+ *   amount: '100',
+ *   baseUrl: 'https://api.gala.com',
+ * });
+ * ```
+ */
+export declare function buildBridgeInboundTransaction(params: BridgeInboundTransactionParams): BridgeTransaction;
+/**
+ * Parameters for building a bridge request DTO.
+ */
+export interface BridgeRequestDtoParams {
+    /** Destination chain ID (number) */
+    destinationChainId: number;
+    /** Bridge fee response from GalaConnect (used as destinationChainTxFee) */
+    bridgeFee: DestinationChainTxFee;
+    /** Amount to bridge (decimal string) */
+    amount: string;
+    /** Recipient address on destination chain */
+    recipientAddress: string;
+    /** Token metadata descriptor */
+    tokenDescriptor: {
+        collection: string;
+        category: string;
+        type: string;
+        additionalKey: string;
+    };
+}
+/**
+ * Build a BridgeRequestDto for the GalaConnect RequestTokenBridgeOut API.
+ *
+ * Eliminates duplicate DTO construction across strategies (~10 lines each).
+ *
+ * @param params - Request parameters
+ * @returns BridgeRequestDto ready for signing
+ *
+ * @example
+ * ```typescript
+ * const dto = buildBridgeRequestDto({
+ *   destinationChainId: CHAIN_IDS.ETHEREUM,
+ *   bridgeFee,
+ *   amount: '100',
+ *   recipientAddress: '0x1234...',
+ *   tokenDescriptor: metadata.descriptor,
+ * });
+ * ```
+ */
+export declare function buildBridgeRequestDto(params: BridgeRequestDtoParams): BridgeRequestDto;
+//# sourceMappingURL=balanceHelpers.d.ts.map

package/dist/src/bridge/utils/balanceHelpers.d.ts.map

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

package/dist/src/bridge/utils/bridgeErrors.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Bridge Error Messages and Validation Helpers
+ *
+ * Centralized error message factories and validation helpers for bridge strategies.
+ * Eliminates DRY violations by providing consistent, reusable error patterns.
+ */
+import { PublicKey } from '@solana/web3.js';
+/**
+ * Bridge error message templates.
+ * Centralized to ensure consistency across strategies.
+ */
+export declare const BRIDGE_ERROR_MESSAGES: {
+    /** Token symbol resolution internal error */
+    readonly TOKEN_SYMBOL_RESOLUTION_FAILED: string;
+    /** Bridge request ID missing from API response */
+    readonly BRIDGE_REQUEST_ID_MISSING: "Bridge request ID missing from RequestTokenBridgeOut response";
+    /** Transaction hash missing from BridgeTokenOut response */
+    readonly BRIDGE_OUT_HASH_MISSING: "BridgeTokenOut response missing transaction hash";
+};
+/**
+ * Validate that a token symbol was resolved by BridgeService.
+ *
+ * This is an internal assertion - strategies expect BridgeService to resolve
+ * tokenId to symbol before calling them.
+ *
+ * @param symbol - The resolved token symbol (may be undefined)
+ * @throws Error if symbol is undefined or empty
+ * @returns The validated symbol (type-narrowed to string)
+ *
+ * @example
+ * ```typescript
+ * const symbol = assertTokenSymbolResolved(params.tokenSymbol);
+ * // symbol is now guaranteed to be a non-empty string
+ * ```
+ */
+export declare function assertTokenSymbolResolved(symbol: string | undefined): string;
+/**
+ * Assert that a bridge request ID was returned from RequestTokenBridgeOut.
+ *
+ * @param bridgeRequestId - The extracted bridge request ID (may be undefined)
+ * @throws Error if bridgeRequestId is undefined or empty
+ * @returns The validated bridge request ID
+ */
+export declare function assertBridgeRequestId(bridgeRequestId: string | undefined): string;
+/**
+ * Extract and validate the transaction hash from a BridgeTokenOut response.
+ *
+ * Handles multiple response formats (Hash vs hash).
+ *
+ * @param response - The BridgeTokenOut API response
+ * @throws Error if transaction hash is missing
+ * @returns The validated transaction hash
+ */
+export declare function extractBridgeOutTransactionHash(response: {
+    Hash?: string;
+    hash?: string;
+}): string;
+/**
+ * Validate an Ethereum address and throw a descriptive error if invalid.
+ *
+ * @param address - The address to validate
+ * @param context - Optional context for the error message (e.g., "recipient", "target")
+ * @throws Error if address is not a valid Ethereum address
+ *
+ * @example
+ * ```typescript
+ * validateEthereumAddressOrThrow(recipientAddress, 'recipient');
+ * // Throws: "Invalid Ethereum recipient address: "abc". Expected valid 0x-prefixed address."
+ * ```
+ */
+export declare function validateEthereumAddressOrThrow(address: string, context?: string): void;
+/**
+ * Validate a Solana address and throw a descriptive error if invalid.
+ *
+ * @param address - The address to validate
+ * @param context - Optional context for the error message (e.g., "recipient", "target")
+ * @throws Error if address is not a valid Solana address
+ * @returns The validated PublicKey object
+ *
+ * @example
+ * ```typescript
+ * const pubkey = validateSolanaAddressOrThrow(recipientAddress, 'recipient');
+ * // Throws: "Invalid Solana recipient address: "abc". <error details>"
+ * ```
+ */
+export declare function validateSolanaAddressOrThrow(address: string, context?: string): PublicKey;
+/**
+ * Parse a Solana address to PublicKey, throwing a simple error on failure.
+ *
+ * Use this for cases where the detailed error message is not needed
+ * (e.g., balance lookups where the address format is already known).
+ *
+ * @param address - The address to parse
+ * @throws Error with simple "Invalid Solana address" message
+ * @returns The parsed PublicKey
+ */
+export declare function parseSolanaAddressOrThrow(address: string): PublicKey;
+//# sourceMappingURL=bridgeErrors.d.ts.map

package/dist/src/bridge/utils/bridgeErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeErrors.d.ts","sourceRoot":"","sources":["../../../../src/bridge/utils/bridgeErrors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAW5C;;;GAGG;AACH,eAAO,MAAM,qBAAqB;IAChC,6CAA6C;;IAK7C,kDAAkD;;IAIlD,4DAA4D;;CAEpD,CAAC;AAMX;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQ5E;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,MAAM,CASR;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,IAAI,CASN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAWX;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAUpE"}

package/dist/src/bridge/utils/bridgeOutHelpers.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Bridge Out Flow Helpers
+ *
+ * Shared utilities for executing bridge out operations across strategies.
+ * Consolidates the common bridgeOut() flow to eliminate DRY violations
+ * between EthereumBridgeStrategy and SolanaBridgeStrategy.
+ *
+ * @module bridge/utils/bridgeOutHelpers
+ */
+import type { Wallet as EthersWallet } from 'ethers';
+import type { BridgeTransaction, BridgeOutParams, ExternalNetwork } from '../types/index.js';
+import type { GalaConnectClient } from '../GalaConnectClient.js';
+import type { TokenMetadataResolver } from './tokenMetadataResolver.js';
+/**
+ * Configuration for executing a bridge out flow.
+ */
+export interface BridgeOutFlowConfig {
+    /** GalaConnect API client */
+    galaConnectClient: GalaConnectClient;
+    /** Token metadata resolver */
+    tokenMetadataResolver: TokenMetadataResolver;
+    /** Ethereum wallet for EIP-712 signing */
+    ethereumWallet: EthersWallet;
+    /** Destination chain ID (from CHAIN_IDS constant) */
+    destinationChainId: number;
+    /** Destination chain name */
+    destinationChain: ExternalNetwork;
+    /** Address validation function (chain-specific) */
+    validateRecipientAddress: (address: string, label: string) => void;
+}
+/**
+ * Execute a complete bridge out flow (GalaChain -> External Chain).
+ *
+ * This helper consolidates the common bridge out logic shared between
+ * EthereumBridgeStrategy and SolanaBridgeStrategy, eliminating ~35 lines
+ * of duplicate code per strategy.
+ *
+ * The flow is:
+ * 1. Validate token symbol was resolved
+ * 2. Validate amount is positive
+ * 3. Validate recipient address (using chain-specific validation)
+ * 4. Fetch token metadata
+ * 5. Fetch bridge fee
+ * 6. Build and sign bridge request DTO
+ * 7. Submit RequestTokenBridgeOut
+ * 8. Extract bridge request ID
+ * 9. Submit BridgeTokenOut
+ * 10. Build transaction response
+ *
+ * @param params - Bridge out parameters from caller
+ * @param config - Strategy-specific configuration
+ * @returns BridgeTransaction with status URL
+ *
+ * @example
+ * ```typescript
+ * // In EthereumBridgeStrategy.bridgeOut():
+ * return executeBridgeOutFlow(params, {
+ *   galaConnectClient: this.galaConnectClient,
+ *   tokenMetadataResolver: this.tokenMetadataResolver,
+ *   ethereumWallet: this.ethereumWallet,
+ *   destinationChainId: CHAIN_IDS.ETHEREUM,
+ *   destinationChain: 'Ethereum',
+ *   validateRecipientAddress: validateEthereumAddressOrThrow,
+ * });
+ * ```
+ */
+export declare function executeBridgeOutFlow(params: BridgeOutParams, config: BridgeOutFlowConfig): Promise<BridgeTransaction>;
+//# sourceMappingURL=bridgeOutHelpers.d.ts.map

package/dist/src/bridge/utils/bridgeOutHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeOutHelpers.d.ts","sourceRoot":"","sources":["../../../../src/bridge/utils/bridgeOutHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,QAAQ,CAAC;AACrD,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAaxE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,8BAA8B;IAC9B,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,0CAA0C;IAC1C,cAAc,EAAE,YAAY,CAAC;IAC7B,qDAAqD;IACrD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,6BAA6B;IAC7B,gBAAgB,EAAE,eAAe,CAAC;IAClC,mDAAmD;IACnD,wBAAwB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAqE5B"}

package/dist/src/bridge/utils/bridgePayload.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Bridge Payload Utilities
+ *
+ * Shared utility functions for bridge payload construction and normalization.
+ * These functions are used by both EthereumBridgeStrategy and SolanaBridgeStrategy
+ * to ensure consistent, deterministic payload generation for EIP-712 signing.
+ */
+import type { DestinationChainTxFee, BridgeTokenMetadata } from '../types/index.js';
+import type { TokenClassKey } from '../../types/common.js';
+/**
+ * Normalize a DestinationChainTxFee response for deterministic signing.
+ *
+ * Converts string timestamps and decimals to numbers to ensure consistent
+ * JSON serialization across different API response formats.
+ *
+ * @param raw - Raw fee response from GalaConnect API
+ * @returns Normalized fee object with numeric timestamps
+ */
+export declare function normalizeDestinationChainTxFee(raw: DestinationChainTxFee): DestinationChainTxFee;
+/**
+ * Remove undefined values from an object for deterministic JSON serialization.
+ *
+ * Creates a clean object without undefined properties, which ensures
+ * consistent JSON.stringify output for signature verification.
+ *
+ * @param obj - Object potentially containing undefined values
+ * @returns Clean object with undefined values removed
+ */
+export declare function sanitizeObject<T extends Record<string, unknown>>(obj: T): T;
+/**
+ * Extract the bridge request ID from a RequestTokenBridgeOut response.
+ *
+ * Handles multiple response formats from the GalaConnect API:
+ * - `{ Data: "..." }` - Direct data field
+ * - `{ data: "..." }` - Lowercase data field
+ * - `{ data: { Data: "..." } }` - Nested data object
+ *
+ * @param response - Response from RequestTokenBridgeOut API call
+ * @returns Bridge request ID if found, undefined otherwise
+ */
+export declare function extractBridgeRequestId(response: Record<string, unknown>): string | undefined;
+/**
+ * Validate a bridge amount for numeric validity and positivity.
+ *
+ * Prevents wasted gas on zero/negative/invalid amounts.
+ *
+ * @param amount - Amount string to validate
+ * @param tokenSymbol - Token symbol for error message context
+ * @throws Error if amount is invalid, zero, or negative
+ * @returns Parsed numeric amount (as side effect of successful validation)
+ *
+ * @example
+ * ```typescript
+ * validateBridgeAmount('100.5', 'GALA'); // Returns: 100.5
+ * validateBridgeAmount('0', 'GALA');     // Throws error
+ * validateBridgeAmount('abc', 'GALA');   // Throws error
+ * ```
+ */
+export declare function validateBridgeAmount(amount: string, tokenSymbol: string): number;
+/**
+ * Build a BridgeTokenMetadata object from token descriptor and decimals.
+ *
+ * Consolidates the pattern of building bridge token metadata from API responses.
+ *
+ * @param tokenDescriptor - Token descriptor with collection, category, type, additionalKey
+ * @param decimals - Token decimals
+ * @param channel - Optional channel identifier for multi-channel tokens
+ * @returns BridgeTokenMetadata object
+ *
+ * @example
+ * ```typescript
+ * const metadata = buildTokenMetadata(
+ *   { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' },
+ *   8
+ * );
+ * ```
+ */
+export declare function buildTokenMetadata(tokenDescriptor: TokenClassKey, decimals: number, channel?: string): BridgeTokenMetadata;
+/**
+ * Build a fee payload object from a DestinationChainTxFee response.
+ *
+ * Consolidates the pattern of extracting fee information from API responses.
+ * Normalizes timestamp to ensure it is always a number.
+ *
+ * @param feeResponse - Raw fee response from GalaConnect API
+ * @returns Fee payload with all relevant fields
+ *
+ * @example
+ * ```typescript
+ * const feePayload = buildFeePayload({
+ *   estimatedTotalTxFeeInGala: '100',
+ *   estimatedTotalTxFeeInExternalToken: '0.005',
+ *   ...
+ * });
+ * ```
+ */
+export declare function buildFeePayload(feeResponse: DestinationChainTxFee): {
+    estimatedFeeInGala: string;
+    estimatedFeeInExternalToken: string;
+    feeToken: import("../types/bridge.dto.js").BridgeTokenDescriptor;
+    pricePerUnit: string;
+    estimatedGasUnits: string;
+    exchangeRate: string;
+    timestamp: number;
+    raw: DestinationChainTxFee;
+};
+//# sourceMappingURL=bridgePayload.d.ts.map

package/dist/src/bridge/utils/bridgePayload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgePayload.d.ts","sourceRoot":"","sources":["../../../../src/bridge/utils/bridgePayload.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,qBAAqB,GACzB,qBAAqB,CAuDvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAY3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,GAAG,SAAS,CAgBpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,MAAM,CAQR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,aAAa,EAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,mBAAmB,CAYrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,qBAAqB;;;;;;;;SAa/B,qBAAqB;EAEvD"}

package/dist/src/bridge/utils/bridgeStatusParser.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Bridge Status Parser
+ *
+ * Shared utility for parsing bridge status responses.
+ * Consolidates duplicate status parsing logic from both bridge strategies.
+ *
+ * @module bridge/utils/bridgeStatusParser
+ */
+import type { BridgeStatus, BridgeStatusCode, BridgeStatusResponse } from '../types/index.js';
+/**
+ * Terminal status codes that indicate a bridge operation is complete.
+ */
+export declare const TERMINAL_STATUS_CODES: {
+    readonly COMPLETED: 5;
+    readonly FAILED: 6;
+    readonly DELIVERY_FAILED: 7;
+};
+/**
+ * Parse a bridge status response into a BridgeStatus object.
+ *
+ * This consolidates the duplicate `getStatus()` result parsing from
+ * EthereumBridgeStrategy and SolanaBridgeStrategy.
+ *
+ * Safely parses the numeric status code using {@link safeParseInt} to handle
+ * edge cases where the API returns unexpected values (strings, null, undefined).
+ *
+ * @param response - Raw response from GalaConnect getBridgeStatus API
+ * @returns Parsed BridgeStatus object with normalized fields
+ *
+ * @example
+ * ```typescript
+ * const response = await galaConnectClient.getBridgeStatus(hash);
+ * const status = parseBridgeStatusResponse(response);
+ * if (status.isComplete) {
+ *   console.log('Bridge completed successfully!');
+ * }
+ * ```
+ */
+export declare function parseBridgeStatusResponse(response: BridgeStatusResponse): BridgeStatus;
+/**
+ * Check if a bridge status indicates completion (success or failure).
+ *
+ * @param statusCode - Bridge status code to check
+ * @returns True if status is terminal (completed, failed, or delivery_failed)
+ */
+export declare function isTerminalStatus(statusCode: BridgeStatusCode): boolean;
+/**
+ * Check if a bridge status indicates success.
+ *
+ * @param statusCode - Bridge status code to check
+ * @returns True if status is COMPLETED
+ */
+export declare function isSuccessStatus(statusCode: BridgeStatusCode): boolean;
+/**
+ * Check if a bridge status indicates failure.
+ *
+ * @param statusCode - Bridge status code to check
+ * @returns True if status is FAILED or DELIVERY_FAILED
+ */
+export declare function isFailureStatus(statusCode: BridgeStatusCode): boolean;
+/**
+ * Bridge status code descriptions for logging and display.
+ */
+export declare const STATUS_DESCRIPTIONS: Record<number, string>;
+/**
+ * Get a human-readable description for a status code.
+ *
+ * Validates that the status code is a valid number before lookup.
+ * Returns a descriptive string or "UNKNOWN(code)" for unrecognized codes.
+ *
+ * @param statusCode - Bridge status code
+ * @returns Human-readable status description
+ */
+export declare function getStatusDescription(statusCode: BridgeStatusCode): string;
+//# sourceMappingURL=bridgeStatusParser.d.ts.map

package/dist/src/bridge/utils/bridgeStatusParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeStatusParser.d.ts","sourceRoot":"","sources":["../../../../src/bridge/utils/bridgeStatusParser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAI9F;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;CAIxB,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,YAAY,CAkBtF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAMtE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAKrE;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAS7C,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,CAOzE"}

package/dist/src/bridge/utils/eip712Helpers.d.ts

@@ -0,0 +1,66 @@
+/**
+ * EIP-712 Signing Helpers
+ *
+ * Shared utilities for EIP-712 payload construction and signing.
+ * Used by both EthereumBridgeStrategy and SolanaBridgeStrategy for
+ * building signed bridge out payloads.
+ *
+ * @module bridge/utils/eip712Helpers
+ */
+import type { Wallet as EthersWallet } from 'ethers';
+import type { BridgeRequestDto } from '../types/index.js';
+/**
+ * Configuration for building bridge out payloads
+ */
+export interface BuildBridgeOutPayloadConfig {
+    /** Ethereum wallet for EIP-712 signing */
+    wallet: EthersWallet;
+}
+/**
+ * Build an EIP-712 signed bridge out payload.
+ *
+ * This consolidates the duplicate `buildBridgeOutPayload()` implementations
+ * from EthereumBridgeStrategy and SolanaBridgeStrategy.
+ *
+ * The payload is signed using EIP-712 typed data signing and includes:
+ * - The message to be signed
+ * - The EIP-712 signature
+ * - The typed data types and domain for verification
+ *
+ * @param dto - Bridge request DTO with transfer details
+ * @param config - Configuration including wallet for signing
+ * @returns Promise resolving to signed payload ready for API submission
+ *
+ * @example
+ * ```typescript
+ * const payload = await buildBridgeOutPayload(
+ *   {
+ *     destinationChainId: CHAIN_IDS.ETHEREUM,
+ *     destinationChainTxFee: bridgeFee,
+ *     quantity: '100',
+ *     recipient: '0x1234...',
+ *     tokenInstance: { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none', instance: '0' },
+ *   },
+ *   { wallet: ethereumWallet }
+ * );
+ * ```
+ */
+export declare function buildBridgeOutPayload(dto: BridgeRequestDto, config: BuildBridgeOutPayloadConfig): Promise<Record<string, unknown>>;
+/**
+ * Create a signed message prefix for a deterministic payload.
+ *
+ * Used for Ethereum signed message format: "\x19Ethereum Signed Message:\n{length}"
+ *
+ * @param payloadLength - Length of the payload string
+ * @returns Formatted prefix string
+ */
+export declare function createSignedMessagePrefix(payloadLength: number): string;
+/**
+ * Generate a unique key for bridge operations.
+ *
+ * Uses crypto.randomUUID() with a galaconnect prefix.
+ *
+ * @returns Unique key string
+ */
+export declare function generateBridgeUniqueKey(): string;
+//# sourceMappingURL=eip712Helpers.d.ts.map

package/dist/src/bridge/utils/eip712Helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eip712Helpers.d.ts","sourceRoot":"","sources":["../../../../src/bridge/utils/eip712Helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,QAAQ,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAQ1D;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,0CAA0C;IAC1C,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA2DlC;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD"}

package/dist/src/bridge/utils/index.d.ts

@@ -7,4 +7,13 @@ export * from './RateLimiter.js';
 export * from './tokenMath.js';
 export * from './retry.js';
 export * from './tokenIdUtils.js';
+export * from './bridgePayload.js';
+export * from './addressValidation.js';
+export * from './tokenMetadataResolver.js';
+export * from './eip712Helpers.js';
+export * from './bridgeStatusParser.js';
+export * from './bridgeErrors.js';
+export * from './balanceHelpers.js';
+export * from './strategyDelegation.js';
+export * from './bridgeOutHelpers.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/bridge/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bridge/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bridge/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}