@circle-fin/app-kit 1.8.0 → 1.9.0

package/estimateBridge.mjs

@@ -22,6 +22,7 @@ import { formatUnits as formatUnits$1, parseUnits as parseUnits$1 } from '@ether
 import { hexlify, hexZeroPad } from '@ethersproject/bytes';
 import { getAddress } from '@ethersproject/address';
 import bs58 from 'bs58';
+import '@ethersproject/abi';
 import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
 import '@coral-xyz/anchor';
@@ -2472,6 +2473,8 @@ class KitError extends Error {
     Blockchain["Celo_Alfajores_Testnet"] = "Celo_Alfajores_Testnet";
     Blockchain["Codex"] = "Codex";
     Blockchain["Codex_Testnet"] = "Codex_Testnet";
+    Blockchain["Cronos"] = "Cronos";
+    Blockchain["Cronos_Testnet"] = "Cronos_Testnet";
     Blockchain["Edge"] = "Edge";
     Blockchain["Edge_Testnet"] = "Edge_Testnet";
     Blockchain["Ethereum"] = "Ethereum";
@@ -2554,6 +2557,7 @@ var BridgeChain;
     BridgeChain["Avalanche"] = "Avalanche";
     BridgeChain["Base"] = "Base";
     BridgeChain["Codex"] = "Codex";
+    BridgeChain["Cronos"] = "Cronos";
     BridgeChain["Edge"] = "Edge";
     BridgeChain["Ethereum"] = "Ethereum";
     BridgeChain["HyperEVM"] = "HyperEVM";
@@ -2578,6 +2582,7 @@ var BridgeChain;
     BridgeChain["Avalanche_Fuji"] = "Avalanche_Fuji";
     BridgeChain["Base_Sepolia"] = "Base_Sepolia";
     BridgeChain["Codex_Testnet"] = "Codex_Testnet";
+    BridgeChain["Cronos_Testnet"] = "Cronos_Testnet";
     BridgeChain["Edge_Testnet"] = "Edge_Testnet";
     BridgeChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
@@ -3623,6 +3628,96 @@ var EarnChain;
     }
 });
 
+/**
+ * Cronos Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Cronos blockchain.
+ * Cronos is an EVM-compatible blockchain.
+ */ const Cronos = defineChain({
+    type: 'evm',
+    chain: Blockchain.Cronos,
+    name: 'Cronos',
+    title: 'Cronos Mainnet',
+    nativeCurrency: {
+        name: 'Cronos',
+        symbol: 'CRO',
+        decimals: 18
+    },
+    chainId: 25,
+    isTestnet: false,
+    explorerUrl: 'https://cronoscan.com/tx/{hash}',
+    rpcEndpoints: [
+        'https://evm.cronos.org'
+    ],
+    eurcAddress: '0xA6dE01a2d62C6B5f3525d768f34d276652C554c8',
+    usdcAddress: '0x3D7F2C478aAfdB65542BCB44bCeeC05849999d2D',
+    usdtAddress: null,
+    cctp: {
+        domain: 32,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+    }
+});
+
+/**
+ * Cronos Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Cronos blockchain.
+ * Cronos is an EVM-compatible blockchain.
+ */ const CronosTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Cronos_Testnet,
+    name: 'Cronos Testnet',
+    title: 'Cronos Testnet',
+    nativeCurrency: {
+        name: 'CRO',
+        symbol: 'tCRO',
+        decimals: 18
+    },
+    chainId: 338,
+    isTestnet: true,
+    explorerUrl: 'https://explorer.cronos.org/testnet/tx/{hash}',
+    rpcEndpoints: [
+        'https://evm-t3.cronos.org'
+    ],
+    eurcAddress: '0x31f7538adb53cF16350e6B0c89d03D91b7D12c46',
+    usdcAddress: '0xEb33dc5fac03833e132593659e1dE7256aB59794',
+    usdtAddress: null,
+    cctp: {
+        domain: 32,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET
+    }
+});
+
 /**
  * Edge Mainnet chain definition
  * @remarks
@@ -5974,6 +6069,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   CeloAlfajoresTestnet: CeloAlfajoresTestnet,
   Codex: Codex,
   CodexTestnet: CodexTestnet,
+  Cronos: Cronos,
+  CronosTestnet: CronosTestnet,
   Edge: Edge,
   EdgeTestnet: EdgeTestnet,
   Ethereum: Ethereum,
@@ -8039,6 +8136,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Base]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
         [Blockchain.Celo]: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
         [Blockchain.Codex]: '0xd996633a415985DBd7D6D12f4A4343E31f5037cf',
+        [Blockchain.Cronos]: '0x3D7F2C478aAfdB65542BCB44bCeeC05849999d2D',
         [Blockchain.Edge]: '0x98d2919b9A214E6Fa5384AC81E6864bA686Ad74c',
         [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
         [Blockchain.Hedera]: '0.0.456858',
@@ -8072,6 +8170,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
         [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
         [Blockchain.Codex_Testnet]: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
+        [Blockchain.Cronos_Testnet]: '0xEb33dc5fac03833e132593659e1dE7256aB59794',
         [Blockchain.Edge_Testnet]: '0x2d9F7CAD728051AA35Ecdc472a14cf8cDF5CFD6B',
         [Blockchain.Ethereum_Sepolia]: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
         [Blockchain.Hedera_Testnet]: '0.0.429274',
@@ -8139,13 +8238,22 @@ const swapTokenEnumSchema = z.enum([
     symbol: 'EURC',
     decimals: 6,
     locators: {
+        // =========================================================================
+        // Mainnets
+        // =========================================================================
         [Blockchain.Avalanche]: '0xc891EB4cbdEFf6e073e859e987815Ed1505c2ACD',
         [Blockchain.Base]: '0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42',
+        [Blockchain.Cronos]: '0xA6dE01a2d62C6B5f3525d768f34d276652C554c8',
         [Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
         [Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
         [Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
+        // =========================================================================
         // Testnets
-        [Blockchain.Arc_Testnet]: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a'
+        // =========================================================================
+        [Blockchain.Arc_Testnet]: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
+        [Blockchain.Base_Sepolia]: '0x808456652fdb597867f38412077A9182bf77359F',
+        [Blockchain.Cronos_Testnet]: '0x31f7538adb53cF16350e6B0c89d03D91b7D12c46',
+        [Blockchain.Ethereum_Sepolia]: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4'
     }
 };
 
@@ -8355,8 +8463,7 @@ const swapTokenEnumSchema = z.enum([
  * cirBTC (Circle Bitcoin) token definition with addresses and metadata.
  *
  * @remarks
- * Built-in cirBTC definition for the TokenRegistry. Currently deployed
- * on Arc Testnet.
+ * Built-in cirBTC definition for the TokenRegistry.
  *
  * @example
  * ```typescript
@@ -8372,7 +8479,15 @@ const swapTokenEnumSchema = z.enum([
     symbol: 'cirBTC',
     decimals: 8,
     locators: {
-        [Blockchain.Arc_Testnet]: '0xf0C4a4CE82A5746AbAAd9425360Ab04fbBA432BF'
+        // =========================================================================
+        // Mainnets
+        // =========================================================================
+        [Blockchain.Ethereum]: '0x72DFB2E44f59C5AD2bAFE84314E5b99a7cd5075E',
+        // =========================================================================
+        // Testnets
+        // =========================================================================
+        [Blockchain.Arc_Testnet]: '0xf0C4a4CE82A5746AbAAd9425360Ab04fbBA432BF',
+        [Blockchain.Ethereum_Sepolia]: '0x3a3fe695F684Bf9b9e43CF43C2b895Ea5e392bB3'
     }
 };
 
@@ -9488,7 +9603,7 @@ function resolveOptions(options) {
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$3 = "1.11.0";
+var version$3 = "1.12.0";
 var pkg$3 = {
 	name: name$2,
 	version: version$3};
@@ -12148,6 +12263,15 @@ const CUSTOM_BURN_GAS_ESTIMATE_EVM = 201_525n // p99 and max are same here: 201_
 ;
 const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_839n) / 2 = 237_401n
 ;
+// Hard execution caps: observed max + ~30% buffer, used as gasLimit overrides on
+// chains whose eth_estimateGas under-reports (e.g. Cronos EIP-7623 calldata floor).
+// Kept separate from the fee-estimate averages above.
+const APPROVE_GAS_LIMIT_EVM = 100_000n // ERC-20 approve observed max ~46k
+;
+const DEPOSIT_FOR_BURN_GAS_LIMIT_EVM = 300_000n // observed max 226_506 + ~30%
+;
+const RECEIVE_MESSAGE_GAS_LIMIT_EVM = 400_000n // observed max 310_839 + ~30%
+;
 /**
  * The minimum finality threshold for CCTPv2 transfers.
  *
@@ -12176,6 +12300,27 @@ const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_8
         'Content-Type': 'application/json'
     }
 };
+/**
+ * Merges caller-provided polling overrides on top of {@link DEFAULT_CONFIG}.
+ *
+ * Headers are merged independently so caller-supplied headers augment the
+ * defaults (such as `Content-Type`) rather than replacing them wholesale.
+ *
+ * @param config - Caller-provided polling configuration overrides
+ * @param internalDefaults - Internal defaults applied before `config` (for example a
+ *   reduced `maxRetries` for one-shot requests); `config` still wins on conflict
+ * @returns The effective polling configuration
+ * @internal
+ */ const mergeAttestationConfig = (config, internalDefaults = {})=>({
+        ...DEFAULT_CONFIG,
+        ...internalDefaults,
+        ...config,
+        headers: {
+            ...DEFAULT_CONFIG.headers,
+            ...internalDefaults.headers,
+            ...config.headers
+        }
+    });
 /**
  * Type guard that verifies if an unknown value matches the AttestationMessage shape
  * and has all required properties.
@@ -12322,10 +12467,7 @@ const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_8
  * ```
  */ const fetchAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
     const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = {
-        ...DEFAULT_CONFIG,
-        ...config
-    };
+    const effectiveConfig = mergeAttestationConfig(config);
     return await pollApiGet(url, isAttestationResponse, effectiveConfig);
 };
 /**
@@ -12368,11 +12510,9 @@ const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_8
  */ const fetchAttestationWithoutStatusCheck = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
     const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
     // Use minimal retries since we're just fetching existing data
-    const effectiveConfig = {
-        ...DEFAULT_CONFIG,
-        maxRetries: 3,
-        ...config
-    };
+    const effectiveConfig = mergeAttestationConfig(config, {
+        maxRetries: 3
+    });
     return await pollApiGet(url, isAttestationResponseWithoutStatusCheck, effectiveConfig);
 };
 /**
@@ -12432,10 +12572,7 @@ const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_8
  * ```
  */ const fetchReAttestedAttestation = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
     const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = {
-        ...DEFAULT_CONFIG,
-        ...config
-    };
+    const effectiveConfig = mergeAttestationConfig(config);
     return await pollApiGet(url, isReAttestedAttestationResponse, effectiveConfig);
 };
 /**
@@ -12501,14 +12638,139 @@ const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_8
  */ const requestReAttestation = async (nonce, isTestnet, config = {})=>{
     const url = buildReAttestUrl(nonce, isTestnet);
     // Use minimal retries since we're just submitting a request, not polling for state
-    const effectiveConfig = {
-        ...DEFAULT_CONFIG,
-        maxRetries: 3,
-        ...config
-    };
+    const effectiveConfig = mergeAttestationConfig(config, {
+        maxRetries: 3
+    });
     return await pollApiPost(url, {}, isReAttestationResponse, effectiveConfig);
 };
 
+/**
+ * Type guard that checks if the relayer has confirmed the mint transaction.
+ *
+ * This function validates that:
+ * 1. The response has valid AttestationResponse structure
+ * 2. At least one message has forwardState === 'CONFIRMED' (or 'COMPLETE') and a valid forwardTxHash
+ *
+ * If forwardState is 'FAILED', throws a non-retryable KitError.
+ * If forwardState is 'PENDING' or not present, throws a RETRYABLE KitError to continue polling.
+ *
+ * @param obj - The value to check, typically a parsed JSON response
+ * @returns True if the relayer has confirmed the mint
+ * @throws {KitError} With FATAL recoverability if structure is invalid
+ * @throws {KitError} With RESUMABLE recoverability if forwardState is 'FAILED'
+ * @throws {KitError} With RETRYABLE recoverability if still pending
+ * @internal
+ */ const isRelayerMintConfirmed = (obj)=>{
+    // First check if the structure is valid
+    if (!hasValidAttestationStructure(obj)) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'Invalid attestation response structure from IRIS API.'
+        });
+    }
+    // Find the first message (typically there's only one)
+    const message = obj.messages[0];
+    if (!message) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'No attestation messages found in IRIS API response.'
+        });
+    }
+    // Check for FAILED state - this is a permanent failure
+    if (message.forwardState === 'FAILED') {
+        throw new KitError({
+            ...NetworkError.RELAYER_FORWARD_FAILED,
+            recoverability: 'RESUMABLE',
+            message: 'Circle relayer failed to forward the mint transaction. The mint may still have succeeded if another party submitted it. Check the recipient wallet balance before retrying. If the mint did not occur, you can manually submit it using the attestation data in the error cause.',
+            cause: {
+                trace: {
+                    eventNonce: message.eventNonce,
+                    attestation: message.attestation,
+                    message: message.message
+                }
+            }
+        });
+    }
+    // Check if mint is confirmed (or complete) with a valid transaction hash
+    // We accept both CONFIRMED and COMPLETE since COMPLETE implies CONFIRMED
+    if ((message.forwardState === 'CONFIRMED' || message.forwardState === 'COMPLETE') && typeof message.forwardTxHash === 'string' && message.forwardTxHash.trim().length > 0) {
+        return true;
+    }
+    // Still pending or not yet processed - throw RETRYABLE error to continue polling
+    throw new KitError({
+        ...NetworkError.RELAYER_PENDING,
+        recoverability: 'RETRYABLE',
+        message: 'Relayer mint not ready. Waiting for confirmation.'
+    });
+};
+/**
+ * Polls the attestation API until the relayer's mint transaction is confirmed.
+ *
+ * This function is used when `useForwarder` is enabled. Instead of the user
+ * submitting the mint transaction, Circle's Orbit relayer handles it automatically.
+ * This function polls until the relayer has submitted and confirmed the mint transaction.
+ *
+ * @remarks
+ * - Uses a 20-minute timeout by default (600 retries × 2 seconds)
+ * - Throws immediately if `forwardState` is 'FAILED'
+ * - Waits for `forwardState` to be 'CONFIRMED' or 'COMPLETE' (COMPLETE implies CONFIRMED)
+ * - Returns the attestation message with `forwardTxHash` populated
+ *
+ * @param sourceDomainId - The CCTP domain ID of the source chain
+ * @param transactionHash - The transaction hash of the burn operation
+ * @param isTestnet - Whether this is for a testnet chain (true) or mainnet (false)
+ * @param config - Optional configuration overrides for polling behavior
+ * @returns The attestation message with confirmed forwardTxHash
+ * @throws {KitError} With code 'NETWORK_RELAYER_FORWARD_FAILED' if relayer failed
+ * @throws {KitError} If timeout is reached while still pending
+ *
+ * @example
+ * ```typescript
+ * const attestation = await fetchRelayerMint(0, '0xabc...', false)
+ * console.log('Relayer mint tx:', attestation.forwardTxHash)
+ * ```
+ */ const fetchRelayerMint = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
+    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
+    const effectiveConfig = mergeAttestationConfig(config);
+    let response;
+    try {
+        response = await pollApiGet(url, isRelayerMintConfirmed, effectiveConfig);
+    } catch (error) {
+        // Enrich RELAYER_FORWARD_FAILED errors with the burn transaction hash
+        if (error instanceof KitError && error.name === 'NETWORK_RELAYER_FORWARD_FAILED') {
+            throw new KitError({
+                ...NetworkError.RELAYER_FORWARD_FAILED,
+                recoverability: error.recoverability,
+                message: error.message,
+                cause: {
+                    ...error.cause,
+                    trace: {
+                        ...error.cause?.trace,
+                        burnTxHash: transactionHash
+                    }
+                }
+            });
+        }
+        throw error;
+    }
+    // Return the first message (which should have forwardTxHash)
+    // Note: This check is needed for TypeScript type safety even though
+    // isRelayerMintConfirmed validates messages[0] exists. The type guard
+    // narrows the type at the call site, but TypeScript can't infer that
+    // the array still has elements after pollApiGet returns.
+    const message = response.messages[0];
+    if (!message) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'No attestation messages found in response after polling.'
+        });
+    }
+    return message;
+};
+
 const assertCCTPv2WalletContextSymbol = Symbol('assertCCTPv2WalletContext');
 /**
  * Asserts that the provided parameters match the CCTPv2 wallet context interface.
@@ -13383,6 +13645,8 @@ function hasPendingState(analysis, result) {
  *   - `adapter`: The adapter that will execute the transaction
  *   - `confirmations`: The number of confirmations to wait for (defaults to 1)
  *   - `timeout`: The timeout for the request in milliseconds
+ *   - `gasLimit`: Optional explicit gas limit (number) forwarded to EVM execute,
+ *     bypassing `eth_estimateGas`; ignored for non-EVM requests
  * @returns The bridge step with the transaction details and explorer URL
  * @throws If the transaction execution fails
  *
@@ -13397,7 +13661,7 @@ function hasPendingState(analysis, result) {
  * })
  * console.log('Transaction hash:', step.txHash)
  * ```
- */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout }) {
+ */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, gasLimit }) {
     const step = {
         name,
         state: 'pending'
@@ -13410,7 +13674,9 @@ function hasPendingState(analysis, result) {
             step.state = 'noop';
             return step;
         }
-        const txHash = await request.execute();
+        const txHash = request.type === 'evm' && gasLimit !== undefined ? await request.execute({
+            gasLimit
+        }) : await request.execute();
         step.txHash = txHash;
         const retryOptions = {
             isRetryable: (err)=>isRetryableError$1(parseBlockchainError(err, {
@@ -13482,7 +13748,8 @@ function hasPendingState(analysis, result) {
         name: 'approve',
         adapter: params.source.adapter,
         chain: params.source.chain,
-        request: await provider.approve(params.source, approvalAmount)
+        request: await provider.approve(params.source, approvalAmount),
+        gasLimit: Number(APPROVE_GAS_LIMIT_EVM)
     });
 }
 
@@ -13509,7 +13776,8 @@ function hasPendingState(analysis, result) {
         name: 'burn',
         adapter: params.source.adapter,
         chain: params.source.chain,
-        request: await provider.burn(params)
+        request: await provider.burn(params),
+        gasLimit: Number(DEPOSIT_FOR_BURN_GAS_LIMIT_EVM)
     });
 }
 
@@ -13595,11 +13863,18 @@ function hasPendingState(analysis, result) {
  */ async function bridgeMint({ params, provider }, attestation) {
     // Validate attestation message matches transfer params
     await assertCCTPv2AttestationParams(attestation, params);
+    const mintRequest = await provider.mint(params.source, params.destination, attestation);
     const step = await executePreparedChainRequest({
         name: 'mint',
         adapter: params.destination.adapter,
         chain: params.destination.chain,
-        request: await provider.mint(params.source, params.destination, attestation)
+        request: mintRequest,
+        // Some chains (e.g. Cronos) enforce an EIP-7623 calldata gas floor that
+        // eth_estimateGas does not account for, returning a below-floor value
+        // without reverting. Pinning to a value above the observed execution max
+        // (310_839) bypasses re-estimation and guarantees we clear both the floor
+        // and the actual execution cost.
+        gasLimit: Number(RECEIVE_MESSAGE_GAS_LIMIT_EVM)
     });
     // Add forwarded: false for non-relayer mints
     return {
@@ -13637,136 +13912,6 @@ const mockAttestationMessage = {
     delayReason: null
 };
 
-/**
- * Type guard that checks if the relayer has confirmed the mint transaction.
- *
- * This function validates that:
- * 1. The response has valid AttestationResponse structure
- * 2. At least one message has forwardState === 'CONFIRMED' (or 'COMPLETE') and a valid forwardTxHash
- *
- * If forwardState is 'FAILED', throws a non-retryable KitError.
- * If forwardState is 'PENDING' or not present, throws a RETRYABLE KitError to continue polling.
- *
- * @param obj - The value to check, typically a parsed JSON response
- * @returns True if the relayer has confirmed the mint
- * @throws {KitError} With FATAL recoverability if structure is invalid
- * @throws {KitError} With RESUMABLE recoverability if forwardState is 'FAILED'
- * @throws {KitError} With RETRYABLE recoverability if still pending
- * @internal
- */ const isRelayerMintConfirmed = (obj)=>{
-    // First check if the structure is valid
-    if (!hasValidAttestationStructure(obj)) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'Invalid attestation response structure from IRIS API.'
-        });
-    }
-    // Find the first message (typically there's only one)
-    const message = obj.messages[0];
-    if (!message) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'No attestation messages found in IRIS API response.'
-        });
-    }
-    // Check for FAILED state - this is a permanent failure
-    if (message.forwardState === 'FAILED') {
-        throw new KitError({
-            ...NetworkError.RELAYER_FORWARD_FAILED,
-            recoverability: 'RESUMABLE',
-            message: 'Circle relayer failed to forward the mint transaction. The mint may still have succeeded if another party submitted it. Check the recipient wallet balance before retrying. If the mint did not occur, you can manually submit it using the attestation data in the error cause.',
-            cause: {
-                trace: {
-                    eventNonce: message.eventNonce,
-                    attestation: message.attestation,
-                    message: message.message
-                }
-            }
-        });
-    }
-    // Check if mint is confirmed (or complete) with a valid transaction hash
-    // We accept both CONFIRMED and COMPLETE since COMPLETE implies CONFIRMED
-    if ((message.forwardState === 'CONFIRMED' || message.forwardState === 'COMPLETE') && typeof message.forwardTxHash === 'string' && message.forwardTxHash.trim().length > 0) {
-        return true;
-    }
-    // Still pending or not yet processed - throw RETRYABLE error to continue polling
-    throw new KitError({
-        ...NetworkError.RELAYER_PENDING,
-        recoverability: 'RETRYABLE',
-        message: 'Relayer mint not ready. Waiting for confirmation.'
-    });
-};
-/**
- * Polls the attestation API until the relayer's mint transaction is confirmed.
- *
- * This function is used when `useForwarder` is enabled. Instead of the user
- * submitting the mint transaction, Circle's Orbit relayer handles it automatically.
- * This function polls until the relayer has submitted and confirmed the mint transaction.
- *
- * @remarks
- * - Uses a 20-minute timeout by default (600 retries × 2 seconds)
- * - Throws immediately if `forwardState` is 'FAILED'
- * - Waits for `forwardState` to be 'CONFIRMED' or 'COMPLETE' (COMPLETE implies CONFIRMED)
- * - Returns the attestation message with `forwardTxHash` populated
- *
- * @param sourceDomainId - The CCTP domain ID of the source chain
- * @param transactionHash - The transaction hash of the burn operation
- * @param isTestnet - Whether this is for a testnet chain (true) or mainnet (false)
- * @param config - Optional configuration overrides for polling behavior
- * @returns The attestation message with confirmed forwardTxHash
- * @throws {KitError} With code 'NETWORK_RELAYER_FORWARD_FAILED' if relayer failed
- * @throws {KitError} If timeout is reached while still pending
- *
- * @example
- * ```typescript
- * const attestation = await fetchRelayerMint(0, '0xabc...', false)
- * console.log('Relayer mint tx:', attestation.forwardTxHash)
- * ```
- */ const fetchRelayerMint = async (sourceDomainId, transactionHash, isTestnet, config = {})=>{
-    const url = buildIrisUrl(sourceDomainId, transactionHash, isTestnet);
-    const effectiveConfig = {
-        ...DEFAULT_CONFIG,
-        ...config
-    };
-    let response;
-    try {
-        response = await pollApiGet(url, isRelayerMintConfirmed, effectiveConfig);
-    } catch (error) {
-        // Enrich RELAYER_FORWARD_FAILED errors with the burn transaction hash
-        if (error instanceof KitError && error.name === 'NETWORK_RELAYER_FORWARD_FAILED') {
-            throw new KitError({
-                ...NetworkError.RELAYER_FORWARD_FAILED,
-                recoverability: error.recoverability,
-                message: error.message,
-                cause: {
-                    ...error.cause,
-                    trace: {
-                        ...error.cause?.trace,
-                        burnTxHash: transactionHash
-                    }
-                }
-            });
-        }
-        throw error;
-    }
-    // Return the first message (which should have forwardTxHash)
-    // Note: This check is needed for TypeScript type safety even though
-    // isRelayerMintConfirmed validates messages[0] exists. The type guard
-    // narrows the type at the call site, but TypeScript can't infer that
-    // the array still has elements after pollApiGet returns.
-    const message = response.messages[0];
-    if (!message) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'No attestation messages found in response after polling.'
-        });
-    }
-    return message;
-};
-
 /**
  * Executes the mint step for forwarding mode where Circle's relayer handles the mint.
  *
@@ -13780,6 +13925,7 @@ const mockAttestationMessage = {
  * immediately after the API confirms the mint.
  *
  * @param params - The bridge parameters containing source, destination, amount and config
+ * @param provider - The CCTP v2 bridging provider
  * @param context - The step context containing burnTxHash from the burn step
  * @returns Promise resolving to the bridge step with transaction details
  * @throws {KitError} If burnTxHash is not available in context
@@ -13788,10 +13934,13 @@ const mockAttestationMessage = {
  *
  * @example
  * ```typescript
- * const step = await bridgeRelayerMint(params, { burnTxHash: '0x...' })
+ * const step = await bridgeRelayerMint(
+ *   { params, provider },
+ *   { burnTxHash: '0x...' }
+ * )
  * console.log('Relayer mint tx:', step.txHash)
  * ```
- */ async function bridgeRelayerMint(params, context) {
+ */ async function bridgeRelayerMint({ params, provider }, context) {
     const step = {
         name: 'mint',
         state: 'pending',
@@ -13807,7 +13956,7 @@ const mockAttestationMessage = {
     }
     try {
         // Poll attestation API until relayer confirms the mint
-        const attestation = await fetchRelayerMint(params.source.chain.cctp.domain, context.burnTxHash, params.source.chain.isTestnet ?? false);
+        const attestation = await provider.fetchRelayerMint(params.source, context.burnTxHash);
         // Extract the relayer's mint transaction hash
         const forwardTxHash = attestation.forwardTxHash;
         if (!forwardTxHash) {
@@ -13901,7 +14050,7 @@ const mockAttestationMessage = {
             name: 'mint',
             // bridgeRelayerMint validates context.burnTxHash internally with a KitError
             // bridgeMint requires attestationData which is validated here
-            executor: useForwarder ? async (params, _provider, context)=>{
+            executor: useForwarder ? async (params, provider, context)=>{
                 if (!context) {
                     throw new KitError({
                         ...InputError.VALIDATION_FAILED,
@@ -13909,7 +14058,10 @@ const mockAttestationMessage = {
                         message: 'Step context is required for relayer mint'
                     });
                 }
-                return bridgeRelayerMint(params, context);
+                return bridgeRelayerMint({
+                    params,
+                    provider
+                }, context);
             } : async (params, provider, context)=>{
                 if (!context?.attestationData) {
                     throw new KitError({
@@ -14240,7 +14392,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$2 = "1.8.4";
+var version$2 = "1.9.0";
 var pkg$2 = {
 	version: version$2};
 
@@ -14946,6 +15098,39 @@ var pkg$2 = {
     }
 }
 
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function assertHeadersConfig(headers, field) {
+    if (headers === undefined) {
+        return;
+    }
+    if (!isPlainObject(headers)) {
+        throw createValidationFailedError$1(field, headers, `${field} must be a plain object with string header values when provided`);
+    }
+    for (const [name, value] of Object.entries(headers)){
+        if (typeof value !== 'string') {
+            throw createValidationFailedError$1(`${field}.${name}`, value, 'header values must be strings');
+        }
+    }
+}
+function assertCCTPV2Config(config) {
+    if (!isPlainObject(config)) {
+        throw createValidationFailedError$1('config', config, 'config must be a plain object when provided');
+    }
+    assertHeadersConfig(config['headers'], 'config.headers');
+    const attestation = config['attestation'];
+    if (attestation !== undefined) {
+        if (!isPlainObject(attestation)) {
+            throw createValidationFailedError$1('config.attestation', attestation, 'config.attestation must be a plain object when provided');
+        }
+        assertHeadersConfig(attestation['headers'], 'config.attestation.headers');
+    }
+}
 /**
  * All chains that are supported by the CCTP v2 provider.
  *
@@ -15014,9 +15199,38 @@ var pkg$2 = {
    * @param config - Optional configuration overrides for the provider
    */ constructor(config = {}){
         super();
+        assertCCTPV2Config(config);
         this.config = config;
     }
     /**
+   * Resolves the effective polling configuration for an attestation request.
+   *
+   * Precedence (lowest to highest): provider `config.attestation`, then the
+   * per-call `config`. Headers merge independently across
+   * `config.attestation.headers`, the provider-level `config.headers`, and any
+   * per-call `config.headers`, so a more specific header augments rather than
+   * replaces the broader ones. The `headers` key is omitted entirely when no
+   * headers are configured, leaving the attestation fetchers' defaults intact.
+   *
+   * @param config - Optional per-call polling configuration overrides
+   * @returns The merged polling configuration passed to the attestation fetchers
+   */ resolveAttestationConfig(config) {
+        const headers = {
+            ...this.config?.attestation?.headers,
+            ...this.config?.headers,
+            ...config?.headers
+        };
+        // Polling fields follow normal precedence; headers are merged separately
+        // below so narrower config layers augment rather than replace broader ones.
+        return {
+            ...this.config?.attestation,
+            ...config,
+            ...Object.keys(headers).length > 0 ? {
+                headers
+            } : {}
+        };
+    }
+    /**
    * Execute a cross-chain USDC bridge operation using the CCTP v2 protocol.
    *
    * This method orchestrates the complete CCTP v2 bridge flow including validation,
@@ -15442,11 +15656,7 @@ var pkg$2 = {
    */ async fetchAttestation(source, transactionHash, config) {
         assertCCTPv2WalletContext(source);
         try {
-            // Merge configs: defaults <- global config <- per-call config
-            const effectiveConfig = {
-                ...this.config?.attestation,
-                ...config
-            };
+            const effectiveConfig = this.resolveAttestationConfig(config);
             const response = await fetchAttestation(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
             const message = response.messages[0];
             if (!message) {
@@ -15463,6 +15673,49 @@ var pkg$2 = {
         }
     }
     /**
+   * Polls attestation data until Circle's relayer mint transaction is confirmed.
+   *
+   * This method is used by forwarded transfers. It polls the same Iris
+   * attestation endpoint as {@link CCTPV2BridgingProvider.fetchAttestation},
+   * but waits for a completed relayer forward state and returns the attestation
+   * message containing `forwardTxHash`.
+   *
+   * @typeParam TFromAdapterCapabilities - The type representing the capabilities of the source adapter
+   * @param source - The source wallet context containing the chain definition and wallet address
+   * @param transactionHash - The transaction hash of the burn operation
+   * @param config - Optional polling configuration overrides for timeout, retries, delay, and headers
+   * @returns A promise that resolves to the attestation message with `forwardTxHash`
+   * @throws KitError If the relayer forward fails, the response is invalid, or polling times out
+   *
+   * @example
+   * ```typescript
+   * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+   * import { Chains } from '@core/chains'
+   *
+   * const provider = new CCTPV2BridgingProvider({
+   *   headers: { 'X-Partner-UUID': '00000000-0000-0000-0000-000000000000' },
+   * })
+   *
+   * const attestation = await provider.fetchRelayerMint(
+   *   {
+   *     adapter,
+   *     chain: Chains.EthereumSepolia,
+   *     address: '0x1234...',
+   *   },
+   *   '0xabc123...',
+   * )
+   *
+   * console.log('Relayer mint tx:', attestation.forwardTxHash)
+   * ```
+   */ async fetchRelayerMint(source, transactionHash, config) {
+        assertCCTPv2WalletContext(source);
+        if (typeof transactionHash !== 'string' || transactionHash.trim() === '') {
+            throw createValidationFailedError$1('transactionHash', transactionHash, 'transactionHash must be a non-empty string');
+        }
+        const effectiveConfig = this.resolveAttestationConfig(config);
+        return await fetchRelayerMint(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
+    }
+    /**
    * Requests a fresh attestation for an expired attestation.
    *
    * This method is used when the original attestation has expired before the mint
@@ -15516,11 +15769,7 @@ var pkg$2 = {
             throw new Error('Failed to re-attest: Invalid transaction hash');
         }
         try {
-            // Merge configs: defaults <- global config <- per-call config
-            const effectiveConfig = {
-                ...this.config?.attestation,
-                ...config
-            };
+            const effectiveConfig = this.resolveAttestationConfig(config);
             // Step 1: Get existing attestation data to extract nonce
             const existingAttestation = await fetchAttestationWithoutStatusCheck(source.chain.cctp.domain, transactionHash, source.chain.isTestnet, effectiveConfig);
             const nonce = existingAttestation.messages[0]?.eventNonce;
@@ -15805,8 +16054,13 @@ var pkg$2 = {
 /**
  * The default providers that will be used in addition to the providers provided
  * to the BridgeKit constructor.
- */ const getDefaultProviders = ()=>[
-        new CCTPV2BridgingProvider()
+ *
+ * @param config - Optional configuration forwarded to the default providers
+ * @returns The default bridging providers
+ */ const getDefaultProviders = (config = {})=>[
+        new CCTPV2BridgingProvider(config.headers ? {
+            headers: config.headers
+        } : {})
     ];
 
 /**
@@ -16049,7 +16303,9 @@ var pkg$2 = {
    * ```
    */ constructor(config = {}){
         // Handle provider configuration
-        const defaultProviders = getDefaultProviders();
+        const defaultProviders = getDefaultProviders(config.headers ? {
+            headers: config.headers
+        } : {});
         this.providers = [
             ...defaultProviders,
             ...config.providers ?? []
@@ -16629,6 +16885,9 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
     const kit = new BridgeKit({
         ...context.disableErrorReporting != null && {
             disableErrorReporting: context.disableErrorReporting
+        },
+        ...context.headers != null && {
+            headers: context.headers
         }
     });
     if (hasBoth) {
@@ -16647,7 +16906,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.3.0";
+var version$1 = "1.3.2";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -18575,7 +18834,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
 var name = "@circle-fin/earn-kit";
-var version = "1.2.0";
+var version = "1.2.2";
 var pkg = {
 	name: name,
 	version: version};
@@ -18614,20 +18873,7 @@ var pkg = {
  */ ({
     [Blockchain.Arc_Testnet]: CHAIN_TO_API[Blockchain.Arc_Testnet]
 });
-/**
- * Expected EIP-712 domain of the ERC-3009 authorization token per source
- * chain.
- *
- * Cross-chain Earn deposits are USDC-only, but USDC deployments differ on the
- * EIP-712 domain name: newer deployments use `USDC` while older ones (for
- * example Arbitrum Sepolia) kept `USD Coin` from the FiatToken V2 upgrade.
- * These values mirror the bridge service's per-chain domain table and the
- * on-chain `DOMAIN_SEPARATOR` inputs. Asserted before signing so a tampered
- * prepare response cannot point the signature at another token. The
- * `satisfies` check forces a domain entry whenever a source chain is added.
- *
- * @internal
- */ ({
+({
     [Blockchain.Arbitrum_Sepolia]: {
         },
     [Blockchain.Base_Sepolia]: {
@@ -18663,6 +18909,7 @@ const hexSignatureSchema = evmSignatureSchema;
 const hexAddressSchema = evmAddressSchema;
 // '0x' prefix + 32 bytes * 2 hex chars.
 const BYTES32_HEX_LENGTH = 66;
+const bridgeFeeTokenSchema = hexAddressSchema;
 /**
  * Zod schema for a non-negative uint256-like value.
  *
@@ -18949,14 +19196,12 @@ const eip712DomainSchema = eip712DomainSchema$1.extend({
  *
  * The bridge prepare path returns one item per collected source fee (e.g.
  * `PRE_FINALITY` for the fast-burn fee and `FORWARD` for the destination
- * forward fee), all denominated in the shared `feeToken`. The signed
- * authorization `value` is `principal + sum(items[].amount)`, so the pre-sign
- * guard parses these to recompute the expected value. Each item's `amount` is
- * a base-unit decimal string in `feeToken` units.
+ * forward fee), all denominated in the shared `feeToken`. Each item's `amount`
+ * is a base-unit decimal string in `feeToken` units.
  *
  * @internal
  */ const bridgeFeeQuoteSchema = z.object({
-    feeToken: hexAddressSchema,
+    feeToken: bridgeFeeTokenSchema,
     items: z.array(z.object({
         type: z.string(),
         amount: uint256LikeSchema
@@ -18972,6 +19217,12 @@ const eip712DomainSchema = eip712DomainSchema$1.extend({
     erc3009TypedData: erc3009TypedDataSchema,
     feeQuote: bridgeFeeQuoteSchema
 }).passthrough();
+const bridgeDepositPrepareReviewSchema = z.object({
+    sourceChain: z.string(),
+    destinationChain: z.string(),
+    amount: amountJsonSchema,
+    vaultAddress: hexAddressSchema
+}).passthrough();
 /**
  * Zod schema for the bridge deposit prepare payload.
  *
@@ -18983,7 +19234,7 @@ const eip712DomainSchema = eip712DomainSchema$1.extend({
     execId: bridgeDepositExecIdSchema,
     erc3009TypedData: bridgeDepositPreparedBundleSchema,
     expiresAt: z.string().datetime(),
-    review: z.unknown().optional()
+    review: bridgeDepositPrepareReviewSchema
 });
 /**
  * Zod schema for the `POST /v1/earnKit/bridge/deposit/prepare` API response.
@@ -19108,10 +19359,11 @@ const eip712DomainSchema = eip712DomainSchema$1.extend({
  * Zod schema for a fee entry in an EarnKit API response.
  *
  * Shared across deposit and withdrawal responses (and reusable for real
- * charged fees, not just quote estimates). `type` identifies the fee category —
- * for cross-chain deposit quotes this is the kits-proxy fee-quote item type
- * (e.g. `'FORWARD'`, `'PRE_FINALITY'`). `status` qualifies the fee (e.g.
- * `'estimated'` for a pre-sign cross-chain fee). Both are omitted on plain fees.
+ * charged fees, not just quote estimates). `type` identifies the fee category.
+ * For cross-chain deposit quotes this is the kits-proxy fee-quote item type
+ * (e.g. `'FORWARD'`, `'PRE_FINALITY'`). For withdrawal quotes, Circle fees use
+ * `type: 'circle'`. `status` qualifies the fee (e.g. `'estimated'` for a
+ * pre-sign cross-chain fee). Both are omitted on plain fees.
  *
  * @internal
  */ const feeSchema = z.object({
@@ -19262,6 +19514,10 @@ const eip712DomainSchema = eip712DomainSchema$1.extend({
     data: exploreVaultsPayloadSchema
 });
 
+// Intentionally built-ins-only: Earn bridge support is limited to SDK-known
+// token contracts plus the explicit ERC-3009 domain allowlist below.
+createTokenRegistry();
+
 /**
  * Shared UTF-8 encoder for building the keccak input in
  * {@link isValidEip55Checksum}, hoisted to module scope to avoid allocating a
@@ -19384,10 +19640,9 @@ const sourceAdapterContextSchema = z.object({
  * Schema for validating human-readable decimal amount strings.
  *
  * Accept positive decimal strings like '100', '100.50', '0.001'. Reject
- * zero, negative, non-numeric, and non-canonical strings. EarnKit
- * same-chain amounts are USDC/EURC (6 decimals), so precision is capped at
- * 6 to match the Earn Service and fail fast locally instead of leaking
- * 7+ decimal-place inputs to the server.
+ * zero, negative, non-numeric, and non-canonical strings. Same-chain
+ * EarnKit vaults can use different asset precisions, so the service enforces
+ * the vault-specific decimal cap after resolving the vault asset.
  *
  * @internal
  */ const amountSchema = z.string({
@@ -19396,32 +19651,15 @@ const sourceAdapterContextSchema = z.object({
     allowZero: false,
     regexMessage: AMOUNT_FORMAT_ERROR_MESSAGE,
     attributeName: 'amount',
-    maxDecimals: 6
-})(z.string())).refine((value)=>CANONICAL_AMOUNT_REGEX.test(value), AMOUNT_FORMAT_ERROR_MESSAGE);
-/**
- * Schema for cross-chain deposit amount strings.
- *
- * Cross-chain Earn deposits are USDC-only, and the signed ERC-3009 value is
- * denominated in USDC's 6 decimals. Reject more precise inputs up front so
- * the signed value always equals the requested amount instead of a silent
- * truncation. Non-canonical forms (leading dot, leading zeros) are rejected
- * too, matching the Earn Service.
- *
- * @internal
- */ const crossChainAmountSchema = z.string({
-    required_error: 'amount is required'
-}).min(1, 'amount is required').pipe(createDecimalStringValidator({
-    allowZero: false,
-    regexMessage: AMOUNT_FORMAT_ERROR_MESSAGE,
-    attributeName: 'amount',
-    maxDecimals: 6
+    maxDecimals: 18
 })(z.string())).refine((value)=>CANONICAL_AMOUNT_REGEX.test(value), AMOUNT_FORMAT_ERROR_MESSAGE);
 /**
  * Schema for cross-chain source fee caps.
  *
- * Cross-chain source fees are denominated in USDC base units. Zero is valid
- * when the quote contains no source-collected fees; otherwise the cap should be
- * the caller-accepted total from a recent quote.
+ * Cross-chain source fees are denominated in the quote's fee token. Zero is
+ * valid when the quote contains no source-collected fees; otherwise the cap
+ * should be the caller-accepted total from a recent quote. The provider
+ * enforces the prepared bundle's fee-token precision before signing.
  *
  * @internal
  */ const crossChainMaxFeeSchema = z.string({
@@ -19430,7 +19668,7 @@ const sourceAdapterContextSchema = z.object({
     allowZero: true,
     regexMessage: AMOUNT_FORMAT_ERROR_MESSAGE,
     attributeName: 'maxFee',
-    maxDecimals: 6
+    maxDecimals: 18
 })(z.string())).refine((value)=>CANONICAL_AMOUNT_REGEX.test(value), AMOUNT_FORMAT_ERROR_MESSAGE);
 /**
  * Build a schema for an optional non-negative decimal filter string.
@@ -19591,7 +19829,7 @@ const crossChainDepositDestinationSchema = z.object({
     from: sourceAdapterContextSchema,
     to: crossChainDepositDestinationSchema,
     vaultAddress: vaultAddressSchema,
-    amount: crossChainAmountSchema,
+    amount: amountSchema,
     maxFee: crossChainMaxFeeSchema,
     transferSpeed: z.enum([
         'FAST',