@circle-fin/app-kit 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# @circle-fin/app-kit
+
+## 1.2.0
+
+### Minor Changes
+
+- Enable forwarder destination support for Codex, Plume, and XDC chains on both mainnet and testnet
+
+### Patch Changes
+
+- Update HyperEVM explorer URLs to use the official Hyperliquid explorer
+
+## 1.1.0
+
+### Minor Changes
+
+- Add support for bridging USDC to and from Edge and Morph networks. Both mainnet and testnet chains are now available as source and destination options in Bridge Kit.
+
+## 1.0.1
+
+### Patch Changes
+
+- Fix package installation failure where `npm install @circle-fin/app-kit` would error with unresolvable dependencies.
+
+## 1.0.0
+
+### Major Changes
+
+- Introducing AppKit — a unified SDK for stablecoin operations combining bridging, swapping, and token transfers in one interface.
+  - `kit.bridge()` — cross-chain USDC transfers via CCTP v2 across 35+ supported chains
+  - `kit.swap()` — same-chain token swaps with smart routing across DEX liquidity sources
+  - `kit.send()` — same-chain transfers for USDC, USDT, native tokens, and any ERC-20/SPL token by contract address
+
+  Each operation has a corresponding estimate method (`estimateBridge`, `estimateSwap`, `estimateSend`) to preview fees and output amounts before executing.
+
+  Additional features:
+  - Unified developer fee configuration across all operations
+  - Action event system for monitoring operation lifecycle
+  - Tree-shakeable subpath imports (`/bridge`, `/swap`, `/chains`, `/context`)
+  - Full error hierarchy with type guards (`isRetryableError`, `isBalanceError`, `isRpcError`, etc.)
+  - Chain definitions available via `@circle-fin/app-kit/chains`
+
+  Configure your adapters once, then use bridge, swap, and send through a single API.

package/README.md

@@ -130,9 +130,9 @@ npm install @circle-fin/adapter-viem-v2 viem
 yarn add @circle-fin/adapter-viem-v2 viem
 
 # For EVM chains using Ethers.js
-npm install @circle-fin/adapter-ethers-v6
+npm install @circle-fin/adapter-ethers-v6 ethers
 # or
-yarn add @circle-fin/adapter-ethers-v6
+yarn add @circle-fin/adapter-ethers-v6 ethers
 
 # For Solana
 npm install @circle-fin/adapter-solana @solana/web3.js @solana/spl-token
@@ -194,6 +194,9 @@ const result = await kit.swap({
   tokenIn: 'USDC',
   tokenOut: 'USDT',
   amountIn: '100.0',
+  config: {
+    kitKey: process.env.KIT_KEY,
+  },
 })
 
 // Swap DAI to USDC (18 decimals handled automatically)
@@ -202,6 +205,9 @@ const daiSwap = await kit.swap({
   tokenIn: 'DAI',
   tokenOut: 'USDC',
   amountIn: '500.0',
+  config: {
+    kitKey: process.env.KIT_KEY,
+  },
 })
 
 // Swap native ETH to stablecoin
@@ -210,6 +216,9 @@ const nativeSwap = await kit.swap({
   tokenIn: 'NATIVE', // ETH on Ethereum
   tokenOut: 'USDC',
   amountIn: '1.5',
+  config: {
+    kitKey: process.env.KIT_KEY,
+  },
 })
 ```
 
@@ -231,6 +240,9 @@ const swapEstimate = await kit.estimateSwap({
   tokenIn: 'USDC',
   tokenOut: 'USDT',
   amountIn: '100.0',
+  config: {
+    kitKey: process.env.KIT_KEY,
+  },
 })
 
 console.log('Bridge fees:', bridgeEstimate.fees)
@@ -260,7 +272,7 @@ const allChains = kit.getSupportedChains()
 
 ### Send Parameters
 
-The `send()` method provides a unified interface for transferring tokens. It automatically determines whether to use bridging or swapping based on the source and destination chains:
+The `send()` method transfers tokens on the same chain from the source adapter to a recipient address or adapter:
 
 ```typescript
 interface SendParams {
@@ -361,6 +373,9 @@ await kit.swap({
   tokenIn: 'EURC',
   tokenOut: 'USDC',
   amountIn: '100.0',
+  config: {
+    kitKey: process.env.KIT_KEY,
+  },
 })
 
 // Swap DAI (18 decimals) to USDT
@@ -369,6 +384,9 @@ await kit.swap({
   tokenIn: 'DAI',
   tokenOut: 'USDT',
   amountIn: '500.0', // SDK automatically handles 18-decimal precision
+  config: {
+    kitKey: process.env.KIT_KEY,
+  },
 })
 
 // Swap native token to stablecoin
@@ -377,6 +395,9 @@ await kit.swap({
   tokenIn: 'NATIVE', // ETH on Ethereum
   tokenOut: 'USDC',
   amountIn: '2.5',
+  config: {
+    kitKey: process.env.KIT_KEY,
+  },
 })
 ```
 
@@ -423,6 +444,7 @@ await kit.swap({
   tokenOut: 'USDT',
   amountIn: '1000',
   config: {
+    kitKey: process.env.KIT_KEY,
     customFee: {
       value: '10',
       recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
@@ -530,6 +552,9 @@ const result = await kit.swap({
   tokenIn: 'USDC',
   tokenOut: 'USDT',
   amountIn: '100.0',
+  config: {
+    kitKey: process.env.KIT_KEY,
+  },
 })
 
 console.log('Swap result:', result)
@@ -538,7 +563,7 @@ console.log('Swap result:', result)
 ### Send to Different Address
 
 ```typescript
-// Send to a different address (automatically chooses bridge or swap)
+// Send to a different address on the same chain
 const result = await kit.send({
   from: { adapter, chain: 'Ethereum' },
   to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
@@ -576,7 +601,7 @@ await kit.bridge({
 
 ### Core Methods
 
-- `kit.send(params)` - Unified interface for transfers (auto-routes to bridge or swap)
+- `kit.send(params)` - Send tokens to a recipient on the same chain
 - `kit.bridge(params)` - Execute cross-chain bridge operation
 - `kit.swap(params)` - Execute same-chain swap operation
 - `kit.estimateBridge(params)` - Get cost estimates for bridging

package/chains.cjs

@@ -1045,7 +1045,7 @@ const Codex = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1088,7 +1088,7 @@ const CodexTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1350,7 +1350,7 @@ const HyperEVM = defineChain({
     },
     chainId: 999,
     isTestnet: false,
-    explorerUrl: 'https://hyperevmscan.io/tx/{hash}',
+    explorerUrl: 'https://app.hyperliquid.xyz/explorer/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
@@ -1395,7 +1395,7 @@ const HyperEVMTestnet = defineChain({
     },
     chainId: 998,
     isTestnet: true,
-    explorerUrl: 'https://testnet.hyperliquid.xyz/explorer/tx/{hash}',
+    explorerUrl: 'https://app.hyperliquid-testnet.xyz/explorer/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid-testnet.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
@@ -2041,7 +2041,7 @@ const Plume = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2086,7 +2086,7 @@ const PlumeTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2864,7 +2864,7 @@ const XDC = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2908,7 +2908,7 @@ const XDCApothem = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {

package/chains.d.ts

@@ -471,7 +471,7 @@ declare const Codex: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -514,7 +514,7 @@ declare const CodexTestnet: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -640,7 +640,7 @@ declare const HyperEVM: {
     };
     readonly chainId: 999;
     readonly isTestnet: false;
-    readonly explorerUrl: "https://hyperevmscan.io/tx/{hash}";
+    readonly explorerUrl: "https://app.hyperliquid.xyz/explorer/tx/{hash}";
     readonly rpcEndpoints: readonly ["https://rpc.hyperliquid.xyz/evm"];
     readonly eurcAddress: null;
     readonly usdcAddress: "0xb88339CB7199b77E23DB6E890353E22632Ba630f";
@@ -685,7 +685,7 @@ declare const HyperEVMTestnet: {
     };
     readonly chainId: 998;
     readonly isTestnet: true;
-    readonly explorerUrl: "https://testnet.hyperliquid.xyz/explorer/tx/{hash}";
+    readonly explorerUrl: "https://app.hyperliquid-testnet.xyz/explorer/tx/{hash}";
     readonly rpcEndpoints: readonly ["https://rpc.hyperliquid-testnet.xyz/evm"];
     readonly eurcAddress: null;
     readonly usdcAddress: "0x2B3370eE501B4a559b57D449569354196457D8Ab";
@@ -1024,7 +1024,7 @@ declare const Plume: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -1069,7 +1069,7 @@ declare const PlumeTestnet: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -1672,7 +1672,7 @@ declare const XDC: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -1716,7 +1716,7 @@ declare const XDCApothem: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {

package/chains.mjs

@@ -1043,7 +1043,7 @@ const Codex = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1086,7 +1086,7 @@ const CodexTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1348,7 +1348,7 @@ const HyperEVM = defineChain({
     },
     chainId: 999,
     isTestnet: false,
-    explorerUrl: 'https://hyperevmscan.io/tx/{hash}',
+    explorerUrl: 'https://app.hyperliquid.xyz/explorer/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
@@ -1393,7 +1393,7 @@ const HyperEVMTestnet = defineChain({
     },
     chainId: 998,
     isTestnet: true,
-    explorerUrl: 'https://testnet.hyperliquid.xyz/explorer/tx/{hash}',
+    explorerUrl: 'https://app.hyperliquid-testnet.xyz/explorer/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid-testnet.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
@@ -2039,7 +2039,7 @@ const Plume = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2084,7 +2084,7 @@ const PlumeTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2862,7 +2862,7 @@ const XDC = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2906,7 +2906,7 @@ const XDCApothem = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {