@circle-fin/adapter-ethers-v6 1.6.3 → 1.6.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @circle-fin/adapter-ethers-v6
 
+## 1.6.4
+
+### Patch Changes
+
+- Update HyperEVM mainnet explorer URL to resolve location-restricted access issues
+- Improved search discoverability
+
 ## 1.6.3
 
 ### Patch Changes

package/index.cjs

@@ -420,6 +420,12 @@ const InputError = {
         name: 'INPUT_UNSUPPORTED_TOKEN',
         type: 'INPUT',
     },
+    /** No route satisfies the slippage or minimum-output constraint */
+    SLIPPAGE_CONSTRAINT_NOT_MET: {
+        code: 1009,
+        name: 'INPUT_SLIPPAGE_CONSTRAINT_NOT_MET',
+        type: 'INPUT',
+    },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
@@ -1199,6 +1205,40 @@ function normalizeTransactionDetails(txHash, explorerUrl) {
     }
     return normalized;
 }
+/**
+ * Pattern that matches on-chain revert reasons caused by slippage or
+ * price constraints. When a revert matches, the error is surfaced as
+ * {@link InputError.SLIPPAGE_CONSTRAINT_NOT_MET} (RETRYABLE) instead of
+ * a generic simulation-failed / transaction-reverted error.
+ *
+ * @internal
+ */
+const SLIPPAGE_REVERT_PATTERN = /slippage|lower than the minimum required|less than the initial balance|minimum.?output|price.?impact|stop.?limit|InsufficientOutput|InsufficientFinalBalance/i;
+/**
+ * Handle simulation / execution revert errors, distinguishing slippage
+ * constraint failures from generic reverts and simulation failures.
+ *
+ * @internal
+ */
+function handleRevertError(msg, error, context) {
+    const reason = extractRevertReason(msg, error) ?? 'Transaction reverted';
+    if (SLIPPAGE_REVERT_PATTERN.test(reason)) {
+        return new KitError({
+            ...InputError.SLIPPAGE_CONSTRAINT_NOT_MET,
+            recoverability: 'RETRYABLE',
+            message: `Transaction on ${context.chain} reverted: "${reason}". ` +
+                'Try increasing slippageBps or adjusting stopLimit.',
+            cause: { trace: { rawError: error, chain: context.chain, reason } },
+        });
+    }
+    if (/simulation failed/i.test(msg) || context.operation === 'simulation') {
+        return createSimulationFailedError(context.chain, reason, {
+            rawError: error,
+        });
+    }
+    const { txHash, explorerUrl } = normalizeTransactionDetails(context.txHash, context.explorerUrl);
+    return createTransactionRevertedError(context.chain, reason, { rawError: error }, txHash, explorerUrl);
+}
 /**
  * Parses raw blockchain errors into structured KitError instances.
  *
@@ -1279,21 +1319,7 @@ function parseBlockchainError(error, context) {
     // Pattern 2: Simulation and execution reverts
     // Matches contract revert errors and simulation failures
     if (/execution reverted|simulation failed|transaction reverted|transaction failed/i.test(msg)) {
-        const reason = extractRevertReason(msg, error) ?? 'Transaction reverted';
-        // Distinguish between simulation failures and transaction reverts
-        // "simulation failed" or "eth_call" indicates pre-flight simulation
-        // "transaction failed" or context.operation === 'transaction' indicates post-execution
-        if (/simulation failed/i.test(msg) || context.operation === 'simulation') {
-            return createSimulationFailedError(context.chain, reason, {
-                rawError: error,
-            });
-        }
-        // Transaction execution failures or reverts
-        // Include txHash and explorerUrl if available (transaction was submitted)
-        const { txHash, explorerUrl } = normalizeTransactionDetails(context.txHash, context.explorerUrl);
-        return createTransactionRevertedError(context.chain, reason, {
-            rawError: error,
-        }, txHash, explorerUrl);
+        return handleRevertError(msg, error, context);
     }
     // Pattern 3: Gas-related errors
     // Matches gas estimation failures and gas exhaustion
@@ -1318,8 +1344,12 @@ function parseBlockchainError(error, context) {
         return createNetworkConnectionError(context.chain, { rawError: error });
     }
     // Pattern 5: RPC provider errors
-    // Matches RPC endpoint errors, invalid responses, and rate limits
-    if (/rpc|invalid response|rate limit|too many requests/i.test(msg)) {
+    // Matches RPC endpoint errors, invalid responses, rate limits, and
+    // transient JSON-RPC internal errors (e.g. ethers.js "could not coalesce error").
+    // Note: "internal error" alone is too broad — contracts like USDT emit
+    // "An internal error was received" for on-chain assertion failures.
+    // We require JSON-RPC context (codes -32603/-32000) instead.
+    if (/rpc|invalid response|rate limit|too many requests|could not coalesce|no response|server error|json-rpc\s+internal|internal json-rpc|-32603|-32000/i.test(msg)) {
         return createRpcEndpointError(context.chain, { rawError: error });
     }
     // Pattern 6: Transaction size limit errors
@@ -1744,8 +1774,9 @@ exports.Blockchain = void 0;
 /**
  * Enum representing chains that support same-chain swaps through the Swap Kit.
  *
- * Unlike the full {@link Blockchain} enum, SwapChain includes only mainnet
- * networks where adapter contracts are deployed (CCTPv2 support).
+ * Unlike the full {@link Blockchain} enum, SwapChain includes mainnet
+ * networks and explicitly whitelisted testnets (e.g., {@link Arc_Testnet})
+ * where adapter contracts are deployed (CCTPv2 support).
  *
  * Dynamic validation via {@link isSwapSupportedChain} ensures chains
  * automatically work when adapter contracts and supported tokens are deployed.
@@ -1790,6 +1821,8 @@ var SwapChain;
     SwapChain["XDC"] = "XDC";
     SwapChain["HyperEVM"] = "HyperEVM";
     SwapChain["Monad"] = "Monad";
+    // Testnet chains with swap support
+    SwapChain["Arc_Testnet"] = "Arc_Testnet";
 })(SwapChain || (SwapChain = {}));
 // -----------------------------------------------------------------------------
 // Bridge Chain Enum (CCTPv2 Supported Chains)
@@ -1886,6 +1919,31 @@ var BridgeChain;
     BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     BridgeChain["XDC_Apothem"] = "XDC_Apothem";
 })(BridgeChain || (BridgeChain = {}));
+// -----------------------------------------------------------------------------
+// Earn Chain Enum
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of blockchains that support earn (vault deposit/withdraw)
+ * operations through the Earn Kit.
+ *
+ * Currently only Ethereum mainnet is supported. Additional chains
+ * will be added as vault protocol support expands.
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@core/chains'
+ *
+ * const result = await earnKit.deposit({
+ *   from: { adapter, chain: EarnChain.Ethereum },
+ *   vaultAddress: '0x...',
+ *   amount: '100',
+ * })
+ * ```
+ */
+var EarnChain;
+(function (EarnChain) {
+    EarnChain["Ethereum"] = "Ethereum";
+})(EarnChain || (EarnChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -2188,6 +2246,14 @@ const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0'
  * on EVM-compatible chains. Use this address for mainnet adapter integrations.
  */
 const ADAPTER_CONTRACT_EVM_MAINNET = '0x7FB8c7260b63934d8da38aF902f87ae6e284a845';
+/**
+ * The adapter contract address for EVM testnet networks.
+ *
+ * This contract serves as an adapter for integrating with various protocols
+ * on EVM-compatible testnet chains. Use this address for testnet adapter
+ * integrations (e.g., Arc Testnet).
+ */
+const ADAPTER_CONTRACT_EVM_TESTNET = '0xBBD70b01a1CAbc96d5b7b129Ae1AAabdf50dd40b';
 
 /**
  * Arc Testnet chain definition
@@ -2236,6 +2302,7 @@ const ArcTestnet = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+        adapter: ADAPTER_CONTRACT_EVM_TESTNET,
     },
 });
 
@@ -2926,7 +2993,7 @@ const HyperEVM = defineChain({
     },
     chainId: 999,
     isTestnet: false,
-    explorerUrl: 'https://app.hyperliquid.xyz/explorer/tx/{hash}',
+    explorerUrl: 'https://hyperevmscan.io/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
@@ -4869,6 +4936,41 @@ zod.z.union([
         message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
     })),
 ]);
+/**
+ * Zod schema for validating earn-specific chain identifiers.
+ *
+ * Validate that the provided chain is supported for earn (vault
+ * deposit/withdraw) operations. Currently only Ethereum is
+ * supported.
+ *
+ * Accept an EarnChain enum value, a matching string literal, or
+ * a ChainDefinition for a supported chain.
+ *
+ * @example
+ * ```typescript
+ * import { earnChainIdentifierSchema } from '@core/chains'
+ * import { EarnChain, Ethereum } from '@core/chains'
+ *
+ * // Valid
+ * earnChainIdentifierSchema.parse(EarnChain.Ethereum)
+ * earnChainIdentifierSchema.parse('Ethereum')
+ * earnChainIdentifierSchema.parse(Ethereum)
+ *
+ * // Invalid (throws ZodError)
+ * earnChainIdentifierSchema.parse('Solana')
+ * ```
+ */
+zod.z.union([
+    zod.z.string().refine((val) => val in EarnChain, (val) => ({
+        message: `"${val}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+    zod.z.nativeEnum(EarnChain),
+    chainDefinitionSchema$1.refine((chain) => chain.chain in EarnChain, (chain) => ({
+        message: `"${chain.chain}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+]);
 
 /**
  * @packageDocumentation
@@ -5956,6 +6058,7 @@ const USDC = {
         // =========================================================================
         // Testnets (alphabetically sorted)
         // =========================================================================
+        [exports.Blockchain.Arc_Testnet]: '0x3600000000000000000000000000000000000000',
         [exports.Blockchain.Arbitrum_Sepolia]: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
         [exports.Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
         [exports.Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
@@ -6032,6 +6135,8 @@ const EURC = {
         [exports.Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
         [exports.Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
         [exports.Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
+        // Testnets
+        [exports.Blockchain.Arc_Testnet]: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
     },
 };
 

package/index.mjs

@@ -415,6 +415,12 @@ const InputError = {
         name: 'INPUT_UNSUPPORTED_TOKEN',
         type: 'INPUT',
     },
+    /** No route satisfies the slippage or minimum-output constraint */
+    SLIPPAGE_CONSTRAINT_NOT_MET: {
+        code: 1009,
+        name: 'INPUT_SLIPPAGE_CONSTRAINT_NOT_MET',
+        type: 'INPUT',
+    },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
@@ -1194,6 +1200,40 @@ function normalizeTransactionDetails(txHash, explorerUrl) {
     }
     return normalized;
 }
+/**
+ * Pattern that matches on-chain revert reasons caused by slippage or
+ * price constraints. When a revert matches, the error is surfaced as
+ * {@link InputError.SLIPPAGE_CONSTRAINT_NOT_MET} (RETRYABLE) instead of
+ * a generic simulation-failed / transaction-reverted error.
+ *
+ * @internal
+ */
+const SLIPPAGE_REVERT_PATTERN = /slippage|lower than the minimum required|less than the initial balance|minimum.?output|price.?impact|stop.?limit|InsufficientOutput|InsufficientFinalBalance/i;
+/**
+ * Handle simulation / execution revert errors, distinguishing slippage
+ * constraint failures from generic reverts and simulation failures.
+ *
+ * @internal
+ */
+function handleRevertError(msg, error, context) {
+    const reason = extractRevertReason(msg, error) ?? 'Transaction reverted';
+    if (SLIPPAGE_REVERT_PATTERN.test(reason)) {
+        return new KitError({
+            ...InputError.SLIPPAGE_CONSTRAINT_NOT_MET,
+            recoverability: 'RETRYABLE',
+            message: `Transaction on ${context.chain} reverted: "${reason}". ` +
+                'Try increasing slippageBps or adjusting stopLimit.',
+            cause: { trace: { rawError: error, chain: context.chain, reason } },
+        });
+    }
+    if (/simulation failed/i.test(msg) || context.operation === 'simulation') {
+        return createSimulationFailedError(context.chain, reason, {
+            rawError: error,
+        });
+    }
+    const { txHash, explorerUrl } = normalizeTransactionDetails(context.txHash, context.explorerUrl);
+    return createTransactionRevertedError(context.chain, reason, { rawError: error }, txHash, explorerUrl);
+}
 /**
  * Parses raw blockchain errors into structured KitError instances.
  *
@@ -1274,21 +1314,7 @@ function parseBlockchainError(error, context) {
     // Pattern 2: Simulation and execution reverts
     // Matches contract revert errors and simulation failures
     if (/execution reverted|simulation failed|transaction reverted|transaction failed/i.test(msg)) {
-        const reason = extractRevertReason(msg, error) ?? 'Transaction reverted';
-        // Distinguish between simulation failures and transaction reverts
-        // "simulation failed" or "eth_call" indicates pre-flight simulation
-        // "transaction failed" or context.operation === 'transaction' indicates post-execution
-        if (/simulation failed/i.test(msg) || context.operation === 'simulation') {
-            return createSimulationFailedError(context.chain, reason, {
-                rawError: error,
-            });
-        }
-        // Transaction execution failures or reverts
-        // Include txHash and explorerUrl if available (transaction was submitted)
-        const { txHash, explorerUrl } = normalizeTransactionDetails(context.txHash, context.explorerUrl);
-        return createTransactionRevertedError(context.chain, reason, {
-            rawError: error,
-        }, txHash, explorerUrl);
+        return handleRevertError(msg, error, context);
     }
     // Pattern 3: Gas-related errors
     // Matches gas estimation failures and gas exhaustion
@@ -1313,8 +1339,12 @@ function parseBlockchainError(error, context) {
         return createNetworkConnectionError(context.chain, { rawError: error });
     }
     // Pattern 5: RPC provider errors
-    // Matches RPC endpoint errors, invalid responses, and rate limits
-    if (/rpc|invalid response|rate limit|too many requests/i.test(msg)) {
+    // Matches RPC endpoint errors, invalid responses, rate limits, and
+    // transient JSON-RPC internal errors (e.g. ethers.js "could not coalesce error").
+    // Note: "internal error" alone is too broad — contracts like USDT emit
+    // "An internal error was received" for on-chain assertion failures.
+    // We require JSON-RPC context (codes -32603/-32000) instead.
+    if (/rpc|invalid response|rate limit|too many requests|could not coalesce|no response|server error|json-rpc\s+internal|internal json-rpc|-32603|-32000/i.test(msg)) {
         return createRpcEndpointError(context.chain, { rawError: error });
     }
     // Pattern 6: Transaction size limit errors
@@ -1739,8 +1769,9 @@ var Blockchain;
 /**
  * Enum representing chains that support same-chain swaps through the Swap Kit.
  *
- * Unlike the full {@link Blockchain} enum, SwapChain includes only mainnet
- * networks where adapter contracts are deployed (CCTPv2 support).
+ * Unlike the full {@link Blockchain} enum, SwapChain includes mainnet
+ * networks and explicitly whitelisted testnets (e.g., {@link Arc_Testnet})
+ * where adapter contracts are deployed (CCTPv2 support).
  *
  * Dynamic validation via {@link isSwapSupportedChain} ensures chains
  * automatically work when adapter contracts and supported tokens are deployed.
@@ -1785,6 +1816,8 @@ var SwapChain;
     SwapChain["XDC"] = "XDC";
     SwapChain["HyperEVM"] = "HyperEVM";
     SwapChain["Monad"] = "Monad";
+    // Testnet chains with swap support
+    SwapChain["Arc_Testnet"] = "Arc_Testnet";
 })(SwapChain || (SwapChain = {}));
 // -----------------------------------------------------------------------------
 // Bridge Chain Enum (CCTPv2 Supported Chains)
@@ -1881,6 +1914,31 @@ var BridgeChain;
     BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     BridgeChain["XDC_Apothem"] = "XDC_Apothem";
 })(BridgeChain || (BridgeChain = {}));
+// -----------------------------------------------------------------------------
+// Earn Chain Enum
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of blockchains that support earn (vault deposit/withdraw)
+ * operations through the Earn Kit.
+ *
+ * Currently only Ethereum mainnet is supported. Additional chains
+ * will be added as vault protocol support expands.
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@core/chains'
+ *
+ * const result = await earnKit.deposit({
+ *   from: { adapter, chain: EarnChain.Ethereum },
+ *   vaultAddress: '0x...',
+ *   amount: '100',
+ * })
+ * ```
+ */
+var EarnChain;
+(function (EarnChain) {
+    EarnChain["Ethereum"] = "Ethereum";
+})(EarnChain || (EarnChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -2183,6 +2241,14 @@ const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0'
  * on EVM-compatible chains. Use this address for mainnet adapter integrations.
  */
 const ADAPTER_CONTRACT_EVM_MAINNET = '0x7FB8c7260b63934d8da38aF902f87ae6e284a845';
+/**
+ * The adapter contract address for EVM testnet networks.
+ *
+ * This contract serves as an adapter for integrating with various protocols
+ * on EVM-compatible testnet chains. Use this address for testnet adapter
+ * integrations (e.g., Arc Testnet).
+ */
+const ADAPTER_CONTRACT_EVM_TESTNET = '0xBBD70b01a1CAbc96d5b7b129Ae1AAabdf50dd40b';
 
 /**
  * Arc Testnet chain definition
@@ -2231,6 +2297,7 @@ const ArcTestnet = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+        adapter: ADAPTER_CONTRACT_EVM_TESTNET,
     },
 });
 
@@ -2921,7 +2988,7 @@ const HyperEVM = defineChain({
     },
     chainId: 999,
     isTestnet: false,
-    explorerUrl: 'https://app.hyperliquid.xyz/explorer/tx/{hash}',
+    explorerUrl: 'https://hyperevmscan.io/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
@@ -4864,6 +4931,41 @@ z.union([
         message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
     })),
 ]);
+/**
+ * Zod schema for validating earn-specific chain identifiers.
+ *
+ * Validate that the provided chain is supported for earn (vault
+ * deposit/withdraw) operations. Currently only Ethereum is
+ * supported.
+ *
+ * Accept an EarnChain enum value, a matching string literal, or
+ * a ChainDefinition for a supported chain.
+ *
+ * @example
+ * ```typescript
+ * import { earnChainIdentifierSchema } from '@core/chains'
+ * import { EarnChain, Ethereum } from '@core/chains'
+ *
+ * // Valid
+ * earnChainIdentifierSchema.parse(EarnChain.Ethereum)
+ * earnChainIdentifierSchema.parse('Ethereum')
+ * earnChainIdentifierSchema.parse(Ethereum)
+ *
+ * // Invalid (throws ZodError)
+ * earnChainIdentifierSchema.parse('Solana')
+ * ```
+ */
+z.union([
+    z.string().refine((val) => val in EarnChain, (val) => ({
+        message: `"${val}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+    z.nativeEnum(EarnChain),
+    chainDefinitionSchema$1.refine((chain) => chain.chain in EarnChain, (chain) => ({
+        message: `"${chain.chain}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+]);
 
 /**
  * @packageDocumentation
@@ -5951,6 +6053,7 @@ const USDC = {
         // =========================================================================
         // Testnets (alphabetically sorted)
         // =========================================================================
+        [Blockchain.Arc_Testnet]: '0x3600000000000000000000000000000000000000',
         [Blockchain.Arbitrum_Sepolia]: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
         [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
         [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
@@ -6027,6 +6130,8 @@ const EURC = {
         [Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
         [Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
         [Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
+        // Testnets
+        [Blockchain.Arc_Testnet]: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
     },
 };
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@circle-fin/adapter-ethers-v6",
-  "version": "1.6.3",
+  "version": "1.6.4",
   "description": "EVM blockchain adapter powered by Ethers v6",
   "keywords": [
     "circle",
+    "circle-fin",
     "cctp",
     "usdc",
     "stablecoin",
@@ -15,7 +16,9 @@
     "ethers",
     "cross-chain",
     "bridge",
-    "bridge-kit"
+    "bridge-kit",
+    "app-kit",
+    "swap-kit"
   ],
   "main": "./index.cjs",
   "module": "./index.mjs",