@circle-fin/app-kit 1.3.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @circle-fin/app-kit
 
+## 1.4.1
+
+### Patch Changes
+
+- Improved README documentation with corrected code examples and updated architecture diagrams
+
+## 1.4.0
+
+### Minor Changes
+
+- App Kit now supports unified cross-chain USDC balance management. Import from `@circle-fin/app-kit/unifiedBalance` to deposit, spend, query balances, and manage delegates across chains
+
 ## 1.3.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 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.**
+**A one-stop Circle SDK for building stablecoin (e.g. USDC) applications, providing a unified set of on-chain tools for bridging, swapping, unified balance management, and other stablecoin operations.**
 
-_Making cross-chain transfers, same-chain swaps, and token sends as simple as a single function call_
+_Making cross-chain transfers, same-chain swaps, unified balance management, and token sends as simple as a single function call_
 
 </div>
 
@@ -27,6 +27,7 @@ _Making cross-chain transfers, same-chain swaps, and token sends as simple as a
     - [🔄 Same-Chain Swap](#-same-chain-swap)
     - [📊 Estimate Operations](#-estimate-operations)
     - [🔍 Query Supported Chains](#-query-supported-chains)
+    - [💰 Unified Balance](#-unified-balance)
   - [Configuration](#configuration)
     - [Send Parameters](#send-parameters)
     - [Swap Parameters](#swap-parameters)
@@ -53,11 +54,11 @@ _Making cross-chain transfers, same-chain swaps, and token sends as simple as a
 
 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 both cross-chain transfers and same-chain swaps, abstracting away the complexity of choosing between bridging and swapping operations. It combines the power of Bridge Kit and Swap Kit into a single, cohesive API.
+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.
 
 ### Why App Kit?
 
-- **🎯 Unified interface**: Single API for both bridge and swap operations
+- **🎯 Unified interface**: Single API for bridge, swap, 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
@@ -78,39 +79,40 @@ The App Kit provides a **unified interface** for both cross-chain transfers and
 
 ## Architecture Flow
 
-The App Kit follows a composable architecture that integrates Bridge Kit and Swap Kit:
+The App Kit follows a composable architecture that integrates Bridge Kit, Swap Kit, and Unified Balance Kit:
 
 ```text
 ┌─────────────────────────────────────────────────────────────┐
-│                        App Kit                               │
+│                          App Kit                            │
 │                   (Unified Interface)                       │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-         ┌─────────────┴─────────────┐
-         │                           │
-         ▼                           ▼
-┌─────────────────┐         ┌─────────────────┐
-│   Bridge Kit    │         │    Swap Kit     │
-│ (Cross-Chain)   │         │  (Same-Chain)   │
-└────────┬────────┘         └────────┬────────┘
-         │                           │
-         ▼                           ▼
-┌─────────────────┐         ┌─────────────────┐
-│     Provider    │         │     Provider    │
-│   (CCTPv2)      │         │   (Service)     │
-└────────┬────────┘         └────────┬────────┘
-         │                           │
-         └─────────────┬─────────────┘
-                       ▼
-               ┌───────────────┐
-               │    Adapter    │
-               │ (Blockchain)  │
-               └───────────────┘
+└────────────────────────────┬────────────────────────────────┘
+                             │
+                ┌────────────┼─────────────┐
+                │            │             │
+                ▼            ▼             ▼
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
+│   Bridge Kit    │ │    Swap Kit     │ │ Unified Balance Kit │
+│ (Cross-Chain)   │ │  (Same-Chain)   │ │   (Cross-Chain)     │
+└────────┬────────┘ └────────┬────────┘ └──────────┬──────────┘
+         │                   │                     │
+         ▼                   ▼                     ▼
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
+│     Provider    │ │     Provider    │ │       Provider      │
+│     (CCTPv2)    │ │    (Service)    │ │     (Gateway v1)    │
+└────────┬────────┘ └────────┬────────┘ └──────────┬──────────┘
+         │                   │                     │
+         └───────────────────┼─────────────────────┘
+                             │
+                             ▼
+                    ┌─────────────────┐
+                    │     Adapter     │
+                    │  (Blockchain)   │
+                    └─────────────────┘
 ```
 
 1. **Adapter**: Handles blockchain-specific operations (wallets, transactions, gas)
-2. **Provider**: Implements protocols (CCTPv2 for bridging, Circle Service for swaps)
-3. **Bridge/Swap Kit**: Specialized kits for each operation type
+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
 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.
@@ -262,16 +264,75 @@ console.log(
 Check which chains support specific operations:
 
 ```typescript
+// Get all chains (bridge, swap, and unified balance)
+const allChains = kit.getSupportedChains()
+
 // Get all chains that support bridging
 const bridgeChains = kit.getSupportedChains('bridge')
 
 // Get all chains that support swapping
 const swapChains = kit.getSupportedChains('swap')
 
-// Get all chains (both bridge and swap)
-const allChains = kit.getSupportedChains()
+// Get chains that support unified balance operations
+const ubChains = kit.getSupportedChains('unifiedBalance')
+```
+
+### 💰 Unified Balance
+
+Manage a unified, cross-chain USDC balance — deposit on any chain, spend on any other, query balances, and manage delegates:
+
+```typescript
+import { AppKit } 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,
+})
+
+// Query balances across all chains
+const balances = await kit.unifiedBalance.getBalances({
+  token: 'USDC',
+  sources: { adapter },
+})
+
+// Deposit USDC into unified balance
+const deposit = await kit.unifiedBalance.deposit({
+  from: { adapter, chain: 'Ethereum' },
+  amount: '100',
+  token: 'USDC',
+})
+
+// Spend from unified balance on a different chain
+const spend = await kit.unifiedBalance.spend({
+  amount: '50',
+  token: 'USDC',
+  from: { adapter, allocations: [{ amount: '50', chain: 'Ethereum' }] },
+  to: { adapter, chain: 'Base' },
+})
+
+// Estimate spend fees before executing
+const estimate = await kit.unifiedBalance.estimateSpend({
+  amount: '50',
+  token: 'USDC',
+  from: { adapter, allocations: [{ amount: '50', chain: 'Ethereum' }] },
+  to: { adapter, chain: 'Base' },
+})
+
+// Manage delegates
+await kit.unifiedBalance.addDelegate({
+  from: { adapter, chain: 'Ethereum' },
+  delegateAddress: '0xDelegate…',
+})
+
+// Listen to unified balance events
+kit.on('unifiedBalance.gateway.spend.succeeded', (payload) => {
+  console.log('Spend succeeded:', payload)
+})
 ```
 
+For the full Unified Balance API, see the [`@circle-fin/unified-balance-kit` README](../unified-balance-kit/README.md).
+
 ## Configuration
 
 ### Send Parameters
@@ -611,10 +672,11 @@ 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
+- `kit.getSupportedChains(operationType?)` - Query supported chains by operation type (`'bridge'`, `'swap'`, `'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.
 
 ## Development