@circle-fin/app-kit 1.7.0 → 1.8.0

package/earn.d.ts

@@ -1006,6 +1006,89 @@ type EarnChainDefinition = ChainDefinition & {
  * - String literals of EarnChain values
  */
 type EarnChainIdentifier = EarnChainDefinition | EarnChain | `${EarnChain}`;
+/**
+ * Blockchains supported as the source chain for cross-chain Earn deposits.
+ *
+ * Single source of truth for the source allowlist: the Earn Service bridge
+ * route map is `satisfies`-checked against {@link EarnBridgeSourceBlockchain},
+ * and both the type and the runtime validation schema derive from this array.
+ *
+ * @example
+ * ```typescript
+ * import { EARN_BRIDGE_SOURCE_BLOCKCHAINS } from '@core/chains'
+ *
+ * console.log(EARN_BRIDGE_SOURCE_BLOCKCHAINS.join(', '))
+ * ```
+ */
+declare const EARN_BRIDGE_SOURCE_BLOCKCHAINS: readonly [Blockchain.Arbitrum_Sepolia, Blockchain.Base_Sepolia, Blockchain.Ethereum_Sepolia];
+/**
+ * Blockchains supported as the source chain for cross-chain Earn deposits.
+ *
+ * Cross-chain Earn deposits bridge USDC from one of these chains into a vault
+ * on an {@link EarnBridgeDestinationBlockchain} chain.
+ */
+type EarnBridgeSourceBlockchain = (typeof EARN_BRIDGE_SOURCE_BLOCKCHAINS)[number];
+/**
+ * Chain definition for a cross-chain Earn deposit source chain.
+ *
+ * Constrained to chains in {@link EarnBridgeSourceBlockchain}.
+ */
+type EarnBridgeSourceChainDefinition = ChainDefinition & {
+    chain: `${EarnBridgeSourceBlockchain}`;
+};
+/**
+ * Chain identifier accepted for the source side of a cross-chain Earn deposit.
+ *
+ * Constrains the source to Ethereum Sepolia, Arbitrum Sepolia, or Base Sepolia.
+ *
+ * @example
+ * ```typescript
+ * import type { EarnBridgeSourceChainIdentifier } from '@core/chains'
+ *
+ * const source: EarnBridgeSourceChainIdentifier = 'Ethereum_Sepolia'
+ * ```
+ */
+type EarnBridgeSourceChainIdentifier = EarnBridgeSourceChainDefinition | EarnBridgeSourceBlockchain | `${EarnBridgeSourceBlockchain}`;
+/**
+ * Blockchains supported as the destination (vault) chain for cross-chain Earn
+ * deposits. Single source of truth for the destination allowlist.
+ *
+ * @example
+ * ```typescript
+ * import { EARN_BRIDGE_DESTINATION_BLOCKCHAINS } from '@core/chains'
+ *
+ * console.log(EARN_BRIDGE_DESTINATION_BLOCKCHAINS.join(', '))
+ * ```
+ */
+declare const EARN_BRIDGE_DESTINATION_BLOCKCHAINS: readonly [Blockchain.Arc_Testnet];
+/**
+ * Blockchains supported as the destination (vault) chain for cross-chain Earn
+ * deposits.
+ *
+ * Intentionally narrower than {@link EarnChain}: cross-chain deposits
+ * currently land only on Arc Testnet.
+ */
+type EarnBridgeDestinationBlockchain = (typeof EARN_BRIDGE_DESTINATION_BLOCKCHAINS)[number];
+/**
+ * Chain definition for a cross-chain Earn deposit destination chain.
+ *
+ * Constrained to chains in {@link EarnBridgeDestinationBlockchain}.
+ */
+type EarnBridgeDestinationChainDefinition = ChainDefinition & {
+    chain: `${EarnBridgeDestinationBlockchain}`;
+};
+/**
+ * Chain identifier accepted for the destination (vault) side of a cross-chain
+ * Earn deposit. Constrains the destination to Arc Testnet.
+ *
+ * @example
+ * ```typescript
+ * import type { EarnBridgeDestinationChainIdentifier } from '@core/chains'
+ *
+ * const destination: EarnBridgeDestinationChainIdentifier = 'Arc_Testnet'
+ * ```
+ */
+type EarnBridgeDestinationChainIdentifier = EarnBridgeDestinationChainDefinition | EarnBridgeDestinationBlockchain | `${EarnBridgeDestinationBlockchain}`;
 
 /**
  * @packageDocumentation
@@ -3606,8 +3689,14 @@ interface AdapterCapabilities {
     /**
      * The set of blockchain networks this adapter supports.
      * Used for validation, capability discovery, and to restrict operations to supported chains.
+     *
+     * @remarks
+     * Typed `readonly` to match the `@core/adapter-base` `AdapterCapabilities`
+     * shape, so the /next adapters (which preserve `readonly` capabilities per
+     * PR #853 A1) remain structurally assignable to this legacy `Adapter`
+     * contract. The collection is only ever read, never mutated.
      */
-    supportedChains: ChainDefinition[];
+    supportedChains: readonly ChainDefinition[];
 }
 /**
  * Abstract class defining the standard interface for an adapter that interacts with a specific blockchain.
@@ -5006,6 +5095,18 @@ interface InvocationMeta {
      * Example: [app, kit, provider]
      */
     readonly callers?: readonly Caller[] | undefined;
+    /**
+     * Cooperative cancellation signal for the invocation.
+     *
+     * @remarks
+     * When provided, the signal is threaded onto the resolved
+     * {@link InvocationContext} so operations can forward it to
+     * cancellable work (e.g. `fetch`, timers, adapter calls). Optional and
+     * backwards-compatible: callers that do not support cancellation simply
+     * omit it. Aborting the signal is the caller's responsibility; the
+     * runtime only propagates it.
+     */
+    readonly signal?: AbortSignal | undefined;
 }
 
 /**
@@ -5984,7 +6085,7 @@ declare class Amount implements AmountFields {
  * ```typescript
  * const query: VaultQuery = {
  *   chain: 'Arc_Testnet',
- *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *   vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  * }
  * ```
  */
@@ -6060,7 +6161,7 @@ interface VaultWarning {
  * @example
  * ```typescript
  * const vault: VaultInfo = {
- *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *   vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  *   chain: 'Arc_Testnet',
  *   name: 'Steakhouse USDC',
  *   protocol: 'MORPHO',
@@ -6074,6 +6175,7 @@ interface VaultWarning {
  *   totalDeposits: Amount.fromJSON({ raw: '15000000000000', decimals: 6 }),
  *   liquidity: Amount.fromJSON({ raw: '5000000000000', decimals: 6 }),
  *   status: 'active',
+ *   circleGuarded: false,
  * }
  * ```
  */
@@ -6106,6 +6208,8 @@ interface VaultInfo {
     readonly liquidity: Amount;
     /** Current vault status. */
     readonly status: 'active' | 'low_liquidity';
+    /** Whether the vault is on Circle's curated Circle-guarded list. */
+    readonly circleGuarded: boolean;
     /** Morpho protocol warnings for this vault. */
     readonly warnings?: readonly VaultWarning[] | undefined;
     /** Circle-specific warnings (e.g., unsupported reward protocol). */
@@ -6273,6 +6377,21 @@ interface AssetAmount {
      * the asset for the calling context.
      */
     readonly address?: string | undefined;
+    /**
+     * Optional category tag for the amount.
+     *
+     * Present on fee entries to identify the kind of fee — for cross-chain
+     * deposit quotes this is the source-fee item type (e.g. `'FORWARD'`,
+     * `'PRE_FINALITY'`). Omitted when the amount has no meaningful category
+     * (plain deposit/withdrawal/share/reward amounts).
+     */
+    readonly type?: string | undefined;
+    /**
+     * Optional status qualifier for a fee entry — e.g. `'estimated'` for a
+     * pre-sign cross-chain fee that may change at execution time. Omitted when
+     * not applicable.
+     */
+    readonly status?: string | undefined;
 }
 /**
  * Result of a deposit operation returned by
@@ -6283,11 +6402,25 @@ interface AssetAmount {
  *
  * @example
  * ```typescript
- * const result: EarnDepositResult = await provider.deposit(params)
+ * const result: EarnSameChainDepositResult = {
+ *   kind: 'same-chain',
+ *   txHash: '0x...',
+ *   explorerUrl: 'https://...',
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * }
  * console.log(`Deposited ${result.amount} into ${result.vaultAddress}, tx: ${result.txHash}`)
  * ```
  */
-interface EarnDepositResult {
+interface EarnSameChainDepositResult {
+    /**
+     * Discriminator for narrowing {@link EarnDepositOutcome}.
+     *
+     * Always set at runtime. Optional only so the pre-cross-chain
+     * {@link EarnDepositResult} shape — and provider implementations or mocks
+     * written against it — remain assignable.
+     */
+    readonly kind?: 'same-chain';
     /** Confirmed on-chain transaction hash. */
     readonly txHash: string;
     /** Explorer URL for the confirmed on-chain transaction. */
@@ -6297,6 +6430,206 @@ interface EarnDepositResult {
     /** Deposit amount in human-readable decimal format. */
     readonly amount: string;
 }
+/**
+ * Result of a cross-chain deposit submitted through the bridge flow.
+ *
+ * @remarks
+ * A `cross-chain` result means the bridge accepted the submission — a weaker
+ * guarantee than the same-chain result's confirmed on-chain `txHash`.
+ * `deposit()` does not poll bridge settlement or vault-position completion.
+ *
+ * @example
+ * ```typescript
+ * const result: EarnCrossChainDepositResult = {
+ *   kind: 'cross-chain',
+ *   execId: '550e8400-e29b-41d4-a716-446655440000',
+ *   status: 'PENDING',
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ *   sourceChain: Blockchain.Ethereum_Sepolia,
+ *   destinationChain: Blockchain.Arc_Testnet,
+ *   expiresAt: '2026-05-19T00:00:00Z',
+ * }
+ * console.log(`Submitted bridge deposit ${result.execId}`)
+ * ```
+ */
+interface EarnCrossChainDepositResult {
+    /** Discriminator for narrowing {@link EarnDepositOutcome}. */
+    readonly kind: 'cross-chain';
+    /** Idempotency execution ID for the cross-chain deposit. */
+    readonly execId: string;
+    /**
+     * API-defined bridge lifecycle status returned by bridge submit.
+     *
+     * The value space is owned by the bridge API and unions two vocabularies:
+     * a first-time submit reports the relay state (for example `'PENDING'`,
+     * `'SENT'`, `'COMPLETE'`, `'FAILED'`), while a replayed submit for an
+     * already-relayed execution reports the bridge lifecycle (for example
+     * `'SOURCE_PENDING'`, `'ATTESTING'`, `'DESTINATION_PENDING'`,
+     * `'COMPLETE'`, `'FAILED'`, `'CANCELLED'`). Neither set is exhaustive;
+     * treat unrecognized values as in-progress rather than branching
+     * exhaustively.
+     *
+     * `deposit()` returns the submit response only. It does not currently poll
+     * bridge settlement or vault-position completion.
+     */
+    readonly status: string;
+    /** Vault contract address deposited into. */
+    readonly vaultAddress: string;
+    /** Deposit amount in human-readable decimal format. */
+    readonly amount: string;
+    /** Source chain where the ERC-3009 authorization is signed. */
+    readonly sourceChain: Blockchain;
+    /** Destination chain where the vault lives. */
+    readonly destinationChain: Blockchain;
+    /**
+     * ISO-8601 UTC timestamp after which the prepared bundle expires.
+     *
+     * `retry()` resumes the same bridge execution and replays the original
+     * prepared bundle before this timestamp. After this timestamp the expiry
+     * error is FATAL (not retryable); call `deposit()` again, which starts a
+     * fresh bridge execution.
+     *
+     * @example '2026-05-19T00:00:00Z'
+     */
+    readonly expiresAt: string;
+}
+/**
+ * Status of one hop (source relay or destination mint) of a cross-chain
+ * bridge deposit.
+ *
+ * The `status` field is an API-defined lifecycle string (e.g. `'COMPLETE'`,
+ * `'NOT_STARTED'`). Additive backend fields (chain, domain, relay/tx ids) are
+ * preserved verbatim.
+ *
+ * @example
+ * ```typescript
+ * const source: EarnBridgeHopStatus = {
+ *   status: 'COMPLETE',
+ *   chain: 'ETH-SEPOLIA',
+ *   domainId: 0,
+ *   relayId: '84b46b27-0144-5e0e-917b-15f2ba85a49b',
+ *   txHash: '0x489b...',
+ * }
+ * ```
+ */
+interface EarnBridgeHopStatus {
+    /** API-defined lifecycle status for this hop. */
+    readonly status: string;
+    /** API chain identifier for this hop, when returned. */
+    readonly chain?: string | undefined;
+    /** API CCTP domain identifier for this hop, when returned. */
+    readonly domainId?: number | undefined;
+    /** Source CCTP domain identifier, when returned. */
+    readonly sourceDomainId?: number | undefined;
+    /** Destination CCTP domain identifier, when returned. */
+    readonly destinationDomainId?: number | undefined;
+    /** Backend relay identifier for this hop, when returned. */
+    readonly relayId?: string | undefined;
+    /** On-chain transaction hash for this hop, when returned. */
+    readonly txHash?: string | undefined;
+    /** Additive backend fields preserved verbatim (chain, domainId, ids, ...). */
+    readonly [key: string]: unknown;
+}
+/**
+ * CCTP attestation status for a cross-chain bridge deposit.
+ *
+ * @example
+ * ```typescript
+ * const cctp: EarnBridgeCctpStatus = {
+ *   status: 'UNKNOWN',
+ *   sourceDomainId: 0,
+ *   destinationDomainId: 26,
+ *   attestationAvailable: false,
+ * }
+ * ```
+ */
+interface EarnBridgeCctpStatus {
+    /** API-defined CCTP lifecycle status. */
+    readonly status: string;
+    /** API CCTP domain identifier, when returned. */
+    readonly domainId?: number | undefined;
+    /** Source CCTP domain identifier, when returned. */
+    readonly sourceDomainId?: number | undefined;
+    /** Destination CCTP domain identifier, when returned. */
+    readonly destinationDomainId?: number | undefined;
+    /** Whether an attestation is available to complete destination minting. */
+    readonly attestationAvailable?: boolean | undefined;
+    /** Additive backend fields preserved verbatim. */
+    readonly [key: string]: unknown;
+}
+/**
+ * Structured status of a cross-chain Earn deposit, keyed by execId.
+ *
+ * The top-level `status` is the overall API-defined bridge lifecycle string
+ * (e.g. `'PENDING'`, `'ATTESTING'`, `'COMPLETE'`). The nested `source`, `cctp`,
+ * and `destination` objects expose per-hop progress when the API returns them.
+ *
+ * @example
+ * ```typescript
+ * const status: EarnCrossChainDepositStatus = {
+ *   execId: 'e9e77922-c8a4-4158-93de-d73a78417d99',
+ *   status: 'ATTESTING',
+ *   source: { status: 'COMPLETE', chain: 'ETH-SEPOLIA', txHash: '0x489b...' },
+ *   cctp: { status: 'UNKNOWN', attestationAvailable: false },
+ *   destination: { status: 'NOT_STARTED', domainId: 26 },
+ * }
+ * console.log(`Bridge ${status.execId} is ${status.status}`)
+ * ```
+ */
+interface EarnCrossChainDepositStatus {
+    /** Idempotency execution ID for the cross-chain deposit. */
+    readonly execId: string;
+    /** Overall API-defined bridge lifecycle status. */
+    readonly status: string;
+    /** Source-chain relay (burn) hop status, when available. */
+    readonly source?: EarnBridgeHopStatus | undefined;
+    /** CCTP attestation status, when available. */
+    readonly cctp?: EarnBridgeCctpStatus | undefined;
+    /** Destination-chain mint hop status, when available. */
+    readonly destination?: EarnBridgeHopStatus | undefined;
+}
+/**
+ * Normalized outcome used by cross-chain deposit waiters.
+ *
+ * `timeout` is a waiter outcome only; it is not derived from an API status.
+ */
+type EarnCrossChainDepositWaitOutcome = 'complete' | 'failed' | 'cancelled' | 'timeout';
+/**
+ * Result returned by waiters for cross-chain Earn deposits.
+ *
+ * The raw bridge status is preserved in `status`. `outcome` summarizes why the
+ * wait stopped, while `terminal` and `timedOut` let callers branch without
+ * re-deriving bridge lifecycle semantics.
+ */
+interface EarnCrossChainDepositWaitResult {
+    /** Last observed structured cross-chain deposit status. */
+    readonly status: EarnCrossChainDepositStatus;
+    /** Normalized outcome that caused the waiter to stop. */
+    readonly outcome: EarnCrossChainDepositWaitOutcome;
+    /** Whether the observed bridge status is terminal. */
+    readonly terminal: boolean;
+    /** Whether the wait budget elapsed before a terminal status was observed. */
+    readonly timedOut: boolean;
+}
+/**
+ * Result of a deposit operation returned by
+ * {@link EarningProvider.deposit}.
+ *
+ * `kind` is always set at runtime, but it is optional on the same-chain
+ * member, so narrow against the required cross-chain discriminator.
+ *
+ * @example
+ * ```typescript
+ * const result: EarnDepositOutcome = await provider.deposit(params)
+ * if (result.kind === 'cross-chain') {
+ *   console.log(`Submitted bridge deposit ${result.execId}`)
+ * } else {
+ *   console.log(`Deposited ${result.amount} into ${result.vaultAddress}, tx: ${result.txHash}`)
+ * }
+ * ```
+ */
+type EarnDepositOutcome = EarnSameChainDepositResult | EarnCrossChainDepositResult;
 /**
  * Result of a withdrawal operation returned by
  * {@link EarningProvider.withdraw}.
@@ -6340,6 +6673,54 @@ interface NoClaimableRewardsResult {
     /** Empty because there were no rewards to claim. */
     readonly rewards: readonly [];
 }
+/**
+ * Fields shared by both {@link EarnGasFeeEstimate} variants.
+ *
+ * @example
+ * ```typescript
+ * const base: EarnGasFeeEstimateBase = {
+ *   name: 'Deposit',
+ *   token: 'ETH',
+ *   blockchain: 'Arc_Testnet',
+ * }
+ * ```
+ */
+interface EarnGasFeeEstimateBase {
+    /** The earn step being estimated, e.g. "Approve", "Deposit", "Withdraw". */
+    readonly name: string;
+    /** Native token used to pay gas fees, e.g. "ETH". */
+    readonly token: string;
+    /** Blockchain where this gas fee applies. */
+    readonly blockchain: ChainDefinition['chain'];
+}
+/**
+ * Estimated native gas fee for one transaction in an Earn quote.
+ *
+ * A discriminated union on `fees`: a successful estimate carries
+ * {@link EstimatedGas} details and no `error`; a failed estimate carries
+ * `fees: null` and a sanitized `error` message. Narrow on `fees`:
+ *
+ * @example
+ * ```typescript
+ * function describe(entry: EarnGasFeeEstimate): string {
+ *   if (entry.fees === null) {
+ *     return `${entry.name}: estimation failed (${entry.error})`
+ *   }
+ *   return `${entry.name}: ${entry.fees.fee} wei`
+ * }
+ * ```
+ */
+type EarnGasFeeEstimate$1 = (EarnGasFeeEstimateBase & {
+    /** Estimated gas details. */
+    readonly fees: EstimatedGas;
+    /** Never present on a successful estimate. */
+    readonly error?: never;
+}) | (EarnGasFeeEstimateBase & {
+    /** Null because estimation failed. */
+    readonly fees: null;
+    /** Sanitized estimation error message. */
+    readonly error: string;
+});
 /**
  * Result from a deposit quote operation.
  *
@@ -6362,8 +6743,39 @@ interface DepositQuoteInfo {
     readonly sharePrice: string;
     /** Current annualized percentage yield. */
     readonly currentApy: number;
-    /** Fees applied to the deposit. Empty when no deposit fee is charged. */
+    /**
+     * Deposit fees charged in the deposit asset. For cross-chain quotes this
+     * carries one entry per source-fee item (e.g. `'FORWARD'`, `'PRE_FINALITY'`),
+     * each tagged with its own {@link AssetAmount.type} and
+     * {@link AssetAmount.status} (e.g. `'estimated'`). Empty when no such fee
+     * applies. Distinct from native gas estimates, which are reported separately
+     * as gas-fee fields.
+     */
     readonly fees: readonly AssetAmount[];
+    /**
+     * Estimated native gas fees for the transactions needed to deposit
+     * (e.g. token approval and the deposit itself).
+     *
+     * Optional so that custom {@link EarningProvider} implementations are not
+     * required to produce gas estimates. The bundled Earn Service provider
+     * always populates this with one entry per transaction in the flow. When an
+     * individual estimate cannot be produced, that entry is still present with
+     * `fees` set to `null` and `error` describing why — so a non-empty array
+     * does not imply every estimate succeeded; inspect each entry's `fees`.
+     *
+     * The number of entries depends on where estimation stopped: when the flow
+     * fails before the approval step is examined, a single entry named after
+     * the main action is returned. Look entries up by `name`, not by index.
+     *
+     * Each estimate simulates the transaction against current chain state.
+     * When a token approval is still pending (typically a first-time deposit),
+     * the deposit simulation reverts because the allowance is not yet in
+     * place, so the deposit entry resolves with `fees: null` while the
+     * approval entry still carries a real estimate. Render a fallback (e.g.
+     * "available after approval") for that case rather than treating it as an
+     * error.
+     */
+    readonly gasFees?: readonly EarnGasFeeEstimate$1[] | undefined;
 }
 /**
  * Result from a withdrawal quote operation.
@@ -6396,6 +6808,29 @@ interface WithdrawalQuoteInfo {
     readonly maxWithdrawable: AssetAmount;
     /** Fees applied to the withdrawal. */
     readonly fees: readonly AssetAmount[];
+    /**
+     * Estimated native gas fees for the transactions needed to withdraw.
+     *
+     * Optional so that custom {@link EarningProvider} implementations are not
+     * required to produce gas estimates. The bundled Earn Service provider
+     * always populates this with one entry per transaction in the flow. When an
+     * individual estimate cannot be produced, that entry is still present with
+     * `fees` set to `null` and `error` describing why — so a non-empty array
+     * does not imply every estimate succeeded; inspect each entry's `fees`.
+     *
+     * The number of entries depends on where estimation stopped: when the flow
+     * fails before the approval step is examined, a single entry named after
+     * the main action is returned. Look entries up by `name`, not by index.
+     *
+     * Each estimate simulates the transaction against current chain state.
+     * When a vault-share approval is still pending (typically the first
+     * withdrawal from a vault), the withdrawal simulation reverts because the
+     * allowance is not yet in place, so the withdrawal entry resolves with
+     * `fees: null` while the approval entry still carries a real estimate.
+     * Render a fallback (e.g. "available after approval") for that case
+     * rather than treating it as an error.
+     */
+    readonly gasFees?: readonly EarnGasFeeEstimate$1[] | undefined;
     /**
      * Informational, plain-string warnings about the quoted withdrawal.
      *
@@ -6425,6 +6860,19 @@ interface WithdrawalQuoteInfo {
 interface ClaimRewardsQuoteInfo {
     /** Reward tokens available for claiming. */
     readonly rewards: readonly AssetAmount[];
+    /**
+     * Estimated native gas fees for claiming rewards. Empty when there are no
+     * rewards to claim.
+     *
+     * Optional so that custom {@link EarningProvider} implementations are not
+     * required to produce gas estimates. Otherwise the bundled Earn Service
+     * provider populates this with one entry per claim transaction; when an
+     * estimate cannot be produced, that entry is still present with `fees` set
+     * to `null` and `error` describing why — so a non-empty array does not imply
+     * every estimate succeeded; inspect each entry's `fees`. Look entries up by
+     * `name`, not by index.
+     */
+    readonly gasFees?: readonly EarnGasFeeEstimate$1[] | undefined;
 }
 /**
  * Result from a batch vault lookup.
@@ -6438,13 +6886,112 @@ interface GetVaultsResult {
     /** Per-vault errors for failed lookups. */
     readonly errors: readonly VaultError[];
 }
+/**
+ * Sort order for a vault discovery query.
+ *
+ * - `apy` — highest current APY first
+ * - `tvl` — highest total deposits first
+ * - `name` — alphabetical by vault name
+ *
+ * @example
+ * ```typescript
+ * const sortBy: ExploreVaultsSortBy = 'apy'
+ * ```
+ */
+type ExploreVaultsSortBy = 'apy' | 'tvl' | 'name';
+/**
+ * Pagination metadata for a vault discovery result.
+ *
+ * @example
+ * ```typescript
+ * const pagination: ExploreVaultsPagination = {
+ *   page: 1,
+ *   pageSize: 100,
+ *   totalCount: 42,
+ *   totalPages: 1,
+ * }
+ * ```
+ */
+interface ExploreVaultsPagination {
+    /** Current page number (1-based). */
+    readonly page: number;
+    /** Number of results per page. */
+    readonly pageSize: number;
+    /** Total number of vaults matching the query. */
+    readonly totalCount: number;
+    /** Total number of pages for the query. */
+    readonly totalPages: number;
+}
+/**
+ * Result from a vault discovery query.
+ *
+ * @example
+ * ```typescript
+ * const result: ExploreVaultsResult = await provider.exploreVaults({
+ *   chain: 'Arc_Testnet',
+ * })
+ * console.log(`${result.pagination.totalCount} vaults available`)
+ * ```
+ */
+interface ExploreVaultsResult {
+    /** Vaults matching the query, in the requested sort order. */
+    readonly vaults: readonly VaultInfo[];
+    /** Pagination metadata for the query. */
+    readonly pagination: ExploreVaultsPagination;
+}
 
+/**
+ * Estimated gas details for one transaction in a kit-level Earn quote, with
+ * every amount as a decimal string so quote results stay JSON-serializable.
+ *
+ * @example
+ * ```typescript
+ * const gas: EarnEstimatedGas = { gas: '73567', gasPrice: '20003763738', fee: '1471616886913446' }
+ * ```
+ */
+interface EarnEstimatedGas {
+    /** Estimated gas units as a decimal string, e.g. '73567'. */
+    readonly gas: string;
+    /** Estimated price per gas unit as a decimal string in wei. */
+    readonly gasPrice: string;
+    /** Total estimated fee as a decimal string in wei. */
+    readonly fee: string;
+}
+/**
+ * Estimated native gas fee for one transaction in an Earn quote.
+ *
+ * A discriminated union on `fees`: a successful estimate carries
+ * {@link EarnEstimatedGas} details and no `error`; a failed estimate carries
+ * `fees: null` and a sanitized `error` message.
+ *
+ * @example
+ * ```typescript
+ * function describe(entry: EarnGasFeeEstimate): string {
+ *   if (entry.fees === null) {
+ *     return `${entry.name}: estimation failed (${entry.error})`
+ *   }
+ *   return `${entry.name}: ${entry.fees.fee} wei`
+ * }
+ * ```
+ */
+type EarnGasFeeEstimate = (EarnGasFeeEstimateBase & {
+    /** Estimated gas details with amounts formatted as decimal strings. */
+    readonly fees: EarnEstimatedGas;
+    /** Never present on a successful estimate. */
+    readonly error?: never;
+}) | (EarnGasFeeEstimateBase & {
+    /** Null because estimation failed. */
+    readonly fees: null;
+    /** Sanitized estimation error message. */
+    readonly error: string;
+});
 /**
  * Adapter context for earn operations, constrained to earn-supported chains.
  *
  * @typeParam TAdapterCapabilities - The adapter capabilities type
+ * @typeParam TChainIdentifier - The chain identifier type accepted by the adapter context
  */
-type EarnAdapterContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> = AdapterContext<TAdapterCapabilities, EarnChainIdentifier>;
+type EarnAdapterContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier$1 = EarnChainIdentifier> = AdapterContext<TAdapterCapabilities, TChainIdentifier>;
 /**
  * Configuration options for earn operations.
  *
@@ -6498,6 +7045,57 @@ interface GetVaultsParams {
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }
+/**
+ * Parameters for discovering vaults available on a chain.
+ *
+ * Only `chain` is required. Filters narrow the result set, and results
+ * are paginated and sorted server-side.
+ *
+ * @example
+ * ```typescript
+ * const params: ExploreVaultsParams = {
+ *   chain: 'Arc_Testnet',
+ *   minApy: '0.03',
+ *   sortBy: 'apy',
+ * }
+ * ```
+ */
+interface ExploreVaultsParams {
+    /** Chain to discover vaults on (e.g., 'Arc_Testnet'). */
+    readonly chain: EarnChainIdentifier;
+    /** Optional protocol filter (e.g., 'morpho'). Matched case-insensitively. */
+    readonly protocol?: string | undefined;
+    /** Optional asset symbol filter, matched case-insensitively. Defaults to 'USDC'. */
+    readonly asset?: string | undefined;
+    /** Optional minimum net APY as a decimal string (e.g., '0.03' for 3%). */
+    readonly minApy?: string | undefined;
+    /** Optional minimum total deposits in token units (e.g., '1000000'). */
+    readonly minTvl?: string | undefined;
+    /** Optional sort order: 'apy', 'tvl', or 'name'. Defaults to 'tvl'. */
+    readonly sortBy?: ExploreVaultsSortBy | undefined;
+    /** Optional page number (1-based). Defaults to 1. */
+    readonly page?: number | undefined;
+    /** Optional results per page (100-500). Defaults to 100. */
+    readonly pageSize?: number | undefined;
+    /** Optional earn configuration. */
+    readonly config?: EarnConfig | undefined;
+}
+/**
+ * Parameters for lazily iterating all vaults available on a chain.
+ *
+ * Identical to {@link ExploreVaultsParams} minus `page`: the iterator
+ * fetches page after page on demand. `pageSize` still controls how many
+ * vaults each underlying request fetches.
+ *
+ * @example
+ * ```typescript
+ * const params: ExploreVaultsIteratorParams = {
+ *   chain: 'Arc_Testnet',
+ *   sortBy: 'apy',
+ * }
+ * ```
+ */
+type ExploreVaultsIteratorParams = Omit<ExploreVaultsParams, 'page'>;
 /**
  * Parameters for fetching a wallet's position in a vault.
  *
@@ -6507,7 +7105,7 @@ interface GetVaultsParams {
  * ```typescript
  * const params: GetPositionParams = {
  *   from: { adapter, chain: 'Arc_Testnet' },
- *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *   vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  * }
  * ```
  */
@@ -6519,6 +7117,60 @@ interface GetPositionParams<TFromAdapterCapabilities extends AdapterCapabilities
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }
+/**
+ * Parameters for retrieving the status of a cross-chain Earn deposit.
+ *
+ * The status lookup is chain-agnostic; it is keyed only by the bridge
+ * execution ID returned from a cross-chain {@link CrossChainDepositParams}
+ * deposit.
+ *
+ * @example
+ * ```typescript
+ * const params: GetCrossChainDepositStatusParams = {
+ *   execId: 'e9e77922-c8a4-4158-93de-d73a78417d99',
+ * }
+ * ```
+ */
+interface GetCrossChainDepositStatusParams {
+    /** Idempotency execution ID returned by the cross-chain deposit. */
+    readonly execId: string;
+    /** Optional earn configuration. */
+    readonly config?: EarnConfig | undefined;
+}
+/**
+ * Parameters for waiting on a cross-chain Earn deposit to reach a terminal
+ * bridge state.
+ *
+ * Polls the bridge status until the deposit settles (or fails) or the wait
+ * budget elapses. On timeout the waiter resolves with the last observed
+ * status and a `timeout` outcome rather than throwing, so callers can inspect
+ * where the bridge stalled.
+ *
+ * @example
+ * ```typescript
+ * const params: WaitForCrossChainDepositParams = {
+ *   execId: 'e9e77922-c8a4-4158-93de-d73a78417d99',
+ *   pollIntervalMs: 5_000,
+ *   maxWaitMs: 1_200_000,
+ * }
+ * ```
+ */
+interface WaitForCrossChainDepositParams {
+    /** Idempotency execution ID returned by the cross-chain deposit. */
+    readonly execId: string;
+    /** Optional earn configuration. */
+    readonly config?: EarnConfig | undefined;
+    /** Delay between status polls in milliseconds. Defaults to 5000. */
+    readonly pollIntervalMs?: number | undefined;
+    /** Maximum total wait time in milliseconds. Defaults to 1200000 (20 min). */
+    readonly maxWaitMs?: number | undefined;
+    /**
+     * Optional cancellation signal. When it aborts, the wait rejects with a
+     * `NETWORK_ABORTED` error instead of resolving. Cancellation is observed
+     * between polls, not mid-request.
+     */
+    readonly signal?: AbortSignal | undefined;
+}
 /**
  * Parameters for depositing into a DeFi lending vault.
  *
@@ -6526,14 +7178,14 @@ interface GetPositionParams<TFromAdapterCapabilities extends AdapterCapabilities
  *
  * @example
  * ```typescript
- * const params: DepositParams = {
+ * const params: SameChainDepositParams = {
  *   from: { adapter, chain: 'Arc_Testnet' },
  *   vaultAddress: '0x...',
  *   amount: '100.50',
  * }
  * ```
  */
-interface DepositParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
+interface SameChainDepositParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
     /** Source adapter context (wallet and chain) for the deposit. */
     readonly from: EarnAdapterContext<TFromAdapterCapabilities>;
     /** On-chain vault contract address to deposit into. */
@@ -6547,6 +7199,114 @@ interface DepositParams<TFromAdapterCapabilities extends AdapterCapabilities = A
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }
+/**
+ * Destination of a cross-chain Earn deposit.
+ *
+ * The destination is adapter-less: the source wallet signs a single ERC-3009
+ * authorization on the source chain, and a relayer executes the bridge and
+ * vault deposit on the destination chain. No destination-side signing occurs,
+ * so only the destination chain and the wallet receiving the vault position
+ * are required.
+ *
+ * @example
+ * ```typescript
+ * const destination: EarnCrossChainDepositDestination = {
+ *   chain: 'Arc_Testnet',
+ *   recipientAddress: '0x1234567890123456789012345678901234567890',
+ * }
+ * ```
+ */
+interface EarnCrossChainDepositDestination {
+    /** Destination Earn chain where the vault is deployed. */
+    readonly chain: EarnBridgeDestinationChainIdentifier;
+    /** Destination wallet that receives the vault position. */
+    readonly recipientAddress: string;
+}
+/**
+ * Parameters for depositing into a DeFi lending vault from another chain.
+ *
+ * @remarks
+ * Cross-chain Earn deposits currently support Ethereum Sepolia, Arbitrum
+ * Sepolia, and Base Sepolia as source chains, with Arc Testnet as the Earn
+ * destination chain.
+ *
+ * Cross-chain deposits require `from.adapter` to support EIP-712 typed-data
+ * signing through `signTypedData`. Providers validate this capability at
+ * runtime before preparing a bridge deposit.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type
+ *
+ * @example
+ * ```typescript
+ * const params: CrossChainDepositParams = {
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   to: {
+ *     chain: 'Arc_Testnet',
+ *     recipientAddress: '0x1234567890123456789012345678901234567890',
+ *   },
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ *   maxFee: '0.028041',
+ * }
+ * ```
+ */
+interface CrossChainDepositParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
+    /** Source adapter context (wallet and source chain) for the deposit. */
+    readonly from: EarnAdapterContext<TFromAdapterCapabilities, EarnBridgeSourceChainIdentifier>;
+    /** Destination chain and recipient of the vault position. */
+    readonly to: EarnCrossChainDepositDestination;
+    /** On-chain vault contract address to deposit into. */
+    readonly vaultAddress: string;
+    /**
+     * Amount to deposit in human-readable decimal format.
+     *
+     * @example '100.50' for 100.50 USDC
+     */
+    readonly amount: string;
+    /**
+     * Maximum source-collected bridge fee the caller is willing to sign for, in
+     * human-readable source token units.
+     *
+     * Derive this from a recent cross-chain deposit quote by summing
+     * `quote.fees[].amount`. The prepared bridge bundle must not exceed this cap
+     * before the source wallet signs its ERC-3009 authorization.
+     *
+     * @example '0.028041' for 0.028041 USDC
+     */
+    readonly maxFee: string;
+    /**
+     * CCTP transfer speed for the source burn.
+     *
+     * `FAST` uses a low finality threshold for quicker settlement;
+     * `SLOW` waits for full finality. Affects the source-collected fee.
+     */
+    readonly transferSpeed?: TransferSpeed | `${TransferSpeed}` | undefined;
+    /** Optional earn configuration. */
+    readonly config?: EarnConfig | undefined;
+}
+/**
+ * Parameters for depositing into a DeFi lending vault.
+ *
+ * @example
+ * ```typescript
+ * const sameChainParams: AnyDepositParams = {
+ *   from: { adapter, chain: 'Arc_Testnet' },
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * }
+ *
+ * const crossChainParams: AnyDepositParams = {
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   to: {
+ *     chain: 'Arc_Testnet',
+ *     recipientAddress: '0x1234567890123456789012345678901234567890',
+ *   },
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * }
+ * ```
+ */
+type AnyDepositParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> = SameChainDepositParams<TFromAdapterCapabilities> | CrossChainDepositParams<TFromAdapterCapabilities>;
 /**
  * Parameters for withdrawing from a DeFi lending vault.
  *
@@ -6584,7 +7344,7 @@ interface WithdrawParams<TFromAdapterCapabilities extends AdapterCapabilities =
  * ```typescript
  * const params: ClaimRewardsParams = {
  *   from: { adapter, chain: 'Arc_Testnet' },
- *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *   vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  * }
  * ```
  */
@@ -6597,20 +7357,20 @@ interface ClaimRewardsParams<TFromAdapterCapabilities extends AdapterCapabilitie
     readonly config?: EarnConfig | undefined;
 }
 /**
- * Parameters for getting a deposit quote.
+ * Parameters for getting a same-chain deposit quote.
  *
  * @typeParam TFromAdapterCapabilities - The adapter capabilities type
  *
  * @example
  * ```typescript
- * const params: GetDepositQuoteParams = {
+ * const params: SameChainGetDepositQuoteParams = {
  *   from: { adapter, chain: 'Arc_Testnet' },
  *   vaultAddress: '0x...',
  *   amount: '100.50',
  * }
  * ```
  */
-interface GetDepositQuoteParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
+interface SameChainGetDepositQuoteParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
     /** Source adapter context (wallet and chain). */
     readonly from: EarnAdapterContext<TFromAdapterCapabilities>;
     /** On-chain vault contract address. */
@@ -6620,6 +7380,74 @@ interface GetDepositQuoteParams<TFromAdapterCapabilities extends AdapterCapabili
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }
+/**
+ * Parameters for getting a cross-chain deposit quote.
+ *
+ * @remarks
+ * Mirrors {@link CrossChainDepositParams}: previews a deposit whose funds
+ * bridge from `from.chain` into a vault on the destination `chain`. The quote
+ * is read-only (no `idempotencyKey`) and surfaces the bridge forwarder fee in
+ * {@link EarnDepositQuoteInfo.fees}.
+ *
+ * @typeParam TFromAdapterCapabilities - The adapter capabilities type
+ *
+ * @example
+ * ```typescript
+ * const params: CrossChainGetDepositQuoteParams = {
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   chain: 'Arc_Testnet',
+ *   address: '0x1234567890123456789012345678901234567890',
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * }
+ * ```
+ */
+interface CrossChainGetDepositQuoteParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
+    /** Source adapter context (wallet and source chain). */
+    readonly from: EarnAdapterContext<TFromAdapterCapabilities, EarnBridgeSourceChainIdentifier>;
+    /** Destination Earn chain where the vault is deployed. */
+    readonly chain: EarnBridgeDestinationChainIdentifier;
+    /** Destination wallet that receives the vault position. */
+    readonly address: string;
+    /** On-chain vault contract address. */
+    readonly vaultAddress: string;
+    /** Amount in human-readable decimal format. */
+    readonly amount: string;
+    /**
+     * CCTP transfer speed to price the quote for.
+     *
+     * Should match the speed used at deposit time so the quoted forwarder fee
+     * reflects the actual cost. `FAST` prices the low-finality path.
+     */
+    readonly transferSpeed?: TransferSpeed | `${TransferSpeed}` | undefined;
+    /** Optional earn configuration. */
+    readonly config?: EarnConfig | undefined;
+}
+/**
+ * Parameters for getting a deposit quote.
+ *
+ * Same-chain when only `from` is provided; cross-chain when a destination
+ * `chain` (and destination `address`) are provided and differ from
+ * `from.chain`.
+ *
+ * @example
+ * ```typescript
+ * const sameChainParams: GetDepositQuoteParams = {
+ *   from: { adapter, chain: 'Arc_Testnet' },
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * }
+ *
+ * const crossChainParams: GetDepositQuoteParams = {
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   chain: 'Arc_Testnet',
+ *   address: '0x1234567890123456789012345678901234567890',
+ *   vaultAddress: '0x...',
+ *   amount: '100.50',
+ * }
+ * ```
+ */
+type GetDepositQuoteParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> = SameChainGetDepositQuoteParams<TFromAdapterCapabilities> | CrossChainGetDepositQuoteParams<TFromAdapterCapabilities>;
 /**
  * Parameters for getting a withdrawal quote.
  *
@@ -6682,6 +7510,11 @@ type EarnGetVaultsResult = Omit<GetVaultsResult, 'vaults'> & {
     /** Successfully resolved vault information. */
     readonly vaults: readonly EarnVaultInfo[];
 };
+/** Result of a vault discovery query. */
+type EarnExploreVaultsResult = Omit<ExploreVaultsResult, 'vaults'> & {
+    /** Vaults matching the query, in the requested sort order. */
+    readonly vaults: readonly EarnVaultInfo[];
+};
 /** Accrued reward returned by the SDK in human-readable decimal form. */
 type EarnAccruedRewardInfo = Omit<AccruedRewardInfo, 'amount'> & {
     /** Accrued reward amount in human-readable decimal format. */
@@ -6742,16 +7575,18 @@ interface EarnClaimedRewardsResult {
  */
 type EarnClaimRewardsResult = NoClaimableRewardsResult | EarnClaimedRewardsResult;
 /** Result of a deposit quote operation. */
-type EarnDepositQuoteInfo = Omit<DepositQuoteInfo, 'deposit' | 'expectedShares' | 'fees'> & {
+type EarnDepositQuoteInfo = Omit<DepositQuoteInfo, 'deposit' | 'expectedShares' | 'fees' | 'gasFees'> & {
     /** Deposit asset and amount in human-readable decimal format. */
     readonly deposit: EarnAssetAmount;
     /** Expected vault shares to receive in human-readable decimal format. */
     readonly expectedShares: EarnAssetAmount;
     /** Fees applied to the deposit in human-readable decimal format. */
     readonly fees: readonly EarnAssetAmount[];
+    /** Estimated native gas fees with amounts formatted as decimal strings. */
+    readonly gasFees?: readonly EarnGasFeeEstimate[] | undefined;
 };
 /** Result of a withdrawal quote operation. */
-type EarnWithdrawalQuoteInfo = Omit<WithdrawalQuoteInfo, 'withdrawal' | 'sharesToRedeem' | 'maxWithdrawable' | 'fees'> & {
+type EarnWithdrawalQuoteInfo = Omit<WithdrawalQuoteInfo, 'withdrawal' | 'sharesToRedeem' | 'maxWithdrawable' | 'fees' | 'gasFees'> & {
     /** The withdrawal amount being quoted in human-readable decimal format. */
     readonly withdrawal: EarnAssetAmount;
     /** Vault shares that would be redeemed in human-readable decimal format. */
@@ -6760,6 +7595,8 @@ type EarnWithdrawalQuoteInfo = Omit<WithdrawalQuoteInfo, 'withdrawal' | 'sharesT
     readonly maxWithdrawable: EarnAssetAmount;
     /** Fees applied to the withdrawal in human-readable decimal format. */
     readonly fees: readonly EarnAssetAmount[];
+    /** Estimated native gas fees with amounts formatted as decimal strings. */
+    readonly gasFees?: readonly EarnGasFeeEstimate[] | undefined;
 };
 /** Result of a claim rewards quote operation. */
 type EarnClaimRewardsQuoteInfo = Omit<ClaimRewardsQuoteInfo, 'rewards'> & {
@@ -6778,7 +7615,7 @@ type EarnClaimRewardsQuoteInfo = Omit<ClaimRewardsQuoteInfo, 'rewards'> & {
  * }
  * ```
  */
-type EarnOperationParams = DepositParams | WithdrawParams | ClaimRewardsParams | GetVaultsParams | GetPositionParams | GetDepositQuoteParams | GetWithdrawalQuoteParams | GetClaimRewardsQuoteParams;
+type EarnOperationParams = AnyDepositParams | WithdrawParams | ClaimRewardsParams | GetVaultsParams | ExploreVaultsParams | ExploreVaultsIteratorParams | GetPositionParams | GetDepositQuoteParams | GetWithdrawalQuoteParams | GetClaimRewardsQuoteParams;
 
 /**
  * Parameters for initiating a cross-chain USDC bridge transfer.
@@ -6890,6 +7727,25 @@ interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = Ad
 type SwapAdapterContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> = Omit<AdapterContext<TAdapterCapabilities>, 'chain'> & {
     chain: SwapChainIdentifier;
 };
+/**
+ * Destination details for same-chain or cross-chain swaps.
+ */
+interface SwapDestination {
+    /**
+     * Optional destination chain.
+     *
+     * Defaults to `from.chain` for same-chain swaps.
+     */
+    chain?: SwapChainIdentifier;
+    /**
+     * Optional recipient address.
+     *
+     * Defaults to the source wallet address for same-chain swaps. Cross-chain
+     * swaps require this field because the destination wallet may be on a
+     * different chain/address format.
+     */
+    recipientAddress?: string;
+}
 /**
  * Allowance strategy for token approvals during swap operations.
  *
@@ -6964,10 +7820,11 @@ interface SwapConfig {
      * callback approach via `setCustomFeePolicy()` instead.
      *
      * @remarks
-     * - Service calculates fee using `estimatedAmount` for output fees
+     * - Service calculates fee using `estimatedAmount` for same-chain output fees
+     * - Cross-chain fees are always collected from the source-chain input token
      * - Fee is sent to your configured `recipientAddress`
      * - Single API call (efficient)
-     * - Must be > 0 and <= 10000 bps (100%)
+     * - Must be greater than 0 and less than or equal to 10000 bps (100%)
      *
      * @example
      * ```typescript
@@ -6983,8 +7840,9 @@ interface SwapConfig {
          *
          * 100 bps = 1%, 1000 bps = 10%, 10000 bps = 100%
          *
-         * Fee is calculated from `estimatedAmount` for output fees.
-         * Must be > 0 and <= 10000 (maximum 100%).
+         * Fee is calculated from `estimatedAmount` for same-chain output fees and
+         * from the input amount for cross-chain swaps.
+         * Must be greater than 0 and less than or equal to 10000 (maximum 100%).
          *
          * For complex fee logic, use kit-level `setCustomFeePolicy()` instead.
          *
@@ -6994,76 +7852,22 @@ interface SwapConfig {
         /**
          * Address that will receive the developer's 90% fee share.
          *
-         * Must be a valid address format for the swap chain (EVM or Solana).
+         * Must be valid on the fee payout chain: source chain for input-side fees
+         * and cross-chain swaps, destination chain for same-chain output-side fees.
          *
          * @example '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          */
         recipientAddress: string;
     };
     /**
-     * Identifier for the kit instance initiating this swap.
+     * Stablecoin Service Kit Key used to authenticate service-backed swap
+     * requests.
      *
-     * Used for tracking and analytics purposes.
+     * Treat this value as a credential. Do not log it, embed it in client-side
+     * source, or expose it in telemetry.
      */
     kitKey?: string;
 }
-/**
- * Parameters for initiating a single-chain stablecoin swap.
- *
- * This type is used as the primary input to swap operations, allowing users to specify
- * the source context, input/output tokens, swap amount, and optional configuration.
- *
- * SwapKit supports swaps between stablecoins (USDC, USDT, EURC, USDe, DAI, PYUSD),
- * wrapped tokens (WBTC, WETH, WSOL, WAVAX, WPOL), and native tokens
- * (e.g., ETH on Ethereum, SOL on Solana) via the `NATIVE` alias.
- *
- * - The `from` field specifies the source adapter context (wallet and chain).
- *   The chain must be a {@link SwapChain} member (or its corresponding string
- *   literal) so IDE autocomplete only surfaces swap-supported networks.
- * - The `tokenIn` field specifies the input token (see {@link SupportedToken}).
- * - The `tokenOut` field specifies the output token (see {@link SupportedToken}).
- * - The `amountIn` field is a human-readable decimal string (e.g., '10.5').
- * - The `config` field allows customization of swap behavior.
- *
- * @typeParam TFromAdapterCapabilities - The adapter capabilities type for the source adapter.
- *
- * @example
- * ```typescript
- * import { SwapParams } from '@circle-fin/swap-kit'
- * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
- *
- * const adapter = createViemAdapterFromPrivateKey({
- *   privateKey: process.env.PRIVATE_KEY,
- * })
- *
- * // Swap 100.50 USDC for USDT
- * const params: SwapParams = {
- *   from: { adapter, chain: 'Ethereum' },
- *   tokenIn: 'USDC',
- *   tokenOut: 'USDT',
- *   amountIn: '100.50', // 100.50 USDC
- *   config: {
- *     slippageBps: 300, // 3% slippage
- *     allowanceStrategy: 'permit'
- *   }
- * }
- * ```
- *
- * @example
- * ```typescript
- * // Swap 0.05 ETH for USDC with explicit address and string literal chain
- * const paramsWithNative: SwapParams = {
- *   from: {
- *     adapter,
- *     chain: 'Ethereum',
- *     address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
- *   },
- *   tokenIn: 'NATIVE',
- *   tokenOut: 'USDC',
- *   amountIn: '0.05' // 0.05 ETH
- * }
- * ```
- */
 interface SwapParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
     /**
      * The source adapter context (wallet and chain) for the swap.
@@ -7092,6 +7896,13 @@ interface SwapParams<TFromAdapterCapabilities extends AdapterCapabilities = Adap
      * (e.g., `'0.05'` for 0.05 USDC or 0.05 ETH).
      */
     amountIn: string;
+    /**
+     * Optional destination chain/address.
+     *
+     * For same-chain swaps this may be omitted and the source wallet address is
+     * used as the recipient. Cross-chain swaps require `recipientAddress`.
+     */
+    to?: SwapDestination;
     /**
      * Optional configuration for swap behavior.
      *
@@ -7147,8 +7958,8 @@ interface OperationParamsMap {
  * ```typescript
  * // Bridge operation - uses BridgeParams
  * const bridgeFee = await context.getFee('bridge', {
- *   from: { agent: sourceAgent, chain: 'Ethereum' },
- *   to: { agent: destAgent, chain: 'Polygon' },
+ *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
+ *   to: { adapter: destAdapter, chain: 'Polygon' },
  *   amount: '100.50'
  * })
  * ```
@@ -7277,7 +8088,9 @@ interface AppKitContext {
  * })
  * ```
  */
-declare function deposit<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(context: AppKitContext, params: DepositParams<TFromAdapterCapabilities>): Promise<EarnDepositResult>;
+declare function deposit<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(context: AppKitContext, params: SameChainDepositParams<TFromAdapterCapabilities>): Promise<EarnSameChainDepositResult>;
+declare function deposit<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(context: AppKitContext, params: CrossChainDepositParams<TFromAdapterCapabilities>): Promise<EarnCrossChainDepositResult>;
+declare function deposit<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(context: AppKitContext, params: AnyDepositParams<TFromAdapterCapabilities>): Promise<EarnDepositOutcome>;
 /**
  * Execute an earn withdrawal operation.
  *
@@ -7344,6 +8157,52 @@ declare function claimRewards<TFromAdapterCapabilities extends AdapterCapabiliti
  * ```
  */
 declare function getVaults(context: AppKitContext, params: GetVaultsParams): Promise<EarnGetVaultsResult>;
+/**
+ * Discover vaults available on a chain.
+ *
+ * @param context - AppKit context
+ * @param params - Discovery parameters. `chain` selects the chain; protocol, asset, APY, and TVL filters are optional
+ * @returns Promise resolving to matching vaults with pagination metadata
+ * @throws If EarnKit validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { exploreVaults } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const result = await exploreVaults(context, {
+ *   chain: EarnChain.Arc_Testnet,
+ *   minApy: '0.03',
+ *   sortBy: 'apy',
+ * })
+ * ```
+ */
+declare function exploreVaults(context: AppKitContext, params: ExploreVaultsParams): Promise<EarnExploreVaultsResult>;
+/**
+ * Lazily iterate every vault available on a chain.
+ *
+ * @param context - AppKit context
+ * @param params - Discovery parameters (no `page`; the iterator manages it)
+ * @returns An async generator yielding each matching vault
+ * @throws If EarnKit validation fails or no provider is configured
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { exploreVaultsIterator } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * for await (const vault of exploreVaultsIterator(context, {
+ *   chain: EarnChain.Arc_Testnet,
+ * })) {
+ *   console.log(vault.name)
+ * }
+ * ```
+ */
+declare function exploreVaultsIterator(context: AppKitContext, params: ExploreVaultsIteratorParams): AsyncGenerator<EarnVaultInfo, void, undefined>;
 /**
  * Fetch a wallet position in a vault.
  *
@@ -7366,6 +8225,49 @@ declare function getVaults(context: AppKitContext, params: GetVaultsParams): Pro
  * ```
  */
 declare function getPosition<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(context: AppKitContext, params: GetPositionParams<TFromAdapterCapabilities>): Promise<EarnPositionInfo>;
+/**
+ * Fetch the current status of a cross-chain Earn deposit.
+ *
+ * @param context - AppKit context
+ * @param params - Status query parameters identifying the deposit by execId
+ * @returns Promise resolving to the structured cross-chain deposit status
+ * @throws If EarnKit validation fails, no provider is configured, or the status request fails
+ *
+ * @example
+ * ```typescript
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { getCrossChainDepositStatus } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const status = await getCrossChainDepositStatus(context, {
+ *   execId: '550e8400-e29b-41d4-a716-446655440000',
+ * })
+ * console.log(status.status)
+ * ```
+ */
+declare function getCrossChainDepositStatus(context: AppKitContext, params: GetCrossChainDepositStatusParams): Promise<EarnCrossChainDepositStatus>;
+/**
+ * Poll a cross-chain Earn deposit until it reaches a terminal bridge state.
+ *
+ * @param context - AppKit context
+ * @param params - Wait parameters including execId and optional polling knobs
+ * @returns Promise resolving to the wait result and last observed bridge status
+ * @throws If EarnKit validation fails, no provider is configured, or a status request fails
+ *
+ * @example
+ * ```typescript
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { waitForCrossChainDeposit } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ * const result = await waitForCrossChainDeposit(context, {
+ *   execId: '550e8400-e29b-41d4-a716-446655440000',
+ *   pollIntervalMs: 5_000,
+ * })
+ * console.log(result.outcome)
+ * ```
+ */
+declare function waitForCrossChainDeposit(context: AppKitContext, params: WaitForCrossChainDepositParams): Promise<EarnCrossChainDepositWaitResult>;
 /**
  * Fetch a deposit quote.
  *
@@ -7435,4 +8337,4 @@ declare function getWithdrawalQuote<TFromAdapterCapabilities extends AdapterCapa
  */
 declare function getClaimRewardsQuote<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(context: AppKitContext, params: GetClaimRewardsQuoteParams<TFromAdapterCapabilities>): Promise<EarnClaimRewardsQuoteInfo>;
 
-export { claimRewards, deposit, getClaimRewardsQuote, getDepositQuote, getPosition, getVaults, getWithdrawalQuote, withdraw };
+export { claimRewards, deposit, exploreVaults, exploreVaultsIterator, getClaimRewardsQuote, getCrossChainDepositStatus, getDepositQuote, getPosition, getVaults, getWithdrawalQuote, waitForCrossChainDeposit, withdraw };