@circle-fin/app-kit 1.0.1 → 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

@@ -63,9 +63,9 @@ The App Kit provides a **unified interface** for both cross-chain transfers and
 - **🔧 Bring your own infrastructure**: Seamlessly integrate with your existing setup when needed
 - **🔒 Production-ready security**: Leverages Circle's CCTPv2 for bridging and trusted swap providers
 - **🚀 Developer experience**: Complete TypeScript support, comprehensive validation, and instant connectivity
-- **🌍 Multi-chain support**: Bridge across **35 chains** with **578 total bridge routes** through Circle's CCTPv2
-  - **Mainnet (17 chains)**: Arbitrum, Avalanche, Base, Codex, Ethereum, HyperEVM, Ink, Linea, OP Mainnet, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC
-  - **Testnet (18 chains)**: Arc Testnet, Arbitrum Sepolia, Avalanche Fuji, Base Sepolia, Codex Testnet, Ethereum Sepolia, HyperEVM Testnet, Ink Testnet, Linea Sepolia, OP Sepolia, Plume Testnet, Polygon PoS Amoy, Sei Testnet, Solana Devnet, Sonic Testnet, Unichain Sepolia, World Chain Sepolia, XDC Apothem
+- **🌍 Multi-chain support**: Bridge across **41 chains** with **800 total bridge routes** through Circle's CCTPv2
+  - **Mainnet (20 chains)**: Arbitrum, Avalanche, Base, Codex, Edge, Ethereum, HyperEVM, Ink, Linea, Monad, Morph, OP Mainnet, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC
+  - **Testnet (21 chains)**: Arc Testnet, Arbitrum Sepolia, Avalanche Fuji, Base Sepolia, Codex Testnet, Edge Testnet, Ethereum Sepolia, HyperEVM Testnet, Ink Testnet, Linea Sepolia, Monad Testnet, Morph Testnet, OP Sepolia, Plume Testnet, Polygon PoS Amoy, Sei Testnet, Solana Devnet, Sonic Testnet, Unichain Sepolia, World Chain Sepolia, XDC Apothem
 - **🔄 Swap support**: Same-chain token swaps powered by Circle's Stablecoin Service
 - **🎯 Flexible adapters**: Supporting EVM (Viem, Ethers) and Solana (@solana/web3)
 - **📡 Real-time event monitoring**: Track progress throughout the operation lifecycle
@@ -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
@@ -155,7 +155,7 @@ const result = await kit.bridge({
 })
 ```
 
-All 35 CCTPv2-supported chains are available for import.
+All 41 CCTPv2-supported chains are available for import.
 
 ## Quick Start
 
@@ -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

@@ -52,6 +52,8 @@ var Blockchain;
     Blockchain["Celo_Alfajores_Testnet"] = "Celo_Alfajores_Testnet";
     Blockchain["Codex"] = "Codex";
     Blockchain["Codex_Testnet"] = "Codex_Testnet";
+    Blockchain["Edge"] = "Edge";
+    Blockchain["Edge_Testnet"] = "Edge_Testnet";
     Blockchain["Ethereum"] = "Ethereum";
     Blockchain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
     Blockchain["Hedera"] = "Hedera";
@@ -64,6 +66,8 @@ var Blockchain;
     Blockchain["Linea_Sepolia"] = "Linea_Sepolia";
     Blockchain["Monad"] = "Monad";
     Blockchain["Monad_Testnet"] = "Monad_Testnet";
+    Blockchain["Morph"] = "Morph";
+    Blockchain["Morph_Testnet"] = "Morph_Testnet";
     Blockchain["NEAR"] = "NEAR";
     Blockchain["NEAR_Testnet"] = "NEAR_Testnet";
     Blockchain["Noble"] = "Noble";
@@ -267,11 +271,13 @@ var BridgeChain;
     BridgeChain["Avalanche"] = "Avalanche";
     BridgeChain["Base"] = "Base";
     BridgeChain["Codex"] = "Codex";
+    BridgeChain["Edge"] = "Edge";
     BridgeChain["Ethereum"] = "Ethereum";
     BridgeChain["HyperEVM"] = "HyperEVM";
     BridgeChain["Ink"] = "Ink";
     BridgeChain["Linea"] = "Linea";
     BridgeChain["Monad"] = "Monad";
+    BridgeChain["Morph"] = "Morph";
     BridgeChain["Optimism"] = "Optimism";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
@@ -287,11 +293,13 @@ var BridgeChain;
     BridgeChain["Avalanche_Fuji"] = "Avalanche_Fuji";
     BridgeChain["Base_Sepolia"] = "Base_Sepolia";
     BridgeChain["Codex_Testnet"] = "Codex_Testnet";
+    BridgeChain["Edge_Testnet"] = "Edge_Testnet";
     BridgeChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
     BridgeChain["Ink_Testnet"] = "Ink_Testnet";
     BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
     BridgeChain["Monad_Testnet"] = "Monad_Testnet";
+    BridgeChain["Morph_Testnet"] = "Morph_Testnet";
     BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
     BridgeChain["Plume_Testnet"] = "Plume_Testnet";
     BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
@@ -1037,7 +1045,7 @@ const Codex = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1080,7 +1088,95 @@ const CodexTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Edge Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Edge blockchain.
+ * Edge is an EVM-compatible blockchain.
+ */
+defineChain({
+    type: 'evm',
+    chain: Blockchain.Edge,
+    name: 'Edge',
+    title: 'Edge Mainnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 3343,
+    isTestnet: false,
+    explorerUrl: 'https://pro.edgex.exchange/en-US/explorer/tx/{hash}',
+    rpcEndpoints: ['https://edge-mainnet.g.alchemy.com/public'],
+    eurcAddress: null,
+    usdcAddress: '0x98d2919b9A214E6Fa5384AC81E6864bA686Ad74c',
+    usdtAddress: null,
+    cctp: {
+        domain: 28,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x98706A006bc632Df31CAdFCBD43F38887ce2ca5c',
+                messageTransmitter: '0x5b61381Fc9e58E70EfC13a4A97516997019198ee',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
+    kitContracts: {
+        bridge: '0x6D1AaE1c34Aeb582022916a67f2A655C6f4eDFF2', //Unique bridge address as CCTP address for Edge is also unique
+    },
+});
+
+/**
+ * Edge Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Edge blockchain.
+ * Edge is an EVM-compatible blockchain.
+ */
+defineChain({
+    type: 'evm',
+    chain: Blockchain.Edge_Testnet,
+    name: 'Edge Testnet',
+    title: 'Edge Testnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 33431,
+    isTestnet: true,
+    explorerUrl: 'https://edge-testnet.explorer.alchemy.com/tx/{hash}',
+    rpcEndpoints: ['https://edge-testnet.g.alchemy.com/public'],
+    eurcAddress: null,
+    usdcAddress: '0x2d9F7CAD728051AA35Ecdc472a14cf8cDF5CFD6B',
+    usdtAddress: null,
+    cctp: {
+        domain: 28,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1254,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',
@@ -1299,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',
@@ -1599,6 +1695,94 @@ defineChain({
     },
 });
 
+/**
+ * Morph Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Morph blockchain.
+ * Morph is an EVM-compatible Layer-2 blockchain built on the OP Stack.
+ */
+defineChain({
+    type: 'evm',
+    chain: Blockchain.Morph,
+    name: 'Morph',
+    title: 'Morph Mainnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 2818,
+    isTestnet: false,
+    explorerUrl: 'https://explorer.morph.network/tx/{hash}',
+    rpcEndpoints: ['https://rpc.morphl2.io'],
+    eurcAddress: null,
+    usdcAddress: '0xCfb1186F4e93D60E60a8bDd997427D1F33bc372B',
+    usdtAddress: null,
+    cctp: {
+        domain: 30,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 64,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Morph Hoodi Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Morph blockchain.
+ * Morph is an EVM-compatible Layer-2 blockchain built on the OP Stack.
+ */
+defineChain({
+    type: 'evm',
+    chain: Blockchain.Morph_Testnet,
+    name: 'Morph Hoodi',
+    title: 'Morph Hoodi Testnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 2910,
+    isTestnet: true,
+    explorerUrl: 'https://explorer-hoodi.morphl2.io/tx/{hash}',
+    rpcEndpoints: ['https://rpc-hoodi.morphl2.io'],
+    eurcAddress: null,
+    usdcAddress: '0x7433b41C6c5e1d58D4Da99483609520255ab661B',
+    usdtAddress: null,
+    cctp: {
+        domain: 30,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 64,
+                fastConfirmations: 1,
+            },
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * NEAR Protocol Mainnet chain definition
  * @remarks
@@ -1857,7 +2041,7 @@ const Plume = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1902,7 +2086,7 @@ const PlumeTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2680,7 +2864,7 @@ const XDC = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2724,7 +2908,7 @@ const XDCApothem = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {

package/chains.d.ts

@@ -44,6 +44,8 @@ declare enum Blockchain {
     Celo_Alfajores_Testnet = "Celo_Alfajores_Testnet",
     Codex = "Codex",
     Codex_Testnet = "Codex_Testnet",
+    Edge = "Edge",
+    Edge_Testnet = "Edge_Testnet",
     Ethereum = "Ethereum",
     Ethereum_Sepolia = "Ethereum_Sepolia",
     Hedera = "Hedera",
@@ -56,6 +58,8 @@ declare enum Blockchain {
     Linea_Sepolia = "Linea_Sepolia",
     Monad = "Monad",
     Monad_Testnet = "Monad_Testnet",
+    Morph = "Morph",
+    Morph_Testnet = "Morph_Testnet",
     NEAR = "NEAR",
     NEAR_Testnet = "NEAR_Testnet",
     Noble = "Noble",
@@ -467,7 +471,7 @@ declare const Codex: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -510,7 +514,7 @@ declare const CodexTestnet: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -636,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";
@@ -681,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";
@@ -1020,7 +1024,7 @@ declare const Plume: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -1065,7 +1069,7 @@ declare const PlumeTestnet: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -1668,7 +1672,7 @@ declare const XDC: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {
@@ -1712,7 +1716,7 @@ declare const XDCApothem: {
         };
         readonly forwarderSupported: {
             readonly source: true;
-            readonly destination: false;
+            readonly destination: true;
         };
     };
     readonly kitContracts: {