refactor(sdk): extract shared gas estimation utilities (#7922)

Author: paulbalaji

.changeset/estimateHandleGas-utility.md

@@ -0,0 +1,5 @@
+---
+"@hyperlane-xyz/sdk": minor
+---
+
+Extracted shared gas estimation utilities: `estimateHandleGasForRecipient()` for `handle()` calls and `estimateCallGas()` for individual contract calls. Added `HyperlaneCore.estimateHandleGas()` accepting minimal params. Refactored `InterchainAccount.estimateIcaHandleGas()` to use shared utilities.

.gitignore

@@ -44,4 +44,6 @@ yalc.lock
 
 # .yarn as we use pnpm now
 .yarn
-.sisyphus/
+
+.opencode
+.sisyphus

typescript/sdk/src/core/HyperlaneCore.ts

@@ -38,6 +38,7 @@ import { DerivedIsmConfig } from '../ism/types.js';
 import { MultiProvider } from '../providers/MultiProvider.js';
 import { RouterConfig } from '../router/types.js';
 import { ChainMap, ChainName, OwnableConfig } from '../types.js';
+import { estimateHandleGasForRecipient } from '../utils/gas.js';
 import { findMatchingLogEvents } from '../utils/logUtils.js';
 
 import { CoreFactories, coreFactories } from './contracts.js';
@@ -257,20 +258,58 @@ export class HyperlaneCore extends HyperlaneApp<CoreFactories> {
     // This estimation overrides transaction.from which requires a funded signer
     // on ZkSync-based chains. We catch estimation failures and return '0' to
     // allow the caller to handle gas estimation differently.
+    return this.estimateHandleGas({
+      destination: this.getDestination(message),
+      recipient: bytes32ToAddress(message.parsed.recipient),
+      origin: message.parsed.origin,
+      sender: message.parsed.sender,
+      body: message.parsed.body,
+    });
+  }
+
+  /**
+   * Estimates gas for calling handle() on a recipient contract.
+   *
+   * This is a flexible utility that accepts minimal parameters (destination,
+   * recipient, origin, sender, body) instead of requiring a full DispatchedMessage.
+   * Use this when you have message components but not a complete DispatchedMessage object.
+   *
+   * @param params - Object containing:
+   *   - destination: The destination chain name
+   *   - recipient: The recipient contract address (or any IMessageRecipient implementation like ICA router)
+   *   - origin: The origin domain ID
+   *   - sender: The sender address (as bytes32 string)
+   *   - body: The message body (as hex string)
+   *   - mailbox: Optional mailbox address override (defaults to chain's configured mailbox)
+   * @returns Gas estimate as a string, or '0' if estimation fails
+   */
+  async estimateHandleGas(params: {
+    destination: ChainName;
+    recipient: Address;
+    origin: number;
+    sender: string;
+    body: string;
+    mailbox?: Address;
+  }): Promise<string> {
     try {
-      return (
-        await this.getRecipient(message).estimateGas.handle(
-          message.parsed.origin,
-          message.parsed.sender,
-          message.parsed.body,
-          { from: this.getAddresses(this.getDestination(message)).mailbox },
-        )
-      ).toString();
-    } catch (error) {
-      this.logger.debug(
-        { error, destination: this.getDestination(message) },
-        'Failed to estimate handle gas, returning 0',
+      const provider = this.multiProvider.getProvider(params.destination);
+      const mailbox =
+        params.mailbox ?? this.getAddresses(params.destination).mailbox;
+      const recipientContract = IMessageRecipient__factory.connect(
+        params.recipient,
+        provider,
       );
+
+      const gasEstimate = await estimateHandleGasForRecipient({
+        recipient: recipientContract,
+        origin: params.origin,
+        sender: params.sender,
+        body: params.body,
+        mailbox,
+      });
+
+      return gasEstimate?.toString() ?? '0';
+    } catch {
       return '0';
     }
   }

typescript/sdk/src/middleware/account/InterchainAccount.test.ts

@@ -159,10 +159,10 @@ describe('InterchainAccount.getCallRemote', () => {
 describe('InterchainAccount.estimateIcaHandleGas', () => {
   const chain = TestChainName.test1;
   const destination = TestChainName.test2;
-  const ICA_HANDLE_GAS_FALLBACK = BigNumber.from(200_000);
   const ICA_OVERHEAD = BigNumber.from(50_000);
   const PER_CALL_OVERHEAD = BigNumber.from(5_000);
   const PER_CALL_FALLBACK = BigNumber.from(50_000);
+  const ICA_HANDLE_GAS_FALLBACK = BigNumber.from(200_000);
 
   let sandbox: sinon.SinonSandbox;
   let multiProvider: MultiProvider;
@@ -293,10 +293,9 @@ describe('InterchainAccount.estimateIcaHandleGas', () => {
     expect(result.toString()).to.equal(expectedWithBuffer.toString());
   });
 
-  it('returns static 200k fallback when Promise.all fails', async () => {
+  it('returns static 200k fallback when getProvider fails', async () => {
     mockDestRouter.estimateGas.handle.rejects(new Error('handle failed'));
 
-    // Make getProvider throw to cause Promise.all to fail
     (multiProvider.getProvider as sinon.SinonStub).throws(
       new Error('provider error'),
     );

typescript/sdk/src/middleware/account/InterchainAccount.ts

@@ -31,6 +31,10 @@ import { MultiProvider } from '../../providers/MultiProvider.js';
 import { CallData as SdkCallData } from '../../providers/transactions/types.js';
 import { RouterApp } from '../../router/RouterApps.js';
 import { ChainMap, ChainName } from '../../types.js';
+import {
+  estimateCallGas,
+  estimateHandleGasForRecipient,
+} from '../../utils/gas.js';
 
 import {
   InterchainAccountFactories,
@@ -39,6 +43,8 @@ import {
 import { AccountConfig, GetCallRemoteSettings } from './types.js';
 
 const IGP_DEFAULT_GAS = BigNumber.from(50_000);
+const ICA_OVERHEAD = BigNumber.from(50_000);
+const PER_CALL_OVERHEAD = BigNumber.from(5_000);
 const ICA_HANDLE_GAS_FALLBACK = BigNumber.from(200_000);
 
 export class InterchainAccount extends RouterApp<InterchainAccountFactories> {
@@ -230,43 +236,53 @@ export class InterchainAccount extends RouterApp<InterchainAccountFactories> {
     );
 
     try {
-      const gasEstimate = await destinationRouter.estimateGas.handle(
-        originDomain,
-        addressToBytes32(localRouterAddress),
-        messageBody,
-        { from: await destinationRouter.mailbox() },
+      const mailbox = await destinationRouter.mailbox();
+      const gasEstimate = await estimateHandleGasForRecipient({
+        recipient: destinationRouter,
+        origin: originDomain,
+        sender: addressToBytes32(localRouterAddress),
+        body: messageBody,
+        mailbox,
+      });
+
+      if (gasEstimate) {
+        return addBufferToGasLimit(gasEstimate);
+      }
+    } catch {
+      // Fall through to individual call estimation
+    }
+
+    this.logger.warn(
+      { destination },
+      'Failed to estimate ICA handle gas, trying individual call estimation',
+    );
+
+    try {
+      const provider = this.multiProvider.getProvider(destination);
+      const individualEstimates = await Promise.all(
+        formattedCalls.map((call) =>
+          estimateCallGas({
+            provider,
+            to: bytes32ToAddress(call.to),
+            data: call.data,
+            value: call.value,
+          }),
+        ),
+      );
+      const totalGas = individualEstimates.reduce(
+        (sum, gas) => sum.add(gas),
+        BigNumber.from(0),
+      );
+      const overhead = ICA_OVERHEAD.add(
+        PER_CALL_OVERHEAD.mul(formattedCalls.length),
       );
-      return addBufferToGasLimit(gasEstimate);
-    } catch (error) {
+      return addBufferToGasLimit(totalGas.add(overhead));
+    } catch {
       this.logger.warn(
-        { error, destination },
-        'Failed to estimate ICA handle gas, trying individual call estimation',
+        { destination },
+        'Individual call estimation also failed, using static fallback',
       );
-
-      try {
-        const individualEstimates = await Promise.all(
-          formattedCalls.map((call) =>
-            this.estimateIndividualCallGas(destination, call),
-          ),
-        );
-        const totalGas = individualEstimates.reduce(
-          (sum, gas) => sum.add(gas),
-          BigNumber.from(0),
-        );
-        // Overhead: ICA deployment check + multicall dispatch + message decoding
-        const ICA_OVERHEAD = BigNumber.from(50_000);
-        const PER_CALL_OVERHEAD = BigNumber.from(5_000);
-        const overhead = ICA_OVERHEAD.add(
-          PER_CALL_OVERHEAD.mul(formattedCalls.length),
-        );
-        return addBufferToGasLimit(totalGas.add(overhead));
-      } catch (fallbackError) {
-        this.logger.warn(
-          { error: fallbackError, destination },
-          'Individual call estimation also failed, using static fallback',
-        );
-        return ICA_HANDLE_GAS_FALLBACK;
-      }
+      return ICA_HANDLE_GAS_FALLBACK;
     }
   }
 
@@ -353,27 +369,6 @@ export class InterchainAccount extends RouterApp<InterchainAccountFactories> {
     return parsed ? BigNumber.from(parsed.gasLimit) : null;
   }
 
-  /**
-   * Estimate gas for a single call on the destination chain.
-   * Used as fallback when full handle() estimation fails.
-   */
-  private async estimateIndividualCallGas(
-    destination: string,
-    call: { to: string; value: BigNumber; data: string },
-  ): Promise<BigNumber> {
-    const provider = this.multiProvider.getProvider(destination);
-    const PER_CALL_FALLBACK = BigNumber.from(50_000);
-    try {
-      return await provider.estimateGas({
-        to: bytes32ToAddress(call.to),
-        data: call.data,
-        value: call.value,
-      });
-    } catch {
-      return PER_CALL_FALLBACK;
-    }
-  }
-
   // general helper for different overloaded callRemote functions
   // can override the gasLimit by StandardHookMetadata.overrideGasLimit for optional hookMetadata here
   async callRemote({

typescript/sdk/src/utils/gas.ts

@@ -0,0 +1,62 @@
+import { BigNumber, providers } from 'ethers';
+
+import { IMessageRecipient } from '@hyperlane-xyz/core';
+import { Address } from '@hyperlane-xyz/utils';
+
+export const DEFAULT_CALL_GAS_FALLBACK = BigNumber.from(50_000);
+
+export interface EstimateHandleGasParams {
+  origin: number;
+  sender: string;
+  body: string;
+  mailbox: Address;
+  recipient: IMessageRecipient;
+}
+
+export interface EstimateCallGasParams {
+  provider: providers.Provider;
+  to: Address;
+  data: string;
+  value?: BigNumber;
+  fallback?: BigNumber;
+}
+
+/**
+ * Estimates gas for calling handle() on a recipient contract.
+ * Returns null if estimation fails (e.g., call would revert).
+ */
+export async function estimateHandleGasForRecipient(
+  params: EstimateHandleGasParams,
+): Promise<BigNumber | null> {
+  try {
+    // await required for catch to handle promise rejection
+    return await params.recipient.estimateGas.handle(
+      params.origin,
+      params.sender,
+      params.body,
+      { from: params.mailbox },
+    );
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Estimates gas for a single contract call.
+ * Returns fallback value (default 50k) if estimation fails.
+ */
+export async function estimateCallGas(
+  params: EstimateCallGasParams,
+): Promise<BigNumber> {
+  const fallback = params.fallback ?? DEFAULT_CALL_GAS_FALLBACK;
+  try {
+    // await required for catch to handle promise rejection
+    return await params.provider.estimateGas({
+      to: params.to,
+      data: params.data,
+      value: params.value,
+    });
+  } catch {
+    return fallback;
+  }
+}