@circle-fin/app-kit 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @circle-fin/app-kit
 
+## 1.6.0
+
+### Minor Changes
+
+- AppKit now exposes Earn operations through `kit.earn`, including supported-chain discovery and re-exports of Earn-related types.
+
+## 1.5.1
+
+### Patch Changes
+
+- Improves the error you get when attempting a Gateway spend with a smart-contract account (SCA) as the signer. The failure previously surfaced as a confusing `invalid integer value <nil>/<nil> for type uint256` response from the Circle Wallets backend; you now get a clear `INPUT_UNSUPPORTED_ACTION` error up front that points at the delegate workflow (`kit.unifiedBalance.addDelegate` + `kit.unifiedBalance.spend` with the delegate EOA as `from.address` and the SCA as `from.sourceAccount`).
+
 ## 1.5.0
 
 ### Minor Changes

package/README.md

@@ -28,6 +28,7 @@ _Making cross-chain transfers, same-chain swaps, unified balance management, and
     - [📊 Estimate Operations](#-estimate-operations)
     - [🔍 Query Supported Chains](#-query-supported-chains)
     - [💰 Unified Balance](#-unified-balance)
+    - [🏦 Earn](#-earn)
   - [Configuration](#configuration)
     - [Send Parameters](#send-parameters)
     - [Swap Parameters](#swap-parameters)
@@ -54,11 +55,11 @@ _Making cross-chain transfers, same-chain swaps, unified balance management, and
 
 The App Kit ecosystem is Circle's open-source effort to streamline stablecoin development with SDKs that are easy to use correctly and hard to misuse. Kits are cross-framework (viem, ethers, @solana/web3) and integrate cleanly into any stack. They're opinionated with sensible defaults, but offer escape hatches for full control. A pluggable architecture makes implementation flexible, and all kits are interoperable, so they can be composed to suit a wide range of use cases.
 
-The App Kit provides a **unified interface** for cross-chain transfers, same-chain swaps, and unified balance management, abstracting away the complexity of choosing between operations. It combines the power of Bridge Kit, Swap Kit, and Unified Balance Kit into a single, cohesive API.
+The App Kit provides a **unified interface** for cross-chain transfers, same-chain swaps, earn vault operations, and unified balance management, abstracting away the complexity of choosing between operations. It combines the power of Bridge Kit, Swap Kit, Earn Kit, and Unified Balance Kit into a single, cohesive API.
 
 ### Why App Kit?
 
-- **🎯 Unified interface**: Single API for bridge, swap, and unified balance operations
+- **🎯 Unified interface**: Single API for bridge, swap, earn, and unified balance operations
 - **🤖 Smart routing**: Automatically selects the appropriate operation (bridge vs swap)
 - **⚡ Zero-config defaults**: Built-in reliable RPC endpoints - start building right away
 - **🔧 Bring your own infrastructure**: Seamlessly integrate with your existing setup when needed
@@ -68,6 +69,7 @@ The App Kit provides a **unified interface** for cross-chain transfers, same-cha
   - **Mainnet (22 chains)**: Arbitrum, Avalanche, Base, Codex, Edge, Ethereum, HyperEVM, Injective, Ink, Linea, Monad, Morph, OP Mainnet, Pharos, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC
   - **Testnet (23 chains)**: Arc Testnet, Arbitrum Sepolia, Avalanche Fuji, Base Sepolia, Codex Testnet, Edge Testnet, Ethereum Sepolia, HyperEVM Testnet, Injective Testnet, Ink Testnet, Linea Sepolia, Monad Testnet, Morph Testnet, OP Sepolia, Pharos Atlantic, 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
+- **🏦 Earn support**: DeFi lending vault deposits, withdrawals, and reward claims via `kit.earn`
 - **🎯 Flexible adapters**: Supporting EVM (Viem, Ethers) and Solana (@solana/web3)
 - **📡 Real-time event monitoring**: Track progress throughout the operation lifecycle
 - **🛡️ Robust error handling**: Graceful partial success recovery
@@ -79,40 +81,40 @@ The App Kit provides a **unified interface** for cross-chain transfers, same-cha
 
 ## Architecture Flow
 
-The App Kit follows a composable architecture that integrates Bridge Kit, Swap Kit, and Unified Balance Kit:
+The App Kit follows a composable architecture that integrates Bridge Kit, Swap Kit, Unified Balance Kit, and Earn Kit:
 
 ```text
-┌─────────────────────────────────────────────────────────────┐
-│                          App Kit                            │
-│                   (Unified Interface)                       │
-└────────────────────────────┬────────────────────────────────┘
-                             │
-                ┌────────────┼─────────────┐
-                │            │             │
-                ▼            ▼             ▼
-┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
-│   Bridge Kit    │ │    Swap Kit     │ │ Unified Balance Kit │
-│ (Cross-Chain)   │ │  (Same-Chain)   │ │   (Cross-Chain)     │
-└────────┬────────┘ └────────┬────────┘ └──────────┬──────────┘
-         │                   │                     │
-         ▼                   ▼                     ▼
-┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
-│     Provider    │ │     Provider    │ │       Provider      │
-│     (CCTPv2)    │ │    (Service)    │ │     (Gateway v1)    │
-└────────┬────────┘ └────────┬────────┘ └──────────┬──────────┘
-         │                   │                     │
-         └───────────────────┼─────────────────────┘
-                             │
-                             ▼
-                    ┌─────────────────┐
-                    │     Adapter     │
-                    │  (Blockchain)   │
-                    └─────────────────┘
+┌──────────────────────────────────────────────────────────────────────────┐
+│                                 App Kit                                  │
+│                           (Unified Interface)                            │
+└───────────────────────────────────┬──────────────────────────────────────┘
+                                    │
+       ┌────────────────┬───────────┴──────┬──────────────────┐
+       │                │                  │                  │
+       ▼                ▼                  ▼                  ▼
+┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
+│  Bridge Kit  │ │   Swap Kit   │ │ Unified Balance  │ │   Earn Kit   │
+│ (Cross-Chain)│ │ (Same-Chain) │ │      Kit         │ │  (Vaults)    │
+└──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ └──────┬───────┘
+       │                │                  │                  │
+       ▼                ▼                  ▼                  ▼
+┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
+│   Provider   │ │   Provider   │ │     Provider     │ │   Provider   │
+│   (CCTPv2)   │ │  (Service)   │ │   (Gateway v1)   │ │   (Earn)     │
+└──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ └──────┬───────┘
+       │                │                  │                  │
+       └────────────────┴───────────┬──────┴──────────────────┘
+                                    │
+                                    ▼
+                           ┌─────────────────┐
+                           │     Adapter     │
+                           │  (Blockchain)   │
+                           └─────────────────┘
 ```
 
 1. **Adapter**: Handles blockchain-specific operations (wallets, transactions, gas)
-2. **Provider**: Implements protocols (CCTPv2 for bridging, Circle Service for swaps, Gateway for unified balance)
-3. **Bridge/Swap/Unified Balance Kit**: Specialized kits for each operation type
+2. **Provider**: Implements protocols (CCTPv2 for bridging, Circle Service for swaps, Gateway for unified balance, Earn for vaults)
+3. **Bridge/Swap/Unified Balance/Earn Kit**: Specialized kits for each operation type
 4. **App Kit**: Unified orchestration layer providing a consistent API
 
 This separation ensures that each component has a single responsibility while maintaining seamless integration across the entire stablecoin operation lifecycle.
@@ -264,7 +266,7 @@ console.log(
 Check which chains support specific operations:
 
 ```typescript
-// Get all chains (bridge, swap, and unified balance)
+// Get all chains (bridge, swap, earn, and unified balance)
 const allChains = kit.getSupportedChains()
 
 // Get all chains that support bridging
@@ -273,6 +275,9 @@ const bridgeChains = kit.getSupportedChains('bridge')
 // Get all chains that support swapping
 const swapChains = kit.getSupportedChains('swap')
 
+// Get chains that support earn vault operations
+const earnChains = kit.getSupportedChains('earn')
+
 // Get chains that support unified balance operations
 const ubChains = kit.getSupportedChains('unifiedBalance')
 ```
@@ -333,6 +338,48 @@ kit.on('unifiedBalance.gateway.spend.succeeded', (payload) => {
 
 For the full Unified Balance API, see the [`@circle-fin/unified-balance-kit` README](../unified-balance-kit/README.md).
 
+### 🏦 Earn
+
+Deposit into and withdraw from DeFi lending vaults, claim rewards, and query positions:
+
+```typescript
+import { AppKit, EarnChain } from '@circle-fin/app-kit'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+const kit = new AppKit()
+const adapter = createViemAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as string,
+})
+
+// Preview a deposit
+const quote = await kit.earn.getDepositQuote({
+  from: { adapter, chain: EarnChain.Arc_Testnet },
+  vaultAddress: '0x1234567890abcdef1234567890abcdef12345678',
+  amount: '100.50',
+})
+
+// Execute the deposit
+await kit.earn.deposit({
+  from: { adapter, chain: EarnChain.Arc_Testnet },
+  vaultAddress: '0x1234567890abcdef1234567890abcdef12345678',
+  amount: '100.50',
+})
+
+// Query a vault position
+const position = await kit.earn.getPosition({
+  from: { adapter, chain: EarnChain.Arc_Testnet },
+  vaultAddress: '0x1234567890abcdef1234567890abcdef12345678',
+})
+
+// Claim accrued rewards
+await kit.earn.claimRewards({
+  from: { adapter, chain: EarnChain.Arc_Testnet },
+  vaultAddress: '0x1234567890abcdef1234567890abcdef12345678',
+})
+```
+
+For the full Earn API, see the [`@circle-fin/earn-kit` README](../earn-kit/README.md).
+
 ## Configuration
 
 ### Send Parameters
@@ -672,11 +719,12 @@ await kit.bridge({
 - `kit.estimateBridge(params)` - Get cost estimates for bridging
 - `kit.estimateSwap(params)` - Get cost estimates for swapping
 - `kit.estimateSend(params)` - Get cost estimates for send operation
-- `kit.getSupportedChains(operationType?)` - Query supported chains by operation type (`'bridge'`, `'swap'`, `'unifiedBalance'`)
+- `kit.getSupportedChains(operationType?)` - Query supported chains by operation type (`'bridge'`, `'swap'`, `'earn'`, `'unifiedBalance'`)
 - `kit.setCustomFeePolicy(policy)` - Set kit-level custom fee policy
 - `kit.on(event, handler)` - Listen to operation events
 - `kit.off(event, handler)` - Remove event listener
 - `kit.unifiedBalance.*` - Unified balance operations (deposit, spend, getBalances, estimateSpend, delegates, and more). See the [`@circle-fin/unified-balance-kit` README](../unified-balance-kit/README.md) for the full API.
+- `kit.earn.*` - Earn vault operations (deposit, withdraw, claimRewards, getVaults, getPosition, and quote helpers). See the [`@circle-fin/earn-kit` README](../earn-kit/README.md) for the full API.
 
 ## Development
 

package/chains.cjs

@@ -379,23 +379,21 @@ var UnifiedBalanceChain;
  * 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 },
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
  *   vaultAddress: '0x...',
  *   amount: '100',
  * })
  * ```
  */
+// Values must match Blockchain enum members exactly.
 var EarnChain;
 (function (EarnChain) {
-    EarnChain["Ethereum"] = "Ethereum";
+    EarnChain["Arc_Testnet"] = "Arc_Testnet";
 })(EarnChain || (EarnChain = {}));
 
 /**
@@ -3931,7 +3929,7 @@ zod.z.union([
  * 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
+ * deposit/withdraw) operations. Currently only Arc Testnet is
  * supported.
  *
  * Accept an EarnChain enum value, a matching string literal, or
@@ -3940,12 +3938,12 @@ zod.z.union([
  * @example
  * ```typescript
  * import { earnChainIdentifierSchema } from '@core/chains'
- * import { EarnChain, Ethereum } from '@core/chains'
+ * import { ArcTestnet, EarnChain } from '@core/chains'
  *
  * // Valid
- * earnChainIdentifierSchema.parse(EarnChain.Ethereum)
- * earnChainIdentifierSchema.parse('Ethereum')
- * earnChainIdentifierSchema.parse(Ethereum)
+ * earnChainIdentifierSchema.parse(EarnChain.Arc_Testnet)
+ * earnChainIdentifierSchema.parse('Arc_Testnet')
+ * earnChainIdentifierSchema.parse(ArcTestnet)
  *
  * // Invalid (throws ZodError)
  * earnChainIdentifierSchema.parse('Solana')

package/chains.mjs

@@ -377,23 +377,21 @@ var UnifiedBalanceChain;
  * 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 },
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
  *   vaultAddress: '0x...',
  *   amount: '100',
  * })
  * ```
  */
+// Values must match Blockchain enum members exactly.
 var EarnChain;
 (function (EarnChain) {
-    EarnChain["Ethereum"] = "Ethereum";
+    EarnChain["Arc_Testnet"] = "Arc_Testnet";
 })(EarnChain || (EarnChain = {}));
 
 /**
@@ -3929,7 +3927,7 @@ z.union([
  * 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
+ * deposit/withdraw) operations. Currently only Arc Testnet is
  * supported.
  *
  * Accept an EarnChain enum value, a matching string literal, or
@@ -3938,12 +3936,12 @@ z.union([
  * @example
  * ```typescript
  * import { earnChainIdentifierSchema } from '@core/chains'
- * import { EarnChain, Ethereum } from '@core/chains'
+ * import { ArcTestnet, EarnChain } from '@core/chains'
  *
  * // Valid
- * earnChainIdentifierSchema.parse(EarnChain.Ethereum)
- * earnChainIdentifierSchema.parse('Ethereum')
- * earnChainIdentifierSchema.parse(Ethereum)
+ * earnChainIdentifierSchema.parse(EarnChain.Arc_Testnet)
+ * earnChainIdentifierSchema.parse('Arc_Testnet')
+ * earnChainIdentifierSchema.parse(ArcTestnet)
  *
  * // Invalid (throws ZodError)
  * earnChainIdentifierSchema.parse('Solana')