@circle-fin/provider-cctp-v2 1.0.5 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @circle-fin/provider-cctp-v2
 
+## 1.1.0
+
+### Minor Changes
+
+- Add `reAttest` method to `CCTPV2BridgingProvider` for handling expired attestations.
+
+  When a CCTP v2 attestation expires before the mint transaction can be completed, users can now call `reAttest()` to request a fresh attestation using the original burn transaction hash.
+
+- **Enhanced bridge estimate response**: `EstimateResult` now includes `token`, `amount`, `source`, `destination` fields to provide complete transfer information alongside cost estimates.
+
+### Patch Changes
+
+- Fix fast burn fee calculation to handle decimal basis points from IRIS API
+
+  The IRIS API returns `minimumFee` as decimal basis points (e.g., `"1.3"` for 1.3 bps), but the code was attempting to convert this directly to `BigInt`, which fails for non-integer values. This caused `"Max fee must be less than amount"` errors during FAST transfers.
+
 ## 1.0.5
 
 ### Patch Changes

package/index.cjs

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -3020,7 +3020,9 @@ const makeApiRequest = async (url, method, isValidType, config, body) => {
             signal: controller.signal,
         };
         // Add body for methods that support it
-        if (body !== undefined && ['POST', 'PUT', 'PATCH'].includes(method)) ;
+        if (body !== undefined && ['POST', 'PUT', 'PATCH'].includes(method)) {
+            requestInit.body = JSON.stringify(body);
+        }
         const response = await fetch(url, requestInit);
         clearTimeout(timeoutId);
         if (!response.ok) {
@@ -3198,6 +3200,30 @@ const pollApiWithValidation = async (url, method, isValidType, config = {}, body
 const pollApiGet = async (url, isValidType, config) => {
     return pollApiWithValidation(url, 'GET', isValidType, config);
 };
+/**
+ * Convenience function for making POST requests with validation.
+ *
+ * @typeParam TResponseType - The expected response type after validation
+ * @typeParam TBody - The type of the request body
+ * @param url - The API endpoint URL
+ * @param body - The request body
+ * @param isValidType - Type guard function to validate the response
+ * @param config - Optional configuration overrides
+ * @returns Promise resolving to the validated response
+ *
+ * @example
+ * ```typescript
+ * const result = await pollApiPost(
+ *   'https://api.example.com/submit',
+ *   { name: 'John', email: 'john@example.com' },
+ *   isSubmissionResponse,
+ *   { maxRetries: 3 }
+ * )
+ * ```
+ */
+const pollApiPost = async (url, body, isValidType, config) => {
+    return pollApiWithValidation(url, 'POST', isValidType, config, body);
+};
 
 /**
  * Valid recoverability values for error handling strategies.
@@ -3405,6 +3431,24 @@ function validateErrorDetails(details) {
  * stays within KitError's constraints.
  */
 const MAX_MESSAGE_LENGTH = 950;
+/**
+ * Standard error message for invalid amount format.
+ *
+ * The SDK enforces strict dot-decimal notation for amount values. This constant
+ * provides a consistent error message when users provide amounts with:
+ * - Comma decimals (e.g., "1,5")
+ * - Thousand separators (e.g., "1,000.50")
+ * - Non-numeric characters
+ * - Invalid format
+ */
+const AMOUNT_FORMAT_ERROR_MESSAGE = 'Amount must be a numeric string with dot (.) as decimal separator (e.g., "10.5", "100"), with no thousand separators or comma decimals';
+/**
+ * Error message for invalid maxFee format.
+ *
+ * Used when validating the maxFee configuration parameter. The maxFee can be zero
+ * or positive and must follow strict dot-decimal notation.
+ */
+const MAX_FEE_FORMAT_ERROR_MESSAGE = 'maxFee must be a numeric string with dot (.) as decimal separator (e.g., "1", "0.5", ".5", "1.5"), with no thousand separators or comma decimals';
 
 /**
  * Structured error class for Stablecoin Kit operations.
@@ -4411,41 +4455,46 @@ var TransferSpeed;
  * - regexMessage: error message when the basic numeric format fails.
  * - maxDecimals: maximum number of decimal places allowed (e.g., 6 for USDC).
  */
-const createDecimalStringValidator = (options) => (schema) => schema
-    .regex(/^-?(?:\d+(?:\.\d+)?|\.\d+)$/, options.regexMessage)
-    .superRefine((val, ctx) => {
-    const amount = Number.parseFloat(val);
-    if (Number.isNaN(amount)) {
-        ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
-            message: options.regexMessage,
-        });
-        return;
-    }
-    // Check decimal precision if maxDecimals is specified
-    if (options.maxDecimals !== undefined) {
-        const decimalPart = val.split('.')[1];
-        if (decimalPart && decimalPart.length > options.maxDecimals) {
+const createDecimalStringValidator = (options) => (schema) => {
+    // Capitalize first letter of attribute name for error messages
+    const capitalizedAttributeName = options.attributeName.charAt(0).toUpperCase() +
+        options.attributeName.slice(1);
+    return schema
+        .regex(/^-?(?:\d+(?:\.\d+)?|\.\d+)$/, options.regexMessage)
+        .superRefine((val, ctx) => {
+        const amount = Number.parseFloat(val);
+        if (Number.isNaN(amount)) {
             ctx.addIssue({
                 code: zod.z.ZodIssueCode.custom,
-                message: `Maximum supported decimal places: ${options.maxDecimals.toString()}`,
+                message: options.regexMessage,
             });
             return;
         }
-    }
-    if (options.allowZero && amount < 0) {
-        ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
-            message: `${options.attributeName} must be non-negative`,
-        });
-    }
-    else if (!options.allowZero && amount <= 0) {
-        ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
-            message: `${options.attributeName} must be greater than 0`,
-        });
-    }
-});
+        // Check decimal precision if maxDecimals is specified
+        if (options.maxDecimals !== undefined) {
+            const decimalPart = val.split('.')[1];
+            if (decimalPart && decimalPart.length > options.maxDecimals) {
+                ctx.addIssue({
+                    code: zod.z.ZodIssueCode.custom,
+                    message: `Maximum supported decimal places: ${options.maxDecimals.toString()}`,
+                });
+                return;
+            }
+        }
+        if (options.allowZero && amount < 0) {
+            ctx.addIssue({
+                code: zod.z.ZodIssueCode.custom,
+                message: `${capitalizedAttributeName} must be non-negative`,
+            });
+        }
+        else if (!options.allowZero && amount <= 0) {
+            ctx.addIssue({
+                code: zod.z.ZodIssueCode.custom,
+                message: `${capitalizedAttributeName} must be greater than 0`,
+            });
+        }
+    });
+};
 /**
  * Schema for validating chain definitions.
  * This ensures the basic structure of a chain definition is valid.
@@ -4605,7 +4654,7 @@ const bridgeParamsSchema = zod.z.object({
         .min(1, 'Required')
         .pipe(createDecimalStringValidator({
         allowZero: false,
-        regexMessage: 'Amount must be a numeric string with dot (.) as decimal separator (e.g., "0.1", ".1", "10.5", "1000.50"), with no thousand separators or comma decimals.',
+        regexMessage: AMOUNT_FORMAT_ERROR_MESSAGE,
         attributeName: 'amount',
         maxDecimals: 6,
     })(zod.z.string())),
@@ -4618,7 +4667,7 @@ const bridgeParamsSchema = zod.z.object({
             .string()
             .pipe(createDecimalStringValidator({
             allowZero: true,
-            regexMessage: 'maxFee must be a numeric string with dot (.) as decimal separator (e.g., "1", "0.5", ".5", "1.5"), with no thousand separators or comma decimals.',
+            regexMessage: MAX_FEE_FORMAT_ERROR_MESSAGE,
             attributeName: 'maxFee',
             maxDecimals: 6,
         })(zod.z.string()))
@@ -4627,6 +4676,19 @@ const bridgeParamsSchema = zod.z.object({
     }),
 });
 
+/**
+ * Base URL for Circle's IRIS API (mainnet/production).
+ *
+ * The IRIS API provides attestation services for CCTP cross-chain transfers.
+ */
+const IRIS_API_BASE_URL = 'https://iris-api.circle.com';
+/**
+ * Base URL for Circle's IRIS API (testnet/sandbox).
+ *
+ * Used for development and testing on testnet chains.
+ */
+const IRIS_API_SANDBOX_BASE_URL = 'https://iris-api-sandbox.circle.com';
+
 /**
  * Type guard to validate the API response structure.
  *
@@ -4675,9 +4737,7 @@ const isFastBurnFeeResponse = (data) => {
  * @returns The complete API URL
  */
 function buildFastBurnFeeUrl(sourceDomain, destinationDomain, isTestnet) {
-    const baseUrl = isTestnet
-        ? 'https://iris-api-sandbox.circle.com'
-        : 'https://iris-api.circle.com';
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
     return `${baseUrl}/v2/burn/USDC/fees/${sourceDomain.toString()}/${destinationDomain.toString()}`;
 }
 const FAST_TIER_FINALITY_THRESHOLD = 1000;
@@ -4693,15 +4753,24 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
  * - Retry delays: 9 × 200 ms = 1 800 ms
  * - Total max time: 2 000 ms + 1 800 ms = 3 800 ms
  *
+ * @remarks
+ * The API returns basis points as a decimal (e.g., "1.3" for 1.3 bps = 0.013%).
+ * This function scales the value by 100 to preserve 2 decimal places of precision.
+ * Callers must divide by 1,000,000 (instead of 10,000) when calculating fees.
+ *
  * @param sourceDomain - The source domain
  * @param destinationDomain - The destination domain
  * @param isTestnet - Whether the request is for a testnet chain
- * @returns The minimum fee for a USDC fast burn operation
+ * @returns The minimum fee in scaled basis points (bps × 100)
  * @throws Error if the input domains are invalid, the API request fails, returns invalid data, or network errors occur
  * @example
  * ```typescript
- * const minimumFee = await fetchUsdcFastBurnFee(0, 6, false) // Ethereum -> Base
- * console.log(minimumFee) // 1000n
+ * const scaledBps = await fetchUsdcFastBurnFee(0, 6, false) // Ethereum -> Base
+ * console.log(scaledBps) // 130n (representing 1.3 bps)
+ *
+ * // To calculate fee for an amount:
+ * const amount = 1_000_000n // 1 USDC
+ * const fee = (scaledBps * amount) / 1_000_000n // 130n (0.00013 USDC)
  * ```
  */
 async function fetchUsdcFastBurnFee(sourceDomain, destinationDomain, isTestnet) {
@@ -4727,14 +4796,16 @@ async function fetchUsdcFastBurnFee(sourceDomain, destinationDomain, isTestnet)
     if (!fastTier) {
         throw new Error(`No fast tier (finalityThreshold: ${FAST_TIER_FINALITY_THRESHOLD.toString()}) available in API response`);
     }
-    // Convert minimumFee to bigint
-    let minimumFee;
-    try {
-        minimumFee = BigInt(fastTier.minimumFee);
-    }
-    catch {
-        throw new Error(`Invalid minimumFee value: cannot convert "${String(fastTier.minimumFee)}" to bigint`);
+    // Convert minimumFee to scaled basis points (bigint)
+    // The API returns basis points as a decimal (e.g., "1.3" for 1.3 bps = 0.013%).
+    // We scale by 100 to preserve 2 decimal places of precision.
+    // The caller (getMaxFee) must divide by 1,000,000 instead of 10,000.
+    const feeValue = Number.parseFloat(String(fastTier.minimumFee));
+    if (Number.isNaN(feeValue) || !Number.isFinite(feeValue)) {
+        throw new Error(`Invalid minimumFee value: cannot parse "${String(fastTier.minimumFee)}" as a number`);
     }
+    // Scale by 100 and round to get integer representation
+    const minimumFee = BigInt(Math.round(feeValue * 100));
     // Validate that minimumFee is non-negative
     if (minimumFee < 0n) {
         throw new Error('Invalid minimumFee: value must be non-negative');
@@ -4909,9 +4980,7 @@ const isAttestationResponse = (obj) => {
  * ```
  */
 const buildIrisUrl = (sourceDomainId, transactionHash, isTestnet) => {
-    const baseUrl = isTestnet
-        ? 'https://iris-api-sandbox.circle.com'
-        : 'https://iris-api.circle.com';
+    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();
@@ -4956,6 +5025,133 @@ const fetchAttestation = async (sourceDomainId, transactionHash, isTestnet, conf
     const effectiveConfig = { ...DEFAULT_CONFIG, ...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 = {
+        ...DEFAULT_CONFIG,
+        maxRetries: 3,
+        ...config,
+    };
+    return await pollApiGet(url, isAttestationResponseWithoutStatusCheck, 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
+ * // Mainnet URL
+ * const mainnetUrl = buildReAttestUrl('0xabc', false)
+ * // => 'https://iris-api.circle.com/v2/reattest/0xabc'
+ *
+ * // Testnet URL
+ * const testnetUrl = buildReAttestUrl('0xabc', true)
+ * // => 'https://iris-api-sandbox.circle.com/v2/reattest/0xabc'
+ * ```
+ */
+const buildReAttestUrl = (nonce, isTestnet) => {
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const url = new URL(`${baseUrl}/v2/reattest/${nonce}`);
+    return url.toString();
+};
+/**
+ * Type guard that validates the re-attestation API response structure.
+ *
+ * @param obj - The value to check, typically a parsed JSON response
+ * @returns True if the object matches the ReAttestationResponse shape
+ * @throws {Error} With "Invalid re-attestation response structure" if structure is invalid
+ * @internal
+ */
+const isReAttestationResponse = (obj) => {
+    if (typeof obj !== 'object' ||
+        obj === null ||
+        !('message' in obj) ||
+        !('nonce' in obj) ||
+        typeof obj.message !== 'string' ||
+        typeof obj.nonce !== 'string') {
+        throw new Error('Invalid re-attestation response structure');
+    }
+    return true;
+};
+/**
+ * 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.
+ *
+ * @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
+ * // Request re-attestation for an expired nonce
+ * const response = await requestReAttestation('0xabc', true)
+ * console.log(response.message) // "Re-attestation successfully requested for nonce."
+ *
+ * // After requesting re-attestation, poll for the new attestation
+ * const attestation = await fetchAttestation(domainId, txHash, true)
+ * ```
+ */
+const requestReAttestation = async (nonce, isTestnet, config = {}) => {
+    const url = buildReAttestUrl(nonce, isTestnet);
+    // Use minimal retries since we're just submitting a request, not polling for state
+    const effectiveConfig = {
+        ...DEFAULT_CONFIG,
+        maxRetries: 3,
+        ...config,
+    };
+    return await pollApiPost(url, {}, isReAttestationResponse, effectiveConfig);
+};
 
 const assertCCTPv2WalletContextSymbol = Symbol('assertCCTPv2WalletContext');
 /**
@@ -7017,6 +7213,19 @@ class CCTPV2BridgingProvider extends BridgingProvider {
                 : Promise.resolve(0n),
         ]);
         const estimateResult = {
+            token: params.token,
+            amount: params.amount,
+            source: {
+                address: source.address,
+                chain: source.chain.chain,
+            },
+            destination: {
+                address: destination.address,
+                chain: destination.chain.chain,
+                ...(destination.recipientAddress && {
+                    recipientAddress: destination.recipientAddress,
+                }),
+            },
             gasFees: [],
             fees: [],
         };
@@ -7302,6 +7511,93 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             throw error;
         }
     }
+    /**
+     * Requests a fresh attestation for an expired attestation.
+     *
+     * This method is used when the original attestation has expired before the mint
+     * transaction could be completed. It performs three steps:
+     * 1. Fetches the existing attestation data to extract the nonce
+     * 2. Requests re-attestation from Circle's API using the nonce
+     * 3. Polls for the fresh attestation and returns it
+     *
+     * @typeParam TFromAdapterCapabilities - The type representing the capabilities of the source adapter
+     * @param source - The source wallet context containing the chain definition and wallet address
+     * @param transactionHash - The transaction hash of the original burn transaction
+     * @param config - Optional polling configuration overrides for timeout, retries, and delay
+     * @returns A promise that resolves to the fresh attestation message
+     * @throws {Error} With "Failed to re-attest: No nonce found for transaction" if the original
+     *   attestation cannot be found or has no nonce
+     * @throws {Error} With "Failed to re-attest: No attestation found after re-attestation request"
+     *   if the fresh attestation cannot be retrieved
+     * @throws {Error} With "Failed to re-attest: {details}" for other errors
+     *
+     * @example
+     * ```typescript
+     * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+     * import { Chains } from '@core/chains'
+     *
+     * const provider = new CCTPV2BridgingProvider()
+     *
+     * // After a mint fails due to expired attestation, request a fresh one
+     * const source = {
+     *   adapter: viemAdapter,
+     *   chain: Chains.EthereumSepolia,
+     *   address: '0x1234...'
+     * }
+     *
+     * try {
+     *   const freshAttestation = await provider.reAttest(
+     *     source,
+     *     '0xabc123...', // Original burn transaction hash
+     *     { timeout: 10000, maxRetries: 5 }
+     *   )
+     *
+     *   // Use the fresh attestation to retry the mint
+     *   const mintRequest = await provider.mint(source, destination, freshAttestation)
+     *   const result = await mintRequest.execute()
+     * } catch (error) {
+     *   console.error('Re-attestation failed:', error.message)
+     * }
+     * ```
+     */
+    async reAttest(source, transactionHash, config) {
+        assertCCTPv2WalletContext(source);
+        if (!transactionHash ||
+            typeof transactionHash !== 'string' ||
+            transactionHash.trim() === '') {
+            throw new Error('Failed to re-attest: Invalid transaction hash');
+        }
+        try {
+            // Merge configs: defaults <- global config <- per-call config
+            const effectiveConfig = {
+                ...this.config?.attestation,
+                ...config,
+            };
+            // Step 1: Get existing attestation data to extract nonce
+            const existingAttestation = await fetchAttestationWithoutStatusCheck(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
+            const nonce = existingAttestation.messages[0]?.eventNonce;
+            if (!nonce || typeof nonce !== 'string') {
+                throw new Error('Failed to re-attest: No nonce found for transaction');
+            }
+            // 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);
+            const message = response.messages[0];
+            if (!message) {
+                throw new Error('Failed to re-attest: No attestation found after re-attestation request');
+            }
+            return message;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            // Always prefix with 'Failed to re-attest'
+            if (!error.message.startsWith('Failed to re-attest')) {
+                throw new Error(`Failed to re-attest: ${error.message}`);
+            }
+            throw error;
+        }
+    }
     /**
      * Checks if both source and destination chains support CCTP v2 transfers.
      *
@@ -7381,15 +7677,17 @@ class CCTPV2BridgingProvider extends BridgingProvider {
         }
         else if (config?.maxFee === undefined) {
             // If the max fee is not provided and the transfer speed is fast, dynamically calculate the max fee
-            const baseFeeInBps = await fetchUsdcFastBurnFee(source.chain.cctp.domain, destination.chain.cctp.domain, source.chain.isTestnet);
+            const scaledBps = await fetchUsdcFastBurnFee(source.chain.cctp.domain, destination.chain.cctp.domain, source.chain.isTestnet);
             // Calculate fee proportional to the transfer amount
             // Convert amount to minor units
             const amountInMinorUnits = BigInt(amount);
             // Calculate base fee proportional to the transfer amount
-            // Formula: (baseFeeInBps * amountInMinorUnits) / 10_000
+            // The API returns basis points as a decimal (e.g., "1.3" for 1.3 bps).
+            // fetchUsdcFastBurnFee scales by 100 to preserve precision, so we divide by 1,000,000.
+            // Formula: (scaledBps * amountInMinorUnits) / 1_000_000
             // We use ceiling division (round up) to ensure sufficient fees and avoid failover to slow burn
-            // Ceiling division: (a + b - 1) / b, where b = 10_000, so (b - 1) = 9_999n
-            const baseFee = (baseFeeInBps * amountInMinorUnits + 9999n) / 10000n;
+            // Ceiling division: (a + b - 1) / b, where b = 1_000_000, so (b - 1) = 999_999n
+            const baseFee = (scaledBps * amountInMinorUnits + 999999n) / 1000000n;
             // Add 10% buffer to account for fee fluctuations: fee + (fee * 10 / 100) = fee + (fee / 10)
             maxFee = baseFee + baseFee / 10n;
         }

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -2614,15 +2614,39 @@ interface BridgeResult {
  *
  * This interface provides detailed information about the expected costs
  * for a transfer, including gas fees on different chains and protocol fees.
+ * It also includes the input context (token, amount, source, destination) to
+ * provide a complete view of the transfer being estimated.
  *
  * @example
  * ```typescript
  * const estimate: EstimateResult = await provider.estimate(source, dest, '100')
+ * console.log('Estimating transfer of', estimate.amount, estimate.token)
+ * console.log('From', estimate.source.chain.name, 'to', estimate.destination.chain.name)
  * console.log('Total gas fees:', estimate.gasFees.length)
  * console.log('Protocol fees:', estimate.fees.length)
  * ```
  */
 interface EstimateResult {
+    /** The token being transferred */
+    token: 'USDC';
+    /** The amount being transferred */
+    amount: string;
+    /** Information about the source chain and address */
+    source: {
+        /** The source wallet/contract address */
+        address: string;
+        /** The source blockchain network */
+        chain: Blockchain;
+    };
+    /** Information about the destination chain and address */
+    destination: {
+        /** The destination wallet/contract address */
+        address: string;
+        /** The destination blockchain network */
+        chain: Blockchain;
+        /** Optional custom recipient address for minted funds. */
+        recipientAddress?: string;
+    };
     /** Array of gas fees required for the transfer on different blockchains */
     gasFees: {
         /** The name of the step */
@@ -3373,6 +3397,20 @@ interface ICCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> {
      * @returns A promise that resolves to the attestation message.
      */
     fetchAttestation<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], txHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
+    /**
+     * Requests a fresh attestation for an expired attestation.
+     *
+     * This method is used when the original attestation has expired before the mint
+     * transaction could be completed. It fetches the existing attestation data to
+     * extract the nonce, requests re-attestation from Circle's API, and then polls
+     * for the fresh attestation.
+     *
+     * @param source - The source wallet context containing the chain definition and wallet address.
+     * @param txHash - The transaction hash of the original burn transaction.
+     * @param config - Optional polling configuration overrides.
+     * @returns A promise that resolves to the fresh attestation message.
+     */
+    reAttest<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], txHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
     /**
      * Mints the amount of tokens for the destination wallet.
      *
@@ -3685,6 +3723,56 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * ```
      */
     fetchAttestation<TFromAdapterCapabilities extends AdapterCapabilities>(source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>, transactionHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
+    /**
+     * Requests a fresh attestation for an expired attestation.
+     *
+     * This method is used when the original attestation has expired before the mint
+     * transaction could be completed. It performs three steps:
+     * 1. Fetches the existing attestation data to extract the nonce
+     * 2. Requests re-attestation from Circle's API using the nonce
+     * 3. Polls for the fresh attestation and returns it
+     *
+     * @typeParam TFromAdapterCapabilities - The type representing the capabilities of the source adapter
+     * @param source - The source wallet context containing the chain definition and wallet address
+     * @param transactionHash - The transaction hash of the original burn transaction
+     * @param config - Optional polling configuration overrides for timeout, retries, and delay
+     * @returns A promise that resolves to the fresh attestation message
+     * @throws {Error} With "Failed to re-attest: No nonce found for transaction" if the original
+     *   attestation cannot be found or has no nonce
+     * @throws {Error} With "Failed to re-attest: No attestation found after re-attestation request"
+     *   if the fresh attestation cannot be retrieved
+     * @throws {Error} With "Failed to re-attest: {details}" for other errors
+     *
+     * @example
+     * ```typescript
+     * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+     * import { Chains } from '@core/chains'
+     *
+     * const provider = new CCTPV2BridgingProvider()
+     *
+     * // After a mint fails due to expired attestation, request a fresh one
+     * const source = {
+     *   adapter: viemAdapter,
+     *   chain: Chains.EthereumSepolia,
+     *   address: '0x1234...'
+     * }
+     *
+     * try {
+     *   const freshAttestation = await provider.reAttest(
+     *     source,
+     *     '0xabc123...', // Original burn transaction hash
+     *     { timeout: 10000, maxRetries: 5 }
+     *   )
+     *
+     *   // Use the fresh attestation to retry the mint
+     *   const mintRequest = await provider.mint(source, destination, freshAttestation)
+     *   const result = await mintRequest.execute()
+     * } catch (error) {
+     *   console.error('Re-attestation failed:', error.message)
+     * }
+     * ```
+     */
+    reAttest<TFromAdapterCapabilities extends AdapterCapabilities>(source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>, transactionHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
     /**
      * Checks if both source and destination chains support CCTP v2 transfers.
      *

package/index.mjs

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -3014,7 +3014,9 @@ const makeApiRequest = async (url, method, isValidType, config, body) => {
             signal: controller.signal,
         };
         // Add body for methods that support it
-        if (body !== undefined && ['POST', 'PUT', 'PATCH'].includes(method)) ;
+        if (body !== undefined && ['POST', 'PUT', 'PATCH'].includes(method)) {
+            requestInit.body = JSON.stringify(body);
+        }
         const response = await fetch(url, requestInit);
         clearTimeout(timeoutId);
         if (!response.ok) {
@@ -3192,6 +3194,30 @@ const pollApiWithValidation = async (url, method, isValidType, config = {}, body
 const pollApiGet = async (url, isValidType, config) => {
     return pollApiWithValidation(url, 'GET', isValidType, config);
 };
+/**
+ * Convenience function for making POST requests with validation.
+ *
+ * @typeParam TResponseType - The expected response type after validation
+ * @typeParam TBody - The type of the request body
+ * @param url - The API endpoint URL
+ * @param body - The request body
+ * @param isValidType - Type guard function to validate the response
+ * @param config - Optional configuration overrides
+ * @returns Promise resolving to the validated response
+ *
+ * @example
+ * ```typescript
+ * const result = await pollApiPost(
+ *   'https://api.example.com/submit',
+ *   { name: 'John', email: 'john@example.com' },
+ *   isSubmissionResponse,
+ *   { maxRetries: 3 }
+ * )
+ * ```
+ */
+const pollApiPost = async (url, body, isValidType, config) => {
+    return pollApiWithValidation(url, 'POST', isValidType, config, body);
+};
 
 /**
  * Valid recoverability values for error handling strategies.
@@ -3399,6 +3425,24 @@ function validateErrorDetails(details) {
  * stays within KitError's constraints.
  */
 const MAX_MESSAGE_LENGTH = 950;
+/**
+ * Standard error message for invalid amount format.
+ *
+ * The SDK enforces strict dot-decimal notation for amount values. This constant
+ * provides a consistent error message when users provide amounts with:
+ * - Comma decimals (e.g., "1,5")
+ * - Thousand separators (e.g., "1,000.50")
+ * - Non-numeric characters
+ * - Invalid format
+ */
+const AMOUNT_FORMAT_ERROR_MESSAGE = 'Amount must be a numeric string with dot (.) as decimal separator (e.g., "10.5", "100"), with no thousand separators or comma decimals';
+/**
+ * Error message for invalid maxFee format.
+ *
+ * Used when validating the maxFee configuration parameter. The maxFee can be zero
+ * or positive and must follow strict dot-decimal notation.
+ */
+const MAX_FEE_FORMAT_ERROR_MESSAGE = 'maxFee must be a numeric string with dot (.) as decimal separator (e.g., "1", "0.5", ".5", "1.5"), with no thousand separators or comma decimals';
 
 /**
  * Structured error class for Stablecoin Kit operations.
@@ -4405,41 +4449,46 @@ var TransferSpeed;
  * - regexMessage: error message when the basic numeric format fails.
  * - maxDecimals: maximum number of decimal places allowed (e.g., 6 for USDC).
  */
-const createDecimalStringValidator = (options) => (schema) => schema
-    .regex(/^-?(?:\d+(?:\.\d+)?|\.\d+)$/, options.regexMessage)
-    .superRefine((val, ctx) => {
-    const amount = Number.parseFloat(val);
-    if (Number.isNaN(amount)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: options.regexMessage,
-        });
-        return;
-    }
-    // Check decimal precision if maxDecimals is specified
-    if (options.maxDecimals !== undefined) {
-        const decimalPart = val.split('.')[1];
-        if (decimalPart && decimalPart.length > options.maxDecimals) {
+const createDecimalStringValidator = (options) => (schema) => {
+    // Capitalize first letter of attribute name for error messages
+    const capitalizedAttributeName = options.attributeName.charAt(0).toUpperCase() +
+        options.attributeName.slice(1);
+    return schema
+        .regex(/^-?(?:\d+(?:\.\d+)?|\.\d+)$/, options.regexMessage)
+        .superRefine((val, ctx) => {
+        const amount = Number.parseFloat(val);
+        if (Number.isNaN(amount)) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
-                message: `Maximum supported decimal places: ${options.maxDecimals.toString()}`,
+                message: options.regexMessage,
             });
             return;
         }
-    }
-    if (options.allowZero && amount < 0) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `${options.attributeName} must be non-negative`,
-        });
-    }
-    else if (!options.allowZero && amount <= 0) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `${options.attributeName} must be greater than 0`,
-        });
-    }
-});
+        // Check decimal precision if maxDecimals is specified
+        if (options.maxDecimals !== undefined) {
+            const decimalPart = val.split('.')[1];
+            if (decimalPart && decimalPart.length > options.maxDecimals) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `Maximum supported decimal places: ${options.maxDecimals.toString()}`,
+                });
+                return;
+            }
+        }
+        if (options.allowZero && amount < 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `${capitalizedAttributeName} must be non-negative`,
+            });
+        }
+        else if (!options.allowZero && amount <= 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `${capitalizedAttributeName} must be greater than 0`,
+            });
+        }
+    });
+};
 /**
  * Schema for validating chain definitions.
  * This ensures the basic structure of a chain definition is valid.
@@ -4599,7 +4648,7 @@ const bridgeParamsSchema = z.object({
         .min(1, 'Required')
         .pipe(createDecimalStringValidator({
         allowZero: false,
-        regexMessage: 'Amount must be a numeric string with dot (.) as decimal separator (e.g., "0.1", ".1", "10.5", "1000.50"), with no thousand separators or comma decimals.',
+        regexMessage: AMOUNT_FORMAT_ERROR_MESSAGE,
         attributeName: 'amount',
         maxDecimals: 6,
     })(z.string())),
@@ -4612,7 +4661,7 @@ const bridgeParamsSchema = z.object({
             .string()
             .pipe(createDecimalStringValidator({
             allowZero: true,
-            regexMessage: 'maxFee must be a numeric string with dot (.) as decimal separator (e.g., "1", "0.5", ".5", "1.5"), with no thousand separators or comma decimals.',
+            regexMessage: MAX_FEE_FORMAT_ERROR_MESSAGE,
             attributeName: 'maxFee',
             maxDecimals: 6,
         })(z.string()))
@@ -4621,6 +4670,19 @@ const bridgeParamsSchema = z.object({
     }),
 });
 
+/**
+ * Base URL for Circle's IRIS API (mainnet/production).
+ *
+ * The IRIS API provides attestation services for CCTP cross-chain transfers.
+ */
+const IRIS_API_BASE_URL = 'https://iris-api.circle.com';
+/**
+ * Base URL for Circle's IRIS API (testnet/sandbox).
+ *
+ * Used for development and testing on testnet chains.
+ */
+const IRIS_API_SANDBOX_BASE_URL = 'https://iris-api-sandbox.circle.com';
+
 /**
  * Type guard to validate the API response structure.
  *
@@ -4669,9 +4731,7 @@ const isFastBurnFeeResponse = (data) => {
  * @returns The complete API URL
  */
 function buildFastBurnFeeUrl(sourceDomain, destinationDomain, isTestnet) {
-    const baseUrl = isTestnet
-        ? 'https://iris-api-sandbox.circle.com'
-        : 'https://iris-api.circle.com';
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
     return `${baseUrl}/v2/burn/USDC/fees/${sourceDomain.toString()}/${destinationDomain.toString()}`;
 }
 const FAST_TIER_FINALITY_THRESHOLD = 1000;
@@ -4687,15 +4747,24 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
  * - Retry delays: 9 × 200 ms = 1 800 ms
  * - Total max time: 2 000 ms + 1 800 ms = 3 800 ms
  *
+ * @remarks
+ * The API returns basis points as a decimal (e.g., "1.3" for 1.3 bps = 0.013%).
+ * This function scales the value by 100 to preserve 2 decimal places of precision.
+ * Callers must divide by 1,000,000 (instead of 10,000) when calculating fees.
+ *
  * @param sourceDomain - The source domain
  * @param destinationDomain - The destination domain
  * @param isTestnet - Whether the request is for a testnet chain
- * @returns The minimum fee for a USDC fast burn operation
+ * @returns The minimum fee in scaled basis points (bps × 100)
  * @throws Error if the input domains are invalid, the API request fails, returns invalid data, or network errors occur
  * @example
  * ```typescript
- * const minimumFee = await fetchUsdcFastBurnFee(0, 6, false) // Ethereum -> Base
- * console.log(minimumFee) // 1000n
+ * const scaledBps = await fetchUsdcFastBurnFee(0, 6, false) // Ethereum -> Base
+ * console.log(scaledBps) // 130n (representing 1.3 bps)
+ *
+ * // To calculate fee for an amount:
+ * const amount = 1_000_000n // 1 USDC
+ * const fee = (scaledBps * amount) / 1_000_000n // 130n (0.00013 USDC)
  * ```
  */
 async function fetchUsdcFastBurnFee(sourceDomain, destinationDomain, isTestnet) {
@@ -4721,14 +4790,16 @@ async function fetchUsdcFastBurnFee(sourceDomain, destinationDomain, isTestnet)
     if (!fastTier) {
         throw new Error(`No fast tier (finalityThreshold: ${FAST_TIER_FINALITY_THRESHOLD.toString()}) available in API response`);
     }
-    // Convert minimumFee to bigint
-    let minimumFee;
-    try {
-        minimumFee = BigInt(fastTier.minimumFee);
-    }
-    catch {
-        throw new Error(`Invalid minimumFee value: cannot convert "${String(fastTier.minimumFee)}" to bigint`);
+    // Convert minimumFee to scaled basis points (bigint)
+    // The API returns basis points as a decimal (e.g., "1.3" for 1.3 bps = 0.013%).
+    // We scale by 100 to preserve 2 decimal places of precision.
+    // The caller (getMaxFee) must divide by 1,000,000 instead of 10,000.
+    const feeValue = Number.parseFloat(String(fastTier.minimumFee));
+    if (Number.isNaN(feeValue) || !Number.isFinite(feeValue)) {
+        throw new Error(`Invalid minimumFee value: cannot parse "${String(fastTier.minimumFee)}" as a number`);
     }
+    // Scale by 100 and round to get integer representation
+    const minimumFee = BigInt(Math.round(feeValue * 100));
     // Validate that minimumFee is non-negative
     if (minimumFee < 0n) {
         throw new Error('Invalid minimumFee: value must be non-negative');
@@ -4903,9 +4974,7 @@ const isAttestationResponse = (obj) => {
  * ```
  */
 const buildIrisUrl = (sourceDomainId, transactionHash, isTestnet) => {
-    const baseUrl = isTestnet
-        ? 'https://iris-api-sandbox.circle.com'
-        : 'https://iris-api.circle.com';
+    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();
@@ -4950,6 +5019,133 @@ const fetchAttestation = async (sourceDomainId, transactionHash, isTestnet, conf
     const effectiveConfig = { ...DEFAULT_CONFIG, ...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 = {
+        ...DEFAULT_CONFIG,
+        maxRetries: 3,
+        ...config,
+    };
+    return await pollApiGet(url, isAttestationResponseWithoutStatusCheck, 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
+ * // Mainnet URL
+ * const mainnetUrl = buildReAttestUrl('0xabc', false)
+ * // => 'https://iris-api.circle.com/v2/reattest/0xabc'
+ *
+ * // Testnet URL
+ * const testnetUrl = buildReAttestUrl('0xabc', true)
+ * // => 'https://iris-api-sandbox.circle.com/v2/reattest/0xabc'
+ * ```
+ */
+const buildReAttestUrl = (nonce, isTestnet) => {
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const url = new URL(`${baseUrl}/v2/reattest/${nonce}`);
+    return url.toString();
+};
+/**
+ * Type guard that validates the re-attestation API response structure.
+ *
+ * @param obj - The value to check, typically a parsed JSON response
+ * @returns True if the object matches the ReAttestationResponse shape
+ * @throws {Error} With "Invalid re-attestation response structure" if structure is invalid
+ * @internal
+ */
+const isReAttestationResponse = (obj) => {
+    if (typeof obj !== 'object' ||
+        obj === null ||
+        !('message' in obj) ||
+        !('nonce' in obj) ||
+        typeof obj.message !== 'string' ||
+        typeof obj.nonce !== 'string') {
+        throw new Error('Invalid re-attestation response structure');
+    }
+    return true;
+};
+/**
+ * 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.
+ *
+ * @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
+ * // Request re-attestation for an expired nonce
+ * const response = await requestReAttestation('0xabc', true)
+ * console.log(response.message) // "Re-attestation successfully requested for nonce."
+ *
+ * // After requesting re-attestation, poll for the new attestation
+ * const attestation = await fetchAttestation(domainId, txHash, true)
+ * ```
+ */
+const requestReAttestation = async (nonce, isTestnet, config = {}) => {
+    const url = buildReAttestUrl(nonce, isTestnet);
+    // Use minimal retries since we're just submitting a request, not polling for state
+    const effectiveConfig = {
+        ...DEFAULT_CONFIG,
+        maxRetries: 3,
+        ...config,
+    };
+    return await pollApiPost(url, {}, isReAttestationResponse, effectiveConfig);
+};
 
 const assertCCTPv2WalletContextSymbol = Symbol('assertCCTPv2WalletContext');
 /**
@@ -7011,6 +7207,19 @@ class CCTPV2BridgingProvider extends BridgingProvider {
                 : Promise.resolve(0n),
         ]);
         const estimateResult = {
+            token: params.token,
+            amount: params.amount,
+            source: {
+                address: source.address,
+                chain: source.chain.chain,
+            },
+            destination: {
+                address: destination.address,
+                chain: destination.chain.chain,
+                ...(destination.recipientAddress && {
+                    recipientAddress: destination.recipientAddress,
+                }),
+            },
             gasFees: [],
             fees: [],
         };
@@ -7296,6 +7505,93 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             throw error;
         }
     }
+    /**
+     * Requests a fresh attestation for an expired attestation.
+     *
+     * This method is used when the original attestation has expired before the mint
+     * transaction could be completed. It performs three steps:
+     * 1. Fetches the existing attestation data to extract the nonce
+     * 2. Requests re-attestation from Circle's API using the nonce
+     * 3. Polls for the fresh attestation and returns it
+     *
+     * @typeParam TFromAdapterCapabilities - The type representing the capabilities of the source adapter
+     * @param source - The source wallet context containing the chain definition and wallet address
+     * @param transactionHash - The transaction hash of the original burn transaction
+     * @param config - Optional polling configuration overrides for timeout, retries, and delay
+     * @returns A promise that resolves to the fresh attestation message
+     * @throws {Error} With "Failed to re-attest: No nonce found for transaction" if the original
+     *   attestation cannot be found or has no nonce
+     * @throws {Error} With "Failed to re-attest: No attestation found after re-attestation request"
+     *   if the fresh attestation cannot be retrieved
+     * @throws {Error} With "Failed to re-attest: {details}" for other errors
+     *
+     * @example
+     * ```typescript
+     * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+     * import { Chains } from '@core/chains'
+     *
+     * const provider = new CCTPV2BridgingProvider()
+     *
+     * // After a mint fails due to expired attestation, request a fresh one
+     * const source = {
+     *   adapter: viemAdapter,
+     *   chain: Chains.EthereumSepolia,
+     *   address: '0x1234...'
+     * }
+     *
+     * try {
+     *   const freshAttestation = await provider.reAttest(
+     *     source,
+     *     '0xabc123...', // Original burn transaction hash
+     *     { timeout: 10000, maxRetries: 5 }
+     *   )
+     *
+     *   // Use the fresh attestation to retry the mint
+     *   const mintRequest = await provider.mint(source, destination, freshAttestation)
+     *   const result = await mintRequest.execute()
+     * } catch (error) {
+     *   console.error('Re-attestation failed:', error.message)
+     * }
+     * ```
+     */
+    async reAttest(source, transactionHash, config) {
+        assertCCTPv2WalletContext(source);
+        if (!transactionHash ||
+            typeof transactionHash !== 'string' ||
+            transactionHash.trim() === '') {
+            throw new Error('Failed to re-attest: Invalid transaction hash');
+        }
+        try {
+            // Merge configs: defaults <- global config <- per-call config
+            const effectiveConfig = {
+                ...this.config?.attestation,
+                ...config,
+            };
+            // Step 1: Get existing attestation data to extract nonce
+            const existingAttestation = await fetchAttestationWithoutStatusCheck(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
+            const nonce = existingAttestation.messages[0]?.eventNonce;
+            if (!nonce || typeof nonce !== 'string') {
+                throw new Error('Failed to re-attest: No nonce found for transaction');
+            }
+            // 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);
+            const message = response.messages[0];
+            if (!message) {
+                throw new Error('Failed to re-attest: No attestation found after re-attestation request');
+            }
+            return message;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            // Always prefix with 'Failed to re-attest'
+            if (!error.message.startsWith('Failed to re-attest')) {
+                throw new Error(`Failed to re-attest: ${error.message}`);
+            }
+            throw error;
+        }
+    }
     /**
      * Checks if both source and destination chains support CCTP v2 transfers.
      *
@@ -7375,15 +7671,17 @@ class CCTPV2BridgingProvider extends BridgingProvider {
         }
         else if (config?.maxFee === undefined) {
             // If the max fee is not provided and the transfer speed is fast, dynamically calculate the max fee
-            const baseFeeInBps = await fetchUsdcFastBurnFee(source.chain.cctp.domain, destination.chain.cctp.domain, source.chain.isTestnet);
+            const scaledBps = await fetchUsdcFastBurnFee(source.chain.cctp.domain, destination.chain.cctp.domain, source.chain.isTestnet);
             // Calculate fee proportional to the transfer amount
             // Convert amount to minor units
             const amountInMinorUnits = BigInt(amount);
             // Calculate base fee proportional to the transfer amount
-            // Formula: (baseFeeInBps * amountInMinorUnits) / 10_000
+            // The API returns basis points as a decimal (e.g., "1.3" for 1.3 bps).
+            // fetchUsdcFastBurnFee scales by 100 to preserve precision, so we divide by 1,000,000.
+            // Formula: (scaledBps * amountInMinorUnits) / 1_000_000
             // We use ceiling division (round up) to ensure sufficient fees and avoid failover to slow burn
-            // Ceiling division: (a + b - 1) / b, where b = 10_000, so (b - 1) = 9_999n
-            const baseFee = (baseFeeInBps * amountInMinorUnits + 9999n) / 10000n;
+            // Ceiling division: (a + b - 1) / b, where b = 1_000_000, so (b - 1) = 999_999n
+            const baseFee = (scaledBps * amountInMinorUnits + 999999n) / 1000000n;
             // Add 10% buffer to account for fee fluctuations: fee + (fee * 10 / 100) = fee + (fee / 10)
             maxFee = baseFee + baseFee / 10n;
         }

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@circle-fin/provider-cctp-v2",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Circle's official Cross-Chain Transfer Protocol v2 provider for native USDC bridging",
+  "keywords": [
+    "circle",
+    "cctp",
+    "usdc",
+    "stablecoin",
+    "provider",
+    "typescript",
+    "cross-chain",
+    "bridge",
+    "bridging",
+    "bridge-kit"
+  ],
   "main": "./index.cjs",
   "module": "./index.mjs",
   "types": "./index.d.ts",