@circle-fin/app-kit 1.15.1 → 1.15.3

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;
 }

package/context.d.ts

@@ -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;
 }