@circle-fin/app-kit 1.8.1 → 1.10.0

package/index.d.ts

@@ -374,6 +374,14 @@ interface CCTPSplitConfig {
     type: 'split';
     tokenMessenger: string;
     messageTransmitter: string;
+    /**
+     * Address of the `TokenMessengerWithFees` wrapper, when deployed on this chain.
+     *
+     * Optional. Present only on chains that support the prepaid FORWARD path
+     * (source-chain fee collection via `depositForBurnWithHookAndFees`). Resolve
+     * it with `resolveCCTPV2ContractAddress(chain, 'tokenMessengerWithFees')`.
+     */
+    tokenMessengerWithFees?: string;
     confirmations: number;
 }
 /**
@@ -394,6 +402,14 @@ interface CCTPSplitConfig {
 interface CCTPMergedConfig {
     type: 'merged';
     contract: string;
+    /**
+     * Address of the `TokenMessengerWithFees` wrapper, when deployed on this chain.
+     *
+     * Optional. Present only on chains that support the prepaid FORWARD path
+     * (source-chain fee collection via `depositForBurnWithHookAndFees`). Resolve
+     * it with `resolveCCTPV2ContractAddress(chain, 'tokenMessengerWithFees')`.
+     */
+    tokenMessengerWithFees?: string;
     confirmations: number;
 }
 /**
@@ -528,6 +544,21 @@ interface GatewayV1Contracts {
      * @example "0xabcdef1234567890abcdef1234567890abcdef12"
      */
     minter: string;
+    /**
+     * The address of the `DepositForHandler` contract.
+     *
+     * @description Optional. The handler the GenericExecutor calls on this chain
+     * to run a fast cross-chain deposit into the {@link GatewayV1Contracts.wallet}.
+     * Present only on chains that are fast-deposit destinations; other Gateway
+     * chains omit it.
+     *
+     * Address format varies by blockchain:
+     * - EVM chains: 40-character hexadecimal with 0x prefix (e.g., "0x1234...")
+     * - Solana: Base58-encoded 32-byte address (e.g., "9WzDX...")
+     *
+     * @example "0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48"
+     */
+    depositForHandler?: string;
 }
 /**
  * Versioned map of Gateway contract configurations.
@@ -659,6 +690,8 @@ declare enum Blockchain {
     Celo_Alfajores_Testnet = "Celo_Alfajores_Testnet",
     Codex = "Codex",
     Codex_Testnet = "Codex_Testnet",
+    Cronos = "Cronos",
+    Cronos_Testnet = "Cronos_Testnet",
     Edge = "Edge",
     Edge_Testnet = "Edge_Testnet",
     Ethereum = "Ethereum",
@@ -900,6 +933,7 @@ declare enum BridgeChain {
     Avalanche = "Avalanche",
     Base = "Base",
     Codex = "Codex",
+    Cronos = "Cronos",
     Edge = "Edge",
     Ethereum = "Ethereum",
     HyperEVM = "HyperEVM",
@@ -923,6 +957,7 @@ declare enum BridgeChain {
     Avalanche_Fuji = "Avalanche_Fuji",
     Base_Sepolia = "Base_Sepolia",
     Codex_Testnet = "Codex_Testnet",
+    Cronos_Testnet = "Cronos_Testnet",
     Edge_Testnet = "Edge_Testnet",
     Ethereum_Sepolia = "Ethereum_Sepolia",
     HyperEVM_Testnet = "HyperEVM_Testnet",
@@ -1358,6 +1393,7 @@ declare const ArcTestnet: {
             readonly v1: {
                 readonly wallet: "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
                 readonly minter: "0x0022222ABE238Cc2C7Bb1f21003F0a260052475B";
+                readonly depositForHandler: "0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48";
             };
         };
         readonly forwarderSupported: {
@@ -1880,6 +1916,94 @@ declare const CodexTestnet: {
     };
 };
 
+/**
+ * Cronos Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Cronos blockchain.
+ * Cronos is an EVM-compatible blockchain.
+ */
+declare const Cronos: {
+    readonly type: "evm";
+    readonly chain: Blockchain.Cronos;
+    readonly name: "Cronos";
+    readonly title: "Cronos Mainnet";
+    readonly nativeCurrency: {
+        readonly name: "Cronos";
+        readonly symbol: "CRO";
+        readonly decimals: 18;
+    };
+    readonly chainId: 25;
+    readonly isTestnet: false;
+    readonly explorerUrl: "https://cronoscan.com/tx/{hash}";
+    readonly rpcEndpoints: readonly ["https://evm.cronos.org"];
+    readonly eurcAddress: "0xA6dE01a2d62C6B5f3525d768f34d276652C554c8";
+    readonly usdcAddress: "0x3D7F2C478aAfdB65542BCB44bCeeC05849999d2D";
+    readonly usdtAddress: null;
+    readonly cctp: {
+        readonly domain: 32;
+        readonly contracts: {
+            readonly v2: {
+                readonly type: "split";
+                readonly tokenMessenger: "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d";
+                readonly messageTransmitter: "0x81D40F21F12A8F0E3252Bccb954D722d4c464B64";
+                readonly confirmations: 1;
+                readonly fastConfirmations: 1;
+            };
+        };
+        readonly forwarderSupported: {
+            readonly source: false;
+            readonly destination: false;
+        };
+    };
+    readonly kitContracts: {
+        readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
+    };
+};
+
+/**
+ * Cronos Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Cronos blockchain.
+ * Cronos is an EVM-compatible blockchain.
+ */
+declare const CronosTestnet: {
+    readonly type: "evm";
+    readonly chain: Blockchain.Cronos_Testnet;
+    readonly name: "Cronos Testnet";
+    readonly title: "Cronos Testnet";
+    readonly nativeCurrency: {
+        readonly name: "CRO";
+        readonly symbol: "tCRO";
+        readonly decimals: 18;
+    };
+    readonly chainId: 338;
+    readonly isTestnet: true;
+    readonly explorerUrl: "https://explorer.cronos.org/testnet/tx/{hash}";
+    readonly rpcEndpoints: readonly ["https://evm-t3.cronos.org"];
+    readonly eurcAddress: "0x31f7538adb53cF16350e6B0c89d03D91b7D12c46";
+    readonly usdcAddress: "0xEb33dc5fac03833e132593659e1dE7256aB59794";
+    readonly usdtAddress: null;
+    readonly cctp: {
+        readonly domain: 32;
+        readonly contracts: {
+            readonly v2: {
+                readonly type: "split";
+                readonly tokenMessenger: "0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA";
+                readonly messageTransmitter: "0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275";
+                readonly confirmations: 1;
+                readonly fastConfirmations: 1;
+            };
+        };
+        readonly forwarderSupported: {
+            readonly source: false;
+            readonly destination: false;
+        };
+    };
+    readonly kitContracts: {
+        readonly bridge: "0xC5567a5E3370d4DBfB0540025078e283e36A363d";
+    };
+};
+
 /**
  * Edge Mainnet chain definition
  * @remarks
@@ -4173,6 +4297,8 @@ declare const Chains_Celo: typeof Celo;
 declare const Chains_CeloAlfajoresTestnet: typeof CeloAlfajoresTestnet;
 declare const Chains_Codex: typeof Codex;
 declare const Chains_CodexTestnet: typeof CodexTestnet;
+declare const Chains_Cronos: typeof Cronos;
+declare const Chains_CronosTestnet: typeof CronosTestnet;
 declare const Chains_Edge: typeof Edge;
 declare const Chains_EdgeTestnet: typeof EdgeTestnet;
 declare const Chains_Ethereum: typeof Ethereum;
@@ -4240,6 +4366,8 @@ declare namespace Chains {
     Chains_CeloAlfajoresTestnet as CeloAlfajoresTestnet,
     Chains_Codex as Codex,
     Chains_CodexTestnet as CodexTestnet,
+    Chains_Cronos as Cronos,
+    Chains_CronosTestnet as CronosTestnet,
     Chains_Edge as Edge,
     Chains_EdgeTestnet as EdgeTestnet,
     Chains_Ethereum as Ethereum,
@@ -5376,6 +5504,110 @@ interface CCTPv2ActionMap {
          */
         hookData: string;
     };
+    /**
+     * Initiate a prepaid cross-chain USDC transfer through the `TokenMessengerWithFees` wrapper.
+     *
+     * Burn USDC on the source chain while collecting all fees up front against a
+     * signed quote. The wrapper collects the fee via `FeeManager`, then delegates
+     * to the unmodified `TokenMessengerV2`. When `hookData` is provided (the
+     * GenericExecutor FORWARD path) the wrapper's `depositForBurnWithHookAndFees`
+     * contract method is used; otherwise `depositForBurnWithFees` is used.
+     *
+     * @remarks
+     * SDK/contract naming: this SDK action is `depositForBurnWithFees` but, when a
+     * `hookData` is present, it dispatches to the `depositForBurnWithHookAndFees`
+     * contract method on `TokenMessengerWithFees` (NOT on `TokenMessengerV2`).
+     *
+     * Fee payment channel (must match the quote's `feeToken`):
+     * - Native fee (`feeToken` is the zero address): exactly `feeTotalAmount` is
+     *   attached as `msg.value`.
+     * - ERC-20 fee (e.g. USDC): no value is attached; the caller must first approve
+     *   the wrapper for `feeTotalAmount` (see the provider's fee approval helper).
+     *
+     * @remarks
+     * Unlike `depositForBurn`, the `TokenMessengerWithFees` contract methods do NOT
+     * take `maxFee` or `minFinalityThreshold` — fee and finality behavior are
+     * derived from the signed quote — so those fields are omitted from this action.
+     *
+     * @example
+     * ```typescript
+     * await adapter.action('cctp.v2.depositForBurnWithFees', {
+     *   amount: BigInt('1000000'),
+     *   mintRecipient: executorAddress,     // GenericExecutor (bytes32)
+     *   destinationCaller: executorAddress, // GenericExecutor (bytes32)
+     *   fromChain: ethereum,
+     *   toChain: arc,
+     *   hookData: geForwardHookData,        // cctp-forward-wrapped GenericExecutor blob
+     *   claim: { signedQuote: '0x...', refundAddress: '0x...' },
+     *   feeToken: '0x0000000000000000000000000000000000000000', // native
+     *   feeTotalAmount: 3500000n,
+     * })
+     * ```
+     */
+    depositForBurnWithFees: Omit<CCTPv2ActionMap['depositForBurn'], 'maxFee' | 'minFinalityThreshold'> & {
+        /**
+         * Optional hex-encoded hook data for the GenericExecutor FORWARD path.
+         *
+         * When present, the `depositForBurnWithHookAndFees` contract method is used
+         * and the blob must be wrapped in the `cctp-forward` envelope (the wrapper
+         * rejects a FORWARD fee quote whose hook lacks it). When omitted, the plain
+         * `depositForBurnWithFees` contract method is used.
+         */
+        hookData?: string;
+        /**
+         * Signed fee quote claim passed to the `TokenMessengerWithFees` wrapper.
+         *
+         * `signedQuote` is the `[uint8 0x01][abi.encode(Quote)]` blob returned by the
+         * Fee Quote service; `refundAddress` receives any fee overpayment refund.
+         */
+        claim: QuoteClaim;
+        /**
+         * Fee token from the signed quote.
+         *
+         * The zero address (`0x000…0`) means the fee is paid in native currency and
+         * is attached as `msg.value`. Any other address (e.g. USDC) means an ERC-20
+         * fee that must be approved to the wrapper beforehand. This is independent of
+         * `burnToken`, which is always USDC.
+         */
+        feeToken: string;
+        /**
+         * Total fee amount from the signed quote, in `feeToken` minor units.
+         *
+         * Firm only until the quote's `expiresAt`. For a native fee this is the exact
+         * `msg.value`; for an ERC-20 fee this is the amount approved to the wrapper.
+         */
+        feeTotalAmount: bigint;
+    };
+}
+/**
+ * Signed fee quote claim consumed by the `TokenMessengerWithFees` wrapper.
+ *
+ * Mirrors the on-chain `IFeeManager.QuoteClaim` struct.
+ *
+ * @example
+ * ```typescript
+ * const claim: QuoteClaim = {
+ *   signedQuote: '0x01...', // [uint8 0x01][abi.encode(Quote)]
+ *   refundAddress: '0xUserWallet...',
+ * }
+ * ```
+ */
+interface QuoteClaim {
+    /**
+     * Opaque signed quote bytes (`0x` hex) from the fee-quote service
+     * (`SignedFeeQuote.signedQuote` returned by `fetchFeeQuote`). Pass verbatim;
+     * do not decode.
+     *
+     * The quote binds the FORWARD fee item to the on-chain call via `argsHash`;
+     * passing a quote that does not match the burn args reverts `QuoteArgsMismatch`.
+     */
+    signedQuote: string;
+    /**
+     * Address that receives any refund of overpaid fees.
+     *
+     * Typically the user wallet that authorized the burn.
+     */
+    refundAddress: string;
 }
 
 /**
@@ -8373,15 +8605,15 @@ declare const ServiceError: {
 };
 
 /**
- * Standardized error definitions for Earn/Zenith operations.
+ * Standardized error definitions for Earn operations.
  *
  * These error codes provide fine-grained categorization of failures
- * from the Zenith earn service, enabling SDK consumers to distinguish
+ * from the Earn service, enabling SDK consumers to distinguish
  * between input errors (fix your request) and service errors (retry later).
  *
  * Error code ranges:
- * - 1100-1105: INPUT errors — invalid inputs, unsupported configurations
- * - 8100-8104: SERVICE errors — retryable backend/provider failures
+ * - 1100-1106: INPUT errors — invalid, unsupported, or stale request state
+ * - 8100-8105: SERVICE errors — retryable backend/provider failures
  *
  * @example
  * ```typescript
@@ -8440,6 +8672,15 @@ declare const EarnError: {
         readonly name: "EARN_UNSUPPORTED_BRIDGE_ROUTE";
         readonly type: ErrorType;
     };
+    /**
+     * The bridge quote expired. This is an INPUT error because the prepared
+     * request is stale and must be replaced instead of retried.
+     */
+    readonly BRIDGE_QUOTE_EXPIRED: {
+        readonly code: 1106;
+        readonly name: "EARN_BRIDGE_QUOTE_EXPIRED";
+        readonly type: ErrorType;
+    };
     /** The proxy signing call failed — retryable. */
     readonly SIGNING_FAILED: {
         readonly code: 8100;
@@ -8470,6 +8711,12 @@ declare const EarnError: {
         readonly name: "EARN_PAUSED";
         readonly type: ErrorType;
     };
+    /** Position PnL is still reconciling and can be retried. */
+    readonly POSITION_PNL_PENDING: {
+        readonly code: 8105;
+        readonly name: "EARN_POSITION_PNL_PENDING";
+        readonly type: ErrorType;
+    };
 };
 
 /**
@@ -12015,6 +12262,38 @@ interface ICCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> {
      * @returns A promise that resolves to the attestation message.
      */
     fetchAttestation<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], txHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
+    /**
+     * Polls attestation data until Circle's relayer mint transaction is confirmed.
+     *
+     * @param source - The source wallet context containing the chain definition and wallet address.
+     * @param txHash - The transaction hash of the deposit for burn transaction.
+     * @param config - Optional polling configuration overrides.
+     * @returns A promise that resolves to the relayer mint attestation message.
+     * @throws KitError If the source wallet context is invalid, the transaction hash is invalid,
+     *   the relayer forward fails, the response is invalid, or polling times out.
+     *
+     * @example
+     * ```typescript
+     * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+     * import { Chains } from '@core/chains'
+     *
+     * const provider = new CCTPV2BridgingProvider({
+     *   headers: { 'X-Partner-UUID': '00000000-0000-0000-0000-000000000000' },
+     * })
+     *
+     * const attestation = await provider.fetchRelayerMint(
+     *   {
+     *     adapter,
+     *     chain: Chains.EthereumSepolia,
+     *     address: '0x1234...',
+     *   },
+     *   '0xabc123...',
+     * )
+     *
+     * console.log('Relayer mint tx:', attestation.forwardTxHash)
+     * ```
+     */
+    fetchRelayerMint<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], txHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
     /**
      * Requests a fresh attestation for an expired attestation.
      *
@@ -12040,16 +12319,173 @@ interface ICCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> {
     mint<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], destination: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>['destination'], attestation: AttestationMessage): Promise<PreparedChainRequest>;
 }
 
+/**
+ * An ERC-20 approval required before a prepaid-FORWARD burn.
+ *
+ * @example
+ * ```typescript
+ * const approval: FeeApproval = {
+ *   token: '0xUSDC...',
+ *   amount: 1_003_500_000n,
+ * }
+ * ```
+ */
+interface FeeApproval {
+    /**
+     * Token address to approve (the burn token and/or the ERC-20 fee token).
+     */
+    token: string;
+    /**
+     * Amount to approve to the `TokenMessengerWithFees` wrapper, in token minor units.
+     */
+    amount: bigint;
+}
+/**
+ * The resolved fee payment channel for a prepaid-FORWARD burn.
+ *
+ * @example
+ * ```typescript
+ * const plan: FeePaymentPlan = {
+ *   isNativeFee: false,
+ *   isBurnTokenFee: true,
+ *   nativeValue: 0n,
+ *   approvals: [{ token: '0xUSDC...', amount: 1_003_500_000n }],
+ * }
+ * ```
+ */
+interface FeePaymentPlan {
+    /**
+     * True when the fee is paid in native currency (`feeToken` is the zero address).
+     */
+    isNativeFee: boolean;
+    /**
+     * True when the fee token is the same token being burned (both USDC).
+     *
+     * In this case a single, combined approval covers both the burn and the fee,
+     * so the redundant second approval is skipped.
+     */
+    isBurnTokenFee: boolean;
+    /**
+     * Native value to attach as `msg.value`.
+     *
+     * Exactly `feeTotalAmount` for a native fee; `0n` for an ERC-20 fee.
+     */
+    nativeValue: bigint;
+    /**
+     * ERC-20 approvals required before the burn, each to the `TokenMessengerWithFees`
+     * wrapper.
+     *
+     * - Native fee: a single approval of `amount` for the burn token.
+     * - ERC-20 fee equal to the burn token: a single approval of `amount + feeTotalAmount`.
+     * - ERC-20 fee different from the burn token: two approvals — `amount` for the
+     *   burn token and `feeTotalAmount` for the fee token.
+     */
+    approvals: FeeApproval[];
+}
+
 /**
  * Configuration options for the CCTP v2 provider.
  *
  * @remarks
  * This interface defines all configurable aspects of the CCTP v2 provider:
  * - attestation: Settings for the attestation fetching process
+ * - headers: Custom HTTP headers sent with every Circle attestation API request
  */
 interface CCTPV2Config {
     /** Configuration for the attestation fetching process */
     attestation?: Partial<ApiPollingConfig>;
+    /**
+     * Custom HTTP headers sent with every Circle attestation (Iris) API request
+     * made by the provider (attestation fetch, re-attestation, and relayer mint
+     * status polling).
+     *
+     * @remarks
+     * Headers are merged on top of the defaults (such as `Content-Type`) without
+     * removing them. The header is forwarded as-is to Circle's API; the SDK does
+     * not interpret it.
+     *
+     * Precedence (lowest to highest): provider defaults, then these
+     * `config.headers`, then any per-call `config.headers` passed to
+     * {@link CCTPV2BridgingProvider.fetchAttestation},
+     * {@link CCTPV2BridgingProvider.fetchRelayerMint}, or
+     * {@link CCTPV2BridgingProvider.reAttest}.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Parameters for a prepaid-FORWARD burn via {@link CCTPV2BridgingProvider.burnWithFees}.
+ *
+ * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
+ */
+interface BurnWithFeesParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
+    /**
+     * Source wallet context (adapter + CCTP v2 source chain).
+     */
+    source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>;
+    /**
+     * Destination chain definition (provides the destination CCTP domain).
+     */
+    destinationChain: ChainDefinitionWithCCTPv2;
+    /**
+     * Amount of USDC to burn, in minor units.
+     */
+    amount: string | bigint;
+    /**
+     * The GenericExecutor address on the destination chain.
+     *
+     * Used for BOTH `mintRecipient` and `destinationCaller` (padded to bytes32 by
+     * the underlying action): the executor mints to itself and is the only account
+     * allowed to complete the transfer.
+     */
+    executor: string;
+    /**
+     * The `cctp-forward`-wrapped GenericExecutor hookData blob.
+     *
+     * Produced with `@core/utils`: wrap the bare blob from
+     * `buildDepositForGenericExecutorPayload(...).hookData` with
+     * `buildForwardingHookDataWithPayload(version, bareBlob)`. It must begin with
+     * the `cctp-forward` frame, or the wrapper reverts `ForwardFeeWithoutHook`.
+     *
+     * Pass the SAME wrapped bytes here that were bound to the FORWARD fee quote
+     * (`fetchFeeQuote` FORWARD `params.hookData`); mismatched bytes revert
+     * `QuoteArgsMismatch`. Do not pass the bare (`circle-generic-executor`) blob.
+     */
+    hookData: string;
+    /**
+     * Signed fee quote claim (`{ signedQuote, refundAddress }`).
+     */
+    claim: QuoteClaim;
+    /**
+     * Fee token from the quote. The zero address denotes a native fee.
+     */
+    feeToken: string;
+    /**
+     * Total fee amount from the quote, in `feeToken` minor units.
+     */
+    feeTotalAmount: string | bigint;
+}
+/**
+ * Result of {@link CCTPV2BridgingProvider.burnWithFees}.
+ *
+ * The prepared requests are returned unexecuted; the caller executes the
+ * approvals first (in order) and then the burn.
+ */
+interface BurnWithFeesResult {
+    /**
+     * ERC-20 approvals to the `TokenMessengerWithFees` wrapper required before the
+     * burn. Always contains at least one entry: the burn-token approval. A
+     * distinct fee-token approval is added only when the fee token differs from
+     * the burn token and is not the native token.
+     */
+    approvals: PreparedChainRequest[];
+    /**
+     * The prepared `depositForBurnWithHookAndFees` burn transaction.
+     */
+    burn: PreparedChainRequest;
+    /**
+     * The resolved fee payment plan (native value, approvals, and flags).
+     */
+    feePayment: FeePaymentPlan;
 }
 /**
  * Concrete implementation of BridgingProvider for Circle's Cross-Chain Transfer Protocol (CCTP) version 2.
@@ -12115,6 +12551,20 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * @param config - Optional configuration overrides for the provider
      */
     constructor(config?: CCTPV2Config);
+    /**
+     * Resolves the effective polling configuration for an attestation request.
+     *
+     * Precedence (lowest to highest): provider `config.attestation`, then the
+     * per-call `config`. Headers merge independently across
+     * `config.attestation.headers`, the provider-level `config.headers`, and any
+     * per-call `config.headers`, so a more specific header augments rather than
+     * replaces the broader ones. The `headers` key is omitted entirely when no
+     * headers are configured, leaving the attestation fetchers' defaults intact.
+     *
+     * @param config - Optional per-call polling configuration overrides
+     * @returns The merged polling configuration passed to the attestation fetchers
+     */
+    private resolveAttestationConfig;
     /**
      * Execute a cross-chain USDC bridge operation using the CCTP v2 protocol.
      *
@@ -12357,6 +12807,43 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * ```
      */
     fetchAttestation<TFromAdapterCapabilities extends AdapterCapabilities>(source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>, transactionHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
+    /**
+     * Polls attestation data until Circle's relayer mint transaction is confirmed.
+     *
+     * This method is used by forwarded transfers. It polls the same Iris
+     * attestation endpoint as {@link CCTPV2BridgingProvider.fetchAttestation},
+     * but waits for a completed relayer forward state and returns the attestation
+     * message containing `forwardTxHash`.
+     *
+     * @typeParam TFromAdapterCapabilities - The type representing the capabilities of the source adapter
+     * @param source - The source wallet context containing the chain definition and wallet address
+     * @param transactionHash - The transaction hash of the burn operation
+     * @param config - Optional polling configuration overrides for timeout, retries, delay, and headers
+     * @returns A promise that resolves to the attestation message with `forwardTxHash`
+     * @throws KitError If the relayer forward fails, the response is invalid, or polling times out
+     *
+     * @example
+     * ```typescript
+     * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+     * import { Chains } from '@core/chains'
+     *
+     * const provider = new CCTPV2BridgingProvider({
+     *   headers: { 'X-Partner-UUID': '00000000-0000-0000-0000-000000000000' },
+     * })
+     *
+     * const attestation = await provider.fetchRelayerMint(
+     *   {
+     *     adapter,
+     *     chain: Chains.EthereumSepolia,
+     *     address: '0x1234...',
+     *   },
+     *   '0xabc123...',
+     * )
+     *
+     * console.log('Relayer mint tx:', attestation.forwardTxHash)
+     * ```
+     */
+    fetchRelayerMint<TFromAdapterCapabilities extends AdapterCapabilities>(source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>, transactionHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
     /**
      * Requests a fresh attestation for an expired attestation.
      *
@@ -12508,6 +12995,57 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * ```
      */
     burn<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>): Promise<PreparedChainRequest>;
+    /**
+     * Prepare a prepaid-FORWARD burn through the `TokenMessengerWithFees` wrapper.
+     *
+     * Builds the source-chain `depositForBurnWithHookAndFees` call for the
+     * GenericExecutor FORWARD path: fees are collected up front on the source chain
+     * against a signed quote, `mintRecipient` and `destinationCaller` are both set to
+     * the GenericExecutor, and the GE `hookData` is passed through unchanged.
+     *
+     * This is the low-level on-chain primitive behind the UBK `fastCrossChainDeposit`
+     * and Bridge Kit `bridge({ deposit })` flows. The `hookData` and signed-quote
+     * `claim` are produced elsewhere and passed in here:
+     * - `hookData`: `buildForwardingHookDataWithPayload(version,
+     *   buildDepositForGenericExecutorPayload(...).hookData)` from `@core/utils`.
+     * - `claim.signedQuote` / `feeToken` / `feeTotalAmount`: from `fetchFeeQuote`
+     *   (`@circle-fin/provider-fee-v1`), whose FORWARD item must be bound to the
+     *   SAME `hookData` and executor `destinationCaller` used here.
+     *
+     * The returned approvals and burn are NOT executed — the caller executes the
+     * approvals first (in order) and then the burn. The fee payment channel matches
+     * the quote's `feeToken`:
+     * - Native fee: exactly `feeTotalAmount` is attached as the burn's `msg.value`;
+     *   only the burn amount is approved.
+     * - USDC fee (same token as the burn): a single combined `amount + feeTotalAmount`
+     *   approval covers both; the redundant second approval is skipped.
+     *
+     * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
+     * @param params - The burn amount, executor, hookData, signed-quote claim, and fee.
+     * @returns The prepared approvals, the prepared burn, and the resolved fee plan.
+     * @throws {KitError} If the wallet context is invalid, `destinationChain` does not
+     *   support CCTP v2, the executor is missing, `amount` or `feeTotalAmount` is not
+     *   a bigint or a numeric string coercible to bigint, the hookData lacks a
+     *   `cctp-forward` frame (guaranteed `ForwardFeeWithoutHook`), or the operation
+     *   context cannot be resolved.
+     *
+     * @example
+     * ```typescript
+     * const { approvals, burn } = await provider.burnWithFees({
+     *   source,
+     *   destinationChain: Arc,
+     *   amount: 1_000_000n,
+     *   executor: genericExecutorAddress,
+     *   hookData: geForwardHookData,
+     *   claim: { signedQuote: '0x01...', refundAddress: userAddress },
+     *   feeToken: '0x0000000000000000000000000000000000000000', // native
+     *   feeTotalAmount: 3_500_000n,
+     * })
+     * for (const approval of approvals) await approval.execute()
+     * const txHash = await burn.execute()
+     * ```
+     */
+    burnWithFees<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(params: BurnWithFeesParams<TFromAdapterCapabilities>): Promise<BurnWithFeesResult>;
     /**
      * Waits for a transaction to be mined and confirmed on the blockchain.
      *
@@ -12532,11 +13070,24 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
     waitForTransaction(adapter: Adapter, txHash: string, chain: ChainDefinition, config?: WaitForTransactionConfig): Promise<WaitForTransactionResponse>;
 }
 
+/**
+ * Configuration forwarded to the default bridging providers.
+ */
+interface DefaultProvidersConfig {
+    /**
+     * Custom HTTP headers forwarded with the CCTP provider's attestation (Iris)
+     * API requests. See {@link BridgeKitConfig.headers}.
+     */
+    headers?: Record<string, string>;
+}
 /**
  * The default providers that will be used in addition to the providers provided
  * to the BridgeKit constructor.
+ *
+ * @param config - Optional configuration forwarded to the default providers
+ * @returns The default bridging providers
  */
-declare const getDefaultProviders$1: () => readonly [CCTPV2BridgingProvider];
+declare const getDefaultProviders$1: (config?: DefaultProvidersConfig) => readonly [CCTPV2BridgingProvider];
 
 /**
  * Configuration options for initializing a BridgeKit instance.
@@ -12593,6 +13144,23 @@ interface BridgeKitConfig<TExtraProviders extends FlexibleBridgingProvider[] = [
      * @defaultValue false
      */
     disableErrorReporting?: boolean;
+    /**
+     * Custom HTTP headers forwarded with the default CCTP provider's attestation
+     * (Iris) API requests.
+     *
+     * @remarks
+     * Headers are merged on top of the SDK defaults (such as `Content-Type`)
+     * rather than replacing them. The header is forwarded as-is to Circle's API;
+     * the SDK does not interpret it.
+     *
+     * @example
+     * ```typescript
+     * const kit = new BridgeKit({
+     *   headers: { 'X-Access-Key': '00000000-0000-0000-0000-000000000000' },
+     * })
+     * ```
+     */
+    headers?: Record<string, string>;
 }
 /**
  * Merges action types from multiple bridging providers into a unified action map.
@@ -13320,6 +13888,29 @@ interface ServiceSwapConfig {
      * @example 'lifi', 'paraswap'
      */
     provider?: string;
+    /**
+     * Whether to fuse the ERC-20 approval and the swap into a single atomic
+     * batch when the adapter supports it (EIP-5792, or a signing strategy that
+     * declares atomic batching).
+     *
+     * @remarks
+     * Defaults to `true`. When batching is available this collapses the two
+     * sequential transactions of the on-chain approval path into one atomic
+     * submission — a single signing challenge for a smart-contract wallet. Set
+     * to `false` to force the sequential approve-then-swap path. Has no effect on
+     * the gasless permit path (already a single transaction) or on native-token
+     * swaps (no approval needed).
+     *
+     * The batch path relies on the wallet's own gas estimation for the swap call:
+     * the service-provided gas floor and pre-flight simulation that the sequential
+     * path applies are not conveyed through the batch. For a complex/multi-hop
+     * swap whose wallet-side estimate under-shoots, this can out-of-gas-revert the
+     * atomic batch where the sequential path would succeed — set `false` to fall
+     * back to the service-floored sequential path if you hit this.
+     *
+     * @defaultValue true
+     */
+    batchTransactions?: boolean;
 }
 /**
  * Parameters for initiating a swap operation through the Stablecoin Service.
@@ -14754,9 +15345,10 @@ interface SwapDestinationLeg {
  * Parameters for {@link SwapKit.getSwapStatus}.
  *
  * @remarks
- * Only `txHash`, `chainIn`, and `kitKey` are required. Supply `chainOut`
- * when the original swap was cross-chain (source chain ≠ destination
- * chain).
+ * Only `txHash` and `chainIn` are required; `chainOut` and `kitKey` are
+ * optional. Supply `chainOut` when the original swap was cross-chain
+ * (source chain ≠ destination chain); omit `kitKey` to call in
+ * permissionless mode.
  *
  * The field names mirror {@link SwapResult.chainIn} / {@link
  * SwapResult.chainOut} so consumers can pipe a `SwapResult` straight into
@@ -14771,11 +15363,11 @@ interface SwapDestinationLeg {
  * ```typescript
  * const result = await kit.swap(params)
  *
+ * // Permissionless — no kit key needed. Pass `kitKey` to authenticate.
  * let status = await kit.getSwapStatus({
  *   txHash: result.txHash,
  *   chainIn: result.chainIn,
  *   chainOut: result.chainOut,
- *   kitKey: process.env.KIT_KEY ?? '',
  * })
  * while (status.progress.status === 'PENDING') {
  *   await new Promise((r) => setTimeout(r, 3_000))
@@ -14783,7 +15375,6 @@ interface SwapDestinationLeg {
  *     txHash: result.txHash,
  *     chainIn: result.chainIn,
  *     chainOut: result.chainOut,
- *     kitKey: process.env.KIT_KEY ?? '',
  *   })
  * }
  * ```
@@ -14811,8 +15402,11 @@ interface GetSwapStatusParams {
     /**
      * Stablecoin Service Kit Key used as a bearer credential for the status
      * request. Treat this value as a secret and do not log it.
+     *
+     * Optional — when omitted, the request is made without an `Authorization`
+     * header (permissionless mode).
      */
-    kitKey: string;
+    kitKey?: string;
 }
 /**
  * Result of a swap status lookup — a single snapshot of the swap's state at
@@ -14860,8 +15454,11 @@ interface WaitForSwapCommonParams {
     /**
      * Stablecoin Service Kit Key used as a bearer credential. Treat as a
      * secret and do not log it.
+     *
+     * Optional — when omitted, the request is made without an `Authorization`
+     * header (permissionless mode).
      */
-    readonly kitKey: string;
+    readonly kitKey?: string;
     /**
      * Overall wait budget, in milliseconds. The promise rejects with a
      * RETRYABLE {@link KitError} when this elapses without a terminal
@@ -15022,8 +15619,11 @@ interface GetTokenRatesParams {
     /**
      * Stablecoin Service Kit Key used as a bearer credential for the rates
      * request. Treat this value as a secret and do not log it.
+     *
+     * Optional — when omitted, the request is made without an `Authorization`
+     * header (permissionless mode).
      */
-    kitKey: string;
+    kitKey?: string;
 }
 /**
  * Result of a token rates lookup.
@@ -15198,6 +15798,30 @@ interface SwapKitConfig<TExtraProviders extends FlexibleSwappingProvider[] = []>
     disableErrorReporting?: boolean;
 }
 
+/** @internal */
+declare const bridgeQuoteExpirySchema: z.ZodCatch<z.ZodOptional<z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
+    mode: z.ZodLiteral<"TIMESTAMP">;
+    expiresAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    mode: "TIMESTAMP";
+    expiresAt: string;
+}, {
+    mode: "TIMESTAMP";
+    expiresAt: string;
+}>, z.ZodObject<{
+    mode: z.ZodLiteral<"BLOCK_NUMBER">;
+    expiresAtBlock: z.ZodNumber;
+    blockEstimatedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    mode: "BLOCK_NUMBER";
+    expiresAtBlock: number;
+    blockEstimatedAt?: string | undefined;
+}, {
+    mode: "BLOCK_NUMBER";
+    expiresAtBlock: number;
+    blockEstimatedAt?: string | undefined;
+}>]>>>;
+
 /**
  * Configuration options for the Earn Service provider.
  *
@@ -15271,6 +15895,7 @@ interface VaultRewardInfo {
  *   assetAddress: '0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf',
  *   lltv: 0.86,
  *   supplyUsd: 50000000.25,
+ *   allocationPct: 0.6,
  * }
  * ```
  */
@@ -15283,6 +15908,17 @@ interface CollateralInfo {
     readonly lltv: number;
     /** Approximate supplied value in USD, e.g. 50000000.25 for $50,000,000.25. */
     readonly supplyUsd: number;
+    /**
+     * Share of the vault's supply allocated to this collateral market
+     * (e.g., 0.6 = 60%).
+     *
+     * Populated for Morpho V1 vaults; `null` when the underlying product
+     * exposes no per-market allocation (e.g. Morpho V2). Optional for now — a
+     * backend that predates this field omits it entirely, matching the other
+     * optional facets on {@link EarnOpportunityBase}; a future release makes it
+     * required once every backend emits it.
+     */
+    readonly allocationPct?: number | null | undefined;
 }
 /**
  * Vault warning from the underlying earn protocol.
@@ -15302,65 +15938,253 @@ interface VaultWarning {
     readonly level: 'YELLOW' | 'RED';
 }
 /**
- * Describe a yield-bearing vault available through the earn service.
+ * Manager (e.g., curator) responsible for a yield opportunity.
+ *
+ * Generalizes Morpho's "curator". `null` on the opportunity when the
+ * underlying product has no per-opportunity manager (e.g., a pooled
+ * lending market).
  *
  * @example
  * ```typescript
- * const vault: VaultInfo = {
- *   vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
- *   chain: 'Arc_Testnet',
- *   name: 'Steakhouse USDC',
- *   protocol: 'MORPHO',
- *   asset: 'USDC',
- *   assetAddress: '0x3600000000000000000000000000000000000000',
- *   currentApy: 0.0425,
- *   nativeApy: 0.035,
- *   vaultFee: 0.05,
- *   rewards: [{ token: 'MORPHO', tokenAddress: '0x...', apy: 0.0075 }],
- *   collateral: [{ asset: 'cbBTC', assetAddress: '0x...', lltv: 0.86, supplyUsd: 50000000.25 }],
- *   totalDeposits: Amount.fromJSON({ raw: '15000000000000', decimals: 6 }),
- *   liquidity: Amount.fromJSON({ raw: '5000000000000', decimals: 6 }),
+ * const manager: ManagerInfo = {
+ *   name: 'Steakhouse',
+ *   address: '0x...',
+ *   type: 'curator',
+ * }
+ * ```
+ */
+interface ManagerInfo {
+    /** Human-readable manager name. */
+    readonly name: string;
+    /** On-chain manager address, when the product exposes one. */
+    readonly address?: string | undefined;
+    /**
+     * Manager role within the product. Only `'curator'` is emitted today
+     * (Morpho V1/V2); additional roles are added as the providers that emit
+     * them land.
+     */
+    readonly type: 'curator';
+}
+/**
+ * Yield profile for an opportunity, including trailing averages.
+ *
+ * `current` is always present; trailing and native values are `null` when
+ * unavailable for this instance (e.g., a vault younger than the lookback
+ * window). `source`/`asOf` carry provenance for derived/staleness-prone
+ * values.
+ *
+ * @example
+ * ```typescript
+ * const apyProfile: ApyProfile = {
+ *   current: 0.085,
+ *   native: 0.071,
+ *   d7: 0.082,
+ *   d30: 0.079,
+ *   d90: 0.081,
+ *   rewardShare: 0.16,
+ *   source: 'morpho:avgNetApy',
+ *   asOf: '2026-06-23T18:00:00Z',
+ * }
+ * ```
+ */
+interface ApyProfile {
+    /** Current total APY including rewards. */
+    readonly current: number;
+    /** Native APY excluding reward incentives; `null` when unavailable. */
+    readonly native: number | null;
+    /** Trailing 7-day average net APY; `null` when unavailable. */
+    readonly d7: number | null;
+    /** Trailing 30-day average net APY; `null` when unavailable. */
+    readonly d30: number | null;
+    /** Trailing 90-day average net APY; `null` when unavailable. */
+    readonly d90: number | null;
+    /** Share of current APY attributable to rewards; `null` when unavailable. */
+    readonly rewardShare: number | null;
+    /** Provenance of the trailing values (`native` or `circle:<source>`). */
+    readonly source?: string | undefined;
+    /** RFC3339 timestamp of the newest input used for the trailing values. */
+    readonly asOf?: string | undefined;
+}
+/**
+ * Fee split for an opportunity.
+ *
+ * Each component is `null` when the product does not levy it (e.g., Morpho
+ * V1 vaults have no management fee).
+ *
+ * @example
+ * ```typescript
+ * const fee: FeeInfo = { performance: 0.1, management: null }
+ * ```
+ */
+interface FeeInfo {
+    /** Performance fee as a decimal (e.g., 0.1 = 10%); `null` when unavailable. */
+    readonly performance: number | null;
+    /** Management fee as a decimal; `null` when unavailable. */
+    readonly management: number | null;
+}
+/**
+ * Liquidity profile for an opportunity.
+ *
+ * @example
+ * ```typescript
+ * const liquidityProfile: LiquidityProfile = {
+ *   totalDeposits: Amount.fromJSON({ raw: '45000000000000', decimals: 6 }),
+ *   available: Amount.fromJSON({ raw: '5200000000000', decimals: 6 }),
+ *   totalSupply: Amount.fromJSON({ raw: '44900000000000000000', decimals: 18 }),
  *   status: 'active',
- *   circleGuarded: false,
  * }
  * ```
  */
-interface VaultInfo {
-    /** On-chain vault contract address. */
-    readonly vaultAddress: string;
-    /** Blockchain where the vault is deployed. */
+interface LiquidityProfile {
+    /** Total value deposited in base-unit amount form. */
+    readonly totalDeposits: Amount;
+    /** Available liquidity in base-unit amount form. */
+    readonly available: Amount;
+    /** Outstanding vault share tokens (ERC4626 totalSupply) in base-unit form. */
+    readonly totalSupply: Amount;
+    /** Current liquidity status. */
+    readonly status: 'active' | 'low_liquidity';
+}
+/**
+ * Risk signals for an opportunity.
+ *
+ * @example
+ * ```typescript
+ * const riskSignals: RiskSignals = {
+ *   circleSentinel: true,
+ *   warnings: [],
+ *   earnKitWarnings: [],
+ * }
+ * ```
+ */
+interface RiskSignals {
+    /** Whether the opportunity is covered by Circle Sentinel. */
+    readonly circleSentinel: boolean;
+    /** Protocol warnings for this opportunity. */
+    readonly warnings?: readonly VaultWarning[] | undefined;
+    /** Circle-specific warnings (e.g., unsupported reward protocol). */
+    readonly earnKitWarnings?: readonly string[] | undefined;
+}
+/**
+ * Facets common to every earn opportunity, plus the deprecated flat
+ * fields retained for backward compatibility.
+ *
+ * The flat aliases are emitted by the backend alongside the nested facets
+ * and mapped straight through, so existing consumers keep reading them until
+ * they are removed in a future major release. Narrow on
+ * {@link EarnOpportunity.productType} to access product-specific fields.
+ */
+interface EarnOpportunityBase {
+    /** Blockchain where the opportunity is deployed. */
     readonly chain: `${EarnChain}`;
-    /** Human-readable vault name. */
+    /** Human-readable opportunity name. */
     readonly name: string;
-    /** Vault protocol identifier. */
+    /** Protocol identifier. */
     readonly protocol: string;
     /** Underlying deposit asset symbol (e.g., 'USDC'). */
     readonly asset: string;
     /** Underlying deposit asset contract address. */
     readonly assetAddress: string;
-    /** Total annualized percentage yield including rewards. */
+    /** Reward tokens distributed by this opportunity. */
+    readonly rewards: readonly VaultRewardInfo[];
+    /** Primary on-chain address (protocol-neutral; replaces vaultAddress). */
+    readonly address?: string | undefined;
+    /** RFC3339 freshness timestamp: provider state ts, else cache sync time. */
+    readonly asOf?: string | undefined;
+    /** Manager/curator identity; `null` when the product has no manager. */
+    readonly manager?: ManagerInfo | null | undefined;
+    /** Yield profile including trailing averages. */
+    readonly apyProfile?: ApyProfile | undefined;
+    /** Fee split. */
+    readonly fee?: FeeInfo | undefined;
+    /** Liquidity profile. */
+    readonly liquidityProfile?: LiquidityProfile | undefined;
+    /** Risk signals. */
+    readonly riskSignals?: RiskSignals | undefined;
+    /** @deprecated use {@link EarnOpportunityBase.address} */
+    readonly vaultAddress: string;
+    /** @deprecated use {@link ApyProfile.current} via apyProfile */
     readonly currentApy: number;
-    /** Native APY excluding reward incentives. */
+    /** @deprecated use {@link ApyProfile.native} via apyProfile */
     readonly nativeApy: number;
-    /** Vault fee as a decimal (e.g., 0.05 = 5%). */
+    /** @deprecated use {@link FeeInfo.performance} via fee */
     readonly vaultFee: number;
-    /** Reward tokens distributed by this vault. */
-    readonly rewards: readonly VaultRewardInfo[];
-    /** Collateral markets backing this vault. */
-    readonly collateral: readonly CollateralInfo[];
-    /** Total value deposited in base-unit amount form. */
+    /** @deprecated use {@link LiquidityProfile.totalDeposits} via liquidityProfile */
     readonly totalDeposits: Amount;
-    /** Available liquidity in the vault. */
+    /** @deprecated use {@link LiquidityProfile.available} via liquidityProfile */
     readonly liquidity: Amount;
-    /** Current vault status. */
+    /** @deprecated use {@link LiquidityProfile.status} via liquidityProfile */
     readonly status: 'active' | 'low_liquidity';
-    /** Whether the vault is on Circle's curated Circle-guarded list. */
+    /** @deprecated use {@link RiskSignals.circleSentinel} via riskSignals */
     readonly circleGuarded: boolean;
-    /** Morpho protocol warnings for this vault. */
+    /** @deprecated use {@link RiskSignals.warnings} via riskSignals */
     readonly warnings?: readonly VaultWarning[] | undefined;
-    /** Circle-specific warnings (e.g., unsupported reward protocol). */
+    /** @deprecated use {@link RiskSignals.earnKitWarnings} via riskSignals */
     readonly earnKitWarnings?: readonly string[] | undefined;
 }
+/**
+ * A yield-bearing vault opportunity (`productType: 'vault'`).
+ *
+ * Carries the universal {@link EarnOpportunityBase} facets plus the
+ * vault-specific `collateral` markets.
+ *
+ * @example
+ * ```typescript
+ * const vault: VaultOpportunity = {
+ *   productType: 'vault',
+ *   address: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *   chain: 'Arc_Testnet',
+ *   name: 'Steakhouse USDC',
+ *   protocol: 'MORPHO',
+ *   asset: 'USDC',
+ *   assetAddress: '0x3600000000000000000000000000000000000000',
+ *   asOf: '2026-06-23T18:00:00Z',
+ *   manager: { name: 'Steakhouse', address: '0x...', type: 'curator' },
+ *   apyProfile: { current: 0.085, native: 0.071, d7: 0.082, d30: 0.079, d90: 0.081, rewardShare: 0.16 },
+ *   fee: { performance: 0.1, management: null },
+ *   liquidityProfile: {
+ *     totalDeposits: Amount.fromJSON({ raw: '15000000000000', decimals: 6 }),
+ *     available: Amount.fromJSON({ raw: '5000000000000', decimals: 6 }),
+ *     totalSupply: Amount.fromJSON({ raw: '14950000000000000000', decimals: 18 }),
+ *     status: 'active',
+ *   },
+ *   riskSignals: { circleSentinel: true, warnings: [], earnKitWarnings: [] },
+ *   rewards: [{ token: 'MORPHO', tokenAddress: '0x...', apy: 0.0075 }],
+ *   collateral: [{ asset: 'cbBTC', assetAddress: '0x...', lltv: 0.86, supplyUsd: 50000000.25, allocationPct: 0.6 }],
+ *   // deprecated flat aliases (dual-emitted during migration)
+ *   vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
+ *   currentApy: 0.085,
+ *   nativeApy: 0.071,
+ *   vaultFee: 0.1,
+ *   totalDeposits: Amount.fromJSON({ raw: '15000000000000', decimals: 6 }),
+ *   liquidity: Amount.fromJSON({ raw: '5000000000000', decimals: 6 }),
+ *   status: 'active',
+ *   circleGuarded: true,
+ * }
+ * ```
+ */
+interface VaultOpportunity extends EarnOpportunityBase {
+    /**
+     * Universal discriminator identifying the opportunity shape.
+     *
+     * Optional for now — a backend that predates the field omits it, matching
+     * the other optional facets — so this release stays source-compatible for
+     * code that constructs the type. A future release makes it required once
+     * every backend emits it. Always present on responses from an emitting
+     * backend; narrow on it before reading product-specific fields.
+     */
+    readonly productType?: 'vault';
+    /** Collateral markets backing this vault. */
+    readonly collateral: readonly CollateralInfo[];
+}
+/**
+ * A yield opportunity available through the earn service.
+ *
+ * Modeled as a discriminated union on `productType` over a shared base.
+ * Only the `vault` variant ships today; additional product types (e.g.
+ * `lending_market`, `rwa_token`) are added as additive union members.
+ */
+type EarnOpportunity = VaultOpportunity;
 /**
  * Per-vault error from a batch vault lookup.
  *
@@ -15526,10 +16350,11 @@ interface AssetAmount {
     /**
      * 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).
+     * 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'`), and for withdrawal quotes this can identify Circle fees
+     * (e.g. `'circle'`). Omitted when the amount has no meaningful
+     * category (plain deposit/withdrawal/share/reward amounts).
      */
     readonly type?: string | undefined;
     /**
@@ -15539,6 +16364,14 @@ interface AssetAmount {
      */
     readonly status?: string | undefined;
 }
+/**
+ * Source-fee quote expiry metadata returned by bridge prepare.
+ *
+ * `TIMESTAMP` expiries use an ISO-8601 UTC `expiresAt`; `BLOCK_NUMBER`
+ * expiries use a source-chain `expiresAtBlock`, with an optional ISO-8601 UTC
+ * `blockEstimatedAt` for when that block estimate was produced.
+ */
+type EarnBridgeQuoteExpiry = Readonly<Exclude<z.infer<typeof bridgeQuoteExpirySchema>, undefined>>;
 /**
  * Result of a deposit operation returned by
  * {@link EarningProvider.deposit}.
@@ -15639,6 +16472,13 @@ interface EarnCrossChainDepositResult {
      * @example '2026-05-19T00:00:00Z'
      */
     readonly expiresAt: string;
+    /** ISO-8601 UTC timestamp at which the source-fee quote was issued. */
+    readonly quoteIssuedAt?: string | undefined;
+    /**
+     * Optional source-fee quote expiry metadata for display and refresh UX.
+     * This deadline is independent of the prepared-bundle `expiresAt` above.
+     */
+    readonly quoteExpiry?: EarnBridgeQuoteExpiry | undefined;
 }
 /**
  * Status of one hop (source relay or destination mint) of a cross-chain
@@ -16115,27 +16955,21 @@ interface DepositQuoteInfo {
      */
     readonly fees: readonly AssetAmount[];
     /**
-     * Estimated native gas fees for the transactions needed to deposit
-     * (e.g. token approval and the deposit itself).
+     * 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.
+     * populates this from the server-side estimate returned on the quote, with
+     * one entry per action. Empty for cross-chain quotes, which resolve no
+     * single source chain.
+     *
+     * Each entry is the Earn Service's estimate for that action, so a pending
+     * token approval no longer causes the deposit entry to fail. An entry may
+     * still carry `fees: null` with an `error` when the service could not
+     * estimate it, so a non-empty array does not imply every estimate
+     * succeeded — inspect each entry's `fees` and look entries up by `name`,
+     * not by index.
      */
     readonly gasFees?: readonly EarnGasFeeEstimate$1[] | undefined;
 }
@@ -16168,29 +17002,29 @@ interface WithdrawalQuoteInfo {
      * available balance and quoted withdrawal in a single round-trip.
      */
     readonly maxWithdrawable: AssetAmount;
-    /** Fees applied to the withdrawal. */
+    /**
+     * Fees applied to the withdrawal.
+     *
+     * Circle fees are returned with `type: 'circle'` so callers can distinguish
+     * them from untyped plain fees and native gas estimates.
+     */
     readonly fees: readonly AssetAmount[];
     /**
-     * Estimated native gas fees for the transactions needed to withdraw.
+     * Estimated native gas fees for the transactions needed to withdraw (e.g.
+     * vault-share approval and the withdrawal 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 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.
+     * populates this from the server-side estimate returned on the quote, with
+     * one entry per action. Empty for cross-chain quotes, which resolve no
+     * single source chain.
+     *
+     * Each entry is the Earn Service's estimate for that action, so a pending
+     * vault-share approval no longer causes the withdrawal entry to fail. An
+     * entry may still carry `fees: null` with an `error` when the service could
+     * not estimate it, so a non-empty array does not imply every estimate
+     * succeeded — inspect each entry's `fees` and look entries up by `name`,
+     * not by index.
      */
     readonly gasFees?: readonly EarnGasFeeEstimate$1[] | undefined;
     /**
@@ -16223,16 +17057,13 @@ 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.
+     * Estimated native gas fees for claiming rewards.
      *
      * 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.
+     * required to produce gas estimates. The bundled Earn Service provider does
+     * not return a gas estimate for claim-rewards quotes, so this is always
+     * empty (`[]`); it is retained for API symmetry with the deposit and
+     * withdrawal quotes.
      */
     readonly gasFees?: readonly EarnGasFeeEstimate$1[] | undefined;
 }
@@ -16243,8 +17074,8 @@ interface ClaimRewardsQuoteInfo {
  * `vaults` while per-vault failures are in `errors`.
  */
 interface GetVaultsResult {
-    /** Successfully resolved vault information. */
-    readonly vaults: readonly VaultInfo[];
+    /** Successfully resolved opportunities. */
+    readonly vaults: readonly EarnOpportunity[];
     /** Per-vault errors for failed lookups. */
     readonly errors: readonly VaultError[];
 }
@@ -16297,7 +17128,7 @@ interface ExploreVaultsPagination {
  */
 interface ExploreVaultsResult {
     /** Vaults matching the query, in the requested sort order. */
-    readonly vaults: readonly VaultInfo[];
+    readonly vaults: readonly EarnOpportunity[];
     /** Pagination metadata for the query. */
     readonly pagination: ExploreVaultsPagination;
 }
@@ -16953,10 +17784,6 @@ declare class EarnServiceProvider implements EarningProvider {
     supportsRetry(error: unknown): boolean;
     /** {@inheritdoc} */
     retry(error: unknown): Promise<EarnDepositOutcome | EarnWithdrawResult | ClaimRewardsResult>;
-    private gasEstimateFailure;
-    private estimateDepositQuoteGasFees;
-    private estimateWithdrawalQuoteGasFees;
-    private estimateClaimRewardsQuoteGasFees;
     /** {@inheritdoc} */
     getDepositQuote<T extends AdapterCapabilities>(params: GetDepositQuoteServiceParams<T>): Promise<DepositQuoteInfo>;
     /** {@inheritdoc} */
@@ -17547,12 +18374,42 @@ type EarnAssetAmount = Omit<AssetAmount, 'amount'> & {
     /** Token amount in human-readable decimal format. */
     readonly amount: string;
 };
-/** Vault information returned by the SDK. */
-type EarnVaultInfo = Omit<VaultInfo, 'totalDeposits' | 'liquidity'> & {
+/**
+ * Distributive `Omit` over a union.
+ *
+ * A plain `Omit<Union, K>` is not distributive: `keyof (A | B)` collapses to
+ * the shared keys, dropping every variant-specific field and the discriminant
+ * narrowing. Distributing over each member preserves the union.
+ */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** Liquidity profile returned by the SDK with amounts as decimal strings. */
+type EarnLiquidityProfile = Omit<LiquidityProfile, 'totalDeposits' | 'available' | 'totalSupply'> & {
+    /** Total value deposited in human-readable decimal format. */
+    readonly totalDeposits: string;
+    /** Available liquidity in human-readable decimal format. */
+    readonly available: string;
+    /** Outstanding vault share tokens (ERC4626 totalSupply) in decimal format. */
+    readonly totalSupply: string;
+};
+/**
+ * Vault information returned by the SDK.
+ *
+ * Derived with a distributive `Omit` so each opportunity variant keeps its
+ * product-specific fields and the `productType` discriminant.
+ */
+type EarnVaultInfo = DistributiveOmit<EarnOpportunity, 'totalDeposits' | 'liquidity' | 'liquidityProfile'> & {
     /** Total value deposited in human-readable decimal format. */
     readonly totalDeposits: string;
     /** Available liquidity in the vault in human-readable decimal format. */
     readonly liquidity: string;
+    /**
+     * Liquidity profile with amounts as human-readable decimal strings.
+     *
+     * Optional during the expand/contract migration window: a backend that
+     * predates the nested facets omits it, so it is absent until the response
+     * carries it.
+     */
+    readonly liquidityProfile?: EarnLiquidityProfile;
 };
 /** Result of a batch vault lookup. */
 type EarnGetVaultsResult = Omit<GetVaultsResult, 'vaults'> & {
@@ -18755,22 +19612,27 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1: z.ZodOptional<z.ZodObject<{
                         wallet: z.ZodString;
                         minter: z.ZodString;
+                        depositForHandler: z.ZodOptional<z.ZodString>;
                     }, "strict", z.ZodTypeAny, {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     }, {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     }>>;
                 }, "strict", z.ZodTypeAny, {
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 }, {
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 }>;
                 forwarderSupported: z.ZodObject<{
@@ -18789,6 +19651,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -18801,6 +19664,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -18839,6 +19703,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -18874,6 +19739,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -18921,22 +19787,27 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1: z.ZodOptional<z.ZodObject<{
                         wallet: z.ZodString;
                         minter: z.ZodString;
+                        depositForHandler: z.ZodOptional<z.ZodString>;
                     }, "strict", z.ZodTypeAny, {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     }, {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     }>>;
                 }, "strict", z.ZodTypeAny, {
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 }, {
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 }>;
                 forwarderSupported: z.ZodObject<{
@@ -18955,6 +19826,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -18967,6 +19839,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19003,6 +19876,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19037,6 +19911,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19072,6 +19947,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19106,6 +19982,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19141,6 +20018,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19175,6 +20053,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19213,6 +20092,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19247,6 +20127,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19285,6 +20166,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19319,6 +20201,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19366,6 +20249,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19400,6 +20284,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19443,6 +20328,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19477,6 +20363,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -19546,22 +20433,27 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1: z.ZodOptional<z.ZodObject<{
                     wallet: z.ZodString;
                     minter: z.ZodString;
+                    depositForHandler: z.ZodOptional<z.ZodString>;
                 }, "strict", z.ZodTypeAny, {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 }, {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 }>>;
             }, "strict", z.ZodTypeAny, {
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             }, {
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             }>;
             forwarderSupported: z.ZodObject<{
@@ -19580,6 +20472,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19592,6 +20485,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19630,6 +20524,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19665,6 +20560,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19712,22 +20608,27 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1: z.ZodOptional<z.ZodObject<{
                     wallet: z.ZodString;
                     minter: z.ZodString;
+                    depositForHandler: z.ZodOptional<z.ZodString>;
                 }, "strict", z.ZodTypeAny, {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 }, {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 }>>;
             }, "strict", z.ZodTypeAny, {
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             }, {
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             }>;
             forwarderSupported: z.ZodObject<{
@@ -19746,6 +20647,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19758,6 +20660,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19794,6 +20697,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19828,6 +20732,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19863,6 +20768,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19897,6 +20803,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19932,6 +20839,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -19966,6 +20874,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20017,6 +20926,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20051,6 +20961,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20098,6 +21009,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20132,6 +21044,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20208,22 +21121,27 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1: z.ZodOptional<z.ZodObject<{
                     wallet: z.ZodString;
                     minter: z.ZodString;
+                    depositForHandler: z.ZodOptional<z.ZodString>;
                 }, "strict", z.ZodTypeAny, {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 }, {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 }>>;
             }, "strict", z.ZodTypeAny, {
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             }, {
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             }>;
             forwarderSupported: z.ZodObject<{
@@ -20242,6 +21160,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20254,6 +21173,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20292,6 +21212,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20327,6 +21248,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20374,22 +21296,27 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1: z.ZodOptional<z.ZodObject<{
                     wallet: z.ZodString;
                     minter: z.ZodString;
+                    depositForHandler: z.ZodOptional<z.ZodString>;
                 }, "strict", z.ZodTypeAny, {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 }, {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 }>>;
             }, "strict", z.ZodTypeAny, {
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             }, {
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             }>;
             forwarderSupported: z.ZodObject<{
@@ -20408,6 +21335,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20420,6 +21348,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20456,6 +21385,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20490,6 +21420,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20525,6 +21456,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20559,6 +21491,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20594,6 +21527,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20628,6 +21562,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20679,6 +21614,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20713,6 +21649,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20759,6 +21696,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20793,6 +21731,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
                 v1?: {
                     wallet: string;
                     minter: string;
+                    depositForHandler?: string | undefined;
                 } | undefined;
             };
             forwarderSupported: {
@@ -20914,22 +21853,27 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1: z.ZodOptional<z.ZodObject<{
                         wallet: z.ZodString;
                         minter: z.ZodString;
+                        depositForHandler: z.ZodOptional<z.ZodString>;
                     }, "strict", z.ZodTypeAny, {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     }, {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     }>>;
                 }, "strict", z.ZodTypeAny, {
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 }, {
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 }>;
                 forwarderSupported: z.ZodObject<{
@@ -20948,6 +21892,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -20960,6 +21905,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -20998,6 +21944,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21033,6 +21980,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21080,22 +22028,27 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1: z.ZodOptional<z.ZodObject<{
                         wallet: z.ZodString;
                         minter: z.ZodString;
+                        depositForHandler: z.ZodOptional<z.ZodString>;
                     }, "strict", z.ZodTypeAny, {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     }, {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     }>>;
                 }, "strict", z.ZodTypeAny, {
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 }, {
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 }>;
                 forwarderSupported: z.ZodObject<{
@@ -21114,6 +22067,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21126,6 +22080,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21162,6 +22117,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21196,6 +22152,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21231,6 +22188,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21265,6 +22223,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21300,6 +22259,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21334,6 +22294,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21372,6 +22333,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21406,6 +22368,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21444,6 +22407,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21478,6 +22442,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21530,6 +22495,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21564,6 +22530,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21612,6 +22579,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -21646,6 +22614,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
                     v1?: {
                         wallet: string;
                         minter: string;
+                        depositForHandler?: string | undefined;
                     } | undefined;
                 };
                 forwarderSupported: {
@@ -23609,14 +24578,17 @@ type TokenAddress = string & {
 /**
  * Known token aliases supported by AppKit.
  *
- * These aliases map to chain-specific token addresses and have dedicated
- * transfer actions in the adapter layer.
+ * These aliases map to chain-specific token addresses. `USDC`, `USDT`, and
+ * `NATIVE` have dedicated transfer actions in the adapter layer. `EURC` has no
+ * dedicated action — it resolves to the chain's `eurcAddress` and is sent via
+ * the generic token transfer action, so it is only supported on chains where
+ * `eurcAddress` is set.
  *
  * @remarks
  * For swap operations, see {@link SupportedToken} in SwapKit which supports
- * additional tokens (EURC, DAI, USDE, PYUSD).
+ * additional tokens (DAI, USDE, PYUSD).
  */
-type TokenAlias = 'USDC' | 'USDT' | 'NATIVE';
+type TokenAlias = 'USDC' | 'USDT' | 'NATIVE' | 'EURC';
 /**
  * Operation types that support the `getFee`/`getFeeRecipient` hooks.
  */
@@ -23745,26 +24717,28 @@ interface AppKitContext {
      * Event handlers registered for AppKit operations.
      *
      * This property stores event handlers that are registered via the AppKit's
-     * `on()` method. Handlers are grouped by operation type. The current runtime
-     * bucket is `bridge`, and the context can add more operation buckets as AppKit
-     * wires action handlers for additional kits.
+     * `on()` method. Handlers are grouped by operation type. The runtime buckets
+     * are `bridge` and `earn`; the context can add more operation buckets as
+     * AppKit wires action handlers for additional kits.
      *
-     * Within each operation bucket, handlers are keyed by action name (for example,
-     * `bridge.approve`) or `*` for wildcard handlers. Each action can have multiple
-     * handlers registered, allowing multiple subscribers to listen to the same event.
+     * Within each operation bucket, handlers are keyed by action name (for
+     * example, `bridge.approve` or `earn.deposit`) or `*` for wildcard handlers.
+     * Each action can have multiple handlers registered, allowing multiple
+     * subscribers to listen to the same event.
      *
      * The handlers are stored in the context to allow deferred registration with
-     * underlying operation kits, enabling a clean separation between event registration
-     * and operation execution.
+     * underlying operation kits, enabling a clean separation between event
+     * registration and operation execution.
      *
      * @example
      * ```typescript
      * const context = createContext()
      * // Handlers registered via kit.on() are stored by operation type
-     * // Bridge handlers are registered with BridgeKit when bridge() is executed
+     * // Bridge handlers are registered with BridgeKit when bridge() runs
+     * // Earn handlers are registered with EarnKit when earn operations run
      * ```
      */
-    actions: Record<'bridge', Record<string, ((payload: unknown) => void)[]>>;
+    actions: Record<'bridge' | 'earn', Record<string, ((payload: unknown) => void)[]>>;
     /**
      * Disable error telemetry for all sub-kits.
      *
@@ -23775,11 +24749,22 @@ interface AppKitContext {
      * @defaultValue false
      */
     disableErrorReporting?: boolean;
+    /**
+     * Custom HTTP headers forwarded with the underlying CCTP provider's
+     * attestation (Iris) API requests made by bridge operations.
+     *
+     * @remarks
+     * Headers are merged on top of the SDK defaults (such as `Content-Type`)
+     * rather than replacing them. The header is forwarded as-is to Circle's API;
+     * the SDK does not interpret it.
+     */
+    headers?: Record<string, string>;
 }
 /**
  * Earn operation namespace exposed as `kit.earn`.
  *
  * Mirrors the operations currently available from `@circle-fin/earn-kit`.
+ * Step events use the AppKit event API (`kit.on('earn.*')` / `kit.on('*')`).
  *
  * @example
  * ```typescript
@@ -24027,6 +25012,40 @@ interface AppKitEarnOperations {
      * @internal
      */
     getClaimRewardsQuote<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(params: GetClaimRewardsQuoteParams<TFromAdapterCapabilities>): Promise<EarnClaimRewardsQuoteInfo>;
+    /**
+     * Resume a multi-phase earn operation that previously failed.
+     *
+     * Pass the {@link KitError} caught from `deposit`, `withdraw`, or
+     * `claimRewards`. The error carries the original inputs and step
+     * progress, so completed phases (for example a successful token
+     * approval) can be skipped. Call `isRetryableError(error)` first.
+     *
+     * @remarks
+     * Retry re-fetches execution params and may re-submit the execute
+     * transaction. Treat this as best-effort recovery: if a prior attempt
+     * broadcast execute but failed before observing the receipt, that
+     * transaction may still be in flight.
+     *
+     * @param error - The error caught from a previous multi-phase earn operation
+     * @returns Promise resolving to the result of the resumed operation
+     * @throws If the error is not retryable or lacks earn retry context
+     *
+     * @example
+     * ```typescript
+     * import { AppKit, isRetryableError } from '@circle-fin/app-kit'
+     *
+     * const kit = new AppKit()
+     *
+     * try {
+     *   await kit.earn.deposit(params)
+     * } catch (error) {
+     *   if (isRetryableError(error)) {
+     *     const result = await kit.earn.retry(error)
+     *   }
+     * }
+     * ```
+     */
+    retry(error: unknown): Promise<EarnDepositOutcome | EarnWithdrawResult | EarnClaimRewardsResult>;
 }
 /**
  * Type for event handler functions that can be registered with the AppKit.
@@ -24073,7 +25092,7 @@ type ActionHandler<T extends {
  * When `to` is a `string`, the address must be a valid address. When `to` is an
  * {@link Adapter}, the recipient is derived from the adapter's active account.
  *
- * The `token` field accepts both supported token aliases ('USDC', 'USDT', 'NATIVE') and custom token
+ * The `token` field accepts both supported token aliases ('USDC', 'USDT', 'NATIVE', 'EURC') and custom token
  * contract addresses.
  *
  * @example
@@ -24113,7 +25132,8 @@ interface SendParams {
      * If omitted, the provider will use 'USDC' by default.
      *
      * Supports both known aliases and custom token contract addresses:
-     * - Known aliases: 'USDC', 'USDT', 'NATIVE'
+     * - Known aliases: 'USDC', 'USDT', 'NATIVE', 'EURC' ('EURC' requires the
+     *   chain to have an `eurcAddress` configured)
      * - Custom token addresses: EVM addresses or Solana SPL token mint addresses
      *
      * @example
@@ -24173,21 +25193,31 @@ type AppKitBridgeActions = PrefixActions<'bridge', DefaultBridgeKitActions>;
  * to namespace them within the AppKit event system.
  */
 type AppKitUnifiedBalanceActions = PrefixActions<'unifiedBalance', GatewayV1Actions>;
+/**
+ * Prefixed earn actions for AppKit.
+ *
+ * Earn step events are exposed under the `earn.` namespace (for example
+ * `earn.deposit`, `earn.approve`, `earn.withdraw`) so they can be
+ * subscribed to via `kit.on()` alongside bridge and unified balance
+ * events.
+ */
+type AppKitEarnActions = PrefixActions<'earn', EarnActions>;
 /**
  * Union of all AppKit action names.
  */
-type AppKitActionName = keyof AppKitBridgeActions | keyof AppKitUnifiedBalanceActions;
+type AppKitActionName = keyof AppKitBridgeActions | keyof AppKitUnifiedBalanceActions | keyof AppKitEarnActions;
 /**
  * All actions available in AppKit.
  */
-type AppKitActions = AppKitBridgeActions & AppKitUnifiedBalanceActions;
+type AppKitActions = AppKitBridgeActions & AppKitUnifiedBalanceActions & AppKitEarnActions;
 
 /**
  * Parameters for creating a AppKit context.
  *
  * This type allows partial customization of the context while ensuring
  * that all required properties have sensible defaults. Users can override
- * specific methods while keeping the rest intact.
+ * specific methods while keeping the rest intact. Action handler buckets
+ * may also be supplied partially; missing buckets default to empty maps.
  *
  * @example
  * ```typescript
@@ -24199,7 +25229,9 @@ type AppKitActions = AppKitBridgeActions & AppKitUnifiedBalanceActions;
  * })
  * ```
  */
-type CreateContextParams = Partial<AppKitContext>;
+type CreateContextParams = Omit<Partial<AppKitContext>, 'actions'> & {
+    actions?: Partial<AppKitContext['actions']>;
+};
 
 /**
  * Destination for a Gateway spend (mint) operation.
@@ -24577,10 +25609,13 @@ interface ResolvedSpendParams<TFromAdapterCapabilities extends AdapterCapabiliti
  */
 type SpendFeeFunction = (params: ResolvedSpendParams) => Promise<string> | string;
 /**
- * Function that resolves the fee recipient address for a given source chain.
- * Called once per source chain in a multi-chain spend.
+ * Function that resolves the fee recipient address for a spend.
+ * Called once per spend, against the resolved **destination** chain —
+ * every fee burn intent in a spend mints to that single chain
+ * regardless of which source chain(s) funded it, so only one
+ * recipient address (valid on the destination chain) is ever needed.
  */
-type SpendFeeRecipientFunction = (feePayoutChain: ChainDefinition, params: ResolvedSpendParams) => Promise<string> | string;
+type SpendFeeRecipientFunction = (destinationChain: ChainDefinition, params: ResolvedSpendParams) => Promise<string> | string;
 /**
  * Policy for computing and routing custom developer fees.
  *
@@ -24590,11 +25625,54 @@ type SpendFeeRecipientFunction = (feePayoutChain: ChainDefinition, params: Resol
  * Fields that only exist after resolution (e.g. per-source allocations)
  * may be `undefined`.  Implementations should only rely on top-level
  * fields such as `to`, `token`, and `amount`.
+ *
+ * @remarks
+ * `resolveFeeRecipientAddress` is optional when you configure
+ * {@link UnifiedBalanceKit.setFeeRecipients} instead — the declarative
+ * map takes priority over this callback when both are present. Provide
+ * exactly one of the two; a policy with neither throws at spend time.
  */
 interface CustomFeePolicy {
     computeFee: SpendFeeFunction;
-    resolveFeeRecipientAddress: SpendFeeRecipientFunction;
+    resolveFeeRecipientAddress?: SpendFeeRecipientFunction;
 }
+/**
+ * Chain type group used to key {@link FeeRecipientsConfig}.
+ *
+ * @remarks
+ * Only `'evm'` and `'solana'` are live today (the only chain types the
+ * kit's provider currently supports). This is deliberately a narrow
+ * subset of `@core/chains`' broader `ChainType` union rather than a
+ * hardcoded two-field struct, so that support for additional non-EVM
+ * chain types (e.g. Stellar, Starknet) can be added later by adding
+ * new union members here — no restructuring of `FeeRecipientsConfig`
+ * or its consumers required.
+ */
+type FeeRecipientChainType = 'evm' | 'solana';
+/**
+ * Declarative map of fee recipient addresses, keyed by chain type.
+ *
+ * @remarks
+ * Set via {@link UnifiedBalanceKit.setFeeRecipients}. At spend time the
+ * kit resolves the spend's destination chain to its
+ * {@link FeeRecipientChainType} and looks up the matching entry —
+ * exactly one recipient is used per spend (see
+ * {@link SpendFeeRecipientFunction}). Provide entries for every chain
+ * type you expect to spend to; a spend to a destination chain type
+ * with no matching entry throws before any fee collection is
+ * attempted.
+ *
+ * @example
+ * ```typescript
+ * import type { FeeRecipientsConfig } from '@circle-fin/unified-balance-kit'
+ *
+ * const feeRecipients: FeeRecipientsConfig = {
+ *   evm: '0x1234567890123456789012345678901234567890',
+ *   solana: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+ * }
+ * ```
+ */
+type FeeRecipientsConfig = Partial<Record<FeeRecipientChainType, string>>;
 /**
  * Fee category describing the origin of a fee line item.
  *
@@ -25908,6 +26986,43 @@ declare class AppKitUnifiedBalance {
      * ```
      */
     removeCustomFeePolicy(): void;
+    /**
+     * Set a declarative fee recipient map, keyed by chain type.
+     *
+     * Once set, `spend()`/`estimateSpend()` resolve the fee recipient by
+     * looking up the spend's destination chain type in this map — taking
+     * priority over `customFeePolicy`'s `resolveFeeRecipientAddress`
+     * callback.
+     *
+     * @remarks
+     * This only controls which address a fee is sent to — it does not by
+     * itself cause any fee to be charged. You still need
+     * `setCustomFeePolicy`'s `computeFee` to determine the fee amount;
+     * calling `setFeeRecipients` without ever calling `setCustomFeePolicy`
+     * throws at spend time (there is no `computeFee` to determine an
+     * amount).
+     *
+     * @param config - Fee recipient addresses keyed by chain type (e.g.
+     *   `{ evm: '0x...', solana: 'Sol...' }`).
+     *
+     * @example
+     * ```typescript
+     * kit.unifiedBalance.setFeeRecipients({
+     *   evm: '0x1234567890123456789012345678901234567890',
+     *   solana: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+     * })
+     * ```
+     */
+    setFeeRecipients(config: FeeRecipientsConfig): void;
+    /**
+     * Remove the declarative fee recipient map.
+     *
+     * @example
+     * ```typescript
+     * kit.unifiedBalance.removeFeeRecipients()
+     * ```
+     */
+    removeFeeRecipients(): void;
 }
 
 interface DeveloperFeeHooks {
@@ -26306,7 +27421,8 @@ declare class AppKit {
      * or `'NOT_FOUND'`). Use {@link AppKit.waitForSwap} if you'd rather
      * not write the polling loop yourself.
      *
-     * @param params - `txHash`, `chainIn`, optional `chainOut`, and `kitKey`.
+     * @param params - `txHash` and `chainIn`, plus optional `chainOut` and
+     *   `kitKey`.
      * @returns A snapshot of the swap's status at the time of the call.
      * @throws \{KitError\} If `chainIn` or `chainOut` is malformed.
      *
@@ -26418,7 +27534,7 @@ declare class AppKit {
      * translates to the chain's native sentinel address — `0xEee…` for EVM,
      * `1111…` for Solana — before querying the service.
      *
-     * @param params - `chain`, optional `tokens`, and `kitKey`.
+     * @param params - `chain`, plus optional `tokens` and `kitKey`.
      * @returns A nested map of `[chain][address] → { priceUSD, fetchedAt }`.
      * @throws \{KitError\} If `chain` is malformed, `tokens` exceeds 100
      *         entries, or any entry is neither a registered symbol nor a
@@ -26472,17 +27588,16 @@ declare class AppKit {
     /**
      * Register an event handler for a specific AppKit action.
      *
-     * Subscribe to events emitted during bridge or unified balance operations.
-     * Bridge events are prefixed with 'bridge.' and unified balance events
-     * with 'unifiedBalance.' to namespace them within the AppKit event system.
+     * Subscribe to step events from bridge, earn, or unified balance
+     * operations. Action names are namespaced: `bridge.*`, `earn.*`, and
+     * `unifiedBalance.*`. Use `'*'` to receive every action.
      *
-     * Handlers receive strongly-typed payloads based on the action name. Multiple
-     * handlers can be registered for the same action, and all will be invoked when
-     * the action occurs. Use the wildcard '*' to listen to all actions.
+     * Handlers receive strongly-typed payloads for the chosen action.
+     * Multiple handlers may be registered for the same action.
      *
      * @typeParam K - The action name to listen for
      * @param action - The namespaced action name or '*' for all actions
-     * @param handler - Callback function to invoke when the action occurs
+     * @param handler - Callback invoked when the action occurs
      *
      * @example
      * ```typescript
@@ -26495,6 +27610,11 @@ declare class AppKit {
      *   console.log('Approval transaction:', payload.values.txHash)
      * })
      *
+     * // Listen to earn deposit steps
+     * kit.on('earn.deposit', (payload) => {
+     *   console.log('Earn deposit step:', payload.values.state)
+     * })
+     *
      * // Listen to unified balance action
      * kit.on('unifiedBalance.gateway.spend.succeeded', (payload) => {
      *   console.log('Spend succeeded:', payload.data)
@@ -26539,6 +27659,16 @@ declare class AppKit {
      */
     off<K extends AppKitActionName>(action: K, handler: (payload: AppKitActions[K]) => void): void;
     off(action: '*', handler: (payload: AppKitActions[keyof AppKitActions]) => void): void;
+    /**
+     * Remove one handler from a deferred AppKit action bucket.
+     *
+     * Deletes the action key when its handler list becomes empty.
+     *
+     * @param handlers - Action bucket to update (`bridge` or `earn`)
+     * @param action - Stored action key, including namespace or `*`
+     * @param handler - Handler reference previously passed to {@link on}
+     */
+    private removeStoredActionHandler;
 }
 
 /**
@@ -26551,7 +27681,11 @@ declare class AppKit {
  * The type annotation `readonly TokenAlias[]` ensures this array stays in sync
  * with the TokenAlias type definition - TypeScript will enforce any changes.
  *
- * For swap operations, additional tokens (EURC, DAI, USDE, PYUSD) are supported
+ * `USDC`, `USDT`, and `NATIVE` map to dedicated adapter transfer actions.
+ * `EURC` has no dedicated action — it resolves to the chain's `eurcAddress`
+ * and uses the generic token transfer action (see {@link prepareSend}).
+ *
+ * For swap operations, additional tokens (DAI, USDE, PYUSD) are supported
  * via SwapKit's SupportedToken type.
  */
 declare const TOKEN_ALIASES: readonly TokenAlias[];
@@ -26562,7 +27696,7 @@ declare const TOKEN_ALIASES: readonly TokenAlias[];
  * or neither.
  */
 interface TokenValidationResult {
-    /** True if the token is a known alias (USDC, USDT, NATIVE) */
+    /** True if the token is a known alias (USDC, USDT, NATIVE, EURC) */
     isAlias: boolean;
     /** True if the token is a valid address for the chain */
     isAddress: boolean;
@@ -26593,7 +27727,7 @@ declare function isTokenAlias(token: string): token is TokenAlias;
  * Type guard to check if a string is a valid token address for a chain.
  *
  * This function verifies that a token string is:
- * 1. Not a known alias ('USDC', 'USDT', 'NATIVE')
+ * 1. Not a known alias ('USDC', 'USDT', 'NATIVE', 'EURC')
  * 2. A valid address format for the specified chain
  *
  * Use this to narrow the type to `TokenAddress` in TypeScript.
@@ -26622,7 +27756,7 @@ declare function isTokenAddress(token: string, chain: ChainDefinition): token is
  * Validate and classify a token identifier.
  *
  * This function determines whether a token string is:
- * 1. A known alias ('USDC', 'USDT', or 'NATIVE')
+ * 1. A known alias ('USDC', 'USDT', 'NATIVE', or 'EURC')
  * 2. A valid token address for the given chain
  * 3. An invalid/unrecognized token identifier
  *
@@ -26654,4 +27788,4 @@ declare function isTokenAddress(token: string, chain: ChainDefinition): token is
 declare function validateToken(token: string, chain: ChainDefinition): TokenValidationResult;
 
 export { AppKit, AppKitUnifiedBalance, BalanceError, Blockchain, BridgeChain, EarnChain, EarnError, EarnKit, InputError, KitError, NetworkError, OnchainError, RateLimitError, RpcError, ServiceError, SwapChain, TOKEN_ALIASES, TransferSpeed, UnifiedBalanceChain, anyDepositParamsSchema, claimRewardsParamsSchema, createEarnKitContext, depositParamsSchema, claimRewards as earnClaimRewards, deposit as earnDeposit, exploreVaults as earnExploreVaults, exploreVaultsIterator as earnExploreVaultsIterator, getClaimRewardsQuote as earnGetClaimRewardsQuote, getCrossChainDepositStatus as earnGetCrossChainDepositStatus, getCrossChainDepositStatusOutcome as earnGetCrossChainDepositStatusOutcome, getDepositQuote as earnGetDepositQuote, getPosition as earnGetPosition, getSupportedChains as earnGetSupportedChains, getVaults as earnGetVaults, getWithdrawalQuote as earnGetWithdrawalQuote, waitForCrossChainDeposit as earnWaitForCrossChainDeposit, withdraw as earnWithdraw, exploreVaultsIteratorParamsSchema, exploreVaultsParamsSchema, getClaimRewardsQuoteParamsSchema, getCrossChainDepositStatusParamsSchema, getDepositQuoteParamsSchema, getErrorCode, getErrorMessage, getPositionParamsSchema, getTokenDecimals, getVaultsParamsSchema, getWithdrawalQuoteParamsSchema, isBalanceError, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRateLimitError, isRetryableError, isRpcError, isServiceError, isTerminalCrossChainDepositStatus as isTerminalEarnCrossChainDepositStatus, isTokenAddress, isTokenAlias, isUserCancellationError, setExternalPrefix, validateToken, waitForCrossChainDepositParamsSchema, withdrawParamsSchema };
-export type { ActionHandler, AdapterContext, AllowanceStrategy$2 as AllowanceStrategy, AppKitActionName, AppKitActions, AppKitBridgeActions, AppKitConfig, AppKitContext, AppKitEarnOperations, AppKitUnifiedBalanceActions, BaseChainDefinition, BridgeConfig, CustomFeePolicy$2 as BridgeCustomFeePolicy, BridgeParams, BridgeResult, BridgeStep, CCTPConfig, CCTPMergedConfig, CCTPSplitConfig, ChainDefinition, Currency, DelegateStatus, DepositForParams, DepositParams, DepositResult, DeveloperFeeHooks, EVMChainDefinition, EarnAccruedRewardInfo, EarnAdapterContext, AnyDepositParams as EarnAnyDepositParams, EarnAssetAmount, EarnBridgeCctpStatus, EarnBridgeHopStatus, ClaimRewardsParams as EarnClaimRewardsParams, EarnClaimRewardsQuoteInfo, EarnClaimRewardsResult, EarnClaimedAmount, EarnClaimedRewardsResult, EarnConfig, EarnCrossChainDepositDestination, CrossChainDepositParams as EarnCrossChainDepositParams, EarnCrossChainDepositResult, EarnCrossChainDepositStatus, EarnCrossChainDepositWaitOutcome, EarnCrossChainDepositWaitResult, CrossChainGetDepositQuoteParams as EarnCrossChainGetDepositQuoteParams, EarnDepositOutcome, DepositParams$2 as EarnDepositParams, EarnDepositQuoteInfo, EarnDepositResult, ExploreVaultsIteratorParams as EarnExploreVaultsIteratorParams, ExploreVaultsPagination as EarnExploreVaultsPagination, ExploreVaultsParams as EarnExploreVaultsParams, EarnExploreVaultsResult, ExploreVaultsSortBy as EarnExploreVaultsSortBy, EarnGasFeeEstimate, EarnGasFeeEstimateBase, GetClaimRewardsQuoteParams as EarnGetClaimRewardsQuoteParams, GetCrossChainDepositStatusParams as EarnGetCrossChainDepositStatusParams, GetDepositQuoteParams as EarnGetDepositQuoteParams, GetPositionParams as EarnGetPositionParams, GetVaultsParams as EarnGetVaultsParams, EarnGetVaultsResult, GetWithdrawalQuoteParams as EarnGetWithdrawalQuoteParams, EarnKitConfig, EarnKitContext, EarnOperationParams, EarnPositionInfo, EarnPositionPnLInfo, EarningProvider as EarnProvider, SameChainDepositParams as EarnSameChainDepositParams, EarnSameChainDepositResult, SameChainGetDepositQuoteParams as EarnSameChainGetDepositQuoteParams, EarnServiceConfig, EarnVaultInfo, VaultQuery as EarnVaultQuery, WaitForCrossChainDepositParams as EarnWaitForCrossChainDepositParams, WithdrawParams as EarnWithdrawParams, EarnWithdrawResult, EarnWithdrawalQuoteInfo, ErrorDetails, EstimateResult$1 as EstimateResult, EstimateSpendResult, EstimatedGas, FeeOperationType, GetBalancesParams, GetBalancesResult, GetDelegateStatusParams, GetSupportedChainsOptions, GetSwapStatusParams, GetTokenRatesParams, GetTokenRatesResult, InitiateRemoveFundParams, InitiateRemoveFundResult, KitContractType, NonEVMChainDefinition, OperationParamsMap, OperationType, Recoverability, RemoveFundParams, RemoveFundResult, RetryContext, SendParams, SpendDestination, SpendParams, SpendResult, SwapConfig, CustomFeePolicy$1 as SwapCustomFeePolicy, SwapDestinationLeg, SwapEstimate, SwapFeeContext, SwapKitConfig, SwapKitContext, SwapParams, SwapProgress, SwapResult, SwapSourceLeg, SwapStatus, SwapStatusResult, SwapTerminalStatus, TokenInfo, TokenRate, UnifiedBalanceChainIdentifier, CustomFeePolicy as UnifiedBalanceCustomFeePolicy, UnifiedBalanceKitConfig, SupportedToken as UnifiedBalanceSupportedToken, UpdateDelegateParams, UpdateDelegateResult, VersionConfig, WaitForSwapDiscreteParams, WaitForSwapParams, WaitForSwapResultParams };
+export type { ActionHandler, AdapterContext, AllowanceStrategy$2 as AllowanceStrategy, AppKitActionName, AppKitActions, AppKitBridgeActions, AppKitConfig, AppKitContext, AppKitEarnActions, AppKitEarnOperations, AppKitUnifiedBalanceActions, BaseChainDefinition, BridgeConfig, CustomFeePolicy$2 as BridgeCustomFeePolicy, BridgeParams, BridgeResult, BridgeStep, CCTPConfig, CCTPMergedConfig, CCTPSplitConfig, ChainDefinition, Currency, DelegateStatus, DepositForParams, DepositParams, DepositResult, DeveloperFeeHooks, EVMChainDefinition, EarnAccruedRewardInfo, EarnAdapterContext, AnyDepositParams as EarnAnyDepositParams, EarnAssetAmount, EarnBridgeCctpStatus, EarnBridgeHopStatus, EarnBridgeQuoteExpiry, ClaimRewardsParams as EarnClaimRewardsParams, EarnClaimRewardsQuoteInfo, EarnClaimRewardsResult, EarnClaimedAmount, EarnClaimedRewardsResult, EarnConfig, EarnCrossChainDepositDestination, CrossChainDepositParams as EarnCrossChainDepositParams, EarnCrossChainDepositResult, EarnCrossChainDepositStatus, EarnCrossChainDepositWaitOutcome, EarnCrossChainDepositWaitResult, CrossChainGetDepositQuoteParams as EarnCrossChainGetDepositQuoteParams, EarnDepositOutcome, DepositParams$2 as EarnDepositParams, EarnDepositQuoteInfo, EarnDepositResult, ExploreVaultsIteratorParams as EarnExploreVaultsIteratorParams, ExploreVaultsPagination as EarnExploreVaultsPagination, ExploreVaultsParams as EarnExploreVaultsParams, EarnExploreVaultsResult, ExploreVaultsSortBy as EarnExploreVaultsSortBy, EarnGasFeeEstimate, EarnGasFeeEstimateBase, GetClaimRewardsQuoteParams as EarnGetClaimRewardsQuoteParams, GetCrossChainDepositStatusParams as EarnGetCrossChainDepositStatusParams, GetDepositQuoteParams as EarnGetDepositQuoteParams, GetPositionParams as EarnGetPositionParams, GetVaultsParams as EarnGetVaultsParams, EarnGetVaultsResult, GetWithdrawalQuoteParams as EarnGetWithdrawalQuoteParams, EarnKitConfig, EarnKitContext, EarnOperationParams, EarnPositionInfo, EarnPositionPnLInfo, EarningProvider as EarnProvider, SameChainDepositParams as EarnSameChainDepositParams, EarnSameChainDepositResult, SameChainGetDepositQuoteParams as EarnSameChainGetDepositQuoteParams, EarnServiceConfig, EarnVaultInfo, VaultQuery as EarnVaultQuery, WaitForCrossChainDepositParams as EarnWaitForCrossChainDepositParams, WithdrawParams as EarnWithdrawParams, EarnWithdrawResult, EarnWithdrawalQuoteInfo, ErrorDetails, EstimateResult$1 as EstimateResult, EstimateSpendResult, EstimatedGas, FeeOperationType, GetBalancesParams, GetBalancesResult, GetDelegateStatusParams, GetSupportedChainsOptions, GetSwapStatusParams, GetTokenRatesParams, GetTokenRatesResult, InitiateRemoveFundParams, InitiateRemoveFundResult, KitContractType, NonEVMChainDefinition, OperationParamsMap, OperationType, Recoverability, RemoveFundParams, RemoveFundResult, RetryContext, SendParams, SpendDestination, SpendParams, SpendResult, SwapConfig, CustomFeePolicy$1 as SwapCustomFeePolicy, SwapDestinationLeg, SwapEstimate, SwapFeeContext, SwapKitConfig, SwapKitContext, SwapParams, SwapProgress, SwapResult, SwapSourceLeg, SwapStatus, SwapStatusResult, SwapTerminalStatus, TokenInfo, TokenRate, UnifiedBalanceChainIdentifier, CustomFeePolicy as UnifiedBalanceCustomFeePolicy, FeeRecipientsConfig as UnifiedBalanceFeeRecipientsConfig, UnifiedBalanceKitConfig, SupportedToken as UnifiedBalanceSupportedToken, UpdateDelegateParams, UpdateDelegateResult, VersionConfig, WaitForSwapDiscreteParams, WaitForSwapParams, WaitForSwapResultParams };