@circle-fin/app-kit 1.9.0 → 1.10.0

package/earn.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.
@@ -2177,6 +2208,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;
 }
 
 /**
@@ -6082,6 +6217,30 @@ declare class Amount implements AmountFields {
     toJSON(): AmountJSON;
 }
 
+/** @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;
+}>]>>>;
+
 /**
  * A single vault query specifying chain and vault address.
  *
@@ -6129,6 +6288,7 @@ interface VaultRewardInfo {
  *   assetAddress: '0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf',
  *   lltv: 0.86,
  *   supplyUsd: 50000000.25,
+ *   allocationPct: 0.6,
  * }
  * ```
  */
@@ -6141,6 +6301,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.
@@ -6160,65 +6331,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.
  *
@@ -6398,6 +6757,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}.
@@ -6498,6 +6865,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
@@ -6758,27 +7132,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;
 }
@@ -6819,26 +7187,21 @@ interface WithdrawalQuoteInfo {
      */
     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;
     /**
@@ -6871,16 +7234,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;
 }
@@ -6891,8 +7251,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[];
 }
@@ -6945,7 +7305,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;
 }
@@ -7508,12 +7868,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'> & {
@@ -8044,26 +8434,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.
      *
@@ -8356,5 +8748,40 @@ declare function getWithdrawalQuote<TFromAdapterCapabilities extends AdapterCapa
  * ```
  */
 declare function getClaimRewardsQuote<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(context: AppKitContext, params: GetClaimRewardsQuoteParams<TFromAdapterCapabilities>): Promise<EarnClaimRewardsQuoteInfo>;
+/**
+ * Resume a multi-phase earn operation that previously failed.
+ *
+ * Pass the {@link KitError} caught from `deposit`, `withdraw`, or
+ * `claimRewards`. Completed phases can be skipped when the error carries
+ * earn retry context. 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 execute
+ * broadcast may still be in flight.
+ *
+ * @param context - AppKit context
+ * @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 { isRetryableError } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { retry } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ *
+ * try {
+ *   await deposit(context, params)
+ * } catch (error) {
+ *   if (isRetryableError(error)) {
+ *     const result = await retry(context, error)
+ *   }
+ * }
+ * ```
+ */
+declare function retry(context: AppKitContext, error: unknown): Promise<EarnDepositOutcome | EarnWithdrawResult | EarnClaimRewardsResult>;
 
-export { claimRewards, deposit, exploreVaults, exploreVaultsIterator, getClaimRewardsQuote, getCrossChainDepositStatus, getDepositQuote, getPosition, getVaults, getWithdrawalQuote, waitForCrossChainDeposit, withdraw };
+export { claimRewards, deposit, exploreVaults, exploreVaultsIterator, getClaimRewardsQuote, getCrossChainDepositStatus, getDepositQuote, getPosition, getVaults, getWithdrawalQuote, retry, waitForCrossChainDeposit, withdraw };