@circle-fin/provider-cctp-v2 1.8.5 → 1.10.0

package/index.cjs

@@ -30,10 +30,11 @@ if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
 
 
 var zod = require('zod');
-var pino = require('pino');
-var units = require('@ethersproject/units');
 var bytes = require('@ethersproject/bytes');
+require('@ethersproject/abi');
 var address = require('@ethersproject/address');
+var pino = require('pino');
+var units = require('@ethersproject/units');
 var bs58 = require('bs58');
 
 function _interopDefault (e) { return e && e.__esModule ? e.default : e; }
@@ -84,6 +85,8 @@ var bs58__default = /*#__PURE__*/_interopDefault(bs58);
     Blockchain["Celo_Alfajores_Testnet"] = "Celo_Alfajores_Testnet";
     Blockchain["Codex"] = "Codex";
     Blockchain["Codex_Testnet"] = "Codex_Testnet";
+    Blockchain["Cronos"] = "Cronos";
+    Blockchain["Cronos_Testnet"] = "Cronos_Testnet";
     Blockchain["Edge"] = "Edge";
     Blockchain["Edge_Testnet"] = "Edge_Testnet";
     Blockchain["Ethereum"] = "Ethereum";
@@ -166,6 +169,7 @@ var BridgeChain;
     BridgeChain["Avalanche"] = "Avalanche";
     BridgeChain["Base"] = "Base";
     BridgeChain["Codex"] = "Codex";
+    BridgeChain["Cronos"] = "Cronos";
     BridgeChain["Edge"] = "Edge";
     BridgeChain["Ethereum"] = "Ethereum";
     BridgeChain["HyperEVM"] = "HyperEVM";
@@ -190,6 +194,7 @@ var BridgeChain;
     BridgeChain["Avalanche_Fuji"] = "Avalanche_Fuji";
     BridgeChain["Base_Sepolia"] = "Base_Sepolia";
     BridgeChain["Codex_Testnet"] = "Codex_Testnet";
+    BridgeChain["Cronos_Testnet"] = "Cronos_Testnet";
     BridgeChain["Edge_Testnet"] = "Edge_Testnet";
     BridgeChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
@@ -701,7 +706,10 @@ var EarnChain;
         contracts: {
             v1: {
                 wallet: GATEWAY_WALLET_EVM_TESTNET,
-                minter: GATEWAY_MINTER_EVM_TESTNET
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+                // DepositForHandler the GenericExecutor calls to run a fast cross-chain
+                // deposit into the GatewayWallet above.
+                depositForHandler: '0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48'
             }
         },
         forwarderSupported: {
@@ -1235,6 +1243,96 @@ var EarnChain;
     }
 });
 
+/**
+ * Cronos Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Cronos blockchain.
+ * Cronos is an EVM-compatible blockchain.
+ */ const Cronos = defineChain({
+    type: 'evm',
+    chain: Blockchain.Cronos,
+    name: 'Cronos',
+    title: 'Cronos Mainnet',
+    nativeCurrency: {
+        name: 'Cronos',
+        symbol: 'CRO',
+        decimals: 18
+    },
+    chainId: 25,
+    isTestnet: false,
+    explorerUrl: 'https://cronoscan.com/tx/{hash}',
+    rpcEndpoints: [
+        'https://evm.cronos.org'
+    ],
+    eurcAddress: '0xA6dE01a2d62C6B5f3525d768f34d276652C554c8',
+    usdcAddress: '0x3D7F2C478aAfdB65542BCB44bCeeC05849999d2D',
+    usdtAddress: null,
+    cctp: {
+        domain: 32,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+    }
+});
+
+/**
+ * Cronos Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Cronos blockchain.
+ * Cronos is an EVM-compatible blockchain.
+ */ const CronosTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Cronos_Testnet,
+    name: 'Cronos Testnet',
+    title: 'Cronos Testnet',
+    nativeCurrency: {
+        name: 'CRO',
+        symbol: 'tCRO',
+        decimals: 18
+    },
+    chainId: 338,
+    isTestnet: true,
+    explorerUrl: 'https://explorer.cronos.org/testnet/tx/{hash}',
+    rpcEndpoints: [
+        'https://evm-t3.cronos.org'
+    ],
+    eurcAddress: '0x31f7538adb53cF16350e6B0c89d03D91b7D12c46',
+    usdcAddress: '0xEb33dc5fac03833e132593659e1dE7256aB59794',
+    usdtAddress: null,
+    cctp: {
+        domain: 32,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET
+    }
+});
+
 /**
  * Edge Mainnet chain definition
  * @remarks
@@ -3586,6 +3684,8 @@ var Chains = {
   CeloAlfajoresTestnet: CeloAlfajoresTestnet,
   Codex: Codex,
   CodexTestnet: CodexTestnet,
+  Cronos: Cronos,
+  CronosTestnet: CronosTestnet,
   Edge: Edge,
   EdgeTestnet: EdgeTestnet,
   Ethereum: Ethereum,
@@ -3727,7 +3827,10 @@ var Chains = {
     minter: zod.z.string({
         required_error: 'Gateway minter address is required. Please provide a valid contract address.',
         invalid_type_error: 'Gateway minter address must be a string.'
-    }).min(1, 'Gateway minter address cannot be empty.')
+    }).min(1, 'Gateway minter address cannot be empty.'),
+    depositForHandler: zod.z.string({
+        invalid_type_error: 'Gateway depositForHandler address must be a string.'
+    }).min(1, 'Gateway depositForHandler address cannot be empty.').optional()
 }).strict() // Reject any additional properties not defined in the schema
 ;
 /**
@@ -4197,21 +4300,31 @@ const swapTokenEnumSchema = zod.z.enum([
  * returning the appropriate address based on the requested contract type.
  *
  * @param chain - The chain definition to resolve the contract address for
- * @param contractType - The type of contract address to resolve ('tokenMessenger' or 'messageTransmitter')
+ * @param contractType - The type of contract address to resolve ('tokenMessenger', 'messageTransmitter', or 'tokenMessengerWithFees')
  * @returns The contract address for the specified contract type
  * @throws Error when chain does not support CCTP v2 or has unsupported contract configuration
+ * @throws Error when 'tokenMessengerWithFees' is requested but not configured on the chain
  */ const resolveCCTPV2ContractAddress = (chain, contractType)=>{
     // Handle custom bridge contract for tokenMessenger (burn transaction)
-    if (hasCustomContractSupport(chain, 'bridge') && chain.kitContracts?.bridge !== undefined) {
+    if (contractType === 'tokenMessenger' && hasCustomContractSupport(chain, 'bridge') && chain.kitContracts?.bridge !== undefined) {
         return chain.kitContracts.bridge;
     }
     // At this point we know CCTP v2 is supported, so contracts exist
     const cctpConfig = chain.cctp;
     const contracts = cctpConfig.contracts.v2;
+    // The `TokenMessengerWithFees` wrapper (prepaid FORWARD path) is an optional
+    // deployment carried alongside both split and merged configurations.
+    if (contractType === 'tokenMessengerWithFees') {
+        const wrapper = contracts.tokenMessengerWithFees;
+        if (wrapper === undefined || wrapper === '') {
+            throw new Error(`TokenMessengerWithFees is not configured on chain ${chain.name}. The prepaid FORWARD path is unavailable on this chain.`);
+        }
+        return wrapper;
+    }
     // Handle different contract types with explicit type checking
     switch(contracts.type){
         case 'split':
-            return contracts.tokenMessenger ;
+            return contractType === 'tokenMessenger' ? contracts.tokenMessenger : contracts.messageTransmitter;
         case 'merged':
             return contracts.contract;
         default:
@@ -7360,6 +7473,7 @@ class KitError extends Error {
         [Blockchain.Base]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
         [Blockchain.Celo]: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
         [Blockchain.Codex]: '0xd996633a415985DBd7D6D12f4A4343E31f5037cf',
+        [Blockchain.Cronos]: '0x3D7F2C478aAfdB65542BCB44bCeeC05849999d2D',
         [Blockchain.Edge]: '0x98d2919b9A214E6Fa5384AC81E6864bA686Ad74c',
         [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
         [Blockchain.Hedera]: '0.0.456858',
@@ -7393,6 +7507,7 @@ class KitError extends Error {
         [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
         [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
         [Blockchain.Codex_Testnet]: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
+        [Blockchain.Cronos_Testnet]: '0xEb33dc5fac03833e132593659e1dE7256aB59794',
         [Blockchain.Edge_Testnet]: '0x2d9F7CAD728051AA35Ecdc472a14cf8cDF5CFD6B',
         [Blockchain.Ethereum_Sepolia]: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
         [Blockchain.Hedera_Testnet]: '0.0.429274',
@@ -7465,6 +7580,7 @@ class KitError extends Error {
         // =========================================================================
         [Blockchain.Avalanche]: '0xc891EB4cbdEFf6e073e859e987815Ed1505c2ACD',
         [Blockchain.Base]: '0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42',
+        [Blockchain.Cronos]: '0xA6dE01a2d62C6B5f3525d768f34d276652C554c8',
         [Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
         [Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
         [Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
@@ -7473,6 +7589,7 @@ class KitError extends Error {
         // =========================================================================
         [Blockchain.Arc_Testnet]: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
         [Blockchain.Base_Sepolia]: '0x808456652fdb597867f38412077A9182bf77359F',
+        [Blockchain.Cronos_Testnet]: '0x31f7538adb53cF16350e6B0c89d03D91b7D12c46',
         [Blockchain.Ethereum_Sepolia]: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4'
     }
 };
@@ -9026,6 +9143,198 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
     return false;
 };
 
+/**
+ * The zero address, denoting a native-currency fee in a signed quote.
+ */ const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+/**
+ * Resolve the fee payment channel for a prepaid-FORWARD burn via `TokenMessengerWithFees`.
+ *
+ * Determines the native `msg.value` and the ERC-20 approvals required, honouring
+ * the quote's `feeToken`:
+ * - Native fee (`feeToken` is the zero address): attach exactly `feeTotalAmount`
+ *   as `msg.value`; approve only the burn amount.
+ * - ERC-20 fee equal to the burn token (both USDC — the `isBurnTokenFee` case):
+ *   approve a single combined `amount + feeTotalAmount` and skip the redundant
+ *   second approval.
+ * - ERC-20 fee different from the burn token: approve the burn amount and the fee
+ *   amount separately.
+ *
+ * This encodes only balance/allowance intent; it does not fetch balances. The
+ * caller is responsible for a balance preflight against the fresh quote.
+ *
+ * @param params - The fee token, burn token, burn amount, and total fee amount.
+ * @returns The resolved fee payment plan.
+ * @throws KitError if `amount` or `feeTotalAmount` is negative.
+ *
+ * @example
+ * ```typescript
+ * // Native fee
+ * resolveFeePayment({
+ *   feeToken: '0x0000000000000000000000000000000000000000',
+ *   burnToken: '0xUSDC...',
+ *   amount: 1_000_000n,
+ *   feeTotalAmount: 3_500_000n,
+ * })
+ * // → { isNativeFee: true, isBurnTokenFee: false, nativeValue: 3_500_000n,
+ * //     approvals: [{ token: '0xUSDC...', amount: 1_000_000n }] }
+ * ```
+ */ const resolveFeePayment = (params)=>{
+    const { feeToken, burnToken, amount, feeTotalAmount } = params;
+    if (typeof amount !== 'bigint' || amount < 0n) {
+        throw createValidationFailedError('amount', amount, 'Must be a non-negative bigint');
+    }
+    if (typeof feeTotalAmount !== 'bigint' || feeTotalAmount < 0n) {
+        throw createValidationFailedError('feeTotalAmount', feeTotalAmount, 'Must be a non-negative bigint');
+    }
+    const isNativeFee = feeToken.toLowerCase() === ZERO_ADDRESS;
+    const isBurnTokenFee = !isNativeFee && feeToken.toLowerCase() === burnToken.toLowerCase();
+    if (isNativeFee) {
+        return {
+            isNativeFee: true,
+            isBurnTokenFee: false,
+            nativeValue: feeTotalAmount,
+            approvals: [
+                {
+                    token: burnToken,
+                    amount
+                }
+            ]
+        };
+    }
+    if (isBurnTokenFee) {
+        // Fee and burn draw on the same token — a single combined approval covers
+        // both; the redundant second approval is skipped.
+        return {
+            isNativeFee: false,
+            isBurnTokenFee: true,
+            nativeValue: 0n,
+            approvals: [
+                {
+                    token: burnToken,
+                    amount: amount + feeTotalAmount
+                }
+            ]
+        };
+    }
+    return {
+        isNativeFee: false,
+        isBurnTokenFee: false,
+        nativeValue: 0n,
+        approvals: [
+            {
+                token: burnToken,
+                amount
+            },
+            {
+                token: feeToken,
+                amount: feeTotalAmount
+            }
+        ]
+    };
+};
+
+/**
+ * Custom errors reverted by the `TokenMessengerWithFees` wrapper on the prepaid
+ * FORWARD path.
+ *
+ * - `IncorrectNativePayment` — `msg.value` did not equal the quoted native fee.
+ * - `ForwardFeeWithoutHook` — the quote has a FORWARD item but the hookData lacks
+ *   a `cctp-forward` frame.
+ * - `ForwardHookWithoutFee` — the hookData has a `cctp-forward` frame but the quote
+ *   omits a FORWARD item.
+ * - `QuoteArgsMismatch` — the signed quote's `argsHash` does not match the on-chain
+ *   call arguments (wrong hookData/destinationCaller/amount/etc.).
+ * - `InvalidQuoteSigner` — the signed quote was not signed by a recognized signer.
+ */ const PREPAID_FORWARD_REVERT_NAMES = [
+    'IncorrectNativePayment',
+    'ForwardFeeWithoutHook',
+    'ForwardHookWithoutFee',
+    'QuoteArgsMismatch',
+    'InvalidQuoteSigner'
+];
+/**
+ * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
+ * hookData must start with.
+ */ const CCTP_FORWARD_MAGIC_HEX = Buffer.from(CCTP_FORWARD_MAGIC_PREFIX, 'ascii').toString('hex');
+/**
+ * Determine whether a hookData blob begins with the `cctp-forward` envelope.
+ *
+ * The prepaid FORWARD path requires the GenericExecutor blob to be wrapped in a
+ * `cctp-forward` frame; without it the wrapper reverts `ForwardFeeWithoutHook`.
+ *
+ * @param hookData - The 0x-prefixed hookData hex string.
+ * @returns True when the hookData starts with the `cctp-forward` magic.
+ *
+ * @example
+ * ```typescript
+ * hasForwardHook('0x636374702d666f7277617264...') // true
+ * hasForwardHook('0xdeadbeef') // false
+ * ```
+ */ const hasForwardHook = (hookData)=>{
+    if (typeof hookData !== 'string') {
+        return false;
+    }
+    const normalized = (hookData.startsWith('0x') ? hookData.slice(2) : hookData).toLowerCase();
+    return normalized.startsWith(CCTP_FORWARD_MAGIC_HEX);
+};
+/**
+ * Assert that a hookData blob is forward-friendly for the prepaid FORWARD path.
+ *
+ * The prepaid FORWARD path always requests a FORWARD fee item, so the wrapper
+ * requires the hookData to start with a `cctp-forward` frame. Validating this
+ * before the burn surfaces the guaranteed `ForwardFeeWithoutHook` revert as a
+ * typed input error instead of an on-chain failure.
+ *
+ * @param hookData - The 0x-prefixed hookData hex string.
+ * @throws KitError (`INPUT_VALIDATION_FAILED`) if the hookData is missing or lacks
+ *   the `cctp-forward` frame.
+ *
+ * @example
+ * ```typescript
+ * assertForwardHookData(geForwardHookData) // ok
+ * assertForwardHookData('0xdeadbeef') // throws — would revert ForwardFeeWithoutHook
+ * ```
+ */ const assertForwardHookData = (hookData)=>{
+    if (!hasForwardHook(hookData)) {
+        throw createValidationFailedError('hookData', hookData, 'Prepaid FORWARD burns require a cctp-forward-wrapped hookData; without it the TokenMessengerWithFees wrapper reverts ForwardFeeWithoutHook');
+    }
+};
+/**
+ * Map a raw error thrown while submitting a prepaid-FORWARD burn to a typed error.
+ *
+ * Inspects the error for a known `TokenMessengerWithFees` custom revert name and,
+ * when found, returns a structured {@link KitError} describing it. Returns
+ * `undefined` when the error is not a recognized wrapper revert so the caller can
+ * fall through to generic blockchain-error parsing.
+ *
+ * @param error - The error thrown by transaction simulation or execution.
+ * @param chain - The source chain name, for the error message.
+ * @returns A typed {@link KitError} for a recognized wrapper revert, else `undefined`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await prepared.execute()
+ * } catch (error) {
+ *   throw mapPrepaidForwardError(error, 'Ethereum') ?? parseBlockchainError(error, { chain: 'Ethereum' })
+ * }
+ * ```
+ */ const mapPrepaidForwardError = (error, chain)=>{
+    let message = '';
+    if (error instanceof Error) {
+        message = error.message;
+    } else if (typeof error === 'string') {
+        message = error;
+    }
+    const matched = PREPAID_FORWARD_REVERT_NAMES.find((name)=>message.includes(name));
+    if (matched === undefined) {
+        return undefined;
+    }
+    return createTransactionRevertedError(chain, matched, {
+        revert: matched
+    });
+};
+
 /**
  * Type guard to validate the forwardFee object structure.
  *
@@ -9182,6 +9491,15 @@ const CUSTOM_BURN_GAS_ESTIMATE_EVM = 201_525n // p99 and max are same here: 201_
 ;
 const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_839n) / 2 = 237_401n
 ;
+// Hard execution caps: observed max + ~30% buffer, used as gasLimit overrides on
+// chains whose eth_estimateGas under-reports (e.g. Cronos EIP-7623 calldata floor).
+// Kept separate from the fee-estimate averages above.
+const APPROVE_GAS_LIMIT_EVM = 100_000n // ERC-20 approve observed max ~46k
+;
+const DEPOSIT_FOR_BURN_GAS_LIMIT_EVM = 300_000n // observed max 226_506 + ~30%
+;
+const RECEIVE_MESSAGE_GAS_LIMIT_EVM = 400_000n // observed max 310_839 + ~30%
+;
 /**
  * The minimum finality threshold for CCTPv2 transfers.
  *
@@ -9210,6 +9528,27 @@ const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_8
         'Content-Type': 'application/json'
     }
 };
+/**
+ * Merges caller-provided polling overrides on top of {@link DEFAULT_CONFIG}.
+ *
+ * Headers are merged independently so caller-supplied headers augment the
+ * defaults (such as `Content-Type`) rather than replacing them wholesale.
+ *
+ * @param config - Caller-provided polling configuration overrides
+ * @param internalDefaults - Internal defaults applied before `config` (for example a
+ *   reduced `maxRetries` for one-shot requests); `config` still wins on conflict
+ * @returns The effective polling configuration
+ * @internal
+ */ const mergeAttestationConfig = (config, internalDefaults = {})=>({
+        ...DEFAULT_CONFIG,
+        ...internalDefaults,
+        ...config,
+        headers: {
+            ...DEFAULT_CONFIG.headers,
+            ...internalDefaults.headers,
+            ...config.headers
+        }
+    });
 /**
  * Type guard that verifies if an unknown value matches the AttestationMessage shape
  * and has all required properties.
@@ -9356,10 +9695,7 @@ const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_8
  * ```
  */ const fetchAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
     const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = {
-        ...DEFAULT_CONFIG,
-        ...config
-    };
+    const effectiveConfig = mergeAttestationConfig(config);
     return await pollApiGet(url, isAttestationResponse, effectiveConfig);
 };
 /**
@@ -9402,11 +9738,9 @@ const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_8
  */ const fetchAttestationWithoutStatusCheck = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
     const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
     // Use minimal retries since we're just fetching existing data
-    const effectiveConfig = {
-        ...DEFAULT_CONFIG,
-        maxRetries: 3,
-        ...config
-    };
+    const effectiveConfig = mergeAttestationConfig(config, {
+        maxRetries: 3
+    });
     return await pollApiGet(url, isAttestationResponseWithoutStatusCheck, effectiveConfig);
 };
 /**
@@ -9466,10 +9800,7 @@ const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_8
  * ```
  */ const fetchReAttestedAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
     const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = {
-        ...DEFAULT_CONFIG,
-        ...config
-    };
+    const effectiveConfig = mergeAttestationConfig(config);
     return await pollApiGet(url, isReAttestedAttestationResponse, effectiveConfig);
 };
 /**
@@ -9535,85 +9866,210 @@ const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_8
  */ const requestReAttestation = async (nonce, isTestnet, config = {})=>{
     const url = buildReAttestUrl(nonce, isTestnet);
     // Use minimal retries since we're just submitting a request, not polling for state
-    const effectiveConfig = {
-        ...DEFAULT_CONFIG,
-        maxRetries: 3,
-        ...config
-    };
+    const effectiveConfig = mergeAttestationConfig(config, {
+        maxRetries: 3
+    });
     return await pollApiPost(url, {}, isReAttestationResponse, effectiveConfig);
 };
 
-const assertCCTPv2WalletContextSymbol = Symbol('assertCCTPv2WalletContext');
 /**
- * Asserts that the provided parameters match the CCTPv2 wallet context interface.
- * The validation includes:
- * - Basic wallet context validation (adapter, address, chain)
- * - CCTPv2-specific chain validation (must be an EVM chain)
- *
- * @param params - The parameters to validate
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
- *
- * @example
- * ```typescript
- * import { assertCCTPv2WalletContext } from '@circle-fin/provider-cctp-v2'
- * import { Ethereum } from '@core/chains'
+ * Type guard that checks if the relayer has confirmed the mint transaction.
  *
- * // Prepare wallet context
- * const context = {
- *   adapter: {
- *     prepare: async () => ({ data: 'prepared transaction' }),
- *     waitForTransaction: async () => ({ status: 'confirmed' })
- *   },
- *   address: '0x1234567890123456789012345678901234567890',
- *   chain: {
- *     ...Ethereum,
- *     usdcAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
- *     cctp: {
- *       domain: 1,
- *       contracts: {
- *         v2: {
- *           tokenMessenger: '0xTokenMessenger',
- *           messageTransmitter: '0xMessageTransmitter'
- *         }
- *       }
- *     }
- *   }
- * }
+ * This function validates that:
+ * 1. The response has valid AttestationResponse structure
+ * 2. At least one message has forwardState === 'CONFIRMED' (or 'COMPLETE') and a valid forwardTxHash
  *
- * // This will throw if validation fails
- * assertCCTPv2WalletContext(context)
+ * If forwardState is 'FAILED', throws a non-retryable KitError.
+ * If forwardState is 'PENDING' or not present, throws a RETRYABLE KitError to continue polling.
  *
- * // If we get here, context is guaranteed to be valid
- * console.log('CCTPv2 wallet context is valid')
- * ```
- */ function assertCCTPv2WalletContext(params) {
-    // First validate basic wallet context
-    validateWithStateTracking(params, walletContextSchema, 'CCTPv2 wallet context', assertCCTPv2WalletContextSymbol);
-    // After validation, we know params is WalletContext
-    const context = params;
-    // Validate USDC support
-    if (context.chain.usdcAddress === null) {
-        throw createInvalidChainError(context.chain.name, 'Does not have USDC configured');
+ * @param obj - The value to check, typically a parsed JSON response
+ * @returns True if the relayer has confirmed the mint
+ * @throws {KitError} With FATAL recoverability if structure is invalid
+ * @throws {KitError} With RESUMABLE recoverability if forwardState is 'FAILED'
+ * @throws {KitError} With RETRYABLE recoverability if still pending
+ * @internal
+ */ const isRelayerMintConfirmed = (obj)=>{
+    // First check if the structure is valid
+    if (!hasValidAttestationStructure(obj)) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'Invalid attestation response structure from IRIS API.'
+        });
     }
-    // Validate CCTPv2 support
-    if (!isCCTPV2Supported(context.chain)) {
-        throw createInvalidChainError(context.chain.name, 'Does not support CCTPv2');
+    // Find the first message (typically there's only one)
+    const message = obj.messages[0];
+    if (!message) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'No attestation messages found in IRIS API response.'
+        });
     }
-}
-
-const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
-/**
- * Asserts that the provided parameters match the CCTPv2 bridge parameters interface.
- * The validation includes:
- * - Basic parameter structure and types
- * - Amount validation (non-empty numeric string \> 0)
- * - Wallet address format validation (must be valid Ethereum address)
- * - Chain definition validation (must be a valid chain with required properties)
- * - Adapter validation (must implement required methods)
- * - Optional config validation (transfer speed and max fee)
- * - Network compatibility (source and destination chains must both be testnet or both mainnet)
- * - CCTPv2-specific wallet context validations
- *
+    // Check for FAILED state - this is a permanent failure
+    if (message.forwardState === 'FAILED') {
+        throw new KitError({
+            ...NetworkError.RELAYER_FORWARD_FAILED,
+            recoverability: 'RESUMABLE',
+            message: 'Circle relayer failed to forward the mint transaction. The mint may still have succeeded if another party submitted it. Check the recipient wallet balance before retrying. If the mint did not occur, you can manually submit it using the attestation data in the error cause.',
+            cause: {
+                trace: {
+                    eventNonce: message.eventNonce,
+                    attestation: message.attestation,
+                    message: message.message
+                }
+            }
+        });
+    }
+    // Check if mint is confirmed (or complete) with a valid transaction hash
+    // We accept both CONFIRMED and COMPLETE since COMPLETE implies CONFIRMED
+    if ((message.forwardState === 'CONFIRMED' || message.forwardState === 'COMPLETE') && typeof message.forwardTxHash === 'string' && message.forwardTxHash.trim().length > 0) {
+        return true;
+    }
+    // Still pending or not yet processed - throw RETRYABLE error to continue polling
+    throw new KitError({
+        ...NetworkError.RELAYER_PENDING,
+        recoverability: 'RETRYABLE',
+        message: 'Relayer mint not ready. Waiting for confirmation.'
+    });
+};
+/**
+ * Polls the attestation API until the relayer's mint transaction is confirmed.
+ *
+ * This function is used when `useForwarder` is enabled. Instead of the user
+ * submitting the mint transaction, Circle's Orbit relayer handles it automatically.
+ * This function polls until the relayer has submitted and confirmed the mint transaction.
+ *
+ * @remarks
+ * - Uses a 20-minute timeout by default (600 retries × 2 seconds)
+ * - Throws immediately if `forwardState` is 'FAILED'
+ * - Waits for `forwardState` to be 'CONFIRMED' or 'COMPLETE' (COMPLETE implies CONFIRMED)
+ * - Returns the attestation message with `forwardTxHash` populated
+ *
+ * @param sourceDomainId - The CCTP domain ID of the source chain
+ * @param transactionHash - The transaction hash of the burn operation
+ * @param isTestnet - Whether this is for a testnet chain (true) or mainnet (false)
+ * @param config - Optional configuration overrides for polling behavior
+ * @returns The attestation message with confirmed forwardTxHash
+ * @throws {KitError} With code 'NETWORK_RELAYER_FORWARD_FAILED' if relayer failed
+ * @throws {KitError} If timeout is reached while still pending
+ *
+ * @example
+ * ```typescript
+ * const attestation = await fetchRelayerMint(0, '0xabc...', false)
+ * console.log('Relayer mint tx:', attestation.forwardTxHash)
+ * ```
+ */ const fetchRelayerMint = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
+    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
+    const effectiveConfig = mergeAttestationConfig(config);
+    let response;
+    try {
+        response = await pollApiGet(url, isRelayerMintConfirmed, effectiveConfig);
+    } catch (error) {
+        // Enrich RELAYER_FORWARD_FAILED errors with the burn transaction hash
+        if (error instanceof KitError && error.name === 'NETWORK_RELAYER_FORWARD_FAILED') {
+            throw new KitError({
+                ...NetworkError.RELAYER_FORWARD_FAILED,
+                recoverability: error.recoverability,
+                message: error.message,
+                cause: {
+                    ...error.cause,
+                    trace: {
+                        ...error.cause?.trace,
+                        burnTxHash: transactionHash
+                    }
+                }
+            });
+        }
+        throw error;
+    }
+    // Return the first message (which should have forwardTxHash)
+    // Note: This check is needed for TypeScript type safety even though
+    // isRelayerMintConfirmed validates messages[0] exists. The type guard
+    // narrows the type at the call site, but TypeScript can't infer that
+    // the array still has elements after pollApiGet returns.
+    const message = response.messages[0];
+    if (!message) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'No attestation messages found in response after polling.'
+        });
+    }
+    return message;
+};
+
+const assertCCTPv2WalletContextSymbol = Symbol('assertCCTPv2WalletContext');
+/**
+ * Asserts that the provided parameters match the CCTPv2 wallet context interface.
+ * The validation includes:
+ * - Basic wallet context validation (adapter, address, chain)
+ * - CCTPv2-specific chain validation (must be an EVM chain)
+ *
+ * @param params - The parameters to validate
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { assertCCTPv2WalletContext } from '@circle-fin/provider-cctp-v2'
+ * import { Ethereum } from '@core/chains'
+ *
+ * // Prepare wallet context
+ * const context = {
+ *   adapter: {
+ *     prepare: async () => ({ data: 'prepared transaction' }),
+ *     waitForTransaction: async () => ({ status: 'confirmed' })
+ *   },
+ *   address: '0x1234567890123456789012345678901234567890',
+ *   chain: {
+ *     ...Ethereum,
+ *     usdcAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *     cctp: {
+ *       domain: 1,
+ *       contracts: {
+ *         v2: {
+ *           tokenMessenger: '0xTokenMessenger',
+ *           messageTransmitter: '0xMessageTransmitter'
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * // This will throw if validation fails
+ * assertCCTPv2WalletContext(context)
+ *
+ * // If we get here, context is guaranteed to be valid
+ * console.log('CCTPv2 wallet context is valid')
+ * ```
+ */ function assertCCTPv2WalletContext(params) {
+    // First validate basic wallet context
+    validateWithStateTracking(params, walletContextSchema, 'CCTPv2 wallet context', assertCCTPv2WalletContextSymbol);
+    // After validation, we know params is WalletContext
+    const context = params;
+    // Validate USDC support
+    if (context.chain.usdcAddress === null) {
+        throw createInvalidChainError(context.chain.name, 'Does not have USDC configured');
+    }
+    // Validate CCTPv2 support
+    if (!isCCTPV2Supported(context.chain)) {
+        throw createInvalidChainError(context.chain.name, 'Does not support CCTPv2');
+    }
+}
+
+const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
+/**
+ * Asserts that the provided parameters match the CCTPv2 bridge parameters interface.
+ * The validation includes:
+ * - Basic parameter structure and types
+ * - Amount validation (non-empty numeric string \> 0)
+ * - Wallet address format validation (must be valid Ethereum address)
+ * - Chain definition validation (must be a valid chain with required properties)
+ * - Adapter validation (must implement required methods)
+ * - Optional config validation (transfer speed and max fee)
+ * - Network compatibility (source and destination chains must both be testnet or both mainnet)
+ * - CCTPv2-specific wallet context validations
+ *
  * @param params - The parameters to validate
  * @throws {KitError} If validation fails, with details about which properties failed
  *
@@ -9811,1422 +10267,1735 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
 }
 
 /**
- * CCTP bridge step names that can occur in the bridging flow.
+ * Resolves an operation context into concrete chain and address values.
  *
- * This object provides type safety for step names and represents all possible
- * steps that can be executed during a CCTP bridge operation. Using const assertions
- * makes this tree-shakable and follows modern TypeScript best practices.
- */ const CCTPv2StepName = {
-    approve: 'approve',
-    burn: 'burn',
-    fetchAttestation: 'fetchAttestation',
-    mint: 'mint',
-    reAttest: 'reAttest'
-};
-/**
- * Conditional step transition rules for CCTP bridge flow.
+ * This function ensures that action handlers always receive defined chain and address
+ * values by applying validation and resolution logic based on the adapter's capabilities.
+ * It enforces compile-time and runtime address requirements based on the adapter's
+ * address control model.
  *
- * Rules are evaluated in order - the first matching condition determines the next step.
- * This approach supports flexible flow logic and makes it easy to extend with new patterns.
- */ const STEP_TRANSITION_RULES = {
-    // Starting state - no steps executed yet
-    '': [
-        {
-            condition: ()=>true,
-            nextStep: CCTPv2StepName.approve,
-            reason: 'Start with approval step',
-            isActionable: true
+ * **Resolution logic**:
+ * - **Chain**: Uses provided chain identifier and resolves to ChainDefinition
+ * - **Address**:
+ *   - For user-controlled adapters: Retrieves current address from adapter (context address ignored)
+ *   - For developer-controlled adapters: Uses address provided in context (required)
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type for compile-time validation
+ * @param adapter - The typed adapter instance with capabilities defined
+ * @param ctx - Operation context with compile-time validated address requirements
+ * @returns Promise resolving to concrete chain and address values
+ * @throws Error when adapter capabilities are not defined
+ * @throws Error when operation context is not provided
+ * @throws Error when address is required but not provided (developer-controlled)
+ * @throws Error when adapter.getAddress() fails (user-controlled)
+ *
+ * @example
+ * ```typescript
+ * import { resolveOperationContext } from '@core/adapter'
+ *
+ * // User-controlled adapter - address forbidden in context
+ * const userAdapter: Adapter<{ addressContext: 'user-controlled', supportedChains: [] }>
+ * const resolved = await resolveOperationContext(userAdapter, {
+ *   chain: 'Base' // address will be resolved from wallet
+ * })
+ * console.log(resolved.chain)   // ChainDefinition - always defined
+ * console.log(resolved.address) // string - resolved from adapter
+ *
+ * // Developer-controlled adapter - address required in context
+ * const devAdapter: Adapter<{ addressContext: 'developer-controlled', supportedChains: [] }>
+ * const resolved = await resolveOperationContext(devAdapter, {
+ *   chain: 'Base',
+ *   address: '0x123...' // Required and enforced at compile time
+ * })
+ * console.log(resolved.address) // '0x123...' - from context
+ * ```
+ */ async function resolveOperationContext(adapter, ctx) {
+    // Adapter must have capabilities defined
+    if (adapter.capabilities === undefined) {
+        throw new Error('Adapter capabilities must be defined. Please ensure the adapter implements the capabilities property.');
+    }
+    // Operation context is required for new typed adapters
+    if (ctx === undefined) {
+        throw new Error('Operation context is required. Please provide a context with the required chain and address information.');
+    }
+    // Resolve chain from context (required)
+    const resolvedChain = resolveChainIdentifier(ctx.chain);
+    // Resolve address based on adapter capabilities
+    let resolvedAddress;
+    if (adapter.capabilities.addressContext === 'developer-controlled') {
+        // Developer-controlled: address must be explicitly provided
+        if (!ctx.address) {
+            throw new Error('Address is required for developer-controlled adapters. Please provide an address in the operation context.');
         }
-    ],
-    // After Approve step
-    [CCTPv2StepName.approve]: [
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'success',
-            nextStep: CCTPv2StepName.burn,
-            reason: 'Approval successful, proceed to burn',
-            isActionable: true
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'error',
-            nextStep: CCTPv2StepName.approve,
-            reason: 'Retry failed approval',
-            isActionable: true
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'noop',
-            nextStep: CCTPv2StepName.burn,
-            reason: 'No approval needed, proceed to burn',
-            isActionable: true
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'pending',
-            nextStep: CCTPv2StepName.approve,
-            reason: 'Continue pending approval',
-            isActionable: false
-        }
-    ],
-    // After Burn step
-    [CCTPv2StepName.burn]: [
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'success',
-            nextStep: CCTPv2StepName.fetchAttestation,
-            reason: 'Burn successful, fetch attestation',
-            isActionable: true
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'error',
-            nextStep: CCTPv2StepName.burn,
-            reason: 'Retry failed burn',
-            isActionable: true
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'pending',
-            nextStep: CCTPv2StepName.burn,
-            reason: 'Continue pending burn',
-            isActionable: false
-        }
-    ],
-    // After FetchAttestation step
-    [CCTPv2StepName.fetchAttestation]: [
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'success',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Attestation fetched, proceed to mint',
-            isActionable: true
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'error',
-            nextStep: CCTPv2StepName.fetchAttestation,
-            reason: 'Retry fetching attestation',
-            isActionable: true
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'pending',
-            nextStep: CCTPv2StepName.fetchAttestation,
-            reason: 'Continue pending attestation fetch',
-            isActionable: false
-        }
-    ],
-    // After Mint step
-    [CCTPv2StepName.mint]: [
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'success',
-            nextStep: null,
-            reason: 'Bridge completed successfully',
-            isActionable: false
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'error',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Retry failed mint',
-            isActionable: true
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'pending',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Continue pending mint',
-            isActionable: false
-        }
-    ],
-    // After ReAttest step
-    [CCTPv2StepName.reAttest]: [
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'success',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Re-attestation successful, proceed to mint',
-            isActionable: true
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'error',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Re-attestation failed, retry mint to re-initiate recovery',
-            isActionable: true
-        },
-        {
-            condition: (ctx)=>ctx.lastStep?.state === 'pending',
-            nextStep: CCTPv2StepName.mint,
-            reason: 'Re-attestation pending, retry mint to re-initiate recovery',
-            isActionable: true
+        resolvedAddress = ctx.address;
+    } else {
+        // User-controlled: get current address from adapter
+        try {
+            // Pass resolved chain to getAddress for adapters that support it (like ViemAdapter)
+            // The chain parameter is optional in implementations, so this is safe
+            resolvedAddress = await adapter.getAddress(resolvedChain);
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to resolve address from user-controlled adapter: ${message}`);
         }
-    ]
-};
+    }
+    return {
+        chain: resolvedChain,
+        address: resolvedAddress
+    };
+}
+
 /**
- * Analyze bridge steps to determine retry feasibility and continuation point.
+ * Schema for validating hexadecimal strings with '0x' prefix.
  *
- * This function examines the current state of bridge steps to determine the optimal
- * continuation strategy. It uses a rule-based approach that makes it easy to extend
- * with new flow patterns and step types in the future.
+ * This schema validates that a string:
+ * - Is a string type
+ * - Is not empty after trimming
+ * - Starts with '0x'
+ * - Contains only valid hexadecimal characters (0-9, a-f, A-F) after '0x'
  *
- * The current analysis supports the standard CCTP flow:
- * **Traditional flow**: Approve → Burn → FetchAttestation → Mint
+ * @remarks
+ * This schema does not validate length, making it suitable for various hex string types
+ * like addresses, transaction hashes, and other hex-encoded data.
  *
- * Key features:
- * - Rule-based transitions: Easy to extend with new step types and logic
- * - Context-aware decisions: Considers execution history and step states
- * - Actionable logic: Distinguishes between steps requiring user action vs waiting
- * - Terminal states: Properly handles completion and non-actionable states
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
- * @param bridgeResult - The bridge result containing step execution history.
- * @returns Analysis result with continuation step and actionability information.
- * @throws Error when bridgeResult is invalid or contains no steps array.
+ * @example
+ * ```typescript
+ * import { hexStringSchema } from '@core/adapter'
+ *
+ * const validAddress = '0x1234567890123456789012345678901234567890'
+ * const validTxHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+ *
+ * const addressResult = hexStringSchema.safeParse(validAddress)
+ * const txHashResult = hexStringSchema.safeParse(validTxHash)
+ * console.log(addressResult.success) // true
+ * console.log(txHashResult.success) // true
+ * ```
+ */ const hexStringSchema = zod.z.string().min(1, 'Hex string is required').refine((value)=>value.trim().length > 0, 'Hex string cannot be empty').refine((value)=>value.startsWith('0x'), 'Hex string must start with 0x prefix').refine((value)=>{
+    const hexPattern = /^0x[0-9a-fA-F]+$/;
+    return hexPattern.test(value);
+}, 'Hex string contains invalid characters. Only hexadecimal characters (0-9, a-f, A-F) are allowed after 0x');
+/**
+ * Schema for validating EVM addresses.
+ *
+ * This schema validates that a string is a properly formatted EVM address:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 42 characters long (0x + 40 hex characters)
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * import { analyzeSteps } from './analyzeSteps'
+ * import { evmAddressSchema } from '@core/adapter'
  *
- * // Failed approval step (requires user action)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'error', errorMessage: 'User rejected' }
- *   ]
- * }
+ * const validAddress = '0x1234567890123456789012345678901234567890'
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: 'Approve', isRetryable: true,
- * //          reason: 'Retry failed approval' }
+ * const result = evmAddressSchema.safeParse(validAddress)
+ * console.log(result.success) // true
  * ```
+ */ const evmAddressSchema = hexStringSchema.refine((value)=>value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)').transform((value)=>value);
+/**
+ * Schema for validating transaction hashes.
+ *
+ * This schema validates that a string is a properly formatted transaction hash:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 66 characters long (0x + 64 hex characters)
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * // Pending transaction (requires waiting, not actionable)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'pending' }
- *   ]
- * }
+ * import { evmTransactionHashSchema } from '@core/adapter'
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: 'Approve', isRetryable: false,
- * //          reason: 'Continue pending approval' }
+ * const validTxHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+ *
+ * const result = evmTransactionHashSchema.safeParse(validTxHash)
+ * console.log(result.success) // true
  * ```
+ */ hexStringSchema.refine((value)=>value.length === 66, 'Transaction hash must be exactly 66 characters long (0x + 64 hex characters)');
+/**
+ * Schema for validating EVM signatures.
+ *
+ * This schema validates that a string is a properly formatted 65-byte EVM
+ * signature:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 132 characters long (0x + 130 hex characters)
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * // Completed bridge (nothing to do)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'success' },
- *     { name: 'Burn', state: 'success' },
- *     { name: 'FetchAttestation', state: 'success' },
- *     { name: 'Mint', state: 'success' }
- *   ]
- * }
+ * import { evmSignatureSchema } from '@core/adapter'
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: null, isRetryable: false,
- * //          reason: 'Bridge completed successfully' }
+ * const validSignature = `0x${'ab'.repeat(65)}`
+ *
+ * const result = evmSignatureSchema.safeParse(validSignature)
+ * console.log(result.success) // true
  * ```
- */ const analyzeSteps = (bridgeResult)=>{
-    // Input validation
-    if (!bridgeResult || !Array.isArray(bridgeResult.steps)) {
-        throw new Error('Invalid bridgeResult: must contain a steps array');
-    }
-    const { steps } = bridgeResult;
-    // Build execution context from step history
-    const context = buildFlowContext(steps);
-    // Determine continuation logic using rule engine
-    const continuation = determineContinuationFromRules(context);
-    return {
-        continuationStep: continuation.nextStep,
-        isActionable: continuation.isActionable,
-        completedSteps: Array.from(context.completedSteps),
-        failedSteps: Array.from(context.failedSteps),
-        reason: continuation.reason
-    };
-};
+ */ hexStringSchema.refine((value)=>value.length === 132, 'EVM signature must be exactly 132 characters long (0x + 130 hex characters)').transform((value)=>value);
 /**
- * Build flow context from the execution history.
+ * Schema for validating base58-encoded strings.
  *
- * @param steps - Array of executed bridge steps.
- * @returns Flow context with execution state and history.
- */ function buildFlowContext(steps) {
-    const completedSteps = new Set();
-    const failedSteps = new Set();
-    let lastStep;
-    // Process step history to build context
-    for (const step of steps){
-        if (step.state === 'success' || step.state === 'noop') {
-            completedSteps.add(step.name);
-        } else if (step.state === 'error') {
-            failedSteps.add(step.name);
-        }
-        // Track the last step for continuation logic
-        lastStep = {
-            name: step.name,
-            state: step.state
-        };
-    }
-    return {
-        completedSteps,
-        failedSteps,
-        ...lastStep && {
-            lastStep
-        }
-    };
-}
-/**
- * Determine continuation step using the rule engine.
+ * This schema validates that a string:
+ * - Is a string type
+ * - Is not empty after trimming
+ * - Contains only valid base58 characters (1-9, A-H, J-N, P-Z, a-k, m-z)
+ * - Does not contain commonly confused characters (0, O, I, l)
  *
- * @param context - The flow context with execution history.
- * @returns Continuation decision with next step and actionability information.
- */ function determineContinuationFromRules(context) {
-    const lastStepName = context.lastStep?.name;
-    // Handle initial state when no steps have been executed
-    if (lastStepName === undefined) {
-        const rules = STEP_TRANSITION_RULES[''];
-        const matchingRule = rules?.find((rule)=>rule.condition(context));
-        if (!matchingRule) {
-            return {
-                nextStep: null,
-                isActionable: false,
-                reason: 'No initial state rule found'
-            };
-        }
-        return {
-            nextStep: matchingRule.nextStep,
-            isActionable: matchingRule.isActionable,
-            reason: matchingRule.reason
-        };
-    }
-    // A step with an empty name is ambiguous and should be treated as an unrecoverable state.
-    if (lastStepName === '') {
-        return {
-            nextStep: null,
-            isActionable: false,
-            reason: 'No transition rules defined for step with empty name'
-        };
-    }
-    const rules = STEP_TRANSITION_RULES[lastStepName];
-    if (!rules) {
-        return {
-            nextStep: null,
-            isActionable: false,
-            reason: `No transition rules defined for step: ${lastStepName}`
-        };
-    }
-    // Find the first matching rule
-    const matchingRule = rules.find((rule)=>rule.condition(context));
-    if (!matchingRule) {
-        return {
-            nextStep: null,
-            isActionable: false,
-            reason: `No matching transition rule for current context`
-        };
-    }
-    return {
-        nextStep: matchingRule.nextStep,
-        isActionable: matchingRule.isActionable,
-        reason: matchingRule.reason
-    };
-}
-
-/**
- * Find a step by name in the bridge result.
+ * @remarks
+ * This schema does not validate length, making it suitable for various base58-encoded data
+ * like Solana addresses, transaction signatures, and other base58-encoded data.
  *
- * @param result - The bridge result to search.
- * @param stepName - The name of the step to find.
- * @returns The step if found, undefined otherwise.
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * import { findStepByName } from './findStep'
+ * import { base58StringSchema } from '@core/adapter'
  *
- * const burnStep = findStepByName(result, 'burn')
- * if (burnStep) {
- *   console.log('Burn tx:', burnStep.txHash)
- * }
+ * const validAddress = 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN'
+ * const validTxHash = '3Jf8k2L5mN9pQ7rS1tV4wX6yZ8aB2cD4eF5gH7iJ9kL1mN3oP5qR7sT9uV1wX3yZ5'
+ *
+ * const addressResult = base58StringSchema.safeParse(validAddress)
+ * const txHashResult = base58StringSchema.safeParse(validTxHash)
+ * console.log(addressResult.success) // true
+ * console.log(txHashResult.success) // true
  * ```
- */ function findStepByName(result, stepName) {
-    return result.steps.find((step)=>step.name === stepName);
-}
+ */ const base58StringSchema = zod.z.string().min(1, 'Base58 string is required').refine((value)=>value.trim().length > 0, 'Base58 string cannot be empty').refine((value)=>{
+    // Base58 alphabet: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
+    // Excludes: 0, O, I, l to avoid confusion
+    const base58Pattern = /^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$/;
+    return base58Pattern.test(value);
+}, 'Base58 string contains invalid characters. Only base58 characters (1-9, A-H, J-N, P-Z, a-k, m-z) are allowed');
 /**
- * Find a pending step by name and return it with its index.
+ * Schema for validating Solana addresses.
  *
- * Searches for a step that matches both the step name and has a pending state.
+ * This schema validates that a string is a properly formatted Solana address:
+ * - Must be a valid base58-encoded string
+ * - Must be between 32-44 characters long (typical length for base58-encoded 32-byte addresses)
  *
- * @param result - The bridge result containing steps to search through.
- * @param stepName - The step name to find (e.g., 'burn', 'mint', 'fetchAttestation').
- * @returns An object containing the step and its index in the steps array.
- * @throws KitError if the specified pending step is not found.
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * import { findPendingStep } from './findStep'
+ * import { solanaAddressSchema } from '@core/adapter'
  *
- * const { step, index } = findPendingStep(result, 'burn')
- * console.log('Pending step:', step.name, 'at index:', index)
+ * const validAddress = 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN'
+ *
+ * const result = solanaAddressSchema.safeParse(validAddress)
+ * console.log(result.success) // true
  * ```
- */ function findPendingStep(result, stepName) {
-    const index = result.steps.findIndex((step)=>step.name === stepName && step.state === 'pending');
-    if (index === -1) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: `Pending step "${stepName}" not found in result`
-        });
-    }
-    const step = result.steps[index];
-    if (!step) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'Pending step is undefined'
-        });
-    }
-    return {
-        step,
-        index
-    };
-}
+ */ base58StringSchema.refine((value)=>value.length >= 32 && value.length <= 44, 'Solana address must be between 32-44 characters long (base58-encoded 32-byte address)');
 /**
- * Get the burn transaction hash from bridge result.
+ * Schema for validating Solana transaction hashes.
  *
- * @param result - The bridge result.
- * @returns The burn transaction hash, or undefined if not found.
+ * This schema validates that a string is a properly formatted Solana transaction hash:
+ * - Must be a valid base58-encoded string
+ * - Must be between 86-88 characters long (typical length for base58-encoded 64-byte signatures)
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * import { getBurnTxHash } from './findStep'
+ * import { solanaTransactionHashSchema } from '@core/adapter'
  *
- * const burnTxHash = getBurnTxHash(result)
- * if (burnTxHash) {
- *   console.log('Burn tx hash:', burnTxHash)
- * }
+ * const validTxHash = '5VfYmGBjvQKe3xgLtTQPSMEUdpEVHrJwLK7pKBJWKzYpNBE2g3kJrq7RSe9M8DqzQJ5J2aZPTjHLvd4WgxPpJKS'
+ *
+ * const result = solanaTransactionHashSchema.safeParse(validTxHash)
+ * console.log(result.success) // true
  * ```
- */ function getBurnTxHash(result) {
-    return findStepByName(result, CCTPv2StepName.burn)?.txHash;
-}
+ */ base58StringSchema.refine((value)=>value.length >= 86 && value.length <= 88, 'Solana transaction hash must be between 86-88 characters long (base58-encoded 64-byte signature)');
 /**
- * Get the attestation data from bridge result.
+ * Schema for validating Adapter objects.
+ * Checks for the required methods that define an Adapter.
+ */ zod.z.object({
+    prepare: zod.z.function(),
+    waitForTransaction: zod.z.function(),
+    getAddress: zod.z.function()
+});
+
+/**
+ * Validate that the adapter has sufficient token balance for a transaction.
  *
- * @param result - The bridge result.
- * @returns The attestation data, or undefined if not found.
+ * This function checks if the adapter's current token balance is greater than or equal
+ * to the requested transaction amount. It throws a KitError with code 9001
+ * (BALANCE_INSUFFICIENT_TOKEN) if the balance is insufficient, providing detailed
+ * information about the shortfall.
+ *
+ * @param params - The validation parameters containing adapter, amount, token, and token address.
+ * @returns A promise that resolves to void if validation passes.
+ * @throws {KitError} When the adapter's balance is less than the required amount (code: 9001).
  *
  * @example
  * ```typescript
- * import { getAttestationData } from './findStep'
+ * import { validateBalanceForTransaction } from '@core/adapter'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ * import { isKitError, ERROR_TYPES } from '@core/errors'
  *
- * const attestation = getAttestationData(result)
- * if (attestation) {
- *   console.log('Attestation:', attestation.message)
+ * const adapter = createViemAdapterFromPrivateKey({
+ *   privateKey: '0x...',
+ *   chain: 'Ethereum',
+ * })
+ *
+ * try {
+ *   await validateBalanceForTransaction({
+ *     adapter,
+ *     amount: '1000000', // 1 USDC (6 decimals)
+ *     token: 'USDC',
+ *     tokenAddress: '0xA0b86a33E6441c8C1c7C16e4c5e3e5b5e4c5e3e5b5e4c5e',
+ *     operationContext: { chain: 'Ethereum' },
+ *   })
+ *   console.log('Balance validation passed')
+ * } catch (error) {
+ *   if (isKitError(error) && error.type === ERROR_TYPES.BALANCE) {
+ *     console.error('Insufficient funds:', error.message)
+ *   }
  * }
  * ```
- */ function getAttestationData(result) {
-    // Prefer reAttest data (most recent attestation after expiry)
-    const reAttestStep = findStepByName(result, CCTPv2StepName.reAttest);
-    if (reAttestStep?.state === 'success' && reAttestStep.data) {
-        return reAttestStep.data;
+ */ const validateBalanceForTransaction = async (params)=>{
+    const { amount, adapter, token, tokenAddress, operationContext } = params;
+    const balancePrepared = await adapter.prepareAction('usdc.balanceOf', {
+        walletAddress: operationContext.address
+    }, operationContext);
+    const balance = await balancePrepared.execute();
+    if (BigInt(balance) < BigInt(amount)) {
+        // Extract chain name from operationContext
+        const chainName = extractChainInfo(operationContext.chain).name;
+        // Create KitError with rich context in trace
+        throw createInsufficientTokenBalanceError(chainName, token, {
+            balance: balance.toString(),
+            amount,
+            tokenAddress,
+            walletAddress: operationContext.address
+        });
     }
-    // Fall back to fetchAttestation step
-    const fetchStep = findStepByName(result, CCTPv2StepName.fetchAttestation);
-    return fetchStep?.data;
-}
+};
 
 /**
- * Check if the analysis indicates a non-actionable pending state.
+ * Permit signature standards for gasless token approvals.
  *
- * A pending state is non-actionable when there's a continuation step but
- * the analysis marks it as not actionable, typically because we need to
- * wait for an ongoing operation to complete.
+ * Defines the permit types that can be used to approve token spending
+ * without requiring a separate approval transaction.
  *
- * @param analysis - The step analysis result from analyzeSteps.
- * @param result - The bridge result to check for pending steps.
- * @returns True if there is a pending step that we should wait for.
+ * @remarks
+ * - NONE: No permit, tokens must be pre-approved via separate transaction
+ * - EIP2612: Standard ERC-20 permit (USDC, DAI v2, and most modern tokens)
+ */ var PermitType;
+(function(PermitType) {
+    /** No permit required - tokens must be pre-approved */ PermitType[PermitType["NONE"] = 0] = "NONE";
+    /** EIP-2612 standard permit */ PermitType[PermitType["EIP2612"] = 1] = "EIP2612";
+})(PermitType || (PermitType = {}));
+
+/**
+ * Assert that `params` is a well-formed {@link BurnWithFeesParams} object.
  *
- * @example
- * ```typescript
- * import { hasPendingState } from './stepUtils'
- * import { analyzeSteps } from '../analyzeSteps'
+ * Validates the full public-boundary input before any field destructuring,
+ * `BigInt()` coercion, or adapter preparation runs, so malformed JS-caller
+ * inputs always produce typed `KitError` validation failures.
  *
- * const analysis = analyzeSteps(bridgeResult)
- * if (hasPendingState(analysis, bridgeResult)) {
- *   // Wait for the pending operation to complete
- * }
- * ```
- */ /**
- * Evaluate a transaction receipt and return the corresponding step state
- * and error message. Centralises the success/revert/unconfirmed logic so
- * every call-site behaves identically.
+ * Checks performed (in order):
+ * - `params` must be a non-null plain object
+ * - `source` — valid CCTP v2 wallet context (via `assertCCTPv2WalletContext`)
+ * - `destinationChain` — present and supports CCTP v2
+ * - source and destination chains must both be testnet or both mainnet
+ * - source and destination chains must differ
+ * - `executor` — non-empty string
+ * - `amount` — bigint or non-empty string coercible to bigint
+ * - `feeTotalAmount` — bigint or non-empty string coercible to bigint
+ * - `feeToken` — valid EVM address (`0x` + 40 hex chars)
+ * - `claim.signedQuote` — valid `0x`-prefixed hex string
+ * - `claim.refundAddress` — valid EVM address
+ * - `hookData` — valid `0x`-prefixed hex string when present
  *
- * @param receipt - The transaction receipt containing status and block info.
- * @param txHash - The transaction hash used in error messages.
- * @returns An object with `state` and an optional `errorMessage`.
+ * @param params - The value to validate.
+ * @throws {KitError} If any field is missing or invalid.
  *
  * @example
  * ```typescript
- * const outcome = evaluateTransactionOutcome(receipt, '0xabc...')
- * step.state = outcome.state
- * if (outcome.errorMessage) step.errorMessage = outcome.errorMessage
+ * assertBurnWithFeesParams(params)
+ * // params is now typed as BurnWithFeesParams and safe to use
+ * const { source, destinationChain, amount } = params
  * ```
- */ function evaluateTransactionOutcome(receipt, txHash) {
-    if (receipt.status === 'success' && receipt.blockNumber) {
-        return {
-            state: 'success'
-        };
+ */ function assertBurnWithFeesParams(params) {
+    if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+        throw createValidationFailedError('params', params, 'Must be a non-null plain object');
     }
-    return {
-        state: 'error',
-        errorMessage: receipt.status === 'reverted' ? `Transaction ${txHash} was reverted` : 'Transaction was not confirmed on-chain'
-    };
-}
-function hasPendingState(analysis, result) {
-    // Check if there's a continuation step that's marked as non-actionable
-    if (analysis.continuationStep === null || analysis.isActionable) {
-        return false;
+    const p = params;
+    // Source wallet context
+    assertCCTPv2WalletContext(p['source']);
+    const source = p['source'];
+    // destinationChain
+    const destinationChain = p['destinationChain'];
+    if (destinationChain === null || destinationChain === undefined || typeof destinationChain !== 'object') {
+        throw createValidationFailedError('destinationChain', destinationChain, 'Must be a chain definition object');
+    }
+    if (!isCCTPV2Supported(destinationChain)) {
+        throw createValidationFailedError('destinationChain', destinationChain, 'destinationChain must support CCTP v2');
+    }
+    const dest = destinationChain;
+    // Testnet / mainnet mismatch
+    if (source.chain.isTestnet !== dest.isTestnet) {
+        throw createNetworkMismatchError(source.chain, dest);
+    }
+    // Same-chain guard
+    if (source.chain.name === dest.name) {
+        throw createUnsupportedRouteError(source.chain.name, dest.name);
+    }
+    // executor
+    const executor = p['executor'];
+    if (typeof executor !== 'string' || executor === '') {
+        throw createValidationFailedError('executor', executor, 'A GenericExecutor address is required (used for both mintRecipient and destinationCaller)');
+    }
+    // amount
+    const rawAmount = p['amount'];
+    if (typeof rawAmount !== 'bigint' && typeof rawAmount !== 'string' || rawAmount === '') {
+        throw createValidationFailedError('amount', rawAmount, 'Must be a bigint or a numeric string');
+    }
+    try {
+        BigInt(rawAmount);
+    } catch  {
+        throw createValidationFailedError('amount', rawAmount, 'Must be a valid integer value coercible to bigint');
+    }
+    // feeTotalAmount
+    const rawFee = p['feeTotalAmount'];
+    if (typeof rawFee !== 'bigint' && typeof rawFee !== 'string' || rawFee === '') {
+        throw createValidationFailedError('feeTotalAmount', rawFee, 'Must be a bigint or a numeric string');
+    }
+    try {
+        BigInt(rawFee);
+    } catch  {
+        throw createValidationFailedError('feeTotalAmount', rawFee, 'Must be a valid integer value coercible to bigint');
+    }
+    // feeToken
+    if (!evmAddressSchema.safeParse(p['feeToken']).success) {
+        throw createValidationFailedError('feeToken', p['feeToken'], 'Must be a valid EVM address (use the zero address for a native fee)');
+    }
+    // claim
+    const rawClaim = p['claim'];
+    if (rawClaim === null || typeof rawClaim !== 'object' || Array.isArray(rawClaim)) {
+        throw createValidationFailedError('claim', rawClaim, 'Must be an object with signedQuote and refundAddress');
+    }
+    const claim = rawClaim;
+    if (!hexStringSchema.safeParse(claim['signedQuote']).success) {
+        throw createValidationFailedError('claim.signedQuote', claim['signedQuote'], 'Must be a valid hex string starting with 0x');
+    }
+    if (!evmAddressSchema.safeParse(claim['refundAddress']).success) {
+        throw createValidationFailedError('claim.refundAddress', claim['refundAddress'], 'Must be a valid EVM address');
+    }
+    // hookData (optional)
+    const hookData = p['hookData'];
+    if (hookData !== undefined && hookData !== '' && !hexStringSchema.safeParse(hookData).success) {
+        throw createValidationFailedError('hookData', hookData, 'Must be a valid hex string starting with 0x');
     }
-    // Verify that the continuation step actually exists and is in pending state
-    const pendingStep = result.steps.find((step)=>step.name === analysis.continuationStep && step.state === 'pending');
-    return pendingStep !== undefined;
 }
+
 /**
- * Check if the step is the last one in the execution flow.
- *
- * @param step - The step object to check.
- * @param stepNames - The ordered list of step names in the execution flow.
- * @returns True if this is the last step in the flow.
+ * CCTP bridge step names that can occur in the bridging flow.
  *
- * @example
- * ```typescript
- * import { isLastStep } from './stepUtils'
+ * This object provides type safety for step names and represents all possible
+ * steps that can be executed during a CCTP bridge operation. Using const assertions
+ * makes this tree-shakable and follows modern TypeScript best practices.
+ */ const CCTPv2StepName = {
+    approve: 'approve',
+    burn: 'burn',
+    fetchAttestation: 'fetchAttestation',
+    mint: 'mint',
+    reAttest: 'reAttest'
+};
+/**
+ * Conditional step transition rules for CCTP bridge flow.
  *
- * const stepNames = ['approve', 'burn', 'fetchAttestation', 'mint']
- * isLastStep({ name: 'mint' }, stepNames) // true
- * isLastStep({ name: 'burn' }, stepNames) // false
- * ```
- */ function isLastStep(step, stepNames) {
-    const stepIndex = stepNames.indexOf(step.name);
-    return stepIndex === -1 || stepIndex >= stepNames.length - 1;
-}
+ * Rules are evaluated in order - the first matching condition determines the next step.
+ * This approach supports flexible flow logic and makes it easy to extend with new patterns.
+ */ const STEP_TRANSITION_RULES = {
+    // Starting state - no steps executed yet
+    '': [
+        {
+            condition: ()=>true,
+            nextStep: CCTPv2StepName.approve,
+            reason: 'Start with approval step',
+            isActionable: true
+        }
+    ],
+    // After Approve step
+    [CCTPv2StepName.approve]: [
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'success',
+            nextStep: CCTPv2StepName.burn,
+            reason: 'Approval successful, proceed to burn',
+            isActionable: true
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'error',
+            nextStep: CCTPv2StepName.approve,
+            reason: 'Retry failed approval',
+            isActionable: true
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'noop',
+            nextStep: CCTPv2StepName.burn,
+            reason: 'No approval needed, proceed to burn',
+            isActionable: true
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'pending',
+            nextStep: CCTPv2StepName.approve,
+            reason: 'Continue pending approval',
+            isActionable: false
+        }
+    ],
+    // After Burn step
+    [CCTPv2StepName.burn]: [
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'success',
+            nextStep: CCTPv2StepName.fetchAttestation,
+            reason: 'Burn successful, fetch attestation',
+            isActionable: true
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'error',
+            nextStep: CCTPv2StepName.burn,
+            reason: 'Retry failed burn',
+            isActionable: true
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'pending',
+            nextStep: CCTPv2StepName.burn,
+            reason: 'Continue pending burn',
+            isActionable: false
+        }
+    ],
+    // After FetchAttestation step
+    [CCTPv2StepName.fetchAttestation]: [
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'success',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Attestation fetched, proceed to mint',
+            isActionable: true
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'error',
+            nextStep: CCTPv2StepName.fetchAttestation,
+            reason: 'Retry fetching attestation',
+            isActionable: true
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'pending',
+            nextStep: CCTPv2StepName.fetchAttestation,
+            reason: 'Continue pending attestation fetch',
+            isActionable: false
+        }
+    ],
+    // After Mint step
+    [CCTPv2StepName.mint]: [
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'success',
+            nextStep: null,
+            reason: 'Bridge completed successfully',
+            isActionable: false
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'error',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Retry failed mint',
+            isActionable: true
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'pending',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Continue pending mint',
+            isActionable: false
+        }
+    ],
+    // After ReAttest step
+    [CCTPv2StepName.reAttest]: [
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'success',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Re-attestation successful, proceed to mint',
+            isActionable: true
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'error',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Re-attestation failed, retry mint to re-initiate recovery',
+            isActionable: true
+        },
+        {
+            condition: (ctx)=>ctx.lastStep?.state === 'pending',
+            nextStep: CCTPv2StepName.mint,
+            reason: 'Re-attestation pending, retry mint to re-initiate recovery',
+            isActionable: true
+        }
+    ]
+};
 /**
- * Wait for a pending transaction to complete.
+ * Analyze bridge steps to determine retry feasibility and continuation point.
  *
- * Poll the adapter until the transaction is confirmed on-chain and return
- * the updated step with success or error state based on the receipt.
+ * This function examines the current state of bridge steps to determine the optimal
+ * continuation strategy. It uses a rule-based approach that makes it easy to extend
+ * with new flow patterns and step types in the future.
  *
- * @param pendingStep - The full step object containing the transaction hash.
- * @param adapter - The adapter to use for waiting.
- * @param chain - The chain where the transaction was submitted.
- * @returns The updated step object with success or error state.
+ * The current analysis supports the standard CCTP flow:
+ * **Traditional flow**: Approve → Burn → FetchAttestation → Mint
  *
- * @throws KitError when the pending step has no transaction hash.
+ * Key features:
+ * - Rule-based transitions: Easy to extend with new step types and logic
+ * - Context-aware decisions: Considers execution history and step states
+ * - Actionable logic: Distinguishes between steps requiring user action vs waiting
+ * - Terminal states: Properly handles completion and non-actionable states
+ *
+ * @param bridgeResult - The bridge result containing step execution history.
+ * @returns Analysis result with continuation step and actionability information.
+ * @throws Error when bridgeResult is invalid or contains no steps array.
  *
  * @example
  * ```typescript
- * import { waitForPendingTransaction } from './bridgeStepUtils'
+ * import { analyzeSteps } from './analyzeSteps'
  *
- * const pendingStep = { name: 'burn', state: 'pending', txHash: '0x123...' }
- * const updatedStep = await waitForPendingTransaction(pendingStep, adapter, chain)
- * // updatedStep.state is now 'success' or 'error'
+ * // Failed approval step (requires user action)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'error', errorMessage: 'User rejected' }
+ *   ]
+ * }
+ *
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: 'Approve', isRetryable: true,
+ * //          reason: 'Retry failed approval' }
  * ```
- */ async function waitForPendingTransaction(pendingStep, adapter, chain) {
-    if (!pendingStep.txHash) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: `Cannot wait for pending ${pendingStep.name}: no transaction hash available`
-        });
-    }
-    const txHash = pendingStep.txHash;
-    const txReceipt = await retryAsync(async ()=>adapter.waitForTransaction(txHash, undefined, chain), {
-        isRetryable: (err)=>isRetryableError$1(parseBlockchainError(err, {
-                chain: chain.name,
-                txHash
-            }))
-    });
-    const outcome = evaluateTransactionOutcome(txReceipt, txHash);
-    return {
-        ...pendingStep,
-        state: outcome.state,
-        data: txReceipt,
-        explorerUrl: buildExplorerUrl(chain, txHash),
-        ...outcome.errorMessage ? {
-            errorMessage: outcome.errorMessage
-        } : {}
-    };
-}
-/**
- * Wait for a pending step to complete.
  *
- * For transaction steps: waits for the transaction to be confirmed.
- * For attestation: re-executes the attestation fetch.
- *
- * @typeParam TFromAdapterCapabilities - The capabilities of the source adapter.
- * @typeParam TToAdapterCapabilities - The capabilities of the destination adapter.
- * @param pendingStep - The full step object (with name, state, txHash, data, etc.) to resolve.
- * @param adapter - The adapter to use.
- * @param chain - The chain where the step is executing.
- * @param context - The retry context.
- * @param result - The bridge result.
- * @param provider - The CCTP v2 bridging provider.
- * @returns The resolved step object with updated state.
+ * @example
+ * ```typescript
+ * // Pending transaction (requires waiting, not actionable)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'pending' }
+ *   ]
+ * }
  *
- * @throws KitError when fetching attestation but burn transaction hash is not found.
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: 'Approve', isRetryable: false,
+ * //          reason: 'Continue pending approval' }
+ * ```
  *
  * @example
  * ```typescript
- * import { waitForStepToComplete } from './bridgeStepUtils'
+ * // Completed bridge (nothing to do)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'success' },
+ *     { name: 'Burn', state: 'success' },
+ *     { name: 'FetchAttestation', state: 'success' },
+ *     { name: 'Mint', state: 'success' }
+ *   ]
+ * }
  *
- * const pendingStep = { name: 'burn', state: 'pending', txHash: '0x123...' }
- * const updatedStep = await waitForStepToComplete(
- *   pendingStep,
- *   adapter,
- *   chain,
- *   context,
- *   result,
- *   provider,
- * )
- * // updatedStep.state is now 'success' or 'error'
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: null, isRetryable: false,
+ * //          reason: 'Bridge completed successfully' }
  * ```
- */ async function waitForStepToComplete(pendingStep, adapter, chain, context, result, provider) {
-    if (pendingStep.name === CCTPv2StepName.fetchAttestation) {
-        // For attestation, re-run the fetch (it has built-in polling)
-        const burnTxHash = getBurnTxHash(result);
-        if (!burnTxHash) {
-            throw new KitError({
-                ...InputError.VALIDATION_FAILED,
-                recoverability: 'FATAL',
-                message: 'Cannot fetch attestation: burn transaction hash not found'
-            });
+ */ const analyzeSteps = (bridgeResult)=>{
+    // Input validation
+    if (!bridgeResult || !Array.isArray(bridgeResult.steps)) {
+        throw new Error('Invalid bridgeResult: must contain a steps array');
+    }
+    const { steps } = bridgeResult;
+    // Build execution context from step history
+    const context = buildFlowContext(steps);
+    // Determine continuation logic using rule engine
+    const continuation = determineContinuationFromRules(context);
+    return {
+        continuationStep: continuation.nextStep,
+        isActionable: continuation.isActionable,
+        completedSteps: Array.from(context.completedSteps),
+        failedSteps: Array.from(context.failedSteps),
+        reason: continuation.reason
+    };
+};
+/**
+ * Build flow context from the execution history.
+ *
+ * @param steps - Array of executed bridge steps.
+ * @returns Flow context with execution state and history.
+ */ function buildFlowContext(steps) {
+    const completedSteps = new Set();
+    const failedSteps = new Set();
+    let lastStep;
+    // Process step history to build context
+    for (const step of steps){
+        if (step.state === 'success' || step.state === 'noop') {
+            completedSteps.add(step.name);
+        } else if (step.state === 'error') {
+            failedSteps.add(step.name);
+        }
+        // Track the last step for continuation logic
+        lastStep = {
+            name: step.name,
+            state: step.state
+        };
+    }
+    return {
+        completedSteps,
+        failedSteps,
+        ...lastStep && {
+            lastStep
+        }
+    };
+}
+/**
+ * Determine continuation step using the rule engine.
+ *
+ * @param context - The flow context with execution history.
+ * @returns Continuation decision with next step and actionability information.
+ */ function determineContinuationFromRules(context) {
+    const lastStepName = context.lastStep?.name;
+    // Handle initial state when no steps have been executed
+    if (lastStepName === undefined) {
+        const rules = STEP_TRANSITION_RULES[''];
+        const matchingRule = rules?.find((rule)=>rule.condition(context));
+        if (!matchingRule) {
+            return {
+                nextStep: null,
+                isActionable: false,
+                reason: 'No initial state rule found'
+            };
         }
-        const sourceAddress = result.source.address;
-        const attestation = await provider.fetchAttestation({
-            chain: result.source.chain,
-            adapter: context.from,
-            address: sourceAddress
-        }, burnTxHash);
         return {
-            ...pendingStep,
-            state: 'success',
-            data: attestation
+            nextStep: matchingRule.nextStep,
+            isActionable: matchingRule.isActionable,
+            reason: matchingRule.reason
         };
     }
-    // For transaction steps, wait for the transaction to complete
-    return waitForPendingTransaction(pendingStep, adapter, chain);
+    // A step with an empty name is ambiguous and should be treated as an unrecoverable state.
+    if (lastStepName === '') {
+        return {
+            nextStep: null,
+            isActionable: false,
+            reason: 'No transition rules defined for step with empty name'
+        };
+    }
+    const rules = STEP_TRANSITION_RULES[lastStepName];
+    if (!rules) {
+        return {
+            nextStep: null,
+            isActionable: false,
+            reason: `No transition rules defined for step: ${lastStepName}`
+        };
+    }
+    // Find the first matching rule
+    const matchingRule = rules.find((rule)=>rule.condition(context));
+    if (!matchingRule) {
+        return {
+            nextStep: null,
+            isActionable: false,
+            reason: `No matching transition rule for current context`
+        };
+    }
+    return {
+        nextStep: matchingRule.nextStep,
+        isActionable: matchingRule.isActionable,
+        reason: matchingRule.reason
+    };
 }
 
 /**
- * Executes a prepared chain request and returns the result as a bridge step.
+ * Find a step by name in the bridge result.
  *
- * This function takes a prepared chain request (containing transaction data) and executes
- * it using the appropriate adapter. It handles the execution details and formats
- * the result as a standardized bridge step with transaction details and explorer URLs.
+ * @param result - The bridge result to search.
+ * @param stepName - The name of the step to find.
+ * @returns The step if found, undefined otherwise.
  *
- * @param params - The execution parameters containing:
- *   - `name`: The name of the step
- *   - `request`: The prepared chain request containing transaction data
- *   - `adapter`: The adapter that will execute the transaction
- *   - `confirmations`: The number of confirmations to wait for (defaults to 1)
- *   - `timeout`: The timeout for the request in milliseconds
- * @returns The bridge step with the transaction details and explorer URL
- * @throws If the transaction execution fails
+ * @example
+ * ```typescript
+ * import { findStepByName } from './findStep'
+ *
+ * const burnStep = findStepByName(result, 'burn')
+ * if (burnStep) {
+ *   console.log('Burn tx:', burnStep.txHash)
+ * }
+ * ```
+ */ function findStepByName(result, stepName) {
+    return result.steps.find((step)=>step.name === stepName);
+}
+/**
+ * Find a pending step by name and return it with its index.
+ *
+ * Searches for a step that matches both the step name and has a pending state.
+ *
+ * @param result - The bridge result containing steps to search through.
+ * @param stepName - The step name to find (e.g., 'burn', 'mint', 'fetchAttestation').
+ * @returns An object containing the step and its index in the steps array.
+ * @throws KitError if the specified pending step is not found.
  *
  * @example
  * ```typescript
- * const step = await executePreparedChainRequest({
- *   name: 'approve',
- *   request: preparedRequest,
- *   adapter: adapter,
- *   confirmations: 2,
- *   timeout: 30000
- * })
- * console.log('Transaction hash:', step.txHash)
+ * import { findPendingStep } from './findStep'
+ *
+ * const { step, index } = findPendingStep(result, 'burn')
+ * console.log('Pending step:', step.name, 'at index:', index)
  * ```
- */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout }) {
-    const step = {
-        name,
-        state: 'pending'
-    };
-    try {
-        /**
-     * No-op requests are not executed.
-     * We return a noop step instead.
-     */ if (request.type === 'noop') {
-            step.state = 'noop';
-            return step;
-        }
-        const txHash = await request.execute();
-        step.txHash = txHash;
-        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);
-        const outcome = evaluateTransactionOutcome(transaction, txHash);
-        step.state = outcome.state;
-        step.data = transaction;
-        // Generate explorer URL for the step
-        step.explorerUrl = buildExplorerUrl(chain, txHash);
-        if (outcome.errorMessage) {
-            step.errorMessage = outcome.errorMessage;
-            // Transaction was mined but reverted on-chain.
-            step.errorCategory = 'chain_revert';
-        }
-    } catch (err) {
-        step.state = 'error';
-        step.error = err;
-        // Sequential path does not yet attempt fine-grained classification of
-        // pre-submission errors (user_rejected, capability errors, etc.). Mark
-        // as `unknown` so consumers can at least detect the category is
-        // populated uniformly across batched and sequential flows.
-        step.errorCategory = 'unknown';
-        // Optionally parse for common blockchain error formats
-        if (err instanceof Error) {
-            step.errorMessage = err.message;
-        } else if (typeof err === 'object' && err != null && 'message' in err) {
-            step.errorMessage = String(err.message);
-        } else {
-            step.errorMessage = `Unknown error occurred during ${name} step.`;
-        }
+ */ function findPendingStep(result, stepName) {
+    const index = result.steps.findIndex((step)=>step.name === stepName && step.state === 'pending');
+    if (index === -1) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Pending step "${stepName}" not found in result`
+        });
     }
-    return step;
+    const step = result.steps[index];
+    if (!step) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'Pending step is undefined'
+        });
+    }
+    return {
+        step,
+        index
+    };
 }
-
 /**
- * Approves the TokenMessenger contract to spend USDC tokens for a bridge operation.
- *
- * This function handles the approval step of the CCTP v2 bridge process, allowing
- * the TokenMessenger contract to spend the specified amount of USDC tokens on behalf
- * of the user. This is a prerequisite for the subsequent burn operation.
+ * Get the burn transaction hash from bridge result.
  *
- * @param params - The bridge parameters containing source, destination, amount and optional config
- * @param sourceChain - The source chain definition where the approval will occur
- * @returns Promise resolving to the bridge step with transaction details
- * @throws {KitError} If the parameters are invalid
- * @throws {BridgeError} If the approval transaction fails
+ * @param result - The bridge result.
+ * @returns The burn transaction hash, or undefined if not found.
  *
  * @example
  * ```typescript
- * const approveStep = await approve(params, sourceChain)
- * console.log('Approval tx:', approveStep.transactionHash)
+ * import { getBurnTxHash } from './findStep'
+ *
+ * const burnTxHash = getBurnTxHash(result)
+ * if (burnTxHash) {
+ *   console.log('Burn tx hash:', burnTxHash)
+ * }
  * ```
- */ async function bridgeApproval({ params, provider }) {
-    // Calculate the approval amount
-    const customFee = BigInt(params.config?.customFee?.value ?? '0');
-    const amountBigInt = BigInt(params.amount);
-    const approvalAmount = (amountBigInt + customFee).toString();
-    return await executePreparedChainRequest({
-        name: 'approve',
-        adapter: params.source.adapter,
-        chain: params.source.chain,
-        request: await provider.approve(params.source, approvalAmount)
-    });
+ */ function getBurnTxHash(result) {
+    return findStepByName(result, CCTPv2StepName.burn)?.txHash;
 }
-
 /**
- * Executes a deposit-for-burn operation on the source chain to initiate a bridge.
- *
- * This function handles the burning step of the CCTP v2 bridge process, where USDC tokens
- * are burned on the source chain to create a message that can be used to mint equivalent
- * tokens on the destination chain.
+ * Get the attestation data from bridge result.
  *
- * @param params - The bridge parameters containing source, destination, amount and optional config
- * @param sourceChain - The source chain definition where the burn will occur
- * @returns Promise resolving to the bridge step with transaction details
- * @throws {KitError} If the parameters are invalid
- * @throws \{BridgeError\} If the burn transaction fails
+ * @param result - The bridge result.
+ * @returns The attestation data, or undefined if not found.
  *
  * @example
  * ```typescript
- * const burnStep = await burn(params, sourceChain)
- * console.log('Burn tx:', burnStep.transactionHash)
+ * import { getAttestationData } from './findStep'
+ *
+ * const attestation = getAttestationData(result)
+ * if (attestation) {
+ *   console.log('Attestation:', attestation.message)
+ * }
  * ```
- */ async function bridgeBurn({ params, provider }) {
-    return await executePreparedChainRequest({
-        name: 'burn',
-        adapter: params.source.adapter,
-        chain: params.source.chain,
-        request: await provider.burn(params)
-    });
+ */ function getAttestationData(result) {
+    // Prefer reAttest data (most recent attestation after expiry)
+    const reAttestStep = findStepByName(result, CCTPv2StepName.reAttest);
+    if (reAttestStep?.state === 'success' && reAttestStep.data) {
+        return reAttestStep.data;
+    }
+    // Fall back to fetchAttestation step
+    const fetchStep = findStepByName(result, CCTPv2StepName.fetchAttestation);
+    return fetchStep?.data;
 }
 
 /**
- * Fetches the attestation from Circle's API for a completed burn operation.
+ * Check if the analysis indicates a non-actionable pending state.
  *
- * This function retrieves the attestation data required to mint tokens on the destination
- * chain after a successful burn operation. The attestation proves that the burn occurred
- * and authorizes the minting of equivalent tokens.
+ * A pending state is non-actionable when there's a continuation step but
+ * the analysis marks it as not actionable, typically because we need to
+ * wait for an ongoing operation to complete.
  *
- * @param params - The bridge parameters containing source, destination, amount and optional config
- * @param txHash - The hash of the burn transaction
- * @returns Promise resolving to the bridge step with attestation data
- * @throws {KitError} If the parameters are invalid
- * @throws {BridgeError} If the attestation fetch fails
+ * @param analysis - The step analysis result from analyzeSteps.
+ * @param result - The bridge result to check for pending steps.
+ * @returns True if there is a pending step that we should wait for.
  *
  * @example
  * ```typescript
- * const attestationStep = await bridgeFetchAttestation(
- *   { params, provider },
- *   burnTxHash
- * )
- * console.log('Attestation data:', attestationStep.data)
+ * import { hasPendingState } from './stepUtils'
+ * import { analyzeSteps } from '../analyzeSteps'
+ *
+ * const analysis = analyzeSteps(bridgeResult)
+ * if (hasPendingState(analysis, bridgeResult)) {
+ *   // Wait for the pending operation to complete
+ * }
  * ```
- */ async function bridgeFetchAttestation({ params, provider }, txHash) {
-    let step = {
-        name: 'fetchAttestation',
-        state: 'pending'
-    };
-    try {
-        /**
-     * Give slow transfers a longer retry delay of 30 seconds to account for the longer time it takes to get the
-     * attestation so that we do not hit the rate limit of the IRIS API or the retry limit of the API polling utility.
-     * We only do this for slow transfers on source chains that have greater than 20 confirmations (5 minutes of blocktime
-     * on the slowest blocktime chains) so that we do not slow down the attestation polling for lower confirmation chains.
-     */ const apiPollingConfig = params.config?.transferSpeed === TransferSpeed.SLOW && params.source.chain.cctp.contracts.v2.confirmations > 20 ? {
-            retryDelay: 30_000
-        } : undefined;
-        const attestation = await provider.fetchAttestation(params.source, txHash, apiPollingConfig);
-        step = {
-            ...step,
-            state: 'success',
-            data: attestation
-        };
-    } catch (err) {
-        let errorMessage = 'Unknown attestation error';
-        if (err instanceof Error) {
-            errorMessage = err.message;
-        } else if (typeof err === 'string') {
-            errorMessage = err;
-        }
-        step = {
-            ...step,
-            state: 'error',
-            error: err,
-            errorMessage,
-            data: undefined
+ */ /**
+ * Evaluate a transaction receipt and return the corresponding step state
+ * and error message. Centralises the success/revert/unconfirmed logic so
+ * every call-site behaves identically.
+ *
+ * @param receipt - The transaction receipt containing status and block info.
+ * @param txHash - The transaction hash used in error messages.
+ * @returns An object with `state` and an optional `errorMessage`.
+ *
+ * @example
+ * ```typescript
+ * const outcome = evaluateTransactionOutcome(receipt, '0xabc...')
+ * step.state = outcome.state
+ * if (outcome.errorMessage) step.errorMessage = outcome.errorMessage
+ * ```
+ */ function evaluateTransactionOutcome(receipt, txHash) {
+    if (receipt.status === 'success' && receipt.blockNumber) {
+        return {
+            state: 'success'
         };
     }
-    return step;
+    return {
+        state: 'error',
+        errorMessage: receipt.status === 'reverted' ? `Transaction ${txHash} was reverted` : 'Transaction was not confirmed on-chain'
+    };
+}
+function hasPendingState(analysis, result) {
+    // Check if there's a continuation step that's marked as non-actionable
+    if (analysis.continuationStep === null || analysis.isActionable) {
+        return false;
+    }
+    // Verify that the continuation step actually exists and is in pending state
+    const pendingStep = result.steps.find((step)=>step.name === analysis.continuationStep && step.state === 'pending');
+    return pendingStep !== undefined;
 }
-
 /**
- * Executes a mint operation on the destination chain to complete a bridge.
- *
- * This function handles the minting step of the CCTP v2 bridge process, where USDC tokens
- * are minted on the destination chain using the attestation and message from the source chain.
- * This is the final step that completes the cross-chain bridge operation.
+ * Check if the step is the last one in the execution flow.
  *
- * @param params - The bridge parameters containing source, destination, amount and optional config
- * @param destinationChain - The destination chain definition where the mint will occur
- * @param attestation - The attestation data from Circle's API
- * @param message - The message from the source chain burn operation
- * @returns Promise resolving to the bridge step with transaction details
- * @throws {KitError} If the parameters are invalid
- * @throws {BridgeError} If the mint transaction fails
+ * @param step - The step object to check.
+ * @param stepNames - The ordered list of step names in the execution flow.
+ * @returns True if this is the last step in the flow.
  *
  * @example
  * ```typescript
- * const mintStep = await mint(params, destinationChain, attestation, message)
- * console.log('Mint tx:', mintStep.transactionHash)
+ * import { isLastStep } from './stepUtils'
+ *
+ * const stepNames = ['approve', 'burn', 'fetchAttestation', 'mint']
+ * isLastStep({ name: 'mint' }, stepNames) // true
+ * isLastStep({ name: 'burn' }, stepNames) // false
  * ```
- */ async function bridgeMint({ params, provider }, attestation) {
-    // Validate attestation message matches transfer params
-    await assertCCTPv2AttestationParams(attestation, params);
-    const step = await executePreparedChainRequest({
-        name: 'mint',
-        adapter: params.destination.adapter,
-        chain: params.destination.chain,
-        request: await provider.mint(params.source, params.destination, attestation)
-    });
-    // Add forwarded: false for non-relayer mints
-    return {
-        ...step,
-        forwarded: false
-    };
+ */ function isLastStep(step, stepNames) {
+    const stepIndex = stepNames.indexOf(step.name);
+    return stepIndex === -1 || stepIndex >= stepNames.length - 1;
 }
-const mockAttestationMessage = {
-    attestation: '0x8bd9b9e63eb05128eb2896b63e3e1df39bfd6bbfb893b69dc53c39252aeb85df1ded70263b07da17abf88e6e1b77f16ebcdb4eb1c6b4ea4c625215e5cb9dddb81bffe0b9d75e2094f05e48f18f70d0b254999bde90bab26f5c0da29b2d7e00feca1cfed119cba0d2a0e887648a40e803e0ca34aa8fd94ce068515eeaef72b520aa1b',
-    message: '0x000000010000000000000006f446cb82eb486fef485c14c301eaab73aa35f87e3feda3547acf0f33cd4b40f30000000000000000000000008fe6b999dc680ccfdd5bf7eb0974218be2542daa0000000000000000000000008fe6b999dc680ccfdd5bf7eb0974218be2542daa0000000000000000000000000000000000000000000000000000000000000000000003e8000003e8000000010000000000000000000000001c7d4b196cb0c7b01d743fbc6116a902379c723800000000000000000000000023f9a5bea7b92a0638520607407bc7f0310aeed400000000000000000000000000000000000000000000000000000000000186a0000000000000000000000000c5567a5e3370d4dbfb0540025078e283e36a363d000000000000000000000000000000000000000000000000000000000000000b000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000001f6b158',
-    eventNonce: '0xf446cb82eb486fef485c14c301eaab73aa35f87e3feda3547acf0f33cd4b40f3',
-    cctpVersion: 2,
-    status: 'complete',
-    decodedMessage: {
-        sourceDomain: '0',
-        destinationDomain: '6',
-        nonce: '0xf446cb82eb486fef485c14c301eaab73aa35f87e3feda3547acf0f33cd4b40f3',
-        sender: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
-        recipient: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
-        destinationCaller: '0x0000000000000000000000000000000000000000000000000000000000000000',
-        minFinalityThreshold: '1000',
-        finalityThresholdExecuted: '1000',
-        messageBody: '0x000000010000000000000000000000001c7d4b196cb0c7b01d743fbc6116a902379c723800000000000000000000000023f9a5bea7b92a0638520607407bc7f0310aeed400000000000000000000000000000000000000000000000000000000000186a0000000000000000000000000c5567a5e3370d4dbfb0540025078e283e36a363d000000000000000000000000000000000000000000000000000000000000000b000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000001f6b158',
-        decodedMessageBody: {
-            burnToken: '0x1c7d4b196cb0c7b01d743fbc6116a902379c7238',
-            mintRecipient: '0x23f9a5bea7b92a0638520607407bc7f0310aeed4',
-            amount: '100000',
-            messageSender: '0xc5567a5e3370d4dbfb0540025078e283e36a363d',
-            maxFee: '11',
-            feeExecuted: '10',
-            expirationBlock: '32944472',
-            hookData: null
-        }
-    },
-    delayReason: null
-};
-
 /**
- * Type guard that checks if the relayer has confirmed the mint transaction.
+ * Wait for a pending transaction to complete.
  *
- * This function validates that:
- * 1. The response has valid AttestationResponse structure
- * 2. At least one message has forwardState === 'CONFIRMED' (or 'COMPLETE') and a valid forwardTxHash
+ * Poll the adapter until the transaction is confirmed on-chain and return
+ * the updated step with success or error state based on the receipt.
  *
- * If forwardState is 'FAILED', throws a non-retryable KitError.
- * If forwardState is 'PENDING' or not present, throws a RETRYABLE KitError to continue polling.
+ * @param pendingStep - The full step object containing the transaction hash.
+ * @param adapter - The adapter to use for waiting.
+ * @param chain - The chain where the transaction was submitted.
+ * @returns The updated step object with success or error state.
  *
- * @param obj - The value to check, typically a parsed JSON response
- * @returns True if the relayer has confirmed the mint
- * @throws {KitError} With FATAL recoverability if structure is invalid
- * @throws {KitError} With RESUMABLE recoverability if forwardState is 'FAILED'
- * @throws {KitError} With RETRYABLE recoverability if still pending
- * @internal
- */ const isRelayerMintConfirmed = (obj)=>{
-    // First check if the structure is valid
-    if (!hasValidAttestationStructure(obj)) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'Invalid attestation response structure from IRIS API.'
-        });
-    }
-    // Find the first message (typically there's only one)
-    const message = obj.messages[0];
-    if (!message) {
+ * @throws KitError when the pending step has no transaction hash.
+ *
+ * @example
+ * ```typescript
+ * import { waitForPendingTransaction } from './bridgeStepUtils'
+ *
+ * const pendingStep = { name: 'burn', state: 'pending', txHash: '0x123...' }
+ * const updatedStep = await waitForPendingTransaction(pendingStep, adapter, chain)
+ * // updatedStep.state is now 'success' or 'error'
+ * ```
+ */ async function waitForPendingTransaction(pendingStep, adapter, chain) {
+    if (!pendingStep.txHash) {
         throw new KitError({
             ...InputError.VALIDATION_FAILED,
             recoverability: 'FATAL',
-            message: 'No attestation messages found in IRIS API response.'
-        });
-    }
-    // Check for FAILED state - this is a permanent failure
-    if (message.forwardState === 'FAILED') {
-        throw new KitError({
-            ...NetworkError.RELAYER_FORWARD_FAILED,
-            recoverability: 'RESUMABLE',
-            message: 'Circle relayer failed to forward the mint transaction. The mint may still have succeeded if another party submitted it. Check the recipient wallet balance before retrying. If the mint did not occur, you can manually submit it using the attestation data in the error cause.',
-            cause: {
-                trace: {
-                    eventNonce: message.eventNonce,
-                    attestation: message.attestation,
-                    message: message.message
-                }
-            }
+            message: `Cannot wait for pending ${pendingStep.name}: no transaction hash available`
         });
     }
-    // Check if mint is confirmed (or complete) with a valid transaction hash
-    // We accept both CONFIRMED and COMPLETE since COMPLETE implies CONFIRMED
-    if ((message.forwardState === 'CONFIRMED' || message.forwardState === 'COMPLETE') && typeof message.forwardTxHash === 'string' && message.forwardTxHash.trim().length > 0) {
-        return true;
-    }
-    // Still pending or not yet processed - throw RETRYABLE error to continue polling
-    throw new KitError({
-        ...NetworkError.RELAYER_PENDING,
-        recoverability: 'RETRYABLE',
-        message: 'Relayer mint not ready. Waiting for confirmation.'
+    const txHash = pendingStep.txHash;
+    const txReceipt = await retryAsync(async ()=>adapter.waitForTransaction(txHash, undefined, chain), {
+        isRetryable: (err)=>isRetryableError$1(parseBlockchainError(err, {
+                chain: chain.name,
+                txHash
+            }))
     });
-};
+    const outcome = evaluateTransactionOutcome(txReceipt, txHash);
+    return {
+        ...pendingStep,
+        state: outcome.state,
+        data: txReceipt,
+        explorerUrl: buildExplorerUrl(chain, txHash),
+        ...outcome.errorMessage ? {
+            errorMessage: outcome.errorMessage
+        } : {}
+    };
+}
 /**
- * Polls the attestation API until the relayer's mint transaction is confirmed.
+ * Wait for a pending step to complete.
  *
- * This function is used when `useForwarder` is enabled. Instead of the user
- * submitting the mint transaction, Circle's Orbit relayer handles it automatically.
- * This function polls until the relayer has submitted and confirmed the mint transaction.
+ * For transaction steps: waits for the transaction to be confirmed.
+ * For attestation: re-executes the attestation fetch.
  *
- * @remarks
- * - Uses a 20-minute timeout by default (600 retries × 2 seconds)
- * - Throws immediately if `forwardState` is 'FAILED'
- * - Waits for `forwardState` to be 'CONFIRMED' or 'COMPLETE' (COMPLETE implies CONFIRMED)
- * - Returns the attestation message with `forwardTxHash` populated
+ * @typeParam TFromAdapterCapabilities - The capabilities of the source adapter.
+ * @typeParam TToAdapterCapabilities - The capabilities of the destination adapter.
+ * @param pendingStep - The full step object (with name, state, txHash, data, etc.) to resolve.
+ * @param adapter - The adapter to use.
+ * @param chain - The chain where the step is executing.
+ * @param context - The retry context.
+ * @param result - The bridge result.
+ * @param provider - The CCTP v2 bridging provider.
+ * @returns The resolved step object with updated state.
  *
- * @param sourceDomainId - The CCTP domain ID of the source chain
- * @param transactionHash - The transaction hash of the burn operation
- * @param isTestnet - Whether this is for a testnet chain (true) or mainnet (false)
- * @param config - Optional configuration overrides for polling behavior
- * @returns The attestation message with confirmed forwardTxHash
- * @throws {KitError} With code 'NETWORK_RELAYER_FORWARD_FAILED' if relayer failed
- * @throws {KitError} If timeout is reached while still pending
+ * @throws KitError when fetching attestation but burn transaction hash is not found.
  *
  * @example
  * ```typescript
- * const attestation = await fetchRelayerMint(0, '0xabc...', false)
- * console.log('Relayer mint tx:', attestation.forwardTxHash)
+ * import { waitForStepToComplete } from './bridgeStepUtils'
+ *
+ * const pendingStep = { name: 'burn', state: 'pending', txHash: '0x123...' }
+ * const updatedStep = await waitForStepToComplete(
+ *   pendingStep,
+ *   adapter,
+ *   chain,
+ *   context,
+ *   result,
+ *   provider,
+ * )
+ * // updatedStep.state is now 'success' or 'error'
  * ```
- */ const fetchRelayerMint = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
-    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = {
-        ...DEFAULT_CONFIG,
-        ...config
-    };
-    let response;
-    try {
-        response = await pollApiGet(url, isRelayerMintConfirmed, effectiveConfig);
-    } catch (error) {
-        // Enrich RELAYER_FORWARD_FAILED errors with the burn transaction hash
-        if (error instanceof KitError && error.name === 'NETWORK_RELAYER_FORWARD_FAILED') {
+ */ async function waitForStepToComplete(pendingStep, adapter, chain, context, result, provider) {
+    if (pendingStep.name === CCTPv2StepName.fetchAttestation) {
+        // For attestation, re-run the fetch (it has built-in polling)
+        const burnTxHash = getBurnTxHash(result);
+        if (!burnTxHash) {
             throw new KitError({
-                ...NetworkError.RELAYER_FORWARD_FAILED,
-                recoverability: error.recoverability,
-                message: error.message,
-                cause: {
-                    ...error.cause,
-                    trace: {
-                        ...error.cause?.trace,
-                        burnTxHash: transactionHash
-                    }
-                }
+                ...InputError.VALIDATION_FAILED,
+                recoverability: 'FATAL',
+                message: 'Cannot fetch attestation: burn transaction hash not found'
             });
         }
-        throw error;
-    }
-    // Return the first message (which should have forwardTxHash)
-    // Note: This check is needed for TypeScript type safety even though
-    // isRelayerMintConfirmed validates messages[0] exists. The type guard
-    // narrows the type at the call site, but TypeScript can't infer that
-    // the array still has elements after pollApiGet returns.
-    const message = response.messages[0];
-    if (!message) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'No attestation messages found in response after polling.'
-        });
+        const sourceAddress = result.source.address;
+        const attestation = await provider.fetchAttestation({
+            chain: result.source.chain,
+            adapter: context.from,
+            address: sourceAddress
+        }, burnTxHash);
+        return {
+            ...pendingStep,
+            state: 'success',
+            data: attestation
+        };
     }
-    return message;
-};
+    // For transaction steps, wait for the transaction to complete
+    return waitForPendingTransaction(pendingStep, adapter, chain);
+}
 
 /**
- * Executes the mint step for forwarding mode where Circle's relayer handles the mint.
+ * Executes a prepared chain request and returns the result as a bridge step.
  *
- * Instead of the user signing and submitting a mint transaction, this function:
- * 1. Polls the attestation API until the relayer has confirmed the mint (forwardState === 'CONFIRMED')
- * 2. Extracts the relayer's mint transaction hash (forwardTxHash)
- * 3. Returns the mint step with the relayer's transaction details
+ * This function takes a prepared chain request (containing transaction data) and executes
+ * it using the appropriate adapter. It handles the execution details and formats
+ * the result as a standardized bridge step with transaction details and explorer URLs.
  *
- * Since Circle's relayer handles the mint transaction, we don't wait for on-chain
- * confirmation - the IRIS API confirmation is sufficient. The step completes
- * immediately after the API confirms the mint.
- *
- * @param params - The bridge parameters containing source, destination, amount and config
- * @param context - The step context containing burnTxHash from the burn step
- * @returns Promise resolving to the bridge step with transaction details
- * @throws {KitError} If burnTxHash is not available in context
- * @throws {KitError} With code 'NETWORK_RELAYER_FORWARD_FAILED' if relayer failed
- * @throws {KitError} If timeout is reached while waiting for relayer
+ * @param params - The execution parameters containing:
+ *   - `name`: The name of the step
+ *   - `request`: The prepared chain request containing transaction data
+ *   - `adapter`: The adapter that will execute the transaction
+ *   - `confirmations`: The number of confirmations to wait for (defaults to 1)
+ *   - `timeout`: The timeout for the request in milliseconds
+ *   - `gasLimit`: Optional explicit gas limit (number) forwarded to EVM execute,
+ *     bypassing `eth_estimateGas`; ignored for non-EVM requests
+ * @returns The bridge step with the transaction details and explorer URL
+ * @throws If the transaction execution fails
  *
  * @example
  * ```typescript
- * const step = await bridgeRelayerMint(params, { burnTxHash: '0x...' })
- * console.log('Relayer mint tx:', step.txHash)
+ * const step = await executePreparedChainRequest({
+ *   name: 'approve',
+ *   request: preparedRequest,
+ *   adapter: adapter,
+ *   confirmations: 2,
+ *   timeout: 30000
+ * })
+ * console.log('Transaction hash:', step.txHash)
  * ```
- */ async function bridgeRelayerMint(params, context) {
+ */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, gasLimit }) {
     const step = {
-        name: 'mint',
-        state: 'pending',
-        forwarded: true
+        name,
+        state: 'pending'
     };
-    // Validate context has burnTxHash
-    if (!context?.burnTxHash) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'Burn transaction hash not available for relayer mint. Ensure the burn step completed successfully.'
-        });
-    }
     try {
-        // Poll attestation API until relayer confirms the mint
-        const attestation = await fetchRelayerMint(params.source.chain.cctp.domain, context.burnTxHash, params.source.chain.isTestnet ?? false);
-        // Extract the relayer's mint transaction hash
-        const forwardTxHash = attestation.forwardTxHash;
-        if (!forwardTxHash) {
-            throw new KitError({
-                ...InputError.VALIDATION_FAILED,
-                recoverability: 'FATAL',
-                message: 'Relayer mint transaction hash not found in attestation response.'
-            });
+        /**
+     * No-op requests are not executed.
+     * We return a noop step instead.
+     */ if (request.type === 'noop') {
+            step.state = 'noop';
+            return step;
+        }
+        const txHash = request.type === 'evm' && gasLimit !== undefined ? await request.execute({
+            gasLimit
+        }) : await request.execute();
+        step.txHash = txHash;
+        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);
+        const outcome = evaluateTransactionOutcome(transaction, txHash);
+        step.state = outcome.state;
+        step.data = transaction;
+        // Generate explorer URL for the step
+        step.explorerUrl = buildExplorerUrl(chain, txHash);
+        if (outcome.errorMessage) {
+            step.errorMessage = outcome.errorMessage;
+            // Transaction was mined but reverted on-chain.
+            step.errorCategory = 'chain_revert';
         }
-        step.txHash = forwardTxHash;
-        step.explorerUrl = buildExplorerUrl(params.destination.chain, forwardTxHash);
-        step.state = 'success';
     } catch (err) {
         step.state = 'error';
         step.error = err;
-        step.errorMessage = getErrorMessage(err);
+        // Sequential path does not yet attempt fine-grained classification of
+        // pre-submission errors (user_rejected, capability errors, etc.). Mark
+        // as `unknown` so consumers can at least detect the category is
+        // populated uniformly across batched and sequential flows.
+        step.errorCategory = 'unknown';
+        // Optionally parse for common blockchain error formats
+        if (err instanceof Error) {
+            step.errorMessage = err.message;
+        } else if (typeof err === 'object' && err != null && 'message' in err) {
+            step.errorMessage = String(err.message);
+        } else {
+            step.errorMessage = `Unknown error occurred during ${name} step.`;
+        }
     }
     return step;
 }
 
 /**
- * Creates the ordered sequence of CCTP v2 bridge step executors.
+ * Approves the TokenMessenger contract to spend USDC tokens for a bridge operation.
  *
- * Defines the complete bridge flow: approve → burn → fetchAttestation → mint.
- * Each step includes an executor function and optional context updater for
- * passing data between steps.
+ * This function handles the approval step of the CCTP v2 bridge process, allowing
+ * the TokenMessenger contract to spend the specified amount of USDC tokens on behalf
+ * of the user. This is a prerequisite for the subsequent burn operation.
  *
- * When `useForwarder` is true, the mint step uses the relayer mint executor
- * which polls for Circle's relayer to submit the mint transaction instead of
- * requiring the user to sign and submit it.
+ * @param params - The bridge parameters containing source, destination, amount and optional config
+ * @param sourceChain - The source chain definition where the approval will occur
+ * @returns Promise resolving to the bridge step with transaction details
+ * @throws {KitError} If the parameters are invalid
+ * @throws {BridgeError} If the approval transaction fails
  *
- * @param useForwarder - When true, uses relayer mint instead of user mint
- * @returns Array of step executor configurations
- */ function createStepExecutors(useForwarder = false) {
-    return [
-        {
-            name: 'approve',
-            executor: async (params, provider)=>bridgeApproval({
-                    params,
-                    provider
-                })
-        },
-        {
-            name: 'burn',
-            executor: async (params, provider)=>bridgeBurn({
-                    params,
-                    provider
-                }),
-            updateContext: (step)=>{
-                if (!step.txHash) {
-                    throw new KitError({
-                        ...InputError.VALIDATION_FAILED,
-                        recoverability: 'FATAL',
-                        message: 'Burn step completed but no transaction hash was returned'
-                    });
-                }
-                return {
-                    burnTxHash: step.txHash
-                };
-            }
-        },
-        {
-            name: 'fetchAttestation',
-            executor: async (params, provider, context)=>{
-                if (!context?.burnTxHash) {
-                    throw new KitError({
-                        ...InputError.VALIDATION_FAILED,
-                        recoverability: 'FATAL',
-                        message: 'Burn transaction hash not available for attestation'
-                    });
-                }
-                return bridgeFetchAttestation({
-                    params,
-                    provider
-                }, context.burnTxHash);
-            },
-            updateContext: (step)=>{
-                if (!step.data) {
-                    throw new KitError({
-                        ...InputError.VALIDATION_FAILED,
-                        recoverability: 'FATAL',
-                        message: 'Attestation step completed but no data was returned'
-                    });
-                }
-                return {
-                    attestationData: step.data
-                };
-            }
-        },
-        {
-            name: 'mint',
-            // bridgeRelayerMint validates context.burnTxHash internally with a KitError
-            // bridgeMint requires attestationData which is validated here
-            executor: useForwarder ? async (params, _provider, context)=>{
-                if (!context) {
-                    throw new KitError({
-                        ...InputError.VALIDATION_FAILED,
-                        recoverability: 'FATAL',
-                        message: 'Step context is required for relayer mint'
-                    });
-                }
-                return bridgeRelayerMint(params, context);
-            } : async (params, provider, context)=>{
-                if (!context?.attestationData) {
-                    throw new KitError({
-                        ...InputError.VALIDATION_FAILED,
-                        recoverability: 'FATAL',
-                        message: 'Attestation data not available for minting'
-                    });
-                }
-                return bridgeMint({
-                    params,
-                    provider
-                }, context.attestationData);
-            }
-        }
-    ];
+ * @example
+ * ```typescript
+ * const approveStep = await approve(params, sourceChain)
+ * console.log('Approval tx:', approveStep.transactionHash)
+ * ```
+ */ async function bridgeApproval({ params, provider }) {
+    // Calculate the approval amount
+    const customFee = BigInt(params.config?.customFee?.value ?? '0');
+    const amountBigInt = BigInt(params.amount);
+    const approvalAmount = (amountBigInt + customFee).toString();
+    return await executePreparedChainRequest({
+        name: 'approve',
+        adapter: params.source.adapter,
+        chain: params.source.chain,
+        request: await provider.approve(params.source, approvalAmount),
+        gasLimit: Number(APPROVE_GAS_LIMIT_EVM)
+    });
 }
+
 /**
- * Helper function to create error step and set result state to error.
+ * Executes a deposit-for-burn operation on the source chain to initiate a bridge.
  *
- * @param stepName - The name of the step that failed
- * @param error - The error that occurred
- * @param result - The bridge result object to update
- */ function handleStepError(stepName, error, result) {
-    result.state = 'error';
-    result.steps.push({
-        name: stepName,
-        state: 'error',
-        error,
-        errorMessage: getErrorMessage(error)
+ * This function handles the burning step of the CCTP v2 bridge process, where USDC tokens
+ * are burned on the source chain to create a message that can be used to mint equivalent
+ * tokens on the destination chain.
+ *
+ * @param params - The bridge parameters containing source, destination, amount and optional config
+ * @param sourceChain - The source chain definition where the burn will occur
+ * @returns Promise resolving to the bridge step with transaction details
+ * @throws {KitError} If the parameters are invalid
+ * @throws \{BridgeError\} If the burn transaction fails
+ *
+ * @example
+ * ```typescript
+ * const burnStep = await burn(params, sourceChain)
+ * console.log('Burn tx:', burnStep.transactionHash)
+ * ```
+ */ async function bridgeBurn({ params, provider }) {
+    return await executePreparedChainRequest({
+        name: 'burn',
+        adapter: params.source.adapter,
+        chain: params.source.chain,
+        request: await provider.burn(params),
+        gasLimit: Number(DEPOSIT_FOR_BURN_GAS_LIMIT_EVM)
     });
 }
 
 /**
- * Dispatch a bridge step event through the provider's action dispatcher.
+ * Fetches the attestation from Circle's API for a completed burn operation.
  *
- * Constructs the appropriate action payload and dispatches it to any registered
- * event listeners. Handles type-safe dispatching for different step types.
- * When provided, traceId from the invocation context is included for end-to-end correlation.
+ * This function retrieves the attestation data required to mint tokens on the destination
+ * chain after a successful burn operation. The attestation proves that the burn occurred
+ * and authorizes the minting of equivalent tokens.
  *
- * @param name - The step name (approve, burn, fetchAttestation, or mint).
- * @param step - The completed bridge step containing transaction details and explorerUrl.
- * @param provider - The CCTP v2 provider with action dispatcher.
- * @param invocation - Optional invocation context containing traceId for correlation.
+ * @param params - The bridge parameters containing source, destination, amount and optional config
+ * @param txHash - The hash of the burn transaction
+ * @returns Promise resolving to the bridge step with attestation data
+ * @throws {KitError} If the parameters are invalid
+ * @throws {BridgeError} If the attestation fetch fails
  *
  * @example
  * ```typescript
- * const step: BridgeStep = {
- *   name: 'burn',
- *   state: 'success',
- *   txHash: '0xabc...',
- *   explorerUrl: 'https://sepolia.etherscan.io/tx/0xabc...',
- *   data: { ... }
- * }
- * dispatchStepEvent('burn', step, provider, invocationContext)
- * ```
- */ function dispatchStepEvent(name, step, provider, invocation) {
-    if (!provider.actionDispatcher) {
-        return;
-    }
-    // Extract traceId from invocation context if provided
-    const traceId = invocation?.traceId;
-    const actionValues = {
-        protocol: 'cctp',
-        version: 'v2',
-        ...traceId !== undefined && {
-            traceId
-        },
-        values: step
+ * const attestationStep = await bridgeFetchAttestation(
+ *   { params, provider },
+ *   burnTxHash
+ * )
+ * console.log('Attestation data:', attestationStep.data)
+ * ```
+ */ async function bridgeFetchAttestation({ params, provider }, txHash) {
+    let step = {
+        name: 'fetchAttestation',
+        state: 'pending'
     };
-    switch(name){
-        case 'approve':
-        case 'burn':
-        case 'mint':
-            provider.actionDispatcher.dispatch(name, {
-                ...actionValues,
-                method: name
-            });
-            break;
-        case 'fetchAttestation':
-        case 'reAttest':
-            provider.actionDispatcher.dispatch(name, {
-                ...actionValues,
-                method: name,
-                values: step
-            });
-            break;
+    try {
+        /**
+     * Give slow transfers a longer retry delay of 30 seconds to account for the longer time it takes to get the
+     * attestation so that we do not hit the rate limit of the IRIS API or the retry limit of the API polling utility.
+     * We only do this for slow transfers on source chains that have greater than 20 confirmations (5 minutes of blocktime
+     * on the slowest blocktime chains) so that we do not slow down the attestation polling for lower confirmation chains.
+     */ const apiPollingConfig = params.config?.transferSpeed === TransferSpeed.SLOW && params.source.chain.cctp.contracts.v2.confirmations > 20 ? {
+            retryDelay: 30_000
+        } : undefined;
+        const attestation = await provider.fetchAttestation(params.source, txHash, apiPollingConfig);
+        step = {
+            ...step,
+            state: 'success',
+            data: attestation
+        };
+    } catch (err) {
+        let errorMessage = 'Unknown attestation error';
+        if (err instanceof Error) {
+            errorMessage = err.message;
+        } else if (typeof err === 'string') {
+            errorMessage = err;
+        }
+        step = {
+            ...step,
+            state: 'error',
+            error: err,
+            errorMessage,
+            data: undefined
+        };
     }
+    return step;
 }
 
 /**
- * Default clock implementation.
+ * Executes a mint operation on the destination chain to complete a bridge.
  *
- * @packageDocumentation
- */ /**
- * Default clock implementation using `Date.now()`.
+ * This function handles the minting step of the CCTP v2 bridge process, where USDC tokens
+ * are minted on the destination chain using the attestation and message from the source chain.
+ * This is the final step that completes the cross-chain bridge operation.
  *
- * @remarks
- * Use this in production code. For testing, inject a mock clock
- * that returns controlled timestamps.
+ * @param params - The bridge parameters containing source, destination, amount and optional config
+ * @param destinationChain - The destination chain definition where the mint will occur
+ * @param attestation - The attestation data from Circle's API
+ * @param message - The message from the source chain burn operation
+ * @returns Promise resolving to the bridge step with transaction details
+ * @throws {KitError} If the parameters are invalid
+ * @throws {BridgeError} If the mint transaction fails
  *
  * @example
  * ```typescript
- * import { defaultClock } from '@core/runtime'
- *
- * const start = defaultClock.now()
- * // ... do work ...
- * const elapsed = defaultClock.since(start)
+ * const mintStep = await mint(params, destinationChain, attestation, message)
+ * console.log('Mint tx:', mintStep.transactionHash)
  * ```
- */ const defaultClock = {
-    now: ()=>Date.now(),
-    since: (start)=>Date.now() - start
+ */ async function bridgeMint({ params, provider }, attestation) {
+    // Validate attestation message matches transfer params
+    await assertCCTPv2AttestationParams(attestation, params);
+    const mintRequest = await provider.mint(params.source, params.destination, attestation);
+    const step = await executePreparedChainRequest({
+        name: 'mint',
+        adapter: params.destination.adapter,
+        chain: params.destination.chain,
+        request: mintRequest,
+        // Some chains (e.g. Cronos) enforce an EIP-7623 calldata gas floor that
+        // eth_estimateGas does not account for, returning a below-floor value
+        // without reverting. Pinning to a value above the observed execution max
+        // (310_839) bypasses re-estimation and guarantees we clear both the floor
+        // and the actual execution cost.
+        gasLimit: Number(RECEIVE_MESSAGE_GAS_LIMIT_EVM)
+    });
+    // Add forwarded: false for non-relayer mints
+    return {
+        ...step,
+        forwarded: false
+    };
+}
+const mockAttestationMessage = {
+    attestation: '0x8bd9b9e63eb05128eb2896b63e3e1df39bfd6bbfb893b69dc53c39252aeb85df1ded70263b07da17abf88e6e1b77f16ebcdb4eb1c6b4ea4c625215e5cb9dddb81bffe0b9d75e2094f05e48f18f70d0b254999bde90bab26f5c0da29b2d7e00feca1cfed119cba0d2a0e887648a40e803e0ca34aa8fd94ce068515eeaef72b520aa1b',
+    message: '0x000000010000000000000006f446cb82eb486fef485c14c301eaab73aa35f87e3feda3547acf0f33cd4b40f30000000000000000000000008fe6b999dc680ccfdd5bf7eb0974218be2542daa0000000000000000000000008fe6b999dc680ccfdd5bf7eb0974218be2542daa0000000000000000000000000000000000000000000000000000000000000000000003e8000003e8000000010000000000000000000000001c7d4b196cb0c7b01d743fbc6116a902379c723800000000000000000000000023f9a5bea7b92a0638520607407bc7f0310aeed400000000000000000000000000000000000000000000000000000000000186a0000000000000000000000000c5567a5e3370d4dbfb0540025078e283e36a363d000000000000000000000000000000000000000000000000000000000000000b000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000001f6b158',
+    eventNonce: '0xf446cb82eb486fef485c14c301eaab73aa35f87e3feda3547acf0f33cd4b40f3',
+    cctpVersion: 2,
+    status: 'complete',
+    decodedMessage: {
+        sourceDomain: '0',
+        destinationDomain: '6',
+        nonce: '0xf446cb82eb486fef485c14c301eaab73aa35f87e3feda3547acf0f33cd4b40f3',
+        sender: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+        recipient: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+        destinationCaller: '0x0000000000000000000000000000000000000000000000000000000000000000',
+        minFinalityThreshold: '1000',
+        finalityThresholdExecuted: '1000',
+        messageBody: '0x000000010000000000000000000000001c7d4b196cb0c7b01d743fbc6116a902379c723800000000000000000000000023f9a5bea7b92a0638520607407bc7f0310aeed400000000000000000000000000000000000000000000000000000000000186a0000000000000000000000000c5567a5e3370d4dbfb0540025078e283e36a363d000000000000000000000000000000000000000000000000000000000000000b000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000001f6b158',
+        decodedMessageBody: {
+            burnToken: '0x1c7d4b196cb0c7b01d743fbc6116a902379c7238',
+            mintRecipient: '0x23f9a5bea7b92a0638520607407bc7f0310aeed4',
+            amount: '100000',
+            messageSender: '0xc5567a5e3370d4dbfb0540025078e283e36a363d',
+            maxFee: '11',
+            feeExecuted: '10',
+            expirationBlock: '32944472',
+            hookData: null
+        }
+    },
+    delayReason: null
 };
 
-// ============================================================================
-// Crypto Utilities (Internal)
-// ============================================================================
-/** @internal */ function hasGetRandomValues() {
-    return typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function';
-}
 /**
- * Create a W3C/OpenTelemetry-compatible trace ID.
+ * Executes the mint step for forwarding mode where Circle's relayer handles the mint.
  *
- * @returns 32-character lowercase hex string (128-bit).
+ * Instead of the user signing and submitting a mint transaction, this function:
+ * 1. Polls the attestation API until the relayer has confirmed the mint (forwardState === 'CONFIRMED')
+ * 2. Extracts the relayer's mint transaction hash (forwardTxHash)
+ * 3. Returns the mint step with the relayer's transaction details
  *
- * @remarks
- * **Standard function for generating `traceId` values.** Compatible with
- * OpenTelemetry, Jaeger, Zipkin, and AWS X-Ray.
+ * Since Circle's relayer handles the mint transaction, we don't wait for on-chain
+ * confirmation - the IRIS API confirmation is sufficient. The step completes
+ * immediately after the API confirms the mint.
+ *
+ * @param params - The bridge parameters containing source, destination, amount and config
+ * @param provider - The CCTP v2 bridging provider
+ * @param context - The step context containing burnTxHash from the burn step
+ * @returns Promise resolving to the bridge step with transaction details
+ * @throws {KitError} If burnTxHash is not available in context
+ * @throws {KitError} With code 'NETWORK_RELAYER_FORWARD_FAILED' if relayer failed
+ * @throws {KitError} If timeout is reached while waiting for relayer
  *
  * @example
  * ```typescript
- * const traceId = createTraceId() // "a1b2c3d4e5f6789012345678abcdef00"
+ * const step = await bridgeRelayerMint(
+ *   { params, provider },
+ *   { burnTxHash: '0x...' }
+ * )
+ * console.log('Relayer mint tx:', step.txHash)
  * ```
- */ function createTraceId() {
-    const bytes = new Uint8Array(16);
-    if (hasGetRandomValues()) {
-        crypto.getRandomValues(bytes);
-    } else {
-        for(let i = 0; i < 16; i++){
-            bytes[i] = Math.floor(Math.random() * 256) // NOSONAR:
-            ;
+ */ async function bridgeRelayerMint({ params, provider }, context) {
+    const step = {
+        name: 'mint',
+        state: 'pending',
+        forwarded: true
+    };
+    // Validate context has burnTxHash
+    if (!context?.burnTxHash) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'Burn transaction hash not available for relayer mint. Ensure the burn step completed successfully.'
+        });
+    }
+    try {
+        // Poll attestation API until relayer confirms the mint
+        const attestation = await provider.fetchRelayerMint(params.source, context.burnTxHash);
+        // Extract the relayer's mint transaction hash
+        const forwardTxHash = attestation.forwardTxHash;
+        if (!forwardTxHash) {
+            throw new KitError({
+                ...InputError.VALIDATION_FAILED,
+                recoverability: 'FATAL',
+                message: 'Relayer mint transaction hash not found in attestation response.'
+            });
         }
+        step.txHash = forwardTxHash;
+        step.explorerUrl = buildExplorerUrl(params.destination.chain, forwardTxHash);
+        step.state = 'success';
+    } catch (err) {
+        step.state = 'error';
+        step.error = err;
+        step.errorMessage = getErrorMessage(err);
     }
-    return Array.from(bytes, (b)=>b.toString(16).padStart(2, '0')).join('');
+    return step;
 }
 
 /**
- * Clean tags by removing keys with undefined values.
- *
- * @param tags - Tags object, may contain undefined values. Accepts `undefined` or `null`.
- * @returns A new object with undefined values removed, or empty object if input is nullish.
- *
- * @remarks
- * This helper ensures tags are safe for serialization and logging.
- * Similar to the internal `cleanUndefined` in the logger module, but
- * typed specifically for {@link Tags}.
- *
- * @example
- * ```typescript
- * import { cleanTags } from '@core/runtime'
- *
- * const tags = { chain: 'Ethereum', amount: 100, extra: undefined }
- * const cleaned = cleanTags(tags)
- * // { chain: 'Ethereum', amount: 100 }
+ * Creates the ordered sequence of CCTP v2 bridge step executors.
  *
- * const empty = cleanTags(undefined)
- * // {}
- * ```
- */ function cleanTags(tags) {
-    if (tags == null) return {};
-    return Object.fromEntries(Object.entries(tags).filter(([, value])=>value !== undefined));
-}
-
-/**
- * Check if a pattern is valid.
+ * Defines the complete bridge flow: approve → burn → fetchAttestation → mint.
+ * Each step includes an executor function and optional context updater for
+ * passing data between steps.
  *
- * @remarks
- * Invalid patterns:
- * - Empty segments (e.g., `a..b`, `.a`, `a.`)
- * - `**` not at end (e.g., `a.**.b`)
+ * When `useForwarder` is true, the mint step uses the relayer mint executor
+ * which polls for Circle's relayer to submit the mint transaction instead of
+ * requiring the user to sign and submit it.
  *
- * @param pattern - The pattern to validate.
- * @returns True if valid, false otherwise.
- */ function isValidPattern(pattern) {
-    // Empty pattern is valid (matches empty topic)
-    if (pattern === '') return true;
-    const segments = pattern.split('.');
-    // Check for empty segments
-    if (segments.includes('')) return false;
-    // Check that ** only appears at the end
-    const doubleStarIndex = segments.indexOf('**');
-    if (doubleStarIndex !== -1 && doubleStarIndex !== segments.length - 1) {
-        return false;
-    }
-    return true;
+ * @param useForwarder - When true, uses relayer mint instead of user mint
+ * @returns Array of step executor configurations
+ */ function createStepExecutors(useForwarder = false) {
+    return [
+        {
+            name: 'approve',
+            executor: async (params, provider)=>bridgeApproval({
+                    params,
+                    provider
+                })
+        },
+        {
+            name: 'burn',
+            executor: async (params, provider)=>bridgeBurn({
+                    params,
+                    provider
+                }),
+            updateContext: (step)=>{
+                if (!step.txHash) {
+                    throw new KitError({
+                        ...InputError.VALIDATION_FAILED,
+                        recoverability: 'FATAL',
+                        message: 'Burn step completed but no transaction hash was returned'
+                    });
+                }
+                return {
+                    burnTxHash: step.txHash
+                };
+            }
+        },
+        {
+            name: 'fetchAttestation',
+            executor: async (params, provider, context)=>{
+                if (!context?.burnTxHash) {
+                    throw new KitError({
+                        ...InputError.VALIDATION_FAILED,
+                        recoverability: 'FATAL',
+                        message: 'Burn transaction hash not available for attestation'
+                    });
+                }
+                return bridgeFetchAttestation({
+                    params,
+                    provider
+                }, context.burnTxHash);
+            },
+            updateContext: (step)=>{
+                if (!step.data) {
+                    throw new KitError({
+                        ...InputError.VALIDATION_FAILED,
+                        recoverability: 'FATAL',
+                        message: 'Attestation step completed but no data was returned'
+                    });
+                }
+                return {
+                    attestationData: step.data
+                };
+            }
+        },
+        {
+            name: 'mint',
+            // bridgeRelayerMint validates context.burnTxHash internally with a KitError
+            // bridgeMint requires attestationData which is validated here
+            executor: useForwarder ? async (params, provider, context)=>{
+                if (!context) {
+                    throw new KitError({
+                        ...InputError.VALIDATION_FAILED,
+                        recoverability: 'FATAL',
+                        message: 'Step context is required for relayer mint'
+                    });
+                }
+                return bridgeRelayerMint({
+                    params,
+                    provider
+                }, context);
+            } : async (params, provider, context)=>{
+                if (!context?.attestationData) {
+                    throw new KitError({
+                        ...InputError.VALIDATION_FAILED,
+                        recoverability: 'FATAL',
+                        message: 'Attestation data not available for minting'
+                    });
+                }
+                return bridgeMint({
+                    params,
+                    provider
+                }, context.attestationData);
+            }
+        }
+    ];
 }
 /**
- * Convert a pattern to a regular expression.
+ * Helper function to create error step and set result state to error.
  *
- * @param pattern - The pattern to convert.
- * @returns A RegExp that matches topics according to the pattern.
- */ function patternToRegex(pattern) {
-    const segments = pattern.split('.');
-    // Handle ** at end specially to match zero or more segments
-    const lastSegment = segments.at(-1);
-    if (lastSegment === '**') {
-        // Everything before ** must match, then optionally more segments
-        const prefix = segments.slice(0, -1).map((seg)=>{
-            if (seg === '*') return '[^.]+';
-            return seg.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
-        }).join(String.raw`\.`);
-        // ** matches zero or more segments:
-        // - If prefix is empty (**), match anything
-        // - Otherwise, match prefix, then optionally (dot + more content)
-        if (prefix === '') {
-            return /^.*$/;
-        }
-        return new RegExp(String.raw`^${prefix}(?:\..*)?$`);
-    }
-    // No ** - just convert segments normally
-    const escaped = segments.map((segment)=>{
-        if (segment === '*') return '[^.]+';
-        return segment.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
-    }).join(String.raw`\.`);
-    return new RegExp(String.raw`^${escaped}$`);
+ * @param stepName - The name of the step that failed
+ * @param error - The error that occurred
+ * @param result - The bridge result object to update
+ */ function handleStepError(stepName, error, result) {
+    result.state = 'error';
+    result.steps.push({
+        name: stepName,
+        state: 'error',
+        error,
+        errorMessage: getErrorMessage(error)
+    });
 }
+
 /**
- * Execute an event handler with error isolation.
+ * Dispatch a bridge step event through the provider's action dispatcher.
  *
- * @param handler - The handler function to execute.
- * @param event - The event to pass to the handler.
- * @param logger - Optional logger for error reporting.
+ * Constructs the appropriate action payload and dispatches it to any registered
+ * event listeners. Handles type-safe dispatching for different step types.
+ * When provided, traceId from the invocation context is included for end-to-end correlation.
  *
- * @remarks
- * - Synchronous errors are caught and logged
- * - Promise rejections are caught without awaiting
- * - Handler errors never propagate to caller
- */ function executeHandler(handler, event, logger) {
-    try {
-        const result = handler(event);
-        // Handle promise rejection without awaiting
-        if (result instanceof Promise) {
-            result.catch((err)=>{
-                logger?.error('Event handler promise rejected', {
-                    event: event.name,
-                    error: extractErrorInfo(err)
-                });
+ * @param name - The step name (approve, burn, fetchAttestation, or mint).
+ * @param step - The completed bridge step containing transaction details and explorerUrl.
+ * @param provider - The CCTP v2 provider with action dispatcher.
+ * @param invocation - Optional invocation context containing traceId for correlation.
+ *
+ * @example
+ * ```typescript
+ * const step: BridgeStep = {
+ *   name: 'burn',
+ *   state: 'success',
+ *   txHash: '0xabc...',
+ *   explorerUrl: 'https://sepolia.etherscan.io/tx/0xabc...',
+ *   data: { ... }
+ * }
+ * dispatchStepEvent('burn', step, provider, invocationContext)
+ * ```
+ */ function dispatchStepEvent(name, step, provider, invocation) {
+    if (!provider.actionDispatcher) {
+        return;
+    }
+    // Extract traceId from invocation context if provided
+    const traceId = invocation?.traceId;
+    const actionValues = {
+        protocol: 'cctp',
+        version: 'v2',
+        ...traceId !== undefined && {
+            traceId
+        },
+        values: step
+    };
+    switch(name){
+        case 'approve':
+        case 'burn':
+        case 'mint':
+            provider.actionDispatcher.dispatch(name, {
+                ...actionValues,
+                method: name
             });
-        }
-    } catch (err) {
-        // Isolate handler errors
-        logger?.error('Event handler threw', {
-            event: event.name,
-            error: extractErrorInfo(err)
-        });
+            break;
+        case 'fetchAttestation':
+        case 'reAttest':
+            provider.actionDispatcher.dispatch(name, {
+                ...actionValues,
+                method: name,
+                values: step
+            });
+            break;
     }
 }
+
 /**
- * Create an event bus.
+ * Default clock implementation.
  *
- * @param opts - Options for the event bus.
- * @returns An EventBus instance.
+ * @packageDocumentation
+ */ /**
+ * Default clock implementation using `Date.now()`.
+ *
+ * @remarks
+ * Use this in production code. For testing, inject a mock clock
+ * that returns controlled timestamps.
  *
  * @example
  * ```typescript
- * import { createEventBus } from '@core/runtime'
+ * import { defaultClock } from '@core/runtime'
  *
- * const bus = createEventBus({ logger })
+ * const start = defaultClock.now()
+ * // ... do work ...
+ * const elapsed = defaultClock.since(start)
+ * ```
+ */ const defaultClock = {
+    now: ()=>Date.now(),
+    since: (start)=>Date.now() - start
+};
+
+// ============================================================================
+// Crypto Utilities (Internal)
+// ============================================================================
+/** @internal */ function hasGetRandomValues() {
+    return typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function';
+}
+/**
+ * Create a W3C/OpenTelemetry-compatible trace ID.
  *
- * // Subscribe to events
- * const unsubscribe = bus.on('tx.*', (event) => {
- *   console.log('Transaction event:', event.name)
- * })
+ * @returns 32-character lowercase hex string (128-bit).
  *
- * // Emit events
- * bus.emit({ name: 'tx.sent', data: { txHash: '0x123' } })
+ * @remarks
+ * **Standard function for generating `traceId` values.** Compatible with
+ * OpenTelemetry, Jaeger, Zipkin, and AWS X-Ray.
  *
- * // Unsubscribe
- * unsubscribe()
+ * @example
+ * ```typescript
+ * const traceId = createTraceId() // "a1b2c3d4e5f6789012345678abcdef00"
  * ```
- */ function createEventBus(opts) {
-    const logger = opts?.logger;
-    const subscriptions = new Set();
-    function createBus(baseTags) {
+ */ function createTraceId() {
+    const bytes = new Uint8Array(16);
+    if (hasGetRandomValues()) {
+        crypto.getRandomValues(bytes);
+    } else {
+        for(let i = 0; i < 16; i++){
+            bytes[i] = Math.floor(Math.random() * 256) // NOSONAR:
+            ;
+        }
+    }
+    return Array.from(bytes, (b)=>b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Clean tags by removing keys with undefined values.
+ *
+ * @param tags - Tags object, may contain undefined values. Accepts `undefined` or `null`.
+ * @returns A new object with undefined values removed, or empty object if input is nullish.
+ *
+ * @remarks
+ * This helper ensures tags are safe for serialization and logging.
+ * Similar to the internal `cleanUndefined` in the logger module, but
+ * typed specifically for {@link Tags}.
+ *
+ * @example
+ * ```typescript
+ * import { cleanTags } from '@core/runtime'
+ *
+ * const tags = { chain: 'Ethereum', amount: 100, extra: undefined }
+ * const cleaned = cleanTags(tags)
+ * // { chain: 'Ethereum', amount: 100 }
+ *
+ * const empty = cleanTags(undefined)
+ * // {}
+ * ```
+ */ function cleanTags(tags) {
+    if (tags == null) return {};
+    return Object.fromEntries(Object.entries(tags).filter(([, value])=>value !== undefined));
+}
+
+/**
+ * Check if a pattern is valid.
+ *
+ * @remarks
+ * Invalid patterns:
+ * - Empty segments (e.g., `a..b`, `.a`, `a.`)
+ * - `**` not at end (e.g., `a.**.b`)
+ *
+ * @param pattern - The pattern to validate.
+ * @returns True if valid, false otherwise.
+ */ function isValidPattern(pattern) {
+    // Empty pattern is valid (matches empty topic)
+    if (pattern === '') return true;
+    const segments = pattern.split('.');
+    // Check for empty segments
+    if (segments.includes('')) return false;
+    // Check that ** only appears at the end
+    const doubleStarIndex = segments.indexOf('**');
+    if (doubleStarIndex !== -1 && doubleStarIndex !== segments.length - 1) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Convert a pattern to a regular expression.
+ *
+ * @param pattern - The pattern to convert.
+ * @returns A RegExp that matches topics according to the pattern.
+ */ function patternToRegex(pattern) {
+    const segments = pattern.split('.');
+    // Handle ** at end specially to match zero or more segments
+    const lastSegment = segments.at(-1);
+    if (lastSegment === '**') {
+        // Everything before ** must match, then optionally more segments
+        const prefix = segments.slice(0, -1).map((seg)=>{
+            if (seg === '*') return '[^.]+';
+            return seg.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+        }).join(String.raw`\.`);
+        // ** matches zero or more segments:
+        // - If prefix is empty (**), match anything
+        // - Otherwise, match prefix, then optionally (dot + more content)
+        if (prefix === '') {
+            return /^.*$/;
+        }
+        return new RegExp(String.raw`^${prefix}(?:\..*)?$`);
+    }
+    // No ** - just convert segments normally
+    const escaped = segments.map((segment)=>{
+        if (segment === '*') return '[^.]+';
+        return segment.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+    }).join(String.raw`\.`);
+    return new RegExp(String.raw`^${escaped}$`);
+}
+/**
+ * Execute an event handler with error isolation.
+ *
+ * @param handler - The handler function to execute.
+ * @param event - The event to pass to the handler.
+ * @param logger - Optional logger for error reporting.
+ *
+ * @remarks
+ * - Synchronous errors are caught and logged
+ * - Promise rejections are caught without awaiting
+ * - Handler errors never propagate to caller
+ */ function executeHandler(handler, event, logger) {
+    try {
+        const result = handler(event);
+        // Handle promise rejection without awaiting
+        if (result instanceof Promise) {
+            result.catch((err)=>{
+                logger?.error('Event handler promise rejected', {
+                    event: event.name,
+                    error: extractErrorInfo(err)
+                });
+            });
+        }
+    } catch (err) {
+        // Isolate handler errors
+        logger?.error('Event handler threw', {
+            event: event.name,
+            error: extractErrorInfo(err)
+        });
+    }
+}
+/**
+ * Create an event bus.
+ *
+ * @param opts - Options for the event bus.
+ * @returns An EventBus instance.
+ *
+ * @example
+ * ```typescript
+ * import { createEventBus } from '@core/runtime'
+ *
+ * const bus = createEventBus({ logger })
+ *
+ * // Subscribe to events
+ * const unsubscribe = bus.on('tx.*', (event) => {
+ *   console.log('Transaction event:', event.name)
+ * })
+ *
+ * // Emit events
+ * bus.emit({ name: 'tx.sent', data: { txHash: '0x123' } })
+ *
+ * // Unsubscribe
+ * unsubscribe()
+ * ```
+ */ function createEventBus(opts) {
+    const logger = opts?.logger;
+    const subscriptions = new Set();
+    function createBus(baseTags) {
         return {
             emit (event) {
                 // Invalid topic names silently don't match any subscriptions
@@ -12006,10 +12775,15 @@ const mockAttestationMessage = {
     const burnCallData = burnRequest.getCallData();
     // batchExecute may throw before submission (wallet declined) but never
     // after — post-submission errors are returned as empty receipts.
+    // The sender is threaded for adapters whose execution is routed through a
+    // signing strategy (which has no wallet account to read it from); the
+    // wallet-client path ignores it.
     const batchResult = await adapter.batchExecute([
         approveCallData,
         burnCallData
-    ], chain);
+    ], chain, {
+        fromAddress: params.source.address
+    });
     const approveReceipt = batchResult.receipts[0];
     const burnReceipt = batchResult.receipts[1];
     const approveStep = await buildBatchedStep('approve', approveReceipt, batchResult.batchId, adapter, chain, batchResult.statusCode, batchResult.error);
@@ -12148,595 +12922,275 @@ const mockAttestationMessage = {
         step.error = err;
         step.errorMessage = err instanceof Error ? err.message : 'Unknown error during confirmation.';
         step.errorCategory = 'unknown';
-    }
-    return step;
-}
-
-var version = "1.8.5";
-var pkg = {
-	version: version};
-
-/**
- * Provider caller component for bridge operations.
- */ const BRIDGE_CALLER = {
-    type: 'provider',
-    name: 'CCTPV2BridgingProvider.bridge',
-    version: pkg.version
-};
-/**
- * Resolve invocation context for bridge operations.
- *
- * Creates or extends invocation context with the bridge caller.
- *
- * @param invocationMeta - Optional invocation metadata provided by caller.
- * @returns Resolved invocation context with bridge caller.
- *
- * @internal
- */ function resolveBridgeInvocation(invocationMeta) {
-    const defaults = {
-        runtime: createRuntime(),
-        tokens: createTokenRegistry()
-    };
-    return extendInvocationContext(resolveInvocationContext(invocationMeta, defaults), BRIDGE_CALLER);
-}
-/**
- * Execute the batched approve + burn path via EIP-5792.
- *
- * Mutate `result` with step data and error state as needed. Return the
- * batch context on success, or `undefined` when the batch failed (in
- * which case `result.state` is set to `'error'`).
- *
- * @internal
- * @param params - Bridge parameters (read-only).
- * @param provider - The CCTP v2 bridging provider (read-only).
- * @param result - Bridge result object — **mutated in place** with step
- *   data and, on failure, `state: 'error'` plus an `error` payload.
- * @param invocation - Invocation context for telemetry (read-only).
- * @returns The step context on success, or `undefined` when the batch failed.
- */ async function executeBatchedPath(params, provider, result, invocation) {
-    // IMPORTANT: once executeBatchedApproveAndBurn is called, we NEVER
-    // fall back to sequential. The wallet may have already signed &
-    // submitted the batch; retrying as individual txs would double-spend.
-    try {
-        const { approveStep, burnStep, context: batchContext } = await executeBatchedApproveAndBurn(params, provider);
-        for (const step of [
-            approveStep,
-            burnStep
-        ]){
-            const stepName = step.name;
-            if (step.state === 'error') {
-                ensureStepErrorMessage(step.name, step);
-                result.steps.push(step);
-                result.state = 'error';
-                dispatchStepEvent(stepName, step, provider, invocation);
-                return undefined;
-            }
-            dispatchStepEvent(stepName, step, provider, invocation);
-            result.steps.push(step);
-        }
-        return batchContext;
-    } catch (error_) {
-        // Only handles pre-submission failures (prepare rejected, wallet
-        // declined, etc.). batchExecute never throws after sendCalls succeeds.
-        result.state = 'error';
-        result.steps.push({
-            name: 'batch',
-            state: 'error',
-            batched: true,
-            error: error_,
-            errorMessage: error_ instanceof Error ? error_.message : 'Batched approve + burn failed.',
-            errorCategory: classifyPreSubmissionError(error_)
-        });
-        return undefined;
-    }
-}
-/**
- * Ensure `step.errorMessage` is populated when an error object exists.
- *
- * @internal
- */ function ensureStepErrorMessage(name, step) {
-    if (!step.errorMessage && step.error) {
-        step.errorMessage = `${name} step failed: ${getErrorMessage(step.error)}`;
-    }
-}
-/**
- * Coerce a raw JSON-RPC `code` to a number.
- *
- * Some wallet SDKs serialize the JSON-RPC `code` as a string ("4001")
- * after round-tripping through JSON; accept both shapes so strict `===`
- * comparisons downstream still classify 5720/5730/5740 correctly — those
- * codes have no message-pattern fallback.
- *
- * @param rawCode - The raw `code` extracted from the error object.
- * @returns The numeric code, or `undefined` if the value cannot be parsed.
- *
- * @internal
- */ function coerceRpcCode(rawCode) {
-    if (typeof rawCode === 'number') {
-        return rawCode;
-    }
-    if (typeof rawCode === 'string') {
-        return Number.parseInt(rawCode, 10);
-    }
-    return undefined;
-}
-/**
- * Classify a pre-submission error thrown during `wallet_sendCalls`.
- *
- * Inspect the error's JSON-RPC `code` (falling back to message pattern
- * matching for wrapper errors like viem's `ChainMismatchError`) and map
- * it to a {@link BridgeStepErrorCategory}. This lets downstream consumers
- * distinguish user rejections, wallet capability gaps, and unknown
- * failures without parsing error messages.
- *
- * @remarks
- * Does NOT alter control flow — the SDK continues to surface a
- * `state: 'error'` step. Auto-fallback to sequential execution is
- * intentionally out of scope for this helper.
- *
- * @param err - The error thrown by `wallet_sendCalls`.
- * @returns The derived error category, or `'unknown'` if no match.
- *
- * @internal
- */ function classifyPreSubmissionError(err) {
-    // Cross-realm-safe duck typing: `instanceof Error` returns false for
-    // errors thrown in a different JavaScript realm (e.g., a wallet
-    // provider running inside an iframe, which is common with WalletConnect
-    // and the Coinbase Wallet SDK).
-    if (typeof err !== 'object' || err === null || !('message' in err)) {
-        return 'unknown';
-    }
-    const code = coerceRpcCode(err.code);
-    const message = String(err.message);
-    // Numeric JSON-RPC codes are authoritative; check them before falling
-    // back to message-pattern matching. Order matters: an error carrying
-    // `code === 5750` with a message like "user rejected the upgrade"
-    // is a capability problem, not a plain user rejection.
-    if (code === 4001) {
-        return 'user_rejected';
-    }
-    if (code === 5700 || code === 5710 || code === 5750) {
-        return 'atomic_unsupported';
-    }
-    if (code === 5720) {
-        return 'duplicate_batch_id';
-    }
-    if (code === 5730) {
-        return 'unknown_bundle';
-    }
-    if (code === 5740) {
-        return 'batch_too_large';
-    }
-    // Fall back to message patterns when no specific code is available —
-    // viem (and other wrapper layers) sometimes strip the numeric code
-    // while preserving the original wallet message in `Details:`.
-    if (/EIP-7702 not supported/i.test(message) || /does not support the requested chain/i.test(message) || /rejected the upgrade/i.test(message)) {
-        return 'atomic_unsupported';
-    }
-    if (/user rejected/i.test(message)) {
-        return 'user_rejected';
-    }
-    return 'unknown';
-}
-/**
- * Execute a cross-chain USDC bridge using the CCTP v2 protocol.
- *
- * @remarks
- * This function performs the full CCTP v2 bridge flow: token approval, burning on the source chain,
- * attestation fetching, and minting on the destination chain. Each step is validated and dispatched
- * through the provider's action dispatcher. If any step fails, the bridge result will have state 'error'.
- * Each step includes transaction details and explorer URLs for easy verification on block explorers.
- *
- * @param params - The bridge parameters containing source, destination, amount, and optional config.
- * @param provider - The CCTP v2 bridging provider instance.
- * @returns A promise resolving to the bridge result, including transaction details, step states, and explorer URLs.
- *
- * @throws Will propagate errors thrown by underlying step functions (approval, burn, attestation, mint) if they throw unexpectedly.
- *
- * @example
- * ```typescript
- * import { bridge } from '@circle-fin/provider-cctp-v2/provider/bridge/bridge'
- * // ...setup params and provider...
- * const result = await bridge(params, provider)
- * if (result.state === 'success') {
- *   console.log('Bridge completed!')
- *   result.steps.forEach(step => {
- *     if (step.explorerUrl) {
- *       console.log(`${step.name}: ${step.explorerUrl}`)
- *     }
- *   })
- * } else {
- *   console.error('Bridge failed at step:', result.steps.find(s => s.state === 'error'))
- * }
- * ```
- */ async function bridge(params, provider) {
-    const useForwarder = params.destination.useForwarder === true;
-    const invocation = resolveBridgeInvocation(params.invocationMeta);
-    const result = {
-        state: 'pending',
-        amount: params.amount,
-        token: params.token,
-        source: {
-            address: params.source.address,
-            chain: params.source.chain
-        },
-        destination: {
-            address: params.destination.address,
-            chain: params.destination.chain,
-            ...params.destination.recipientAddress && {
-                recipientAddress: params.destination.recipientAddress
-            },
-            ...useForwarder && {
-                useForwarder: true
-            }
-        },
-        steps: [],
-        config: params.config,
-        provider: provider.name
-    };
-    let context = undefined;
-    let useBatched = false;
-    try {
-        useBatched = await shouldUseBatchedExecution(params);
-    } catch  {
-    // Silently fall back to sequential
-    }
-    const executors = createStepExecutors(useForwarder);
-    if (useBatched) {
-        const batchContext = await executeBatchedPath(params, provider, result, invocation);
-        if (result.state === 'error') {
-            return result;
-        }
-        context = batchContext;
-    }
-    const stepsToRun = useBatched ? executors.filter(({ name })=>name !== 'approve' && name !== 'burn') : executors;
-    for (const { name, executor, updateContext } of stepsToRun){
-        try {
-            const step = await executor(params, provider, context);
-            if (step.state === 'error') {
-                ensureStepErrorMessage(name, step);
-                result.steps.push(step);
-                result.state = 'error';
-                dispatchStepEvent(name, step, provider, invocation);
-                return result;
-            }
-            const newContext = updateContext?.(step);
-            if (newContext) {
-                context = {
-                    ...context,
-                    ...newContext
-                };
-            }
-            dispatchStepEvent(name, step, provider, invocation);
-            result.steps.push(step);
-        } catch (error) {
-            handleStepError(name, error, result);
-            return result;
-        }
-    }
-    result.state = 'success';
-    return result;
-}
-
-/**
- * Resolves an operation context into concrete chain and address values.
- *
- * This function ensures that action handlers always receive defined chain and address
- * values by applying validation and resolution logic based on the adapter's capabilities.
- * It enforces compile-time and runtime address requirements based on the adapter's
- * address control model.
- *
- * **Resolution logic**:
- * - **Chain**: Uses provided chain identifier and resolves to ChainDefinition
- * - **Address**:
- *   - For user-controlled adapters: Retrieves current address from adapter (context address ignored)
- *   - For developer-controlled adapters: Uses address provided in context (required)
- *
- * @typeParam TAdapterCapabilities - The adapter capabilities type for compile-time validation
- * @param adapter - The typed adapter instance with capabilities defined
- * @param ctx - Operation context with compile-time validated address requirements
- * @returns Promise resolving to concrete chain and address values
- * @throws Error when adapter capabilities are not defined
- * @throws Error when operation context is not provided
- * @throws Error when address is required but not provided (developer-controlled)
- * @throws Error when adapter.getAddress() fails (user-controlled)
- *
- * @example
- * ```typescript
- * import { resolveOperationContext } from '@core/adapter'
- *
- * // User-controlled adapter - address forbidden in context
- * const userAdapter: Adapter<{ addressContext: 'user-controlled', supportedChains: [] }>
- * const resolved = await resolveOperationContext(userAdapter, {
- *   chain: 'Base' // address will be resolved from wallet
- * })
- * console.log(resolved.chain)   // ChainDefinition - always defined
- * console.log(resolved.address) // string - resolved from adapter
- *
- * // Developer-controlled adapter - address required in context
- * const devAdapter: Adapter<{ addressContext: 'developer-controlled', supportedChains: [] }>
- * const resolved = await resolveOperationContext(devAdapter, {
- *   chain: 'Base',
- *   address: '0x123...' // Required and enforced at compile time
- * })
- * console.log(resolved.address) // '0x123...' - from context
- * ```
- */ async function resolveOperationContext(adapter, ctx) {
-    // Adapter must have capabilities defined
-    if (adapter.capabilities === undefined) {
-        throw new Error('Adapter capabilities must be defined. Please ensure the adapter implements the capabilities property.');
-    }
-    // Operation context is required for new typed adapters
-    if (ctx === undefined) {
-        throw new Error('Operation context is required. Please provide a context with the required chain and address information.');
-    }
-    // Resolve chain from context (required)
-    const resolvedChain = resolveChainIdentifier(ctx.chain);
-    // Resolve address based on adapter capabilities
-    let resolvedAddress;
-    if (adapter.capabilities.addressContext === 'developer-controlled') {
-        // Developer-controlled: address must be explicitly provided
-        if (!ctx.address) {
-            throw new Error('Address is required for developer-controlled adapters. Please provide an address in the operation context.');
-        }
-        resolvedAddress = ctx.address;
-    } else {
-        // User-controlled: get current address from adapter
-        try {
-            // Pass resolved chain to getAddress for adapters that support it (like ViemAdapter)
-            // The chain parameter is optional in implementations, so this is safe
-            resolvedAddress = await adapter.getAddress(resolvedChain);
-        } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Failed to resolve address from user-controlled adapter: ${message}`);
-        }
-    }
-    return {
-        chain: resolvedChain,
-        address: resolvedAddress
-    };
+    }
+    return step;
 }
 
+var version = "1.10.0";
+var pkg = {
+	version: version};
+
 /**
- * Schema for validating hexadecimal strings with '0x' prefix.
- *
- * This schema validates that a string:
- * - Is a string type
- * - Is not empty after trimming
- * - Starts with '0x'
- * - Contains only valid hexadecimal characters (0-9, a-f, A-F) after '0x'
- *
- * @remarks
- * This schema does not validate length, making it suitable for various hex string types
- * like addresses, transaction hashes, and other hex-encoded data.
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
- *
- * @example
- * ```typescript
- * import { hexStringSchema } from '@core/adapter'
- *
- * const validAddress = '0x1234567890123456789012345678901234567890'
- * const validTxHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
- *
- * const addressResult = hexStringSchema.safeParse(validAddress)
- * const txHashResult = hexStringSchema.safeParse(validTxHash)
- * console.log(addressResult.success) // true
- * console.log(txHashResult.success) // true
- * ```
- */ const hexStringSchema = zod.z.string().min(1, 'Hex string is required').refine((value)=>value.trim().length > 0, 'Hex string cannot be empty').refine((value)=>value.startsWith('0x'), 'Hex string must start with 0x prefix').refine((value)=>{
-    const hexPattern = /^0x[0-9a-fA-F]+$/;
-    return hexPattern.test(value);
-}, 'Hex string contains invalid characters. Only hexadecimal characters (0-9, a-f, A-F) are allowed after 0x');
+ * Provider caller component for bridge operations.
+ */ const BRIDGE_CALLER = {
+    type: 'provider',
+    name: 'CCTPV2BridgingProvider.bridge',
+    version: pkg.version
+};
 /**
- * Schema for validating EVM addresses.
- *
- * This schema validates that a string is a properly formatted EVM address:
- * - Must be a valid hex string with '0x' prefix
- * - Must be exactly 42 characters long (0x + 40 hex characters)
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ * Resolve invocation context for bridge operations.
  *
- * @example
- * ```typescript
- * import { evmAddressSchema } from '@core/adapter'
+ * Creates or extends invocation context with the bridge caller.
  *
- * const validAddress = '0x1234567890123456789012345678901234567890'
+ * @param invocationMeta - Optional invocation metadata provided by caller.
+ * @returns Resolved invocation context with bridge caller.
  *
- * const result = evmAddressSchema.safeParse(validAddress)
- * console.log(result.success) // true
- * ```
- */ hexStringSchema.refine((value)=>value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)').transform((value)=>value);
+ * @internal
+ */ function resolveBridgeInvocation(invocationMeta) {
+    const defaults = {
+        runtime: createRuntime(),
+        tokens: createTokenRegistry()
+    };
+    return extendInvocationContext(resolveInvocationContext(invocationMeta, defaults), BRIDGE_CALLER);
+}
 /**
- * Schema for validating transaction hashes.
- *
- * This schema validates that a string is a properly formatted transaction hash:
- * - Must be a valid hex string with '0x' prefix
- * - Must be exactly 66 characters long (0x + 64 hex characters)
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
- *
- * @example
- * ```typescript
- * import { evmTransactionHashSchema } from '@core/adapter'
+ * Execute the batched approve + burn path via EIP-5792.
  *
- * const validTxHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+ * Mutate `result` with step data and error state as needed. Return the
+ * batch context on success, or `undefined` when the batch failed (in
+ * which case `result.state` is set to `'error'`).
  *
- * const result = evmTransactionHashSchema.safeParse(validTxHash)
- * console.log(result.success) // true
- * ```
- */ hexStringSchema.refine((value)=>value.length === 66, 'Transaction hash must be exactly 66 characters long (0x + 64 hex characters)');
+ * @internal
+ * @param params - Bridge parameters (read-only).
+ * @param provider - The CCTP v2 bridging provider (read-only).
+ * @param result - Bridge result object — **mutated in place** with step
+ *   data and, on failure, `state: 'error'` plus an `error` payload.
+ * @param invocation - Invocation context for telemetry (read-only).
+ * @returns The step context on success, or `undefined` when the batch failed.
+ */ async function executeBatchedPath(params, provider, result, invocation) {
+    // IMPORTANT: once executeBatchedApproveAndBurn is called, we NEVER
+    // fall back to sequential. The wallet may have already signed &
+    // submitted the batch; retrying as individual txs would double-spend.
+    try {
+        const { approveStep, burnStep, context: batchContext } = await executeBatchedApproveAndBurn(params, provider);
+        for (const step of [
+            approveStep,
+            burnStep
+        ]){
+            const stepName = step.name;
+            if (step.state === 'error') {
+                ensureStepErrorMessage(step.name, step);
+                result.steps.push(step);
+                result.state = 'error';
+                dispatchStepEvent(stepName, step, provider, invocation);
+                return undefined;
+            }
+            dispatchStepEvent(stepName, step, provider, invocation);
+            result.steps.push(step);
+        }
+        return batchContext;
+    } catch (error_) {
+        // Only handles pre-submission failures (prepare rejected, wallet
+        // declined, etc.). batchExecute never throws after sendCalls succeeds.
+        result.state = 'error';
+        result.steps.push({
+            name: 'batch',
+            state: 'error',
+            batched: true,
+            error: error_,
+            errorMessage: error_ instanceof Error ? error_.message : 'Batched approve + burn failed.',
+            errorCategory: classifyPreSubmissionError(error_)
+        });
+        return undefined;
+    }
+}
 /**
- * Schema for validating EVM signatures.
- *
- * This schema validates that a string is a properly formatted 65-byte EVM
- * signature:
- * - Must be a valid hex string with '0x' prefix
- * - Must be exactly 132 characters long (0x + 130 hex characters)
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
- *
- * @example
- * ```typescript
- * import { evmSignatureSchema } from '@core/adapter'
- *
- * const validSignature = `0x${'ab'.repeat(65)}`
+ * Ensure `step.errorMessage` is populated when an error object exists.
  *
- * const result = evmSignatureSchema.safeParse(validSignature)
- * console.log(result.success) // true
- * ```
- */ hexStringSchema.refine((value)=>value.length === 132, 'EVM signature must be exactly 132 characters long (0x + 130 hex characters)').transform((value)=>value);
+ * @internal
+ */ function ensureStepErrorMessage(name, step) {
+    if (!step.errorMessage && step.error) {
+        step.errorMessage = `${name} step failed: ${getErrorMessage(step.error)}`;
+    }
+}
 /**
- * Schema for validating base58-encoded strings.
- *
- * This schema validates that a string:
- * - Is a string type
- * - Is not empty after trimming
- * - Contains only valid base58 characters (1-9, A-H, J-N, P-Z, a-k, m-z)
- * - Does not contain commonly confused characters (0, O, I, l)
- *
- * @remarks
- * This schema does not validate length, making it suitable for various base58-encoded data
- * like Solana addresses, transaction signatures, and other base58-encoded data.
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ * Coerce a raw JSON-RPC `code` to a number.
  *
- * @example
- * ```typescript
- * import { base58StringSchema } from '@core/adapter'
+ * Some wallet SDKs serialize the JSON-RPC `code` as a string ("4001")
+ * after round-tripping through JSON; accept both shapes so strict `===`
+ * comparisons downstream still classify 5720/5730/5740 correctly — those
+ * codes have no message-pattern fallback.
  *
- * const validAddress = 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN'
- * const validTxHash = '3Jf8k2L5mN9pQ7rS1tV4wX6yZ8aB2cD4eF5gH7iJ9kL1mN3oP5qR7sT9uV1wX3yZ5'
+ * @param rawCode - The raw `code` extracted from the error object.
+ * @returns The numeric code, or `undefined` if the value cannot be parsed.
  *
- * const addressResult = base58StringSchema.safeParse(validAddress)
- * const txHashResult = base58StringSchema.safeParse(validTxHash)
- * console.log(addressResult.success) // true
- * console.log(txHashResult.success) // true
- * ```
- */ const base58StringSchema = zod.z.string().min(1, 'Base58 string is required').refine((value)=>value.trim().length > 0, 'Base58 string cannot be empty').refine((value)=>{
-    // Base58 alphabet: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
-    // Excludes: 0, O, I, l to avoid confusion
-    const base58Pattern = /^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$/;
-    return base58Pattern.test(value);
-}, 'Base58 string contains invalid characters. Only base58 characters (1-9, A-H, J-N, P-Z, a-k, m-z) are allowed');
+ * @internal
+ */ function coerceRpcCode(rawCode) {
+    if (typeof rawCode === 'number') {
+        return rawCode;
+    }
+    if (typeof rawCode === 'string') {
+        return Number.parseInt(rawCode, 10);
+    }
+    return undefined;
+}
 /**
- * Schema for validating Solana addresses.
- *
- * This schema validates that a string is a properly formatted Solana address:
- * - Must be a valid base58-encoded string
- * - Must be between 32-44 characters long (typical length for base58-encoded 32-byte addresses)
+ * Classify a pre-submission error thrown during `wallet_sendCalls`.
  *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ * Inspect the error's JSON-RPC `code` (falling back to message pattern
+ * matching for wrapper errors like viem's `ChainMismatchError`) and map
+ * it to a {@link BridgeStepErrorCategory}. This lets downstream consumers
+ * distinguish user rejections, wallet capability gaps, and unknown
+ * failures without parsing error messages.
  *
- * @example
- * ```typescript
- * import { solanaAddressSchema } from '@core/adapter'
+ * @remarks
+ * Does NOT alter control flow — the SDK continues to surface a
+ * `state: 'error'` step. Auto-fallback to sequential execution is
+ * intentionally out of scope for this helper.
  *
- * const validAddress = 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN'
+ * @param err - The error thrown by `wallet_sendCalls`.
+ * @returns The derived error category, or `'unknown'` if no match.
  *
- * const result = solanaAddressSchema.safeParse(validAddress)
- * console.log(result.success) // true
- * ```
- */ base58StringSchema.refine((value)=>value.length >= 32 && value.length <= 44, 'Solana address must be between 32-44 characters long (base58-encoded 32-byte address)');
+ * @internal
+ */ function classifyPreSubmissionError(err) {
+    // Cross-realm-safe duck typing: `instanceof Error` returns false for
+    // errors thrown in a different JavaScript realm (e.g., a wallet
+    // provider running inside an iframe, which is common with WalletConnect
+    // and the Coinbase Wallet SDK).
+    if (typeof err !== 'object' || err === null || !('message' in err)) {
+        return 'unknown';
+    }
+    const code = coerceRpcCode(err.code);
+    const message = String(err.message);
+    // Numeric JSON-RPC codes are authoritative; check them before falling
+    // back to message-pattern matching. Order matters: an error carrying
+    // `code === 5750` with a message like "user rejected the upgrade"
+    // is a capability problem, not a plain user rejection.
+    if (code === 4001) {
+        return 'user_rejected';
+    }
+    if (code === 5700 || code === 5710 || code === 5750) {
+        return 'atomic_unsupported';
+    }
+    if (code === 5720) {
+        return 'duplicate_batch_id';
+    }
+    if (code === 5730) {
+        return 'unknown_bundle';
+    }
+    if (code === 5740) {
+        return 'batch_too_large';
+    }
+    // Fall back to message patterns when no specific code is available —
+    // viem (and other wrapper layers) sometimes strip the numeric code
+    // while preserving the original wallet message in `Details:`.
+    if (/EIP-7702 not supported/i.test(message) || /does not support the requested chain/i.test(message) || /rejected the upgrade/i.test(message)) {
+        return 'atomic_unsupported';
+    }
+    if (/user rejected/i.test(message)) {
+        return 'user_rejected';
+    }
+    return 'unknown';
+}
 /**
- * Schema for validating Solana transaction hashes.
- *
- * This schema validates that a string is a properly formatted Solana transaction hash:
- * - Must be a valid base58-encoded string
- * - Must be between 86-88 characters long (typical length for base58-encoded 64-byte signatures)
- *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
- *
- * @example
- * ```typescript
- * import { solanaTransactionHashSchema } from '@core/adapter'
- *
- * const validTxHash = '5VfYmGBjvQKe3xgLtTQPSMEUdpEVHrJwLK7pKBJWKzYpNBE2g3kJrq7RSe9M8DqzQJ5J2aZPTjHLvd4WgxPpJKS'
+ * Execute a cross-chain USDC bridge using the CCTP v2 protocol.
  *
- * const result = solanaTransactionHashSchema.safeParse(validTxHash)
- * console.log(result.success) // true
- * ```
- */ base58StringSchema.refine((value)=>value.length >= 86 && value.length <= 88, 'Solana transaction hash must be between 86-88 characters long (base58-encoded 64-byte signature)');
-/**
- * Schema for validating Adapter objects.
- * Checks for the required methods that define an Adapter.
- */ zod.z.object({
-    prepare: zod.z.function(),
-    waitForTransaction: zod.z.function(),
-    getAddress: zod.z.function()
-});
-
-/**
- * Validate that the adapter has sufficient token balance for a transaction.
+ * @remarks
+ * This function performs the full CCTP v2 bridge flow: token approval, burning on the source chain,
+ * attestation fetching, and minting on the destination chain. Each step is validated and dispatched
+ * through the provider's action dispatcher. If any step fails, the bridge result will have state 'error'.
+ * Each step includes transaction details and explorer URLs for easy verification on block explorers.
  *
- * This function checks if the adapter's current token balance is greater than or equal
- * to the requested transaction amount. It throws a KitError with code 9001
- * (BALANCE_INSUFFICIENT_TOKEN) if the balance is insufficient, providing detailed
- * information about the shortfall.
+ * @param params - The bridge parameters containing source, destination, amount, and optional config.
+ * @param provider - The CCTP v2 bridging provider instance.
+ * @returns A promise resolving to the bridge result, including transaction details, step states, and explorer URLs.
  *
- * @param params - The validation parameters containing adapter, amount, token, and token address.
- * @returns A promise that resolves to void if validation passes.
- * @throws {KitError} When the adapter's balance is less than the required amount (code: 9001).
+ * @throws Will propagate errors thrown by underlying step functions (approval, burn, attestation, mint) if they throw unexpectedly.
  *
  * @example
  * ```typescript
- * import { validateBalanceForTransaction } from '@core/adapter'
- * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
- * import { isKitError, ERROR_TYPES } from '@core/errors'
- *
- * const adapter = createViemAdapterFromPrivateKey({
- *   privateKey: '0x...',
- *   chain: 'Ethereum',
- * })
- *
- * try {
- *   await validateBalanceForTransaction({
- *     adapter,
- *     amount: '1000000', // 1 USDC (6 decimals)
- *     token: 'USDC',
- *     tokenAddress: '0xA0b86a33E6441c8C1c7C16e4c5e3e5b5e4c5e3e5b5e4c5e',
- *     operationContext: { chain: 'Ethereum' },
+ * import { bridge } from '@circle-fin/provider-cctp-v2/provider/bridge/bridge'
+ * // ...setup params and provider...
+ * const result = await bridge(params, provider)
+ * if (result.state === 'success') {
+ *   console.log('Bridge completed!')
+ *   result.steps.forEach(step => {
+ *     if (step.explorerUrl) {
+ *       console.log(`${step.name}: ${step.explorerUrl}`)
+ *     }
  *   })
- *   console.log('Balance validation passed')
- * } catch (error) {
- *   if (isKitError(error) && error.type === ERROR_TYPES.BALANCE) {
- *     console.error('Insufficient funds:', error.message)
- *   }
+ * } else {
+ *   console.error('Bridge failed at step:', result.steps.find(s => s.state === 'error'))
  * }
  * ```
- */ const validateBalanceForTransaction = async (params)=>{
-    const { amount, adapter, token, tokenAddress, operationContext } = params;
-    const balancePrepared = await adapter.prepareAction('usdc.balanceOf', {
-        walletAddress: operationContext.address
-    }, operationContext);
-    const balance = await balancePrepared.execute();
-    if (BigInt(balance) < BigInt(amount)) {
-        // Extract chain name from operationContext
-        const chainName = extractChainInfo(operationContext.chain).name;
-        // Create KitError with rich context in trace
-        throw createInsufficientTokenBalanceError(chainName, token, {
-            balance: balance.toString(),
-            amount,
-            tokenAddress,
-            walletAddress: operationContext.address
-        });
+ */ async function bridge(params, provider) {
+    const useForwarder = params.destination.useForwarder === true;
+    const invocation = resolveBridgeInvocation(params.invocationMeta);
+    const result = {
+        state: 'pending',
+        amount: params.amount,
+        token: params.token,
+        source: {
+            address: params.source.address,
+            chain: params.source.chain
+        },
+        destination: {
+            address: params.destination.address,
+            chain: params.destination.chain,
+            ...params.destination.recipientAddress && {
+                recipientAddress: params.destination.recipientAddress
+            },
+            ...useForwarder && {
+                useForwarder: true
+            }
+        },
+        steps: [],
+        config: params.config,
+        provider: provider.name
+    };
+    let context = undefined;
+    let useBatched = false;
+    try {
+        useBatched = await shouldUseBatchedExecution(params);
+    } catch  {
+    // Silently fall back to sequential
     }
-};
-
-/**
- * Permit signature standards for gasless token approvals.
- *
- * Defines the permit types that can be used to approve token spending
- * without requiring a separate approval transaction.
- *
- * @remarks
- * - NONE: No permit, tokens must be pre-approved via separate transaction
- * - EIP2612: Standard ERC-20 permit (USDC, DAI v2, and most modern tokens)
- */ var PermitType;
-(function(PermitType) {
-    /** No permit required - tokens must be pre-approved */ PermitType[PermitType["NONE"] = 0] = "NONE";
-    /** EIP-2612 standard permit */ PermitType[PermitType["EIP2612"] = 1] = "EIP2612";
-})(PermitType || (PermitType = {}));
+    const executors = createStepExecutors(useForwarder);
+    if (useBatched) {
+        const batchContext = await executeBatchedPath(params, provider, result, invocation);
+        if (result.state === 'error') {
+            return result;
+        }
+        context = batchContext;
+    }
+    const stepsToRun = useBatched ? executors.filter(({ name })=>name !== 'approve' && name !== 'burn') : executors;
+    for (const { name, executor, updateContext } of stepsToRun){
+        try {
+            const step = await executor(params, provider, context);
+            if (step.state === 'error') {
+                ensureStepErrorMessage(name, step);
+                result.steps.push(step);
+                result.state = 'error';
+                dispatchStepEvent(name, step, provider, invocation);
+                return result;
+            }
+            const newContext = updateContext?.(step);
+            if (newContext) {
+                context = {
+                    ...context,
+                    ...newContext
+                };
+            }
+            dispatchStepEvent(name, step, provider, invocation);
+            result.steps.push(step);
+        } catch (error) {
+            handleStepError(name, error, result);
+            return result;
+        }
+    }
+    result.state = 'success';
+    return result;
+}
 
 /**
  * Determine if a step executes on the source chain.
@@ -13178,6 +13632,39 @@ var pkg = {
     }
 }
 
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function assertHeadersConfig(headers, field) {
+    if (headers === undefined) {
+        return;
+    }
+    if (!isPlainObject(headers)) {
+        throw createValidationFailedError(field, headers, `${field} must be a plain object with string header values when provided`);
+    }
+    for (const [name, value] of Object.entries(headers)){
+        if (typeof value !== 'string') {
+            throw createValidationFailedError(`${field}.${name}`, value, 'header values must be strings');
+        }
+    }
+}
+function assertCCTPV2Config(config) {
+    if (!isPlainObject(config)) {
+        throw createValidationFailedError('config', config, 'config must be a plain object when provided');
+    }
+    assertHeadersConfig(config['headers'], 'config.headers');
+    const attestation = config['attestation'];
+    if (attestation !== undefined) {
+        if (!isPlainObject(attestation)) {
+            throw createValidationFailedError('config.attestation', attestation, 'config.attestation must be a plain object when provided');
+        }
+        assertHeadersConfig(attestation['headers'], 'config.attestation.headers');
+    }
+}
 /**
  * All chains that are supported by the CCTP v2 provider.
  *
@@ -13246,9 +13733,38 @@ var pkg = {
    * @param config - Optional configuration overrides for the provider
    */ constructor(config = {}){
         super();
+        assertCCTPV2Config(config);
         this.config = config;
     }
     /**
+   * Resolves the effective polling configuration for an attestation request.
+   *
+   * Precedence (lowest to highest): provider `config.attestation`, then the
+   * per-call `config`. Headers merge independently across
+   * `config.attestation.headers`, the provider-level `config.headers`, and any
+   * per-call `config.headers`, so a more specific header augments rather than
+   * replaces the broader ones. The `headers` key is omitted entirely when no
+   * headers are configured, leaving the attestation fetchers' defaults intact.
+   *
+   * @param config - Optional per-call polling configuration overrides
+   * @returns The merged polling configuration passed to the attestation fetchers
+   */ resolveAttestationConfig(config) {
+        const headers = {
+            ...this.config?.attestation?.headers,
+            ...this.config?.headers,
+            ...config?.headers
+        };
+        // Polling fields follow normal precedence; headers are merged separately
+        // below so narrower config layers augment rather than replace broader ones.
+        return {
+            ...this.config?.attestation,
+            ...config,
+            ...Object.keys(headers).length > 0 ? {
+                headers
+            } : {}
+        };
+    }
+    /**
    * Execute a cross-chain USDC bridge operation using the CCTP v2 protocol.
    *
    * This method orchestrates the complete CCTP v2 bridge flow including validation,
@@ -13565,7 +14081,7 @@ var pkg = {
             throw new Error(`Failed to resolve operation context: ${error instanceof Error ? error.message : String(error)}`);
         }
         // Resolve spender address with proper error handling
-        const spenderAddress = resolveCCTPV2ContractAddress(chain);
+        const spenderAddress = resolveCCTPV2ContractAddress(chain, 'tokenMessenger');
         // Prepare action parameters
         const actionParams = {
             amount: BigInt(amount),
@@ -13674,11 +14190,7 @@ var pkg = {
    */ async fetchAttestation(source, transactionHash, config) {
         assertCCTPv2WalletContext(source);
         try {
-            // Merge configs: defaults <- global config <- per-call config
-            const effectiveConfig = {
-                ...this.config?.attestation,
-                ...config
-            };
+            const effectiveConfig = this.resolveAttestationConfig(config);
             const response = await fetchAttestation(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
             const message = response.messages[0];
             if (!message) {
@@ -13695,6 +14207,49 @@ var pkg = {
         }
     }
     /**
+   * Polls attestation data until Circle's relayer mint transaction is confirmed.
+   *
+   * This method is used by forwarded transfers. It polls the same Iris
+   * attestation endpoint as {@link CCTPV2BridgingProvider.fetchAttestation},
+   * but waits for a completed relayer forward state and returns the attestation
+   * message containing `forwardTxHash`.
+   *
+   * @typeParam TFromAdapterCapabilities - The type representing the capabilities of the source adapter
+   * @param source - The source wallet context containing the chain definition and wallet address
+   * @param transactionHash - The transaction hash of the burn operation
+   * @param config - Optional polling configuration overrides for timeout, retries, delay, and headers
+   * @returns A promise that resolves to the attestation message with `forwardTxHash`
+   * @throws KitError If the relayer forward fails, the response is invalid, or polling times out
+   *
+   * @example
+   * ```typescript
+   * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+   * import { Chains } from '@core/chains'
+   *
+   * const provider = new CCTPV2BridgingProvider({
+   *   headers: { 'X-Partner-UUID': '00000000-0000-0000-0000-000000000000' },
+   * })
+   *
+   * const attestation = await provider.fetchRelayerMint(
+   *   {
+   *     adapter,
+   *     chain: Chains.EthereumSepolia,
+   *     address: '0x1234...',
+   *   },
+   *   '0xabc123...',
+   * )
+   *
+   * console.log('Relayer mint tx:', attestation.forwardTxHash)
+   * ```
+   */ async fetchRelayerMint(source, transactionHash, config) {
+        assertCCTPv2WalletContext(source);
+        if (typeof transactionHash !== 'string' || transactionHash.trim() === '') {
+            throw createValidationFailedError('transactionHash', transactionHash, 'transactionHash must be a non-empty string');
+        }
+        const effectiveConfig = this.resolveAttestationConfig(config);
+        return await fetchRelayerMint(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
+    }
+    /**
    * Requests a fresh attestation for an expired attestation.
    *
    * This method is used when the original attestation has expired before the mint
@@ -13748,11 +14303,7 @@ var pkg = {
             throw new Error('Failed to re-attest: Invalid transaction hash');
         }
         try {
-            // Merge configs: defaults <- global config <- per-call config
-            const effectiveConfig = {
-                ...this.config?.attestation,
-                ...config
-            };
+            const effectiveConfig = this.resolveAttestationConfig(config);
             // Step 1: Get existing attestation data to extract nonce
             const existingAttestation = await fetchAttestationWithoutStatusCheck(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
             const nonce = existingAttestation.messages[0]?.eventNonce;
@@ -14010,6 +14561,106 @@ var pkg = {
         return await source.adapter.prepareAction('cctp.v2.depositForBurn', actionParams, resolvedContext);
     }
     /**
+   * Prepare a prepaid-FORWARD burn through the `TokenMessengerWithFees` wrapper.
+   *
+   * Builds the source-chain `depositForBurnWithHookAndFees` call for the
+   * GenericExecutor FORWARD path: fees are collected up front on the source chain
+   * against a signed quote, `mintRecipient` and `destinationCaller` are both set to
+   * the GenericExecutor, and the GE `hookData` is passed through unchanged.
+   *
+   * This is the low-level on-chain primitive behind the UBK `fastCrossChainDeposit`
+   * and Bridge Kit `bridge({ deposit })` flows. The `hookData` and signed-quote
+   * `claim` are produced elsewhere and passed in here:
+   * - `hookData`: `buildForwardingHookDataWithPayload(version,
+   *   buildDepositForGenericExecutorPayload(...).hookData)` from `@core/utils`.
+   * - `claim.signedQuote` / `feeToken` / `feeTotalAmount`: from `fetchFeeQuote`
+   *   (`@circle-fin/provider-fee-v1`), whose FORWARD item must be bound to the
+   *   SAME `hookData` and executor `destinationCaller` used here.
+   *
+   * The returned approvals and burn are NOT executed — the caller executes the
+   * approvals first (in order) and then the burn. The fee payment channel matches
+   * the quote's `feeToken`:
+   * - Native fee: exactly `feeTotalAmount` is attached as the burn's `msg.value`;
+   *   only the burn amount is approved.
+   * - USDC fee (same token as the burn): a single combined `amount + feeTotalAmount`
+   *   approval covers both; the redundant second approval is skipped.
+   *
+   * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
+   * @param params - The burn amount, executor, hookData, signed-quote claim, and fee.
+   * @returns The prepared approvals, the prepared burn, and the resolved fee plan.
+   * @throws {KitError} If the wallet context is invalid, `destinationChain` does not
+   *   support CCTP v2, the executor is missing, `amount` or `feeTotalAmount` is not
+   *   a bigint or a numeric string coercible to bigint, the hookData lacks a
+   *   `cctp-forward` frame (guaranteed `ForwardFeeWithoutHook`), or the operation
+   *   context cannot be resolved.
+   *
+   * @example
+   * ```typescript
+   * const { approvals, burn } = await provider.burnWithFees({
+   *   source,
+   *   destinationChain: Arc,
+   *   amount: 1_000_000n,
+   *   executor: genericExecutorAddress,
+   *   hookData: geForwardHookData,
+   *   claim: { signedQuote: '0x01...', refundAddress: userAddress },
+   *   feeToken: '0x0000000000000000000000000000000000000000', // native
+   *   feeTotalAmount: 3_500_000n,
+   * })
+   * for (const approval of approvals) await approval.execute()
+   * const txHash = await burn.execute()
+   * ```
+   */ async burnWithFees(params) {
+        assertBurnWithFeesParams(params);
+        const { source, destinationChain, executor, hookData, claim, feeToken } = params;
+        const amount = BigInt(params.amount);
+        const feeTotalAmount = BigInt(params.feeTotalAmount);
+        // Coupling guard: the prepaid FORWARD path always requests a FORWARD fee item,
+        // so the hookData must carry a cctp-forward frame; otherwise the wrapper
+        // reverts ForwardFeeWithoutHook. Surface it as a typed input error up front.
+        assertForwardHookData(hookData);
+        const burnToken = source.chain.usdcAddress;
+        const feePayment = resolveFeePayment({
+            feeToken,
+            burnToken,
+            amount,
+            feeTotalAmount
+        });
+        // Resolve operation context from the source wallet context.
+        const operationContext = this.extractOperationContext(source);
+        let resolvedContext;
+        try {
+            resolvedContext = await resolveOperationContext(source.adapter, operationContext);
+        } catch (error) {
+            throw createValidationFailedError('source.adapter', undefined, `Failed to resolve operation context: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const context = resolvedContext;
+        const wrapperAddress = resolveCCTPV2ContractAddress(source.chain, 'tokenMessengerWithFees');
+        // Build the ERC-20 approvals to the wrapper (burn token, plus a distinct fee
+        // token only when the fee is not paid in the burn token).
+        const approvals = await Promise.all(feePayment.approvals.map(async (approval)=>source.adapter.prepareAction('token.approve', {
+                tokenAddress: approval.token,
+                delegate: wrapperAddress,
+                amount: approval.amount
+            }, context)));
+        // Build the burn: mintRecipient AND destinationCaller are both the executor.
+        const burn = await source.adapter.prepareAction('cctp.v2.depositForBurnWithFees', {
+            fromChain: source.chain,
+            toChain: destinationChain,
+            amount,
+            mintRecipient: executor,
+            destinationCaller: executor,
+            hookData,
+            claim,
+            feeToken,
+            feeTotalAmount
+        }, context);
+        return {
+            approvals,
+            burn,
+            feePayment
+        };
+    }
+    /**
    * Waits for a transaction to be mined and confirmed on the blockchain.
    *
    * This method should block until the transaction is confirmed on the blockchain.
@@ -14035,9 +14686,14 @@ var pkg = {
 }
 
 exports.CCTPV2BridgingProvider = CCTPV2BridgingProvider;
+exports.PREPAID_FORWARD_REVERT_NAMES = PREPAID_FORWARD_REVERT_NAMES;
+exports.assertForwardHookData = assertForwardHookData;
 exports.getBlocksUntilExpiry = getBlocksUntilExpiry;
 exports.getMintRecipientAccount = getMintRecipientAccount;
+exports.hasForwardHook = hasForwardHook;
 exports.isAttestationExpired = isAttestationExpired;
 exports.isMintFailureRelatedToAttestation = isMintFailureRelatedToAttestation;
+exports.mapPrepaidForwardError = mapPrepaidForwardError;
+exports.resolveFeePayment = resolveFeePayment;
 exports.validateAndConvertFee = validateAndConvertFee;
 //# sourceMappingURL=index.cjs.map