@circle-fin/app-kit 1.6.1 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,230 @@
 # @circle-fin/app-kit
 
+## 1.8.0
+
+### Minor Changes
+
+- Vault results from `getVaults`, `exploreVaults`, and `exploreVaultsIterator`
+  now include a `circleGuarded` boolean that marks vaults on Circle's curated
+  Circle-guarded list.
+
+  ```typescript
+  const result = await kit.getVaults({
+    vaults: [{ chain: "Ethereum", vaultAddress: "0xbeef..." }],
+  });
+  console.log(result.vaults[0].circleGuarded);
+  ```
+
+  This release requires an Earn Service version that returns the
+  `circleGuarded` field.
+
+- EarnKit can now discover vaults with the new `exploreVaultsIterator` and
+  `exploreVaults` operations.
+
+  `exploreVaultsIterator` lazily iterates every vault available on a chain,
+  fetching pages on demand so there is no page arithmetic to manage:
+
+  ```typescript
+  for await (const vault of kit.exploreVaultsIterator({
+    chain: "Arc_Testnet",
+    sortBy: "apy",
+  })) {
+    console.log(`${vault.name}: ${(vault.currentApy * 100).toFixed(2)}% APY`);
+  }
+  ```
+
+  `exploreVaults` fetches a single page with pagination metadata for paged
+  UIs. Both operations accept optional `protocol`, `asset`, `minApy`, and
+  `minTvl` filters (protocol and asset are matched case-insensitively) and a
+  `sortBy` of `apy`, `tvl`, or `name`.
+
+  Also available through `@circle-fin/app-kit` as `kit.earn.exploreVaults()` /
+  `kit.earn.exploreVaultsIterator()` and the functional `earnExploreVaults` /
+  `earnExploreVaultsIterator` exports.
+
+  No changes are required for custom `EarningProvider` implementations: the
+  new `exploreVaults` method is optional on the interface. Providers that do
+  not implement it cause a clear "no provider supports exploreVaults" error
+  when vault discovery is called; implement the method to opt in.
+
+- Earn quotes now include gas fee estimates.
+
+  `getDepositQuote`, `getWithdrawalQuote`, and `getClaimRewardsQuote` now return a
+  `gasFees` array estimating the native-token gas cost of each transaction in the
+  flow (approval, deposit, withdraw, claim), so you can show users the expected
+  cost before they commit. When an estimate cannot be produced, the entry's `fees`
+  is `null` and `error` carries a short message describing why, while the rest of
+  the quote still resolves.
+
+  Also available through `@circle-fin/app-kit`'s earn quote operations.
+
+- 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.
+  - Swap estimates and results include `chainIn`, `chainOut`, and `progress` so apps can show where a swap started, where it will settle, and its current state.
+  - 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.
+  - Invalid token or chain values return structured validation errors instead of silently returning an empty rate map or surfacing a raw service error.
+  - Each returned rate carries `priceUSD` and `fetchedAt`, plus an optional `decimals` (the token's on-chain precision) when the service reports it.
+
+- Surface a typed, retryable `EarnError.PAUSED` when EarnKit is temporarily
+  paused off-chain (the earn service returns backend code `380414` /
+  `EARNKIT_OFFCHAIN_PAUSED` / HTTP `409`).
+
+  | 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
+    pause and retry later.
+  - `@circle-fin/provider-earn-service`: `parseEarnApiError` now maps `380414`
+    to `EarnError.PAUSED`, so `EarnServiceProvider` deposit/withdraw/claim calls
+    throw a retryable `EARN_PAUSED` instead of falling through to the previous
+    fatal `VALIDATION_FAILED`.
+
+- The publicly re-exported `InputError` registry now includes three new
+  chain pre-flight codes that the `/next` EVM adapters can throw:
+
+  | Code   | Name                          |
+  | ------ | ----------------------------- |
+  | `1010` | `INPUT_CHAIN_MISMATCH`        |
+  | `1011` | `INPUT_CHAIN_SWITCH_REJECTED` |
+  | `1012` | `INPUT_UNRECOGNIZED_CHAIN`    |
+
+  Consumers that branch on `InputError` (or on raw numeric codes) gain
+  these values: `CHAIN_MISMATCH` when the connected wallet is on a
+  different chain than the request targets, `CHAIN_SWITCH_REJECTED` when
+  the user declines a programmatic switch, and `UNRECOGNIZED_CHAIN` when a
+  chain definition cannot be resolved.
+
+- **Behavioral change:** the re-exported `isRetryableError` no longer
+  treats nonce errors (`4003` / `RPC_NONCE_ERROR`) as retryable.
+
+  A nonce error is genuinely ambiguous — the transaction may already have
+  been accepted (the nonce moved on), a concurrent transaction from the
+  same key may have consumed the slot, or a local nonce tracker may have
+  drifted. Generic automatic retry risks a double-spend or a
+  nonce-conflict flip-flop, so `4003` was removed from
+  `DEFAULT_RETRYABLE_ERROR_CODES` and callers must now decide explicitly
+  whether to refresh the nonce and resubmit.
+
+  For `@circle-fin/app-kit` specifically, the documented resume guard
+  `if (isRetryableError(failedStep.error)) await kit.retryBridge(...)` now
+  skips bridges that failed on a nonce error; handle code `4003` yourself
+  if you want to refresh the nonce and retry.
+
+- Add APIs to track a cross-chain Earn deposit after it is submitted.
+
+  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? })`
+    - poll until the deposit settles, fails, or the wait budget elapses (default
+      20 min). On timeout it resolves with the last status instead of throwing, so
+      you can see where the bridge stalled. Pass an `AbortSignal` to cancel a long
+      wait. While polling it emits events you can subscribe to with
+      `kit.on('crossChainDepositStatus', ...)`.
+
+  New exported types: `EarnCrossChainDepositStatus`,
+  `EarnCrossChainDepositWaitResult`, `EarnBridgeHopStatus`,
+  `EarnBridgeCctpStatus`, plus the param types and schemas for both methods. All
+  are re-exported from `@circle-fin/app-kit` with earn-prefixed names.
+
+- 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.
+  - New param types: `SameChainGetDepositQuoteParams` / `CrossChainGetDepositQuoteParams` (the existing `GetDepositQuoteParams` becomes their union). Provider gains `SameChainGetDepositQuoteServiceParams` / `CrossChainGetDepositQuoteServiceParams`.
+  - The provider sends `sourceChain` / `sourceAddress` / `transferSpeed` to `POST /v1/earnKit/deposit/quote` and parses the per-fee `fees[]` response (each with `type` + `status`).
+  - `AssetAmount` gains optional `type` and `status` tags (used on fee entries).
+  - 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.
+
+- Add cross-chain Earn deposits through the bridge prepare, sign, and submit flow.
+
+  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.
+  - Bridge phases emit on a new `crossChainDeposit` event (`method: 'prepare' | 'sign' | 'submit'`, `values: EarnBridgeDepositStep`). The existing `deposit` event is unchanged and never fires bridge phases.
+  - `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'`.
+
+### Patch Changes
+
+- Canonicalize native-stablecoin token spellings across the swap path. On chains whose native gas token is USDC (e.g. Arc), the `NATIVE` symbol, the EIP-7528 sentinel (`0xEeee…`), and the zero address now all resolve to the USDC contract address. As a result, `NATIVE` and `USDC` are treated as the same asset (so `supportsRoute('NATIVE', 'USDC', Arc)` returns `false`), `getTokenDecimals` resolves native-alias addresses to the chain's native decimals without an on-chain call, and the service never receives a native spelling for what is already canonical as USDC. This is derived generically from chain metadata, so any future native-stablecoin chain is covered automatically. Behavior on all other chains is unchanged.
+
+  `@circle-fin/app-kit`'s `send` now canonicalizes EVM native-alias address spellings (EIP-7528 sentinel `0xEeee…`, zero address) to `'NATIVE'` before routing. Without this, those addresses passed validation as custom token addresses and reached `token.transfer` (the ERC-20 rail) while `getTokenDecimals` returned 18-decimal native amounts — a decimals↔rail mismatch that reverts on Arc. After canonicalization both the rail (`native.transfer`) and the decimals (18) are consistent on EVM chains. On non-EVM chains, those EVM placeholder addresses are left to chain-specific token validation and rejected instead of being promoted to native transfers.
+
+- 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
+    server rejected 7+ decimal-place inputs.
+  - Non-canonical numeric forms are now rejected locally on both same-chain and
+    cross-chain amounts: a leading decimal point ('.5') and leading zeros
+    ('00.5', '07'). These passed the generic decimal-string validator but were
+    rejected by the server.
+
+  Well-formed amounts are unaffected.
+
+- Fix forwarded-route support to depend only on the destination chain.
+
+  `supportsRoute(source, destination, 'USDC', true)` previously also required the
+  source chain's `cctp.forwarderSupported.source` to be `true`. Today's Forwarding
+  Service operates on the destination chain, so any CCTP v2 chain can originate a
+  forwarded transfer; the route check now gates only on the destination chain's
+  `cctp.forwarderSupported.destination`, matching the bridge execution path.
+
+  `cctp.forwarderSupported.source` is now `false` for every chain definition,
+  reflecting that source-side forwarding is not yet available. This corrects
+  metadata that previously implied source-side forwarding was supported.
+
+  Also surfaced through `@circle-fin/bridge-kit` and `@circle-fin/app-kit`.
+
+- Fix broken `exports` maps so subpath and CommonJS entry points resolve correctly.
+
+  `@circle-fin/app-kit`: the `./context`, `./bridge`, `./estimateBridge`, `./swap`, `./estimateSwap`, and `./unifiedBalance` subpath exports pointed at `./kit/...` source-style paths that the build never emits — it flattens additional entry points to the package root. `./context`, `./bridge`, and `./estimateBridge` now point at the built `./context.*`, `./bridge.*`, and `./estimateBridge.*` files. `./swap`, `./estimateSwap`, and `./unifiedBalance` — documented in the changelog and JSDoc but never wired into the build — are now emitted as package-root entry points and added to `files`, so all six documented subpaths resolve under Node and bundlers.
+
+  `@circle-fin/provider-stablecoin-service`: `main` and `exports["."].default` referenced `./index.cjs.js`, a file the build never produces; both now point at the real `./index.cjs`.
+
+## 1.7.0
+
+### Minor Changes
+
+- EarnKit (exposed under `kit.earn`) now emits step-level events for multi-phase operations (`deposit`, `withdraw`, `claimRewards`) via `kit.earn.on()` / `kit.earn.off()`, and exposes `kit.earn.retry(error)` to resume an operation that failed after a prior phase (such as a token approval) already succeeded. Failed earn operations now throw a `KitError` carrying step progress and resume context, and `isRetryableError` recognizes `RESUMABLE` errors as retryable.
+
+### Patch Changes
+
+- `kit.bridge` and `kit.unifiedBalance` operations (`deposit`, `depositFor`, `addDelegate`, `removeDelegate`, `initiateRemoveFund`, `removeFund`) no longer reject Gas Station-enabled smart-contract accounts (SCAs) with zero native balance. EOA wallets without native funds will still fail at simulation with the underlying RPC error.
+
 ## 1.6.1
 
 ### Patch Changes

package/README.md

@@ -143,9 +143,9 @@ npm install @circle-fin/adapter-ethers-v6 ethers
 yarn add @circle-fin/adapter-ethers-v6 ethers
 
 # For Solana
-npm install @circle-fin/adapter-solana @solana/web3.js @solana/spl-token
+npm install @circle-fin/adapter-solana @solana/web3.js
 # or
-yarn add @circle-fin/adapter-solana @solana/web3.js @solana/spl-token
+yarn add @circle-fin/adapter-solana @solana/web3.js
 ```
 
 ### Chain Definitions
@@ -345,7 +345,7 @@ For the full Unified Balance API, see the [`@circle-fin/unified-balance-kit` REA
 Deposit into and withdraw from DeFi lending vaults, claim rewards, and query positions:
 
 ```typescript
-import { AppKit, EarnChain } from '@circle-fin/app-kit'
+import { AppKit, Blockchain, EarnChain } from '@circle-fin/app-kit'
 import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 const kit = new AppKit()
@@ -360,13 +360,32 @@ const quote = await kit.earn.getDepositQuote({
   amount: '100.50',
 })
 
-// Execute the deposit
-await kit.earn.deposit({
+// Execute a same-chain deposit
+const depositResult = await kit.earn.deposit({
   from: { adapter, chain: EarnChain.Arc_Testnet },
   vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
   amount: '100.50',
 })
 
+console.log(`Deposit submitted: ${depositResult.txHash}`)
+
+// Execute a cross-chain deposit into an Earn vault
+const bridgeDeposit = await kit.earn.deposit({
+  from: { adapter, chain: Blockchain.Ethereum_Sepolia },
+  to: {
+    chain: EarnChain.Arc_Testnet,
+    recipientAddress: '0x1234567890123456789012345678901234567890',
+  },
+  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
+  amount: '100.50',
+})
+
+console.log(`Bridge deposit submitted: ${bridgeDeposit.execId}`)
+
+// Cross-chain Earn deposits currently support Ethereum Sepolia, Arbitrum
+// Sepolia, and Base Sepolia as sources, with Arc Testnet as the Earn
+// destination.
+
 // Query a vault position
 const position = await kit.earn.getPosition({
   from: { adapter, chain: EarnChain.Arc_Testnet },
@@ -380,6 +399,10 @@ await kit.earn.claimRewards({
 })
 ```
 
+Same-chain Earn deposits keep the existing transaction result. Cross-chain Earn
+deposits return bridge submission details such as `execId`, `status`, and
+`expiresAt`.
+
 For the full Earn API, see the [`@circle-fin/earn-kit` README](../earn-kit/README.md).
 
 ## Configuration