@circle-fin/app-kit 1.8.1 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @circle-fin/app-kit
 
+## 1.10.0
+
+### Minor Changes
+
+- Emit earn step events from `AppKit.on()` / `off()` and add `kit.earn.retry()` for resumable multi-phase earn failures.
+- Add `setFeeRecipients()` / `removeFeeRecipients()` on `appKit.unifiedBalance`. Declare fee recipient addresses per chain type (`{ evm, solana }`) instead of writing per-chain branching logic in a `resolveFeeRecipientAddress` callback. Mirrors the same methods added to `@circle-fin/unified-balance-kit`.
+- Surface bridge quote metadata and quote-expired errors for cross-chain Earn deposits.
+
+  Cross-chain deposit results now include optional `quoteIssuedAt` and `quoteExpiry` metadata so applications can display quote validity and refresh before expiration. Expired quotes are surfaced as fatal `EarnError.BRIDGE_QUOTE_EXPIRED` errors, signaling that callers should start a new prepare/deposit flow instead of retrying stale prepared data.
+
+- Swap no longer requires a Stablecoin Service kit key. You can now call `swap`, `estimateSwap`, `getSwapStatus`, `getTokenRates`, and `waitForSwap` without one — unblocking client-side and browser apps that can't safely ship a secret key.
+
+  This is non-breaking: if you already pass a `kitKey` it keeps working unchanged (and an invalid key is still rejected). To go keyless, omit `kitKey` from your config.
+
+### Patch Changes
+
+- Deposit and withdrawal quotes now report the gas-fee estimate provided by the Earn Service instead of estimating it in the SDK. Previously the SDK estimated gas locally by simulating each action against current on-chain state, so the deposit or withdrawal entry could come back as `fees: null` with a revert error whenever a token approval had not yet been made — the Earn Service estimates gas for those actions, so quotes now return a usable gas fee in that case. Claim-rewards quotes do not carry a gas estimate (the service does not provide one), so their `gasFees` is now always empty. The response shape is unchanged (`EarnGasFeeEstimate[]`).
+- Format cross-chain swap fees against the chain the fee token is denominated on. Swap, provider, and developer fees paid in the destination (output) token were resolved against the source chain, so the token symbol and decimals could not be found and the amount was returned as raw base units. This was most visible for Solana → any-chain swaps (e.g. a swap fee paid in EURC on Base surfaced as `'13202'` instead of `'0.013202'`). Fees now prefer the `decimals`/`symbol` the service supplies on each fee item, and otherwise resolve against whichever of the source or destination chain recognises the fee token, so amounts are consistently human-readable.
+- Fix automatic allocation (`amountIn`) sometimes failing with an insufficient-balance error even when your balance was sufficient.
+
+  When you let the SDK choose which chains to draw from (passing `amountIn` instead of explicit `allocations`), a transfer could be rejected with `BALANCE_INSUFFICIENT_TOKEN` (9001) even though you held enough USDC, and topping up did not help.
+
+  Auto-allocation now accounts for the network's actual gas fee before submitting, so these transfers go through. If your balance genuinely cannot cover the amount plus gas, you now get a clear `BALANCE_INSUFFICIENT_GAS` (9002) error naming the affected chain and the shortfall, instead of an opaque rejection — reduce the amount or add USDC on that chain. Transfers with explicit `allocations` are unchanged, and there is no extra latency unless a correction is actually needed.
+
+- Swaps that require an ERC-20 approval now submit the approval and the swap as a single atomic batch when your wallet supports it — one signing prompt instead of two for smart-contract wallets. Native-token and gasless permit swaps are unchanged.
+
+## 1.9.0
+
+### Minor Changes
+
+- Add support for bridging USDC to and from Cronos (mainnet and testnet) via CCTP v2.
+- Support `token: 'EURC'` in App Kit `send()` and `estimateSend()`.
+
+  `EURC` is now a recognized token alias alongside `USDC`, `USDT`, and `NATIVE`.
+  On chains where EURC is deployed (the chain definition's `eurcAddress` is set,
+  e.g. Arc Testnet), `send({ token: 'EURC', ... })` resolves the EURC contract
+  address and routes the transfer through the generic token transfer action with
+  6 decimals. On chains without an `eurcAddress`, `EURC` is rejected with an
+  `INPUT_UNSUPPORTED_TOKEN` error.
+
+  Previously `send()` rejected `token: 'EURC'` outright — even on chains where
+  EURC was configured — because `EURC` was not in the send token alias list.
+
+- Add a `headers` config option to forward custom HTTP headers with CCTP
+  attestation API requests.
+
+  `CCTPV2Config`, `BridgeKitConfig`, and the AppKit context now accept an optional
+  `headers` map. The headers are sent with every Circle attestation (Iris) API
+  request the CCTP v2 provider makes — attestation fetch, re-attestation, and
+  relayer mint status polling — and are merged on top of the SDK defaults (such
+  as `Content-Type`) rather than replacing them.
+
+### Patch Changes
+
+- Fix withdrawal fee metadata being dropped, and correctly surface errors for pending profit-and-loss (PnL) calculations.
+- Fix a missing runtime dependency (`@coral-xyz/anchor`, `@noble/curves`, `bn.js`,
+  `@ethersproject/keccak256`, and `pino`) that could cause `Could not find package`
+  errors under strict module resolvers (Deno, Supabase Edge Runtime, pnpm).
+
 ## 1.8.1
 
 ### Patch Changes
@@ -68,6 +127,7 @@
 
 - Enable Circle's Forwarding Service as a destination for Solana (mainnet and devnet). A Gateway `spend` with `useForwarder: true` to a Solana destination is now accepted instead of being rejected.
 - Add cross-chain swap support to SwapKit, AppKit, and the Stablecoin Service swap provider.
+
   - `swap` and `estimate` can now route the output token to another supported chain with `to.chain`.
   - Cross-chain swaps can send the output to a recipient on the destination chain with `to.recipientAddress`.
   - `getSwapStatus` and `waitForSwap` can now track cross-chain swaps until they finish, including progress details for source and destination activity.
@@ -75,6 +135,7 @@
   - Invalid transaction hashes or unsupported chain values are reported as structured validation errors before a status request is sent.
 
 - Add `getTokenRates` to SwapKit and AppKit for fetching USD rates for tokens on a chain.
+
   - Look up rates by registered token symbol, native token alias (`NATIVE`, `ETH`, `POL`, etc.), raw EVM token address, or Solana mint.
   - Token symbols are resolved through the kit token registry for the requested chain.
   - Native tokens are normalized to the service native-token address before the request is sent.
@@ -88,6 +149,7 @@
   | Code   | Name          | Type      | Recoverability |
   | ------ | ------------- | --------- | -------------- |
   | `8104` | `EARN_PAUSED` | `SERVICE` | `RETRYABLE`    |
+
   - `@circle-fin/earn-kit` / `@circle-fin/app-kit`: the publicly re-exported
     `EarnError` registry now includes `EARN_PAUSED`. Consumers that branch on
     `EarnError` (or on `recoverability`) gain this value and can detect the
@@ -133,6 +195,7 @@
   A cross-chain `deposit()` returns an `execId` while the bridge (source burn ->
   CCTP attestation -> destination mint) is still settling. Two new kit methods let
   you follow it:
+
   - `kit.getCrossChainDepositStatus({ execId })` - read the deposit's current
     bridge status (source, CCTP, and destination hops) once.
   - `kit.waitForCrossChainDeposit({ execId, pollIntervalMs?, maxWaitMs?, signal? })`
@@ -150,6 +213,7 @@
 - Surface the source-collected bridge fees in cross-chain Earn deposit quotes, and let callers pick the CCTP transfer speed.
 
   New:
+
   - `getDepositQuote` now accepts a cross-chain variant: pass a destination `chain` and `address` that differ from `from.chain` (same `SameChain` / `CrossChain` discriminator pattern as `deposit()`). Same-chain quotes are unchanged.
   - Cross-chain quotes return the source-collected bridge fees in `EarnDepositQuoteInfo.fees` as one entry per fee item. Each entry carries its own `type` (e.g. `'FORWARD'`, `'PRE_FINALITY'`) and `status` (e.g. `'estimated'` for a pre-sign estimate). Same-chain quotes return `fees: []`.
   - Cross-chain `deposit()` and `getDepositQuote()` accept an optional `transferSpeed` (`'FAST'` | `'SLOW'`), forwarded to the bridge prepare request so the quote prices — and the deposit burns — the chosen CCTP finality path.
@@ -159,6 +223,7 @@
   - The cross-chain pre-sign value guard is now fee-aware: the prepared bundle's `feeQuote` (`feeToken` + `items[]`) is parsed, the fee token is pinned to the source token contract, and the signed authorization `value` is checked against `principal + sum(feeQuote.items[].amount)` rather than the principal alone, so fee-bearing deposits are accepted while any other value tampering is still rejected before signing.
 
   Notes:
+
   - The cross-chain fees are pre-sign **estimates** sourced from the bridge prepare path; the value shown at quote time may differ from the amount locked at deposit/sign. This is signalled per fee via `status: 'estimated'`.
   - Existing same-chain `getDepositQuote` callers are unaffected — the response shape is unchanged for same-chain quotes.
 
@@ -167,6 +232,7 @@
   Cross-chain deposits use the same nested `from`/`to` input shape as the other kits: `from: { adapter, chain }` is the source signer and `to: { chain, recipientAddress }` is the Earn destination. `from.chain` and `to.chain` are constrained at compile time to the supported route (Ethereum Sepolia, Arbitrum Sepolia, or Base Sepolia as sources; Arc Testnet as the destination), the source adapter must support `signTypedData`, and amounts accept at most 6 decimal places (USDC precision). Cross-chain results report the bridge `execId`, an API-defined bridge lifecycle `status`, `sourceChain`/`destinationChain`, and the prepared bundle expiry.
 
   Every published name keeps its existing shape; cross-chain support lands under new names:
+
   - `EarnDepositOutcome` is the new union of `EarnSameChainDepositResult | EarnCrossChainDepositResult`. Narrow with `result.kind === 'cross-chain'` — `kind` is always set at runtime, but optional on the same-chain member so the pre-cross-chain result shape remains assignable.
   - `AnyDepositParams` (kit) and `AnyDepositServiceParams` (provider) are the new param unions of the same-chain and cross-chain variants; `anyDepositParamsSchema` is the matching validation schema.
   - `deposit()` gains overloads: same-chain params resolve to `EarnSameChainDepositResult`, cross-chain params to `EarnCrossChainDepositResult`, so existing same-chain call sites keep their narrow result type.
@@ -174,11 +240,13 @@
   - `EarningProvider` gains an **optional** `supportsCrossChainDeposit(source, destination)` method (mirroring swap-kit's route-aware `supportsRoute`). The kit only routes cross-chain deposits to providers that implement it and return `true`; existing provider implementations keep compiling and never receive cross-chain params.
 
   Deprecations (existing aliases keep working):
+
   - `EarnDepositResult` — use `EarnSameChainDepositResult`, or `EarnDepositOutcome` for cross-chain-aware code. This alias may repoint to `EarnDepositOutcome` in the next major.
   - `DepositParams` / `DepositServiceParams` — use `SameChainDepositParams` / `SameChainDepositServiceParams`, or the `Any*` unions for cross-chain-aware code.
   - `depositParamsSchema` — use `anyDepositParamsSchema`, which also accepts cross-chain deposit params.
 
   Type changes (diagnostic types only):
+
   - `EarnErrorTrace`: the deposit variant's `params` is now `AnyDepositServiceParams`, and `steps` may include `EarnBridgeDepositStep` entries for cross-chain deposits.
   - `EarningProvider.retry()` and `EarnKit.retry()` may now resolve to `EarnCrossChainDepositResult` when resuming a cross-chain deposit.
   - `EarnActionName` gains `'crossChainDeposit'`.
@@ -192,6 +260,7 @@
 - EarnKit now validates amount precision and format locally to match the Earn
   Service, so malformed amounts fail fast with a clear SDK error instead of a
   server round-trip.
+
   - Same-chain deposit/withdraw/quote amounts are now capped at 6 decimal places
     (USDC/EURC), matching the server and the existing cross-chain amount schema.
     Previously up to 18 decimal places passed local validation and only the
@@ -329,6 +398,7 @@
 ### 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
@@ -336,6 +406,7 @@
   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`)

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 **45 chains** with **968 total bridge routes** through Circle's CCTPv2
-  - **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
+- **🌍 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
 - **🔄 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)