@circle-fin/app-kit 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @circle-fin/app-kit
 
+## 1.12.0
+
+### Minor Changes
+
+- Add X Layer chain definitions (mainnet and testnet) with CCTP v2 support, USDC token addresses, Viem adapter mappings, Bridge Kit exports.
+- Add App Kit-level operation-scoped custom fee policy configuration and scoped
+  custom fee policy removal. Align the README with the current public API,
+  including explicit operation methods, supported send and swap tokens, and the
+  complete core method list.
+
+- Same-chain Earn deposits, withdrawals, and reward claims can now surface a
+  verified `earn.execute` review to an adapter `onBeforeAuthorize` hook before
+  authorization. Use `isEarnExecuteReview` to inspect the decoded Earn operation
+  and exact call data; returning `reject` prevents signing.
+- Support spending a unified balance from a smart contract account via Gateway's
+  ERC-1271 programmable authorization.
+
+  Previously, `spend` rejected any smart contract account (SCA) signer up front
+  and told you to register an EOA delegate against the SCA, because Gateway
+  validated burn-intent signatures with `ecrecover` only. Gateway now also
+  validates contract signatures with ERC-1271, so the SDK detects a contract
+  signer from its on-chain bytecode and marks the transfer request
+  `contractSigner: true` — multisigs, passkey wallets, Circle SCA wallets, and
+  other ERC-1271 accounts can authorize transfers directly.
+
+  No API change: `spend` takes the same parameters and picks the validation path
+  for you. EOA transfers are unaffected, and EIP-7702-delegated EOAs keep using
+  the `ecrecover` path since their signatures verify that way.
+
+  ERC-1271 validation is EVM-only. Solana burn intents are unchanged.
+
+### Patch Changes
+
+- Batch same-chain Earn deposits and withdrawals through an adapter's shared
+  `supportsAtomicBatch` and `batchExecute` capabilities. Approval and execution
+  calls are submitted atomically when supported, with a configuration option to
+  force the existing sequential flow. Legacy Viem batches now request atomic
+  EIP-5792 execution by default.
+
+## 1.11.0
+
+### Minor Changes
+
+- AppKit now accepts `disableAnalytics` to turn off success analytics in its
+  underlying EarnKit, SwapKit, and UnifiedBalanceKit operations. Use the existing
+  `disableErrorReporting` option to turn off error reporting.
+
+### Patch Changes
+
+- Clarify Unified Balance `removeFund` documentation as a recovery path with a
+  7-day withdrawal delay.
+- Make the SDK safe to bundle and run in browsers/client-side apps.
+
+  - Browser requests omit Node-only headers that would cause CORS failures, including EarnKit’s SDK-version header.
+  - Solana operations in App Kit, Adapter Solana Kit, and Gateway work in a browser without requiring a consumer-provided `Buffer` polyfill.
+  - Supplying a `kitKey` or Circle Wallets `apiKey` in a browser now fails early. Keep those secrets on the server and forward a prepared transaction or other safe result to the client.
+
+- EarnKit now sends structured telemetry for public-operation errors and for
+  completed vault lookups, vault discovery, deposits, withdrawals, and reward
+  claims. No code changes are required. Telemetry is enabled by default and
+  contains no wallet addresses or amounts. To opt out when constructing
+  `EarnKit`:
+
+  ```ts
+  const kit = new EarnKit({
+    disableAnalytics: true,
+    disableErrorReporting: true,
+  });
+  ```
+
+  AppKit now forwards its existing `disableErrorReporting` option to its EarnKit
+  operations.
+
 ## 1.10.0
 
 ### Minor Changes

package/README.md

@@ -35,7 +35,7 @@ _Making cross-chain transfers, same-chain swaps, unified balance management, and
     - [Bridge Parameters](#bridge-parameters)
   - [Custom Fees](#custom-fees)
     - [Operation-Level Custom Fees](#operation-level-custom-fees)
-    - [Kit-Level Fee Policies](#kit-level-fee-policies)
+    - [Kit-Level Custom Fee Policies](#kit-level-custom-fee-policies)
   - [Error Handling](#error-handling)
   - [Examples](#examples)
     - [Basic Cross-Chain Transfer](#basic-cross-chain-transfer)
@@ -55,19 +55,19 @@ _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, 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.
+The App Kit provides a **unified interface** for cross-chain transfers, same-chain swaps, token sends, earn vault operations, and unified balance management. It combines the power of Bridge Kit, Swap Kit, Earn Kit, and Unified Balance Kit into a single, cohesive API with explicit methods for each operation.
 
 ### Why App Kit?
 
-- **🎯 Unified interface**: Single API for bridge, swap, earn, and unified balance operations
-- **🤖 Smart routing**: Automatically selects the appropriate operation (bridge vs swap)
+- **🎯 Unified interface**: Single SDK surface for bridge, swap, send, earn, and unified balance operations
+- **🧭 Explicit operation methods**: Choose `bridge`, `swap`, `send`, `earn`, or `unifiedBalance` based on the flow you are building
 - **⚡ Zero-config defaults**: Built-in reliable RPC endpoints - start building right away
 - **🔧 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 **47 chains** with **1058 total bridge routes** through Circle's CCTPv2
-  - **Mainnet (23 chains)**: Arbitrum, Avalanche, Base, Codex, Cronos, Edge, Ethereum, HyperEVM, Injective, Ink, Linea, Monad, Morph, OP Mainnet, Pharos, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC
-  - **Testnet (24 chains)**: Arc Testnet, Arbitrum Sepolia, Avalanche Fuji, Base Sepolia, Codex Testnet, Cronos 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
+- **🌍 Multi-chain support**: Bridge across **49 chains** with **1152 total bridge routes** through Circle's CCTPv2
+  - **Mainnet (24 chains)**: Arbitrum, Avalanche, Base, Codex, Cronos, Edge, Ethereum, HyperEVM, Injective, Ink, Linea, Monad, Morph, OP Mainnet, Pharos, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC, X Layer
+  - **Testnet (25 chains)**: Arc Testnet, Arbitrum Sepolia, Avalanche Fuji, Base Sepolia, Codex Testnet, Cronos 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, X Layer Testnet
 - **🔄 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)
@@ -163,7 +163,7 @@ const result = await kit.bridge({
 })
 ```
 
-All 41 CCTPv2-supported chains are available for import.
+A curated subset of 37 CCTPv2-supported chains is available for import from App Kit.
 
 ## Quick Start
 
@@ -429,13 +429,15 @@ The `token` field accepts both known aliases and custom token contract addresses
 - `'USDC'` - USD Coin (6 decimals)
 - `'USDT'` - Tether USD (6 decimals)
 - `'NATIVE'` - Chain's native currency (ETH, SOL, etc.)
+- `'EURC'` - Euro Coin, on chains with `eurcAddress` configured
 
 **Custom addresses:**
 
 - EVM contract addresses (e.g., `0x6B175474E89094C44Da98b954EedeAC495271d0F`)
 - Solana SPL mint addresses
 
-**Note**: For swap operations, additional stablecoins (EURC, DAI, USDE, PYUSD) are supported. See [Swap Parameters](#swap-parameters) section below.
+**Note**: For swap operations, additional stablecoins and wrapped assets are
+supported. See [Swap Parameters](#swap-parameters) section below.
 
 **Examples**
 
@@ -498,6 +500,7 @@ interface SwapParams {
 // SupportedToken includes:
 // - Stablecoins (6 decimals): 'USDC', 'EURC', 'USDT', 'PYUSD'
 // - Stablecoins (18 decimals): 'DAI', 'USDE'
+// - Wrapped assets: 'WBTC', 'WETH', 'WSOL', 'WAVAX', 'WPOL', 'CIRBTC'
 // - Native: 'NATIVE' (chain's native currency)
 ```
 
@@ -590,38 +593,61 @@ await kit.swap({
 })
 ```
 
-### Kit-Level Fee Policies
+### Kit-Level Custom Fee Policies
 
-For dynamic fee calculation across all operations, use kit-level policies:
+For dynamic fee calculation, provide operation-scoped custom fee policies at the
+App Kit level. Configure only the operations that need custom fees.
 
 ```typescript
 import { AppKit } from '@circle-fin/app-kit'
-import { formatUnits } from 'viem'
 
 const kit = new AppKit()
 
 kit.setCustomFeePolicy({
-  calculateFee: (params) => {
-    // Calculate fee based on operation type and parameters
-    const amount = Number(formatUnits(BigInt(params.amount), 6))
-    const feePercentage = type === 'bridge' ? 0.01 : 0.005 // 1% for bridge, 0.5% for swap
-
-    return (amount * feePercentage).toFixed(6)
+  bridge: {
+    computeFee: (params) => {
+      const amount = Number(params.amount)
+      return (amount * 0.01).toFixed(6)
+    },
+    resolveFeeRecipientAddress: (chain) => {
+      return chain.type === 'solana'
+        ? 'SolanaAddressBase58...'
+        : '0xEvmAddress...'
+    },
   },
-  resolveFeeRecipientAddress: (type, info) => {
-    // Return appropriate address based on operation type and chain
-    return info.chain.type === 'solana'
-      ? 'SolanaAddressBase58...'
-      : '0xEvmAddress...'
+  swap: {
+    computeFee: (params) => {
+      const amount = Number(params.amountIn)
+      return (amount * 0.005).toFixed(6)
+    },
+    resolveFeeRecipientAddress: (chain) => {
+      return chain.type === 'solana'
+        ? 'SolanaAddressBase58...'
+        : '0xEvmAddress...'
+    },
+  },
+  unifiedBalance: {
+    computeFee: (params) => {
+      const amount = Number(params.amount)
+      return (amount * 0.01).toFixed(6)
+    },
+    resolveFeeRecipientAddress: (destinationChain) => {
+      return destinationChain.type === 'solana'
+        ? 'SolanaAddressBase58...'
+        : '0xEvmAddress...'
+    },
   },
 })
 
-// All subsequent operations will use this policy
+// All subsequent configured operations will use these policies
 await kit.bridge({
   from: { adapter, chain: 'Ethereum' },
   to: { adapter, chain: 'Base' },
   amount: '1000', // Custom fee calculated automatically
 })
+
+// Remove one operation-scoped policy without affecting the others
+kit.removeCustomFeePolicy('bridge')
 ```
 
 ## Error Handling
@@ -740,12 +766,17 @@ await kit.bridge({
 
 - `kit.send(params)` - Send tokens to a recipient on the same chain
 - `kit.bridge(params)` - Execute cross-chain bridge operation
+- `kit.retryBridge(result, retryContext)` - Retry a failed bridge operation
 - `kit.swap(params)` - Execute same-chain swap operation
 - `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.getSwapStatus(params)` - Fetch the current status of a swap
+- `kit.waitForSwap(params)` - Poll until a swap reaches a terminal status
+- `kit.getTokenRates(params)` - Fetch cached token USD rates
 - `kit.getSupportedChains(operationType?)` - Query supported chains by operation type (`'bridge'`, `'swap'`, `'earn'`, `'unifiedBalance'`)
-- `kit.setCustomFeePolicy(policy)` - Set kit-level custom fee policy
+- `kit.setCustomFeePolicy(policy)` - Set operation-scoped custom fee policies
+- `kit.removeCustomFeePolicy(operation)` - Remove an operation-scoped 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.