@circle-fin/app-kit 1.4.1 → 1.4.2

package/index.mjs

@@ -3412,6 +3412,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";
@@ -3620,6 +3622,7 @@ var BridgeChain;
     BridgeChain["Monad"] = "Monad";
     BridgeChain["Morph"] = "Morph";
     BridgeChain["Optimism"] = "Optimism";
+    BridgeChain["Pharos"] = "Pharos";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
     BridgeChain["Sei"] = "Sei";
@@ -3642,6 +3645,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";
@@ -3987,6 +3991,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.
@@ -5683,6 +5693,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
@@ -5965,7 +6065,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',
@@ -6023,7 +6123,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',
@@ -6840,6 +6940,8 @@ var Chains = /*#__PURE__*/Object.freeze({
     NobleTestnet: NobleTestnet,
     Optimism: Optimism,
     OptimismSepolia: OptimismSepolia,
+    Pharos: Pharos,
+    PharosTestnet: PharosTestnet,
     Plume: Plume,
     PlumeTestnet: PlumeTestnet,
     PolkadotAssetHub: PolkadotAssetHub,
@@ -9108,6 +9210,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',
@@ -9139,6 +9242,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',
@@ -9419,6 +9523,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.
@@ -9427,7 +9557,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
@@ -9458,6 +9588,7 @@ const DEFAULT_TOKENS = [
     POL,
     PLUME,
     MON,
+    CIRBTC,
 ];
 /**
  * Uppercased token symbols approved for swap fee collection.
@@ -10206,7 +10337,7 @@ async function retryAsync(fn, options) {
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$3 = "1.8.3";
+var version$3 = "1.9.0";
 var pkg$3 = {
 	name: name$2,
 	version: version$3};
@@ -14337,11 +14468,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;
@@ -15007,16 +15145,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.
  *
@@ -15031,11 +15223,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',
@@ -15045,6 +15243,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;
@@ -15054,11 +15256,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 {
@@ -15073,6 +15277,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) {
@@ -15080,11 +15285,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$2 = "1.6.3";
+var version$2 = "1.7.0";
 var pkg$2 = {
 	version: version$2};
 
@@ -15160,6 +15366,7 @@ async function executeBatchedPath(params, provider, result, invocation) {
             errorMessage: error_ instanceof Error
                 ? error_.message
                 : 'Batched approve + burn failed.',
+            errorCategory: classifyPreSubmissionError(error_),
         });
         return undefined;
     }
@@ -15174,6 +15381,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.
  *
@@ -17317,7 +17607,7 @@ const createBridgeKit = (context) => {
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.1.0";
+var version$1 = "1.1.1";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -28691,7 +28981,7 @@ const prepareSend = async (params) => {
     const fromContext = params.from;
     const fromAdapter = fromContext.adapter;
     const fromChain = resolveChainIdentifier(fromContext.chain);
-    const fromAddress = await fromAdapter.getAddress(fromChain);
+    const fromAddress = fromContext.address ?? (await fromAdapter.getAddress(fromChain));
     // resolve input parameters
     const token = params.token ?? 'USDC';
     // Validate token and determine if it's an alias or custom address
@@ -29136,7 +29426,7 @@ const getSupportedChains$2 = (context, operationType, unifiedBalance) => {
 };
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.0.1";
+var version = "1.0.2";
 var pkg = {
 	name: name,
 	version: version};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/app-kit",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "A one-stop Circle SDK solution for building stablecoin (e.g. USDC) applications, with bridging, swapping, and more on-chain operations",
   "keywords": [
     "circle",
@@ -36,10 +36,10 @@
   "module": "./index.mjs",
   "types": "./index.d.ts",
   "dependencies": {
-    "@circle-fin/unified-balance-kit": "1.0.1",
-    "@circle-fin/provider-gateway-v1": "1.0.1",
-    "@circle-fin/bridge-kit": "1.8.3",
-    "@circle-fin/swap-kit": "1.1.0",
+    "@circle-fin/unified-balance-kit": "1.0.2",
+    "@circle-fin/provider-gateway-v1": "1.0.2",
+    "@circle-fin/bridge-kit": "1.9.0",
+    "@circle-fin/swap-kit": "1.1.1",
     "zod": "3.25.67",
     "@ethersproject/address": "^5.8.0",
     "@ethersproject/bytes": "^5.8.0",