@gala-chain/launchpad-sdk 8.1.0 → 9.0.0-rc.0

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

@@ -1,772 +0,0 @@
-/**
- * Bridge DTOs and Interfaces
- *
- * Type definitions for cross-chain bridging operations between
- * GalaChain, Ethereum, and Solana.
- */
-import type { TokenId } from '../../types/common.js';
-/**
- * Supported external networks for bridging
- */
-export type ExternalNetwork = 'Ethereum' | 'Solana';
-/**
- * Token descriptor for GalaChain tokens
- */
-export interface BridgeTokenDescriptor {
-    collection: string;
-    category: string;
-    type: string;
-    additionalKey: string;
-}
-/**
- * Token descriptor with instance (for specific token instances)
- */
-export interface BridgeTokenInstance extends BridgeTokenDescriptor {
-    instance: string;
-}
-/**
- * Ethereum token configuration
- */
-export interface EthereumTokenConfig {
-    symbol: string;
-    amount: string;
-    contractAddress: string;
-    bridgeUsesPermit?: boolean;
-    decimals?: number;
-}
-/**
- * Solana token configuration
- */
-export interface SolanaTokenConfig {
-    symbol: string;
-    amount: string;
-    mintAddress: string;
-    isNative?: boolean;
-    decimals?: number;
-}
-/**
- * Bridge token configuration from GalaConnect API
- */
-export interface BridgeConfigurationToken extends BridgeTokenDescriptor {
-    symbol: string;
-    decimals: number;
-    verified?: boolean;
-    channel?: string;
-    canBridgeTo?: Array<{
-        network: string;
-        symbol: string;
-        destinationChainIds: string[];
-    }>;
-    otherNetworks?: Array<{
-        network: string;
-        symbol: string;
-        contractAddress: string;
-        canBridgeTo?: Array<{
-            network: string;
-            symbol: string;
-            destinationChainIds: string[];
-        }>;
-    }>;
-}
-/**
- * Bridge token metadata for internal use
- *
- * Lightweight metadata for bridging operations,
- * distinct from blockchain metadata or cache entries.
- *
- * @since 6.10.0 - Renamed from TokenMetadata for clarity
- */
-export interface BridgeTokenMetadata {
-    /** Token descriptor (collection, category, type, additionalKey) */
-    descriptor: BridgeTokenDescriptor;
-    /** Token decimal places */
-    decimals: number;
-    /** GalaChain channel (optional) */
-    channel?: string;
-}
-/**
- * External token information (for exchange rates)
- */
-export interface ExternalTokenInfo {
-    name: string;
-    symbol: string;
-}
-/**
- * GALA exchange rate from oracle
- */
-export interface GalaExchangeRate {
-    identity: string;
-    oracle: string;
-    source: string;
-    sourceUrl: string;
-    timestamp: number | string;
-    baseToken?: BridgeTokenInstance;
-    exchangeRate: string;
-    externalQuoteToken?: ExternalTokenInfo;
-}
-/**
- * Base token cross rate
- */
-export interface BaseTokenCrossRate {
-    identity: string;
-    oracle: string;
-    source: string;
-    sourceUrl: string;
-    timestamp: number | string;
-    exchangeRate: string;
-    externalBaseToken?: ExternalTokenInfo;
-    externalQuoteToken?: ExternalTokenInfo;
-    signature: string;
-}
-/**
- * Quote token cross rate
- */
-export interface QuoteTokenCrossRate {
-    identity: string;
-    oracle: string;
-    source: string;
-    sourceUrl: string;
-    timestamp: number | string;
-    baseToken?: BridgeTokenInstance;
-    exchangeRate: string;
-    externalQuoteToken?: ExternalTokenInfo;
-    signature: string;
-}
-/**
- * GALA exchange cross rate (for non-GALA tokens)
- */
-export interface GalaExchangeCrossRate {
-    baseTokenCrossRate?: BaseTokenCrossRate;
-    crossRate: string;
-    externalCrossRateToken?: ExternalTokenInfo;
-    identity: string;
-    oracle: string;
-    quoteTokenCrossRate?: QuoteTokenCrossRate;
-    source: string;
-    timestamp: number | string;
-}
-/**
- * Destination chain transaction fee structure
- */
-export interface DestinationChainTxFee {
-    bridgeToken: BridgeTokenDescriptor;
-    bridgeTokenIsNonFungible: boolean;
-    estimatedPricePerTxFeeUnit: string;
-    estimatedTotalTxFeeInExternalToken: string;
-    estimatedTotalTxFeeInGala: string;
-    estimatedTxFeeUnitsTotal: string;
-    galaDecimals: number | string;
-    galaExchangeRate?: GalaExchangeRate;
-    galaExchangeCrossRate?: GalaExchangeCrossRate;
-    timestamp: number | string;
-    signingIdentity: string;
-    signature: string;
-}
-/**
- * Bridge fee estimate returned to SDK users
- */
-export interface BridgeFeeEstimate {
-    /** Estimated fee in GALA */
-    estimatedFeeInGala: string;
-    /** Estimated fee in the external chain's native token */
-    estimatedFeeInExternalToken: string;
-    /** Token used for bridge fees */
-    feeToken: BridgeTokenDescriptor;
-    /** Gas price per unit */
-    pricePerUnit: string;
-    /** Total estimated gas units */
-    estimatedGasUnits: string;
-    /** GALA exchange rate at time of estimate */
-    exchangeRate: string;
-    /** Timestamp of the estimate */
-    timestamp: number;
-    /** Raw fee response for advanced usage */
-    raw: DestinationChainTxFee;
-}
-/**
- * Bridge request DTO for outbound bridges
- */
-export interface BridgeRequestDto {
-    uniqueKey?: string;
-    tokenInstance: BridgeTokenInstance;
-    destinationChainId: number | string;
-    quantity: string;
-    recipient: string;
-    destinationChainTxFee: DestinationChainTxFee;
-}
-/**
- * Bridge status codes
- */
-export declare enum BridgeStatusCode {
-    PENDING = 0,
-    SUBMITTED = 1,
-    CONFIRMED = 2,
-    PROCESSING = 3,
-    FINALIZING = 4,
-    COMPLETED = 5,
-    FAILED = 6,
-    /** Delivery failed - tokens left source chain but failed to arrive on destination */
-    DELIVERY_FAILED = 7
-}
-/**
- * Bridge status response (normalized)
- */
-export interface BridgeStatus {
-    /** Numeric status code */
-    status: BridgeStatusCode;
-    /** Human-readable status description */
-    statusDescription: string;
-    /** Source chain */
-    fromChain: string;
-    /** Destination chain */
-    toChain: string;
-    /** Amount being bridged */
-    quantity: string;
-    /** Transaction hash on emitter chain */
-    transactionHash: string;
-    /** Token being bridged */
-    tokenInstance?: BridgeTokenInstance;
-    /** Whether the bridge is complete */
-    isComplete: boolean;
-    /** Whether the bridge failed */
-    isFailed: boolean;
-    /** Error message if failed */
-    error?: string;
-}
-/**
- * Solana transaction status from RPC query
- *
- * Used by `getSolanaTransactionStatus()` to report the confirmation
- * status of Solana transactions (airdrops, bridges, etc.)
- */
-export interface SolanaTransactionStatus {
-    /**
-     * Whether the transaction has been successfully processed on-chain.
-     * - true: Transaction executed successfully
-     * - false: Transaction not found, still pending, or failed
-     */
-    confirmed: boolean;
-    /**
-     * Detailed status of the transaction:
-     * - 'confirmed': Transaction confirmed by supermajority of cluster
-     * - 'finalized': Transaction finalized (maximum certainty)
-     * - 'processed': Transaction processed by connected node
-     * - 'not_found': Transaction not yet visible on-chain
-     * - 'failed': Transaction was processed but failed (see error field)
-     */
-    status: 'confirmed' | 'finalized' | 'processed' | 'not_found' | 'failed';
-    /**
-     * Block slot number where transaction was processed.
-     * Present when transaction has been found on-chain.
-     */
-    slot?: number;
-    /**
-     * Error details if transaction failed.
-     * Contains JSON-stringified Solana error object.
-     */
-    error?: string;
-}
-/**
- * Ethereum transaction status from RPC query
- *
- * Used by `getEthereumTransactionStatus()` to report the confirmation
- * status of Ethereum transactions (bridges, transfers, etc.)
- */
-export interface EthereumTransactionStatus {
-    /**
-     * Whether the transaction has been successfully processed on-chain.
-     * - true: Transaction confirmed and executed successfully
-     * - false: Transaction not found, still pending, or failed
-     */
-    confirmed: boolean;
-    /**
-     * Detailed status of the transaction:
-     * - 'pending': Transaction in mempool, not yet mined
-     * - 'confirmed': Transaction mined in block
-     * - 'finalized': Transaction finalized (12+ confirmations for safety)
-     * - 'not_found': Transaction not yet visible on-chain
-     * - 'failed': Transaction mined but execution failed (reverted)
-     */
-    status: 'pending' | 'confirmed' | 'finalized' | 'not_found' | 'failed';
-    /**
-     * Block number where transaction was mined.
-     * Present when transaction has been found on-chain.
-     */
-    blockNumber?: number;
-    /**
-     * Number of confirmations since block inclusion.
-     * Calculated as (currentBlockNumber - blockNumber + 1).
-     * Higher values indicate stronger finality.
-     */
-    confirmations?: number;
-    /**
-     * Transaction hash (normalized to lowercase).
-     */
-    transactionHash: string;
-    /**
-     * Gas used by transaction (if mined).
-     */
-    gasUsed?: string;
-    /**
-     * Effective gas price in wei (if mined).
-     */
-    effectiveGasPrice?: string;
-    /**
-     * Error details if transaction failed.
-     * Contains the revert reason or execution error.
-     */
-    error?: string;
-}
-/**
- * Bridge transaction result
- */
-export interface BridgeTransaction {
-    /** Direction of the bridge */
-    direction: 'outbound' | 'inbound';
-    /** Source chain */
-    fromChain: string;
-    /** Destination chain */
-    toChain: string;
-    /** Transaction hash */
-    transactionHash: string;
-    /** Token symbol */
-    tokenSymbol: string;
-    /** Amount bridged */
-    amount: string;
-    /** Fee paid (in GALA for outbound, native token for inbound) */
-    feePaid?: string;
-    /** Timestamp when transaction was submitted */
-    timestamp: number;
-    /** Bridge status tracking URL */
-    statusUrl: string;
-}
-/**
- * Bridge leg result (for round-trip tracking)
- */
-export interface BridgeLegResult {
-    direction: 'Outbound' | 'Inbound';
-    fromChain: string;
-    toChain: string;
-    startTimestamp: number;
-    endTimestamp?: number;
-    durationMs?: number;
-    feePaid?: string;
-    feeToken?: string;
-    transactionHash?: string;
-    additionalInfo?: Record<string, unknown>;
-    error?: string;
-}
-/**
- * Token round-trip result
- */
-export interface TokenRoundTripResult {
-    token: string;
-    network: ExternalNetwork;
-    amount: string;
-    legs: BridgeLegResult[];
-    outboundCompleted: boolean;
-    inboundCompleted: boolean;
-    roundTripDurationMs?: number;
-    totalFees?: Array<{
-        amount: string;
-        token: string;
-        context: string;
-    }>;
-    failures?: string[];
-}
-/**
- * Supported bridge token info for discovery
- */
-export interface BridgeToken {
-    /** Token symbol (e.g., 'GALA', 'GWETH') */
-    symbol: string;
-    /** Token name */
-    name?: string;
-    /** Token decimals */
-    decimals: number;
-    /** Whether verified by Gala */
-    verified: boolean;
-    /** Supported destination chains */
-    supportedChains: ExternalNetwork[];
-    /** GalaChain token descriptor */
-    galaChainDescriptor: BridgeTokenDescriptor;
-    /** External chain addresses */
-    externalAddresses: {
-        ethereum?: string;
-        solana?: string;
-    };
-}
-/**
- * Bridge SDK configuration
- */
-export interface BridgeConfig {
-    /** GalaConnect API base URL */
-    galaConnectBaseUrl: string;
-    /** GalaChain API base URL (optional, defaults to galaConnectBaseUrl) */
-    galaChainApiBaseUrl?: string;
-    /** Ethereum RPC URL (optional, defaults to public endpoint) */
-    ethereumRpcUrl?: string;
-    /** Solana RPC URL (optional, defaults to public endpoint) */
-    solanaRpcUrl?: string;
-    /** Ethereum bridge contract address (optional, defaults to mainnet) */
-    ethereumBridgeContract?: string;
-    /** Solana bridge program ID (optional, defaults to mainnet) */
-    solanaBridgeProgram?: string;
-    /** Ethereum private key for inbound bridges (optional) */
-    ethereumPrivateKey?: string;
-    /** Solana private key (base58) for inbound bridges (optional) */
-    solanaPrivateKey?: string;
-    /** Rate limit for API calls (requests per second) */
-    rateLimit?: number;
-    /** Status polling interval in milliseconds */
-    pollInterval?: number;
-    /** Status polling timeout in milliseconds */
-    pollTimeout?: number;
-}
-/**
- * Parameters for estimating bridge fees
- *
- * @example Using string tokenId (pipe-delimited)
- * ```typescript
- * const fee = await sdk.estimateBridgeFee({
- *   tokenId: 'GALA|Unit|none|none',
- *   destinationChain: 'Ethereum',
- * });
- * ```
- *
- * @example Using TokenClassKey object
- * ```typescript
- * const fee = await sdk.estimateBridgeFee({
- *   tokenId: { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' },
- *   destinationChain: 'Ethereum',
- * });
- * ```
- */
-export interface EstimateBridgeFeeParams {
-    /**
-     * Token identifier - accepts pipe-delimited string or TokenClassKey object.
-     *
-     * Get from `fetchAllBridgeableTokensByNetwork()` result's `stringifiedTokenClassKey` field,
-     * or construct manually: `{ collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' }`
-     */
-    tokenId: TokenId;
-    /** Destination chain */
-    destinationChain: ExternalNetwork;
-    /** Amount to bridge (optional, for more accurate estimates) */
-    amount?: string;
-}
-/**
- * Parameters for bridging out (GalaChain -> External)
- *
- * @example Bridge GALA to Ethereum
- * ```typescript
- * const result = await sdk.bridgeOut({
- *   tokenId: 'GALA|Unit|none|none',
- *   amount: '100',
- *   destinationChain: 'Ethereum',
- *   recipientAddress: '0x1234...abcd',
- * });
- * ```
- */
-export interface BridgeOutParams {
-    /**
-     * Token identifier - accepts pipe-delimited string or TokenClassKey object.
-     *
-     * Get from `fetchAllBridgeableTokensByNetwork()` result's `stringifiedTokenClassKey` field,
-     * or construct manually: `{ collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' }`
-     */
-    tokenId: TokenId;
-    /** Amount to bridge */
-    amount: string;
-    /** Destination chain */
-    destinationChain: ExternalNetwork;
-    /** Recipient address on destination chain */
-    recipientAddress: string;
-    /** Optional slippage tolerance for fee (0-1, e.g., 0.01 for 1%) */
-    feeSlippageTolerance?: number;
-    /**
-     * @internal Resolved token symbol (set by BridgeService, not user-provided)
-     */
-    tokenSymbol?: string;
-}
-/**
- * Parameters for bridging in (External -> GalaChain)
- *
- * @example Bridge GALA from Ethereum to GalaChain
- * ```typescript
- * const result = await sdk.bridgeIn({
- *   tokenId: 'GALA|Unit|none|none',
- *   amount: '100',
- *   sourceChain: 'Ethereum',
- *   sourcePrivateKey: '0xabc...', // Ethereum wallet private key
- * });
- * ```
- */
-export interface BridgeInParams {
-    /**
-     * Token identifier - accepts pipe-delimited string or TokenClassKey object.
-     *
-     * Get from `fetchAllBridgeableTokensByNetwork()` result's `stringifiedTokenClassKey` field,
-     * or construct manually: `{ collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' }`
-     */
-    tokenId: TokenId;
-    /** Amount to bridge */
-    amount: string;
-    /** Source chain */
-    sourceChain: ExternalNetwork;
-    /** Private key for source chain wallet (overrides config) */
-    sourcePrivateKey?: string;
-    /** Recipient GalaChain address (optional, defaults to SDK wallet) */
-    recipientAddress?: string;
-    /**
-     * @internal Resolved token symbol (set by BridgeService, not user-provided)
-     */
-    tokenSymbol?: string;
-}
-/**
- * Options for waiting on bridge completion
- */
-export interface WaitForBridgeOptions {
-    /** Polling interval in milliseconds (default: 15000) */
-    pollInterval?: number;
-    /** Timeout in milliseconds (default: 45 minutes) */
-    timeout?: number;
-    /** Callback for status updates */
-    onStatusUpdate?: (status: BridgeStatus) => void;
-}
-/**
- * Configuration for GalaConnect client
- */
-export interface GalaConnectConfig {
-    /** GalaConnect API base URL */
-    baseUrl?: string;
-    /** GalaChain API base URL */
-    galachainBaseUrl?: string;
-    /** Wallet address in GalaChain format (e.g., 'eth|0x...') */
-    walletAddress: string;
-    /** Requests per second (rate limiting) */
-    requestsPerSecond?: number;
-    /**
-     * Enable automatic retry for transient failures (default: true)
-     *
-     * When enabled, requests that fail due to network errors or
-     * server errors (5xx, 429) will be automatically retried with
-     * exponential backoff.
-     */
-    enableRetry?: boolean;
-    /**
-     * Maximum number of retry attempts (default: 3)
-     *
-     * Only used when enableRetry is true.
-     */
-    maxRetries?: number;
-    /**
-     * Initial delay in milliseconds before first retry (default: 1000)
-     *
-     * Subsequent retries use exponential backoff (delay doubles each time).
-     */
-    retryInitialDelayMs?: number;
-    /**
-     * Callback invoked before each retry attempt.
-     *
-     * Useful for logging or monitoring retry behavior.
-     *
-     * @param error - The error that triggered the retry
-     * @param attempt - Current attempt number (1-based)
-     * @param delayMs - Delay before next attempt in milliseconds
-     */
-    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
-}
-/**
- * Bridge fee response from GalaConnect API
- */
-export interface BridgeFeeResponse {
-    bridgeToken: BridgeTokenDescriptor;
-    bridgeTokenIsNonFungible: boolean;
-    estimatedPricePerTxFeeUnit: string;
-    estimatedTotalTxFeeInExternalToken: string;
-    estimatedTotalTxFeeInGala: string;
-    estimatedTxFeeUnitsTotal: string;
-    galaDecimals: number;
-    galaExchangeRate: GalaExchangeRate;
-    galaExchangeCrossRate?: GalaExchangeCrossRate;
-    timestamp: number;
-    signingIdentity: string;
-    signature: string;
-}
-/**
- * Response from RequestTokenBridgeOut API
- *
- * Note: The GalaConnect API may return additional undocumented fields.
- * The index signature ensures compatibility with Record<string, unknown>
- * while preserving type safety for known fields.
- *
- * Known fields may appear in different casings (e.g., Data/data, Hash/hash)
- * due to API response inconsistencies across different endpoints.
- */
-export interface RequestBridgeOutResponse {
-    Data?: string;
-    data?: {
-        Data?: string;
-    } | string;
-    Hash?: string;
-    hash?: string;
-    Status?: number;
-    status?: number;
-    message?: string;
-    /** Index signature for API compatibility (additional undocumented fields) */
-    [key: string]: unknown;
-}
-/**
- * Response from BridgeTokenOut API
- */
-export interface BridgeTokenOutResponse {
-    Data?: {
-        chainId: number;
-        emitter: string;
-        nonce: string;
-        sequence: string;
-        payload: string;
-    };
-    Hash?: string;
-    hash?: string;
-    Status?: number;
-    status?: number;
-    message?: string;
-}
-/**
- * Response from bridge status API.
- *
- * Note: The API returns a flat response structure (no data wrapper).
- */
-export interface BridgeStatusResponse {
-    /** Status code (0-6 mapping to BridgeStatusCode) */
-    status: number;
-    /** Human-readable status description */
-    statusDescription: string;
-    /** Source chain (e.g., "GC" for GalaChain) */
-    fromChain: string;
-    /** Destination chain (e.g., "Ethereum") */
-    toChain: string;
-    /** Amount being bridged */
-    quantity: string;
-    /** Transaction hash on the emitter (source) chain */
-    emitterTransactionHash: string;
-    /** Token instance being bridged */
-    tokenInstance: BridgeTokenInstance;
-    /** Transaction hash on the receiver (destination) chain, if available */
-    receiverTransactionHash?: string;
-}
-/**
- * Response from bridge transaction registration API
- */
-export interface BridgeTransactionRegistrationResponse {
-    status: number;
-    message: string;
-    error: boolean;
-    data?: Record<string, unknown>;
-}
-/**
- * Token balance entry from FetchBalances
- */
-export interface TokenBalanceEntry {
-    tokenInstance: BridgeTokenInstance;
-    balance: string;
-    locked?: string;
-}
-/**
- * Response from FetchBalances API
- */
-export interface FetchBalancesResponse {
-    status: number;
-    message: string;
-    error: boolean;
-    data?: {
-        balances: TokenBalanceEntry[];
-    };
-}
-/**
- * Balance for a single token on an external chain (Ethereum or Solana)
- *
- * Represents either a native token (ETH/SOL) or a token contract (ERC-20/SPL).
- *
- * @example
- * ```typescript
- * // Native ETH balance
- * const ethBalance: ExternalChainBalance = {
- *   symbol: 'ETH',
- *   quantity: '1.500000000000000000',
- *   decimals: 18,
- *   contractAddress: null,
- *   isNative: true,
- * };
- *
- * // ERC-20 GALA balance
- * const galaBalance: ExternalChainBalance = {
- *   symbol: 'GALA',
- *   quantity: '1000.00000000',
- *   decimals: 8,
- *   contractAddress: '0x15D4c048F83bd7e37d49eA4C83a07267Ec4203dA',
- *   isNative: false,
- * };
- * ```
- */
-export interface ExternalChainBalance {
-    /** Token symbol (e.g., "GALA", "GWETH", "ETH", "SOL") */
-    symbol: string;
-    /** Balance as decimal string (e.g., "123.45678901") */
-    quantity: string;
-    /** Token decimals */
-    decimals: number;
-    /** Contract address (ERC-20) or mint address (SPL), null for native tokens */
-    contractAddress: string | null;
-    /** Whether this is the native token (ETH/SOL) */
-    isNative: boolean;
-}
-/**
- * Complete Ethereum wallet balance result
- *
- * Returns native ETH balance plus all supported ERC-20 token balances:
- * GALA, GWETH, GUSDC, GUSDT, GWTRX, GWBTC
- *
- * @example
- * ```typescript
- * const result = await sdk.fetchEthereumWalletBalance('0x...');
- * console.log(`ETH: ${result.native.quantity}`);
- * console.log(`Tokens: ${result.tokens.map(t => `${t.symbol}: ${t.quantity}`).join(', ')}`);
- * ```
- */
-export interface EthereumWalletBalanceResult {
-    /** Wallet address queried (0x format) */
-    address: string;
-    /** Native ETH balance */
-    native: ExternalChainBalance;
-    /** ERC-20 token balances (GALA, GWETH, GUSDC, GUSDT, GWTRX, GWBTC) */
-    tokens: ExternalChainBalance[];
-    /** Query timestamp (epoch ms) */
-    timestamp: number;
-}
-/**
- * Complete Solana wallet balance result
- *
- * Returns native SOL balance plus all supported SPL token balances:
- * GALA, GSOL
- *
- * @example
- * ```typescript
- * const result = await sdk.fetchSolanaWalletBalance('9WzDXw...');
- * console.log(`SOL: ${result.native.quantity}`);
- * console.log(`Tokens: ${result.tokens.map(t => `${t.symbol}: ${t.quantity}`).join(', ')}`);
- * ```
- */
-export interface SolanaWalletBalanceResult {
-    /** Wallet address queried (base58 format) */
-    address: string;
-    /** Native SOL balance */
-    native: ExternalChainBalance;
-    /** SPL token balances (GALA, GSOL) */
-    tokens: ExternalChainBalance[];
-    /** Query timestamp (epoch ms) */
-    timestamp: number;
-}
-//# sourceMappingURL=bridge.dto.d.ts.map