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

package/index.d.ts

@@ -666,6 +666,8 @@ declare enum Blockchain {
     Hedera_Testnet = "Hedera_Testnet",
     HyperEVM = "HyperEVM",
     HyperEVM_Testnet = "HyperEVM_Testnet",
+    Injective = "Injective",
+    Injective_Testnet = "Injective_Testnet",
     Ink = "Ink",
     Ink_Testnet = "Ink_Testnet",
     Linea = "Linea",
@@ -680,6 +682,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 +3704,7 @@ declare module './types' {
         POL: true;
         PLUME: true;
         MON: true;
+        cirBTC: true;
     }
 }
 
@@ -4894,6 +4899,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 +5012,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.