@circle-fin/app-kit 1.12.0 → 1.12.1

package/estimateBridge.mjs

@@ -8323,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',
@@ -9910,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.
  *
@@ -9989,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.
  *
@@ -10198,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
@@ -12600,6 +12704,25 @@ const DEPOSIT_FOR_BURN_GAS_LIMIT_EVM = 500_000n // buffered worst 474_078 (Sei 3
 ;
 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.
  *
@@ -12618,1595 +12741,1595 @@ const RECEIVE_MESSAGE_GAS_LIMIT_EVM = 400_000n // observed max 310_839; clears C
 };
 
 /**
- * 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.
+ * CCTP bridge step names that can occur in the bridging flow.
  *
- * @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';
+ * 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'
 };
 /**
- * Type guard that verifies if an attestation message is complete.
+ * Conditional step transition rules for CCTP bridge flow.
  *
- * @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';
+ * 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
+        }
+    ]
 };
 /**
- * Type guard that verifies if an unknown value has the correct structure
- * for an AttestationResponse, regardless of attestation completion status.
+ * Analyze bridge steps to determine retry feasibility and continuation point.
  *
- * @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 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 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'
+ * The current analysis supports the standard CCTP flow:
+ * **Traditional flow**: Approve → Burn → FetchAttestation → Mint
  *
- * @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.
+ * 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 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)
+ * @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
- * const response = await fetch('https://iris-api.circle.com/...')
- * const data = await response.json()
+ * import { analyzeSteps } from './analyzeSteps'
  *
- * 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)
+ * // Failed approval step (requires user action)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'error', errorMessage: 'User rejected' }
+ *   ]
  * }
- * ```
- */ 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;
-};
-/**
- * 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
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: 'Approve', isRetryable: true,
+ * //          reason: 'Retry failed approval' }
+ * ```
  *
  * @example
  * ```typescript
- * // Mainnet URL
- * const mainnetUrl = buildIrisUrl(1, '0xabc...', false)
- * // => 'https://iris-api.circle.com/v2/messages/1?transactionHash=0xabc...'
+ * // Pending transaction (requires waiting, not actionable)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'pending' }
+ *   ]
+ * }
  *
- * // Testnet URL
- * const testnetUrl = buildIrisUrl(1, '0xdef...', true)
- * // => 'https://iris-api-sandbox.circle.com/v2/messages/1?transactionHash=0xdef...'
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: 'Approve', isRetryable: false,
+ * //          reason: 'Continue pending approval' }
  * ```
- */ 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();
-};
-/**
- * Fetches attestation data from the IRIS API with retry and timeout handling.
- *
- * 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`)
+ * // Completed bridge (nothing to do)
+ * const bridgeResult = {
+ *   steps: [
+ *     { name: 'Approve', state: 'success' },
+ *     { name: 'Burn', state: 'success' },
+ *     { name: 'FetchAttestation', state: 'success' },
+ *     { name: 'Mint', state: 'success' }
+ *   ]
+ * }
  *
- * // Fetch with custom timeout
- * const response2 = await fetchAttestation(1, '0xdef...', true, {
- *   timeout: 5000,
- *   maxRetries: 5
- * })
+ * const analysis = analyzeSteps(bridgeResult)
+ * // Result: { continuationStep: null, isRetryable: false,
+ * //          reason: 'Bridge completed successfully' }
  * ```
- */ const fetchAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
-    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = mergeAttestationConfig(config);
-    return await pollApiGet(url, isAttestationResponse, effectiveConfig);
+ */ 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
+    };
 };
 /**
- * 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.
+ * Build flow context from the execution history.
  *
- * @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');
+ * @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 true;
-};
+    return {
+        completedSteps,
+        failedSteps,
+        ...lastStep && {
+            lastStep
+        }
+    };
+}
 /**
- * Fetches attestation data without requiring the attestation to be complete.
+ * Determine continuation step using the rule engine.
  *
- * 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 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 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
+ * @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
- * // 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);
-};
+ * import { findStepByName } from './findStep'
+ *
+ * const burnStep = findStepByName(result, 'burn')
+ * if (burnStep) {
+ *   console.log('Burn tx:', burnStep.txHash)
+ * }
+ * ```
+ */ function findStepByName(result, stepName) {
+    return result.steps.find((step)=>step.name === stepName);
+}
 /**
- * Type guard that validates attestation response has expirationBlock === '0'.
+ * Find a pending step by name and return it with its index.
  *
- * 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.
+ * 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 attestation has expirationBlock === '0'
- * @throws {Error} With "Re-attestation not yet complete" if expirationBlock is not '0'
+ * @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
- * // After requesting re-attestation, use this to validate the response
- * const response = await pollApiGet(url, isReAttestedAttestationResponse, config)
- * // response.messages[0].decodedMessage.decodedMessageBody.expirationBlock === '0'
- * ```
+ * import { findPendingStep } from './findStep'
  *
- * @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 { step, index } = findPendingStep(result, 'burn')
+ * console.log('Pending step:', step.name, 'at index:', index)
+ * ```
+ */ function findPendingStep(result, stepName) {
+    const index = result.steps.findIndex((step)=>step.name === stepName && step.state === 'pending');
+    if (index === -1) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Pending step "${stepName}" not found in result`
+        });
     }
-    return true;
-};
+    const step = result.steps[index];
+    if (!step) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'Pending step is undefined'
+        });
+    }
+    return {
+        step,
+        index
+    };
+}
 /**
- * Fetches attestation data and polls until expirationBlock === '0'.
+ * Get the burn transaction hash from bridge result.
  *
- * 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 result - The bridge result.
+ * @returns The burn transaction hash, or undefined if not found.
  *
- * @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
+ * import { getBurnTxHash } from './findStep'
+ *
+ * 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
- * // After requesting re-attestation
- * await requestReAttestation(nonce, isTestnet)
+ * import { getAttestationData } from './findStep'
  *
- * // Poll until expirationBlock becomes 0
- * const response = await fetchReAttestedAttestation(domainId, txHash, isTestnet)
- * // response.messages[0].decodedMessage.decodedMessageBody.expirationBlock === '0'
+ * const attestation = getAttestationData(result)
+ * if (attestation) {
+ *   console.log('Attestation:', attestation.message)
+ * }
  * ```
- */ const fetchReAttestedAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
-    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = mergeAttestationConfig(config);
-    return await pollApiGet(url, isReAttestedAttestationResponse, effectiveConfig);
-};
+ */ function getAttestationData(result) {
+    // Prefer reAttest data (most recent attestation after expiry)
+    const reAttestStep = findStepByName(result, CCTPv2StepName.reAttest);
+    if (reAttestStep?.state === 'success' && reAttestStep.data) {
+        return reAttestStep.data;
+    }
+    // Fall back to fetchAttestation step
+    const fetchStep = findStepByName(result, CCTPv2StepName.fetchAttestation);
+    return fetchStep?.data;
+}
+
 /**
- * Builds the IRIS API URL for re-attestation requests.
+ * Check if the analysis indicates a non-actionable pending state.
  *
- * Constructs the URL for Circle's re-attestation endpoint that allows
- * requesting a fresh attestation for an expired nonce.
+ * 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 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 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
- * // Mainnet URL
- * const mainnetUrl = buildReAttestUrl('0xabc', false)
- * // => 'https://iris-api.circle.com/v2/reattest/0xabc'
+ * import { hasPendingState } from './stepUtils'
+ * import { analyzeSteps } from '../analyzeSteps'
  *
- * // Testnet URL
- * const testnetUrl = buildReAttestUrl('0xabc', true)
- * // => 'https://iris-api-sandbox.circle.com/v2/reattest/0xabc'
+ * const analysis = analyzeSteps(bridgeResult)
+ * if (hasPendingState(analysis, bridgeResult)) {
+ *   // Wait for the pending operation to complete
+ * }
  * ```
- */ 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.
+ */ /**
+ * 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 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');
+ * @param receipt - The transaction receipt containing status and block info.
+ * @param txHash - The transaction hash used in error messages.
+ * @returns An object with `state` and an optional `errorMessage`.
+ *
+ * @example
+ * ```typescript
+ * const outcome = evaluateTransactionOutcome(receipt, '0xabc...')
+ * step.state = outcome.state
+ * if (outcome.errorMessage) step.errorMessage = outcome.errorMessage
+ * ```
+ */ function evaluateTransactionOutcome(receipt, txHash) {
+    if (receipt.status === 'success' && receipt.blockNumber) {
+        return {
+            state: 'success'
+        };
     }
-    return true;
-};
+    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;
+}
 /**
- * Requests re-attestation for an expired attestation nonce.
- *
- * 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.
+ * Check if the step is the last one in the execution flow.
  *
- * @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 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
- * // Request re-attestation for an expired nonce
- * const response = await requestReAttestation('0xabc', true)
- * console.log(response.message) // "Re-attestation successfully requested for nonce."
+ * import { isLastStep } from './stepUtils'
  *
- * // After requesting re-attestation, poll for the new attestation
- * const attestation = await fetchAttestation(domainId, txHash, true)
+ * const stepNames = ['approve', 'burn', 'fetchAttestation', 'mint']
+ * isLastStep({ name: 'mint' }, stepNames) // true
+ * isLastStep({ name: 'burn' }, stepNames) // false
  * ```
- */ 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);
-};
-
+ */ function isLastStep(step, stepNames) {
+    const stepIndex = stepNames.indexOf(step.name);
+    return stepIndex === -1 || stepIndex >= stepNames.length - 1;
+}
 /**
- * Type guard that checks if the relayer has confirmed the mint transaction.
+ * Wait for a pending transaction to complete.
  *
- * This function validates that:
- * 1. The response has valid AttestationResponse structure
- * 2. At least one message has forwardState === 'CONFIRMED' (or 'COMPLETE') and a valid forwardTxHash
+ * Poll the adapter until the transaction is confirmed on-chain and return
+ * the updated step with success or error state based on the receipt.
  *
- * If forwardState is 'FAILED', throws a non-retryable KitError.
- * If forwardState is 'PENDING' or not present, throws a RETRYABLE KitError to continue polling.
+ * @param pendingStep - The full step object containing the transaction hash.
+ * @param adapter - The adapter to use for waiting.
+ * @param chain - The chain where the transaction was submitted.
+ * @returns The updated step object with success or error state.
  *
- * @param obj - The value to check, typically a parsed JSON response
- * @returns True if the relayer has confirmed the mint
- * @throws {KitError} With FATAL recoverability if structure is invalid
- * @throws {KitError} With RESUMABLE recoverability if forwardState is 'FAILED'
- * @throws {KitError} With RETRYABLE recoverability if still pending
- * @internal
- */ const isRelayerMintConfirmed = (obj)=>{
-    // First check if the structure is valid
-    if (!hasValidAttestationStructure(obj)) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'Invalid attestation response structure from IRIS API.'
-        });
-    }
-    // Find the first message (typically there's only one)
-    const message = obj.messages[0];
-    if (!message) {
+ * @throws KitError when the pending step has no transaction hash.
+ *
+ * @example
+ * ```typescript
+ * import { waitForPendingTransaction } from './bridgeStepUtils'
+ *
+ * const pendingStep = { name: 'burn', state: 'pending', txHash: '0x123...' }
+ * const updatedStep = await waitForPendingTransaction(pendingStep, adapter, chain)
+ * // updatedStep.state is now 'success' or 'error'
+ * ```
+ */ async function waitForPendingTransaction(pendingStep, adapter, chain) {
+    if (!pendingStep.txHash) {
         throw new KitError({
             ...InputError.VALIDATION_FAILED,
             recoverability: 'FATAL',
-            message: 'No attestation messages found in IRIS API response.'
-        });
-    }
-    // Check for FAILED state - this is a permanent failure
-    if (message.forwardState === 'FAILED') {
-        throw new KitError({
-            ...NetworkError.RELAYER_FORWARD_FAILED,
-            recoverability: 'RESUMABLE',
-            message: 'Circle relayer failed to forward the mint transaction. The mint may still have succeeded if another party submitted it. Check the recipient wallet balance before retrying. If the mint did not occur, you can manually submit it using the attestation data in the error cause.',
-            cause: {
-                trace: {
-                    eventNonce: message.eventNonce,
-                    attestation: message.attestation,
-                    message: message.message
-                }
-            }
+            message: `Cannot wait for pending ${pendingStep.name}: no transaction hash available`
         });
     }
-    // Check if mint is confirmed (or complete) with a valid transaction hash
-    // We accept both CONFIRMED and COMPLETE since COMPLETE implies CONFIRMED
-    if ((message.forwardState === 'CONFIRMED' || message.forwardState === 'COMPLETE') && typeof message.forwardTxHash === 'string' && message.forwardTxHash.trim().length > 0) {
-        return true;
-    }
-    // Still pending or not yet processed - throw RETRYABLE error to continue polling
-    throw new KitError({
-        ...NetworkError.RELAYER_PENDING,
-        recoverability: 'RETRYABLE',
-        message: 'Relayer mint not ready. Waiting for confirmation.'
+    const txHash = pendingStep.txHash;
+    const txReceipt = await retryAsync(async ()=>adapter.waitForTransaction(txHash, undefined, chain), {
+        isRetryable: (err)=>isRetryableError$1(parseBlockchainError(err, {
+                chain: chain.name,
+                txHash
+            }))
     });
-};
+    const outcome = evaluateTransactionOutcome(txReceipt, txHash);
+    return {
+        ...pendingStep,
+        state: outcome.state,
+        data: txReceipt,
+        explorerUrl: buildExplorerUrl(chain, txHash),
+        ...outcome.errorMessage ? {
+            errorMessage: outcome.errorMessage
+        } : {}
+    };
+}
 /**
- * Polls the attestation API until the relayer's mint transaction is confirmed.
+ * Wait for a pending step to complete.
  *
- * This function is used when `useForwarder` is enabled. Instead of the user
- * submitting the mint transaction, Circle's Orbit relayer handles it automatically.
- * This function polls until the relayer has submitted and confirmed the mint transaction.
+ * For transaction steps: waits for the transaction to be confirmed.
+ * For attestation: re-executes the attestation fetch.
  *
- * @remarks
- * - Uses a 20-minute timeout by default (600 retries × 2 seconds)
- * - Throws immediately if `forwardState` is 'FAILED'
- * - Waits for `forwardState` to be 'CONFIRMED' or 'COMPLETE' (COMPLETE implies CONFIRMED)
- * - Returns the attestation message with `forwardTxHash` populated
+ * @typeParam TFromAdapterCapabilities - The capabilities of the source adapter.
+ * @typeParam TToAdapterCapabilities - The capabilities of the destination adapter.
+ * @param pendingStep - The full step object (with name, state, txHash, data, etc.) to resolve.
+ * @param adapter - The adapter to use.
+ * @param chain - The chain where the step is executing.
+ * @param context - The retry context.
+ * @param result - The bridge result.
+ * @param provider - The CCTP v2 bridging provider.
+ * @returns The resolved step object with updated state.
  *
- * @param sourceDomainId - The CCTP domain ID of the source chain
- * @param transactionHash - The transaction hash of the burn operation
- * @param isTestnet - Whether this is for a testnet chain (true) or mainnet (false)
- * @param config - Optional configuration overrides for polling behavior
- * @returns The attestation message with confirmed forwardTxHash
- * @throws {KitError} With code 'NETWORK_RELAYER_FORWARD_FAILED' if relayer failed
- * @throws {KitError} If timeout is reached while still pending
+ * @throws KitError when fetching attestation but burn transaction hash is not found.
  *
  * @example
  * ```typescript
- * const attestation = await fetchRelayerMint(0, '0xabc...', false)
- * console.log('Relayer mint tx:', attestation.forwardTxHash)
+ * import { waitForStepToComplete } from './bridgeStepUtils'
+ *
+ * const pendingStep = { name: 'burn', state: 'pending', txHash: '0x123...' }
+ * const updatedStep = await waitForStepToComplete(
+ *   pendingStep,
+ *   adapter,
+ *   chain,
+ *   context,
+ *   result,
+ *   provider,
+ * )
+ * // updatedStep.state is now 'success' or 'error'
  * ```
- */ const fetchRelayerMint = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
-    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = 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') {
+ */ async function waitForStepToComplete(pendingStep, adapter, chain, context, result, provider) {
+    if (pendingStep.name === CCTPv2StepName.fetchAttestation) {
+        // For attestation, re-run the fetch (it has built-in polling)
+        const burnTxHash = getBurnTxHash(result);
+        if (!burnTxHash) {
             throw new KitError({
-                ...NetworkError.RELAYER_FORWARD_FAILED,
-                recoverability: error.recoverability,
-                message: error.message,
-                cause: {
-                    ...error.cause,
-                    trace: {
-                        ...error.cause?.trace,
-                        burnTxHash: transactionHash
-                    }
-                }
+                ...InputError.VALIDATION_FAILED,
+                recoverability: 'FATAL',
+                message: 'Cannot fetch attestation: burn transaction hash not found'
             });
         }
-        throw error;
-    }
-    // Return the first message (which should have forwardTxHash)
-    // Note: This check is needed for TypeScript type safety even though
-    // isRelayerMintConfirmed validates messages[0] exists. The type guard
-    // narrows the type at the call site, but TypeScript can't infer that
-    // the array still has elements after pollApiGet returns.
-    const message = response.messages[0];
-    if (!message) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'No attestation messages found in response after polling.'
-        });
+        const sourceAddress = result.source.address;
+        const attestation = await provider.fetchAttestation({
+            chain: result.source.chain,
+            adapter: context.from,
+            address: sourceAddress
+        }, burnTxHash);
+        return {
+            ...pendingStep,
+            state: 'success',
+            data: attestation
+        };
     }
-    return message;
-};
+    // For transaction steps, wait for the transaction to complete
+    return waitForPendingTransaction(pendingStep, adapter, chain);
+}
 
-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)
+ * Multiplier applied to a successful gas estimate before it is submitted.
  *
- * @param params - The parameters to validate
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ * 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.
  *
- * @example
- * ```typescript
- * import { assertCCTPv2WalletContext } from '@circle-fin/provider-cctp-v2'
- * import { Ethereum } from '@core/chains'
+ * @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)`.
  *
- * // 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'
- *         }
- *       }
- *     }
- *   }
- * }
+ * 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.
  *
- * // This will throw if validation fails
- * assertCCTPv2WalletContext(context)
+ * @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`
  *
- * // If we get here, context is guaranteed to be valid
- * console.log('CCTPv2 wallet context is valid')
+ * @example
+ * ```typescript
+ * const gasLimit = await resolveGasLimit(request, 150_000)
  * ```
- */ function assertCCTPv2WalletContext(params) {
-    // First validate basic wallet context
-    validateWithStateTracking(params, walletContextSchema, 'CCTPv2 wallet context', assertCCTPv2WalletContextSymbol);
-    // After validation, we know params is WalletContext
-    const context = params;
-    // Validate USDC support
-    if (context.chain.usdcAddress === null) {
-        throw createInvalidChainError(context.chain.name, 'Does not have USDC configured');
-    }
-    // Validate CCTPv2 support
-    if (!isCCTPV2Supported(context.chain)) {
-        throw createInvalidChainError(context.chain.name, 'Does not support CCTPv2');
-    }
-}
-
-const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
-/**
- * Asserts that the provided parameters match the CCTPv2 bridge parameters interface.
- * The validation includes:
- * - Basic parameter structure and types
- * - Amount validation (non-empty numeric string \> 0)
- * - Wallet address format validation (must be valid Ethereum address)
- * - Chain definition validation (must be a valid chain with required properties)
- * - Adapter validation (must implement required methods)
- * - Optional config validation (transfer speed and max fee)
- * - Network compatibility (source and destination chains must both be testnet or both mainnet)
- * - CCTPv2-specific wallet context validations
+ */ const resolveGasLimit = async (request, gasFloor)=>{
+    try {
+        // 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  {
+        // 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.
  *
- * @param params - The parameters to validate
- * @throws {KitError} If validation fails, with details about which properties failed
+ * 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
- * import { assertCCTPv2BridgeParams } from '@circle-fin/provider-cctp-v2'
- * import { Ethereum, Base } from '@core/chains'
- *
- * // 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 step = await executePreparedChainRequest({
+ *   name: 'approve',
+ *   request: preparedRequest,
+ *   adapter: adapter,
+ *   confirmations: 2,
+ *   timeout: 30000
+ * })
+ * console.log('Transaction hash:', step.txHash)
  * ```
- */ 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.');
+ */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, gasFloor }) {
+    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' && 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.`;
         }
     }
-    // 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);
-    }
+    return step;
 }
+
 /**
- * Validate CCTP v2 support on both chains
- */ /**
- * Throws a KitError if the given chain does not support CCTP v2.
- *
- * @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);
+ * 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'
     }
-}
+};
 /**
- * Validates that the forwarder (relaying) feature is compatible with the route.
- *
- * Checks the destination chain's `cctp.forwarderSupported.destination` property
- * to determine whether the chain supports receiving forwarded transfers.
+ * Merges caller-provided polling overrides on top of {@link DEFAULT_CONFIG}.
  *
- * @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.
+ * Headers are merged independently so caller-supplied headers augment the
+ * defaults (such as `Content-Type`) rather than replacing them wholesale.
  *
- * @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)}`);
-    }
-}
+ * @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
+        }
+    });
 /**
- * Asserts that the decoded message from attestation matches the provided transfer params.
- * Throws KitError if any field mismatches, with clear error messages.
+ * Type guard that verifies if an unknown value matches the AttestationMessage shape
+ * and has all required properties.
  *
- * @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: `${errorMessage}: ${firstError}`,
-            cause: {
-                trace: {
-                    validationErrors: errors
-                }
-            }
-        });
+ * @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);
+};
 /**
- * Assert that `params` is a well-formed {@link BurnWithFeesParams} object.
+ * Type guard that verifies if an unknown value matches the AttestationResponse shape
+ * and contains a complete attestation.
  *
- * 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.
+ * 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'
  *
- * 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
+ * @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.
  *
- * @param params - The value to validate.
- * @throws {KitError} If any field is missing or invalid.
+ * 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
- * assertBurnWithFeesParams(params)
- * // params is now typed as BurnWithFeesParams and safe to use
- * const { source, destinationChain, amount } = params
+ * 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)
+ * }
  * ```
- */ 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');
-    }
-    try {
-        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');
+ */ 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);
+};
+/**
+ * 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.
+ *
+ * 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 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
+ * // 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);
 };
 /**
- * Analyze bridge steps to determine retry feasibility and continuation point.
- *
- * 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.
- *
- * The current analysis supports the standard CCTP flow:
- * **Traditional flow**: Approve → Burn → FetchAttestation → Mint
+ * Type guard that validates attestation response has expirationBlock === '0'.
  *
- * 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 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.
  *
- * @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 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
- * import { analyzeSteps } from './analyzeSteps'
+ * // After requesting re-attestation, use this to validate the response
+ * const response = await pollApiGet(url, isReAttestedAttestationResponse, config)
+ * // response.messages[0].decodedMessage.decodedMessageBody.expirationBlock === '0'
+ * ```
  *
- * // Failed approval step (requires user action)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'error', errorMessage: 'User rejected' }
- *   ]
- * }
+ * @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'.
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: 'Approve', isRetryable: true,
- * //          reason: 'Retry failed approval' }
- * ```
+ * 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
- * // Pending transaction (requires waiting, not actionable)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'pending' }
- *   ]
- * }
+ * // After requesting re-attestation
+ * await requestReAttestation(nonce, isTestnet)
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: 'Approve', isRetryable: false,
- * //          reason: 'Continue pending approval' }
+ * // 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);
+};
+/**
+ * Builds the IRIS API URL for re-attestation requests.
+ *
+ * Constructs the URL for Circle's re-attestation endpoint that allows
+ * requesting a fresh attestation for an expired nonce.
+ *
+ * @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
- * // Completed bridge (nothing to do)
- * const bridgeResult = {
- *   steps: [
- *     { name: 'Approve', state: 'success' },
- *     { name: 'Burn', state: 'success' },
- *     { name: 'FetchAttestation', state: 'success' },
- *     { name: 'Mint', state: 'success' }
- *   ]
- * }
+ * // Mainnet URL
+ * const mainnetUrl = buildReAttestUrl('0xabc', false)
+ * // => 'https://iris-api.circle.com/v2/reattest/0xabc'
  *
- * const analysis = analyzeSteps(bridgeResult)
- * // Result: { continuationStep: null, isRetryable: false,
- * //          reason: 'Bridge completed successfully' }
+ * // Testnet URL
+ * const testnetUrl = buildReAttestUrl('0xabc', true)
+ * // => 'https://iris-api-sandbox.circle.com/v2/reattest/0xabc'
  * ```
- */ 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 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();
 };
 /**
- * Build flow context from the execution history.
+ * Type guard that validates the re-attestation API response structure.
  *
- * @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
-        };
+ * @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 {
-        completedSteps,
-        failedSteps,
-        ...lastStep && {
-            lastStep
-        }
-    };
-}
+    return true;
+};
 /**
- * Determine continuation step using the rule engine.
+ * Requests re-attestation for an expired attestation 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.
+ * 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 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 (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 { findStepByName } 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 burnStep = findStepByName(result, 'burn')
- * if (burnStep) {
- *   console.log('Burn tx:', burnStep.txHash)
- * }
+ * // After requesting re-attestation, poll for the new attestation
+ * const attestation = await fetchAttestation(domainId, txHash, true)
  * ```
- */ function findStepByName(result, stepName) {
-    return result.steps.find((step)=>step.name === stepName);
-}
+ */ 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);
+};
+
 /**
- * Find a pending step by name and return it with its index.
- *
- * Searches for a step that matches both the step name and has a pending state.
+ * Type guard that checks if the relayer has confirmed the mint transaction.
  *
- * @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 validates that:
+ * 1. The response has valid AttestationResponse structure
+ * 2. At least one message has forwardState === 'CONFIRMED' (or 'COMPLETE') and a valid forwardTxHash
  *
- * @example
- * ```typescript
- * import { findPendingStep } from './findStep'
+ * If forwardState is 'FAILED', throws a non-retryable KitError.
+ * If forwardState is 'PENDING' or not present, throws a RETRYABLE KitError to continue polling.
  *
- * const { step, index } = findPendingStep(result, 'burn')
- * console.log('Pending step:', step.name, 'at index:', index)
- * ```
- */ function findPendingStep(result, stepName) {
-    const index = result.steps.findIndex((step)=>step.name === stepName && step.state === 'pending');
-    if (index === -1) {
+ * @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.
- *
- * @param result - The bridge result.
- * @returns The burn transaction hash, or undefined if not found.
+ * Polls the attestation API until the relayer's mint transaction is confirmed.
  *
- * @example
- * ```typescript
- * import { getBurnTxHash } from './findStep'
+ * 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.
  *
- * 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.
+ * @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 result - The bridge result.
- * @returns The attestation data, or undefined if not found.
+ * @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 { getAttestationData } from './findStep'
- *
- * const attestation = getAttestationData(result)
- * if (attestation) {
- *   console.log('Attestation:', attestation.message)
- * }
+ * const attestation = await fetchRelayerMint(0, '0xabc...', false)
+ * console.log('Relayer mint tx:', attestation.forwardTxHash)
  * ```
- */ function getAttestationData(result) {
-    // Prefer reAttest data (most recent attestation after expiry)
-    const reAttestStep = findStepByName(result, CCTPv2StepName.reAttest);
-    if (reAttestStep?.state === 'success' && reAttestStep.data) {
-        return reAttestStep.data;
+ */ const 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;
     }
-    // Fall back to fetchAttestation step
-    const fetchStep = findStepByName(result, CCTPv2StepName.fetchAttestation);
-    return fetchStep?.data;
-}
+    // 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');
 /**
- * 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 wallet context interface.
+ * The validation includes:
+ * - Basic wallet context validation (adapter, address, chain)
+ * - CCTPv2-specific chain validation (must be an EVM chain)
  *
- * @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 INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
- * import { hasPendingState } from './stepUtils'
- * import { analyzeSteps } from '../analyzeSteps'
+ * import { assertCCTPv2WalletContext } from '@circle-fin/provider-cctp-v2'
+ * import { Ethereum } from '@core/chains'
  *
- * const analysis = analyzeSteps(bridgeResult)
- * if (hasPendingState(analysis, bridgeResult)) {
- *   // Wait for the pending operation to complete
+ * // 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'
+ *         }
+ *       }
+ *     }
+ *   }
  * }
- * ```
- */ /**
- * 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
+ * assertCCTPv2WalletContext(context)
  *
- * @example
- * ```typescript
- * const outcome = evaluateTransactionOutcome(receipt, '0xabc...')
- * step.state = outcome.state
- * if (outcome.errorMessage) step.errorMessage = outcome.errorMessage
+ * // If we get here, context is guaranteed to be valid
+ * console.log('CCTPv2 wallet context is valid')
  * ```
- */ function evaluateTransactionOutcome(receipt, txHash) {
-    if (receipt.status === 'success' && receipt.blockNumber) {
-        return {
-            state: 'success'
-        };
-    }
-    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;
+ */ 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');
     }
-    // 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');
 /**
- * Check if the step is the last one in the execution flow.
+ * 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 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.
+ * @param params - The parameters to validate
+ * @throws {KitError} If validation fails, with details about which properties failed
  *
  * @example
  * ```typescript
- * import { isLastStep } from './stepUtils'
+ * import { assertCCTPv2BridgeParams } from '@circle-fin/provider-cctp-v2'
+ * import { Ethereum, Base } from '@core/chains'
  *
- * const stepNames = ['approve', 'burn', 'fetchAttestation', 'mint']
- * isLastStep({ name: 'mint' }, stepNames) // true
- * isLastStep({ name: 'burn' }, stepNames) // false
+ * // 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')
  * ```
- */ function isLastStep(step, stepNames) {
-    const stepIndex = stepNames.indexOf(step.name);
-    return stepIndex === -1 || stepIndex >= stepNames.length - 1;
+ */ 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);
+    }
 }
 /**
- * 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.
- *
- * @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.
+ * Validate CCTP v2 support on both chains
+ */ /**
+ * Throws a KitError if the given chain does not support CCTP v2.
  *
- * @throws KitError when the pending step has no transaction hash.
+ * @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.
  *
- * @example
- * ```typescript
- * import { waitForPendingTransaction } from './bridgeStepUtils'
+ * Checks the destination chain's `cctp.forwarderSupported.destination` property
+ * to determine whether the chain supports receiving forwarded transfers.
  *
- * 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 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.VALIDATION_FAILED,
+            ...InputError.UNSUPPORTED_ROUTE,
             recoverability: 'FATAL',
-            message: `Cannot wait for pending ${pendingStep.name}: no transaction hash available`
+            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
+                }
+            }
         });
     }
-    const txHash = pendingStep.txHash;
-    const txReceipt = await retryAsync(async ()=>adapter.waitForTransaction(txHash, undefined, chain), {
-        isRetryable: (err)=>isRetryableError$1(parseBlockchainError(err, {
-                chain: chain.name,
-                txHash
-            }))
-    });
-    const outcome = evaluateTransactionOutcome(txReceipt, txHash);
-    return {
-        ...pendingStep,
-        state: outcome.state,
-        data: txReceipt,
-        explorerUrl: buildExplorerUrl(chain, txHash),
-        ...outcome.errorMessage ? {
-            errorMessage: outcome.errorMessage
-        } : {}
-    };
 }
+
 /**
- * Wait for a pending step to complete.
- *
- * For transaction steps: waits for the transaction to be confirmed.
- * For attestation: re-executes the attestation fetch.
- *
- * @typeParam TFromAdapterCapabilities - The capabilities of the source adapter.
- * @typeParam TToAdapterCapabilities - The capabilities of the destination adapter.
- * @param pendingStep - The full step object (with name, state, txHash, data, etc.) to resolve.
- * @param adapter - The adapter to use.
- * @param chain - The chain where the step is executing.
- * @param context - The retry context.
- * @param result - The bridge result.
- * @param provider - The CCTP v2 bridging provider.
- * @returns The resolved step object with updated state.
- *
- * @throws KitError when fetching attestation but burn transaction hash is not found.
+ * 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 { waitForStepToComplete } 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 waitForStepToComplete(
- *   pendingStep,
- *   adapter,
- *   chain,
- *   context,
- *   result,
- *   provider,
- * )
- * // updatedStep.state is now 'success' or 'error'
- * ```
- */ 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
-        };
+ * @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: `${errorMessage}: ${firstError}`,
+            cause: {
+                trace: {
+                    validationErrors: errors
+                }
+            }
+        });
     }
-    // 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.
+ * Assert that `params` is a well-formed {@link BurnWithFeesParams} object.
  *
- * @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)`.
+ * 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.
  *
- * 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.
+ * Checks performed (in order):
+ * - `params` must be a non-null plain object
+ * - `source` — valid CCTP v2 wallet context (via `assertCCTPv2WalletContext`)
+ * - `destinationChain` — present and supports CCTP v2
+ * - source and destination chains must both be testnet or both mainnet
+ * - source and destination chains must differ
+ * - `executor` — non-empty string
+ * - `amount` — bigint or non-empty string coercible to bigint
+ * - `feeTotalAmount` — bigint or non-empty string coercible to bigint
+ * - `feeToken` — valid EVM address (`0x` + 40 hex chars)
+ * - `claim.signedQuote` — valid `0x`-prefixed hex string
+ * - `claim.refundAddress` — valid EVM address
+ * - `hookData` — valid `0x`-prefixed hex string when present
  *
- * @param 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`
+ * @param params - The value to validate.
+ * @throws {KitError} If any field is missing or invalid.
  *
  * @example
  * ```typescript
- * const gasLimit = await resolveGasLimit(request, 150_000)
+ * assertBurnWithFeesParams(params)
+ * // params is now typed as BurnWithFeesParams and safe to use
+ * const { source, destinationChain, amount } = params
  * ```
- */ const resolveGasLimit = async (request, gasFloor)=>{
+ */ 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');
+    }
     try {
-        // 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);
+        BigInt(rawAmount);
     } catch  {
-        // Estimation is best-effort; the floor is the known-safe value.
-        return gasFloor;
+        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');
     }
-};
-/**
- * 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 {
-        /**
-     * 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.`;
-        }
+        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;
 }
 
 /**
@@ -14237,7 +14360,7 @@ function hasPendingState(analysis, result) {
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.approve(params.source, approvalAmount),
-        gasFloor: Number(APPROVE_GAS_LIMIT_EVM)
+        gasFloor: Number(BRIDGE_STEP_GAS_FLOORS_EVM.approve)
     });
 }
 
@@ -14265,7 +14388,7 @@ function hasPendingState(analysis, result) {
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.burn(params),
-        gasFloor: Number(DEPOSIT_FOR_BURN_GAS_LIMIT_EVM)
+        gasFloor: Number(BRIDGE_STEP_GAS_FLOORS_EVM.burn)
     });
 }
 
@@ -14361,7 +14484,7 @@ function hasPendingState(analysis, result) {
         // eth_estimateGas does not account for, returning a below-floor value
         // without reverting. The floor covers those; chains that cost more than the
         // floor are covered by their own estimate.
-        gasFloor: Number(RECEIVE_MESSAGE_GAS_LIMIT_EVM)
+        gasFloor: Number(BRIDGE_STEP_GAS_FLOORS_EVM.mint)
     });
     // Add forwarded: false for non-relayer mints
     return {
@@ -14884,7 +15007,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$2 = "1.10.2";
+var version$2 = "1.11.0";
 var pkg$2 = {
 	version: version$2};
 
@@ -15843,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;
@@ -15855,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)
@@ -17500,7 +17651,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.5.1";
+var version$1 = "1.5.2";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -19443,7 +19594,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
 var name = "@circle-fin/earn-kit";
-var version = "1.5.0";
+var version = "1.5.1";
 var pkg = {
 	name: name,
 	version: version};