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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @circle-fin/provider-cctp-v2
 
+## 1.7.0
+
+### Minor Changes
+
+- Add support for bridging USDC to and from Pharos (mainnet and testnet) via CCTP v2.
+- Bridge errors now expose a machine-readable `errorCategory` so apps can distinguish user rejections, wallet capability errors, and offchain vs onchain failures without string-matching.
+
 ## 1.6.3
 
 ### Patch Changes

package/README.md

@@ -9,7 +9,7 @@
 
 **Circle's Cross-Chain Transfer Protocol v2 provider for Bridge Kit**
 
-_Native USDC bridging across 41 chains using Circle's battle-tested protocols._
+_Native USDC bridging across 43 chains using Circle's battle-tested protocols._
 
 </div>
 
@@ -130,7 +130,7 @@ const result = await provider.bridge({
 - ✅ **Native USDC bridging** - Move real USDC between supported networks
 - ✅ **CCTP v2 integration** - Direct integration with Circle's CCTP v2 protocol
 - ✅ **Comprehensive validation** - Route validation and parameter checking
-- ✅ **Multi-chain support** - Works across all 41 CCTPv2-supported chains
+- ✅ **Multi-chain support** - Works across all 43 CCTPv2-supported chains
 - ✅ **Type safety** - Full TypeScript support with detailed error handling
 - ✅ **Bridge speeds** - Support for both FAST and SLOW bridge configurations
 - ✅ **Forwarder integration** - Circle's Orbit relayer handles attestation and mint automatically
@@ -138,15 +138,15 @@ const result = await provider.bridge({
 
 ## Supported Chains & Routes
 
-The provider supports **800 total bridge routes** across these chains:
+The provider supports **882 total bridge routes** across these chains:
 
 ### Mainnet Chains
 
-**Arbitrum**, **Avalanche**, **Base**, **Codex**, **Edge**, **Ethereum**, **HyperEVM**, **Ink**, **Linea**, **Monad**, **Morph**, **OP Mainnet**, **Plume**, **Polygon PoS**, **Sei**, **Solana**, **Sonic**, **Unichain**, **World Chain**, **XDC**
+**Arbitrum**, **Avalanche**, **Base**, **Codex**, **Edge**, **Ethereum**, **HyperEVM**, **Ink**, **Linea**, **Monad**, **Morph**, **OP Mainnet**, **Pharos**, **Plume**, **Polygon PoS**, **Sei**, **Solana**, **Sonic**, **Unichain**, **World Chain**, **XDC**
 
 ### Testnet Chains
 
-**Arc Testnet**, **Arbitrum Sepolia**, **Avalanche Fuji**, **Base Sepolia**, **Codex Testnet**, **Edge Testnet**, **Ethereum Sepolia**, **HyperEVM Testnet**, **Ink Testnet**, **Linea Sepolia**, **Monad Testnet**, **Morph Testnet**, **OP Sepolia**, **Plume Testnet**, **Polygon PoS Amoy**, **Sei Testnet**, **Solana Devnet**, **Sonic Testnet**, **Unichain Sepolia**, **World Chain Sepolia**, **XDC Apothem**
+**Arc Testnet**, **Arbitrum Sepolia**, **Avalanche Fuji**, **Base Sepolia**, **Codex Testnet**, **Edge Testnet**, **Ethereum Sepolia**, **HyperEVM Testnet**, **Ink Testnet**, **Linea Sepolia**, **Monad Testnet**, **Morph Testnet**, **OP Sepolia**, **Pharos Atlantic**, **Plume Testnet**, **Polygon PoS Amoy**, **Sei Testnet**, **Solana Devnet**, **Sonic Testnet**, **Unichain Sepolia**, **World Chain Sepolia**, **XDC Apothem**
 
 ## Error Handling
 

package/index.cjs

@@ -95,6 +95,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";
@@ -303,6 +305,7 @@ var BridgeChain;
     BridgeChain["Monad"] = "Monad";
     BridgeChain["Morph"] = "Morph";
     BridgeChain["Optimism"] = "Optimism";
+    BridgeChain["Pharos"] = "Pharos";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
     BridgeChain["Sei"] = "Sei";
@@ -325,6 +328,7 @@ var BridgeChain;
     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";
@@ -670,6 +674,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.
@@ -2341,6 +2351,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
@@ -2623,7 +2723,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',
@@ -2681,7 +2781,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',
@@ -3498,6 +3598,8 @@ var Chains = {
     NobleTestnet: NobleTestnet,
     Optimism: Optimism,
     OptimismSepolia: OptimismSepolia,
+    Pharos: Pharos,
+    PharosTestnet: PharosTestnet,
     Plume: Plume,
     PlumeTestnet: PlumeTestnet,
     PolkadotAssetHub: PolkadotAssetHub,
@@ -5002,6 +5104,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,
@@ -7185,6 +7290,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',
@@ -7216,6 +7322,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',
@@ -7496,6 +7603,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.
@@ -7504,7 +7637,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
@@ -7535,6 +7668,7 @@ const DEFAULT_TOKENS = [
     POL,
     PLUME,
     MON,
+    CIRBTC,
 ];
 /**
  * Uppercased token symbols approved for swap fee collection.
@@ -10311,11 +10445,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;
@@ -11864,16 +12005,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.
  *
@@ -11888,11 +12083,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',
@@ -11902,6 +12103,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;
@@ -11911,11 +12116,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 {
@@ -11930,6 +12137,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) {
@@ -11937,11 +12145,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.7.0";
 var pkg = {
 	version: version};
 
@@ -12017,6 +12226,7 @@ async function executeBatchedPath(params, provider, result, invocation) {
             errorMessage: error_ instanceof Error
                 ? error_.message
                 : 'Batched approve + burn failed.',
+            errorCategory: classifyPreSubmissionError(error_),
         });
         return undefined;
     }
@@ -12031,6 +12241,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/index.d.ts

@@ -680,6 +680,8 @@ declare enum Blockchain {
     Noble_Testnet = "Noble_Testnet",
     Optimism = "Optimism",
     Optimism_Sepolia = "Optimism_Sepolia",
+    Pharos = "Pharos",
+    Pharos_Testnet = "Pharos_Testnet",
     Polkadot_Asset_Hub = "Polkadot_Asset_Hub",
     Polkadot_Westmint = "Polkadot_Westmint",
     Plume = "Plume",
@@ -3700,6 +3702,7 @@ declare module './types' {
         POL: true;
         PLUME: true;
         MON: true;
+        cirBTC: true;
     }
 }
 
@@ -4894,6 +4897,63 @@ TChainDefinition extends ChainDefinition = ChainDefinition> {
      */
     invocationMeta?: InvocationMeta;
 }
+/**
+ * Machine-readable classification of a {@link BridgeStep} error.
+ *
+ * Consumers may use this field for UX decisions (e.g. distinguish a user
+ * rejection from a wallet capability error) without string-matching on
+ * {@link BridgeStep.errorMessage}. The original human-readable error
+ * message is always preserved for display/logging.
+ *
+ * @remarks
+ * The categories map to the most common failure shapes observed across
+ * the EIP-5792 batched bridge path and the sequential bridge path:
+ *
+ * - `user_rejected` — user declined a wallet request (JSON-RPC `4001`).
+ * - `atomic_unsupported` — wallet reported it cannot perform EIP-5792
+ *   atomic batching on this chain. Covers JSON-RPC `5700` (unsupported
+ *   capabilities), `5710` (chain not supported for the requested
+ *   capability), and `5750` (atomicity requires a wallet upgrade which
+ *   the user declined), or equivalent viem-wrapped messages.
+ * - `batch_too_large` — wallet rejected the batch for exceeding its
+ *   size limit (JSON-RPC `5740`).
+ * - `duplicate_batch_id` — wallet reported a duplicate batchId
+ *   (JSON-RPC `5720`).
+ * - `unknown_bundle` — wallet reported an unknown bundle id during
+ *   status polling (JSON-RPC `5730`).
+ * - `polling_timeout` — SDK polled `wallet_getCallsStatus` until the
+ *   configured timeout without receiving a terminal status.
+ * - `failed_offchain` — wallet reported EIP-5792 `statusCode: 400`
+ *   (batch not included onchain, wallet will not retry).
+ * - `reverted_onchain` — wallet reported EIP-5792 `statusCode: 500`
+ *   (batch reverted completely onchain).
+ * - `partial_reverted` — wallet reported EIP-5792 `statusCode: 600`
+ *   (batch reverted partially onchain).
+ * - `chain_revert` — transaction was mined but reverted on-chain
+ *   (sequential path).
+ * - `unknown` — error did not match any of the above categories.
+ *
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeStep } from '@core/provider'
+ *
+ * const step: BridgeStep = {
+ *   name: 'approve',
+ *   state: 'error',
+ *   errorMessage: 'User rejected the request',
+ *   errorCategory: 'user_rejected',
+ * }
+ *
+ * if (step.errorCategory === 'user_rejected') {
+ *   // silent abort: user intentionally cancelled
+ * } else if (step.errorCategory === 'atomic_unsupported') {
+ *   // hint the user about switching to step-by-step signing
+ * }
+ * ```
+ */
+type BridgeStepErrorCategory = 'user_rejected' | 'atomic_unsupported' | 'batch_too_large' | 'duplicate_batch_id' | 'unknown_bundle' | 'polling_timeout' | 'failed_offchain' | 'reverted_onchain' | 'partial_reverted' | 'chain_revert' | 'unknown';
 /**
  * A step in the bridge process.
  *
@@ -4950,6 +5010,21 @@ interface BridgeStep {
     errorMessage?: string;
     /** Optional raw error object (can be Viem/Ethers/Chain error) */
     error?: unknown;
+    /**
+     * Optional machine-readable classification of the error.
+     *
+     * Present when the step is in `state: 'error'` and the SDK was able to
+     * categorize the failure. See {@link BridgeStepErrorCategory} for the
+     * list of categories and how they map to underlying error shapes.
+     *
+     * @remarks
+     * The human-readable {@link errorMessage} is always preserved for
+     * logging and display; this field is additive and should be preferred
+     * over string-matching `errorMessage` for machine decisions.
+     *
+     * @since 2.0.0
+     */
+    errorCategory?: BridgeStepErrorCategory;
 }
 /**
  * Result object returned after a successful cross-chain bridge operation.

package/index.mjs

@@ -88,6 +88,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";
@@ -296,6 +298,7 @@ var BridgeChain;
     BridgeChain["Monad"] = "Monad";
     BridgeChain["Morph"] = "Morph";
     BridgeChain["Optimism"] = "Optimism";
+    BridgeChain["Pharos"] = "Pharos";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
     BridgeChain["Sei"] = "Sei";
@@ -318,6 +321,7 @@ var BridgeChain;
     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 +667,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.
@@ -2334,6 +2344,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 +2716,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 +2774,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',
@@ -3491,6 +3591,8 @@ var Chains = /*#__PURE__*/Object.freeze({
     NobleTestnet: NobleTestnet,
     Optimism: Optimism,
     OptimismSepolia: OptimismSepolia,
+    Pharos: Pharos,
+    PharosTestnet: PharosTestnet,
     Plume: Plume,
     PlumeTestnet: PlumeTestnet,
     PolkadotAssetHub: PolkadotAssetHub,
@@ -4995,6 +5097,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,
@@ -7178,6 +7283,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',
@@ -7209,6 +7315,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 +7596,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 +7630,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 +7661,7 @@ const DEFAULT_TOKENS = [
     POL,
     PLUME,
     MON,
+    CIRBTC,
 ];
 /**
  * Uppercased token symbols approved for swap fee collection.
@@ -10304,11 +10438,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 +11998,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 +12076,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 +12096,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 +12109,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 +12130,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 +12138,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.7.0";
 var pkg = {
 	version: version};
 
@@ -12010,6 +12219,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 +12234,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.7.0",
   "description": "Circle's official Cross-Chain Transfer Protocol v2 provider for native USDC bridging",
   "keywords": [
     "circle",