@n1xyz/wallet-widget 0.0.35-alpha.0 → 0.0.35-alpha.1

package/dist/src/utils/address.js

@@ -0,0 +1,274 @@
+/**
+ * Address utilities for validation and normalization across Solana and EVM chains.
+ * Uses library functions from @solana/web3.js and viem for proper validation.
+ * Centralizes address handling that was previously scattered across multiple files.
+ */
+import { PublicKey } from '@solana/web3.js';
+import { isAddress as viemIsAddress, getAddress as viemGetAddress } from 'viem';
+// ---------------------------------------------------------------------------
+// Solana Address Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validates a Solana address by attempting to construct a PublicKey.
+ * This validates the base58 encoding and length.
+ *
+ * @param address - The address to validate
+ * @returns true if valid Solana address format
+ */
+export function isValidSolanaAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return false;
+    }
+    try {
+        new PublicKey(address);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Validates a Solana wallet address (must be on the ed25519 curve).
+ * PDAs (Program Derived Addresses) are intentionally off-curve and will return false.
+ * Use isValidSolanaAddress() if you need to accept PDAs.
+ *
+ * @param address - The address to validate
+ * @returns true if valid Solana wallet address on the ed25519 curve
+ */
+export function isValidSolanaWalletAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return false;
+    }
+    try {
+        var pubkey = new PublicKey(address);
+        return PublicKey.isOnCurve(pubkey.toBytes());
+    }
+    catch (_a) {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// EVM Address Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validates an EVM address using viem's isAddress function.
+ * Uses strict: false to accept addresses regardless of checksum.
+ *
+ * @param address - The address to validate
+ * @returns true if valid EVM address format
+ */
+export function isValidEVMAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return false;
+    }
+    // Use strict: false to accept addresses regardless of checksum
+    return viemIsAddress(address, { strict: false });
+}
+/**
+ * Validates an EVM address with strict checksum validation.
+ *
+ * @param address - The address to validate
+ * @returns true if valid EVM address with correct checksum
+ */
+export function isValidEVMAddressStrict(address) {
+    if (!address || typeof address !== 'string') {
+        return false;
+    }
+    return viemIsAddress(address, { strict: true });
+}
+// ---------------------------------------------------------------------------
+// Universal Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validates an address for either Solana or EVM.
+ *
+ * @param address - The address to validate
+ * @returns Object with isValid flag and detected network type
+ */
+export function validateAddress(address) {
+    if (isValidEVMAddress(address)) {
+        return { isValid: true, network: 'evm' };
+    }
+    if (isValidSolanaAddress(address)) {
+        return { isValid: true, network: 'solana' };
+    }
+    return { isValid: false, network: null };
+}
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+/**
+ * Normalizes an EVM address to checksummed format using viem.
+ * This is the canonical format for EVM addresses.
+ *
+ * @param address - The EVM address to normalize
+ * @returns Checksummed address, or empty string if invalid
+ */
+export function normalizeEVMAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return '';
+    }
+    try {
+        return viemGetAddress(address);
+    }
+    catch (_a) {
+        // If getAddress fails, return lowercase as fallback
+        return address.toLowerCase().trim();
+    }
+}
+/**
+ * Normalizes an EVM address to lowercase for comparison purposes.
+ * This replaces the duplicated normalizeAddress functions in TurnkeyProvider.tsx
+ * and turnkeySessionStorage.ts.
+ *
+ * @param address - The EVM address to normalize
+ * @returns Lowercase address, or empty string if invalid
+ */
+export function normalizeEVMAddressLowercase(address) {
+    if (!address || typeof address !== 'string') {
+        return '';
+    }
+    return address.toLowerCase().trim();
+}
+/**
+ * Normalizes a Solana address (trimming whitespace).
+ * Solana addresses are case-sensitive (base58), so we only trim.
+ *
+ * @param address - The Solana address to normalize
+ * @returns Trimmed address, or empty string if invalid
+ */
+export function normalizeSolanaAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return '';
+    }
+    return address.trim();
+}
+/**
+ * Normalizes any address based on detected type.
+ * EVM addresses are lowercased, Solana addresses are trimmed.
+ *
+ * @param address - The address to normalize
+ * @returns Normalized address
+ */
+export function normalizeAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return '';
+    }
+    var trimmed = address.trim();
+    // If it looks like an EVM address, lowercase it for comparison
+    if (trimmed.startsWith('0x')) {
+        return trimmed.toLowerCase();
+    }
+    // Otherwise treat as Solana (case-sensitive)
+    return trimmed;
+}
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+/**
+ * Compares two addresses for equality.
+ * Handles case-insensitive comparison for EVM and case-sensitive for Solana.
+ *
+ * @param a - First address
+ * @param b - Second address
+ * @returns true if addresses are equal
+ */
+export function compareAddresses(a, b) {
+    if (!a || !b) {
+        return a === b; // Both null/undefined = equal, one null = not equal
+    }
+    return normalizeAddress(a) === normalizeAddress(b);
+}
+/**
+ * Compares two EVM addresses for equality using viem's address comparison.
+ * More robust than string comparison.
+ *
+ * @param a - First EVM address
+ * @param b - Second EVM address
+ * @returns true if addresses are equal
+ */
+export function compareEVMAddresses(a, b) {
+    if (!a || !b) {
+        return a === b;
+    }
+    try {
+        return viemGetAddress(a) === viemGetAddress(b);
+    }
+    catch (_a) {
+        // Fall back to lowercase comparison if getAddress fails
+        return a.toLowerCase() === b.toLowerCase();
+    }
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+/**
+ * Shortens an address for display.
+ * Example: "0x1234567890abcdef1234567890abcdef12345678" -> "0x1234...5678"
+ *
+ * @param address - The address to shorten
+ * @param chars - Number of characters to show at start/end (default: 4)
+ * @returns Shortened address
+ */
+export function shortenAddress(address, chars) {
+    if (chars === void 0) { chars = 4; }
+    if (!address || typeof address !== 'string') {
+        return '';
+    }
+    var trimmed = address.trim();
+    // If address is short enough, return as-is
+    if (trimmed.length <= chars * 2 + 3) {
+        return trimmed;
+    }
+    // Handle EVM addresses (0x prefix)
+    if (trimmed.startsWith('0x')) {
+        return "".concat(trimmed.slice(0, chars + 2), "...").concat(trimmed.slice(-chars));
+    }
+    // Handle Solana or other addresses
+    return "".concat(trimmed.slice(0, chars), "...").concat(trimmed.slice(-chars));
+}
+// ---------------------------------------------------------------------------
+// Conversion
+// ---------------------------------------------------------------------------
+/**
+ * Converts a Solana PublicKey to its base58 string representation.
+ *
+ * @param pubkey - The PublicKey to convert (can be PublicKey object or Uint8Array)
+ * @returns Base58 string representation
+ */
+export function solanaPublicKeyToString(pubkey) {
+    if (pubkey instanceof PublicKey) {
+        return pubkey.toBase58();
+    }
+    return new PublicKey(pubkey).toBase58();
+}
+/**
+ * Converts a base58 string to a Solana PublicKey.
+ *
+ * @param address - The base58 address string
+ * @returns PublicKey object, or null if invalid
+ */
+export function stringToSolanaPublicKey(address) {
+    try {
+        return new PublicKey(address);
+    }
+    catch (_a) {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+/**
+ * Type guard to check if an address is a valid EVM address.
+ */
+export function isEVMAddress(address) {
+    return typeof address === 'string' && isValidEVMAddress(address);
+}
+/**
+ * Type guard to check if an address is a valid Solana address.
+ */
+export function isSolanaAddress(address) {
+    return typeof address === 'string' && isValidSolanaAddress(address);
+}
+//# sourceMappingURL=address.js.map

package/dist/src/utils/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../../src/utils/address.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Address utilities for validation and normalization across Solana and EVM chains.\n * Uses library functions from @solana/web3.js and viem for proper validation.\n * Centralizes address handling that was previously scattered across multiple files.\n */\n\nimport { PublicKey } from '@solana/web3.js';\nimport { isAddress as viemIsAddress, getAddress as viemGetAddress } from 'viem';\n\n// ---------------------------------------------------------------------------\n// Solana Address Validation\n// ---------------------------------------------------------------------------\n\n/**\n * Validates a Solana address by attempting to construct a PublicKey.\n * This validates the base58 encoding and length.\n *\n * @param address - The address to validate\n * @returns true if valid Solana address format\n */\nexport function isValidSolanaAddress(address: string): boolean {\n  if (!address || typeof address !== 'string') {\n    return false;\n  }\n\n  try {\n    new PublicKey(address);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Validates a Solana wallet address (must be on the ed25519 curve).\n * PDAs (Program Derived Addresses) are intentionally off-curve and will return false.\n * Use isValidSolanaAddress() if you need to accept PDAs.\n *\n * @param address - The address to validate\n * @returns true if valid Solana wallet address on the ed25519 curve\n */\nexport function isValidSolanaWalletAddress(address: string): boolean {\n  if (!address || typeof address !== 'string') {\n    return false;\n  }\n\n  try {\n    const pubkey = new PublicKey(address);\n    return PublicKey.isOnCurve(pubkey.toBytes());\n  } catch {\n    return false;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// EVM Address Validation\n// ---------------------------------------------------------------------------\n\n/**\n * Validates an EVM address using viem's isAddress function.\n * Uses strict: false to accept addresses regardless of checksum.\n *\n * @param address - The address to validate\n * @returns true if valid EVM address format\n */\nexport function isValidEVMAddress(address: string): boolean {\n  if (!address || typeof address !== 'string') {\n    return false;\n  }\n\n  // Use strict: false to accept addresses regardless of checksum\n  return viemIsAddress(address, { strict: false });\n}\n\n/**\n * Validates an EVM address with strict checksum validation.\n *\n * @param address - The address to validate\n * @returns true if valid EVM address with correct checksum\n */\nexport function isValidEVMAddressStrict(address: string): boolean {\n  if (!address || typeof address !== 'string') {\n    return false;\n  }\n\n  return viemIsAddress(address, { strict: true });\n}\n\n// ---------------------------------------------------------------------------\n// Universal Validation\n// ---------------------------------------------------------------------------\n\n/**\n * Validates an address for either Solana or EVM.\n *\n * @param address - The address to validate\n * @returns Object with isValid flag and detected network type\n */\nexport function validateAddress(address: string): {\n  isValid: boolean;\n  network: 'solana' | 'evm' | null;\n} {\n  if (isValidEVMAddress(address)) {\n    return { isValid: true, network: 'evm' };\n  }\n  if (isValidSolanaAddress(address)) {\n    return { isValid: true, network: 'solana' };\n  }\n  return { isValid: false, network: null };\n}\n\n// ---------------------------------------------------------------------------\n// Normalization\n// ---------------------------------------------------------------------------\n\n/**\n * Normalizes an EVM address to checksummed format using viem.\n * This is the canonical format for EVM addresses.\n *\n * @param address - The EVM address to normalize\n * @returns Checksummed address, or empty string if invalid\n */\nexport function normalizeEVMAddress(address: string | null | undefined): string {\n  if (!address || typeof address !== 'string') {\n    return '';\n  }\n\n  try {\n    return viemGetAddress(address);\n  } catch {\n    // If getAddress fails, return lowercase as fallback\n    return address.toLowerCase().trim();\n  }\n}\n\n/**\n * Normalizes an EVM address to lowercase for comparison purposes.\n * This replaces the duplicated normalizeAddress functions in TurnkeyProvider.tsx\n * and turnkeySessionStorage.ts.\n *\n * @param address - The EVM address to normalize\n * @returns Lowercase address, or empty string if invalid\n */\nexport function normalizeEVMAddressLowercase(address: string | null | undefined): string {\n  if (!address || typeof address !== 'string') {\n    return '';\n  }\n  return address.toLowerCase().trim();\n}\n\n/**\n * Normalizes a Solana address (trimming whitespace).\n * Solana addresses are case-sensitive (base58), so we only trim.\n *\n * @param address - The Solana address to normalize\n * @returns Trimmed address, or empty string if invalid\n */\nexport function normalizeSolanaAddress(address: string | null | undefined): string {\n  if (!address || typeof address !== 'string') {\n    return '';\n  }\n  return address.trim();\n}\n\n/**\n * Normalizes any address based on detected type.\n * EVM addresses are lowercased, Solana addresses are trimmed.\n *\n * @param address - The address to normalize\n * @returns Normalized address\n */\nexport function normalizeAddress(address: string | null | undefined): string {\n  if (!address || typeof address !== 'string') {\n    return '';\n  }\n\n  const trimmed = address.trim();\n\n  // If it looks like an EVM address, lowercase it for comparison\n  if (trimmed.startsWith('0x')) {\n    return trimmed.toLowerCase();\n  }\n\n  // Otherwise treat as Solana (case-sensitive)\n  return trimmed;\n}\n\n// ---------------------------------------------------------------------------\n// Comparison\n// ---------------------------------------------------------------------------\n\n/**\n * Compares two addresses for equality.\n * Handles case-insensitive comparison for EVM and case-sensitive for Solana.\n *\n * @param a - First address\n * @param b - Second address\n * @returns true if addresses are equal\n */\nexport function compareAddresses(\n  a: string | null | undefined,\n  b: string | null | undefined\n): boolean {\n  if (!a || !b) {\n    return a === b; // Both null/undefined = equal, one null = not equal\n  }\n\n  return normalizeAddress(a) === normalizeAddress(b);\n}\n\n/**\n * Compares two EVM addresses for equality using viem's address comparison.\n * More robust than string comparison.\n *\n * @param a - First EVM address\n * @param b - Second EVM address\n * @returns true if addresses are equal\n */\nexport function compareEVMAddresses(\n  a: string | null | undefined,\n  b: string | null | undefined\n): boolean {\n  if (!a || !b) {\n    return a === b;\n  }\n\n  try {\n    return viemGetAddress(a) === viemGetAddress(b);\n  } catch {\n    // Fall back to lowercase comparison if getAddress fails\n    return a.toLowerCase() === b.toLowerCase();\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Formatting\n// ---------------------------------------------------------------------------\n\n/**\n * Shortens an address for display.\n * Example: \"0x1234567890abcdef1234567890abcdef12345678\" -> \"0x1234...5678\"\n *\n * @param address - The address to shorten\n * @param chars - Number of characters to show at start/end (default: 4)\n * @returns Shortened address\n */\nexport function shortenAddress(address: string | null | undefined, chars: number = 4): string {\n  if (!address || typeof address !== 'string') {\n    return '';\n  }\n\n  const trimmed = address.trim();\n\n  // If address is short enough, return as-is\n  if (trimmed.length <= chars * 2 + 3) {\n    return trimmed;\n  }\n\n  // Handle EVM addresses (0x prefix)\n  if (trimmed.startsWith('0x')) {\n    return `${trimmed.slice(0, chars + 2)}...${trimmed.slice(-chars)}`;\n  }\n\n  // Handle Solana or other addresses\n  return `${trimmed.slice(0, chars)}...${trimmed.slice(-chars)}`;\n}\n\n// ---------------------------------------------------------------------------\n// Conversion\n// ---------------------------------------------------------------------------\n\n/**\n * Converts a Solana PublicKey to its base58 string representation.\n *\n * @param pubkey - The PublicKey to convert (can be PublicKey object or Uint8Array)\n * @returns Base58 string representation\n */\nexport function solanaPublicKeyToString(pubkey: PublicKey | Uint8Array): string {\n  if (pubkey instanceof PublicKey) {\n    return pubkey.toBase58();\n  }\n  return new PublicKey(pubkey).toBase58();\n}\n\n/**\n * Converts a base58 string to a Solana PublicKey.\n *\n * @param address - The base58 address string\n * @returns PublicKey object, or null if invalid\n */\nexport function stringToSolanaPublicKey(address: string): PublicKey | null {\n  try {\n    return new PublicKey(address);\n  } catch {\n    return null;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Type Guards\n// ---------------------------------------------------------------------------\n\n/**\n * Type guard to check if an address is a valid EVM address.\n */\nexport function isEVMAddress(address: unknown): address is string {\n  return typeof address === 'string' && isValidEVMAddress(address);\n}\n\n/**\n * Type guard to check if an address is a valid Solana address.\n */\nexport function isSolanaAddress(address: unknown): address is string {\n  return typeof address === 'string' && isValidSolanaAddress(address);\n}\n"]}

package/dist/src/utils/chain.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Chain utilities for handling chain IDs and network identification.
+ * Centralizes chain handling that was previously scattered across multiple files.
+ *
+ * Integrates with:
+ * - viem's Chain type for EVM chains
+ * - Project's src/config/chains.tsx for network configuration
+ */
+import type { Chain as ViemChain } from 'viem';
+export type NetworkType = 'solana' | 'evm';
+export interface ChainInfo {
+    id: string;
+    name: string;
+    network: NetworkType;
+    chainId?: number;
+}
+/**
+ * Normalizes a chain ID to hexadecimal format (e.g., "0x1").
+ * This is the format expected by EIP-1193 providers.
+ *
+ * Handles:
+ * - Numbers (1 -> "0x1")
+ * - Hex strings ("0x1" -> "0x1")
+ * - Decimal strings ("1" -> "0x1")
+ * - Objects with chainId or id properties (viem Chain objects)
+ *
+ * Replaces the normalizeChainId function in createWalletProvider.ts
+ */
+export declare function normalizeChainId(value: unknown): string;
+/**
+ * Converts a chain ID to a number.
+ * Handles hex strings, decimal strings, numbers, and viem Chain objects.
+ */
+export declare function chainIdToNumber(value: unknown): number | null;
+/**
+ * Normalizes a chain identifier to a canonical name.
+ * Handles various formats: names, aliases, chain IDs (number or hex).
+ *
+ * Examples:
+ * - "arb" -> "arbitrum"
+ * - "ETH" -> "ethereum"
+ * - "arbitrum-one" -> "arbitrum"
+ * - "0x1" -> "ethereum"
+ * - 42161 -> "arbitrum"
+ */
+export declare function normalizeChainName(chain: string | number | null | undefined): string;
+/**
+ * Normalizes a chain for CCTP (Circle's Cross-Chain Transfer Protocol).
+ * Replaces normalizeCctpChain in bridgeUtils.ts
+ */
+export declare function normalizeCctpChain(chain: string | null | undefined): string;
+/**
+ * Derives a chain label for display.
+ * Returns both an id and a display name.
+ * Replaces deriveChainLabel in bridgeUtils.ts
+ */
+export declare function deriveChainLabel(chainId: string | null | undefined): {
+    id: string;
+    name: string;
+};
+/**
+ * Gets chain information from a chain identifier.
+ */
+export declare function getChainInfo(chain: string | number | null | undefined): ChainInfo | null;
+/**
+ * Checks if a chain is Solana.
+ */
+export declare function isSolanaChain(chain: string | null | undefined): boolean;
+/**
+ * Checks if a chain is an EVM chain.
+ */
+export declare function isEVMChain(chain: string | number | null | undefined): boolean;
+/**
+ * Detects the network type from a chain identifier.
+ */
+export declare function detectNetworkType(chain: string | number | null | undefined): NetworkType | null;
+/**
+ * Extracts the chain ID from a viem Chain object.
+ */
+export declare function getChainIdFromViemChain(chain: ViemChain | null | undefined): number | null;
+/**
+ * Checks if a chain ID matches a viem Chain object.
+ */
+export declare function chainIdMatchesViemChain(chainId: unknown, chain: ViemChain): boolean;
+/**
+ * Validates a chain ID format.
+ * Returns true if it's a valid hex string or positive number.
+ */
+export declare function isValidChainId(value: unknown): boolean;

package/dist/src/utils/chain.js

@@ -0,0 +1,282 @@
+/**
+ * Chain utilities for handling chain IDs and network identification.
+ * Centralizes chain handling that was previously scattered across multiple files.
+ *
+ * Integrates with:
+ * - viem's Chain type for EVM chains
+ * - Project's src/config/chains.tsx for network configuration
+ */
+// ---------------------------------------------------------------------------
+// Chain ID Normalization (from createWalletProvider.ts)
+// ---------------------------------------------------------------------------
+/**
+ * Normalizes a chain ID to hexadecimal format (e.g., "0x1").
+ * This is the format expected by EIP-1193 providers.
+ *
+ * Handles:
+ * - Numbers (1 -> "0x1")
+ * - Hex strings ("0x1" -> "0x1")
+ * - Decimal strings ("1" -> "0x1")
+ * - Objects with chainId or id properties (viem Chain objects)
+ *
+ * Replaces the normalizeChainId function in createWalletProvider.ts
+ */
+export function normalizeChainId(value) {
+    // Handle objects with chainId or id properties (including viem Chain objects)
+    if (value && typeof value === 'object') {
+        var candidate = value;
+        if (typeof candidate.chainId === 'number' || typeof candidate.chainId === 'string') {
+            return normalizeChainId(candidate.chainId);
+        }
+        if (typeof candidate.id === 'number' || typeof candidate.id === 'string') {
+            return normalizeChainId(candidate.id);
+        }
+    }
+    // Handle numbers
+    if (typeof value === 'number') {
+        return "0x".concat(value.toString(16));
+    }
+    // Handle strings
+    if (typeof value === 'string') {
+        // Already hex format
+        if (value.startsWith('0x')) {
+            return value;
+        }
+        // Try to parse as decimal
+        var numeric = Number(value);
+        if (!Number.isNaN(numeric)) {
+            return "0x".concat(numeric.toString(16));
+        }
+        // Return as-is (might be a chain name)
+        return value;
+    }
+    // Default to Ethereum mainnet
+    return '0x1';
+}
+/**
+ * Converts a chain ID to a number.
+ * Handles hex strings, decimal strings, numbers, and viem Chain objects.
+ */
+export function chainIdToNumber(value) {
+    // Handle viem Chain objects
+    if (value && typeof value === 'object') {
+        var candidate = value;
+        if (typeof candidate.id === 'number')
+            return candidate.id;
+        if (typeof candidate.chainId === 'number')
+            return candidate.chainId;
+    }
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (typeof value === 'string') {
+        if (value.startsWith('0x')) {
+            return parseInt(value, 16);
+        }
+        var parsed = parseInt(value, 10);
+        return Number.isNaN(parsed) ? null : parsed;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Chain Name Normalization (from bridgeUtils.ts)
+// ---------------------------------------------------------------------------
+/**
+ * Chain name aliases mapped to canonical names.
+ */
+var CHAIN_ALIASES = {
+    // Ethereum
+    eth: 'ethereum',
+    mainnet: 'ethereum',
+    evm: 'ethereum',
+    // Arbitrum
+    arb: 'arbitrum',
+    'arbitrum-one': 'arbitrum',
+    // Solana
+    sol: 'solana',
+};
+/**
+ * Known EVM chain IDs to canonical names.
+ */
+var CHAIN_ID_TO_NAME = {
+    // Mainnets
+    1: 'ethereum',
+    42161: 'arbitrum',
+    8453: 'base',
+    // Testnets
+    11155111: 'ethereum',
+    421614: 'arbitrum',
+    84532: 'base',
+};
+/**
+ * Normalizes a chain identifier to a canonical name.
+ * Handles various formats: names, aliases, chain IDs (number or hex).
+ *
+ * Examples:
+ * - "arb" -> "arbitrum"
+ * - "ETH" -> "ethereum"
+ * - "arbitrum-one" -> "arbitrum"
+ * - "0x1" -> "ethereum"
+ * - 42161 -> "arbitrum"
+ */
+export function normalizeChainName(chain) {
+    var _a, _b;
+    if (chain === null || chain === undefined)
+        return 'ethereum';
+    // Handle numeric chain IDs
+    if (typeof chain === 'number') {
+        return (_a = CHAIN_ID_TO_NAME[chain]) !== null && _a !== void 0 ? _a : 'ethereum';
+    }
+    var lower = chain.toLowerCase().trim();
+    // Check if it's a hex chain ID
+    if (lower.startsWith('0x')) {
+        var numericId = parseInt(lower, 16);
+        return (_b = CHAIN_ID_TO_NAME[numericId]) !== null && _b !== void 0 ? _b : 'ethereum';
+    }
+    // Check if it's a decimal chain ID string
+    var numeric = parseInt(lower, 10);
+    if (!Number.isNaN(numeric) && CHAIN_ID_TO_NAME[numeric]) {
+        return CHAIN_ID_TO_NAME[numeric];
+    }
+    // Check aliases
+    if (CHAIN_ALIASES[lower]) {
+        return CHAIN_ALIASES[lower];
+    }
+    // Return as-is if it's a known chain name or unknown
+    return lower;
+}
+/**
+ * Normalizes a chain for CCTP (Circle's Cross-Chain Transfer Protocol).
+ * Replaces normalizeCctpChain in bridgeUtils.ts
+ */
+export function normalizeCctpChain(chain) {
+    if (!chain)
+        return 'ethereum';
+    var lower = chain.toLowerCase();
+    if (lower === 'evm')
+        return 'ethereum';
+    if (lower === 'arb' || lower === 'arbitrum' || lower === 'arbitrum-one')
+        return 'arbitrum';
+    if (lower === 'base')
+        return 'base';
+    return lower;
+}
+// ---------------------------------------------------------------------------
+// Chain Info & Labels (from bridgeUtils.ts)
+// ---------------------------------------------------------------------------
+var CHAIN_DISPLAY_NAMES = {
+    solana: 'Solana',
+    ethereum: 'Ethereum',
+    arbitrum: 'Arbitrum',
+    base: 'Base',
+};
+/**
+ * Derives a chain label for display.
+ * Returns both an id and a display name.
+ * Replaces deriveChainLabel in bridgeUtils.ts
+ */
+export function deriveChainLabel(chainId) {
+    var _a;
+    if (!chainId)
+        return { id: 'solana', name: 'Solana' };
+    var normalized = normalizeChainName(chainId);
+    var displayName = (_a = CHAIN_DISPLAY_NAMES[normalized]) !== null && _a !== void 0 ? _a : chainId;
+    return { id: normalized, name: displayName };
+}
+/**
+ * Gets chain information from a chain identifier.
+ */
+export function getChainInfo(chain) {
+    if (chain === null || chain === undefined)
+        return null;
+    var normalized = normalizeChainName(chain);
+    var displayName = CHAIN_DISPLAY_NAMES[normalized];
+    if (!displayName)
+        return null;
+    var network = normalized === 'solana' ? 'solana' : 'evm';
+    return {
+        id: normalized,
+        name: displayName,
+        network: network,
+    };
+}
+// ---------------------------------------------------------------------------
+// Network Type Detection
+// ---------------------------------------------------------------------------
+/**
+ * Checks if a chain is Solana.
+ */
+export function isSolanaChain(chain) {
+    if (!chain)
+        return false;
+    return normalizeChainName(chain) === 'solana';
+}
+/**
+ * Checks if a chain is an EVM chain.
+ */
+export function isEVMChain(chain) {
+    if (chain === null || chain === undefined)
+        return false;
+    // Numeric chain IDs are always EVM
+    if (typeof chain === 'number')
+        return true;
+    var lower = chain.toLowerCase().trim();
+    // Hex chain IDs are EVM
+    if (lower.startsWith('0x'))
+        return true;
+    // Normalize and check
+    var normalized = normalizeChainName(chain);
+    return normalized !== 'solana';
+}
+/**
+ * Detects the network type from a chain identifier.
+ */
+export function detectNetworkType(chain) {
+    if (chain === null || chain === undefined)
+        return null;
+    if (isSolanaChain(chain))
+        return 'solana';
+    if (isEVMChain(chain))
+        return 'evm';
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Viem Chain Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extracts the chain ID from a viem Chain object.
+ */
+export function getChainIdFromViemChain(chain) {
+    if (!chain)
+        return null;
+    return chain.id;
+}
+/**
+ * Checks if a chain ID matches a viem Chain object.
+ */
+export function chainIdMatchesViemChain(chainId, chain) {
+    var numericId = chainIdToNumber(chainId);
+    return numericId === chain.id;
+}
+// ---------------------------------------------------------------------------
+// Chain ID Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validates a chain ID format.
+ * Returns true if it's a valid hex string or positive number.
+ */
+export function isValidChainId(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+        return true;
+    }
+    if (typeof value === 'string') {
+        if (value.startsWith('0x')) {
+            var hex = value.slice(2);
+            return /^[0-9a-fA-F]+$/.test(hex) && hex.length > 0;
+        }
+        var numeric = parseInt(value, 10);
+        return !Number.isNaN(numeric) && numeric > 0;
+    }
+    return false;
+}
+//# sourceMappingURL=chain.js.map