@circle-fin/app-kit 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @circle-fin/app-kit
 
+## 1.3.0
+
+### Minor Changes
+
+- Add `retryBridge()` method to AppKit for retrying failed or incomplete cross-chain bridge operations.
+- Add Arc Testnet support for swap operations.
+
+### Patch Changes
+
+- Swap slippage and stop-limit failures now return a distinct retryable error instead of fatal "route not found"
+- Bridge operations now automatically retry transient RPC errors with exponential backoff
+- Update HyperEVM mainnet explorer URL to resolve location-restricted access issues
+- Improved search discoverability
+
+## 1.2.1
+
+### Patch Changes
+
+- Add support for Solana as a forwarder destination
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -7,9 +7,9 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Discord](https://img.shields.io/discord/473781666251538452?label=Discord&logo=discord)](https://discord.com/invite/buildoncircle)
 
-**A unified, strongly-typed SDK for seamless stablecoin operations across chains**
+**A one-stop Circle SDK for building stablecoin (e.g. USDC) applications, providing a unified set of on-chain tools for bridging, swapping, and other stablecoin operations.**
 
-_Making cross-chain transfers and same-chain swaps as simple as a single function call_
+_Making cross-chain transfers, same-chain swaps, and token sends as simple as a single function call_
 
 </div>
 
@@ -72,6 +72,10 @@ The App Kit provides a **unified interface** for both cross-chain transfers and
 - **🛡️ Robust error handling**: Graceful partial success recovery
 - **✈️ Pre-flight validation**: Verify operations with cost estimation before execution
 
+## Developer Documentation
+
+- [App Kit Documentation](https://docs.arc.network/app-kit)
+
 ## Architecture Flow
 
 The App Kit follows a composable architecture that integrates Bridge Kit and Swap Kit:

package/chains.cjs

@@ -168,8 +168,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.
@@ -214,6 +215,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)
@@ -310,6 +313,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.
@@ -612,6 +640,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
@@ -660,6 +696,7 @@ const ArcTestnet = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+        adapter: ADAPTER_CONTRACT_EVM_TESTNET,
     },
 });
 
@@ -1350,7 +1387,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',
@@ -2458,7 +2495,7 @@ const Solana = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2505,7 +2542,7 @@ const SolanaDevnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -3177,6 +3214,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.refine((chain) => chain.chain in EarnChain, (chain) => ({
+        message: `"${chain.chain}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+]);
 
 /**
  * @packageDocumentation

package/chains.d.ts

@@ -136,6 +136,7 @@ declare const ArcTestnet: {
     };
     readonly kitContracts: {
         readonly bridge: "0xC5567a5E3370d4DBfB0540025078e283e36A363d";
+        readonly adapter: "0xBBD70b01a1CAbc96d5b7b129Ae1AAabdf50dd40b";
     };
 };
 
@@ -640,7 +641,7 @@ declare const HyperEVM: {
     };
     readonly chainId: 999;
     readonly isTestnet: false;
-    readonly explorerUrl: "https://app.hyperliquid.xyz/explorer/tx/{hash}";
+    readonly explorerUrl: "https://hyperevmscan.io/tx/{hash}";
     readonly rpcEndpoints: readonly ["https://rpc.hyperliquid.xyz/evm"];
     readonly eurcAddress: null;
     readonly usdcAddress: "0xb88339CB7199b77E23DB6E890353E22632Ba630f";
@@ -1393,7 +1394,7 @@ declare const Solana: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -1440,7 +1441,7 @@ declare const SolanaDevnet: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {

package/chains.mjs

@@ -166,8 +166,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.
@@ -212,6 +213,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)
@@ -308,6 +311,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.
@@ -610,6 +638,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
@@ -658,6 +694,7 @@ const ArcTestnet = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+        adapter: ADAPTER_CONTRACT_EVM_TESTNET,
     },
 });
 
@@ -1348,7 +1385,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',
@@ -2456,7 +2493,7 @@ const Solana = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2503,7 +2540,7 @@ const SolanaDevnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -3175,6 +3212,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.refine((chain) => chain.chain in EarnChain, (chain) => ({
+        message: `"${chain.chain}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+]);
 
 /**
  * @packageDocumentation