@circle-fin/provider-cctp-v2 1.6.3 → 1.8.0

package/index.mjs

@@ -74,6 +74,8 @@ var Blockchain;
     Blockchain["Hedera_Testnet"] = "Hedera_Testnet";
     Blockchain["HyperEVM"] = "HyperEVM";
     Blockchain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    Blockchain["Injective"] = "Injective";
+    Blockchain["Injective_Testnet"] = "Injective_Testnet";
     Blockchain["Ink"] = "Ink";
     Blockchain["Ink_Testnet"] = "Ink_Testnet";
     Blockchain["Linea"] = "Linea";
@@ -88,6 +90,8 @@ var Blockchain;
     Blockchain["Noble_Testnet"] = "Noble_Testnet";
     Blockchain["Optimism"] = "Optimism";
     Blockchain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    Blockchain["Pharos"] = "Pharos";
+    Blockchain["Pharos_Testnet"] = "Pharos_Testnet";
     Blockchain["Polkadot_Asset_Hub"] = "Polkadot_Asset_Hub";
     Blockchain["Polkadot_Westmint"] = "Polkadot_Westmint";
     Blockchain["Plume"] = "Plume";
@@ -291,11 +295,13 @@ var BridgeChain;
     BridgeChain["Edge"] = "Edge";
     BridgeChain["Ethereum"] = "Ethereum";
     BridgeChain["HyperEVM"] = "HyperEVM";
+    BridgeChain["Injective"] = "Injective";
     BridgeChain["Ink"] = "Ink";
     BridgeChain["Linea"] = "Linea";
     BridgeChain["Monad"] = "Monad";
     BridgeChain["Morph"] = "Morph";
     BridgeChain["Optimism"] = "Optimism";
+    BridgeChain["Pharos"] = "Pharos";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
     BridgeChain["Sei"] = "Sei";
@@ -313,11 +319,13 @@ var BridgeChain;
     BridgeChain["Edge_Testnet"] = "Edge_Testnet";
     BridgeChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    BridgeChain["Injective_Testnet"] = "Injective_Testnet";
     BridgeChain["Ink_Testnet"] = "Ink_Testnet";
     BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
     BridgeChain["Monad_Testnet"] = "Monad_Testnet";
     BridgeChain["Morph_Testnet"] = "Morph_Testnet";
     BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    BridgeChain["Pharos_Testnet"] = "Pharos_Testnet";
     BridgeChain["Plume_Testnet"] = "Plume_Testnet";
     BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
     BridgeChain["Sei_Testnet"] = "Sei_Testnet";
@@ -663,6 +671,12 @@ const SWAP_TOKEN_REGISTRY = {
         category: 'wrapped',
         description: 'Wrapped Polygon',
     },
+    CIRBTC: {
+        symbol: 'CIRBTC',
+        decimals: 8,
+        category: 'wrapped',
+        description: 'Circle Bitcoin',
+    },
 };
 /**
  * Special NATIVE token constant for swap operations.
@@ -1725,6 +1739,98 @@ const HyperEVMTestnet = defineChain({
     },
 });
 
+/**
+ * Injective Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Injective blockchain.
+ * Injective is a high-performance, interoperable Layer-1 blockchain built for
+ * finance, with an EVM execution layer on top of a Cosmos SDK base and
+ * sub-second block finality.
+ */
+const Injective = defineChain({
+    type: 'evm',
+    chain: Blockchain.Injective,
+    name: 'Injective',
+    title: 'Injective Mainnet',
+    nativeCurrency: {
+        name: 'Injective',
+        symbol: 'INJ',
+        decimals: 18,
+    },
+    chainId: 1776,
+    isTestnet: false,
+    explorerUrl: 'https://injscan.com/transaction/{hash}',
+    rpcEndpoints: ['https://sentry.evm-rpc.injective.network'],
+    eurcAddress: null,
+    usdcAddress: '0xa00C59fF5a080D2b954d0c75e46E22a0c371235a',
+    usdtAddress: null,
+    cctp: {
+        domain: 29,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Injective Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Injective blockchain.
+ * Injective is a high-performance, interoperable Layer-1 blockchain built for
+ * finance, with an EVM execution layer on top of a Cosmos SDK base and
+ * sub-second block finality.
+ */
+const InjectiveTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Injective_Testnet,
+    name: 'Injective Testnet',
+    title: 'Injective Testnet',
+    nativeCurrency: {
+        name: 'Injective',
+        symbol: 'INJ',
+        decimals: 18,
+    },
+    chainId: 1439,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.explorer.injective.network/transaction/{hash}',
+    rpcEndpoints: ['https://k8s.testnet.json-rpc.injective.network'],
+    eurcAddress: null,
+    usdcAddress: '0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d',
+    usdtAddress: null,
+    cctp: {
+        domain: 29,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * Ink Mainnet chain definition
  * @remarks
@@ -2334,6 +2440,96 @@ const OptimismSepolia = defineChain({
     },
 });
 
+/**
+ * Pharos Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Pharos blockchain.
+ * Pharos is a modular, full-stack parallel Layer 1 blockchain with
+ * sub-second finality and EVM compatibility.
+ */
+const Pharos = defineChain({
+    type: 'evm',
+    chain: Blockchain.Pharos,
+    name: 'Pharos',
+    title: 'Pharos Mainnet',
+    nativeCurrency: {
+        name: 'Pharos',
+        symbol: 'PHAROS',
+        decimals: 18,
+    },
+    chainId: 1672,
+    isTestnet: false,
+    explorerUrl: 'https://pharos.socialscan.io/tx/{hash}',
+    rpcEndpoints: ['https://rpc.pharos.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0xC879C018dB60520F4355C26eD1a6D572cdAC1815',
+    usdtAddress: null,
+    cctp: {
+        domain: 31,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Pharos Atlantic Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Pharos blockchain.
+ * Pharos is a modular, full-stack parallel Layer 1 blockchain with
+ * sub-second finality and EVM compatibility.
+ */
+const PharosTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Pharos_Testnet,
+    name: 'Pharos Atlantic',
+    title: 'Pharos Atlantic Testnet',
+    nativeCurrency: {
+        name: 'Pharos',
+        symbol: 'PHAROS',
+        decimals: 18,
+    },
+    chainId: 688689,
+    isTestnet: true,
+    explorerUrl: 'https://atlantic.pharosscan.xyz/tx/{hash}',
+    rpcEndpoints: ['https://atlantic.dplabs-internal.com'],
+    eurcAddress: null,
+    usdcAddress: '0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B',
+    usdtAddress: null,
+    cctp: {
+        domain: 31,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * Plume Mainnet chain definition
  * @remarks
@@ -2616,7 +2812,7 @@ const Sei = defineChain({
     },
     chainId: 1329,
     isTestnet: false,
-    explorerUrl: 'https://seitrace.com/tx/{hash}?chain=pacific-1',
+    explorerUrl: 'https://seiscan.io/tx/{hash}',
     rpcEndpoints: ['https://evm-rpc.sei-apis.com'],
     eurcAddress: null,
     usdcAddress: '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392',
@@ -2674,7 +2870,7 @@ const SeiTestnet = defineChain({
     },
     chainId: 1328,
     isTestnet: true,
-    explorerUrl: 'https://seitrace.com/tx/{hash}?chain=atlantic-2',
+    explorerUrl: 'https://testnet.seiscan.io/tx/{hash}',
     rpcEndpoints: ['https://evm-rpc-testnet.sei-apis.com'],
     eurcAddress: null,
     usdcAddress: '0x4fCF1784B31630811181f670Aea7A7bEF803eaED',
@@ -3477,6 +3673,8 @@ var Chains = /*#__PURE__*/Object.freeze({
     HederaTestnet: HederaTestnet,
     HyperEVM: HyperEVM,
     HyperEVMTestnet: HyperEVMTestnet,
+    Injective: Injective,
+    InjectiveTestnet: InjectiveTestnet,
     Ink: Ink,
     InkTestnet: InkTestnet,
     Linea: Linea,
@@ -3491,6 +3689,8 @@ var Chains = /*#__PURE__*/Object.freeze({
     NobleTestnet: NobleTestnet,
     Optimism: Optimism,
     OptimismSepolia: OptimismSepolia,
+    Pharos: Pharos,
+    PharosTestnet: PharosTestnet,
     Plume: Plume,
     PlumeTestnet: PlumeTestnet,
     PolkadotAssetHub: PolkadotAssetHub,
@@ -4995,6 +5195,9 @@ const NetworkError = {
         name: 'NETWORK_CONNECTION_FAILED',
         type: 'NETWORK',
     },
+    /** Network request timeout */
+    TIMEOUT: {
+        code: 3002},
     /** Circle relayer failed to process the forwarding/mint transaction */
     RELAYER_FORWARD_FAILED: {
         code: 3003,
@@ -7171,6 +7374,7 @@ const USDC = {
         [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
         [Blockchain.Hedera]: '0.0.456858',
         [Blockchain.HyperEVM]: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
+        [Blockchain.Injective]: '0xa00C59fF5a080D2b954d0c75e46E22a0c371235a',
         [Blockchain.Ink]: '0x2D270e6886d130D724215A266106e6832161EAEd',
         [Blockchain.Linea]: '0x176211869ca2b568f2a7d4ee941e073a821ee1ff',
         [Blockchain.Monad]: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
@@ -7178,6 +7382,7 @@ const USDC = {
         [Blockchain.NEAR]: '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1',
         [Blockchain.Noble]: 'uusdc',
         [Blockchain.Optimism]: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
+        [Blockchain.Pharos]: '0xC879C018dB60520F4355C26eD1a6D572cdAC1815',
         [Blockchain.Plume]: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
         [Blockchain.Polkadot_Asset_Hub]: '1337',
         [Blockchain.Polygon]: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
@@ -7202,6 +7407,7 @@ const USDC = {
         [Blockchain.Ethereum_Sepolia]: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
         [Blockchain.Hedera_Testnet]: '0.0.429274',
         [Blockchain.HyperEVM_Testnet]: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
+        [Blockchain.Injective_Testnet]: '0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d',
         [Blockchain.Ink_Testnet]: '0xFabab97dCE620294D2B0b0e46C68964e326300Ac',
         [Blockchain.Linea_Sepolia]: '0xfece4462d57bd51a6a552365a011b95f0e16d9b7',
         [Blockchain.Monad_Testnet]: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
@@ -7209,6 +7415,7 @@ const USDC = {
         [Blockchain.NEAR_Testnet]: '3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af',
         [Blockchain.Noble_Testnet]: 'uusdc',
         [Blockchain.Optimism_Sepolia]: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
+        [Blockchain.Pharos_Testnet]: '0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B',
         [Blockchain.Plume_Testnet]: '0xcB5f30e335672893c7eb944B374c196392C19D18',
         [Blockchain.Polkadot_Westmint]: '31337',
         [Blockchain.Polygon_Amoy_Testnet]: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
@@ -7489,6 +7696,32 @@ const MON = {
     },
 };
 
+/**
+ * cirBTC (Circle Bitcoin) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in cirBTC definition for the TokenRegistry. Currently deployed
+ * on Arc Testnet.
+ *
+ * @example
+ * ```typescript
+ * import { CIRBTC } from '@core/tokens'
+ * import { Blockchain } from '@core/chains'
+ *
+ * console.log(CIRBTC.symbol)   // 'cirBTC'
+ * console.log(CIRBTC.decimals) // 8
+ * console.log(CIRBTC.locators[Blockchain.Arc_Testnet])
+ * // '0xf0C4a4CE82A5746AbAAd9425360Ab04fbBA432BF'
+ * ```
+ */
+const CIRBTC = {
+    symbol: 'cirBTC',
+    decimals: 8,
+    locators: {
+        [Blockchain.Arc_Testnet]: '0xf0C4a4CE82A5746AbAAd9425360Ab04fbBA432BF',
+    },
+};
+
 // Re-export for consumers
 /**
  * All default token definitions.
@@ -7497,7 +7730,7 @@ const MON = {
  * These tokens are automatically included in the TokenRegistry when created
  * without explicit defaults. Extensions can override these definitions.
  * Includes USDC, USDT, EURC, DAI, USDE, PYUSD, WETH, WBTC, WSOL, WAVAX,
- * WPOL, ETH, POL, PLUME, and MON.
+ * WPOL, ETH, POL, PLUME, MON, and cirBTC.
  *
  * @example
  * ```typescript
@@ -7528,6 +7761,7 @@ const DEFAULT_TOKENS = [
     POL,
     PLUME,
     MON,
+    CIRBTC,
 ];
 /**
  * Uppercased token symbols approved for swap fee collection.
@@ -9138,18 +9372,16 @@ const buildIrisUrl = (sourceDomainId, transactionHash, isTestnet) => {
 };
 /**
  * Fetches attestation data from the IRIS API with retry and timeout handling.
- * Since fetching starts after a confirmed burn transaction, we attempt up to 10 retries.
- * Implements a conservative delay between requests to respect the API rate
- * limit of 35 requests per second. To avoid rate limiting when multiple processes are
- * running concurrently, we enforce a 200ms delay between retries.
  *
- * Each HTTP request is given a maximum of 2 seconds before it is aborted.
- * We retry up to 10 times, waiting 200ms between attempts.
+ * Polls the IRIS API until a complete attestation is available. The default
+ * window is sized for slow source chains where finality may take many
+ * confirmations.
  *
- * The total maximum time this function might take (worst case) is:
- * - Per‐attempt timeout: 2 000 ms
- * - Retry delays: 9 × 200 ms = 1 800 ms
- * - Total max time: 2 000 ms + 1 800 ms = 3 800 ms
+ * Defaults (see `DEFAULT_CONFIG`):
+ * - Per-attempt timeout: 2 000 ms (each HTTP request aborts after 2 s)
+ * - Retry delay: 2 000 ms between attempts
+ * - Max retries: 600 (30 × 20)
+ * - Total worst-case polling window: 600 × (2 000 ms + 2 000 ms) ≈ 40 minutes
  *
  * @param sourceDomainId - The CCTP domain ID.
  * @param transactionHash - The transaction hash to fetch attestation for.
@@ -10304,11 +10536,18 @@ async function executePreparedChainRequest({ name, request, adapter, chain, conf
         step.explorerUrl = buildExplorerUrl(chain, txHash);
         if (outcome.errorMessage) {
             step.errorMessage = outcome.errorMessage;
+            // Transaction was mined but reverted on-chain.
+            step.errorCategory = 'chain_revert';
         }
     }
     catch (err) {
         step.state = 'error';
         step.error = err;
+        // Sequential path does not yet attempt fine-grained classification of
+        // pre-submission errors (user_rejected, capability errors, etc.). Mark
+        // as `unknown` so consumers can at least detect the category is
+        // populated uniformly across batched and sequential flows.
+        step.errorCategory = 'unknown';
         // Optionally parse for common blockchain error formats
         if (err instanceof Error) {
             step.errorMessage = err.message;
@@ -11857,16 +12096,70 @@ async function executeBatchedApproveAndBurn(params, provider) {
     const batchResult = await adapter.batchExecute([approveCallData, burnCallData], chain);
     const approveReceipt = batchResult.receipts[0];
     const burnReceipt = batchResult.receipts[1];
-    const approveStep = await buildBatchedStep('approve', approveReceipt, batchResult.batchId, adapter, chain);
-    const burnStep = await buildBatchedStep('burn', burnReceipt, batchResult.batchId, adapter, chain);
+    const approveStep = await buildBatchedStep('approve', approveReceipt, batchResult.batchId, adapter, chain, batchResult.statusCode, batchResult.error);
+    const burnStep = await buildBatchedStep('burn', burnReceipt, batchResult.batchId, adapter, chain, batchResult.statusCode, batchResult.error);
     if (burnStep.state !== 'error' && !burnStep.txHash) {
         burnStep.state = 'error';
         burnStep.errorMessage =
             'Batched burn step completed but no transaction hash was returned.';
+        burnStep.errorCategory = 'unknown';
     }
     const context = { burnTxHash: burnStep.txHash ?? '' };
     return { approveStep, burnStep, context };
 }
+/**
+ * Derive a {@link BridgeStepErrorCategory} for a missing receipt.
+ *
+ * Combines the EIP-5792 `statusCode` (when present) with the underlying
+ * polling error (when set) to produce the most specific category available.
+ * Falls back to `'unknown'` when neither signal is conclusive.
+ *
+ * @param statusCode - The terminal `statusCode` from `wallet_getCallsStatus`, if any.
+ * @param batchError - The polling error from `batchExecute`, if any.
+ * @returns The derived error category for a missing-receipt step.
+ *
+ * @internal
+ */
+function categorizeMissingReceipt(statusCode, batchError) {
+    if (statusCode === 400)
+        return 'failed_offchain';
+    if (statusCode === 500)
+        return 'reverted_onchain';
+    if (statusCode === 600)
+        return 'partial_reverted';
+    if (batchError instanceof KitError &&
+        batchError.code === NetworkError.TIMEOUT.code) {
+        return 'polling_timeout';
+    }
+    return 'unknown';
+}
+/**
+ * Derive a {@link BridgeStepErrorCategory} for a receipt that was returned
+ * but whose per-call `status` is not `'success'`.
+ *
+ * A numeric EIP-5792 `statusCode` of 500 or 600 tells us the whole batch
+ * reverted on-chain (completely or partially); otherwise the receipt
+ * itself signalled a revert without a distinguishing code, so classify
+ * as a plain on-chain revert.
+ *
+ * @param statusCode - The terminal `statusCode` from `wallet_getCallsStatus`, if any.
+ * @returns The derived error category for a failed-receipt step.
+ *
+ * @internal
+ */
+function categorizeFailedReceipt(statusCode) {
+    // Mirror categorizeMissingReceipt: if the wallet's terminal status is
+    // 400 ("batch not included onchain"), that judgement is authoritative
+    // even when a non-success receipt is attached. Without this, a wrapped
+    // 400 receipt would fall through to `chain_revert` and mislead UX.
+    if (statusCode === 400)
+        return 'failed_offchain';
+    if (statusCode === 600)
+        return 'partial_reverted';
+    if (statusCode === 500)
+        return 'reverted_onchain';
+    return 'chain_revert';
+}
 /**
  * Build a {@link BridgeStep} from a single receipt within a batch.
  *
@@ -11881,11 +12174,17 @@ async function executeBatchedApproveAndBurn(params, provider) {
  * @param batchId - Wallet-assigned batch identifier.
  * @param adapter - The batch-capable adapter (used for confirmation).
  * @param chain - The EVM chain the batch was executed on.
+ * @param statusCode - Optional EIP-5792 `statusCode` for the batch.
+ *   Used to classify the step's error category when the receipt is
+ *   missing or failed.
+ * @param batchError - Optional polling error from `batchExecute`.
+ *   Preserved on the step so callers can inspect underlying timeouts
+ *   or RPC failures.
  * @returns A fully-populated bridge step with state, tx hash and explorer URL.
  *
  * @internal
  */
-async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
+async function buildBatchedStep(name, receipt, batchId, adapter, chain, statusCode, batchError) {
     const step = {
         name,
         state: 'pending',
@@ -11895,6 +12194,10 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
     if (!receipt) {
         step.state = 'error';
         step.errorMessage = `No receipt returned for ${name} in batch ${batchId}.`;
+        step.errorCategory = categorizeMissingReceipt(statusCode, batchError);
+        if (batchError !== undefined) {
+            step.error = batchError;
+        }
         return step;
     }
     step.txHash = receipt.txHash;
@@ -11904,11 +12207,13 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
     if (receipt.status !== 'success') {
         step.state = 'error';
         step.errorMessage = `${name} call failed within batch ${batchId}.`;
+        step.errorCategory = categorizeFailedReceipt(statusCode);
         return step;
     }
     if (!receipt.txHash) {
         step.state = 'error';
         step.errorMessage = `${name} succeeded in batch but returned an empty transaction hash.`;
+        step.errorCategory = 'unknown';
         return step;
     }
     try {
@@ -11923,6 +12228,7 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
         step.data = transaction;
         if (outcome.errorMessage) {
             step.errorMessage = outcome.errorMessage;
+            step.errorCategory = 'chain_revert';
         }
     }
     catch (err) {
@@ -11930,11 +12236,12 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
         step.error = err;
         step.errorMessage =
             err instanceof Error ? err.message : 'Unknown error during confirmation.';
+        step.errorCategory = 'unknown';
     }
     return step;
 }
 
-var version = "1.6.3";
+var version = "1.8.0";
 var pkg = {
 	version: version};
 
@@ -12010,6 +12317,7 @@ async function executeBatchedPath(params, provider, result, invocation) {
             errorMessage: error_ instanceof Error
                 ? error_.message
                 : 'Batched approve + burn failed.',
+            errorCategory: classifyPreSubmissionError(error_),
         });
         return undefined;
     }
@@ -12024,6 +12332,89 @@ function ensureStepErrorMessage(name, step) {
         step.errorMessage = `${name} step failed: ${getErrorMessage(step.error)}`;
     }
 }
+/**
+ * Coerce a raw JSON-RPC `code` to a number.
+ *
+ * Some wallet SDKs serialize the JSON-RPC `code` as a string ("4001")
+ * after round-tripping through JSON; accept both shapes so strict `===`
+ * comparisons downstream still classify 5720/5730/5740 correctly — those
+ * codes have no message-pattern fallback.
+ *
+ * @param rawCode - The raw `code` extracted from the error object.
+ * @returns The numeric code, or `undefined` if the value cannot be parsed.
+ *
+ * @internal
+ */
+function coerceRpcCode(rawCode) {
+    if (typeof rawCode === 'number') {
+        return rawCode;
+    }
+    if (typeof rawCode === 'string') {
+        return Number.parseInt(rawCode, 10);
+    }
+    return undefined;
+}
+/**
+ * Classify a pre-submission error thrown during `wallet_sendCalls`.
+ *
+ * Inspect the error's JSON-RPC `code` (falling back to message pattern
+ * matching for wrapper errors like viem's `ChainMismatchError`) and map
+ * it to a {@link BridgeStepErrorCategory}. This lets downstream consumers
+ * distinguish user rejections, wallet capability gaps, and unknown
+ * failures without parsing error messages.
+ *
+ * @remarks
+ * Does NOT alter control flow — the SDK continues to surface a
+ * `state: 'error'` step. Auto-fallback to sequential execution is
+ * intentionally out of scope for this helper.
+ *
+ * @param err - The error thrown by `wallet_sendCalls`.
+ * @returns The derived error category, or `'unknown'` if no match.
+ *
+ * @internal
+ */
+function classifyPreSubmissionError(err) {
+    // Cross-realm-safe duck typing: `instanceof Error` returns false for
+    // errors thrown in a different JavaScript realm (e.g., a wallet
+    // provider running inside an iframe, which is common with WalletConnect
+    // and the Coinbase Wallet SDK).
+    if (typeof err !== 'object' || err === null || !('message' in err)) {
+        return 'unknown';
+    }
+    const code = coerceRpcCode(err.code);
+    const message = String(err.message);
+    // Numeric JSON-RPC codes are authoritative; check them before falling
+    // back to message-pattern matching. Order matters: an error carrying
+    // `code === 5750` with a message like "user rejected the upgrade"
+    // is a capability problem, not a plain user rejection.
+    if (code === 4001) {
+        return 'user_rejected';
+    }
+    if (code === 5700 || code === 5710 || code === 5750) {
+        return 'atomic_unsupported';
+    }
+    if (code === 5720) {
+        return 'duplicate_batch_id';
+    }
+    if (code === 5730) {
+        return 'unknown_bundle';
+    }
+    if (code === 5740) {
+        return 'batch_too_large';
+    }
+    // Fall back to message patterns when no specific code is available —
+    // viem (and other wrapper layers) sometimes strip the numeric code
+    // while preserving the original wallet message in `Details:`.
+    if (/EIP-7702 not supported/i.test(message) ||
+        /does not support the requested chain/i.test(message) ||
+        /rejected the upgrade/i.test(message)) {
+        return 'atomic_unsupported';
+    }
+    if (/user rejected/i.test(message)) {
+        return 'user_rejected';
+    }
+    return 'unknown';
+}
 /**
  * Execute a cross-chain USDC bridge using the CCTP v2 protocol.
  *

package/package.json

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