@circle-fin/provider-cctp-v2 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @circle-fin/provider-cctp-v2
 
+## 1.3.0
+
+### Minor Changes
+
+- Integrate automatic re-attestation into bridge orchestrator retry logic for CCTP v2 fast transfers:
+  - Automatically detect mint failures due to expired attestations and trigger re-attestation flow
+
 ## 1.2.0
 
 ### Minor Changes

package/index.cjs

@@ -81,6 +81,8 @@ var Blockchain;
     Blockchain["Ink_Testnet"] = "Ink_Testnet";
     Blockchain["Linea"] = "Linea";
     Blockchain["Linea_Sepolia"] = "Linea_Sepolia";
+    Blockchain["Monad"] = "Monad";
+    Blockchain["Monad_Testnet"] = "Monad_Testnet";
     Blockchain["NEAR"] = "NEAR";
     Blockchain["NEAR_Testnet"] = "NEAR_Testnet";
     Blockchain["Noble"] = "Noble";
@@ -172,6 +174,7 @@ var BridgeChain;
     BridgeChain["HyperEVM"] = "HyperEVM";
     BridgeChain["Ink"] = "Ink";
     BridgeChain["Linea"] = "Linea";
+    BridgeChain["Monad"] = "Monad";
     BridgeChain["Optimism"] = "Optimism";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
@@ -191,6 +194,7 @@ var BridgeChain;
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
     BridgeChain["Ink_Testnet"] = "Ink_Testnet";
     BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
+    BridgeChain["Monad_Testnet"] = "Monad_Testnet";
     BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
     BridgeChain["Plume_Testnet"] = "Plume_Testnet";
     BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
@@ -1177,6 +1181,86 @@ const LineaSepolia = defineChain({
     },
 });
 
+/**
+ * Monad Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Monad blockchain.
+ * Monad is a high-performance EVM-compatible Layer-1 blockchain featuring
+ * over 10,000 TPS, sub-second finality, and near-zero gas fees.
+ */
+const Monad = defineChain({
+    type: 'evm',
+    chain: Blockchain.Monad,
+    name: 'Monad',
+    title: 'Monad Mainnet',
+    nativeCurrency: {
+        name: 'Monad',
+        symbol: 'MON',
+        decimals: 18,
+    },
+    chainId: 143,
+    isTestnet: false,
+    explorerUrl: 'https://monadscan.com/tx/{hash}',
+    rpcEndpoints: ['https://rpc.monad.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
+    cctp: {
+        domain: 15,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Monad Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Monad blockchain.
+ * Monad is a high-performance EVM-compatible Layer-1 blockchain featuring
+ * over 10,000 TPS, sub-second finality, and near-zero gas fees.
+ */
+const MonadTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Monad_Testnet,
+    name: 'Monad Testnet',
+    title: 'Monad Testnet',
+    nativeCurrency: {
+        name: 'Monad',
+        symbol: 'MON',
+        decimals: 18,
+    },
+    chainId: 10143,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.monadscan.com/tx/{hash}',
+    rpcEndpoints: ['https://testnet-rpc.monad.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
+    cctp: {
+        domain: 15,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * NEAR Protocol Mainnet chain definition
  * @remarks
@@ -2261,6 +2345,8 @@ var Chains = {
     InkTestnet: InkTestnet,
     Linea: Linea,
     LineaSepolia: LineaSepolia,
+    Monad: Monad,
+    MonadTestnet: MonadTestnet,
     NEAR: NEAR,
     NEARTestnet: NEARTestnet,
     Noble: Noble,
@@ -3284,6 +3370,8 @@ const ERROR_TYPES = {
     RPC: 'RPC',
     /** Internet connectivity, DNS resolution, connection issues */
     NETWORK: 'NETWORK',
+    /** Catch-all for unrecognized errors (code 0) */
+    UNKNOWN: 'UNKNOWN',
 };
 /**
  * Array of valid error type values for validation.
@@ -3297,6 +3385,8 @@ const ERROR_TYPE_ARRAY = [...ERROR_TYPE_VALUES];
 /**
  * Error code ranges for validation.
  * Single source of truth for valid error code ranges.
+ *
+ * Note: Code 0 is special - it's the UNKNOWN catch-all error.
  */
 const ERROR_CODE_RANGES = [
     { min: 1000, max: 1999, type: 'INPUT' },
@@ -3305,6 +3395,8 @@ const ERROR_CODE_RANGES = [
     { min: 5000, max: 5999, type: 'ONCHAIN' },
     { min: 9000, max: 9999, type: 'BALANCE' },
 ];
+/** Special code for UNKNOWN errors */
+const UNKNOWN_ERROR_CODE = 0;
 /**
  * Zod schema for validating ErrorDetails objects.
  *
@@ -3343,6 +3435,7 @@ const ERROR_CODE_RANGES = [
 const errorDetailsSchema = zod.z.object({
     /**
      * Numeric identifier following standardized ranges:
+     * - 0: UNKNOWN - Catch-all for unrecognized errors
      * - 1000-1999: INPUT errors - Parameter validation
      * - 3000-3999: NETWORK errors - Connectivity issues
      * - 4000-4999: RPC errors - Provider issues, gas estimation
@@ -3352,8 +3445,9 @@ const errorDetailsSchema = zod.z.object({
     code: zod.z
         .number()
         .int('Error code must be an integer')
-        .refine((code) => ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
-        message: 'Error code must be in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
+        .refine((code) => code === UNKNOWN_ERROR_CODE ||
+        ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
+        message: 'Error code must be 0 (UNKNOWN) or in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
     }),
     /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
     name: zod.z
@@ -3363,7 +3457,7 @@ const errorDetailsSchema = zod.z.object({
     /** Error category indicating where the error originated */
     type: zod.z.enum(ERROR_TYPE_ARRAY, {
         errorMap: () => ({
-            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK',
+            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK, UNKNOWN',
         }),
     }),
     /** Error handling strategy */
@@ -3564,6 +3658,7 @@ class KitError extends Error {
 /**
  * Standardized error code ranges for consistent categorization:
  *
+ * - 0: UNKNOWN - Catch-all for unrecognized errors
  * - 1000-1999: INPUT errors - Parameter validation, input format errors
  * - 3000-3999: NETWORK errors - Internet connectivity, DNS, connection issues
  * - 4000-4999: RPC errors - Blockchain provider issues, gas estimation, nonce errors
@@ -3654,6 +3749,31 @@ const BalanceError = {
         name: 'BALANCE_INSUFFICIENT_GAS',
         type: 'BALANCE',
     }};
+/**
+ * Standardized error definitions for ONCHAIN type errors.
+ *
+ * ONCHAIN errors occur during transaction execution, simulation,
+ * or interaction with smart contracts on the blockchain.
+ *
+ * @example
+ * ```typescript
+ * import { OnchainError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...OnchainError.SIMULATION_FAILED,
+ *   recoverability: 'FATAL',
+ *   message: 'Simulation failed: ERC20 transfer amount exceeds balance',
+ *   cause: { trace: { reason: 'ERC20: transfer amount exceeds balance' } }
+ * })
+ * ```
+ */
+const OnchainError = {
+    /** Pre-flight transaction simulation failed */
+    SIMULATION_FAILED: {
+        code: 5002,
+        name: 'ONCHAIN_SIMULATION_FAILED',
+        type: 'ONCHAIN',
+    }};
 
 /**
  * Creates error for network type mismatch between source and destination.
@@ -3958,6 +4078,51 @@ function createInsufficientGasError(chain, trace) {
     });
 }
 
+/**
+ * Creates error for transaction simulation failures.
+ *
+ * This error is thrown when a pre-flight transaction simulation fails,
+ * typically due to contract logic that would revert. The error is FATAL
+ * as it indicates the transaction would fail if submitted.
+ *
+ * @param chain - The blockchain network where the simulation failed
+ * @param reason - The reason for simulation failure (e.g., revert message)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
+ * @returns KitError with simulation failure details
+ *
+ * @example
+ * ```typescript
+ * import { createSimulationFailedError } from '@core/errors'
+ *
+ * throw createSimulationFailedError('Ethereum', 'ERC20: insufficient allowance')
+ * // Message: "Simulation failed on Ethereum: ERC20: insufficient allowance"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createSimulationFailedError('Ethereum', 'ERC20: insufficient allowance', {
+ *   rawError: error,
+ *   txHash: '0x1234...',
+ *   gasLimit: '21000',
+ * })
+ * ```
+ */
+function createSimulationFailedError(chain, reason, trace) {
+    return new KitError({
+        ...OnchainError.SIMULATION_FAILED,
+        recoverability: 'FATAL',
+        message: `Simulation failed on ${chain}: ${reason}`,
+        cause: {
+            trace: {
+                ...trace,
+                chain,
+                reason,
+            },
+        },
+    });
+}
+
 /**
  * Type guard to check if an error is a KitError instance.
  *
@@ -5162,6 +5327,68 @@ const fetchAttestationWithoutStatusCheck = async (sourceDomainId, transactionHas
     };
     return await pollApiGet(url, isAttestationResponseWithoutStatusCheck, effectiveConfig);
 };
+/**
+ * Type guard that validates attestation response has expirationBlock === '0'.
+ *
+ * This is used after requestReAttestation() to poll until the attestation
+ * is fully re-processed and has a zero expiration block (never expires).
+ * The expiration block transitions from non-zero to zero when Circle
+ * completes processing the re-attestation request.
+ *
+ * @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
+ * // After requesting re-attestation, use this to validate the response
+ * const response = await pollApiGet(url, isReAttestedAttestationResponse, config)
+ * // response.messages[0].decodedMessage.decodedMessageBody.expirationBlock === '0'
+ * ```
+ *
+ * @internal
+ */
+const isReAttestedAttestationResponse = (obj) => {
+    // First validate the basic structure and completion status
+    // This will throw appropriate errors for invalid structure or incomplete attestation
+    if (!isAttestationResponse(obj)) ;
+    // Check if the first message has expirationBlock === '0'
+    const expirationBlock = obj.messages[0]?.decodedMessage?.decodedMessageBody?.expirationBlock;
+    if (expirationBlock !== '0') {
+        // Re-attestation not yet complete - allow retry via polling
+        throw new Error('Re-attestation not yet complete: waiting for expirationBlock to become 0');
+    }
+    return true;
+};
+/**
+ * Fetches attestation data and polls until expirationBlock === '0'.
+ *
+ * This function is used after calling requestReAttestation() to wait until
+ * the attestation is fully re-processed. The expirationBlock transitions
+ * from non-zero to zero when Circle completes the re-attestation.
+ *
+ * @param sourceDomainId - The CCTP domain ID of the source chain
+ * @param transactionHash - The transaction hash to fetch attestation for
+ * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
+ * @param config - Optional configuration overrides
+ * @returns The re-attested attestation response with expirationBlock === '0'
+ * @throws If the request fails, times out, or expirationBlock never becomes 0
+ *
+ * @example
+ * ```typescript
+ * // After requesting re-attestation
+ * await requestReAttestation(nonce, isTestnet)
+ *
+ * // 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 = { ...DEFAULT_CONFIG, ...config };
+    return await pollApiGet(url, isReAttestedAttestationResponse, effectiveConfig);
+};
 /**
  * Builds the IRIS API URL for re-attestation requests.
  *
@@ -6091,6 +6318,7 @@ function dispatchStepEvent(name, step, provider) {
             });
             break;
         case 'fetchAttestation':
+        case 'reAttest':
             provider.actionDispatcher.dispatch(name, {
                 ...actionValues,
                 method: name,
@@ -6557,6 +6785,7 @@ const CCTPv2StepName = {
     burn: 'burn',
     fetchAttestation: 'fetchAttestation',
     mint: 'mint',
+    reAttest: 'reAttest',
 };
 /**
  * Conditional step transition rules for CCTP bridge flow.
@@ -6664,6 +6893,27 @@ const STEP_TRANSITION_RULES = {
             isActionable: false, // Waiting for pending transaction
         },
     ],
+    // 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,
+        },
+    ],
 };
 /**
  * Analyze bridge steps to determine retry feasibility and continuation point.
@@ -6930,8 +7180,14 @@ function getBurnTxHash(result) {
  * ```
  */
 function getAttestationData(result) {
-    const step = findStepByName(result, CCTPv2StepName.fetchAttestation);
-    return step?.data;
+    // 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;
 }
 
 /**
@@ -7129,7 +7385,7 @@ async function waitForStepToComplete(pendingStep, adapter, chain, context, resul
                 message: 'Cannot fetch attestation: burn transaction hash not found',
             });
         }
-        const sourceAddress = await context.from.getAddress(result.source.chain);
+        const sourceAddress = result.source.address;
         const attestation = await provider.fetchAttestation({
             chain: result.source.chain,
             adapter: context.from,
@@ -7145,6 +7401,63 @@ async function waitForStepToComplete(pendingStep, adapter, chain, context, resul
     return waitForPendingTransaction(pendingStep, adapter, chain);
 }
 
+/**
+ * Executes a re-attestation operation to obtain a fresh attestation for an expired message.
+ *
+ * This function handles the re-attestation step of the CCTP v2 bridge process, where a fresh
+ * attestation is requested from Circle's API when the original attestation has expired.
+ * It first checks if the attestation has already been re-attested before making the API call.
+ *
+ * @param params - The bridge parameters containing source, destination, amount and optional config
+ * @param provider - The CCTP v2 bridging provider
+ * @param burnTxHash - The transaction hash of the original burn operation
+ * @returns Promise resolving to the bridge step with fresh attestation data
+ *
+ * @example
+ * ```typescript
+ * const reAttestStep = await bridgeReAttest(
+ *   { params, provider },
+ *   burnTxHash
+ * )
+ * console.log('Fresh attestation:', reAttestStep.data)
+ * ```
+ */
+async function bridgeReAttest({ params, provider, }, burnTxHash) {
+    const step = {
+        name: 'reAttest',
+        state: 'pending',
+    };
+    try {
+        // Fetch current attestation to check if already re-attested
+        const currentAttestation = await provider.fetchAttestation(params.source, burnTxHash);
+        // Check if already re-attested (expirationBlock === '0' means never expires)
+        const expirationBlock = currentAttestation.decodedMessage.decodedMessageBody.expirationBlock;
+        if (expirationBlock === '0') {
+            // Already re-attested - return current attestation without calling reAttest API
+            return { ...step, state: 'success', data: currentAttestation };
+        }
+        // Not yet re-attested - proceed with re-attestation request
+        const reAttestedAttestation = await provider.reAttest(params.source, burnTxHash);
+        return { ...step, state: 'success', data: reAttestedAttestation };
+    }
+    catch (err) {
+        let errorMessage = 'Unknown re-attestation error';
+        if (err instanceof Error) {
+            errorMessage = err.message;
+        }
+        else if (typeof err === 'string') {
+            errorMessage = err;
+        }
+        return {
+            ...step,
+            state: 'error',
+            error: err,
+            errorMessage,
+            data: undefined,
+        };
+    }
+}
+
 /**
  * Extract context data from completed bridge steps for retry operations.
  *
@@ -7160,6 +7473,116 @@ function populateContext(result) {
         attestationData: getAttestationData(result),
     };
 }
+/**
+ * Handle re-attestation and mint retry when mint fails due to expired attestation.
+ *
+ * @internal
+ */
+async function handleReAttestationAndRetry(params, provider, executor, updateContext, stepContext, result) {
+    const burnTxHash = stepContext?.burnTxHash ?? getBurnTxHash(result);
+    if (burnTxHash === undefined || burnTxHash === '') {
+        handleStepError('mint', new Error('Cannot attempt re-attestation: Burn transaction hash not found in previous steps.'), result);
+        return { success: false };
+    }
+    const reAttestStep = await bridgeReAttest({ params, provider }, burnTxHash);
+    dispatchStepEvent('reAttest', reAttestStep, provider);
+    result.steps.push(reAttestStep);
+    if (reAttestStep.state === 'error') {
+        result.state = 'error';
+        return { success: false };
+    }
+    const freshContext = {
+        ...stepContext,
+        burnTxHash,
+        attestationData: reAttestStep.data,
+    };
+    return executeMintRetry(params, provider, executor, freshContext, updateContext, result);
+}
+/**
+ * Handle step execution error in retry loop.
+ *
+ * Determines if re-attestation should be attempted for mint failures,
+ * or records the error and signals to exit the loop.
+ *
+ * @internal
+ */
+async function handleStepExecutionError(name, error, context) {
+    const { params, provider, executor, updateContext, stepContext, result } = context;
+    const shouldAttemptReAttestation = name === 'mint' && isMintFailureRelatedToAttestation(error);
+    if (!shouldAttemptReAttestation) {
+        handleStepError(name, error, result);
+        return { shouldContinue: false };
+    }
+    const reAttestResult = await handleReAttestationAndRetry(params, provider, executor, updateContext, stepContext, result);
+    if (!reAttestResult.success) {
+        return { shouldContinue: false };
+    }
+    return { shouldContinue: true, stepContext: reAttestResult.stepContext };
+}
+/**
+ * Execute mint retry with fresh attestation context.
+ *
+ * @internal
+ */
+async function executeMintRetry(params, provider, executor, freshContext, updateContext, result) {
+    try {
+        const retryStep = await executor(params, provider, freshContext);
+        if (retryStep.state === 'error') {
+            throw new Error(retryStep.errorMessage ?? 'mint step returned error state');
+        }
+        dispatchStepEvent('mint', retryStep, provider);
+        result.steps.push(retryStep);
+        return { success: true, stepContext: updateContext?.(retryStep) };
+    }
+    catch (retryError) {
+        if (isMintFailureRelatedToAttestation(retryError)) {
+            const kitError = createSimulationFailedError(result.destination.chain.name, getErrorMessage(retryError), { error: retryError });
+            handleStepError('mint', kitError, result);
+        }
+        else {
+            handleStepError('mint', retryError, result);
+        }
+        return { success: false };
+    }
+}
+/**
+ * Execute remaining bridge steps starting from a specific index.
+ *
+ * Handles the step execution loop with error handling and re-attestation support.
+ * Returns true if all steps completed successfully, false if stopped due to error.
+ *
+ * @internal
+ */
+async function executeSteps(params, provider, result, startIndex) {
+    let stepContext = populateContext(result);
+    for (const { name, executor, updateContext } of stepExecutors.slice(startIndex)) {
+        try {
+            const step = await executor(params, provider, stepContext);
+            if (step.state === 'error') {
+                const errorMessage = step.errorMessage ?? `${name} step returned error state`;
+                throw new Error(errorMessage);
+            }
+            stepContext = updateContext?.(step);
+            dispatchStepEvent(name, step, provider);
+            result.steps.push(step);
+        }
+        catch (error) {
+            const errorResult = await handleStepExecutionError(name, error, {
+                params,
+                provider,
+                executor,
+                updateContext,
+                stepContext,
+                result,
+            });
+            if (!errorResult.shouldContinue) {
+                return false;
+            }
+            stepContext = errorResult.stepContext;
+        }
+    }
+    return true;
+}
 /**
  * Retry a failed or incomplete CCTP v2 bridge operation from where it left off.
  *
@@ -7181,15 +7604,12 @@ function populateContext(result) {
 async function retry(result, context, provider) {
     const analysis = analyzeSteps(result);
     if (!analysis.isActionable) {
-        // Terminal completion - bridge already complete, return gracefully
         if (analysis.continuationStep === null && result.state === 'success') {
             return result;
         }
-        // Pending states - wait for the pending operation to complete
         if (hasPendingState(analysis, result)) {
             return handlePendingState(result, context, provider, analysis);
         }
-        // No valid continuation - cannot proceed
         throw new Error('Retry not supported for this result, requires user action');
     }
     if (!isCCTPV2Supported(result.source.chain)) {
@@ -7216,25 +7636,10 @@ async function retry(result, context, provider) {
     if (indexOfSteps === -1) {
         throw new Error(`Continuation step ${analysis.continuationStep ?? ''} not found`);
     }
-    let stepContext = populateContext(result);
-    // Execute each step in sequence
-    for (const { name, executor, updateContext } of stepExecutors.slice(indexOfSteps)) {
-        try {
-            const step = await executor(params, provider, stepContext);
-            if (step.state === 'error') {
-                const errorMessage = step.errorMessage ?? `${name} step returned error state`;
-                throw new Error(errorMessage);
-            }
-            stepContext = updateContext?.(step);
-            dispatchStepEvent(name, step, provider);
-            result.steps.push(step);
-        }
-        catch (error) {
-            handleStepError(name, error, result);
-            return result;
-        }
+    const completed = await executeSteps(params, provider, result, indexOfSteps);
+    if (completed) {
+        result.state = 'success';
     }
-    result.state = 'success';
     return result;
 }
 /**
@@ -7254,7 +7659,7 @@ async function retry(result, context, provider) {
  * @returns Updated bridge result after pending operation completes.
  */
 async function handlePendingState(result, context, provider, analysis) {
-    if (!analysis.continuationStep) {
+    if (analysis.continuationStep === null || analysis.continuationStep === '') {
         // This should not be reachable due to the `hasPendingState` check,
         // but it ensures type safety for `continuationStep`.
         throw new KitError({
@@ -7888,8 +8293,10 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             }
             // Step 2: Request re-attestation
             await requestReAttestation(nonce, source.chain.isTestnet, effectiveConfig);
-            // Step 3: Poll for fresh attestation
-            const response = await fetchAttestation(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
+            // Step 3: Poll for fresh attestation until expirationBlock === '0'
+            // The expiration block transitions from non-zero to zero when Circle
+            // completes processing the re-attestation request.
+            const response = await fetchReAttestedAttestation(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
             const message = response.messages[0];
             if (!message) {
                 throw new Error('Failed to re-attest: No attestation found after re-attestation request');

package/index.d.ts

@@ -435,6 +435,8 @@ declare enum Blockchain {
     Ink_Testnet = "Ink_Testnet",
     Linea = "Linea",
     Linea_Sepolia = "Linea_Sepolia",
+    Monad = "Monad",
+    Monad_Testnet = "Monad_Testnet",
     NEAR = "NEAR",
     NEAR_Testnet = "NEAR_Testnet",
     Noble = "Noble",
@@ -3407,6 +3409,16 @@ interface CCTPV2Actions {
         method: 'mint';
         values: BridgeStep;
     };
+    /**
+     * Re-attestation action for CCTP v2 transfers.
+     * Used to request a fresh attestation when the original has expired.
+     */
+    reAttest: {
+        protocol: 'cctp';
+        version: 'v2';
+        method: 'reAttest';
+        values: BridgeFetchAttestationStep;
+    };
 }
 /**
  * CCTPv2 bridging provider interface.

package/index.mjs

@@ -75,6 +75,8 @@ var Blockchain;
     Blockchain["Ink_Testnet"] = "Ink_Testnet";
     Blockchain["Linea"] = "Linea";
     Blockchain["Linea_Sepolia"] = "Linea_Sepolia";
+    Blockchain["Monad"] = "Monad";
+    Blockchain["Monad_Testnet"] = "Monad_Testnet";
     Blockchain["NEAR"] = "NEAR";
     Blockchain["NEAR_Testnet"] = "NEAR_Testnet";
     Blockchain["Noble"] = "Noble";
@@ -166,6 +168,7 @@ var BridgeChain;
     BridgeChain["HyperEVM"] = "HyperEVM";
     BridgeChain["Ink"] = "Ink";
     BridgeChain["Linea"] = "Linea";
+    BridgeChain["Monad"] = "Monad";
     BridgeChain["Optimism"] = "Optimism";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
@@ -185,6 +188,7 @@ var BridgeChain;
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
     BridgeChain["Ink_Testnet"] = "Ink_Testnet";
     BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
+    BridgeChain["Monad_Testnet"] = "Monad_Testnet";
     BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
     BridgeChain["Plume_Testnet"] = "Plume_Testnet";
     BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
@@ -1171,6 +1175,86 @@ const LineaSepolia = defineChain({
     },
 });
 
+/**
+ * Monad Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Monad blockchain.
+ * Monad is a high-performance EVM-compatible Layer-1 blockchain featuring
+ * over 10,000 TPS, sub-second finality, and near-zero gas fees.
+ */
+const Monad = defineChain({
+    type: 'evm',
+    chain: Blockchain.Monad,
+    name: 'Monad',
+    title: 'Monad Mainnet',
+    nativeCurrency: {
+        name: 'Monad',
+        symbol: 'MON',
+        decimals: 18,
+    },
+    chainId: 143,
+    isTestnet: false,
+    explorerUrl: 'https://monadscan.com/tx/{hash}',
+    rpcEndpoints: ['https://rpc.monad.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
+    cctp: {
+        domain: 15,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Monad Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Monad blockchain.
+ * Monad is a high-performance EVM-compatible Layer-1 blockchain featuring
+ * over 10,000 TPS, sub-second finality, and near-zero gas fees.
+ */
+const MonadTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Monad_Testnet,
+    name: 'Monad Testnet',
+    title: 'Monad Testnet',
+    nativeCurrency: {
+        name: 'Monad',
+        symbol: 'MON',
+        decimals: 18,
+    },
+    chainId: 10143,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.monadscan.com/tx/{hash}',
+    rpcEndpoints: ['https://testnet-rpc.monad.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
+    cctp: {
+        domain: 15,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * NEAR Protocol Mainnet chain definition
  * @remarks
@@ -2255,6 +2339,8 @@ var Chains = /*#__PURE__*/Object.freeze({
     InkTestnet: InkTestnet,
     Linea: Linea,
     LineaSepolia: LineaSepolia,
+    Monad: Monad,
+    MonadTestnet: MonadTestnet,
     NEAR: NEAR,
     NEARTestnet: NEARTestnet,
     Noble: Noble,
@@ -3278,6 +3364,8 @@ const ERROR_TYPES = {
     RPC: 'RPC',
     /** Internet connectivity, DNS resolution, connection issues */
     NETWORK: 'NETWORK',
+    /** Catch-all for unrecognized errors (code 0) */
+    UNKNOWN: 'UNKNOWN',
 };
 /**
  * Array of valid error type values for validation.
@@ -3291,6 +3379,8 @@ const ERROR_TYPE_ARRAY = [...ERROR_TYPE_VALUES];
 /**
  * Error code ranges for validation.
  * Single source of truth for valid error code ranges.
+ *
+ * Note: Code 0 is special - it's the UNKNOWN catch-all error.
  */
 const ERROR_CODE_RANGES = [
     { min: 1000, max: 1999, type: 'INPUT' },
@@ -3299,6 +3389,8 @@ const ERROR_CODE_RANGES = [
     { min: 5000, max: 5999, type: 'ONCHAIN' },
     { min: 9000, max: 9999, type: 'BALANCE' },
 ];
+/** Special code for UNKNOWN errors */
+const UNKNOWN_ERROR_CODE = 0;
 /**
  * Zod schema for validating ErrorDetails objects.
  *
@@ -3337,6 +3429,7 @@ const ERROR_CODE_RANGES = [
 const errorDetailsSchema = z.object({
     /**
      * Numeric identifier following standardized ranges:
+     * - 0: UNKNOWN - Catch-all for unrecognized errors
      * - 1000-1999: INPUT errors - Parameter validation
      * - 3000-3999: NETWORK errors - Connectivity issues
      * - 4000-4999: RPC errors - Provider issues, gas estimation
@@ -3346,8 +3439,9 @@ const errorDetailsSchema = z.object({
     code: z
         .number()
         .int('Error code must be an integer')
-        .refine((code) => ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
-        message: 'Error code must be in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
+        .refine((code) => code === UNKNOWN_ERROR_CODE ||
+        ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
+        message: 'Error code must be 0 (UNKNOWN) or in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
     }),
     /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
     name: z
@@ -3357,7 +3451,7 @@ const errorDetailsSchema = z.object({
     /** Error category indicating where the error originated */
     type: z.enum(ERROR_TYPE_ARRAY, {
         errorMap: () => ({
-            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK',
+            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK, UNKNOWN',
         }),
     }),
     /** Error handling strategy */
@@ -3558,6 +3652,7 @@ class KitError extends Error {
 /**
  * Standardized error code ranges for consistent categorization:
  *
+ * - 0: UNKNOWN - Catch-all for unrecognized errors
  * - 1000-1999: INPUT errors - Parameter validation, input format errors
  * - 3000-3999: NETWORK errors - Internet connectivity, DNS, connection issues
  * - 4000-4999: RPC errors - Blockchain provider issues, gas estimation, nonce errors
@@ -3648,6 +3743,31 @@ const BalanceError = {
         name: 'BALANCE_INSUFFICIENT_GAS',
         type: 'BALANCE',
     }};
+/**
+ * Standardized error definitions for ONCHAIN type errors.
+ *
+ * ONCHAIN errors occur during transaction execution, simulation,
+ * or interaction with smart contracts on the blockchain.
+ *
+ * @example
+ * ```typescript
+ * import { OnchainError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...OnchainError.SIMULATION_FAILED,
+ *   recoverability: 'FATAL',
+ *   message: 'Simulation failed: ERC20 transfer amount exceeds balance',
+ *   cause: { trace: { reason: 'ERC20: transfer amount exceeds balance' } }
+ * })
+ * ```
+ */
+const OnchainError = {
+    /** Pre-flight transaction simulation failed */
+    SIMULATION_FAILED: {
+        code: 5002,
+        name: 'ONCHAIN_SIMULATION_FAILED',
+        type: 'ONCHAIN',
+    }};
 
 /**
  * Creates error for network type mismatch between source and destination.
@@ -3952,6 +4072,51 @@ function createInsufficientGasError(chain, trace) {
     });
 }
 
+/**
+ * Creates error for transaction simulation failures.
+ *
+ * This error is thrown when a pre-flight transaction simulation fails,
+ * typically due to contract logic that would revert. The error is FATAL
+ * as it indicates the transaction would fail if submitted.
+ *
+ * @param chain - The blockchain network where the simulation failed
+ * @param reason - The reason for simulation failure (e.g., revert message)
+ * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
+ * @returns KitError with simulation failure details
+ *
+ * @example
+ * ```typescript
+ * import { createSimulationFailedError } from '@core/errors'
+ *
+ * throw createSimulationFailedError('Ethereum', 'ERC20: insufficient allowance')
+ * // Message: "Simulation failed on Ethereum: ERC20: insufficient allowance"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With trace context for debugging
+ * throw createSimulationFailedError('Ethereum', 'ERC20: insufficient allowance', {
+ *   rawError: error,
+ *   txHash: '0x1234...',
+ *   gasLimit: '21000',
+ * })
+ * ```
+ */
+function createSimulationFailedError(chain, reason, trace) {
+    return new KitError({
+        ...OnchainError.SIMULATION_FAILED,
+        recoverability: 'FATAL',
+        message: `Simulation failed on ${chain}: ${reason}`,
+        cause: {
+            trace: {
+                ...trace,
+                chain,
+                reason,
+            },
+        },
+    });
+}
+
 /**
  * Type guard to check if an error is a KitError instance.
  *
@@ -5156,6 +5321,68 @@ const fetchAttestationWithoutStatusCheck = async (sourceDomainId, transactionHas
     };
     return await pollApiGet(url, isAttestationResponseWithoutStatusCheck, effectiveConfig);
 };
+/**
+ * Type guard that validates attestation response has expirationBlock === '0'.
+ *
+ * This is used after requestReAttestation() to poll until the attestation
+ * is fully re-processed and has a zero expiration block (never expires).
+ * The expiration block transitions from non-zero to zero when Circle
+ * completes processing the re-attestation request.
+ *
+ * @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
+ * // After requesting re-attestation, use this to validate the response
+ * const response = await pollApiGet(url, isReAttestedAttestationResponse, config)
+ * // response.messages[0].decodedMessage.decodedMessageBody.expirationBlock === '0'
+ * ```
+ *
+ * @internal
+ */
+const isReAttestedAttestationResponse = (obj) => {
+    // First validate the basic structure and completion status
+    // This will throw appropriate errors for invalid structure or incomplete attestation
+    if (!isAttestationResponse(obj)) ;
+    // Check if the first message has expirationBlock === '0'
+    const expirationBlock = obj.messages[0]?.decodedMessage?.decodedMessageBody?.expirationBlock;
+    if (expirationBlock !== '0') {
+        // Re-attestation not yet complete - allow retry via polling
+        throw new Error('Re-attestation not yet complete: waiting for expirationBlock to become 0');
+    }
+    return true;
+};
+/**
+ * Fetches attestation data and polls until expirationBlock === '0'.
+ *
+ * This function is used after calling requestReAttestation() to wait until
+ * the attestation is fully re-processed. The expirationBlock transitions
+ * from non-zero to zero when Circle completes the re-attestation.
+ *
+ * @param sourceDomainId - The CCTP domain ID of the source chain
+ * @param transactionHash - The transaction hash to fetch attestation for
+ * @param isTestnet - Whether this is for a testnet chain (true) or mainnet chain (false)
+ * @param config - Optional configuration overrides
+ * @returns The re-attested attestation response with expirationBlock === '0'
+ * @throws If the request fails, times out, or expirationBlock never becomes 0
+ *
+ * @example
+ * ```typescript
+ * // After requesting re-attestation
+ * await requestReAttestation(nonce, isTestnet)
+ *
+ * // 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 = { ...DEFAULT_CONFIG, ...config };
+    return await pollApiGet(url, isReAttestedAttestationResponse, effectiveConfig);
+};
 /**
  * Builds the IRIS API URL for re-attestation requests.
  *
@@ -6085,6 +6312,7 @@ function dispatchStepEvent(name, step, provider) {
             });
             break;
         case 'fetchAttestation':
+        case 'reAttest':
             provider.actionDispatcher.dispatch(name, {
                 ...actionValues,
                 method: name,
@@ -6551,6 +6779,7 @@ const CCTPv2StepName = {
     burn: 'burn',
     fetchAttestation: 'fetchAttestation',
     mint: 'mint',
+    reAttest: 'reAttest',
 };
 /**
  * Conditional step transition rules for CCTP bridge flow.
@@ -6658,6 +6887,27 @@ const STEP_TRANSITION_RULES = {
             isActionable: false, // Waiting for pending transaction
         },
     ],
+    // 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,
+        },
+    ],
 };
 /**
  * Analyze bridge steps to determine retry feasibility and continuation point.
@@ -6924,8 +7174,14 @@ function getBurnTxHash(result) {
  * ```
  */
 function getAttestationData(result) {
-    const step = findStepByName(result, CCTPv2StepName.fetchAttestation);
-    return step?.data;
+    // 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;
 }
 
 /**
@@ -7123,7 +7379,7 @@ async function waitForStepToComplete(pendingStep, adapter, chain, context, resul
                 message: 'Cannot fetch attestation: burn transaction hash not found',
             });
         }
-        const sourceAddress = await context.from.getAddress(result.source.chain);
+        const sourceAddress = result.source.address;
         const attestation = await provider.fetchAttestation({
             chain: result.source.chain,
             adapter: context.from,
@@ -7139,6 +7395,63 @@ async function waitForStepToComplete(pendingStep, adapter, chain, context, resul
     return waitForPendingTransaction(pendingStep, adapter, chain);
 }
 
+/**
+ * Executes a re-attestation operation to obtain a fresh attestation for an expired message.
+ *
+ * This function handles the re-attestation step of the CCTP v2 bridge process, where a fresh
+ * attestation is requested from Circle's API when the original attestation has expired.
+ * It first checks if the attestation has already been re-attested before making the API call.
+ *
+ * @param params - The bridge parameters containing source, destination, amount and optional config
+ * @param provider - The CCTP v2 bridging provider
+ * @param burnTxHash - The transaction hash of the original burn operation
+ * @returns Promise resolving to the bridge step with fresh attestation data
+ *
+ * @example
+ * ```typescript
+ * const reAttestStep = await bridgeReAttest(
+ *   { params, provider },
+ *   burnTxHash
+ * )
+ * console.log('Fresh attestation:', reAttestStep.data)
+ * ```
+ */
+async function bridgeReAttest({ params, provider, }, burnTxHash) {
+    const step = {
+        name: 'reAttest',
+        state: 'pending',
+    };
+    try {
+        // Fetch current attestation to check if already re-attested
+        const currentAttestation = await provider.fetchAttestation(params.source, burnTxHash);
+        // Check if already re-attested (expirationBlock === '0' means never expires)
+        const expirationBlock = currentAttestation.decodedMessage.decodedMessageBody.expirationBlock;
+        if (expirationBlock === '0') {
+            // Already re-attested - return current attestation without calling reAttest API
+            return { ...step, state: 'success', data: currentAttestation };
+        }
+        // Not yet re-attested - proceed with re-attestation request
+        const reAttestedAttestation = await provider.reAttest(params.source, burnTxHash);
+        return { ...step, state: 'success', data: reAttestedAttestation };
+    }
+    catch (err) {
+        let errorMessage = 'Unknown re-attestation error';
+        if (err instanceof Error) {
+            errorMessage = err.message;
+        }
+        else if (typeof err === 'string') {
+            errorMessage = err;
+        }
+        return {
+            ...step,
+            state: 'error',
+            error: err,
+            errorMessage,
+            data: undefined,
+        };
+    }
+}
+
 /**
  * Extract context data from completed bridge steps for retry operations.
  *
@@ -7154,6 +7467,116 @@ function populateContext(result) {
         attestationData: getAttestationData(result),
     };
 }
+/**
+ * Handle re-attestation and mint retry when mint fails due to expired attestation.
+ *
+ * @internal
+ */
+async function handleReAttestationAndRetry(params, provider, executor, updateContext, stepContext, result) {
+    const burnTxHash = stepContext?.burnTxHash ?? getBurnTxHash(result);
+    if (burnTxHash === undefined || burnTxHash === '') {
+        handleStepError('mint', new Error('Cannot attempt re-attestation: Burn transaction hash not found in previous steps.'), result);
+        return { success: false };
+    }
+    const reAttestStep = await bridgeReAttest({ params, provider }, burnTxHash);
+    dispatchStepEvent('reAttest', reAttestStep, provider);
+    result.steps.push(reAttestStep);
+    if (reAttestStep.state === 'error') {
+        result.state = 'error';
+        return { success: false };
+    }
+    const freshContext = {
+        ...stepContext,
+        burnTxHash,
+        attestationData: reAttestStep.data,
+    };
+    return executeMintRetry(params, provider, executor, freshContext, updateContext, result);
+}
+/**
+ * Handle step execution error in retry loop.
+ *
+ * Determines if re-attestation should be attempted for mint failures,
+ * or records the error and signals to exit the loop.
+ *
+ * @internal
+ */
+async function handleStepExecutionError(name, error, context) {
+    const { params, provider, executor, updateContext, stepContext, result } = context;
+    const shouldAttemptReAttestation = name === 'mint' && isMintFailureRelatedToAttestation(error);
+    if (!shouldAttemptReAttestation) {
+        handleStepError(name, error, result);
+        return { shouldContinue: false };
+    }
+    const reAttestResult = await handleReAttestationAndRetry(params, provider, executor, updateContext, stepContext, result);
+    if (!reAttestResult.success) {
+        return { shouldContinue: false };
+    }
+    return { shouldContinue: true, stepContext: reAttestResult.stepContext };
+}
+/**
+ * Execute mint retry with fresh attestation context.
+ *
+ * @internal
+ */
+async function executeMintRetry(params, provider, executor, freshContext, updateContext, result) {
+    try {
+        const retryStep = await executor(params, provider, freshContext);
+        if (retryStep.state === 'error') {
+            throw new Error(retryStep.errorMessage ?? 'mint step returned error state');
+        }
+        dispatchStepEvent('mint', retryStep, provider);
+        result.steps.push(retryStep);
+        return { success: true, stepContext: updateContext?.(retryStep) };
+    }
+    catch (retryError) {
+        if (isMintFailureRelatedToAttestation(retryError)) {
+            const kitError = createSimulationFailedError(result.destination.chain.name, getErrorMessage(retryError), { error: retryError });
+            handleStepError('mint', kitError, result);
+        }
+        else {
+            handleStepError('mint', retryError, result);
+        }
+        return { success: false };
+    }
+}
+/**
+ * Execute remaining bridge steps starting from a specific index.
+ *
+ * Handles the step execution loop with error handling and re-attestation support.
+ * Returns true if all steps completed successfully, false if stopped due to error.
+ *
+ * @internal
+ */
+async function executeSteps(params, provider, result, startIndex) {
+    let stepContext = populateContext(result);
+    for (const { name, executor, updateContext } of stepExecutors.slice(startIndex)) {
+        try {
+            const step = await executor(params, provider, stepContext);
+            if (step.state === 'error') {
+                const errorMessage = step.errorMessage ?? `${name} step returned error state`;
+                throw new Error(errorMessage);
+            }
+            stepContext = updateContext?.(step);
+            dispatchStepEvent(name, step, provider);
+            result.steps.push(step);
+        }
+        catch (error) {
+            const errorResult = await handleStepExecutionError(name, error, {
+                params,
+                provider,
+                executor,
+                updateContext,
+                stepContext,
+                result,
+            });
+            if (!errorResult.shouldContinue) {
+                return false;
+            }
+            stepContext = errorResult.stepContext;
+        }
+    }
+    return true;
+}
 /**
  * Retry a failed or incomplete CCTP v2 bridge operation from where it left off.
  *
@@ -7175,15 +7598,12 @@ function populateContext(result) {
 async function retry(result, context, provider) {
     const analysis = analyzeSteps(result);
     if (!analysis.isActionable) {
-        // Terminal completion - bridge already complete, return gracefully
         if (analysis.continuationStep === null && result.state === 'success') {
             return result;
         }
-        // Pending states - wait for the pending operation to complete
         if (hasPendingState(analysis, result)) {
             return handlePendingState(result, context, provider, analysis);
         }
-        // No valid continuation - cannot proceed
         throw new Error('Retry not supported for this result, requires user action');
     }
     if (!isCCTPV2Supported(result.source.chain)) {
@@ -7210,25 +7630,10 @@ async function retry(result, context, provider) {
     if (indexOfSteps === -1) {
         throw new Error(`Continuation step ${analysis.continuationStep ?? ''} not found`);
     }
-    let stepContext = populateContext(result);
-    // Execute each step in sequence
-    for (const { name, executor, updateContext } of stepExecutors.slice(indexOfSteps)) {
-        try {
-            const step = await executor(params, provider, stepContext);
-            if (step.state === 'error') {
-                const errorMessage = step.errorMessage ?? `${name} step returned error state`;
-                throw new Error(errorMessage);
-            }
-            stepContext = updateContext?.(step);
-            dispatchStepEvent(name, step, provider);
-            result.steps.push(step);
-        }
-        catch (error) {
-            handleStepError(name, error, result);
-            return result;
-        }
+    const completed = await executeSteps(params, provider, result, indexOfSteps);
+    if (completed) {
+        result.state = 'success';
     }
-    result.state = 'success';
     return result;
 }
 /**
@@ -7248,7 +7653,7 @@ async function retry(result, context, provider) {
  * @returns Updated bridge result after pending operation completes.
  */
 async function handlePendingState(result, context, provider, analysis) {
-    if (!analysis.continuationStep) {
+    if (analysis.continuationStep === null || analysis.continuationStep === '') {
         // This should not be reachable due to the `hasPendingState` check,
         // but it ensures type safety for `continuationStep`.
         throw new KitError({
@@ -7882,8 +8287,10 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             }
             // Step 2: Request re-attestation
             await requestReAttestation(nonce, source.chain.isTestnet, effectiveConfig);
-            // Step 3: Poll for fresh attestation
-            const response = await fetchAttestation(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
+            // Step 3: Poll for fresh attestation until expirationBlock === '0'
+            // The expiration block transitions from non-zero to zero when Circle
+            // completes processing the re-attestation request.
+            const response = await fetchReAttestedAttestation(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
             const message = response.messages[0];
             if (!message) {
                 throw new Error('Failed to re-attest: No attestation found after re-attestation request');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/provider-cctp-v2",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Circle's official Cross-Chain Transfer Protocol v2 provider for native USDC bridging",
   "keywords": [
     "circle",