@circle-fin/app-kit 1.12.1 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # @circle-fin/app-kit
 
+## 1.14.0
+
+### Minor Changes
+
+- Add fast cross-chain deposits and fee estimation to Unified Balance Kit.
+
+  ## Fast cross-chain deposits
+
+  `deposit` and `depositFor` now accept a `to` field and a `config.transferSpeed`
+  of `'FAST'` to burn USDC on the source chain and credit a Gateway balance on a
+  different destination chain in a single relayed flow:
+
+  ```typescript
+  const result = await kit.deposit({
+    from,
+    amount: "10",
+    token: "USDC",
+    to: { chain: "Arc_Testnet" },
+    config: { transferSpeed: "FAST" },
+  });
+  ```
+
+  `DepositResult` now includes `fees`, `progress`, `sourceChain`, and
+  `destinationChain` on the fast path.
+
+  ## Fee estimation
+
+  New `estimateDeposit` method returns an itemized fee breakdown and a signed
+  quote that can be passed directly into a subsequent `deposit` / `depositFor` to
+  lock the price:
+
+  ```typescript
+  const estimate = await kit.estimateDeposit({
+    from,
+    amount: "10",
+    token: "USDC",
+    to: { chain: "Arc_Testnet" },
+    config: { transferSpeed: "FAST" },
+  });
+
+  // Spread the estimate at the top level; re-attach `from` (which holds the signer).
+  // The signed `quote` inside the estimate locks the quoted fee for this call.
+  const result = await kit.deposit({ ...estimate, from });
+  ```
+
+  `estimateDeposit` is also available on `AppKit` via
+  `kit.unifiedBalance.estimateDeposit(...)`.
+
+### Patch Changes
+
+- Fix `getSupportedChains({ sourceFeeSupported: true })` over-reporting source-fee
+  bridging support. Previously, source-fee eligibility was inferred from a contract
+  address shared with the fast-deposit forwarding path, causing fast-deposit-only chains
+  to appear supported and fail at the Quote API instead of being rejected client-side.
+  Source-fee support is now gated on an explicit allowlist of eligible source chains.
+
+## 1.13.0
+
+### Minor Changes
+
+- Add Plasma (mainnet and testnet) support. Bridge USDC to and from Plasma via CCTP v2 in Bridge Kit and App Kit using `'Plasma'` or `'Plasma_Testnet'` as source or destination. No change required unless you want these routes.
+- Configure custom HTTP headers for Circle Gateway API requests through
+  `GatewayV1Config` and `UnifiedBalanceKitConfig`. AppKit's existing top-level
+  `headers` option now also applies to Unified Balance Gateway requests, while
+  `unifiedBalance.headers` can override it.
+
+  The headers are sent with every Gateway API request the provider makes —
+  balances, deposits, spend estimate, transfer, forwarder status polling, and
+  `/v1/info` — and are merged on top of the SDK defaults (such as
+  `Content-Type`) rather than replacing them.
+
+- Bridge Kit and App Kit now support receive-exact forwarded USDC transfers with
+  `config.feePayment: 'source'`. Estimates return the exact recipient amount,
+  signed source-chain fee breakdown, total wallet debit, quote expiry, and an
+  opaque signed quote. Caller-supplied quotes commit to the estimated price and
+  are rejected when they are invalid, mismatched, expired, or too close to
+  expiry; omitting the quote lets the kit fetch one automatically. Quote responses
+  now support both timestamp and source-chain block expiries, and execution
+  validates claimability against the current chain tip before burning.
+  Source-fee bridges emit the same
+  `approve`/`burn`/`mint` step events as the standard bridge path. The CCTP v2
+  provider now also supports explicit mint recipient and destination-caller
+  inputs for signed-fee burns and exposes `emitBridgeStep` for kit-level
+  orchestration.
+
+  Receive-exact source-paid fees are now available on every CCTP v2 EVM source
+  chain the Fee Service supports (FAST where pre-finality is offered, otherwise
+  STANDARD), rather than only the initial set of sources. Discover the
+  source-fee-capable chains with
+  `bridgeKit.getSupportedChains({ sourceFeeSupported: true })` or
+  `appKit.getSupportedChains('bridge', { sourceFeeSupported: true })`.
+
+### Patch Changes
+
+- Accept Circle API keys as the credential for service-backed swap and earn
+  operations via the new `config.apiKey` field. Previously only `kitKey` values
+  were accepted, so a Circle API key was rejected before it could be used.
+
+  `config.kitKey` is deprecated but still works, so no change is required. Move to
+  `config.apiKey` when convenient; when both are set, `apiKey` wins. `apiKey` is
+  also stripped from results and error traces, matching `kitKey`.
+
+- Forwarded EVM→Solana bridges now create the recipient's Associated Token
+  Account (ATA). When a CCTP v2 burn is forwarded (`destination.useForwarder`) to
+  a Solana destination, the provider emits `cctp-forward` hookData carrying
+  `createAta` + the recipient's owner key, instructing Circle's relayer to create
+  the recipient ATA (idempotently, at the relayer's expense) before minting. This
+  prevents mints from targeting a non-existent ATA for fresh Solana wallets, which
+  previously left forwarded transfers unclaimed. Bridges made through Bridge Kit
+  and App Kit inherit this fix automatically.
+
+  EVM destinations are unchanged — they continue to receive the empty forwarding
+  frame. The CCTP v2 provider also exposes a new `getForwarderHookData` utility
+  that builds the destination-appropriate forwarding frame.
+
 ## 1.12.1
 
 ### Patch Changes

package/README.md

@@ -65,9 +65,9 @@ The App Kit provides a **unified interface** for cross-chain transfers, same-cha
 - **🔧 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 **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
+- **🌍 Multi-chain support**: Bridge across **51 chains** with **1250 total bridge routes** through Circle's CCTPv2
+  - **Mainnet (25 chains)**: Arbitrum, Avalanche, Base, Codex, Cronos, Edge, Ethereum, HyperEVM, Injective, Ink, Linea, Monad, Morph, OP Mainnet, Pharos, Plasma, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC, X Layer
+  - **Testnet (26 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, Plasma Testnet, 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)
@@ -203,7 +203,7 @@ const result = await kit.swap({
   tokenOut: 'USDT',
   amountIn: '100.0',
   config: {
-    kitKey: process.env.KIT_KEY,
+    apiKey: process.env.CIRCLE_API_KEY,
   },
 })
 
@@ -214,7 +214,7 @@ const daiSwap = await kit.swap({
   tokenOut: 'USDC',
   amountIn: '500.0',
   config: {
-    kitKey: process.env.KIT_KEY,
+    apiKey: process.env.CIRCLE_API_KEY,
   },
 })
 
@@ -225,7 +225,7 @@ const nativeSwap = await kit.swap({
   tokenOut: 'USDC',
   amountIn: '1.5',
   config: {
-    kitKey: process.env.KIT_KEY,
+    apiKey: process.env.CIRCLE_API_KEY,
   },
 })
 ```
@@ -249,7 +249,7 @@ const swapEstimate = await kit.estimateSwap({
   tokenOut: 'USDT',
   amountIn: '100.0',
   config: {
-    kitKey: process.env.KIT_KEY,
+    apiKey: process.env.CIRCLE_API_KEY,
   },
 })
 
@@ -483,6 +483,25 @@ await kit.send({
 })
 ```
 
+### Authentication
+
+Service-backed operations take a Circle API key as `config.apiKey`. Omit it to
+use the permissionless (keyless) path.
+
+```typescript
+config: {
+  apiKey: process.env.CIRCLE_API_KEY, // <ENV>_API_KEY:<keyId>:<keySecret>
+}
+```
+
+The API key is a server-only secret — supplying it from a browser throws. Hold
+it on your server and forward the prepared transaction to the client.
+
+> **Migrating from `kitKey`:** `config.kitKey` is deprecated in favor of
+> `config.apiKey`. It keeps working, and legacy `KIT_KEY:<keyId>:<keySecret>`
+> values are still accepted, so you can move over at your own pace. When both
+> fields are set, `apiKey` wins.
+
 ### Swap Parameters
 
 For explicit same-chain swaps:
@@ -514,7 +533,7 @@ await kit.swap({
   tokenOut: 'USDC',
   amountIn: '100.0',
   config: {
-    kitKey: process.env.KIT_KEY,
+    apiKey: process.env.CIRCLE_API_KEY,
   },
 })
 
@@ -525,7 +544,7 @@ await kit.swap({
   tokenOut: 'USDT',
   amountIn: '500.0', // SDK automatically handles 18-decimal precision
   config: {
-    kitKey: process.env.KIT_KEY,
+    apiKey: process.env.CIRCLE_API_KEY,
   },
 })
 
@@ -536,7 +555,7 @@ await kit.swap({
   tokenOut: 'USDC',
   amountIn: '2.5',
   config: {
-    kitKey: process.env.KIT_KEY,
+    apiKey: process.env.CIRCLE_API_KEY,
   },
 })
 ```
@@ -584,7 +603,7 @@ await kit.swap({
   tokenOut: 'USDT',
   amountIn: '1000',
   config: {
-    kitKey: process.env.KIT_KEY,
+    apiKey: process.env.CIRCLE_API_KEY,
     customFee: {
       value: '10',
       recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
@@ -716,7 +735,7 @@ const result = await kit.swap({
   tokenOut: 'USDT',
   amountIn: '100.0',
   config: {
-    kitKey: process.env.KIT_KEY,
+    apiKey: process.env.CIRCLE_API_KEY,
   },
 })