@circle-fin/app-kit 1.11.0 → 1.12.1

package/estimateBridge.mjs

@@ -38,6 +38,7 @@ import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
 import '@coral-xyz/anchor';
 import '@noble/curves/ed25519';
+import 'viem';
 import { keccak256 } from '@ethersproject/keccak256';
 
 // Import global type declarations
@@ -2555,6 +2556,8 @@ class KitError extends Error {
     Blockchain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     Blockchain["XDC"] = "XDC";
     Blockchain["XDC_Apothem"] = "XDC_Apothem";
+    Blockchain["X_Layer"] = "X_Layer";
+    Blockchain["X_Layer_Testnet"] = "X_Layer_Testnet";
     Blockchain["ZKSync_Era"] = "ZKSync_Era";
     Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
 })(Blockchain || (Blockchain = {}));
@@ -2608,6 +2611,7 @@ var BridgeChain;
     BridgeChain["Unichain"] = "Unichain";
     BridgeChain["World_Chain"] = "World_Chain";
     BridgeChain["XDC"] = "XDC";
+    BridgeChain["X_Layer"] = "X_Layer";
     // Testnet chains with CCTPv2 support
     BridgeChain["Arc_Testnet"] = "Arc_Testnet";
     BridgeChain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
@@ -2633,6 +2637,7 @@ var BridgeChain;
     BridgeChain["Unichain_Sepolia"] = "Unichain_Sepolia";
     BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     BridgeChain["XDC_Apothem"] = "XDC_Apothem";
+    BridgeChain["X_Layer_Testnet"] = "X_Layer_Testnet";
 })(BridgeChain || (BridgeChain = {}));
 var UnifiedBalanceChain;
 (function(UnifiedBalanceChain) {
@@ -5170,7 +5175,8 @@ var EarnChain;
     isTestnet: true,
     explorerUrl: 'https://amoy.polygonscan.com/tx/{hash}',
     rpcEndpoints: [
-        'https://rpc-amoy.polygon.technology'
+        'https://polygon-amoy-bor-rpc.publicnode.com',
+        'https://polygon-amoy.drpc.org'
     ],
     eurcAddress: null,
     usdcAddress: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
@@ -6035,6 +6041,104 @@ var EarnChain;
     }
 });
 
+/**
+ * X Layer Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the X Layer blockchain.
+ * X Layer is an EVM-compatible OP Stack Layer-2 blockchain built by OKX,
+ * using OKB as its native gas token. (Migrated from Polygon zkEVM/CDK to the
+ * OP Stack on 2025-10-27; older docs describing it as zkEVM are obsolete.)
+ */ const XLayer = defineChain({
+    type: 'evm',
+    chain: Blockchain.X_Layer,
+    name: 'X Layer',
+    title: 'X Layer Mainnet',
+    nativeCurrency: {
+        name: 'OKB',
+        symbol: 'OKB',
+        decimals: 18
+    },
+    chainId: 196,
+    isTestnet: false,
+    explorerUrl: 'https://www.oklink.com/xlayer/tx/{hash}',
+    rpcEndpoints: [
+        'https://xlayerrpc.okx.com'
+    ],
+    eurcAddress: null,
+    usdcAddress: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
+    usdtAddress: null,
+    cctp: {
+        domain: 37,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+    }
+});
+
+/**
+ * X Layer Testnet chain definition
+ * @remarks
+ * This represents the official test network for the X Layer blockchain.
+ * X Layer is an EVM-compatible OP Stack Layer-2 blockchain built by OKX,
+ * using OKB as its native gas token. (Migrated from Polygon zkEVM/CDK to the
+ * OP Stack on 2025-10-27; older docs describing it as zkEVM are obsolete.)
+ */ const XLayerTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.X_Layer_Testnet,
+    name: 'X Layer Testnet',
+    title: 'X Layer Testnet',
+    nativeCurrency: {
+        name: 'OKB',
+        symbol: 'OKB',
+        decimals: 18
+    },
+    chainId: 1952,
+    isTestnet: true,
+    // Deliberately not oklink.com (used for mainnet): viem's bundled OKLink
+    // testnet URL targets the deprecated pre-rebrand chain ID 195, not this
+    // chain's ID (1952). Verified against the internal chain-expansion-scripts
+    // config (`v2config.sandbox.yml`) — do not "normalize" this to match mainnet.
+    explorerUrl: 'https://web3.okx.com/explorer/x-layer-testnet/tx/{hash}',
+    rpcEndpoints: [
+        'https://testrpc.xlayer.tech'
+    ],
+    eurcAddress: null,
+    usdcAddress: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
+    usdtAddress: null,
+    cctp: {
+        domain: 37,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 65,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET
+    }
+});
+
 /**
  * ZKSync Era Mainnet chain definition
  * @remarks
@@ -6154,6 +6258,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   WorldChainSepolia: WorldChainSepolia,
   XDC: XDC,
   XDCApothem: XDCApothem,
+  XLayer: XLayer,
+  XLayerTestnet: XLayerTestnet,
   ZKSyncEra: ZKSyncEra,
   ZKSyncEraSepolia: ZKSyncEraSepolia
 });
@@ -8208,6 +8314,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
         [Blockchain.World_Chain]: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
         [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [Blockchain.X_Layer]: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
         [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
         // =========================================================================
         // Testnets (alphabetically sorted)
@@ -8216,6 +8323,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Arbitrum_Sepolia]: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
         [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
         [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+        [Blockchain.Celo_Alfajores_Testnet]: '0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B',
         [Blockchain.Codex_Testnet]: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
         [Blockchain.Cronos_Testnet]: '0xEb33dc5fac03833e132593659e1dE7256aB59794',
         [Blockchain.Edge_Testnet]: '0x2d9F7CAD728051AA35Ecdc472a14cf8cDF5CFD6B',
@@ -8242,6 +8350,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
         [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
         [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [Blockchain.X_Layer_Testnet]: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
         [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853'
     }
 };
@@ -9653,7 +9762,7 @@ function resolveOptions(options) {
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$3 = "1.12.2";
+var version$3 = "1.13.0";
 var pkg$3 = {
 	name: name$2,
 	version: version$3};
@@ -9690,13 +9799,21 @@ const assertCustomFeePolicySymbol = Symbol('assertCustomFeePolicy');
     computeFee: z.function().returns(z.string().or(z.promise(z.string()))).optional(),
     calculateFee: z.function().returns(z.string().or(z.promise(z.string()))).optional(),
     resolveFeeRecipientAddress: z.function().returns(z.string().or(z.promise(z.string())))
-}).strict().refine((data)=>{
+}).strict().superRefine((data, ctx)=>{
     const hasComputeFee = data.computeFee !== undefined;
     const hasCalculateFee = data.calculateFee !== undefined;
-    // XOR: exactly one must be provided
-    return hasComputeFee !== hasCalculateFee;
-}, {
-    message: 'Provide either computeFee or calculateFee, not both. Use computeFee (recommended) for human-readable amounts.'
+    if (hasComputeFee && hasCalculateFee) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide either computeFee or calculateFee, not both. Use computeFee (recommended) for human-readable amounts.'
+        });
+    }
+    if (!hasComputeFee && !hasCalculateFee) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide either computeFee or calculateFee. Use computeFee (recommended) for human-readable amounts.'
+        });
+    }
 });
 /**
  * Assert that the provided value conforms to {@link CustomFeePolicy}.
@@ -9794,6 +9911,44 @@ function assertBridgeParams(params, schema) {
     }
 }
 
+/**
+ * Canonical list of actions that do not prepare or submit transactions.
+ *
+ * @internal
+ */ const READ_ACTION_KEYS = [
+    'token.allowance',
+    'token.balanceOf',
+    'token.name',
+    'native.balanceOf',
+    'usdc.allowance',
+    'usdc.balanceOf',
+    'usdc.name',
+    'gateway.v1.isDelegate',
+    'gateway.v1.withdrawingBalance',
+    'gateway.v1.withdrawalBlock',
+    'gateway.v1.signBurnIntents'
+];
+const READ_ACTION_KEY_SET = new Set(READ_ACTION_KEYS);
+/**
+ * Check whether a runtime value identifies a read action.
+ *
+ * @param action - The value to classify.
+ * @returns Whether the value is a registered read-action key.
+ *
+ * @example
+ * ```typescript
+ * import { isReadActionKey } from '@core/adapter'
+ *
+ * if (isReadActionKey(value)) {
+ *   await adapter.readAction(value, params, context)
+ * }
+ * ```
+ *
+ * @internal
+ */ function isReadActionKey(action) {
+    return READ_ACTION_KEY_SET.has(action);
+}
+
 /**
  * Resolves an operation context into concrete chain and address values.
  *
@@ -9873,6 +10028,72 @@ function assertBridgeParams(params, schema) {
     };
 }
 
+/**
+ * Create the standard error for a missing or non-read action.
+ *
+ * @param action - The unsupported action value.
+ * @returns A fatal unsupported-action error.
+ *
+ * @internal
+ */ function createUnsupportedReadActionError(action) {
+    return new KitError({
+        ...InputError.UNSUPPORTED_ACTION,
+        recoverability: 'FATAL',
+        message: `Read action "${String(action)}" is not registered in this adapter.`
+    });
+}
+/**
+ * Execute a read through the adapter's dedicated read seam when available.
+ *
+ * @remarks
+ * Fall back to the legacy `prepareAction().execute()` contract so providers
+ * remain runtime-compatible with adapter versions released before `readAction`.
+ * Consumers must upgrade their adapter package for reads to bypass custom
+ * `prepareAction` wrappers.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type.
+ * @typeParam TActionKey - The read action key.
+ * @param adapter - The adapter that owns the read action.
+ * @param action - The read action to execute.
+ * @param params - The parameters for the read action.
+ * @param ctx - The operation context.
+ * @returns The raw read-action result.
+ * @throws {KitError} When `action` is not a supported read-action key.
+ *
+ * @example
+ * ```typescript
+ * import { executeAdapterReadAction } from '@core/adapter'
+ * import { Ethereum } from '@core/chains'
+ *
+ * const allowance = await executeAdapterReadAction(
+ *   adapter,
+ *   'token.allowance',
+ *   { tokenAddress, delegate },
+ *   { chain: Ethereum },
+ * )
+ * ```
+ *
+ * @internal
+ */ async function executeAdapterReadAction(adapter, action, params, ctx) {
+    if (!isReadActionKey(action)) {
+        throw createUnsupportedReadActionError(action);
+    }
+    const runtimeAdapter = adapter;
+    if (typeof runtimeAdapter.readAction === 'function') {
+        return runtimeAdapter.readAction(action, params, ctx);
+    }
+    let request;
+    try {
+        request = await adapter.prepareAction(action, params, ctx);
+    } catch (error) {
+        if (error instanceof Error && error.message === `Action ${action} is not supported`) {
+            throw createUnsupportedReadActionError(action);
+        }
+        throw error;
+    }
+    return request.execute();
+}
+
 /**
  * Schema for validating hexadecimal strings with '0x' prefix.
  *
@@ -10082,16 +10303,15 @@ function assertBridgeParams(params, schema) {
  * ```
  */ const validateBalanceForTransaction = async (params)=>{
     const { amount, adapter, token, tokenAddress, operationContext } = params;
-    const balancePrepared = await adapter.prepareAction('usdc.balanceOf', {
+    const balance = await executeAdapterReadAction(adapter, 'usdc.balanceOf', {
         walletAddress: operationContext.address
     }, operationContext);
-    const balance = await balancePrepared.execute();
-    if (BigInt(balance) < BigInt(amount)) {
+    if (BigInt(String(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(),
+            balance: String(balance),
             amount,
             tokenAddress,
             walletAddress: operationContext.address
@@ -12457,15 +12677,52 @@ 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
+// Gas FLOORS, not ceilings — kept separate from the fee-estimate averages
+// above. `executePreparedChainRequest` submits
+// max(estimate * buffer, floor), so a chain whose real cost exceeds the floor
+// is covered by its own estimate, and a chain whose estimator under-reports
+// (Cronos: returns 30_600 where the EIP-7623 calldata floor is 45_000) is
+// covered by the floor.
+//
+// Two distinct chain surcharges drive these numbers, both measured live:
+//   Sei  — ~+51_500 per NEWLY CREATED storage slot (73_595 vs vanilla 22_100);
+//          no flat per-tx surcharge (31_535, identical to Base).
+//   Edge — ~+53_200 flat on EVERY tx (84_751 vs Base 31_535); storage priced
+//          normally. Edge therefore fails warm as well as cold.
+// A floor must clear the worst COLD cost, since a slot that exists at estimate
+// time can be consumed before inclusion and cost a full step more on execution.
+// Each floor is therefore derived from the worst observed estimate *after* the
+// 1.25x buffer, plus headroom — sizing it below the buffered value would leave
+// the estimate governing and defeat the point of the floor.
+//
+// The `*_GAS_LIMIT_EVM` names are kept despite these being floors: they are
+// exported, so renaming to `*_GAS_FLOOR_EVM` would be a breaking change for
+// consumers. Read "LIMIT" here as "the limit we submit", never as a ceiling.
+const APPROVE_GAS_LIMIT_EVM = 150_000n // buffered worst cold 149_355 (Edge Testnet 119_484 x 1.25) + drift headroom
 ;
-const DEPOSIT_FOR_BURN_GAS_LIMIT_EVM = 300_000n // observed max 226_506 + ~30%
+const DEPOSIT_FOR_BURN_GAS_LIMIT_EVM = 500_000n // buffered worst 474_078 (Sei 379_263 x 1.25) + ~26k headroom
 ;
-const RECEIVE_MESSAGE_GAS_LIMIT_EVM = 400_000n // observed max 310_839 + ~30%
+const RECEIVE_MESSAGE_GAS_LIMIT_EVM = 400_000n // observed max 310_839; clears Cronos' calldata floor ~10x
 ;
+/**
+ * The gas floor for each bridge step, keyed by step name.
+ *
+ * Two places need these and they must agree: each step module passes its floor
+ * to `executePreparedChainRequest` for submission, and
+ * `CCTPV2BridgingProvider.estimate()` quotes the resulting limit so a caller
+ * can fund a wallet. A transaction is only admitted when the sender holds
+ * `gasLimit * maxFeePerGas`, so a quote taken from anything other than the
+ * submitted limit under-reports what the wallet actually needs — historically
+ * the quote sat ~2.5x below the reserved limit.
+ *
+ * Both sides read this map so the two cannot drift apart. Change a floor here
+ * and the quote moves with it; point one side at a different value and the
+ * divergence is visible in review rather than silent at runtime.
+ */ const BRIDGE_STEP_GAS_FLOORS_EVM = {
+    approve: APPROVE_GAS_LIMIT_EVM,
+    burn: DEPOSIT_FOR_BURN_GAS_LIMIT_EVM,
+    mint: RECEIVE_MESSAGE_GAS_LIMIT_EVM
+};
 /**
  * The minimum finality threshold for CCTPv2 transfers.
  *
@@ -12484,1538 +12741,1595 @@ const RECEIVE_MESSAGE_GAS_LIMIT_EVM = 400_000n // observed max 310_839 + ~30%
 };
 
 /**
- * Default configuration values for the attestation fetcher.
- * @internal
- */ const DEFAULT_CONFIG = {
-    timeout: 2_000,
-    maxRetries: 30 * 20,
-    retryDelay: 2_000,
-    headers: {
-        '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.
- *
- * @param obj - The value to check, typically an element from the messages array
- * @returns True if the object matches the AttestationMessage shape, false otherwise
- * @internal
- */ const isValidAttestationMessage = (obj)=>{
-    return typeof obj === 'object' && obj !== null && 'message' in obj && 'eventNonce' in obj && 'attestation' in obj && 'decodedMessage' in obj && 'cctpVersion' in obj && 'status' in obj && typeof obj.status === 'string';
-};
-/**
- * Type guard that verifies if an attestation message is complete.
- *
- * @param message - The attestation message to check
- * @returns True if the message status is 'complete', false otherwise
- * @internal
- */ const isCompleteAttestation = (message)=>{
-    return message.status === 'complete';
-};
-/**
- * Type guard that verifies if an unknown value has the correct structure
- * for an AttestationResponse, regardless of attestation completion status.
- *
- * @param obj - The value to check, typically a parsed JSON response
- * @returns True if the object matches the AttestationResponse shape
- * @internal
- */ const hasValidAttestationStructure = (obj)=>{
-    if (typeof obj !== 'object' || obj === null || !('messages' in obj) || !Array.isArray(obj.messages)) {
-        return false;
-    }
-    const messages = obj.messages;
-    // Validate all messages have the correct shape
-    return messages.every(isValidAttestationMessage);
-};
-/**
- * Type guard that verifies if an unknown value matches the AttestationResponse shape
- * and contains a complete attestation.
- *
- * This function performs runtime validation to ensure that the provided value
- * conforms to the expected structure of an AttestationResponse and has at least
- * one complete attestation. It checks that:
- * 1. The value has valid AttestationResponse structure
- * 2. At least one message has status 'complete'
- *
- * @remarks
- * This type guard is used internally by the attestation fetcher to validate
- * responses from the IRIS API before processing them. It provides runtime
- * type safety for data coming from the network and ensures we have a complete
- * attestation before proceeding.
- *
- * If the response has valid structure but no complete attestation yet,
- * it throws a retryable error. If the response structure is invalid,
- * it throws a non-retryable validation error.
- *
- * @param obj - The value to check, typically a parsed JSON response
- * @returns True if the object matches the AttestationResponse shape and has a complete attestation
- * @throws {Error} With "Invalid attestation response structure" if structure is invalid (non-retryable)
- * @throws {Error} With "Attestation not ready" if no complete attestation yet (retryable)
- *
- * @example
- * ```typescript
- * const response = await fetch('https://iris-api.circle.com/...')
- * const data = await response.json()
+ * CCTP bridge step names that can occur in the bridging flow.
  *
- * if (isAttestationResponse(data)) {
- *   // TypeScript now knows data is AttestationResponse with at least one complete attestation
- *   const completeMessage = data.messages.find(msg => msg.status === 'complete')
- *   console.log('Found complete attestation:', completeMessage.attestation)
- * }
- * ```
- */ const isAttestationResponse = (obj)=>{
-    // First check if the structure is valid
-    if (!hasValidAttestationStructure(obj)) {
-        // If structure is invalid, this is a permanent failure - don't retry
-        throw new Error('Invalid attestation response structure');
-    }
-    // Then check if at least one message is complete
-    if (!obj.messages.some(isCompleteAttestation)) {
-        // If no complete message, this is a temporary state - allow retry
-        throw new Error('Attestation not ready');
-    }
-    return true;
+ * 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'
 };
 /**
- * Builds the IRIS API URL for fetching attestation data from Circle's CCTP service.
- *
- * Constructs a properly formatted URL for the IRIS API v2 endpoint that provides
- * attestation messages for cross-chain transfers. The URL includes both the source
- * domain identifier and the transaction hash as query parameters. The base URL
- * is selected based on whether the operation is for testnet or mainnet.
- *
- * @param sourceDomainId - The CCTP domain ID of the source chain (numeric or string)
- * @param transactionHash - The transaction hash of the burn operation to fetch attestation for
- * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
- * @returns A fully qualified URL string for the IRIS API endpoint
+ * Conditional step transition rules for CCTP bridge flow.
  *
- * @example
- * ```typescript
- * // Mainnet URL
- * const mainnetUrl = buildIrisUrl(1, '0xabc...', false)
- * // => 'https://iris-api.circle.com/v2/messages/1?transactionHash=0xabc...'
- *
- * // Testnet URL
- * const testnetUrl = buildIrisUrl(1, '0xdef...', true)
- * // => 'https://iris-api-sandbox.circle.com/v2/messages/1?transactionHash=0xdef...'
- * ```
- */ const buildIrisUrl = (sourceDomainId, transactionHash, isTestnet)=>{
-    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
-    const url = new URL(`${baseUrl}/v2/messages/${String(sourceDomainId)}`);
-    url.searchParams.set('transactionHash', transactionHash);
-    return url.toString();
+ * 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
+        }
+    ]
 };
 /**
- * Fetches attestation data from the IRIS API with retry and timeout handling.
+ * Analyze bridge steps to determine retry feasibility and continuation point.
  *
- * Polls the IRIS API until a complete attestation is available. The default
- * window is sized for slow source chains where finality may take many
- * confirmations.
+ * 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.
  *
- * Defaults (see `DEFAULT_CONFIG`):
- * - Per-attempt timeout: 2 000 ms (each HTTP request aborts after 2 s)
- * - Retry delay: 2 000 ms between attempts
- * - Max retries: 600 (30 × 20)
- * - Total worst-case polling window: 600 × (2 000 ms + 2 000 ms) ≈ 40 minutes
+ * The current analysis supports the standard CCTP flow:
+ * **Traditional flow**: Approve → Burn → FetchAttestation → Mint
  *
- * @param sourceDomainId - The CCTP domain ID.
- * @param transactionHash - The transaction hash to fetch attestation for.
- * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
- * @param config - Optional configuration overrides for the attestation fetcher
- * @returns The attestation response data.
- * @throws If the request fails, times out, or returns invalid 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
+ *
+ * @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
- * // Fetch attestation for mainnet transaction
- * const response = await fetchAttestation(1, '0xabc...', false)
- * console.log(`Found ${response.messages.length} attestation messages`)
- *
- * // Fetch with custom timeout
- * const response2 = await fetchAttestation(1, '0xdef...', true, {
- *   timeout: 5000,
- *   maxRetries: 5
- * })
- * ```
- */ const fetchAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
-    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = mergeAttestationConfig(config);
-    return await pollApiGet(url, isAttestationResponse, effectiveConfig);
-};
-/**
- * Type guard that validates attestation response structure without requiring completion status.
- *
- * This is used by `fetchAttestationWithoutStatusCheck` to extract the nonce from an existing
- * attestation, even if the attestation is expired or pending. Unlike `isAttestationResponse`,
- * this function does not throw if no complete attestation is found.
- *
- * @param obj - The value to check, typically a parsed JSON response
- * @returns True if the object has valid attestation structure
- * @throws {Error} With "Invalid attestation response structure" if structure is invalid
- * @internal
- */ const isAttestationResponseWithoutStatusCheck = (obj)=>{
-    if (!hasValidAttestationStructure(obj)) {
-        throw new Error('Invalid attestation response structure');
-    }
-    return true;
-};
-/**
- * Fetches attestation data without requiring the attestation to be complete.
+ * import { analyzeSteps } from './analyzeSteps'
  *
- * This function is useful for retrieving attestation data (particularly the nonce)
- * from an existing transaction, even if the attestation has expired or is pending.
- * It uses minimal retries since we're fetching existing data, not waiting for completion.
+ * // Failed approval step (requires user action)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'error', errorMessage: 'User rejected' }
+ *   ]
+ * }
  *
- * @param sourceDomainId - The CCTP domain ID of the source chain
- * @param transactionHash - The transaction hash to fetch attestation for
- * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
- * @param config - Optional configuration overrides
- * @returns The attestation response data (may contain incomplete/expired attestations)
- * @throws If the request fails, times out, or returns invalid data
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: 'Approve', isRetryable: true,
+ * //          reason: 'Retry failed approval' }
+ * ```
  *
  * @example
  * ```typescript
- * // Fetch existing attestation to extract nonce for re-attestation
- * const response = await fetchAttestationWithoutStatusCheck(1, '0xabc...', true)
- * const nonce = response.messages[0]?.eventNonce
- * ```
- */ 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 = mergeAttestationConfig(config, {
-        maxRetries: 3
-    });
-    return await pollApiGet(url, isAttestationResponseWithoutStatusCheck, effectiveConfig);
-};
-/**
- * Type guard that validates attestation response has expirationBlock === '0'.
- *
- * This is used after requestReAttestation() to poll until the attestation
- * is fully re-processed and has a zero expiration block (never expires).
- * The expiration block transitions from non-zero to zero when Circle
- * completes processing the re-attestation request.
+ * // Pending transaction (requires waiting, not actionable)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'pending' }
+ *   ]
+ * }
  *
- * @param obj - The value to check, typically a parsed JSON response
- * @returns True if the attestation has expirationBlock === '0'
- * @throws {Error} With "Re-attestation not yet complete" if expirationBlock is not '0'
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: 'Approve', isRetryable: false,
+ * //          reason: 'Continue pending approval' }
+ * ```
  *
  * @example
  * ```typescript
- * // After requesting re-attestation, use this to validate the response
- * const response = await pollApiGet(url, isReAttestedAttestationResponse, config)
- * // response.messages[0].decodedMessage.decodedMessageBody.expirationBlock === '0'
- * ```
+ * // Completed bridge (nothing to do)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'success' },
+ *     { name: 'Burn', state: 'success' },
+ *     { name: 'FetchAttestation', state: 'success' },
+ *     { name: 'Mint', state: 'success' }
+ *   ]
+ * }
  *
- * @internal
- */ const isReAttestedAttestationResponse = (obj)=>{
-    // First validate the basic structure and completion status
-    // This will throw appropriate errors for invalid structure or incomplete attestation
-    if (!isAttestationResponse(obj)) ;
-    // Check if the first message has expirationBlock === '0'
-    const expirationBlock = obj.messages[0]?.decodedMessage?.decodedMessageBody?.expirationBlock;
-    if (expirationBlock !== '0') {
-        // Re-attestation not yet complete - allow retry via polling
-        throw new Error('Re-attestation not yet complete: waiting for expirationBlock to become 0');
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: null, isRetryable: false,
+ * //          reason: 'Bridge completed successfully' }
+ * ```
+ */ const analyzeSteps = (bridgeResult)=>{
+    // Input validation
+    if (!bridgeResult || !Array.isArray(bridgeResult.steps)) {
+        throw new Error('Invalid bridgeResult: must contain a steps array');
     }
-    return true;
+    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
+    };
 };
 /**
- * Fetches attestation data and polls until expirationBlock === '0'.
- *
- * This function is used after calling requestReAttestation() to wait until
- * the attestation is fully re-processed. The expirationBlock transitions
- * from non-zero to zero when Circle completes the re-attestation.
- *
- * @param sourceDomainId - The CCTP domain ID of the source chain
- * @param transactionHash - The transaction hash to fetch attestation for
- * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
- * @param config - Optional configuration overrides
- * @returns The re-attested attestation response with expirationBlock === '0'
- * @throws If the request fails, times out, or expirationBlock never becomes 0
- *
- * @example
- * ```typescript
- * // After requesting re-attestation
- * await requestReAttestation(nonce, isTestnet)
+ * Build flow context from the execution history.
  *
- * // Poll until expirationBlock becomes 0
- * const response = await fetchReAttestedAttestation(domainId, txHash, isTestnet)
- * // response.messages[0].decodedMessage.decodedMessageBody.expirationBlock === '0'
- * ```
- */ const fetchReAttestedAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
-    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = mergeAttestationConfig(config);
-    return await pollApiGet(url, isReAttestedAttestationResponse, effectiveConfig);
-};
+ * @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
+        }
+    };
+}
 /**
- * Builds the IRIS API URL for re-attestation requests.
+ * Determine continuation step using the rule engine.
  *
- * Constructs the URL for Circle's re-attestation endpoint that allows
- * requesting a fresh attestation for an expired nonce.
+ * @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.
  *
- * @param nonce - The nonce from the original attestation
- * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
- * @returns A fully qualified URL string for the re-attestation endpoint
+ * @param result - The bridge result to search.
+ * @param stepName - The name of the step to find.
+ * @returns The step if found, undefined otherwise.
  *
  * @example
  * ```typescript
- * // Mainnet URL
- * const mainnetUrl = buildReAttestUrl('0xabc', false)
- * // => 'https://iris-api.circle.com/v2/reattest/0xabc'
+ * import { findStepByName } from './findStep'
  *
- * // Testnet URL
- * const testnetUrl = buildReAttestUrl('0xabc', true)
- * // => 'https://iris-api-sandbox.circle.com/v2/reattest/0xabc'
+ * const burnStep = findStepByName(result, 'burn')
+ * if (burnStep) {
+ *   console.log('Burn tx:', burnStep.txHash)
+ * }
  * ```
- */ const buildReAttestUrl = (nonce, isTestnet)=>{
-    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
-    const url = new URL(`${baseUrl}/v2/reattest/${nonce}`);
-    return url.toString();
-};
-/**
- * Type guard that validates the re-attestation API response structure.
- *
- * @param obj - The value to check, typically a parsed JSON response
- * @returns True if the object matches the ReAttestationResponse shape
- * @throws {Error} With "Invalid re-attestation response structure" if structure is invalid
- * @internal
- */ const isReAttestationResponse = (obj)=>{
-    if (typeof obj !== 'object' || obj === null || !('message' in obj) || !('nonce' in obj) || typeof obj.message !== 'string' || typeof obj.nonce !== 'string') {
-        throw new Error('Invalid re-attestation response structure');
-    }
-    return true;
-};
+ */ function findStepByName(result, stepName) {
+    return result.steps.find((step)=>step.name === stepName);
+}
 /**
- * Requests re-attestation for an expired attestation nonce.
+ * Find a pending step by name and return it with its index.
  *
- * This function calls Circle's re-attestation API endpoint to request a fresh
- * attestation for a previously issued nonce. After calling this function,
- * you should poll `fetchAttestation` to retrieve the new attestation.
+ * Searches for a step that matches both the step name and has a pending state.
  *
- * @param nonce - The nonce from the original (expired) attestation
- * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
- * @param config - Optional configuration overrides for the request
- * @returns The re-attestation response confirming the request was accepted
- * @throws If the request fails, times out, or returns invalid data
+ * @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
- * // Request re-attestation for an expired nonce
- * const response = await requestReAttestation('0xabc', true)
- * console.log(response.message) // "Re-attestation successfully requested for nonce."
+ * import { findPendingStep } from './findStep'
  *
- * // After requesting re-attestation, poll for the new attestation
- * const attestation = await fetchAttestation(domainId, txHash, true)
+ * const { step, index } = findPendingStep(result, 'burn')
+ * console.log('Pending step:', step.name, 'at index:', index)
  * ```
- */ 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 = mergeAttestationConfig(config, {
-        maxRetries: 3
-    });
-    return await pollApiPost(url, {}, isReAttestationResponse, effectiveConfig);
-};
-
-/**
- * Type guard that checks if the relayer has confirmed the mint transaction.
- *
- * 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
- *
- * If forwardState is 'FAILED', throws a non-retryable KitError.
- * If forwardState is 'PENDING' or not present, throws a RETRYABLE KitError to continue polling.
- *
- * @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)) {
+ */ 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: 'Invalid attestation response structure from IRIS API.'
+            message: `Pending step "${stepName}" not found in result`
         });
     }
-    // Find the first message (typically there's only one)
-    const message = obj.messages[0];
-    if (!message) {
+    const step = result.steps[index];
+    if (!step) {
         throw new KitError({
             ...InputError.VALIDATION_FAILED,
             recoverability: 'FATAL',
-            message: 'No attestation messages found in IRIS API response.'
+            message: 'Pending step is undefined'
         });
     }
-    // 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.'
-    });
-};
+    return {
+        step,
+        index
+    };
+}
 /**
- * Polls the attestation API until the relayer's mint transaction is confirmed.
+ * Get the burn transaction hash from bridge result.
  *
- * 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.
+ * @param result - The bridge result.
+ * @returns The burn transaction hash, or undefined if not found.
  *
- * @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
+ * @example
+ * ```typescript
+ * import { getBurnTxHash } from './findStep'
  *
- * @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
+ * const burnTxHash = getBurnTxHash(result)
+ * if (burnTxHash) {
+ *   console.log('Burn tx hash:', burnTxHash)
+ * }
+ * ```
+ */ function getBurnTxHash(result) {
+    return findStepByName(result, CCTPv2StepName.burn)?.txHash;
+}
+/**
+ * Get the attestation data from bridge result.
+ *
+ * @param result - The bridge result.
+ * @returns The attestation data, or undefined if not found.
  *
  * @example
  * ```typescript
- * const attestation = await fetchRelayerMint(0, '0xabc...', false)
- * console.log('Relayer mint tx:', attestation.forwardTxHash)
+ * import { getAttestationData } from './findStep'
+ *
+ * const attestation = getAttestationData(result)
+ * if (attestation) {
+ *   console.log('Attestation:', attestation.message)
+ * }
  * ```
- */ 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.'
-        });
+ */ 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;
     }
-    return message;
-};
+    // Fall back to fetchAttestation step
+    const fetchStep = findStepByName(result, CCTPv2StepName.fetchAttestation);
+    return fetchStep?.data;
+}
 
-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)
+ * Check if the analysis indicates a non-actionable pending state.
  *
- * @param params - The parameters to validate
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ * 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 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
- * import { assertCCTPv2WalletContext } from '@circle-fin/provider-cctp-v2'
- * import { Ethereum } from '@core/chains'
+ * import { hasPendingState } from './stepUtils'
+ * import { analyzeSteps } from '../analyzeSteps'
  *
- * // 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'
- *         }
- *       }
- *     }
- *   }
+ * 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.
  *
- * // This will throw if validation fails
- * assertCCTPv2WalletContext(context)
+ * @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`.
  *
- * // If we get here, context is guaranteed to be valid
- * console.log('CCTPv2 wallet context is valid')
+ * @example
+ * ```typescript
+ * const outcome = evaluateTransactionOutcome(receipt, '0xabc...')
+ * step.state = outcome.state
+ * if (outcome.errorMessage) step.errorMessage = outcome.errorMessage
  * ```
- */ 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');
+ */ function evaluateTransactionOutcome(receipt, txHash) {
+    if (receipt.status === 'success' && receipt.blockNumber) {
+        return {
+            state: 'success'
+        };
     }
-    // Validate CCTPv2 support
-    if (!isCCTPV2Supported(context.chain)) {
-        throw createInvalidChainError(context.chain.name, 'Does not support CCTPv2');
+    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;
 }
-
-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 if the step is the last one in the execution flow.
  *
- * @param params - The parameters to validate
- * @throws {KitError} If validation fails, with details about which properties failed
+ * @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
- * import { assertCCTPv2BridgeParams } from '@circle-fin/provider-cctp-v2'
- * import { Ethereum, Base } from '@core/chains'
+ * import { isLastStep } from './stepUtils'
  *
- * // Prepare transfer parameters
- * const params = {
- *   amount: '100.50',
- *   source: {
- *     adapter: sourceAdapter,
- *     address: '0xSourceAddress',
- *     chain: {
- *       ...Ethereum,
- *       cctp: {
- *         domain: 1,
- *         contracts: {
- *           v2: {
- *             tokenMessenger: '0xTokenMessenger',
- *             messageTransmitter: '0xMessageTransmitter'
- *           }
- *         }
- *       }
- *     }
- *   },
- *   destination: {
- *     adapter: destAdapter,
- *     address: '0xDestAddress',
- *     chain: {
- *       ...Base,
- *       cctp: {
- *         domain: 2,
- *         contracts: {
- *           v2: {
- *             tokenMessenger: '0xTokenMessenger',
- *             messageTransmitter: '0xMessageTransmitter'
- *           }
- *         }
- *       }
- *     }
- *   },
- *   token: 'USDC',
- *   config: {
- *     transferSpeed: 'FAST',
- *     maxFee: '1000000'
- *   }
- * }
- *
- * // This will throw if validation fails
- * assertCCTPv2BridgeParams(params)
- *
- * // If we get here, params is guaranteed to be valid
- * console.log('CCTPv2 transfer parameters are valid')
+ * const stepNames = ['approve', 'burn', 'fetchAttestation', 'mint']
+ * isLastStep({ name: 'mint' }, stepNames) // true
+ * isLastStep({ name: 'burn' }, stepNames) // false
  * ```
- */ function assertCCTPv2BridgeParams(params) {
-    // First validate basic bridge params
-    validateWithStateTracking(params, bridgeParamsSchema, 'CCTPv2 bridge parameters', assertCCTPv2BridgeParamsSymbol);
-    // After validation, we know params is CCTPV2BridgeParams
-    const bridgeParams = params;
-    // Enforce that source and destination chains are either testnet or mainnet
-    if (bridgeParams.source.chain.isTestnet !== bridgeParams.destination.chain.isTestnet) {
-        throw createNetworkMismatchError(bridgeParams.source.chain, bridgeParams.destination.chain);
-    }
-    assertCCTPV2Support(bridgeParams.source.chain, bridgeParams.destination.chain);
-    // Validate that the destination chain supports forwarding when forwarder is enabled
-    assertForwarderRouteSupport(bridgeParams.source.chain, bridgeParams.destination.chain, bridgeParams.destination.useForwarder);
-    /**
-   * Enforce that if fee is defined then feeRecipient must be defined.
-   * We do not do this in the validation function itself because we want to allow
-   * optional properties when calling `provider.bridge()` due to the custom fee
-   * configuration being possible at the kit level as well.
-   */ if (bridgeParams.config?.customFee?.value !== undefined && bridgeParams.config?.customFee?.recipientAddress === undefined) {
-        throw createValidationFailedError$1('recipientAddress', bridgeParams.config.customFee.value, 'Custom fee is defined but fee recipient is not. Please provide a fee recipient.');
-    }
-    // Check if this is a forwarder-only destination (no adapter, requires useForwarder: true)
-    const isForwarderOnly = bridgeParams.destination.useForwarder === true && !('adapter' in bridgeParams.destination && bridgeParams.destination.adapter);
-    // Forwarder-only destinations require recipientAddress
-    if (isForwarderOnly) {
-        if (!bridgeParams.destination.recipientAddress?.trim()) {
-            throw createValidationFailedError$1('recipientAddress', bridgeParams.destination.recipientAddress, 'recipientAddress is required when using forwarder without a destination adapter.');
-        }
-    }
-    // Validate CCTP v2 specific requirements for source wallet
-    assertCCTPv2WalletContext(bridgeParams.source);
-    // Validate that source adapter supports the chain (defense-in-depth)
-    bridgeParams.source.adapter.validateChainSupport(bridgeParams.source.chain);
-    // Only validate destination wallet context and adapter if not forwarder-only
-    if (!isForwarderOnly) {
-        assertCCTPv2WalletContext(bridgeParams.destination);
-        // Validate that destination adapter supports the chain (defense-in-depth)
-        bridgeParams.destination.adapter.validateChainSupport(bridgeParams.destination.chain);
-    }
+ */ function isLastStep(step, stepNames) {
+    const stepIndex = stepNames.indexOf(step.name);
+    return stepIndex === -1 || stepIndex >= stepNames.length - 1;
 }
 /**
- * Validate CCTP v2 support on both chains
- */ /**
- * Throws a KitError if the given chain does not support CCTP v2.
+ * Wait for a pending transaction to complete.
  *
- * @param chain - The chain to check for CCTP v2 support
- * @param otherChain - The other chain in the route (for error context)
- * @param isSource - Whether this is the source chain (for error context)
- */ function assertCCTPV2Support(source, destination) {
-    if (!isCCTPV2Supported(source) || !isCCTPV2Supported(destination)) {
-        throw createUnsupportedRouteError(source.name, destination.name);
-    }
-}
-/**
- * Validates that the forwarder (relaying) feature is compatible with the route.
+ * Poll the adapter until the transaction is confirmed on-chain and return
+ * the updated step with success or error state based on the receipt.
  *
- * Checks the destination chain's `cctp.forwarderSupported.destination` property
- * to determine whether the chain supports receiving forwarded transfers.
+ * @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 source - The source chain definition
- * @param destination - The destination chain definition
- * @param useForwarder - Whether the forwarder is enabled on the destination
- * @throws {KitError} If the forwarder is enabled and the destination chain does not support forwarding
- */ function assertForwarderRouteSupport(source, destination, useForwarder) {
-    if (useForwarder === true && !destination.cctp?.forwarderSupported.destination) {
-        throw new KitError({
-            ...InputError.UNSUPPORTED_ROUTE,
-            recoverability: 'FATAL',
-            message: `Route from ${source.name} to ${destination.name} with forwarder is not supported (destination chain does not support forwarding).`,
-            cause: {
-                trace: {
-                    source: source.name,
-                    destination: destination.name
-                }
-            }
-        });
-    }
-}
-
-/**
- * Checks if a decoded attestation field matches the corresponding transfer parameter.
- * If the values do not match, appends a descriptive error message to the errors array.
+ * @throws KitError when the pending step has no transaction hash.
  *
- * @param field - The name of the field being compared (for error reporting)
- * @param decoded - The value decoded from the attestation message
- * @param param - The expected value from the transfer parameters
- * @param errors - The array to which error messages will be appended if a mismatch is found
- */ function checkFieldMismatch(field, decoded, param, errors) {
-    if (decoded !== param) {
-        errors.push(`${field} mismatch: decoded=${String(decoded)}, params=${String(param)}`);
-    }
-}
-/**
- * Asserts that the decoded message from attestation matches the provided transfer params.
- * Throws KitError if any field mismatches, with clear error messages.
+ * @example
+ * ```typescript
+ * import { waitForPendingTransaction } from './bridgeStepUtils'
  *
- * @param attestation - The attestation message containing the decoded message
- * @param params - The transfer parameters to validate against
- * @throws {@link KitError} If any field mismatches
- */ async function assertCCTPv2AttestationParams(attestation, params) {
-    const errors = [];
-    const message = attestation.decodedMessage;
-    const messageBody = message.decodedMessageBody;
-    // Use recipientAddress if provided, otherwise use destination.address
-    const destinationAddressForMint = params.destination.recipientAddress ?? params.destination.address;
-    const mintRecipient = await getMintRecipientAccount(params.destination.chain.type, destinationAddressForMint, params.destination.chain.usdcAddress);
-    let sender;
-    if (hasCustomContractSupport(params.source.chain, 'bridge')) {
-        if (params.source.chain.type === 'solana') {
-            // Solana: User → Bridge contract → CCTP (user remains sender)
-            sender = params.source.address;
-        } else {
-            // Other chains (like EVM): Bridge contract → CCTP (bridge contract becomes sender)
-            sender = params.source.chain.kitContracts?.bridge;
-        }
-    } else {
-        sender = params.source.address;
-    }
-    checkFieldMismatch('sourceDomain', message.sourceDomain, params.source.chain.cctp.domain.toString(), errors);
-    checkFieldMismatch('destinationDomain', message.destinationDomain, params.destination.chain.cctp.domain.toString(), errors);
-    checkFieldMismatch('minFinalityThreshold', message.minFinalityThreshold, CCTPv2MinFinalityThreshold[params.config.transferSpeed ?? 'FAST'].toString(), errors);
-    checkFieldMismatch('sender', params.source.chain.type === 'evm' ? messageBody.messageSender.toLowerCase() : messageBody.messageSender, params.source.chain.type === 'evm' ? sender?.toLowerCase() : sender, errors);
-    checkFieldMismatch('recipient', params.destination.chain.type === 'evm' ? messageBody.mintRecipient.toLowerCase() : messageBody.mintRecipient, params.destination.chain.type === 'evm' ? mintRecipient.toLowerCase() : mintRecipient, errors);
-    checkFieldMismatch('amount', messageBody.amount, params.amount.toString(), errors);
-    checkFieldMismatch('burnToken', messageBody.burnToken.toLowerCase(), params.source.chain.usdcAddress.toLowerCase(), errors);
-    if (errors.length > 0) {
-        const errorMessage = 'Attestation validation failed: received attestation does not match expected transfer parameters';
-        const firstError = errors[0] ?? '';
+ * 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: `${errorMessage}: ${firstError}`,
-            cause: {
-                trace: {
-                    validationErrors: errors
-                }
-            }
+            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
+        } : {}
+    };
 }
-
 /**
- * Assert that `params` is a well-formed {@link BurnWithFeesParams} object.
+ * Wait for a pending step to complete.
  *
- * 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.
+ * For transaction steps: waits for the transaction to be confirmed.
+ * For attestation: re-executes the attestation fetch.
  *
- * 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
+ * @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 params - The value to validate.
- * @throws {KitError} If any field is missing or invalid.
+ * @throws KitError when fetching attestation but burn transaction hash is not found.
  *
  * @example
  * ```typescript
- * assertBurnWithFeesParams(params)
- * // params is now typed as BurnWithFeesParams and safe to use
- * const { source, destinationChain, amount } = params
+ * 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'
  * ```
- */ function assertBurnWithFeesParams(params) {
-    if (params === null || typeof params !== 'object' || Array.isArray(params)) {
-        throw createValidationFailedError$1('params', params, 'Must be a non-null plain object');
-    }
-    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$1('destinationChain', destinationChain, 'Must be a chain definition object');
-    }
-    if (!isCCTPV2Supported(destinationChain)) {
-        throw createValidationFailedError$1('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$1('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$1('amount', rawAmount, 'Must be a bigint or a numeric string');
+ */ 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 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
+        };
     }
+    // For transaction steps, wait for the transaction to complete
+    return waitForPendingTransaction(pendingStep, adapter, chain);
+}
+
+/**
+ * Multiplier applied to a successful gas estimate before it is submitted.
+ *
+ * Estimates are exact, not padded: Sei returns 109_739 for an approve that
+ * consumes 107_717 (1.9% headroom). Chains that price storage in large steps
+ * can exceed the estimate if state changes between estimation and inclusion,
+ * so the estimate is padded before use.
+ *
+ * @remarks
+ * This buffer alone does NOT cover Sei's ~51_500 per-new-slot step at approve
+ * scale (25% of ~110_000 is only ~27_500). For approve, the FLOOR is what
+ * covers a slot that exists at estimation time and is consumed before
+ * inclusion — so do not lower `APPROVE_GAS_LIMIT_EVM` on the reasoning that
+ * the estimate covers it. For burn the buffer does cover a step (25% of
+ * ~300_000 exceeds 51_500).
+ */ const GAS_ESTIMATE_BUFFER_PERCENT = 125n;
+/**
+ * Resolve the gas limit for an EVM request as `max(estimate * buffer, floor)`.
+ *
+ * Estimates first so chains whose real cost exceeds the floor are covered by
+ * their own measurement, and falls back to the floor whenever estimation is
+ * unavailable or under-reports. Estimation failure is never fatal here: before
+ * floors existed these requests were submitted with a pinned limit and no
+ * estimate at all, so degrading to the floor is never worse than the previous
+ * behaviour.
+ *
+ * @param request - The prepared EVM request to size a gas limit for
+ * @param gasFloor - The minimum gas limit to submit, in gas units
+ * @returns The gas limit to submit, in gas units
+ * @throws Never — estimation failures degrade to `gasFloor`
+ *
+ * @example
+ * ```typescript
+ * const gasLimit = await resolveGasLimit(request, 150_000)
+ * ```
+ */ const resolveGasLimit = async (request, gasFloor)=>{
     try {
-        BigInt(rawAmount);
+        // Deliberately called without a `fallback`: both the viem and ethers
+        // adapters *return* the supplied fallback object when estimation reverts
+        // rather than throwing, which would set the estimate to the floor and then
+        // multiply it by the buffer below. Omitting it routes reverts through the
+        // catch, so a failed estimate degrades to exactly the floor.
+        const estimate = await request.estimate();
+        // The arithmetic stays inside the try on purpose. `EstimatedGas.gas` is
+        // typed `bigint`, but adapters are a public extension point and may be
+        // implemented in plain JS, so a non-bigint `gas` would throw here
+        // ("Cannot mix BigInt and other types"). Guarding it keeps the documented
+        // contract — estimation never aborts a step, it degrades to the floor.
+        const buffered = estimate.gas * GAS_ESTIMATE_BUFFER_PERCENT / 100n;
+        // Convert before comparing: Math.max throws on BigInt operands, and gas
+        // units are far below Number.MAX_SAFE_INTEGER so the narrowing is lossless.
+        return Math.max(Number(buffered), gasFloor);
     } catch  {
-        throw createValidationFailedError$1('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$1('feeTotalAmount', rawFee, 'Must be a bigint or a numeric string');
+        // Estimation is best-effort; the floor is the known-safe value.
+        return gasFloor;
     }
+};
+/**
+ * Executes a prepared chain request and returns the result as a bridge step.
+ *
+ * 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 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
+ *   - `gasFloor`: Optional minimum gas limit (number); the request is submitted
+ *     with `max(estimate * 1.25, gasFloor)`. 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 executePreparedChainRequest({
+ *   name: 'approve',
+ *   request: preparedRequest,
+ *   adapter: adapter,
+ *   confirmations: 2,
+ *   timeout: 30000
+ * })
+ * console.log('Transaction hash:', step.txHash)
+ * ```
+ */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, gasFloor }) {
+    const step = {
+        name,
+        state: 'pending'
+    };
     try {
-        BigInt(rawFee);
-    } catch  {
-        throw createValidationFailedError$1('feeTotalAmount', rawFee, 'Must be a valid integer value coercible to bigint');
-    }
-    // feeToken
-    if (!evmAddressSchema.safeParse(p['feeToken']).success) {
-        throw createValidationFailedError$1('feeToken', p['feeToken'], 'Must be a valid EVM address (use the zero address for a native fee)');
+        /**
+     * 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' && gasFloor !== undefined ? await request.execute({
+            gasLimit: await resolveGasLimit(request, gasFloor)
+        }) : 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.`;
+        }
     }
-    // claim
-    const rawClaim = p['claim'];
-    if (rawClaim === null || typeof rawClaim !== 'object' || Array.isArray(rawClaim)) {
-        throw createValidationFailedError$1('claim', rawClaim, 'Must be an object with signedQuote and refundAddress');
+    return step;
+}
+
+/**
+ * Default configuration values for the attestation fetcher.
+ * @internal
+ */ const DEFAULT_CONFIG = {
+    timeout: 2_000,
+    maxRetries: 30 * 20,
+    retryDelay: 2_000,
+    headers: {
+        'Content-Type': 'application/json'
     }
-    const claim = rawClaim;
-    if (!hexStringSchema.safeParse(claim['signedQuote']).success) {
-        throw createValidationFailedError$1('claim.signedQuote', claim['signedQuote'], 'Must be a valid hex string starting with 0x');
+};
+/**
+ * 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.
+ *
+ * @param obj - The value to check, typically an element from the messages array
+ * @returns True if the object matches the AttestationMessage shape, false otherwise
+ * @internal
+ */ const isValidAttestationMessage = (obj)=>{
+    return typeof obj === 'object' && obj !== null && 'message' in obj && 'eventNonce' in obj && 'attestation' in obj && 'decodedMessage' in obj && 'cctpVersion' in obj && 'status' in obj && typeof obj.status === 'string';
+};
+/**
+ * Type guard that verifies if an attestation message is complete.
+ *
+ * @param message - The attestation message to check
+ * @returns True if the message status is 'complete', false otherwise
+ * @internal
+ */ const isCompleteAttestation = (message)=>{
+    return message.status === 'complete';
+};
+/**
+ * Type guard that verifies if an unknown value has the correct structure
+ * for an AttestationResponse, regardless of attestation completion status.
+ *
+ * @param obj - The value to check, typically a parsed JSON response
+ * @returns True if the object matches the AttestationResponse shape
+ * @internal
+ */ const hasValidAttestationStructure = (obj)=>{
+    if (typeof obj !== 'object' || obj === null || !('messages' in obj) || !Array.isArray(obj.messages)) {
+        return false;
     }
-    if (!evmAddressSchema.safeParse(claim['refundAddress']).success) {
-        throw createValidationFailedError$1('claim.refundAddress', claim['refundAddress'], 'Must be a valid EVM address');
+    const messages = obj.messages;
+    // Validate all messages have the correct shape
+    return messages.every(isValidAttestationMessage);
+};
+/**
+ * Type guard that verifies if an unknown value matches the AttestationResponse shape
+ * and contains a complete attestation.
+ *
+ * This function performs runtime validation to ensure that the provided value
+ * conforms to the expected structure of an AttestationResponse and has at least
+ * one complete attestation. It checks that:
+ * 1. The value has valid AttestationResponse structure
+ * 2. At least one message has status 'complete'
+ *
+ * @remarks
+ * This type guard is used internally by the attestation fetcher to validate
+ * responses from the IRIS API before processing them. It provides runtime
+ * type safety for data coming from the network and ensures we have a complete
+ * attestation before proceeding.
+ *
+ * If the response has valid structure but no complete attestation yet,
+ * it throws a retryable error. If the response structure is invalid,
+ * it throws a non-retryable validation error.
+ *
+ * @param obj - The value to check, typically a parsed JSON response
+ * @returns True if the object matches the AttestationResponse shape and has a complete attestation
+ * @throws {Error} With "Invalid attestation response structure" if structure is invalid (non-retryable)
+ * @throws {Error} With "Attestation not ready" if no complete attestation yet (retryable)
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('https://iris-api.circle.com/...')
+ * const data = await response.json()
+ *
+ * if (isAttestationResponse(data)) {
+ *   // TypeScript now knows data is AttestationResponse with at least one complete attestation
+ *   const completeMessage = data.messages.find(msg => msg.status === 'complete')
+ *   console.log('Found complete attestation:', completeMessage.attestation)
+ * }
+ * ```
+ */ const isAttestationResponse = (obj)=>{
+    // First check if the structure is valid
+    if (!hasValidAttestationStructure(obj)) {
+        // If structure is invalid, this is a permanent failure - don't retry
+        throw new Error('Invalid attestation response structure');
     }
-    // hookData (optional)
-    const hookData = p['hookData'];
-    if (hookData !== undefined && hookData !== '' && !hexStringSchema.safeParse(hookData).success) {
-        throw createValidationFailedError$1('hookData', hookData, 'Must be a valid hex string starting with 0x');
+    // Then check if at least one message is complete
+    if (!obj.messages.some(isCompleteAttestation)) {
+        // If no complete message, this is a temporary state - allow retry
+        throw new Error('Attestation not ready');
     }
-}
-
+    return true;
+};
 /**
- * CCTP bridge step names that can occur in the bridging flow.
+ * Builds the IRIS API URL for fetching attestation data from Circle's CCTP service.
  *
- * 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'
+ * Constructs a properly formatted URL for the IRIS API v2 endpoint that provides
+ * attestation messages for cross-chain transfers. The URL includes both the source
+ * domain identifier and the transaction hash as query parameters. The base URL
+ * is selected based on whether the operation is for testnet or mainnet.
+ *
+ * @param sourceDomainId - The CCTP domain ID of the source chain (numeric or string)
+ * @param transactionHash - The transaction hash of the burn operation to fetch attestation for
+ * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
+ * @returns A fully qualified URL string for the IRIS API endpoint
+ *
+ * @example
+ * ```typescript
+ * // Mainnet URL
+ * const mainnetUrl = buildIrisUrl(1, '0xabc...', false)
+ * // => 'https://iris-api.circle.com/v2/messages/1?transactionHash=0xabc...'
+ *
+ * // Testnet URL
+ * const testnetUrl = buildIrisUrl(1, '0xdef...', true)
+ * // => 'https://iris-api-sandbox.circle.com/v2/messages/1?transactionHash=0xdef...'
+ * ```
+ */ const buildIrisUrl = (sourceDomainId, transactionHash, isTestnet)=>{
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const url = new URL(`${baseUrl}/v2/messages/${String(sourceDomainId)}`);
+    url.searchParams.set('transactionHash', transactionHash);
+    return url.toString();
 };
 /**
- * Conditional step transition rules for CCTP bridge flow.
+ * Fetches attestation data from the IRIS API with retry and timeout handling.
  *
- * 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
-        }
-    ]
+ * Polls the IRIS API until a complete attestation is available. The default
+ * window is sized for slow source chains where finality may take many
+ * confirmations.
+ *
+ * Defaults (see `DEFAULT_CONFIG`):
+ * - Per-attempt timeout: 2 000 ms (each HTTP request aborts after 2 s)
+ * - Retry delay: 2 000 ms between attempts
+ * - Max retries: 600 (30 × 20)
+ * - Total worst-case polling window: 600 × (2 000 ms + 2 000 ms) ≈ 40 minutes
+ *
+ * @param sourceDomainId - The CCTP domain ID.
+ * @param transactionHash - The transaction hash to fetch attestation for.
+ * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
+ * @param config - Optional configuration overrides for the attestation fetcher
+ * @returns The attestation response data.
+ * @throws If the request fails, times out, or returns invalid data.
+ *
+ * @example
+ * ```typescript
+ * // Fetch attestation for mainnet transaction
+ * const response = await fetchAttestation(1, '0xabc...', false)
+ * console.log(`Found ${response.messages.length} attestation messages`)
+ *
+ * // Fetch with custom timeout
+ * const response2 = await fetchAttestation(1, '0xdef...', true, {
+ *   timeout: 5000,
+ *   maxRetries: 5
+ * })
+ * ```
+ */ const fetchAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
+    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
+    const effectiveConfig = mergeAttestationConfig(config);
+    return await pollApiGet(url, isAttestationResponse, effectiveConfig);
 };
 /**
- * Analyze bridge steps to determine retry feasibility and continuation point.
+ * Type guard that validates attestation response structure without requiring completion status.
  *
- * 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 is used by `fetchAttestationWithoutStatusCheck` to extract the nonce from an existing
+ * attestation, even if the attestation is expired or pending. Unlike `isAttestationResponse`,
+ * this function does not throw if no complete attestation is found.
  *
- * The current analysis supports the standard CCTP flow:
- * **Traditional flow**: Approve → Burn → FetchAttestation → Mint
+ * @param obj - The value to check, typically a parsed JSON response
+ * @returns True if the object has valid attestation structure
+ * @throws {Error} With "Invalid attestation response structure" if structure is invalid
+ * @internal
+ */ const isAttestationResponseWithoutStatusCheck = (obj)=>{
+    if (!hasValidAttestationStructure(obj)) {
+        throw new Error('Invalid attestation response structure');
+    }
+    return true;
+};
+/**
+ * Fetches attestation data without requiring the attestation to be complete.
  *
- * 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
+ * This function is useful for retrieving attestation data (particularly the nonce)
+ * from an existing transaction, even if the attestation has expired or is pending.
+ * It uses minimal retries since we're fetching existing data, not waiting for completion.
  *
- * @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.
+ * @param sourceDomainId - The CCTP domain ID of the source chain
+ * @param transactionHash - The transaction hash to fetch attestation for
+ * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
+ * @param config - Optional configuration overrides
+ * @returns The attestation response data (may contain incomplete/expired attestations)
+ * @throws If the request fails, times out, or returns invalid data
  *
  * @example
  * ```typescript
- * import { analyzeSteps } from './analyzeSteps'
+ * // Fetch existing attestation to extract nonce for re-attestation
+ * const response = await fetchAttestationWithoutStatusCheck(1, '0xabc...', true)
+ * const nonce = response.messages[0]?.eventNonce
+ * ```
+ */ 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 = mergeAttestationConfig(config, {
+        maxRetries: 3
+    });
+    return await pollApiGet(url, isAttestationResponseWithoutStatusCheck, effectiveConfig);
+};
+/**
+ * Type guard that validates attestation response has expirationBlock === '0'.
  *
- * // Failed approval step (requires user action)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'error', errorMessage: 'User rejected' }
- *   ]
- * }
+ * This is used after requestReAttestation() to poll until the attestation
+ * is fully re-processed and has a zero expiration block (never expires).
+ * The expiration block transitions from non-zero to zero when Circle
+ * completes processing the re-attestation request.
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: 'Approve', isRetryable: true,
- * //          reason: 'Retry failed approval' }
- * ```
+ * @param obj - The value to check, typically a parsed JSON response
+ * @returns True if the attestation has expirationBlock === '0'
+ * @throws {Error} With "Re-attestation not yet complete" if expirationBlock is not '0'
  *
  * @example
  * ```typescript
- * // Pending transaction (requires waiting, not actionable)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'pending' }
- *   ]
- * }
- *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: 'Approve', isRetryable: false,
- * //          reason: 'Continue pending approval' }
+ * // After requesting re-attestation, use this to validate the response
+ * const response = await pollApiGet(url, isReAttestedAttestationResponse, config)
+ * // response.messages[0].decodedMessage.decodedMessageBody.expirationBlock === '0'
  * ```
  *
+ * @internal
+ */ const isReAttestedAttestationResponse = (obj)=>{
+    // First validate the basic structure and completion status
+    // This will throw appropriate errors for invalid structure or incomplete attestation
+    if (!isAttestationResponse(obj)) ;
+    // Check if the first message has expirationBlock === '0'
+    const expirationBlock = obj.messages[0]?.decodedMessage?.decodedMessageBody?.expirationBlock;
+    if (expirationBlock !== '0') {
+        // Re-attestation not yet complete - allow retry via polling
+        throw new Error('Re-attestation not yet complete: waiting for expirationBlock to become 0');
+    }
+    return true;
+};
+/**
+ * Fetches attestation data and polls until expirationBlock === '0'.
+ *
+ * This function is used after calling requestReAttestation() to wait until
+ * the attestation is fully re-processed. The expirationBlock transitions
+ * from non-zero to zero when Circle completes the re-attestation.
+ *
+ * @param sourceDomainId - The CCTP domain ID of the source chain
+ * @param transactionHash - The transaction hash to fetch attestation for
+ * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
+ * @param config - Optional configuration overrides
+ * @returns The re-attested attestation response with expirationBlock === '0'
+ * @throws If the request fails, times out, or expirationBlock never becomes 0
+ *
  * @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' }
- *   ]
- * }
+ * // After requesting re-attestation
+ * await requestReAttestation(nonce, isTestnet)
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: null, isRetryable: false,
- * //          reason: 'Bridge completed successfully' }
+ * // Poll until expirationBlock becomes 0
+ * const response = await fetchReAttestedAttestation(domainId, txHash, isTestnet)
+ * // response.messages[0].decodedMessage.decodedMessageBody.expirationBlock === '0'
  * ```
- */ 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
-    };
+ */ const fetchReAttestedAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
+    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
+    const effectiveConfig = mergeAttestationConfig(config);
+    return await pollApiGet(url, isReAttestedAttestationResponse, effectiveConfig);
 };
 /**
- * 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.
+ * Builds the IRIS API URL for re-attestation requests.
  *
- * @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.
+ * Constructs the URL for Circle's re-attestation endpoint that allows
+ * requesting a fresh attestation for an expired nonce.
  *
- * @param result - The bridge result to search.
- * @param stepName - The name of the step to find.
- * @returns The step if found, undefined otherwise.
+ * @param nonce - The nonce from the original attestation
+ * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
+ * @returns A fully qualified URL string for the re-attestation endpoint
  *
  * @example
  * ```typescript
- * import { findStepByName } from './findStep'
+ * // Mainnet URL
+ * const mainnetUrl = buildReAttestUrl('0xabc', false)
+ * // => 'https://iris-api.circle.com/v2/reattest/0xabc'
  *
- * const burnStep = findStepByName(result, 'burn')
- * if (burnStep) {
- *   console.log('Burn tx:', burnStep.txHash)
- * }
+ * // Testnet URL
+ * const testnetUrl = buildReAttestUrl('0xabc', true)
+ * // => 'https://iris-api-sandbox.circle.com/v2/reattest/0xabc'
  * ```
- */ function findStepByName(result, stepName) {
-    return result.steps.find((step)=>step.name === stepName);
-}
+ */ const buildReAttestUrl = (nonce, isTestnet)=>{
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const url = new URL(`${baseUrl}/v2/reattest/${nonce}`);
+    return url.toString();
+};
 /**
- * Find a pending step by name and return it with its index.
+ * Type guard that validates the re-attestation API response structure.
  *
- * Searches for a step that matches both the step name and has a pending state.
+ * @param obj - The value to check, typically a parsed JSON response
+ * @returns True if the object matches the ReAttestationResponse shape
+ * @throws {Error} With "Invalid re-attestation response structure" if structure is invalid
+ * @internal
+ */ const isReAttestationResponse = (obj)=>{
+    if (typeof obj !== 'object' || obj === null || !('message' in obj) || !('nonce' in obj) || typeof obj.message !== 'string' || typeof obj.nonce !== 'string') {
+        throw new Error('Invalid re-attestation response structure');
+    }
+    return true;
+};
+/**
+ * Requests re-attestation for an expired attestation nonce.
  *
- * @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.
+ * This function calls Circle's re-attestation API endpoint to request a fresh
+ * attestation for a previously issued nonce. After calling this function,
+ * you should poll `fetchAttestation` to retrieve the new attestation.
+ *
+ * @param nonce - The nonce from the original (expired) attestation
+ * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
+ * @param config - Optional configuration overrides for the request
+ * @returns The re-attestation response confirming the request was accepted
+ * @throws If the request fails, times out, or returns invalid data
  *
  * @example
  * ```typescript
- * import { findPendingStep } from './findStep'
+ * // Request re-attestation for an expired nonce
+ * const response = await requestReAttestation('0xabc', true)
+ * console.log(response.message) // "Re-attestation successfully requested for nonce."
  *
- * const { step, index } = findPendingStep(result, 'burn')
- * console.log('Pending step:', step.name, 'at index:', index)
+ * // After requesting re-attestation, poll for the new attestation
+ * const attestation = await fetchAttestation(domainId, txHash, true)
  * ```
- */ function findPendingStep(result, stepName) {
-    const index = result.steps.findIndex((step)=>step.name === stepName && step.state === 'pending');
-    if (index === -1) {
+ */ 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 = mergeAttestationConfig(config, {
+        maxRetries: 3
+    });
+    return await pollApiPost(url, {}, isReAttestationResponse, effectiveConfig);
+};
+
+/**
+ * Type guard that checks if the relayer has confirmed the mint transaction.
+ *
+ * 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
+ *
+ * If forwardState is 'FAILED', throws a non-retryable KitError.
+ * If forwardState is 'PENDING' or not present, throws a RETRYABLE KitError to continue polling.
+ *
+ * @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: `Pending step "${stepName}" not found in result`
+            message: 'Invalid attestation response structure from IRIS API.'
         });
     }
-    const step = result.steps[index];
-    if (!step) {
+    // 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: 'Pending step is undefined'
+            message: 'No attestation messages found in IRIS API response.'
         });
     }
-    return {
-        step,
-        index
-    };
-}
+    // 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.'
+    });
+};
 /**
- * Get the burn transaction hash from bridge result.
+ * Polls the attestation API until the relayer's mint transaction is confirmed.
  *
- * @param result - The bridge result.
- * @returns The burn transaction hash, or undefined if not found.
+ * 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
- * import { getBurnTxHash } from './findStep'
- *
- * const burnTxHash = getBurnTxHash(result)
- * if (burnTxHash) {
- *   console.log('Burn tx hash:', burnTxHash)
- * }
+ * const attestation = await fetchRelayerMint(0, '0xabc...', false)
+ * console.log('Relayer mint tx:', attestation.forwardTxHash)
  * ```
- */ function getBurnTxHash(result) {
-    return findStepByName(result, CCTPv2StepName.burn)?.txHash;
-}
+ */ 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');
 /**
- * Get the attestation data from bridge result.
+ * 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 result - The bridge result.
- * @returns The attestation data, or undefined if not found.
+ * @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 { getAttestationData } from './findStep'
+ * import { assertCCTPv2WalletContext } from '@circle-fin/provider-cctp-v2'
+ * import { Ethereum } from '@core/chains'
  *
- * const attestation = getAttestationData(result)
- * if (attestation) {
- *   console.log('Attestation:', attestation.message)
+ * // 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 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;
+ */ 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');
     }
-    // Fall back to fetchAttestation step
-    const fetchStep = findStepByName(result, CCTPv2StepName.fetchAttestation);
-    return fetchStep?.data;
 }
 
+const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
 /**
- * Check if the analysis indicates a non-actionable pending state.
- *
- * 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.
+ * 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 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.
+ * @param params - The parameters to validate
+ * @throws {KitError} If validation fails, with details about which properties failed
  *
  * @example
  * ```typescript
- * import { hasPendingState } from './stepUtils'
- * import { analyzeSteps } from '../analyzeSteps'
+ * import { assertCCTPv2BridgeParams } from '@circle-fin/provider-cctp-v2'
+ * import { Ethereum, Base } from '@core/chains'
  *
- * const analysis = analyzeSteps(bridgeResult)
- * if (hasPendingState(analysis, bridgeResult)) {
- *   // Wait for the pending operation to complete
+ * // Prepare transfer parameters
+ * const params = {
+ *   amount: '100.50',
+ *   source: {
+ *     adapter: sourceAdapter,
+ *     address: '0xSourceAddress',
+ *     chain: {
+ *       ...Ethereum,
+ *       cctp: {
+ *         domain: 1,
+ *         contracts: {
+ *           v2: {
+ *             tokenMessenger: '0xTokenMessenger',
+ *             messageTransmitter: '0xMessageTransmitter'
+ *           }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   destination: {
+ *     adapter: destAdapter,
+ *     address: '0xDestAddress',
+ *     chain: {
+ *       ...Base,
+ *       cctp: {
+ *         domain: 2,
+ *         contracts: {
+ *           v2: {
+ *             tokenMessenger: '0xTokenMessenger',
+ *             messageTransmitter: '0xMessageTransmitter'
+ *           }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   token: 'USDC',
+ *   config: {
+ *     transferSpeed: 'FAST',
+ *     maxFee: '1000000'
+ *   }
  * }
- * ```
- */ /**
- * 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`.
+ * // This will throw if validation fails
+ * assertCCTPv2BridgeParams(params)
  *
- * @example
- * ```typescript
- * const outcome = evaluateTransactionOutcome(receipt, '0xabc...')
- * step.state = outcome.state
- * if (outcome.errorMessage) step.errorMessage = outcome.errorMessage
+ * // If we get here, params is guaranteed to be valid
+ * console.log('CCTPv2 transfer parameters are valid')
  * ```
- */ function evaluateTransactionOutcome(receipt, txHash) {
-    if (receipt.status === 'success' && receipt.blockNumber) {
-        return {
-            state: 'success'
-        };
+ */ function assertCCTPv2BridgeParams(params) {
+    // First validate basic bridge params
+    validateWithStateTracking(params, bridgeParamsSchema, 'CCTPv2 bridge parameters', assertCCTPv2BridgeParamsSymbol);
+    // After validation, we know params is CCTPV2BridgeParams
+    const bridgeParams = params;
+    // Enforce that source and destination chains are either testnet or mainnet
+    if (bridgeParams.source.chain.isTestnet !== bridgeParams.destination.chain.isTestnet) {
+        throw createNetworkMismatchError(bridgeParams.source.chain, bridgeParams.destination.chain);
     }
-    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;
+    assertCCTPV2Support(bridgeParams.source.chain, bridgeParams.destination.chain);
+    // Validate that the destination chain supports forwarding when forwarder is enabled
+    assertForwarderRouteSupport(bridgeParams.source.chain, bridgeParams.destination.chain, bridgeParams.destination.useForwarder);
+    /**
+   * Enforce that if fee is defined then feeRecipient must be defined.
+   * We do not do this in the validation function itself because we want to allow
+   * optional properties when calling `provider.bridge()` due to the custom fee
+   * configuration being possible at the kit level as well.
+   */ if (bridgeParams.config?.customFee?.value !== undefined && bridgeParams.config?.customFee?.recipientAddress === undefined) {
+        throw createValidationFailedError$1('recipientAddress', bridgeParams.config.customFee.value, 'Custom fee is defined but fee recipient is not. Please provide a fee recipient.');
+    }
+    // Check if this is a forwarder-only destination (no adapter, requires useForwarder: true)
+    const isForwarderOnly = bridgeParams.destination.useForwarder === true && !('adapter' in bridgeParams.destination && bridgeParams.destination.adapter);
+    // Forwarder-only destinations require recipientAddress
+    if (isForwarderOnly) {
+        if (!bridgeParams.destination.recipientAddress?.trim()) {
+            throw createValidationFailedError$1('recipientAddress', bridgeParams.destination.recipientAddress, 'recipientAddress is required when using forwarder without a destination adapter.');
+        }
+    }
+    // Validate CCTP v2 specific requirements for source wallet
+    assertCCTPv2WalletContext(bridgeParams.source);
+    // Validate that source adapter supports the chain (defense-in-depth)
+    bridgeParams.source.adapter.validateChainSupport(bridgeParams.source.chain);
+    // Only validate destination wallet context and adapter if not forwarder-only
+    if (!isForwarderOnly) {
+        assertCCTPv2WalletContext(bridgeParams.destination);
+        // Validate that destination adapter supports the chain (defense-in-depth)
+        bridgeParams.destination.adapter.validateChainSupport(bridgeParams.destination.chain);
     }
-    // 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.
- *
- * @example
- * ```typescript
- * import { isLastStep } from './stepUtils'
+ * Validate CCTP v2 support on both chains
+ */ /**
+ * Throws a KitError if the given chain does not support CCTP v2.
  *
- * 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;
+ * @param chain - The chain to check for CCTP v2 support
+ * @param otherChain - The other chain in the route (for error context)
+ * @param isSource - Whether this is the source chain (for error context)
+ */ function assertCCTPV2Support(source, destination) {
+    if (!isCCTPV2Supported(source) || !isCCTPV2Supported(destination)) {
+        throw createUnsupportedRouteError(source.name, destination.name);
+    }
 }
 /**
- * Wait for a pending transaction to complete.
- *
- * Poll the adapter until the transaction is confirmed on-chain and return
- * the updated step with success or error state based on the receipt.
+ * Validates that the forwarder (relaying) feature is compatible with the route.
  *
- * @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.
+ * Checks the destination chain's `cctp.forwarderSupported.destination` property
+ * to determine whether the chain supports receiving forwarded transfers.
  *
- * @throws KitError when the pending step has no transaction hash.
+ * @param source - The source chain definition
+ * @param destination - The destination chain definition
+ * @param useForwarder - Whether the forwarder is enabled on the destination
+ * @throws {KitError} If the forwarder is enabled and the destination chain does not support forwarding
+ */ function assertForwarderRouteSupport(source, destination, useForwarder) {
+    if (useForwarder === true && !destination.cctp?.forwarderSupported.destination) {
+        throw new KitError({
+            ...InputError.UNSUPPORTED_ROUTE,
+            recoverability: 'FATAL',
+            message: `Route from ${source.name} to ${destination.name} with forwarder is not supported (destination chain does not support forwarding).`,
+            cause: {
+                trace: {
+                    source: source.name,
+                    destination: destination.name
+                }
+            }
+        });
+    }
+}
+
+/**
+ * Checks if a decoded attestation field matches the corresponding transfer parameter.
+ * If the values do not match, appends a descriptive error message to the errors array.
  *
- * @example
- * ```typescript
- * import { waitForPendingTransaction } from './bridgeStepUtils'
+ * @param field - The name of the field being compared (for error reporting)
+ * @param decoded - The value decoded from the attestation message
+ * @param param - The expected value from the transfer parameters
+ * @param errors - The array to which error messages will be appended if a mismatch is found
+ */ function checkFieldMismatch(field, decoded, param, errors) {
+    if (decoded !== param) {
+        errors.push(`${field} mismatch: decoded=${String(decoded)}, params=${String(param)}`);
+    }
+}
+/**
+ * Asserts that the decoded message from attestation matches the provided transfer params.
+ * Throws KitError if any field mismatches, with clear error messages.
  *
- * 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) {
+ * @param attestation - The attestation message containing the decoded message
+ * @param params - The transfer parameters to validate against
+ * @throws {@link KitError} If any field mismatches
+ */ async function assertCCTPv2AttestationParams(attestation, params) {
+    const errors = [];
+    const message = attestation.decodedMessage;
+    const messageBody = message.decodedMessageBody;
+    // Use recipientAddress if provided, otherwise use destination.address
+    const destinationAddressForMint = params.destination.recipientAddress ?? params.destination.address;
+    const mintRecipient = await getMintRecipientAccount(params.destination.chain.type, destinationAddressForMint, params.destination.chain.usdcAddress);
+    let sender;
+    if (hasCustomContractSupport(params.source.chain, 'bridge')) {
+        if (params.source.chain.type === 'solana') {
+            // Solana: User → Bridge contract → CCTP (user remains sender)
+            sender = params.source.address;
+        } else {
+            // Other chains (like EVM): Bridge contract → CCTP (bridge contract becomes sender)
+            sender = params.source.chain.kitContracts?.bridge;
+        }
+    } else {
+        sender = params.source.address;
+    }
+    checkFieldMismatch('sourceDomain', message.sourceDomain, params.source.chain.cctp.domain.toString(), errors);
+    checkFieldMismatch('destinationDomain', message.destinationDomain, params.destination.chain.cctp.domain.toString(), errors);
+    checkFieldMismatch('minFinalityThreshold', message.minFinalityThreshold, CCTPv2MinFinalityThreshold[params.config.transferSpeed ?? 'FAST'].toString(), errors);
+    checkFieldMismatch('sender', params.source.chain.type === 'evm' ? messageBody.messageSender.toLowerCase() : messageBody.messageSender, params.source.chain.type === 'evm' ? sender?.toLowerCase() : sender, errors);
+    checkFieldMismatch('recipient', params.destination.chain.type === 'evm' ? messageBody.mintRecipient.toLowerCase() : messageBody.mintRecipient, params.destination.chain.type === 'evm' ? mintRecipient.toLowerCase() : mintRecipient, errors);
+    checkFieldMismatch('amount', messageBody.amount, params.amount.toString(), errors);
+    checkFieldMismatch('burnToken', messageBody.burnToken.toLowerCase(), params.source.chain.usdcAddress.toLowerCase(), errors);
+    if (errors.length > 0) {
+        const errorMessage = 'Attestation validation failed: received attestation does not match expected transfer parameters';
+        const firstError = errors[0] ?? '';
         throw new KitError({
             ...InputError.VALIDATION_FAILED,
             recoverability: 'FATAL',
-            message: `Cannot wait for pending ${pendingStep.name}: no transaction hash available`
+            message: `${errorMessage}: ${firstError}`,
+            cause: {
+                trace: {
+                    validationErrors: errors
+                }
+            }
         });
     }
-    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.
+ * Assert that `params` is a well-formed {@link BurnWithFeesParams} object.
  *
- * For transaction steps: waits for the transaction to be confirmed.
- * For attestation: re-executes the attestation fetch.
+ * 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.
  *
- * @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.
+ * 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
  *
- * @throws KitError when fetching attestation but burn transaction hash is not found.
+ * @param params - The value to validate.
+ * @throws {KitError} If any field is missing or invalid.
  *
  * @example
  * ```typescript
- * 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'
+ * assertBurnWithFeesParams(params)
+ * // params is now typed as BurnWithFeesParams and safe to use
+ * const { source, destinationChain, amount } = params
  * ```
- */ 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 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
-        };
+ */ function assertBurnWithFeesParams(params) {
+    if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+        throw createValidationFailedError$1('params', params, 'Must be a non-null plain object');
+    }
+    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$1('destinationChain', destinationChain, 'Must be a chain definition object');
+    }
+    if (!isCCTPV2Supported(destinationChain)) {
+        throw createValidationFailedError$1('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$1('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$1('amount', rawAmount, 'Must be a bigint or a numeric string');
     }
-    // For transaction steps, wait for the transaction to complete
-    return waitForPendingTransaction(pendingStep, adapter, chain);
-}
-
-/**
- * Executes a prepared chain request and returns the result as a bridge step.
- *
- * 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 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 executePreparedChainRequest({
- *   name: 'approve',
- *   request: preparedRequest,
- *   adapter: adapter,
- *   confirmations: 2,
- *   timeout: 30000
- * })
- * console.log('Transaction hash:', step.txHash)
- * ```
- */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, gasLimit }) {
-    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 = 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';
-        }
-    } 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.`;
-        }
+        BigInt(rawAmount);
+    } catch  {
+        throw createValidationFailedError$1('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$1('feeTotalAmount', rawFee, 'Must be a bigint or a numeric string');
+    }
+    try {
+        BigInt(rawFee);
+    } catch  {
+        throw createValidationFailedError$1('feeTotalAmount', rawFee, 'Must be a valid integer value coercible to bigint');
+    }
+    // feeToken
+    if (!evmAddressSchema.safeParse(p['feeToken']).success) {
+        throw createValidationFailedError$1('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$1('claim', rawClaim, 'Must be an object with signedQuote and refundAddress');
+    }
+    const claim = rawClaim;
+    if (!hexStringSchema.safeParse(claim['signedQuote']).success) {
+        throw createValidationFailedError$1('claim.signedQuote', claim['signedQuote'], 'Must be a valid hex string starting with 0x');
+    }
+    if (!evmAddressSchema.safeParse(claim['refundAddress']).success) {
+        throw createValidationFailedError$1('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$1('hookData', hookData, 'Must be a valid hex string starting with 0x');
     }
-    return step;
 }
 
 /**
@@ -14046,7 +14360,7 @@ function hasPendingState(analysis, result) {
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.approve(params.source, approvalAmount),
-        gasLimit: Number(APPROVE_GAS_LIMIT_EVM)
+        gasFloor: Number(BRIDGE_STEP_GAS_FLOORS_EVM.approve)
     });
 }
 
@@ -14074,7 +14388,7 @@ function hasPendingState(analysis, result) {
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.burn(params),
-        gasLimit: Number(DEPOSIT_FOR_BURN_GAS_LIMIT_EVM)
+        gasFloor: Number(BRIDGE_STEP_GAS_FLOORS_EVM.burn)
     });
 }
 
@@ -14168,10 +14482,9 @@ function hasPendingState(analysis, result) {
         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)
+        // without reverting. The floor covers those; chains that cost more than the
+        // floor are covered by their own estimate.
+        gasFloor: Number(BRIDGE_STEP_GAS_FLOORS_EVM.mint)
     });
     // Add forwarded: false for non-relayer mints
     return {
@@ -14694,7 +15007,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$2 = "1.10.1";
+var version$2 = "1.11.0";
 var pkg$2 = {
 	version: version$2};
 
@@ -15653,10 +15966,39 @@ function assertCCTPV2Config(config) {
         // CCTP-specific transfer params validation (includes base validation)
         assertCCTPv2BridgeParams(params);
         const { source, destination, amount } = params;
-        const estimateBurn = async ()=>{
-            const burn = await this.burn(params);
-            return await burn.estimate(undefined, await source.adapter.calculateTransactionFee(hasCustomContractSupport(source.chain, 'bridge') ? CUSTOM_BURN_GAS_ESTIMATE_EVM : DEPOSIT_FOR_BURN_GAS_ESTIMATE_EVM, undefined, source.chain));
+        /**
+     * Price the gas a step will RESERVE on-chain, not what it will spend.
+     *
+     * A transaction is only admitted when the sender holds
+     * `gasLimit * gasPrice`, and `executePreparedChainRequest` submits
+     * `max(estimate * buffer, floor)`. Quoting a bare `estimate()` therefore
+     * under-reports what a wallet must hold to send at all: the floor governs
+     * on virtually every chain, which put the burn quote ~2.5x below the real
+     * requirement and left anyone funding from it unable to submit.
+     *
+     * Delegates to the same `resolveGasLimit` the execute path calls, so a
+     * quote and the limit later submitted for that step cannot drift apart.
+     * That also means an estimation failure degrades to the floor here exactly
+     * as it does on execution, rather than surfacing as a failed quote — the
+     * floor is what would be submitted, so it is the honest number to quote.
+     *
+     * Non-EVM requests are unchanged: `executePreparedChainRequest` only
+     * applies a floor when `request.type === 'evm'`, so there is no reserved
+     * limit to quote on other chains.
+     */ const quoteReservedGas = async (request, gasFloor, priceGas, // Ignored on EVM — only evaluated and used on non-EVM paths.
+        nonEvmFallbackGasEstimate)=>{
+            if (request.type !== 'evm') {
+                return nonEvmFallbackGasEstimate === undefined ? await request.estimate() : await request.estimate(undefined, await priceGas(nonEvmFallbackGasEstimate()));
+            }
+            // resolveGasLimit returns number; gas units are well below Number.MAX_SAFE_INTEGER,
+            // so the Number() → resolveGasLimit → BigInt() round-trip is lossless.
+            return await priceGas(BigInt(await resolveGasLimit(request, Number(gasFloor))));
         };
+        const priceGasFor = (ctx)=>async (gasUnits)=>await ctx.adapter.calculateTransactionFee(gasUnits, undefined, ctx.chain);
+        const priceSourceGas = priceGasFor(source);
+        const priceDestinationGas = priceGasFor(destination);
+        const estimateApprove = async ()=>await quoteReservedGas(await this.approve(source, amount), BRIDGE_STEP_GAS_FLOORS_EVM.approve, priceSourceGas);
+        const estimateBurn = async ()=>await quoteReservedGas(await this.burn(params), BRIDGE_STEP_GAS_FLOORS_EVM.burn, priceSourceGas, ()=>hasCustomContractSupport(source.chain, 'bridge') ? CUSTOM_BURN_GAS_ESTIMATE_EVM : DEPOSIT_FOR_BURN_GAS_ESTIMATE_EVM);
         // Only estimate Mint gas when not using forwarder (user pays gas)
         // When useForwarder=true, Circle's Orbit relayer handles and pays for the mint
         const useForwarder = destination.useForwarder === true;
@@ -15665,12 +16007,11 @@ function assertCCTPV2Config(config) {
                 return null // Skip mint estimation when forwarder handles it
                 ;
             }
-            const mint = await this.mint(source, destination, mockAttestationMessage);
-            return await mint.estimate(undefined, await destination.adapter.calculateTransactionFee(RECEIVE_MESSAGE_GAS_ESTIMATE_EVM, undefined, destination.chain));
+            return await quoteReservedGas(await this.mint(source, destination, mockAttestationMessage), BRIDGE_STEP_GAS_FLOORS_EVM.mint, priceDestinationGas, ()=>RECEIVE_MESSAGE_GAS_ESTIMATE_EVM);
         };
         // Parallelize all independent async operations
         const [approveEstimate, depositForBurnFee, receiveMessageFee, feeEstimates] = await Promise.allSettled([
-            this.approve(source, amount).then(async (approve)=>approve.estimate()),
+            estimateApprove(),
             estimateBurn(),
             estimateMint(),
             this.getMaxFee(params)
@@ -17292,7 +17633,9 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
             headers: context.headers
         }
     });
-    if (hasBoth) {
+    if (context.customFeePolicy?.bridge != null) {
+        kit.setCustomFeePolicy(context.customFeePolicy.bridge);
+    } else if (hasBoth) {
         kit.setCustomFeePolicy({
             calculateFee: async (params)=>{
                 const feeStr = await getFee('bridge', params);
@@ -17308,7 +17651,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.5.0";
+var version$1 = "1.5.2";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -19251,7 +19594,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
 var name = "@circle-fin/earn-kit";
-var version = "1.4.0";
+var version = "1.5.1";
 var pkg = {
 	name: name,
 	version: version};
@@ -20262,11 +20605,16 @@ const sourceAdapterContextSchema = z.object({
  *
  * Validate the optional Kit Key field using the standard `apiKeySchema`
  * format (`KIT_KEY:<keyId>:<keySecret>`). When omitted, the SDK
- * operates in permissionless mode.
+ * operates in permissionless mode. `baseUrl` overrides the Earn Service
+ * endpoint (e.g. staging); `batchTransactions: false` opts out of atomic
+ * batched execution. Both are forwarded to the provider, so this `.strict()`
+ * schema must accept them or a valid config object is rejected.
  *
  * @internal
  */ const earnConfigSchema = z.object({
-    kitKey: apiKeySchema.optional()
+    kitKey: apiKeySchema.optional(),
+    baseUrl: z.string().optional(),
+    batchTransactions: z.boolean().optional()
 }).strict();
 /**
  * Canonical decimal form: a leading digit with no leading zeros (a single