@circle-fin/app-kit 1.15.2 → 1.15.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @circle-fin/app-kit
 
+## 1.15.3
+
+### Patch Changes
+
+- Internal dependency updates. No user-facing changes.
+
 ## 1.15.2
 
 ### Patch Changes

package/bridge.cjs

@@ -29506,7 +29506,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
 var name = "@circle-fin/earn-kit";
-var version = "1.7.0";
+var version = "1.8.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -29648,10 +29648,8 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     assetAddress: zod.z.string(),
     lltv: zod.z.number(),
     supplyUsd: zod.z.number(),
-    // Optional during the expand/contract window (a backend that predates the
-    // field omits the key), mirroring the `.optional()` facets on the base
-    // schema; `null` when the product exposes no per-market allocation (V2).
-    allocationPct: zod.z.number().nullable().optional()
+    // `null` when the product exposes no per-market allocation (V2).
+    allocationPct: zod.z.number().nullable()
 });
 /**
  * Zod schema for a Morpho vault warning in the API response.
@@ -29758,19 +29756,20 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     earnKitWarnings: zod.z.array(zod.z.string()).optional()
 });
 /**
- * Shared base schema: existing flat fields (kept) plus the new nested
- * facets and neutral identity. Facets are `.optional()` during the
- * transition; flip to required once the backend is confirmed emitting.
+ * Shared base schema: existing flat fields (kept as deprecated aliases) plus
+ * the nested facets. Zenith emits all facets on every response; required here
+ * so a partial emission is caught at parse time rather than surfacing as a
+ * runtime `undefined` access.
  *
  * @internal
  */ const earnBaseSchema = vaultInfoResponseSchema.extend({
-    address: zod.z.string().optional(),
-    asOf: zod.z.string().optional(),
-    manager: managerSchema.nullable().optional(),
-    apyProfile: apyProfileSchema.optional(),
-    fee: feeInfoSchema.optional(),
-    liquidityProfile: liquidityProfileSchema.optional(),
-    riskSignals: riskSignalsSchema.optional()
+    address: zod.z.string(),
+    asOf: zod.z.string(),
+    manager: managerSchema.nullable(),
+    apyProfile: apyProfileSchema,
+    fee: feeInfoSchema,
+    liquidityProfile: liquidityProfileSchema,
+    riskSignals: riskSignalsSchema
 });
 /**
  * Zod schema for the `vault` opportunity variant.
@@ -30740,6 +30739,49 @@ const sourceAdapterContextSchema = zod.z.object({
     vaultAddress: vaultAddressSchema,
     config: earnConfigSchema.optional()
 });
+/**
+ * Schema for a successful gas fee entry (fees is non-null).
+ *
+ * Validates the kit shape — {@link EarnEstimatedGas} uses decimal strings for
+ * `gas`, `gasPrice`, and `fee`. Only digits are accepted so that the deposit
+ * operation can safely convert them to `bigint` before passing them to the
+ * provider's `computeGasReserve`.
+ *
+ * @internal
+ */ const earnGasFeeEstimateSuccessSchema = zod.z.object({
+    name: zod.z.string(),
+    token: zod.z.string(),
+    blockchain: zod.z.string(),
+    fees: zod.z.object({
+        gas: zod.z.string().regex(/^\d+$/, 'gas must be a non-negative integer string'),
+        gasPrice: zod.z.string().regex(/^\d+$/, 'gasPrice must be a non-negative integer string'),
+        fee: zod.z.string().regex(/^\d+$/, 'fee must be a non-negative integer string')
+    }),
+    error: zod.z.undefined().optional()
+}).strict();
+/**
+ * Schema for a failed gas fee entry (fees is null, error is a string).
+ *
+ * @internal
+ */ const earnGasFeeEstimateFailureSchema = zod.z.object({
+    name: zod.z.string(),
+    token: zod.z.string(),
+    blockchain: zod.z.string(),
+    fees: zod.z.null(),
+    error: zod.z.string()
+}).strict();
+/**
+ * Schema for a single kit-level gas fee estimate entry.
+ *
+ * Rejects arbitrary inputs (null, numbers, empty objects, non-numeric fee
+ * strings) so callers receive a descriptive validation error instead of a
+ * raw `BigInt` conversion error inside `computeGasReserve`.
+ *
+ * @internal
+ */ const earnGasFeeEstimateSchema = zod.z.union([
+    earnGasFeeEstimateSuccessSchema,
+    earnGasFeeEstimateFailureSchema
+]);
 /**
  * Validation schema for the same-chain variant of DepositParams.
  *
@@ -30752,6 +30794,7 @@ const sourceAdapterContextSchema = zod.z.object({
     to: zod.z.undefined().optional(),
     vaultAddress: vaultAddressSchema,
     amount: amountSchema,
+    gasFees: zod.z.array(earnGasFeeEstimateSchema).optional(),
     config: earnConfigSchema.optional()
 }).strict();
 const crossChainDepositDestinationSchema = zod.z.object({

package/bridge.d.cts

@@ -7467,6 +7467,26 @@ interface VaultQuery {
     /** On-chain vault contract address. */
     readonly vaultAddress: string;
 }
+/**
+ * Fields shared by both {@link EarnGasFeeEstimate} variants.
+ *
+ * @example
+ * ```typescript
+ * const base: EarnGasFeeEstimateBase = {
+ *   name: 'Deposit',
+ *   token: 'ETH',
+ *   blockchain: 'Arc_Testnet',
+ * }
+ * ```
+ */
+interface EarnGasFeeEstimateBase {
+    /** The earn step being estimated, e.g. "Approve", "Deposit", "Withdraw". */
+    readonly name: string;
+    /** Native token used to pay gas fees, e.g. "ETH". */
+    readonly token: string;
+    /** Blockchain where this gas fee applies. */
+    readonly blockchain: ChainDefinition['chain'];
+}
 /**
  * Sort order for a vault discovery query.
  *
@@ -7481,6 +7501,51 @@ interface VaultQuery {
  */
 type ExploreVaultsSortBy = 'apy' | 'tvl' | 'name';
 
+/**
+ * Estimated gas details for one transaction in a kit-level Earn quote, with
+ * every amount as a decimal string so quote results stay JSON-serializable.
+ *
+ * @example
+ * ```typescript
+ * const gas: EarnEstimatedGas = { gas: '73567', gasPrice: '20003763738', fee: '1471616886913446' }
+ * ```
+ */
+interface EarnEstimatedGas {
+    /** Estimated gas units as a decimal string, e.g. '73567'. */
+    readonly gas: string;
+    /** Estimated price per gas unit as a decimal string in wei. */
+    readonly gasPrice: string;
+    /** Total estimated fee as a decimal string in wei. */
+    readonly fee: string;
+}
+/**
+ * Estimated native gas fee for one transaction in an Earn quote.
+ *
+ * A discriminated union on `fees`: a successful estimate carries
+ * {@link EarnEstimatedGas} details and no `error`; a failed estimate carries
+ * `fees: null` and a sanitized `error` message.
+ *
+ * @example
+ * ```typescript
+ * function describe(entry: EarnGasFeeEstimate): string {
+ *   if (entry.fees === null) {
+ *     return `${entry.name}: estimation failed (${entry.error})`
+ *   }
+ *   return `${entry.name}: ${entry.fees.fee} wei`
+ * }
+ * ```
+ */
+type EarnGasFeeEstimate = (EarnGasFeeEstimateBase & {
+    /** Estimated gas details with amounts formatted as decimal strings. */
+    readonly fees: EarnEstimatedGas;
+    /** Never present on a successful estimate. */
+    readonly error?: never;
+}) | (EarnGasFeeEstimateBase & {
+    /** Null because estimation failed. */
+    readonly fees: null;
+    /** Sanitized estimation error message. */
+    readonly error: string;
+});
 /**
  * Adapter context for earn operations, constrained to earn-supported chains.
  *
@@ -7664,6 +7729,12 @@ interface SameChainDepositParams<TFromAdapterCapabilities extends AdapterCapabil
      * @example '100.50' for 100.50 USDC
      */
     readonly amount: string;
+    /**
+     * Gas fee estimates from a prior {@link getDepositQuote} call. When provided,
+     * the pre-broadcast gas reserve check uses the actual estimated cost instead
+     * of the conservative fallback reserve.
+     */
+    readonly gasFees?: readonly EarnGasFeeEstimate[] | undefined;
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }

package/bridge.d.mts

@@ -7467,6 +7467,26 @@ interface VaultQuery {
     /** On-chain vault contract address. */
     readonly vaultAddress: string;
 }
+/**
+ * Fields shared by both {@link EarnGasFeeEstimate} variants.
+ *
+ * @example
+ * ```typescript
+ * const base: EarnGasFeeEstimateBase = {
+ *   name: 'Deposit',
+ *   token: 'ETH',
+ *   blockchain: 'Arc_Testnet',
+ * }
+ * ```
+ */
+interface EarnGasFeeEstimateBase {
+    /** The earn step being estimated, e.g. "Approve", "Deposit", "Withdraw". */
+    readonly name: string;
+    /** Native token used to pay gas fees, e.g. "ETH". */
+    readonly token: string;
+    /** Blockchain where this gas fee applies. */
+    readonly blockchain: ChainDefinition['chain'];
+}
 /**
  * Sort order for a vault discovery query.
  *
@@ -7481,6 +7501,51 @@ interface VaultQuery {
  */
 type ExploreVaultsSortBy = 'apy' | 'tvl' | 'name';
 
+/**
+ * Estimated gas details for one transaction in a kit-level Earn quote, with
+ * every amount as a decimal string so quote results stay JSON-serializable.
+ *
+ * @example
+ * ```typescript
+ * const gas: EarnEstimatedGas = { gas: '73567', gasPrice: '20003763738', fee: '1471616886913446' }
+ * ```
+ */
+interface EarnEstimatedGas {
+    /** Estimated gas units as a decimal string, e.g. '73567'. */
+    readonly gas: string;
+    /** Estimated price per gas unit as a decimal string in wei. */
+    readonly gasPrice: string;
+    /** Total estimated fee as a decimal string in wei. */
+    readonly fee: string;
+}
+/**
+ * Estimated native gas fee for one transaction in an Earn quote.
+ *
+ * A discriminated union on `fees`: a successful estimate carries
+ * {@link EarnEstimatedGas} details and no `error`; a failed estimate carries
+ * `fees: null` and a sanitized `error` message.
+ *
+ * @example
+ * ```typescript
+ * function describe(entry: EarnGasFeeEstimate): string {
+ *   if (entry.fees === null) {
+ *     return `${entry.name}: estimation failed (${entry.error})`
+ *   }
+ *   return `${entry.name}: ${entry.fees.fee} wei`
+ * }
+ * ```
+ */
+type EarnGasFeeEstimate = (EarnGasFeeEstimateBase & {
+    /** Estimated gas details with amounts formatted as decimal strings. */
+    readonly fees: EarnEstimatedGas;
+    /** Never present on a successful estimate. */
+    readonly error?: never;
+}) | (EarnGasFeeEstimateBase & {
+    /** Null because estimation failed. */
+    readonly fees: null;
+    /** Sanitized estimation error message. */
+    readonly error: string;
+});
 /**
  * Adapter context for earn operations, constrained to earn-supported chains.
  *
@@ -7664,6 +7729,12 @@ interface SameChainDepositParams<TFromAdapterCapabilities extends AdapterCapabil
      * @example '100.50' for 100.50 USDC
      */
     readonly amount: string;
+    /**
+     * Gas fee estimates from a prior {@link getDepositQuote} call. When provided,
+     * the pre-broadcast gas reserve check uses the actual estimated cost instead
+     * of the conservative fallback reserve.
+     */
+    readonly gasFees?: readonly EarnGasFeeEstimate[] | undefined;
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }

package/bridge.d.ts

@@ -7467,6 +7467,26 @@ interface VaultQuery {
     /** On-chain vault contract address. */
     readonly vaultAddress: string;
 }
+/**
+ * Fields shared by both {@link EarnGasFeeEstimate} variants.
+ *
+ * @example
+ * ```typescript
+ * const base: EarnGasFeeEstimateBase = {
+ *   name: 'Deposit',
+ *   token: 'ETH',
+ *   blockchain: 'Arc_Testnet',
+ * }
+ * ```
+ */
+interface EarnGasFeeEstimateBase {
+    /** The earn step being estimated, e.g. "Approve", "Deposit", "Withdraw". */
+    readonly name: string;
+    /** Native token used to pay gas fees, e.g. "ETH". */
+    readonly token: string;
+    /** Blockchain where this gas fee applies. */
+    readonly blockchain: ChainDefinition['chain'];
+}
 /**
  * Sort order for a vault discovery query.
  *
@@ -7481,6 +7501,51 @@ interface VaultQuery {
  */
 type ExploreVaultsSortBy = 'apy' | 'tvl' | 'name';
 
+/**
+ * Estimated gas details for one transaction in a kit-level Earn quote, with
+ * every amount as a decimal string so quote results stay JSON-serializable.
+ *
+ * @example
+ * ```typescript
+ * const gas: EarnEstimatedGas = { gas: '73567', gasPrice: '20003763738', fee: '1471616886913446' }
+ * ```
+ */
+interface EarnEstimatedGas {
+    /** Estimated gas units as a decimal string, e.g. '73567'. */
+    readonly gas: string;
+    /** Estimated price per gas unit as a decimal string in wei. */
+    readonly gasPrice: string;
+    /** Total estimated fee as a decimal string in wei. */
+    readonly fee: string;
+}
+/**
+ * Estimated native gas fee for one transaction in an Earn quote.
+ *
+ * A discriminated union on `fees`: a successful estimate carries
+ * {@link EarnEstimatedGas} details and no `error`; a failed estimate carries
+ * `fees: null` and a sanitized `error` message.
+ *
+ * @example
+ * ```typescript
+ * function describe(entry: EarnGasFeeEstimate): string {
+ *   if (entry.fees === null) {
+ *     return `${entry.name}: estimation failed (${entry.error})`
+ *   }
+ *   return `${entry.name}: ${entry.fees.fee} wei`
+ * }
+ * ```
+ */
+type EarnGasFeeEstimate = (EarnGasFeeEstimateBase & {
+    /** Estimated gas details with amounts formatted as decimal strings. */
+    readonly fees: EarnEstimatedGas;
+    /** Never present on a successful estimate. */
+    readonly error?: never;
+}) | (EarnGasFeeEstimateBase & {
+    /** Null because estimation failed. */
+    readonly fees: null;
+    /** Sanitized estimation error message. */
+    readonly error: string;
+});
 /**
  * Adapter context for earn operations, constrained to earn-supported chains.
  *
@@ -7664,6 +7729,12 @@ interface SameChainDepositParams<TFromAdapterCapabilities extends AdapterCapabil
      * @example '100.50' for 100.50 USDC
      */
     readonly amount: string;
+    /**
+     * Gas fee estimates from a prior {@link getDepositQuote} call. When provided,
+     * the pre-broadcast gas reserve check uses the actual estimated cost instead
+     * of the conservative fallback reserve.
+     */
+    readonly gasFees?: readonly EarnGasFeeEstimate[] | undefined;
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }

package/bridge.mjs

@@ -29499,7 +29499,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
 var name = "@circle-fin/earn-kit";
-var version = "1.7.0";
+var version = "1.8.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -29641,10 +29641,8 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     assetAddress: z.string(),
     lltv: z.number(),
     supplyUsd: z.number(),
-    // Optional during the expand/contract window (a backend that predates the
-    // field omits the key), mirroring the `.optional()` facets on the base
-    // schema; `null` when the product exposes no per-market allocation (V2).
-    allocationPct: z.number().nullable().optional()
+    // `null` when the product exposes no per-market allocation (V2).
+    allocationPct: z.number().nullable()
 });
 /**
  * Zod schema for a Morpho vault warning in the API response.
@@ -29751,19 +29749,20 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     earnKitWarnings: z.array(z.string()).optional()
 });
 /**
- * Shared base schema: existing flat fields (kept) plus the new nested
- * facets and neutral identity. Facets are `.optional()` during the
- * transition; flip to required once the backend is confirmed emitting.
+ * Shared base schema: existing flat fields (kept as deprecated aliases) plus
+ * the nested facets. Zenith emits all facets on every response; required here
+ * so a partial emission is caught at parse time rather than surfacing as a
+ * runtime `undefined` access.
  *
  * @internal
  */ const earnBaseSchema = vaultInfoResponseSchema.extend({
-    address: z.string().optional(),
-    asOf: z.string().optional(),
-    manager: managerSchema.nullable().optional(),
-    apyProfile: apyProfileSchema.optional(),
-    fee: feeInfoSchema.optional(),
-    liquidityProfile: liquidityProfileSchema.optional(),
-    riskSignals: riskSignalsSchema.optional()
+    address: z.string(),
+    asOf: z.string(),
+    manager: managerSchema.nullable(),
+    apyProfile: apyProfileSchema,
+    fee: feeInfoSchema,
+    liquidityProfile: liquidityProfileSchema,
+    riskSignals: riskSignalsSchema
 });
 /**
  * Zod schema for the `vault` opportunity variant.
@@ -30733,6 +30732,49 @@ const sourceAdapterContextSchema = z.object({
     vaultAddress: vaultAddressSchema,
     config: earnConfigSchema.optional()
 });
+/**
+ * Schema for a successful gas fee entry (fees is non-null).
+ *
+ * Validates the kit shape — {@link EarnEstimatedGas} uses decimal strings for
+ * `gas`, `gasPrice`, and `fee`. Only digits are accepted so that the deposit
+ * operation can safely convert them to `bigint` before passing them to the
+ * provider's `computeGasReserve`.
+ *
+ * @internal
+ */ const earnGasFeeEstimateSuccessSchema = z.object({
+    name: z.string(),
+    token: z.string(),
+    blockchain: z.string(),
+    fees: z.object({
+        gas: z.string().regex(/^\d+$/, 'gas must be a non-negative integer string'),
+        gasPrice: z.string().regex(/^\d+$/, 'gasPrice must be a non-negative integer string'),
+        fee: z.string().regex(/^\d+$/, 'fee must be a non-negative integer string')
+    }),
+    error: z.undefined().optional()
+}).strict();
+/**
+ * Schema for a failed gas fee entry (fees is null, error is a string).
+ *
+ * @internal
+ */ const earnGasFeeEstimateFailureSchema = z.object({
+    name: z.string(),
+    token: z.string(),
+    blockchain: z.string(),
+    fees: z.null(),
+    error: z.string()
+}).strict();
+/**
+ * Schema for a single kit-level gas fee estimate entry.
+ *
+ * Rejects arbitrary inputs (null, numbers, empty objects, non-numeric fee
+ * strings) so callers receive a descriptive validation error instead of a
+ * raw `BigInt` conversion error inside `computeGasReserve`.
+ *
+ * @internal
+ */ const earnGasFeeEstimateSchema = z.union([
+    earnGasFeeEstimateSuccessSchema,
+    earnGasFeeEstimateFailureSchema
+]);
 /**
  * Validation schema for the same-chain variant of DepositParams.
  *
@@ -30745,6 +30787,7 @@ const sourceAdapterContextSchema = z.object({
     to: z.undefined().optional(),
     vaultAddress: vaultAddressSchema,
     amount: amountSchema,
+    gasFees: z.array(earnGasFeeEstimateSchema).optional(),
     config: earnConfigSchema.optional()
 }).strict();
 const crossChainDepositDestinationSchema = z.object({

package/context.d.cts

@@ -7225,6 +7225,26 @@ interface VaultQuery {
     /** On-chain vault contract address. */
     readonly vaultAddress: string;
 }
+/**
+ * Fields shared by both {@link EarnGasFeeEstimate} variants.
+ *
+ * @example
+ * ```typescript
+ * const base: EarnGasFeeEstimateBase = {
+ *   name: 'Deposit',
+ *   token: 'ETH',
+ *   blockchain: 'Arc_Testnet',
+ * }
+ * ```
+ */
+interface EarnGasFeeEstimateBase {
+    /** The earn step being estimated, e.g. "Approve", "Deposit", "Withdraw". */
+    readonly name: string;
+    /** Native token used to pay gas fees, e.g. "ETH". */
+    readonly token: string;
+    /** Blockchain where this gas fee applies. */
+    readonly blockchain: ChainDefinition['chain'];
+}
 /**
  * Sort order for a vault discovery query.
  *
@@ -7239,6 +7259,51 @@ interface VaultQuery {
  */
 type ExploreVaultsSortBy = 'apy' | 'tvl' | 'name';
 
+/**
+ * Estimated gas details for one transaction in a kit-level Earn quote, with
+ * every amount as a decimal string so quote results stay JSON-serializable.
+ *
+ * @example
+ * ```typescript
+ * const gas: EarnEstimatedGas = { gas: '73567', gasPrice: '20003763738', fee: '1471616886913446' }
+ * ```
+ */
+interface EarnEstimatedGas {
+    /** Estimated gas units as a decimal string, e.g. '73567'. */
+    readonly gas: string;
+    /** Estimated price per gas unit as a decimal string in wei. */
+    readonly gasPrice: string;
+    /** Total estimated fee as a decimal string in wei. */
+    readonly fee: string;
+}
+/**
+ * Estimated native gas fee for one transaction in an Earn quote.
+ *
+ * A discriminated union on `fees`: a successful estimate carries
+ * {@link EarnEstimatedGas} details and no `error`; a failed estimate carries
+ * `fees: null` and a sanitized `error` message.
+ *
+ * @example
+ * ```typescript
+ * function describe(entry: EarnGasFeeEstimate): string {
+ *   if (entry.fees === null) {
+ *     return `${entry.name}: estimation failed (${entry.error})`
+ *   }
+ *   return `${entry.name}: ${entry.fees.fee} wei`
+ * }
+ * ```
+ */
+type EarnGasFeeEstimate = (EarnGasFeeEstimateBase & {
+    /** Estimated gas details with amounts formatted as decimal strings. */
+    readonly fees: EarnEstimatedGas;
+    /** Never present on a successful estimate. */
+    readonly error?: never;
+}) | (EarnGasFeeEstimateBase & {
+    /** Null because estimation failed. */
+    readonly fees: null;
+    /** Sanitized estimation error message. */
+    readonly error: string;
+});
 /**
  * Adapter context for earn operations, constrained to earn-supported chains.
  *
@@ -7422,6 +7487,12 @@ interface SameChainDepositParams<TFromAdapterCapabilities extends AdapterCapabil
      * @example '100.50' for 100.50 USDC
      */
     readonly amount: string;
+    /**
+     * Gas fee estimates from a prior {@link getDepositQuote} call. When provided,
+     * the pre-broadcast gas reserve check uses the actual estimated cost instead
+     * of the conservative fallback reserve.
+     */
+    readonly gasFees?: readonly EarnGasFeeEstimate[] | undefined;
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }

package/context.d.mts

@@ -7225,6 +7225,26 @@ interface VaultQuery {
     /** On-chain vault contract address. */
     readonly vaultAddress: string;
 }
+/**
+ * Fields shared by both {@link EarnGasFeeEstimate} variants.
+ *
+ * @example
+ * ```typescript
+ * const base: EarnGasFeeEstimateBase = {
+ *   name: 'Deposit',
+ *   token: 'ETH',
+ *   blockchain: 'Arc_Testnet',
+ * }
+ * ```
+ */
+interface EarnGasFeeEstimateBase {
+    /** The earn step being estimated, e.g. "Approve", "Deposit", "Withdraw". */
+    readonly name: string;
+    /** Native token used to pay gas fees, e.g. "ETH". */
+    readonly token: string;
+    /** Blockchain where this gas fee applies. */
+    readonly blockchain: ChainDefinition['chain'];
+}
 /**
  * Sort order for a vault discovery query.
  *
@@ -7239,6 +7259,51 @@ interface VaultQuery {
  */
 type ExploreVaultsSortBy = 'apy' | 'tvl' | 'name';
 
+/**
+ * Estimated gas details for one transaction in a kit-level Earn quote, with
+ * every amount as a decimal string so quote results stay JSON-serializable.
+ *
+ * @example
+ * ```typescript
+ * const gas: EarnEstimatedGas = { gas: '73567', gasPrice: '20003763738', fee: '1471616886913446' }
+ * ```
+ */
+interface EarnEstimatedGas {
+    /** Estimated gas units as a decimal string, e.g. '73567'. */
+    readonly gas: string;
+    /** Estimated price per gas unit as a decimal string in wei. */
+    readonly gasPrice: string;
+    /** Total estimated fee as a decimal string in wei. */
+    readonly fee: string;
+}
+/**
+ * Estimated native gas fee for one transaction in an Earn quote.
+ *
+ * A discriminated union on `fees`: a successful estimate carries
+ * {@link EarnEstimatedGas} details and no `error`; a failed estimate carries
+ * `fees: null` and a sanitized `error` message.
+ *
+ * @example
+ * ```typescript
+ * function describe(entry: EarnGasFeeEstimate): string {
+ *   if (entry.fees === null) {
+ *     return `${entry.name}: estimation failed (${entry.error})`
+ *   }
+ *   return `${entry.name}: ${entry.fees.fee} wei`
+ * }
+ * ```
+ */
+type EarnGasFeeEstimate = (EarnGasFeeEstimateBase & {
+    /** Estimated gas details with amounts formatted as decimal strings. */
+    readonly fees: EarnEstimatedGas;
+    /** Never present on a successful estimate. */
+    readonly error?: never;
+}) | (EarnGasFeeEstimateBase & {
+    /** Null because estimation failed. */
+    readonly fees: null;
+    /** Sanitized estimation error message. */
+    readonly error: string;
+});
 /**
  * Adapter context for earn operations, constrained to earn-supported chains.
  *
@@ -7422,6 +7487,12 @@ interface SameChainDepositParams<TFromAdapterCapabilities extends AdapterCapabil
      * @example '100.50' for 100.50 USDC
      */
     readonly amount: string;
+    /**
+     * Gas fee estimates from a prior {@link getDepositQuote} call. When provided,
+     * the pre-broadcast gas reserve check uses the actual estimated cost instead
+     * of the conservative fallback reserve.
+     */
+    readonly gasFees?: readonly EarnGasFeeEstimate[] | undefined;
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }