@circle-fin/adapter-ethers-v6 1.3.0 → 1.5.0

package/index.mjs

@@ -80,6 +80,8 @@ const ERROR_TYPES = {
     RPC: 'RPC',
     /** Internet connectivity, DNS resolution, connection issues */
     NETWORK: 'NETWORK',
+    /** Catch-all for unrecognized errors (code 0) */
+    UNKNOWN: 'UNKNOWN',
 };
 /**
  * Array of valid error type values for validation.
@@ -93,6 +95,8 @@ const ERROR_TYPE_ARRAY = [...ERROR_TYPE_VALUES];
 /**
  * Error code ranges for validation.
  * Single source of truth for valid error code ranges.
+ *
+ * Note: Code 0 is special - it's the UNKNOWN catch-all error.
  */
 const ERROR_CODE_RANGES = [
     { min: 1000, max: 1999, type: 'INPUT' },
@@ -101,6 +105,8 @@ const ERROR_CODE_RANGES = [
     { min: 5000, max: 5999, type: 'ONCHAIN' },
     { min: 9000, max: 9999, type: 'BALANCE' },
 ];
+/** Special code for UNKNOWN errors */
+const UNKNOWN_ERROR_CODE = 0;
 /**
  * Zod schema for validating ErrorDetails objects.
  *
@@ -139,6 +145,7 @@ const ERROR_CODE_RANGES = [
 const errorDetailsSchema = z.object({
     /**
      * Numeric identifier following standardized ranges:
+     * - 0: UNKNOWN - Catch-all for unrecognized errors
      * - 1000-1999: INPUT errors - Parameter validation
      * - 3000-3999: NETWORK errors - Connectivity issues
      * - 4000-4999: RPC errors - Provider issues, gas estimation
@@ -148,8 +155,9 @@ const errorDetailsSchema = z.object({
     code: z
         .number()
         .int('Error code must be an integer')
-        .refine((code) => ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
-        message: 'Error code must be in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
+        .refine((code) => code === UNKNOWN_ERROR_CODE ||
+        ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
+        message: 'Error code must be 0 (UNKNOWN) or in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
     }),
     /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
     name: z
@@ -159,7 +167,7 @@ const errorDetailsSchema = z.object({
     /** Error category indicating where the error originated */
     type: z.enum(ERROR_TYPE_ARRAY, {
         errorMap: () => ({
-            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK',
+            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK, UNKNOWN',
         }),
     }),
     /** Error handling strategy */
@@ -342,6 +350,7 @@ class KitError extends Error {
 /**
  * Standardized error code ranges for consistent categorization:
  *
+ * - 0: UNKNOWN - Catch-all for unrecognized errors
  * - 1000-1999: INPUT errors - Parameter validation, input format errors
  * - 3000-3999: NETWORK errors - Internet connectivity, DNS, connection issues
  * - 4000-4999: RPC errors - Blockchain provider issues, gas estimation, nonce errors
@@ -537,6 +546,53 @@ function createInvalidChainError(chain, reason) {
     };
     return new KitError(errorDetails);
 }
+/**
+ * Creates error for general validation failure.
+ *
+ * This error is thrown when input validation fails for reasons not covered
+ * by more specific error types.
+ *
+ * @param field - The field that failed validation
+ * @param value - The invalid value (can be any type)
+ * @param reason - Specific reason why validation failed
+ * @returns KitError with validation details
+ *
+ * @example
+ * ```typescript
+ * import { createValidationFailedError } from '@core/errors'
+ *
+ * throw createValidationFailedError('recipient', 'invalid@email', 'Must be a valid wallet address')
+ * // Message: "Validation failed for 'recipient': 'invalid@email' - Must be a valid wallet address"
+ *
+ * throw createValidationFailedError('chainId', 999, 'Unsupported chain ID')
+ * // Message: "Validation failed for 'chainId': 999 - Unsupported chain ID"
+ *
+ * throw createValidationFailedError('config', { invalid: true }, 'Missing required properties')
+ * // Message: "Validation failed for 'config': [object Object] - Missing required properties"
+ * ```
+ */
+function createValidationFailedError(field, value, reason) {
+    // Convert value to string for display, handling different types appropriately
+    let valueString;
+    if (typeof value === 'string') {
+        valueString = `'${value}'`;
+    }
+    else if (typeof value === 'object' && value !== null) {
+        valueString = JSON.stringify(value);
+    }
+    else {
+        valueString = String(value);
+    }
+    const errorDetails = {
+        ...InputError.VALIDATION_FAILED,
+        recoverability: 'FATAL',
+        message: `Validation failed for '${field}': ${valueString} - ${reason}.`,
+        cause: {
+            trace: { field, value, reason },
+        },
+    };
+    return new KitError(errorDetails);
+}
 /**
  * Creates a KitError from a Zod validation error with detailed error information.
  *
@@ -1163,6 +1219,8 @@ var Blockchain;
     Blockchain["Ink_Testnet"] = "Ink_Testnet";
     Blockchain["Linea"] = "Linea";
     Blockchain["Linea_Sepolia"] = "Linea_Sepolia";
+    Blockchain["Monad"] = "Monad";
+    Blockchain["Monad_Testnet"] = "Monad_Testnet";
     Blockchain["NEAR"] = "NEAR";
     Blockchain["NEAR_Testnet"] = "NEAR_Testnet";
     Blockchain["Noble"] = "Noble";
@@ -1254,6 +1312,7 @@ var BridgeChain;
     BridgeChain["HyperEVM"] = "HyperEVM";
     BridgeChain["Ink"] = "Ink";
     BridgeChain["Linea"] = "Linea";
+    BridgeChain["Monad"] = "Monad";
     BridgeChain["Optimism"] = "Optimism";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
@@ -1273,6 +1332,7 @@ var BridgeChain;
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
     BridgeChain["Ink_Testnet"] = "Ink_Testnet";
     BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
+    BridgeChain["Monad_Testnet"] = "Monad_Testnet";
     BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
     BridgeChain["Plume_Testnet"] = "Plume_Testnet";
     BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
@@ -1399,6 +1459,10 @@ const Aptos = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -1432,6 +1496,10 @@ const AptosTestnet = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -1491,6 +1559,10 @@ const ArcTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1535,6 +1607,10 @@ const Arbitrum = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1579,6 +1655,10 @@ const ArbitrumSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1623,6 +1703,10 @@ const Avalanche = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1666,6 +1750,10 @@ const AvalancheFuji = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     rpcEndpoints: ['https://api.avax-test.network/ext/bc/C/rpc'],
     kitContracts: {
@@ -1711,6 +1799,10 @@ const Base = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1755,6 +1847,10 @@ const BaseSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1841,6 +1937,10 @@ const Codex = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1879,6 +1979,10 @@ const CodexTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1923,6 +2027,10 @@ const Ethereum = defineChain({
                 fastConfirmations: 2,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1967,6 +2075,10 @@ const EthereumSepolia = defineChain({
                 fastConfirmations: 2,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2053,6 +2165,10 @@ const HyperEVM = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2092,6 +2208,10 @@ const HyperEVMTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2135,6 +2255,10 @@ const Ink = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2177,6 +2301,10 @@ const InkTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2215,6 +2343,10 @@ const Linea = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2253,6 +2385,98 @@ const LineaSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Monad Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Monad blockchain.
+ * Monad is a high-performance EVM-compatible Layer-1 blockchain featuring
+ * over 10,000 TPS, sub-second finality, and near-zero gas fees.
+ */
+const Monad = defineChain({
+    type: 'evm',
+    chain: Blockchain.Monad,
+    name: 'Monad',
+    title: 'Monad Mainnet',
+    nativeCurrency: {
+        name: 'Monad',
+        symbol: 'MON',
+        decimals: 18,
+    },
+    chainId: 143,
+    isTestnet: false,
+    explorerUrl: 'https://monadscan.com/tx/{hash}',
+    rpcEndpoints: ['https://rpc.monad.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
+    cctp: {
+        domain: 15,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Monad Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Monad blockchain.
+ * Monad is a high-performance EVM-compatible Layer-1 blockchain featuring
+ * over 10,000 TPS, sub-second finality, and near-zero gas fees.
+ */
+const MonadTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Monad_Testnet,
+    name: 'Monad Testnet',
+    title: 'Monad Testnet',
+    nativeCurrency: {
+        name: 'Monad',
+        symbol: 'MON',
+        decimals: 18,
+    },
+    chainId: 10143,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.monadscan.com/tx/{hash}',
+    rpcEndpoints: ['https://testnet-rpc.monad.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
+    cctp: {
+        domain: 15,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2334,6 +2558,10 @@ const Noble = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -2366,6 +2594,10 @@ const NobleTestnet = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -2407,6 +2639,10 @@ const Optimism = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2451,6 +2687,10 @@ const OptimismSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2491,6 +2731,10 @@ const Plume = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2530,6 +2774,10 @@ const PlumeTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2620,6 +2868,10 @@ const Polygon = defineChain({
                 fastConfirmations: 13,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2664,6 +2916,10 @@ const PolygonAmoy = defineChain({
                 fastConfirmations: 13,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2704,6 +2960,10 @@ const Sei = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2743,6 +3003,10 @@ const SeiTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2781,6 +3045,10 @@ const Sonic = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2819,6 +3087,10 @@ const SonicTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2862,6 +3134,10 @@ const Solana = defineChain({
                 fastConfirmations: 3,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
@@ -2904,6 +3180,10 @@ const SolanaDevnet = defineChain({
                 fastConfirmations: 3,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
@@ -2987,6 +3267,10 @@ const Sui = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -3020,6 +3304,10 @@ const SuiTestnet = defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -3041,7 +3329,7 @@ const Unichain = defineChain({
     chainId: 130,
     isTestnet: false,
     explorerUrl: 'https://unichain.blockscout.com/tx/{hash}',
-    rpcEndpoints: ['https://rpc.unichain.org', 'https://mainnet.unichain.org'],
+    rpcEndpoints: ['https://mainnet.unichain.org'],
     eurcAddress: null,
     usdcAddress: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
     cctp: {
@@ -3061,6 +3349,10 @@ const Unichain = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -3105,6 +3397,10 @@ const UnichainSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -3131,7 +3427,7 @@ const WorldChain = defineChain({
     explorerUrl: 'https://worldscan.org/tx/{hash}',
     rpcEndpoints: ['https://worldchain-mainnet.g.alchemy.com/public'],
     eurcAddress: null,
-    usdcAddress: '0x79A02482A880bCe3F13E09da970dC34dB4cD24D1',
+    usdcAddress: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
     cctp: {
         domain: 14,
         contracts: {
@@ -3143,6 +3439,10 @@ const WorldChain = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -3184,6 +3484,10 @@ const WorldChainSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -3210,7 +3514,7 @@ const XDC = defineChain({
     chainId: 50,
     isTestnet: false,
     explorerUrl: 'https://xdcscan.io/tx/{hash}',
-    rpcEndpoints: ['https://erpc.xinfin.network'],
+    rpcEndpoints: ['https://erpc.xdcrpc.com', 'https://erpc.xinfin.network'],
     eurcAddress: null,
     usdcAddress: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
     cctp: {
@@ -3224,6 +3528,10 @@ const XDC = defineChain({
                 fastConfirmations: 3,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -3262,6 +3570,10 @@ const XDCApothem = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -3343,6 +3655,8 @@ var Blockchains = /*#__PURE__*/Object.freeze({
     InkTestnet: InkTestnet,
     Linea: Linea,
     LineaSepolia: LineaSepolia,
+    Monad: Monad,
+    MonadTestnet: MonadTestnet,
     NEAR: NEAR,
     NEARTestnet: NEARTestnet,
     Noble: Noble,
@@ -4371,9 +4685,8 @@ const transactionHashSchema = z
     required_error: 'Transaction hash is required',
     invalid_type_error: 'Transaction hash must be a string',
 })
-    .min(1, 'Transaction hash cannot be empty')
-    .transform((hash) => hash.trim()) // Automatically trim whitespace
-    .refine((hash) => hash.length > 0, 'Transaction hash must not be empty or whitespace-only');
+    .transform((hash) => hash.trim())
+    .refine((hash) => hash.length > 0, 'Transaction hash cannot be empty');
 /**
  * Zod schema for validating buildExplorerUrl function parameters.
  * This schema validates both the chain definition and transaction hash together.
@@ -8289,28 +8602,79 @@ const bridgeContractAbi = [
 const ZERO_HASH = '0x0000000000000000000000000000000000000000000000000000000000000000';
 
 /**
- * Prepares an EVM-compatible `depositForBurn` transaction for CCTP v2.
+ * Prepare an EVM-compatible deposit for burn transaction for CCTP v2.
  *
- * This function creates a prepared chain request for burning USDC tokens on the source EVM chain
- * to initiate a cross-chain transfer using Circle's CCTP v2 protocol. It leverages the adapter's
- * chain context and transaction preparation utilities to construct a transaction targeting the
- * TokenMessengerV2 contract.
+ * This is the shared implementation for both `depositForBurn` and `depositForBurnWithHook` actions.
+ * It creates a prepared chain request for burning USDC tokens on the source EVM chain to initiate
+ * a cross-chain transfer using Circle's CCTP v2 protocol.
  *
- * The function validates that the `fromChain` is EVM-compatible, then constructs a transaction
- * using the canonical TokenMessengerV2 ABI and the resolved contract address for the source chain.
- * The resulting prepared request can be executed or simulated by the caller.
+ * The function automatically selects the appropriate contract method based on whether hookData
+ * is present:
+ * - Without hookData → `depositForBurn`
+ * - With hookData → `depositForBurnWithHook`
+ *
+ * @param params - The action payload (either depositForBurn or depositForBurnWithHook params).
+ * @param adapter - The EVM adapter responsible for chain context and transaction preparation.
+ * @param context - The resolved operation context providing chain and address information.
+ * @returns A promise that resolves to a prepared chain request.
+ * @throws KitError if the `fromChain` is not EVM-compatible.
+ * @throws KitError if `hookData` is provided but is not a valid hex string.
+ *
+ * @internal This function is used internally by depositForBurn and depositForBurnWithHook wrappers.
+ */
+const prepareDepositForBurn = async (params, adapter, context) => {
+    if (params.fromChain.type !== 'evm') {
+        throw createInvalidChainError(params.fromChain.name, `Expected EVM chain but received chain type: ${params.fromChain.type}`);
+    }
+    // Detect if hookData is present (depositForBurnWithHook action)
+    const hookData = 'hookData' in params ? params.hookData : undefined;
+    // Build args array - base args are the same for both variants
+    const args = [
+        params.amount,
+        params.toChain.cctp.domain,
+        convertAddress(params.mintRecipient, 'bytes32'),
+        params.fromChain.usdcAddress,
+        params.destinationCaller ?? ZERO_HASH,
+        params.maxFee,
+        params.minFinalityThreshold,
+    ];
+    const hasHookData = hookData !== undefined && hookData !== '';
+    // Add hookData as the last argument if present, after validating format
+    if (hasHookData) {
+        const result = hexStringSchema.safeParse(hookData);
+        if (!result.success) {
+            throw createValidationFailedError('hookData', hookData, 'Must be a valid hex string starting with 0x');
+        }
+        args.push(hookData);
+    }
+    // Select function name based on hookData presence
+    const functionName = hasHookData ? 'depositForBurnWithHook' : 'depositForBurn';
+    return adapter.prepare({
+        type: 'evm',
+        abi: tokenMessengerV2Abi,
+        address: resolveCCTPV2ContractAddress(params.fromChain, 'tokenMessenger'),
+        functionName,
+        args,
+    }, context);
+};
+
+/**
+ * Prepare an EVM-compatible `depositForBurn` transaction for CCTP v2.
+ *
+ * This function creates a prepared chain request for burning USDC tokens on the source EVM chain
+ * to initiate a cross-chain transfer using Circle's CCTP v2 protocol.
  *
  * @param params - The action payload containing:
  *   - `fromChain`: The EVM chain definition where the burn will occur.
  *   - `toChain`: The destination chain definition (must include CCTP domain).
- *   - `amount`: The amount of USDC to burn (as a string, in the smallest unit).
- *   - `mintRecipient`: The address (as string) to receive minted USDC on the destination chain.
+ *   - `amount`: The amount of USDC to burn (as bigint, in the smallest unit).
+ *   - `mintRecipient`: The address to receive minted USDC on the destination chain.
  *   - `maxFee`: The maximum fee to pay for the cross-chain message relay.
  *   - `minFinalityThreshold`: The minimum finality threshold for the burn event.
  * @param adapter - The EVM adapter responsible for chain context and transaction preparation.
  * @param context - The resolved operation context providing chain and address information.
  * @returns A promise that resolves to a prepared chain request for the `depositForBurn` call.
- * @throws Error if the `fromChain` is not EVM-compatible or if preparation fails.
+ * @throws KitError if the `fromChain` is not EVM-compatible or if preparation fails.
  *
  * @example
  * ```typescript
@@ -8318,37 +8682,63 @@ const ZERO_HASH = '0x00000000000000000000000000000000000000000000000000000000000
  *   {
  *     fromChain,
  *     toChain,
- *     amount: '1000000',
+ *     amount: 1000000n,
  *     mintRecipient: '0xabc...',
  *     maxFee: 0n,
- *     minFinalityThreshold: 1n,
+ *     minFinalityThreshold: 1000,
  *   },
  *   adapter,
  *   context
- * );
- * await prepared.execute();
+ * )
+ * await prepared.execute()
  * ```
  */
 const depositForBurn = async (params, adapter, context) => {
-    if (params.fromChain.type !== 'evm') {
-        throw new Error(`Expected fromChain to be EVM chain definition, but received chain type: ${params.fromChain.type}`);
-    }
-    // Prepare the deposit for burn transaction
-    return adapter.prepare({
-        type: 'evm',
-        abi: tokenMessengerV2Abi,
-        address: resolveCCTPV2ContractAddress(params.fromChain, 'tokenMessenger'),
-        functionName: 'depositForBurn',
-        args: [
-            BigInt(params.amount),
-            params.toChain.cctp.domain,
-            convertAddress(params.mintRecipient, 'bytes32'),
-            params.fromChain.usdcAddress,
-            params.destinationCaller ?? ZERO_HASH, // destinationCaller as ZeroHash (allows any caller) if not provided
-            params.maxFee,
-            params.minFinalityThreshold,
-        ],
-    }, context);
+    return prepareDepositForBurn(params, adapter, context);
+};
+
+/**
+ * Prepare an EVM-compatible `depositForBurnWithHook` transaction for CCTP v2 forwarding.
+ *
+ * This function creates a prepared chain request for burning USDC tokens on the source EVM chain
+ * with hook data that signals to Circle's Orbit relayer that forwarding is requested. The relayer
+ * will automatically fetch the attestation and submit the destination mint transaction.
+ *
+ * @param params - The action payload containing:
+ *   - `fromChain`: The EVM chain definition where the burn will occur.
+ *   - `toChain`: The destination chain definition (must include CCTP domain).
+ *   - `amount`: The amount of USDC to burn (as bigint, in the smallest unit).
+ *   - `mintRecipient`: The address to receive minted USDC on the destination chain.
+ *   - `maxFee`: The maximum fee to pay (must cover burn fee + forwarding fee).
+ *   - `minFinalityThreshold`: The minimum finality threshold for the burn event.
+ *   - `hookData`: Hex-encoded hook data for CCTP forwarding.
+ * @param adapter - The EVM adapter responsible for chain context and transaction preparation.
+ * @param context - The resolved operation context providing chain and address information.
+ * @returns A promise that resolves to a prepared chain request for the `depositForBurnWithHook` call.
+ * @throws KitError if the `fromChain` is not EVM-compatible or if preparation fails.
+ *
+ * @example
+ * ```typescript
+ * import { buildForwardingHookData } from '@core/utils'
+ *
+ * const prepared = await depositForBurnWithHook(
+ *   {
+ *     fromChain,
+ *     toChain,
+ *     amount: 1000000n,
+ *     mintRecipient: '0xabc...',
+ *     maxFee: 50000n,
+ *     minFinalityThreshold: 1000,
+ *     hookData: buildForwardingHookData(),
+ *   },
+ *   adapter,
+ *   context
+ * )
+ * await prepared.execute()
+ * ```
+ */
+const depositForBurnWithHook = async (params, adapter, context) => {
+    return prepareDepositForBurn(params, adapter, context);
 };
 
 /**
@@ -8399,8 +8789,317 @@ const receiveMessage = async (params, adapter, context) => {
     }, context);
 };
 
+// ============================================================================
+// Validation Helper Functions
+// ============================================================================
+/**
+ * Validate that the source chain is EVM-compatible and supports custom bridge contracts.
+ *
+ * Custom bridge contracts are Circle's kit-specific contracts that provide
+ * additional functionality beyond the standard CCTP TokenMessenger, such as:
+ * - Permit-based gasless approvals (EIP-2612)
+ * - Protocol fee collection
+ * - Hook data for automatic forwarding
+ *
+ * Not all chains have custom bridge contracts deployed. For chains without
+ * custom bridge support, users should use `cctp.v2.depositForBurn` instead,
+ * which interacts directly with Circle's TokenMessenger contract.
+ *
+ * @param params - The custom burn parameters containing chain definitions.
+ * @throws KitError if the source chain is not EVM (e.g., Solana).
+ * @throws KitError if the chain doesn't have a custom bridge contract deployed.
+ */
+function validateChainSupport(params) {
+    // Ensure source chain is EVM - Solana uses a different code path
+    if (params.fromChain.type !== 'evm') {
+        throw createInvalidChainError(params.fromChain.name, `Expected EVM chain but received chain type: ${params.fromChain.type}`);
+    }
+    // Check if the chain has a custom bridge contract in its configuration
+    if (!hasCustomContractSupport(params.fromChain, 'bridge')) {
+        throw createInvalidChainError(params.fromChain.name, "Chain does not support custom bridge contracts. Use 'cctp.v2.depositForBurn' instead.");
+    }
+}
+/**
+ * Validate the logical consistency of protocol fee parameters.
+ *
+ * The protocol fee mechanism allows integrators to collect a fee on each
+ * cross-chain transfer. When enabled, the fee is deducted from the transfer
+ * amount and sent to the specified fee recipient.
+ *
+ * Business rules:
+ * - protocolFee MUST be non-negative
+ * - If protocolFee is non-zero, feeRecipient MUST be specified (where does the fee go?)
+ * - If feeRecipient is specified, protocolFee MUST be non-zero (why specify recipient for zero fee?)
+ * - When feeRecipient is provided, it must be a valid EVM address
+ *
+ * @param protocolFee - The fee amount (defaults to 0n if not provided).
+ * @param feeRecipient - The address to receive the fee (optional).
+ * @throws KitError if protocolFee is negative.
+ * @throws KitError if protocolFee is set but feeRecipient is missing.
+ * @throws KitError if feeRecipient is set but protocolFee is zero.
+ * @throws KitError if feeRecipient is not a valid EVM address.
+ */
+function validateProtocolFeeParams(protocolFee, feeRecipient) {
+    // Validate: fee must be non-negative
+    if (protocolFee < 0n) {
+        throw createValidationFailedError('protocolFee', protocolFee, 'Must be non-negative');
+    }
+    // Validate: fee without recipient makes no sense
+    if (protocolFee > 0n && feeRecipient === undefined) {
+        throw createValidationFailedError('protocolFee', protocolFee, 'Requires feeRecipient. Specify where the fee should be sent');
+    }
+    // Validate: recipient without fee makes no sense
+    if (feeRecipient !== undefined && protocolFee === 0n) {
+        throw createValidationFailedError('feeRecipient', feeRecipient, 'Requires non-zero protocolFee. Specify the fee amount to send');
+    }
+    // Validate the fee recipient address format if provided
+    if (feeRecipient !== undefined) {
+        assertEvmAddress(feeRecipient);
+    }
+}
+/**
+ * Validate EIP-2612 permit signature components if provided.
+ *
+ * EIP-2612 permits allow gasless token approvals via off-chain signatures.
+ * Instead of the user calling `approve()` on the USDC contract (which costs gas),
+ * they sign a message off-chain, and the bridge contract calls `permit()` on
+ * their behalf as part of the bridge transaction.
+ *
+ * The permit signature consists of:
+ * - `deadline`: Unix timestamp after which the permit expires
+ * - `v`: ECDSA signature recovery parameter (27 or 28)
+ * - `r`: ECDSA signature component (32 bytes)
+ * - `s`: ECDSA signature component (32 bytes)
+ *
+ * @param permitParams - The permit parameters including deadline and signature.
+ * @throws KitError if the permit deadline has already passed.
+ * @throws KitError if the signature recovery parameter (v) is invalid.
+ */
+function validatePermitParams(permitParams) {
+    // Early return if no permit params - caller will use preapproval flow instead
+    if (!permitParams) {
+        return;
+    }
+    // Check that the permit hasn't expired
+    // Deadline is compared against current Unix timestamp (seconds since epoch)
+    const currentTimestamp = BigInt(Math.floor(Date.now() / 1000));
+    if (permitParams.deadline <= currentTimestamp) {
+        throw createValidationFailedError('permitParams.deadline', permitParams.deadline, 'Permit deadline has expired');
+    }
+    // Validate ECDSA signature recovery parameter (v).
+    // In the EVM's ECDSA implementation, 'v' is the recovery identifier that
+    // allows the public key to be recovered from the signature. Per EIP-155,
+    // valid values are:
+    //   - 27: corresponds to recovery id 0 (even y-coordinate)
+    //   - 28: corresponds to recovery id 1 (odd y-coordinate)
+    // These are the only valid values for standard Ethereum signatures.
+    const VALID_RECOVERY_PARAMS = [27, 28];
+    if (!VALID_RECOVERY_PARAMS.includes(permitParams.v)) {
+        throw createValidationFailedError('permitParams.v', permitParams.v, 'Invalid ECDSA recovery parameter. Must be 27 or 28');
+    }
+}
+/**
+ * Get and validate the custom bridge contract address from chain definition.
+ *
+ * The bridge contract address is stored in the chain definition under
+ * `kitContracts.bridge`. This function retrieves it and validates that
+ * it's a properly formatted EVM address (0x-prefixed, 40 hex characters).
+ *
+ * @param fromChain - The source EVM chain definition.
+ * @returns The validated bridge contract address.
+ * @throws KitError if no bridge contract address is configured for the chain.
+ * @throws KitError if the address format is invalid.
+ */
+function getBridgeAddress(fromChain) {
+    const bridgeAddress = fromChain.kitContracts?.bridge;
+    if (bridgeAddress === undefined) {
+        throw createInvalidChainError(fromChain.name, 'No bridge contract address found in chain configuration');
+    }
+    // Validate address format (throws if invalid)
+    assertEvmAddress(bridgeAddress);
+    return bridgeAddress;
+}
+// ============================================================================
+// Contract Call Builder Functions
+// ============================================================================
+/**
+ * Build the BridgeParams struct for the smart contract call.
+ *
+ * Construct the struct from user-provided parameters, applying defaults and
+ * converting addresses to bytes32 format as required by CCTP's cross-chain messaging.
+ *
+ * @param params - The custom burn parameters from the user.
+ * @param protocolFee - The validated protocol fee amount.
+ * @param bridgeAddress - The bridge contract address (used as default fee recipient).
+ * @returns The BridgeParams struct ready for the contract call.
+ */
+function buildBridgeParams(params, protocolFee, bridgeAddress) {
+    const fromChain = params.fromChain;
+    return {
+        amount: params.amount,
+        maxFee: params.maxFee,
+        fee: protocolFee,
+        // Convert recipient to bytes32 for cross-chain compatibility
+        mintRecipient: convertAddress(params.mintRecipient, 'bytes32'),
+        // Zero address means any caller can claim on destination
+        destinationCaller: convertAddress(params.destinationCaller ?? ZERO_HASH, 'bytes32'),
+        // USDC address on the source chain
+        burnToken: fromChain.usdcAddress,
+        // Fee recipient defaults to bridge contract if not specified
+        feeRecipient: params.feeRecipient ?? bridgeAddress,
+        // CCTP domain ID (e.g., 0 = Ethereum, 1 = Avalanche, 6 = Base)
+        destinationDomain: params.toChain.cctp.domain,
+        // Convert to bigint for contract compatibility
+        minFinalityThreshold: BigInt(params.minFinalityThreshold),
+    };
+}
+/**
+ * Determine which bridge contract function to call.
+ *
+ * The function selection follows a 2x2 matrix based on:
+ * 1. Authorization method: Has the user provided a permit signature?
+ * 2. Forwarding mode: Should the relayer auto-complete the transfer?
+ *
+ * Decision tree:
+ * - Permit + Hook → bridgeWithPermitAndHook
+ * - Permit + No Hook → bridgeWithPermit
+ * - No Permit + Hook → bridgeWithPreapprovalAndHook
+ * - No Permit + No Hook → bridgeWithPreapproval
+ *
+ * @param hasPermit - True if permit params were provided.
+ * @param hasHookData - True if hook data was provided for auto-forwarding.
+ * @returns The name of the bridge contract function to call.
+ */
+function selectBridgeFunction(hasPermit, hasHookData) {
+    if (hasPermit) {
+        return hasHookData ? 'bridgeWithPermitAndHook' : 'bridgeWithPermit';
+    }
+    return hasHookData ? 'bridgeWithPreapprovalAndHook' : 'bridgeWithPreapproval';
+}
+/**
+ * Build the arguments array for the bridge contract call.
+ *
+ * Different bridge functions expect different argument patterns:
+ * - bridgeWithPreapproval(bridgeParams)
+ * - bridgeWithPermit(bridgeParams, permitParams)
+ * - bridgeWithPreapprovalAndHook(bridgeParams, hookData)
+ * - bridgeWithPermitAndHook(bridgeParams, permitParams, hookData)
+ *
+ * This function constructs the correct args array based on which optional
+ * parameters are present.
+ *
+ * @param bridgeParams - The BridgeParams struct (always first argument).
+ * @param permitParams - Optional EIP-2612 permit signature.
+ * @param hookData - Optional hook data for CCTP forwarding.
+ * @returns The arguments array ready for the contract call.
+ * @throws KitError if hookData is not a valid hex string starting with 0x.
+ */
+function buildContractArgs(bridgeParams, permitParams, hookData) {
+    // BridgeParams is always the first argument
+    const args = [bridgeParams];
+    // Add permit params if using permit-based authorization
+    if (permitParams) {
+        args.push({
+            deadline: permitParams.deadline,
+            v: permitParams.v,
+            r: permitParams.r,
+            s: permitParams.s,
+        });
+    }
+    // Add hook data if using auto-forwarding, after validating format
+    // Empty string is treated as "no hook data"
+    if (hookData !== undefined && hookData !== '') {
+        const result = hexStringSchema.safeParse(hookData);
+        if (!result.success) {
+            throw createValidationFailedError('hookData', hookData, 'Must be a valid hex string starting with 0x');
+        }
+        args.push(hookData);
+    }
+    return args;
+}
+// ============================================================================
+// Main Export Function
+// ============================================================================
+/**
+ * Prepare an EVM-compatible custom burn transaction for CCTP v2 using a custom bridge contract.
+ *
+ * This is the shared implementation for both `customBurn` and `customBurnWithHook` actions.
+ * It creates a prepared chain request for burning USDC tokens using a custom bridge
+ * contract that supports preapproval, permit-based authorization, and optional hook data
+ * for CCTP forwarding.
+ *
+ * **Authorization Methods**
+ *
+ * **Preapproval**: User has already called `approve()` on the USDC contract to allow
+ * the bridge to spend their tokens. This requires a separate transaction but gives
+ * the user full control over when and how much they approve.
+ *
+ * **Permit**: User signs an EIP-2612 permit message off-chain, and the bridge contract
+ * calls `permit()` on their behalf. This enables gasless approvals in a single transaction.
+ *
+ * **Forwarding Modes**
+ *
+ * **Standard**: User must manually claim the USDC on the destination chain by submitting
+ * the attestation to the destination MessageTransmitter.
+ *
+ * **Hook (Auto-forwarding)**: Circle's Orbit relayer automatically fetches the attestation
+ * and submits the mint transaction on the destination chain. The user pays a higher fee
+ * but doesn't need to interact with the destination chain.
+ *
+ * **Function Selection**
+ *
+ * The function automatically selects the appropriate bridge method based on parameters:
+ * - Without hookData + without permit → `bridgeWithPreapproval`
+ * - Without hookData + with permit → `bridgeWithPermit`
+ * - With hookData + without permit → `bridgeWithPreapprovalAndHook`
+ * - With hookData + with permit → `bridgeWithPermitAndHook`
+ *
+ * @param params - The action payload (either customBurn or customBurnWithHook params).
+ * @param adapter - The EVM adapter responsible for chain context and transaction preparation.
+ * @param context - The resolved operation context providing chain and address information.
+ * @returns A promise that resolves to a prepared chain request.
+ * @throws KitError if the source chain doesn't support custom bridge contracts.
+ * @throws KitError if the source chain is not EVM-compatible.
+ * @throws KitError if permit signature validation fails.
+ * @throws KitError if transaction preparation fails.
+ *
+ * @internal This function is used internally by customBurn and customBurnWithHook wrappers.
+ */
+const prepareCustomBurn = async (params, adapter, context) => {
+    // Step 1: Validate that the source chain supports custom bridge contracts
+    validateChainSupport(params);
+    // Step 2: Validate protocol fee configuration
+    // Default protocolFee to 0 if not specified (no fee collection)
+    const protocolFee = params.protocolFee ?? 0n;
+    validateProtocolFeeParams(protocolFee, params.feeRecipient);
+    // Step 3: Validate permit signature if provided
+    // This checks deadline and ECDSA parameters
+    validatePermitParams(params.permitParams);
+    // Step 4: Get the custom bridge contract address from chain config
+    const fromChain = params.fromChain;
+    const bridgeAddress = getBridgeAddress(fromChain);
+    // Step 5: Build the BridgeParams struct for the contract
+    const bridgeParams = buildBridgeParams(params, protocolFee, bridgeAddress);
+    // Step 6: Detect if hookData is present and determine which function to call
+    // Hook data is only present in customBurnWithHook action payload
+    const hookData = 'hookData' in params ? params.hookData : undefined;
+    const hasHookData = hookData !== undefined && hookData !== '';
+    const functionName = selectBridgeFunction(!!params.permitParams, hasHookData);
+    // Step 7: Build the arguments array for the contract call
+    const args = buildContractArgs(bridgeParams, params.permitParams, hookData);
+    // Step 8: Prepare the transaction using the adapter
+    // This creates a PreparedChainRequest that can be executed or simulated
+    return adapter.prepare({
+        type: 'evm',
+        abi: bridgeContractAbi,
+        address: bridgeAddress,
+        functionName,
+        args,
+    }, context);
+};
+
 /**
- * Prepares an EVM-compatible `customBurn` transaction for CCTP v2 using a custom bridge contract.
+ * Prepare an EVM-compatible `customBurn` transaction for CCTP v2 using a custom bridge contract.
  *
  * This function creates a prepared chain request for burning USDC tokens using a custom bridge
  * contract that supports both preapproval and permit-based token authorization. The custom
@@ -8410,9 +9109,6 @@ const receiveMessage = async (params, adapter, context) => {
  * - When `permitParams` is provided → uses `bridgeWithPermit` for EIP-2612 signature-based approval
  * - When `permitParams` is not provided → uses `bridgeWithPreapproval` for traditional preapproval
  *
- * The action provides a unified interface for both approval methods, with extra bridge
- * contract parameters (fee, burnToken, feeRecipient) automatically resolved for ease of use.
- *
  * @param params - The action payload containing:
  *   - `fromChain`: The EVM chain definition where the burn will occur (must support custom bridge).
  *   - `toChain`: The destination chain definition (must include CCTP domain).
@@ -8424,17 +9120,13 @@ const receiveMessage = async (params, adapter, context) => {
  *   - `protocolFee`: Optional protocol fee amount (defaults to 0n for basic usage).
  *   - `feeRecipient`: Optional fee recipient address (defaults to bridge address).
  *   - `permitParams`: Optional EIP-2612 permit signature for gasless approval.
- *
- *   For basic usage, only the core CCTP parameters are needed (same as depositForBurn).
- *   For advanced usage, protocol fee parameters enable custom fee collection.
- *   For gasless transactions, provide permitParams to avoid separate approval transactions.
  * @param adapter - The EVM adapter responsible for chain context and transaction preparation.
  * @param context - The resolved operation context providing chain and address information.
  * @returns A promise that resolves to a prepared chain request for the `customBurn` operation.
- * @throws Error if the source chain doesn't support custom bridge contracts.
- * @throws Error if the source chain is not EVM-compatible.
- * @throws Error if permit signature validation fails.
- * @throws Error if transaction preparation fails.
+ * @throws KitError if the source chain doesn't support custom bridge contracts.
+ * @throws KitError if the source chain is not EVM-compatible.
+ * @throws KitError if permit signature validation fails.
+ * @throws KitError if transaction preparation fails.
  *
  * @example
  * ```typescript
@@ -8442,9 +9134,7 @@ const receiveMessage = async (params, adapter, context) => {
  *
  * // Check if chain supports custom bridge before using
  * if (hasCustomContractSupport(sourceChain, 'bridge')) {
- *
- *   // Basic usage with preapproval (same interface as depositForBurn)
- *   const basicTransfer = await customBurn(
+ *   const prepared = await customBurn(
  *     {
  *       fromChain: sourceChain,
  *       toChain: destinationChain,
@@ -8452,127 +9142,74 @@ const receiveMessage = async (params, adapter, context) => {
  *       mintRecipient: recipientAddress,
  *       maxFee: BigInt('1000'),
  *       minFinalityThreshold: 65
- *       // protocolFee and feeRecipient auto-default
  *     },
  *     adapter,
  *     context
  *   )
+ *   await prepared.execute()
+ * }
+ * ```
+ */
+const customBurn = async (params, adapter, context) => {
+    return prepareCustomBurn(params, adapter, context);
+};
+
+/**
+ * Prepare an EVM-compatible `customBurnWithHook` transaction for CCTP v2 with forwarding.
  *
- *   // Usage with permit signature (gasless approval)
- *   const permitTransfer = await customBurn(
- *     {
- *       fromChain: sourceChain,
- *       toChain: destinationChain,
- *       amount: BigInt('1000000'),
- *       mintRecipient: recipientAddress,
- *       maxFee: BigInt('1000'),
- *       minFinalityThreshold: 65,
- *       permitParams: {
- *         deadline: BigInt(Math.floor(Date.now() / 1000) + 3600), // 1 hour
- *         v: 27,
- *         r: '0x1234567890abcdef...',
- *         s: '0xfedcba0987654321...'
- *       }
- *     },
- *     adapter,
- *     context
- *   )
+ * This function creates a prepared chain request for burning USDC tokens using a custom bridge
+ * contract with hook data that signals to Circle's Orbit relayer that forwarding is requested.
+ * The relayer will automatically fetch the attestation and submit the destination mint transaction.
+ *
+ * The function automatically selects the appropriate bridge method based on parameters:
+ * - When `permitParams` is provided → uses `bridgeWithPermitAndHook`
+ * - When `permitParams` is not provided → uses `bridgeWithPreapprovalAndHook`
  *
- *   // Advanced usage with protocol fees
- *   const advancedTransfer = await customBurn(
+ * @param params - The action payload containing:
+ *   - `fromChain`: The EVM chain definition where the burn will occur (must support custom bridge).
+ *   - `toChain`: The destination chain definition (must include CCTP domain).
+ *   - `amount`: The amount of USDC to burn (as bigint, in the smallest unit).
+ *   - `mintRecipient`: The address to receive minted USDC on the destination chain.
+ *   - `destinationCaller`: Optional address authorized to call receiveMessage (zero hash if any).
+ *   - `maxFee`: The maximum fee to pay (must cover burn fee + forwarding fee).
+ *   - `minFinalityThreshold`: The minimum finality threshold for the burn event.
+ *   - `protocolFee`: Optional protocol fee amount (defaults to 0n for basic usage).
+ *   - `feeRecipient`: Optional fee recipient address (defaults to bridge address).
+ *   - `permitParams`: Optional EIP-2612 permit signature for gasless approval.
+ *   - `hookData`: Hex-encoded hook data for CCTP forwarding.
+ * @param adapter - The EVM adapter responsible for chain context and transaction preparation.
+ * @param context - The resolved operation context providing chain and address information.
+ * @returns A promise that resolves to a prepared chain request for the `customBurnWithHook` operation.
+ * @throws KitError if the source chain doesn't support custom bridge contracts.
+ * @throws KitError if the source chain is not EVM-compatible.
+ * @throws KitError if permit signature validation fails.
+ * @throws KitError if transaction preparation fails.
+ *
+ * @example
+ * ```typescript
+ * import { hasCustomContractSupport } from '@core/chains'
+ * import { buildForwardingHookData } from '@core/utils'
+ *
+ * if (hasCustomContractSupport(sourceChain, 'bridge')) {
+ *   const prepared = await customBurnWithHook(
  *     {
  *       fromChain: sourceChain,
  *       toChain: destinationChain,
  *       amount: BigInt('1000000'),
  *       mintRecipient: recipientAddress,
- *       maxFee: BigInt('1000'),
+ *       maxFee: BigInt('50000'),
  *       minFinalityThreshold: 65,
- *       protocolFee: BigInt('100'),
- *       feeRecipient: '0xFeeRecipientAddress'
+ *       hookData: buildForwardingHookData()
  *     },
  *     adapter,
  *     context
  *   )
- *
- *   await basicTransfer.execute()
+ *   await prepared.execute()
  * }
  * ```
  */
-const customBurn = async (params, adapter, context) => {
-    // Validate that this is an EVM chain
-    if (params.fromChain.type !== 'evm') {
-        throw new Error(`Expected fromChain to be EVM chain definition, but received chain type: ${params.fromChain.type}`);
-    }
-    // Validate that the chain supports custom bridge contracts
-    if (!hasCustomContractSupport(params.fromChain, 'bridge')) {
-        throw new Error(`Chain ${params.fromChain.name} does not support custom bridge contracts. Use 'cctp.v2.depositForBurn' instead.`);
-    }
-    // Validate logical consistency: protocolFee and feeRecipient must be used together
-    const protocolFee = params.protocolFee ?? 0n;
-    if (protocolFee > 0n && params.feeRecipient === undefined) {
-        throw new Error('protocolFee requires feeRecipient. Specify where the fee should be sent.');
-    }
-    if (params.feeRecipient !== undefined && protocolFee === 0n) {
-        throw new Error('feeRecipient requires non-zero protocolFee. Specify the fee amount to send.');
-    }
-    // Validate address format for user-provided feeRecipient
-    if (params.feeRecipient !== undefined) {
-        assertEvmAddress(params.feeRecipient);
-    }
-    // Validate permit signature components if provided
-    if (params.permitParams) {
-        const currentTimestamp = BigInt(Math.floor(Date.now() / 1000));
-        if (params.permitParams.deadline <= currentTimestamp) {
-            throw new Error('Permit deadline has expired');
-        }
-        if (![27, 28].includes(params.permitParams.v)) {
-            throw new Error('Invalid permit signature recovery parameter (v)');
-        }
-    }
-    // Get the custom bridge contract address from chain definition
-    const bridgeAddress = params.fromChain.kitContracts?.bridge;
-    if (bridgeAddress === undefined) {
-        throw new Error(`No bridge contract address found for chain ${params.fromChain.name}`);
-    }
-    assertEvmAddress(bridgeAddress);
-    // Prepare the bridge parameters struct for the contract call
-    // Use optional parameters with sensible defaults:
-    // - feeRecipient: defaults to bridge address (safe for zero fees)
-    // - burnToken: auto-resolve from chain definition (same as depositForBurn)
-    const destinationCallerAddress = convertAddress(params.destinationCaller ?? ZERO_HASH, 'bytes32');
-    const feeRecipient = params.feeRecipient ?? bridgeAddress;
-    const bridgeParams = {
-        amount: params.amount,
-        maxFee: params.maxFee,
-        fee: protocolFee,
-        mintRecipient: convertAddress(params.mintRecipient, 'bytes32'),
-        destinationCaller: destinationCallerAddress,
-        burnToken: params.fromChain.usdcAddress,
-        feeRecipient,
-        destinationDomain: params.toChain.cctp.domain,
-        minFinalityThreshold: BigInt(params.minFinalityThreshold), // Convert to bigint for contract
-    };
-    // Prepare the custom bridge transaction - select method based on whether permit is provided
-    const args = [bridgeParams];
-    let functionName = 'bridgeWithPreapproval';
-    if (params.permitParams) {
-        // Use bridgeWithPermit when permit signature is provided
-        const permitParams = {
-            deadline: params.permitParams.deadline,
-            v: params.permitParams.v,
-            r: params.permitParams.r,
-            s: params.permitParams.s,
-        };
-        args.push(permitParams);
-        functionName = 'bridgeWithPermit';
-    }
-    return adapter.prepare({
-        type: 'evm',
-        abi: bridgeContractAbi,
-        address: bridgeAddress,
-        functionName,
-        args,
-    }, context);
+const customBurnWithHook = async (params, adapter, context) => {
+    return prepareCustomBurn(params, adapter, context);
 };
 
 /**
@@ -8935,6 +9572,16 @@ const getHandlers = (adapter) => {
         'cctp.v2.depositForBurn': async (params, context) => {
             return depositForBurn(params, adapter, context);
         },
+        /**
+         * Handler for CCTP v2 deposit for burn with hook operations on EVM chains.
+         *
+         * Burns USDC tokens with hook data that signals to Circle's Orbit relayer
+         * that forwarding is requested. The relayer will automatically fetch the
+         * attestation and submit the destination mint transaction.
+         */
+        'cctp.v2.depositForBurnWithHook': async (params, context) => {
+            return depositForBurnWithHook(params, adapter, context);
+        },
         /**
          * Handler for CCTP v2 receive message operations on EVM chains.
          *
@@ -8955,6 +9602,17 @@ const getHandlers = (adapter) => {
         'cctp.v2.customBurn': async (params, context) => {
             return customBurn(params, adapter, context);
         },
+        /**
+         * Handler for CCTP v2 custom burn with hook operations on EVM chains.
+         *
+         * Burns USDC tokens using a custom bridge contract with hook data that
+         * signals to Circle's Orbit relayer that forwarding is requested.
+         * Combines the custom bridge functionality (preapproval/permit) with
+         * automated attestation and destination mint execution.
+         */
+        'cctp.v2.customBurnWithHook': async (params, context) => {
+            return customBurnWithHook(params, adapter, context);
+        },
         /**
          * Handler for native token balance operations on EVM chains.
          *
@@ -11021,16 +11679,31 @@ class EthersAdapter extends EvmAdapter {
      * Simulates a contract function call using Ethers v6 `.staticCall`.
      */
     async simulateFunctionCall(contract, functionName, args, chain) {
-        try {
-            const func = contract.getFunction(functionName);
-            await func.staticCall(...args);
-        }
-        catch (err) {
-            // Wrap simulation errors with structured error format
-            throw parseBlockchainError(err, {
-                chain: chain.name,
-                operation: 'simulation',
-            });
+        // Retry on allowance errors to handle RPC state propagation delays
+        // (e.g., approve tx confirmed but not yet visible in latest block for staticCall)
+        const MAX_SIMULATION_ATTEMPTS = 3;
+        const SIMULATION_RETRY_DELAY_MS = 1000;
+        for (let attempt = 1; attempt <= MAX_SIMULATION_ATTEMPTS; attempt++) {
+            try {
+                const func = contract.getFunction(functionName);
+                await func.staticCall(...args);
+                return;
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                const lowerCaseError = errorMessage.toLowerCase();
+                const isAllowanceError = lowerCaseError.includes('exceeds allowance') ||
+                    lowerCaseError.includes('insufficient allowance');
+                if (isAllowanceError && attempt < MAX_SIMULATION_ATTEMPTS) {
+                    await new Promise((resolve) => setTimeout(resolve, SIMULATION_RETRY_DELAY_MS * attempt));
+                    continue;
+                }
+                // Wrap simulation errors with structured error format
+                throw parseBlockchainError(err, {
+                    chain: chain.name,
+                    operation: 'simulation',
+                });
+            }
         }
     }
     /**
@@ -11938,7 +12611,7 @@ const createAdapterFromPrivateKey = createEthersAdapterFromPrivateKey;
  * const adapter = await createEthersAdapterFromProvider({
  *   provider: window.ethereum,
  *   getProvider: ({ chain }) => new JsonRpcProvider(
- *     `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
+ *     `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
  *     { name: chain.name, chainId: chain.chainId }
  *   )
  * })
@@ -12108,7 +12781,7 @@ const createEthersAdapterFromProvider = async (params) => {
  * const adapter = await createAdapterFromProvider({
  *   provider: window.ethereum,
  *   getProvider: ({ chain }) => new JsonRpcProvider(
- *     `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
+ *     `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
  *     { name: chain.name, chainId: chain.chainId }
  *   )
  * })