@circle-fin/provider-cctp-v2 1.6.1 → 1.6.2

package/index.mjs

@@ -182,8 +182,9 @@ var Blockchain;
 /**
  * Enum representing chains that support same-chain swaps through the Swap Kit.
  *
- * Unlike the full {@link Blockchain} enum, SwapChain includes only mainnet
- * networks where adapter contracts are deployed (CCTPv2 support).
+ * Unlike the full {@link Blockchain} enum, SwapChain includes mainnet
+ * networks and explicitly whitelisted testnets (e.g., {@link Arc_Testnet})
+ * where adapter contracts are deployed (CCTPv2 support).
  *
  * Dynamic validation via {@link isSwapSupportedChain} ensures chains
  * automatically work when adapter contracts and supported tokens are deployed.
@@ -228,6 +229,8 @@ var SwapChain;
     SwapChain["XDC"] = "XDC";
     SwapChain["HyperEVM"] = "HyperEVM";
     SwapChain["Monad"] = "Monad";
+    // Testnet chains with swap support
+    SwapChain["Arc_Testnet"] = "Arc_Testnet";
 })(SwapChain || (SwapChain = {}));
 // -----------------------------------------------------------------------------
 // Bridge Chain Enum (CCTPv2 Supported Chains)
@@ -324,6 +327,31 @@ var BridgeChain;
     BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     BridgeChain["XDC_Apothem"] = "XDC_Apothem";
 })(BridgeChain || (BridgeChain = {}));
+// -----------------------------------------------------------------------------
+// Earn Chain Enum
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of blockchains that support earn (vault deposit/withdraw)
+ * operations through the Earn Kit.
+ *
+ * Currently only Ethereum mainnet is supported. Additional chains
+ * will be added as vault protocol support expands.
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@core/chains'
+ *
+ * const result = await earnKit.deposit({
+ *   from: { adapter, chain: EarnChain.Ethereum },
+ *   vaultAddress: '0x...',
+ *   amount: '100',
+ * })
+ * ```
+ */
+var EarnChain;
+(function (EarnChain) {
+    EarnChain["Ethereum"] = "Ethereum";
+})(EarnChain || (EarnChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -626,6 +654,14 @@ const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0'
  * on EVM-compatible chains. Use this address for mainnet adapter integrations.
  */
 const ADAPTER_CONTRACT_EVM_MAINNET = '0x7FB8c7260b63934d8da38aF902f87ae6e284a845';
+/**
+ * The adapter contract address for EVM testnet networks.
+ *
+ * This contract serves as an adapter for integrating with various protocols
+ * on EVM-compatible testnet chains. Use this address for testnet adapter
+ * integrations (e.g., Arc Testnet).
+ */
+const ADAPTER_CONTRACT_EVM_TESTNET = '0xBBD70b01a1CAbc96d5b7b129Ae1AAabdf50dd40b';
 
 /**
  * Arc Testnet chain definition
@@ -674,6 +710,7 @@ const ArcTestnet = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+        adapter: ADAPTER_CONTRACT_EVM_TESTNET,
     },
 });
 
@@ -1364,7 +1401,7 @@ const HyperEVM = defineChain({
     },
     chainId: 999,
     isTestnet: false,
-    explorerUrl: 'https://app.hyperliquid.xyz/explorer/tx/{hash}',
+    explorerUrl: 'https://hyperevmscan.io/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
@@ -3329,6 +3366,41 @@ z.union([
         message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
     })),
 ]);
+/**
+ * Zod schema for validating earn-specific chain identifiers.
+ *
+ * Validate that the provided chain is supported for earn (vault
+ * deposit/withdraw) operations. Currently only Ethereum is
+ * supported.
+ *
+ * Accept an EarnChain enum value, a matching string literal, or
+ * a ChainDefinition for a supported chain.
+ *
+ * @example
+ * ```typescript
+ * import { earnChainIdentifierSchema } from '@core/chains'
+ * import { EarnChain, Ethereum } from '@core/chains'
+ *
+ * // Valid
+ * earnChainIdentifierSchema.parse(EarnChain.Ethereum)
+ * earnChainIdentifierSchema.parse('Ethereum')
+ * earnChainIdentifierSchema.parse(Ethereum)
+ *
+ * // Invalid (throws ZodError)
+ * earnChainIdentifierSchema.parse('Solana')
+ * ```
+ */
+z.union([
+    z.string().refine((val) => val in EarnChain, (val) => ({
+        message: `"${val}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+    z.nativeEnum(EarnChain),
+    chainDefinitionSchema$2.refine((chain) => chain.chain in EarnChain, (chain) => ({
+        message: `"${chain.chain}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+]);
 
 /**
  * @packageDocumentation
@@ -4205,6 +4277,12 @@ const InputError = {
         name: 'INPUT_UNSUPPORTED_ACTION',
         type: 'INPUT',
     },
+    /** No route satisfies the slippage or minimum-output constraint */
+    SLIPPAGE_CONSTRAINT_NOT_MET: {
+        code: 1009,
+        name: 'INPUT_SLIPPAGE_CONSTRAINT_NOT_MET',
+        type: 'INPUT',
+    },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
@@ -4268,11 +4346,61 @@ const BalanceError = {
  * ```
  */
 const OnchainError = {
+    /** Transaction reverted on-chain after execution */
+    TRANSACTION_REVERTED: {
+        code: 5001,
+        name: 'ONCHAIN_TRANSACTION_REVERTED',
+        type: 'ONCHAIN',
+    },
     /** Pre-flight transaction simulation failed */
     SIMULATION_FAILED: {
         code: 5002,
         name: 'ONCHAIN_SIMULATION_FAILED',
         type: 'ONCHAIN',
+    },
+    /** Transaction ran out of gas during execution */
+    OUT_OF_GAS: {
+        code: 5003,
+        name: 'ONCHAIN_OUT_OF_GAS',
+        type: 'ONCHAIN',
+    },
+    /** Transaction size exceeds blockchain limit */
+    TRANSACTION_TOO_LARGE: {
+        code: 5005,
+        name: 'ONCHAIN_TRANSACTION_TOO_LARGE',
+        type: 'ONCHAIN',
+    },
+    /** Unknown blockchain error that cannot be categorized */
+    UNKNOWN_BLOCKCHAIN_ERROR: {
+        code: 5099,
+        name: 'ONCHAIN_UNKNOWN_BLOCKCHAIN_ERROR',
+        type: 'ONCHAIN',
+    },
+};
+/**
+ * Standardized error definitions for RPC type errors.
+ *
+ * RPC errors occur when communicating with blockchain RPC providers,
+ * including endpoint failures, invalid responses, and provider-specific issues.
+ *
+ * @example
+ * ```typescript
+ * import { RpcError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...RpcError.ENDPOINT_ERROR,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'RPC endpoint unavailable on Ethereum',
+ *   cause: { trace: { endpoint: 'https://mainnet.infura.io' } }
+ * })
+ * ```
+ */
+const RpcError = {
+    /** RPC endpoint returned error or is unavailable */
+    ENDPOINT_ERROR: {
+        code: 4001,
+        name: 'RPC_ENDPOINT_ERROR',
+        type: 'RPC',
     }};
 /**
  * Standardized error definitions for NETWORK type errors.
@@ -4293,6 +4421,12 @@ const OnchainError = {
  * ```
  */
 const NetworkError = {
+    /** Network connection failed or unreachable */
+    CONNECTION_FAILED: {
+        code: 3001,
+        name: 'NETWORK_CONNECTION_FAILED',
+        type: 'NETWORK',
+    },
     /** Circle relayer failed to process the forwarding/mint transaction */
     RELAYER_FORWARD_FAILED: {
         code: 3003,
@@ -4653,6 +4787,687 @@ function createSimulationFailedError(chain, reason, trace) {
         },
     });
 }
+/**
+ * Creates error for transaction reverts.
+ *
+ * This error is thrown when a transaction is submitted and confirmed
+ * but reverts on-chain. The error is FATAL as it indicates the
+ * transaction executed but failed.
+ *
+ * @param chain - The blockchain network where the transaction reverted
+ * @param reason - The reason for the revert (e.g., revert message)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
+ * @param txHash - The transaction hash if the transaction was submitted (optional)
+ * @param explorerUrl - The block explorer URL for the transaction (optional)
+ * @returns KitError with transaction revert details
+ *
+ * @example
+ * ```typescript
+ * import { createTransactionRevertedError } from '@core/errors'
+ *
+ * throw createTransactionRevertedError('Base', 'Slippage exceeded')
+ * // Message: "Transaction reverted on Base: Slippage exceeded"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context and transaction details for debugging
+ * throw createTransactionRevertedError(
+ *   'Base',
+ *   'Slippage exceeded',
+ *   { rawError: error },
+ *   '0x123...',
+ *   'https://basescan.org/tx/0x123...'
+ * )
+ * ```
+ */
+function createTransactionRevertedError(chain, reason, trace, txHash, explorerUrl) {
+    return new KitError({
+        ...OnchainError.TRANSACTION_REVERTED,
+        recoverability: 'FATAL',
+        message: `Transaction reverted on ${chain}: ${reason}`,
+        cause: {
+            trace: {
+                ...trace,
+                chain,
+                reason,
+                ...(txHash !== undefined && txHash !== '' && { txHash }),
+                ...(explorerUrl !== undefined && explorerUrl !== '' && { explorerUrl }),
+            },
+        },
+    });
+}
+/**
+ * Creates error for out of gas failures.
+ *
+ * This error is thrown when a transaction runs out of gas during execution.
+ * The error is FATAL as it requires adjusting gas limits or transaction logic.
+ *
+ * @param chain - The blockchain network where the transaction ran out of gas
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
+ * @param txHash - The transaction hash if the transaction was submitted (optional)
+ * @param explorerUrl - The block explorer URL for the transaction (optional)
+ * @returns KitError with out of gas details
+ *
+ * @example
+ * ```typescript
+ * import { createOutOfGasError } from '@core/errors'
+ *
+ * throw createOutOfGasError('Polygon')
+ * // Message: "Transaction ran out of gas on Polygon"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createOutOfGasError('Polygon', {
+ *   gasUsed: '50000',
+ *   gasLimit: '45000',
+ * },
+ *  '0xabc...',
+ *   'https://polygonscan.com/tx/0xabc...'
+ * )
+ * ```
+ */
+function createOutOfGasError(chain, trace, txHash, explorerUrl) {
+    return new KitError({
+        ...OnchainError.OUT_OF_GAS,
+        recoverability: 'FATAL',
+        message: `Transaction ran out of gas on ${chain}`,
+        cause: {
+            trace: {
+                ...trace,
+                chain,
+                ...(txHash !== undefined && txHash !== '' && { txHash }),
+                ...(explorerUrl !== undefined && explorerUrl !== '' && { explorerUrl }),
+            },
+        },
+    });
+}
+/**
+ * Creates error for transaction size exceeding blockchain limits.
+ *
+ * This error is thrown when a transaction's serialized size exceeds
+ * the blockchain's maximum transaction size limit. The error is FATAL
+ * as it requires reducing the transaction size (e.g., fewer instructions,
+ * smaller data payloads, or splitting into multiple transactions).
+ *
+ * Common on Solana where transactions have strict size limits (e.g., max 1232 bytes).
+ *
+ * @param chain - The blockchain network where the size limit was exceeded
+ * @param rawError - The original error from the underlying system (optional)
+ * @returns KitError with transaction size exceeded details
+ *
+ * @example
+ * ```typescript
+ * import { createTransactionTooLargeError } from '@core/errors'
+ *
+ * throw createTransactionTooLargeError('Solana')
+ * // Message: "Transaction size exceeds limit on Solana"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createTransactionTooLargeError } from '@core/errors'
+ *
+ * // With raw error containing size details
+ * throw createTransactionTooLargeError(
+ *   'Solana',
+ *   new Error('transaction too large: max: encoded/raw 1644/1232')
+ * )
+ * // Error includes size information in cause.trace
+ * ```
+ */
+function createTransactionTooLargeError(chain, rawError) {
+    return new KitError({
+        ...OnchainError.TRANSACTION_TOO_LARGE,
+        recoverability: 'FATAL',
+        message: `Transaction size exceeds limit on ${chain}`,
+        cause: {
+            trace: {
+                chain,
+                rawError,
+            },
+        },
+    });
+}
+/**
+ * Creates error for unknown blockchain errors that cannot be categorized.
+ *
+ * This error is used as a fallback when a blockchain error doesn't match
+ * any known patterns (balance, simulation, gas, network, RPC, etc.).
+ * The error is FATAL as we cannot determine if it's retriable without
+ * understanding the underlying cause.
+ *
+ * The original error message and context are preserved in the trace for
+ * debugging purposes.
+ *
+ * @param chain - The blockchain network where the error occurred
+ * @param originalMessage - The original error message from the blockchain
+ * @param rawError - The original error object from the underlying system (optional)
+ * @returns KitError with unknown blockchain error details
+ *
+ * @example
+ * ```typescript
+ * import { createUnknownBlockchainError } from '@core/errors'
+ *
+ * throw createUnknownBlockchainError('Ethereum', 'Unknown protocol error')
+ * // Message: "Unknown blockchain error on Ethereum: Unknown protocol error"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createUnknownBlockchainError } from '@core/errors'
+ *
+ * // With raw error for debugging
+ * const rawError = new Error('Unexpected blockchain state')
+ * throw createUnknownBlockchainError('Solana', rawError.message, rawError)
+ * // Error preserves full context in cause.trace
+ * ```
+ */
+function createUnknownBlockchainError(chain, originalMessage, rawError) {
+    const errorMessage = originalMessage
+        ? 'Unknown blockchain error on ' + chain + ': ' + originalMessage
+        : 'Unknown blockchain error on ' + chain;
+    return new KitError({
+        ...OnchainError.UNKNOWN_BLOCKCHAIN_ERROR,
+        recoverability: 'FATAL',
+        message: errorMessage,
+        cause: {
+            trace: {
+                chain,
+                rawError,
+            },
+        },
+    });
+}
+
+/**
+ * Create error for RPC endpoint failures.
+ *
+ * Throw when an RPC provider endpoint fails, returns an error,
+ * or is unavailable. The error is RETRYABLE as RPC issues are often temporary.
+ *
+ * @param chain - The blockchain network where the RPC error occurred.
+ * @param trace - Optional trace context (can include rawError and debugging data).
+ * @returns KitError with RPC endpoint error details.
+ *
+ * @example
+ * ```typescript
+ * import { createRpcEndpointError } from '@core/errors'
+ *
+ * throw createRpcEndpointError('Ethereum')
+ * // Message: "RPC endpoint error on Ethereum"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * throw createRpcEndpointError('Ethereum', {
+ *   rawError: error,
+ *   endpoint: 'https://mainnet.infura.io/v3/...',
+ *   statusCode: 429,
+ * })
+ * ```
+ */
+function createRpcEndpointError(chain, trace) {
+    return new KitError({
+        ...RpcError.ENDPOINT_ERROR,
+        recoverability: 'RETRYABLE',
+        message: `RPC endpoint error on ${chain}`,
+        cause: {
+            trace: {
+                ...trace,
+                chain,
+            },
+        },
+    });
+}
+
+/**
+ * Create error for network connection failures.
+ *
+ * Throw when network connectivity issues prevent reaching
+ * the blockchain network. The error is RETRYABLE as network issues are
+ * often temporary.
+ *
+ * @param chain - The blockchain network where the connection failed.
+ * @param trace - Optional trace context (can include rawError and debugging data).
+ * @returns KitError with network connection error details.
+ *
+ * @example
+ * ```typescript
+ * import { createNetworkConnectionError } from '@core/errors'
+ *
+ * throw createNetworkConnectionError('Ethereum')
+ * // Message: "Network connection failed for Ethereum"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * throw createNetworkConnectionError('Ethereum', {
+ *   rawError: error,
+ *   endpoint: 'https://eth-mainnet.g.alchemy.com/v2/...',
+ *   retryCount: 3,
+ * })
+ * ```
+ */
+function createNetworkConnectionError(chain, trace) {
+    return new KitError({
+        ...NetworkError.CONNECTION_FAILED,
+        recoverability: 'RETRYABLE',
+        message: `Network connection failed for ${chain}`,
+        cause: {
+            trace: {
+                ...trace,
+                chain,
+            },
+        },
+    });
+}
+
+/**
+ * Normalizes optional transaction details for error factories.
+ *
+ * Converts empty strings to undefined to ensure clean error traces.
+ *
+ * @param txHash - The transaction hash.
+ * @param explorerUrl - The explorer URL.
+ * @returns Normalized values or undefined.
+ */
+function normalizeTransactionDetails(txHash, explorerUrl) {
+    const normalized = {};
+    if (txHash !== undefined && txHash !== '') {
+        normalized.txHash = txHash;
+    }
+    if (explorerUrl !== undefined && explorerUrl !== '') {
+        normalized.explorerUrl = explorerUrl;
+    }
+    return normalized;
+}
+/**
+ * Pattern that matches on-chain revert reasons caused by slippage or
+ * price constraints. When a revert matches, the error is surfaced as
+ * {@link InputError.SLIPPAGE_CONSTRAINT_NOT_MET} (RETRYABLE) instead of
+ * a generic simulation-failed / transaction-reverted error.
+ *
+ * @internal
+ */
+const SLIPPAGE_REVERT_PATTERN = /slippage|lower than the minimum required|less than the initial balance|minimum.?output|price.?impact|stop.?limit|InsufficientOutput|InsufficientFinalBalance/i;
+/**
+ * Handle simulation / execution revert errors, distinguishing slippage
+ * constraint failures from generic reverts and simulation failures.
+ *
+ * @internal
+ */
+function handleRevertError(msg, error, context) {
+    const reason = extractRevertReason(msg, error) ?? 'Transaction reverted';
+    if (SLIPPAGE_REVERT_PATTERN.test(reason)) {
+        return new KitError({
+            ...InputError.SLIPPAGE_CONSTRAINT_NOT_MET,
+            recoverability: 'RETRYABLE',
+            message: `Transaction on ${context.chain} reverted: "${reason}". ` +
+                'Try increasing slippageBps or adjusting stopLimit.',
+            cause: { trace: { rawError: error, chain: context.chain, reason } },
+        });
+    }
+    if (/simulation failed/i.test(msg) || context.operation === 'simulation') {
+        return createSimulationFailedError(context.chain, reason, {
+            rawError: error,
+        });
+    }
+    const { txHash, explorerUrl } = normalizeTransactionDetails(context.txHash, context.explorerUrl);
+    return createTransactionRevertedError(context.chain, reason, { rawError: error }, txHash, explorerUrl);
+}
+/**
+ * Parses raw blockchain errors into structured KitError instances.
+ *
+ * This function uses pattern matching to identify common blockchain error
+ * types and converts them into standardized KitError format. It handles
+ * errors from viem, ethers, Solana web3.js, and other blockchain libraries.
+ *
+ * The parser recognizes 6 main error patterns:
+ * 1. Insufficient balance errors
+ * 2. Simulation/execution reverted errors
+ * 3. Gas-related errors
+ * 4. Network connectivity errors
+ * 5. RPC provider errors
+ * 6. Transaction size limit errors
+ *
+ * When errors don't match known patterns, the parser uses operation context
+ * (e.g., 'simulation', 'estimateGas') to categorize them appropriately.
+ * Unrecognized errors without context are categorized as UNKNOWN_BLOCKCHAIN_ERROR.
+ *
+ * @param error - The raw error from the blockchain library
+ * @param context - Context information including chain and optional token
+ * @returns A structured KitError instance
+ *
+ * @example
+ * ```typescript
+ * import { parseBlockchainError } from '@core/errors'
+ *
+ * try {
+ *   await walletClient.sendTransaction(...)
+ * } catch (error) {
+ *   throw parseBlockchainError(error, {
+ *     chain: 'Ethereum',
+ *     token: 'USDC',
+ *     operation: 'transfer'
+ *   })
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Minimal usage
+ * try {
+ *   await connection.sendTransaction(...)
+ * } catch (error) {
+ *   throw parseBlockchainError(error, { chain: 'Solana' })
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With transaction hash and explorer URL
+ * import { buildExplorerUrl } from '@core/utils'
+ * import { Ethereum } from '@core/chains'
+ *
+ * try {
+ *   const txHash = await walletClient.sendTransaction(...)
+ *   await waitForTransaction(txHash)
+ * } catch (error) {
+ *   const explorerUrl = buildExplorerUrl(Ethereum, txHash)
+ *   throw parseBlockchainError(error, {
+ *     chain: 'Ethereum',
+ *     txHash,
+ *     explorerUrl
+ *   })
+ * }
+ * ```
+ */
+function parseBlockchainError(error, context) {
+    const msg = extractMessage(error);
+    const token = context.token ?? 'token';
+    // Pattern 1: Insufficient balance errors
+    // Matches balance-related errors from ERC20 contracts, native transfers, and Solana programs
+    if (/transfer amount exceeds balance|insufficient (balance|funds)|burn amount exceeded/i.test(msg)) {
+        return createInsufficientTokenBalanceError(context.chain, token, {
+            rawError: error,
+        });
+    }
+    // Pattern 2: Simulation and execution reverts
+    // Matches contract revert errors and simulation failures
+    if (/execution reverted|simulation failed|transaction reverted|transaction failed/i.test(msg)) {
+        return handleRevertError(msg, error, context);
+    }
+    // Pattern 3: Gas-related errors
+    // Matches gas estimation failures and gas exhaustion
+    // Check specific patterns first, then generic "gas" patterns
+    // Gas estimation failures are RPC issues
+    if (/gas estimation failed|cannot estimate gas/i.test(msg)) {
+        return createRpcEndpointError(context.chain, { rawError: error });
+    }
+    // Gas exhaustion errors
+    // Use specific patterns without wildcards to avoid ReDoS
+    if (/out of gas|gas limit exceeded|exceeds block gas limit/i.test(msg)) {
+        const { txHash, explorerUrl } = normalizeTransactionDetails(context.txHash, context.explorerUrl);
+        return createOutOfGasError(context.chain, { rawError: error }, txHash, explorerUrl);
+    }
+    // Insufficient funds for gas
+    if (/insufficient funds for gas/i.test(msg)) {
+        return createInsufficientGasError(context.chain, { rawError: error });
+    }
+    // Pattern 4: Network connectivity errors
+    // Matches connection failures, DNS errors, and timeouts
+    if (/connection (refused|failed)|network|timeout|ENOTFOUND|ECONNREFUSED/i.test(msg)) {
+        return createNetworkConnectionError(context.chain, { rawError: error });
+    }
+    // Pattern 5: RPC provider errors
+    // Matches RPC endpoint errors, invalid responses, rate limits, and
+    // transient JSON-RPC internal errors (e.g. ethers.js "could not coalesce error").
+    // Note: "internal error" alone is too broad — contracts like USDT emit
+    // "An internal error was received" for on-chain assertion failures.
+    // We require JSON-RPC context (codes -32603/-32000) instead.
+    if (/rpc|invalid response|rate limit|too many requests|could not coalesce|no response|server error|json-rpc\s+internal|internal json-rpc|-32603|-32000/i.test(msg)) {
+        return createRpcEndpointError(context.chain, { rawError: error });
+    }
+    // Pattern 6: Transaction size limit errors
+    // Matches transaction size errors from various blockchains:
+    // - Solana: "transaction too large: max: encoded/raw 1644/1232"
+    // - Generic: "transaction exceeds size limit", "max transaction size"
+    // Split into two checks to reduce regex complexity for SonarQube
+    const isSizeError = /transaction (?:too large|exceeds size limit|size exceeds)|encoded\/raw\s+\d+\/\d+|max transaction size/i.test(msg) || /(?:tx|transaction) size is too big:\s*\d+,\s*max:\s*\d+/i.test(msg);
+    if (isSizeError) {
+        return createTransactionTooLargeError(context.chain, error);
+    }
+    // Fallback based on operation context
+    // Gas-related operations are RPC calls
+    if (context.operation === 'estimateGas' ||
+        context.operation === 'getGasPrice') {
+        return createRpcEndpointError(context.chain, { rawError: error });
+    }
+    // Simulation operations that don't match standard patterns should still be
+    // categorized as simulation failures. This handles cases where blockchain
+    // libraries throw generic errors (e.g., "fail", "error") during staticCall
+    // operations without descriptive messages. The operation context is authoritative
+    // about what was being attempted, even when error messages are unclear.
+    //
+    // Example: ethers.js staticCall rejection with message "fail"
+    //   - Message doesn't match /execution reverted|simulation failed/
+    //   - But context.operation === 'simulation' tells us it was a simulation
+    //   - Result: SIMULATION_FAILED (accurate) vs UNKNOWN_BLOCKCHAIN_ERROR (misleading)
+    if (context.operation === 'simulation') {
+        return createSimulationFailedError(context.chain, msg.length > 0 ? msg : 'Simulation failed', { rawError: error });
+    }
+    // Final fallback for truly unrecognized errors
+    // Only errors that don't match any pattern AND lack operation context
+    // are categorized as unknown.
+    return createUnknownBlockchainError(context.chain, msg.length > 0 ? msg : 'Unknown error', { rawError: error });
+}
+/**
+ * Type guard to check if error has Solana-Kit structure with logs.
+ *
+ * Checks if the error object contains a context with logs array,
+ * which is the structure used by Solana Kit errors.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error has Solana-Kit logs structure
+ */
+function hasSolanaLogs(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'context' in error &&
+        error.context !== null &&
+        typeof error.context === 'object' &&
+        'logs' in error.context &&
+        Array.isArray(error.context.logs));
+}
+/**
+ * Extracts a human-readable error message from various error types.
+ *
+ * Handles Error objects, string errors, objects with message properties,
+ * Solana-Kit errors with context logs, and falls back to string representation.
+ * For Solana-Kit errors, extracts Anchor error messages from transaction logs.
+ *
+ * @param error - Unknown error to extract message from
+ * @returns Extracted error message string
+ *
+ * @example
+ * ```typescript
+ * const msg1 = extractMessage(new Error('test'))  // 'test'
+ * const msg2 = extractMessage('string error')     // 'string error'
+ * const msg3 = extractMessage({ message: 'obj' }) // 'obj'
+ * ```
+ */
+function extractMessage(error) {
+    // Check for Solana-Kit errors with context.logs
+    if (hasSolanaLogs(error)) {
+        // Extract Anchor error message from logs
+        const anchorLog = error.context.logs.find((log) => log.includes('AnchorError') || log.includes('Error Message'));
+        if (anchorLog !== undefined) {
+            // Return the anchor error log which contains the detailed message
+            return anchorLog;
+        }
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (typeof error === 'object' && error !== null && 'message' in error) {
+        return String(error.message);
+    }
+    return String(error);
+}
+/**
+ * Mapping of custom error selectors to human-readable error names.
+ *
+ * These selectors correspond to custom errors from the contracts.
+ * When a transaction reverts with a custom error, the 4-byte selector
+ * (first 4 bytes of keccak256 of the error signature) is included in the error message.
+ *
+ */
+const CUSTOM_ERROR_SELECTORS = {
+    '0xd93c0665': 'This contract is currently paused', // EnforcedPause()
+    '0x3ee5aeb5': 'Security check failed due to a reentrancy attempt', // ReentrancyGuardReentrantCall()
+    '0x8baa579f': 'The provided signature is invalid or could not be verified', // InvalidSignature()
+    '0x1ab7da6b': 'This request has expired', // DeadlineExpired()
+    '0x64eee62e': 'No instructions provided', // EmptyInstructions()
+    '0x3c46992e': 'Too many execution steps were provided', // TooManyInstructions()
+    '0xe066e60e': 'Exceeds maximum token inputs limit', // TooManyTokenInputs()
+    '0x5566df5c': 'The beneficiary address is invalid', // InvalidBeneficiary()
+    '0xf41d7bc6': 'Execution ID already used', // ExecIdUsed()
+    '0x948726e2': 'The account balance does not meet the required minimum', // InvalidBalanceState()
+    '0x01aa0452': 'The permit type provided is not supported', // UnsupportedPermitType()
+    '0x13be252b': 'Token approval failed and the allowance is insufficient', // InsufficientAllowance()
+    '0x5274afe7': 'Token transfer or approval failed', // SafeERC20FailedOperation(address)
+    '0x00bc1dcb': 'One of the execution targets is invalid', // InvalidInstruction(uint256)
+    '0x5d693841': 'Cannot approve a zero address or a native token', // InvalidApprovalConfig(uint256)
+    '0x3ec5cfe1': 'Cannot validate output for a zero address token', // InvalidOutputConfig(uint256)
+    '0x492fd70e': 'Instruction call failed without revert data', // ExecutionFailed(uint256)
+    '0xba235e1a': 'The received token amount is lower than the minimum required', // InsufficientOutput(uint256,address,uint256,uint256)
+    '0x9147d463': 'Final balance is less than the initial balance', // InsufficientFinalBalance(address,uint256,uint256)
+    '0xf4b3b1bc': 'Native token transfer to the beneficiary failed', // NativeTransferFailed()
+};
+/**
+ * Attempts to extract an error selector from an error object or message.
+ *
+ * Checks multiple sources in priority order:
+ * 1. `error.data` field
+ * 2. Message pattern: "custom error 0x8baa579f"
+ *
+ * @param msg - The error message
+ * @param error - The error object (optional)
+ * @returns The 4 bytes selector , or undefined if not found
+ */
+function extractErrorSelector(msg, error) {
+    // Check error.data field
+    if (error !== null && typeof error === 'object' && 'data' in error) {
+        if (typeof error.data === 'string' && /^0x[0-9a-f]{8}$/i.test(error.data)) {
+            return error.data.toLowerCase();
+        }
+    }
+    // Check for "custom error 0x8baa579f" in the message
+    const match = /custom error (0x[0-9a-f]{8})\b/i.exec(msg);
+    const selector = match?.[1];
+    if (selector !== undefined && selector.length > 0) {
+        return selector.toLowerCase();
+    }
+    return undefined;
+}
+/**
+ * Extracts the revert reason from an error message and error object.
+ *
+ * Attempts to parse out the meaningful reason from execution revert errors,
+ * removing common prefixes like "execution reverted:" or "reverted:".
+ * If the error contains a custom error selector, it will be resolved to its
+ * human-readable description with the selector included for developer reference.
+ *
+ * Supports multiple error formats:
+ * - Custom error with selector in `error.data` field (e.g., `{ data: "0x8baa579f", ... }`)
+ * - Message with selector pattern: `"Execution reverted with reason: custom error 0x8baa579f"`
+ * - Standard revert: `"execution reverted: Insufficient funds"`
+ *
+ * @param msg - The error message to extract from
+ * @param error - The full error object (optional, used to extract selector from `data` field)
+ * @returns The extracted revert reason, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const reason = extractRevertReason(
+ *   'execution reverted: ERC20: transfer amount exceeds balance'
+ * )
+ * // Returns: 'ERC20: transfer amount exceeds balance'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const reason = extractRevertReason(
+ *   'Simulation failed: Execution reverted with reason: Insufficient allowance'
+ * )
+ * // Returns: 'Insufficient allowance'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom error with selector in message
+ * const reason = extractRevertReason(
+ *   'Execution reverted with reason: custom error 0x8baa579f'
+ * )
+ * // Returns: 'The provided signature is invalid or could not be verified (0x8baa579f)'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error with data field
+ * const reason = extractRevertReason(
+ *   'execution reverted (unknown custom error)',
+ *   { data: '0x8baa579f' }
+ * )
+ * // Returns: 'The provided signature is invalid or could not be verified (0x8baa579f)'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Unrecognized selector preserved for debugging
+ * const reason = extractRevertReason(
+ *   'execution reverted (unknown custom error)',
+ *   { data: '0xdeadbeef' }
+ * )
+ * // Returns: 'Transaction reverted with error (0xdeadbeef)'
+ * ```
+ */
+function extractRevertReason(msg, error) {
+    // Try to extract and decode custom error selector
+    const selector = extractErrorSelector(msg, error);
+    if (selector !== undefined) {
+        const errorMessage = CUSTOM_ERROR_SELECTORS[selector];
+        if (errorMessage !== undefined) {
+            return `${errorMessage} (${selector})`;
+        }
+    }
+    // Try to extract reason after "execution reverted:" or "reason:"
+    // Use [^\n.]+ instead of .+? to avoid ReDoS vulnerability
+    // Fall back to standard revert reason extraction
+    const patterns = [
+        /(?:execution reverted|reverted):\s*([^\n.]+)/i,
+        /reason:\s*([^\n.]+)/i,
+        /with reason:\s*([^\n.]+)/i,
+    ];
+    for (const pattern of patterns) {
+        const match = pattern.exec(msg);
+        const extractedReason = match?.at(1);
+        if (extractedReason !== undefined && extractedReason.length > 0) {
+            return extractedReason.trim();
+        }
+    }
+    // Preserve unrecognized selector so it appears in error output for debugging
+    if (selector !== undefined) {
+        return `Transaction reverted with error (${selector})`;
+    }
+    return null;
+}
 
 /**
  * Type guard to check if an error is a KitError instance.
@@ -4710,6 +5525,102 @@ function isKitError(error) {
 function isFatalError(error) {
     return isKitError(error) && error.recoverability === 'FATAL';
 }
+/**
+ * Error codes that are considered retryable by default.
+ *
+ * @remarks
+ * These are typically transient errors that may succeed on retry:
+ * - Network connectivity issues (3001, 3002)
+ * - Provider unavailability (4001, 4002)
+ * - RPC nonce errors (4003)
+ */
+const DEFAULT_RETRYABLE_ERROR_CODES = [
+    // Network errors
+    3001, // NETWORK_CONNECTION_FAILED
+    3002, // NETWORK_TIMEOUT
+    // Provider errors
+    4001, // PROVIDER_UNAVAILABLE
+    4002, // PROVIDER_TIMEOUT
+    4003, // RPC_NONCE_ERROR
+];
+/**
+ * Checks if an error is retryable.
+ *
+ * @remarks
+ * Check order for KitError instances:
+ * 1. If `recoverability === 'RETRYABLE'`, return `true` immediately (priority check).
+ * 2. Otherwise, check if `error.code` is in `DEFAULT_RETRYABLE_ERROR_CODES` (fallback check).
+ * 3. Non-KitError instances always return `false`.
+ *
+ * This two-tier approach allows both explicit recoverability control and
+ * backward-compatible code-based retry logic.
+ *
+ * RETRYABLE errors indicate transient failures that may succeed on
+ * subsequent attempts, such as network timeouts or temporary service
+ * unavailability. These errors are safe to retry after a delay.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is retryable
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isRetryableError(error)) {
+ *     // Implement retry logic with exponential backoff
+ *     setTimeout(() => retryOperation(), 5000)
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError, createNetworkConnectionError, KitError } from '@core/errors'
+ *
+ * // KitError with RETRYABLE recoverability (priority check)
+ * const error1 = createNetworkConnectionError('Ethereum')
+ * isRetryableError(error1) // true
+ *
+ * // KitError with default retryable code (fallback check)
+ * const error2 = new KitError({
+ *   code: 3002, // NETWORK_TIMEOUT - in DEFAULT_RETRYABLE_ERROR_CODES
+ *   name: 'NETWORK_TIMEOUT',
+ *   type: 'NETWORK',
+ *   recoverability: 'FATAL', // Not RETRYABLE
+ *   message: 'Timeout',
+ * })
+ * isRetryableError(error2) // true (code 3002 is in default list)
+ *
+ * // KitError with non-retryable code and FATAL recoverability
+ * const error3 = new KitError({
+ *   code: 1001,
+ *   name: 'INPUT_NETWORK_MISMATCH',
+ *   type: 'INPUT',
+ *   recoverability: 'FATAL',
+ *   message: 'Invalid input',
+ * })
+ * isRetryableError(error3) // false
+ *
+ * // Non-KitError
+ * const error4 = new Error('Standard error')
+ * isRetryableError(error4) // false
+ * ```
+ */
+function isRetryableError$1(error) {
+    // Use proper type guard to check if it's a KitError
+    if (isKitError(error)) {
+        // Priority check: explicit recoverability
+        if (error.recoverability === 'RETRYABLE') {
+            return true;
+        }
+        // Fallback check: error code against default retryable codes
+        return DEFAULT_RETRYABLE_ERROR_CODES.includes(error.code);
+    }
+    return false;
+}
 /**
  * Safely extracts error message from any error type.
  *
@@ -5088,8 +5999,15 @@ const pollApiWithValidation = async (url, method, isValidType, config = {}, body
             }
         }
     }
-    // After the loop: we're guaranteed to have a lastError
-    throw new Error(`Maximum retry attempts (${String(effectiveConfig.maxRetries)}) exceeded: ${String(lastError?.message)}`);
+    // Preserve responseBody from the last attempt so upstream parsers
+    // (e.g. parseApiError) can inspect the server's structured response.
+    const retryError = new Error(`Maximum retry attempts (${String(effectiveConfig.maxRetries)}) exceeded: ${String(lastError?.message)}`);
+    if (lastError !== undefined &&
+        'responseBody' in lastError &&
+        lastError.responseBody !== undefined) {
+        retryError.responseBody = lastError.responseBody;
+    }
+    throw retryError;
 };
 /**
  * Convenience function for making GET requests with validation.
@@ -5630,6 +6548,7 @@ const USDC = {
         // =========================================================================
         // Testnets (alphabetically sorted)
         // =========================================================================
+        [Blockchain.Arc_Testnet]: '0x3600000000000000000000000000000000000000',
         [Blockchain.Arbitrum_Sepolia]: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
         [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
         [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
@@ -5706,6 +6625,8 @@ const EURC = {
         [Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
         [Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
         [Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
+        // Testnets
+        [Blockchain.Arc_Testnet]: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
     },
 };
 
@@ -6396,6 +7317,86 @@ function buildForwardingHookData() {
     return cachedHookDataHex;
 }
 
+const DEFAULTS = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 15_000,
+    deadlineMs: undefined,
+    jitter: true,
+    isRetryable: () => true,
+};
+function resolveOptions(options) {
+    if (options === undefined)
+        return DEFAULTS;
+    return {
+        maxRetries: options.maxRetries ?? DEFAULTS.maxRetries,
+        baseDelayMs: options.baseDelayMs ?? DEFAULTS.baseDelayMs,
+        maxDelayMs: options.maxDelayMs ?? DEFAULTS.maxDelayMs,
+        deadlineMs: options.deadlineMs ?? DEFAULTS.deadlineMs,
+        jitter: options.jitter ?? DEFAULTS.jitter,
+        isRetryable: options.isRetryable ?? DEFAULTS.isRetryable,
+    };
+}
+/**
+ * Calculate exponential backoff delay with optional jitter.
+ *
+ * @param attempt - 1-indexed retry attempt number.
+ * @param config - Resolved retry configuration.
+ * @returns Delay in milliseconds.
+ */
+function calculateDelay(attempt, config) {
+    let delay = config.baseDelayMs * Math.pow(2, attempt - 1);
+    delay = Math.min(delay, config.maxDelayMs);
+    if (config.jitter) {
+        const jitterFactor = 0.75 + Math.random() * 0.5; // NOSONAR - not security-sensitive
+        delay = Math.round(delay * jitterFactor);
+    }
+    return delay;
+}
+/**
+ * Retry an async function with exponential backoff and jitter.
+ *
+ * This is a lightweight standalone utility with no `@core/runtime`
+ * dependency, suitable for use in adapters and providers that do not
+ * participate in the middleware pipeline.
+ *
+ * @typeParam T - The resolved value type.
+ * @param fn - The async function to execute (and potentially retry).
+ * @param options - Retry configuration.
+ * @returns The resolved value of `fn`.
+ * @throws The last error when all retry attempts are exhausted, or
+ *   immediately when `isRetryable` returns `false`.
+ *
+ * @example
+ * ```typescript
+ * import { retryAsync } from '@core/utils'
+ *
+ * const receipt = await retryAsync(
+ *   () => adapter.waitForTransaction(txHash, { confirmations: 1 }, chain),
+ *   { maxRetries: 3, isRetryable: (err) => isTransientRpcError(err) },
+ * )
+ * ```
+ */
+async function retryAsync(fn, options) {
+    const config = resolveOptions(options);
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const pastDeadline = config.deadlineMs !== undefined && Date.now() >= config.deadlineMs;
+            const isLastAttempt = attempt >= config.maxRetries;
+            if (isLastAttempt || pastDeadline || !config.isRetryable(error)) {
+                throw error;
+            }
+            const delayMs = calculateDelay(attempt + 1, config);
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    /* istanbul ignore next: unreachable safety throw for TypeScript */
+    throw new Error('retryAsync: unreachable');
+}
+
 /**
  * Transfer speed options for cross-chain operations.
  *
@@ -8045,10 +9046,13 @@ async function executePreparedChainRequest({ name, request, adapter, chain, conf
         }
         const txHash = await request.execute();
         step.txHash = txHash;
-        const transaction = await adapter.waitForTransaction(txHash, {
-            confirmations,
-            timeout,
-        }, chain);
+        const retryOptions = {
+            isRetryable: (err) => isRetryableError$1(parseBlockchainError(err, { chain: chain.name, txHash })),
+        };
+        if (timeout !== undefined) {
+            retryOptions.deadlineMs = Date.now() + timeout;
+        }
+        const transaction = await retryAsync(async () => adapter.waitForTransaction(txHash, { confirmations, timeout }, chain), retryOptions);
         step.state = transaction.blockNumber ? 'success' : 'error';
         step.data = transaction;
         // Generate explorer URL for the step
@@ -9663,7 +10667,12 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
         return step;
     }
     try {
-        const transaction = await adapter.waitForTransaction(receipt.txHash, { confirmations: 1 }, chain);
+        const transaction = await retryAsync(async () => adapter.waitForTransaction(receipt.txHash, { confirmations: 1 }, chain), {
+            isRetryable: (err) => isRetryableError$1(parseBlockchainError(err, {
+                chain: chain.name,
+                txHash: receipt.txHash,
+            })),
+        });
         step.state = transaction.blockNumber === undefined ? 'error' : 'success';
         step.data = transaction;
         if (transaction.blockNumber === undefined) {
@@ -9679,7 +10688,7 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
     return step;
 }
 
-var version = "1.6.1";
+var version = "1.6.2";
 var pkg = {
 	version: version};
 
@@ -10795,7 +11804,10 @@ async function waitForPendingTransaction(pendingStep, adapter, chain) {
             message: `Cannot wait for pending ${pendingStep.name}: no transaction hash available`,
         });
     }
-    const txReceipt = await adapter.waitForTransaction(pendingStep.txHash, undefined, chain);
+    const txHash = pendingStep.txHash;
+    const txReceipt = await retryAsync(async () => adapter.waitForTransaction(txHash, undefined, chain), {
+        isRetryable: (err) => isRetryableError$1(parseBlockchainError(err, { chain: chain.name, txHash })),
+    });
     // Check if transaction was confirmed on-chain
     if (!txReceipt.blockNumber) {
         return {