@hyperlane-xyz/rebalancer 2.0.0 → 3.1.0

package/src/utils/gasEstimation.ts

@@ -0,0 +1,272 @@
+import { BigNumber } from 'ethers';
+import type { Logger } from 'pino';
+
+import {
+  type AnnotatedEV5Transaction,
+  type ChainName,
+  type InterchainGasQuote,
+  type MultiProvider,
+  type Token,
+  TokenStandard,
+} from '@hyperlane-xyz/sdk';
+import { addBufferToGasLimit, isZeroishAddress } from '@hyperlane-xyz/utils';
+
+/**
+ * Fallback gas limit for transferRemote when eth_estimateGas fails.
+ * Conservative estimate for cross-chain token transfers.
+ */
+export const FALLBACK_TRANSFER_REMOTE_GAS_LIMIT = 300_000n;
+
+/**
+ * Cost multiplier for minimum viable transfer.
+ * A transfer must be worth at least this multiple of its cost to be worthwhile.
+ */
+export const MIN_VIABLE_COST_MULTIPLIER = 2n;
+
+/**
+ * Transfer cost estimate for native token transfers.
+ * Contains all cost components needed for transfer decisions.
+ */
+export interface TransferCostEstimate {
+  /** IGP cost for the Hyperlane message */
+  igpCost: bigint;
+  /** Estimated gas cost for the transferRemote transaction (with buffer) */
+  gasCost: bigint;
+  /** Token fee cost (native denom only) */
+  tokenFeeCost: bigint;
+  /** Total cost = igpCost + gasCost + tokenFeeCost */
+  totalCost: bigint;
+  /** Maximum transferable amount after reserving costs (availableInventory - totalCost) */
+  maxTransferable: bigint;
+  /** Minimum viable transfer (totalCost * MIN_VIABLE_COST_MULTIPLIER) */
+  minViableTransfer: bigint;
+  /** Gas quote from adapter (for passing to executeTransferRemote) */
+  gasQuote?: InterchainGasQuote;
+}
+
+/**
+ * Estimate gas for a transferRemote transaction using eth_estimateGas.
+ * Falls back to conservative estimate if estimation fails.
+ *
+ * @param originChain - Chain where transferRemote will be called
+ * @param destinationChain - Chain where the Hyperlane message goes
+ * @param amount - Amount to transfer
+ * @param multiProvider - MultiProvider for chain access
+ * @param warpCoreMultiProvider - MultiProvider from WarpCore for adapter access
+ * @param getTokenForChain - Function to get token for a chain
+ * @param inventorySigner - Address of the inventory signer
+ * @param logger - Logger instance
+ * @returns Estimated gas limit for the transaction
+ */
+export async function estimateTransferRemoteGas(
+  originChain: ChainName,
+  destinationChain: ChainName,
+  amount: bigint,
+  multiProvider: MultiProvider,
+  warpCoreMultiProvider: any,
+  getTokenForChain: (chain: ChainName) => Token | undefined,
+  inventorySigner: string,
+  logger: Logger,
+): Promise<bigint> {
+  const originToken = getTokenForChain(originChain);
+  if (!originToken) {
+    logger.warn(
+      { originChain },
+      'No token found for origin chain, using fallback gas limit',
+    );
+    return FALLBACK_TRANSFER_REMOTE_GAS_LIMIT;
+  }
+
+  try {
+    const destinationDomain = multiProvider.getDomainId(destinationChain);
+    const adapter = originToken.getHypAdapter(warpCoreMultiProvider);
+
+    // Quote the IGP gas first (needed for the full transaction)
+    const gasQuote = await adapter.quoteTransferRemoteGas({
+      destination: destinationDomain,
+      sender: inventorySigner,
+      recipient: inventorySigner,
+      amount,
+    });
+
+    // Populate with minimal amount for gas estimation
+    // Gas cost is independent of transfer size (just a require check in _transferFromSender),
+    // and using minimal amount prevents eth_estimateGas from failing when account balance < requested amount
+    // Note: getHypAdapter returns IHypTokenAdapter<unknown> for protocol-agnostic support.
+    // For EVM chains (which inventory rebalancing uses), the actual type is AnnotatedEV5Transaction.
+    const populatedTx = (await adapter.populateTransferRemoteTx({
+      destination: destinationDomain,
+      recipient: inventorySigner,
+      weiAmountOrId: 1n,
+      interchainGas: gasQuote,
+    })) as AnnotatedEV5Transaction;
+
+    // Estimate gas using the provider
+    const provider = multiProvider.getProvider(originChain);
+    const gasEstimate = await provider.estimateGas({
+      to: populatedTx.to,
+      data: populatedTx.data,
+      value: populatedTx.value,
+      from: inventorySigner,
+    });
+
+    const estimatedGas = BigInt(gasEstimate.toString());
+
+    logger.debug(
+      {
+        originChain,
+        destinationChain,
+        amount: amount.toString(),
+        estimatedGas: estimatedGas.toString(),
+      },
+      'Estimated transferRemote gas via eth_estimateGas',
+    );
+
+    return estimatedGas;
+  } catch (error) {
+    logger.warn(
+      {
+        originChain,
+        destinationChain,
+        error: (error as Error).message,
+        fallbackGas: FALLBACK_TRANSFER_REMOTE_GAS_LIMIT.toString(),
+      },
+      'Gas estimation failed, using fallback gas limit',
+    );
+    return FALLBACK_TRANSFER_REMOTE_GAS_LIMIT;
+  }
+}
+
+/**
+ * Calculate all transfer costs for a transferRemote operation.
+ * Consolidates IGP costs, gas costs, and derived values (max transferable, min viable).
+ *
+ * @param originChain - Chain to transfer from (where transferRemote is called)
+ * @param destinationChain - Chain to transfer to (Hyperlane message destination)
+ * @param availableInventory - Available token balance on origin chain
+ * @param requestedAmount - Requested transfer amount
+ * @param multiProvider - MultiProvider for chain access
+ * @param warpCoreMultiProvider - MultiProvider from WarpCore for adapter access
+ * @param getTokenForChain - Function to get token for a chain
+ * @param inventorySigner - Address of the inventory signer
+ * @param isNativeTokenStandard - Function to check if token standard is native
+ * @param logger - Logger instance
+ * @returns Cost estimate with all components and derived values
+ */
+export async function calculateTransferCosts(
+  originChain: ChainName,
+  destinationChain: ChainName,
+  availableInventory: bigint,
+  requestedAmount: bigint,
+  multiProvider: MultiProvider,
+  warpCoreMultiProvider: any,
+  getTokenForChain: (chain: ChainName) => Token | undefined,
+  inventorySigner: string,
+  isNativeTokenStandard: (standard: TokenStandard) => boolean,
+  logger: Logger,
+): Promise<TransferCostEstimate> {
+  const originToken = getTokenForChain(originChain);
+  if (!originToken) {
+    throw new Error(`No token found for origin chain: ${originChain}`);
+  }
+
+  const destinationDomain = multiProvider.getDomainId(destinationChain);
+  const adapter = originToken.getHypAdapter(warpCoreMultiProvider);
+
+  // Always quote IGP for the gas quote (needed for populateTransferRemoteTx)
+  const gasQuote = await adapter.quoteTransferRemoteGas({
+    destination: destinationDomain,
+    sender: inventorySigner,
+    recipient: inventorySigner,
+    amount: requestedAmount,
+  });
+
+  // For non-native tokens, no cost reservation needed from token balance
+  if (!isNativeTokenStandard(originToken.standard)) {
+    return {
+      igpCost: 0n,
+      gasCost: 0n,
+      tokenFeeCost: 0n,
+      totalCost: 0n,
+      maxTransferable:
+        availableInventory < requestedAmount
+          ? availableInventory
+          : requestedAmount,
+      minViableTransfer: 0n,
+      gasQuote,
+    };
+  }
+
+  // For native tokens, calculate costs
+  const igpCost = gasQuote.igpQuote.amount;
+
+  // Extract token fee cost (native denom only)
+  const tokenFeeCost =
+    !gasQuote.tokenFeeQuote?.addressOrDenom ||
+    isZeroishAddress(gasQuote.tokenFeeQuote.addressOrDenom)
+      ? (gasQuote.tokenFeeQuote?.amount ?? 0n)
+      : 0n;
+
+  // Estimate gas with buffer
+  const estimatedGasLimit = await estimateTransferRemoteGas(
+    originChain,
+    destinationChain,
+    requestedAmount,
+    multiProvider,
+    warpCoreMultiProvider,
+    getTokenForChain,
+    inventorySigner,
+    logger,
+  );
+  const bufferedGasLimit = addBufferToGasLimit(
+    BigNumber.from(estimatedGasLimit.toString()),
+  );
+
+  // Get gas price and calculate cost
+  const provider = multiProvider.getProvider(originChain);
+  const feeData = await provider.getFeeData();
+  const gasPrice = feeData.maxFeePerGas ?? feeData.gasPrice ?? 0n;
+  const gasCost = bufferedGasLimit.toBigInt() * BigInt(gasPrice.toString());
+
+  const totalCost = igpCost + gasCost + tokenFeeCost;
+
+  // Calculate derived values
+  let maxTransferable: bigint;
+  if (availableInventory <= totalCost) {
+    maxTransferable = 0n;
+  } else {
+    const maxAfterReservation = availableInventory - totalCost;
+    maxTransferable =
+      maxAfterReservation < requestedAmount
+        ? maxAfterReservation
+        : requestedAmount;
+  }
+
+  const minViableTransfer = totalCost * MIN_VIABLE_COST_MULTIPLIER;
+
+  logger.debug(
+    {
+      originChain,
+      destinationChain,
+      availableInventory: availableInventory.toString(),
+      requestedAmount: requestedAmount.toString(),
+      igpCost: igpCost.toString(),
+      gasCost: gasCost.toString(),
+      tokenFeeCost: tokenFeeCost.toString(),
+      totalCost: totalCost.toString(),
+      maxTransferable: maxTransferable.toString(),
+      minViableTransfer: minViableTransfer.toString(),
+    },
+    'Calculated transfer costs for native token',
+  );
+
+  return {
+    igpCost,
+    gasCost,
+    tokenFeeCost,
+    totalCost,
+    maxTransferable,
+    minViableTransfer,
+    gasQuote,
+  };
+}

package/src/utils/tokenUtils.ts

@@ -5,6 +5,18 @@ const REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS = new Set<TokenStandard>([
   TokenStandard.EvmHypNative,
 ]);
 
+/**
+ * Check if a token's balance is the same as native gas balance.
+ * For these tokens, we must reserve funds for IGP when calculating max transferable.
+ *
+ * @param standard - The token standard to check.
+ * @returns `true` if the token is a native token standard, `false` otherwise.
+ */
+export function isNativeTokenStandard(standard: TokenStandard): boolean {
+  // EvmHypNative covers all native token types including scaled variants
+  return standard === TokenStandard.EvmHypNative;
+}
+
 /**
  * @dev This function exists because the rebalancer currently only supports a subset of collateralized token standards
  *   (see `REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS` vs. all possible `TOKEN_COLLATERALIZED_STANDARDS`).

package/dist/tracking/index.d.ts

@@ -1,7 +0,0 @@
-export type { IStore } from './store/index.js';
-export { InMemoryStore } from './store/index.js';
-export type { Identifiable, CrossChainAction, Timestamped, TrackedActionBase, TransferStatus, RebalanceIntentStatus, RebalanceActionStatus, Transfer, RebalanceIntent, RebalanceAction, ITransferStore, IRebalanceIntentStore, IRebalanceActionStore, } from './types.js';
-export { ActionTracker, type ActionTrackerConfig } from './ActionTracker.js';
-export type { IActionTracker, CreateRebalanceIntentParams, CreateRebalanceActionParams, } from './IActionTracker.js';
-export { InflightContextAdapter } from './InflightContextAdapter.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/tracking/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tracking/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,YAAY,EAEV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EAEjB,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EAErB,QAAQ,EACR,eAAe,EACf,eAAe,EAEf,cAAc,EACd,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE7E,YAAY,EACV,cAAc,EACd,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/tracking/index.js

@@ -1,6 +0,0 @@
-export { InMemoryStore } from './store/index.js';
-// Export ActionTracker components
-export { ActionTracker } from './ActionTracker.js';
-// Export InflightContextAdapter
-export { InflightContextAdapter } from './InflightContextAdapter.js';
-//# sourceMappingURL=index.js.map

package/dist/tracking/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tracking/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAuBjD,kCAAkC;AAClC,OAAO,EAAE,aAAa,EAA4B,MAAM,oBAAoB,CAAC;AAQ7E,gCAAgC;AAChC,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/utils/index.d.ts

@@ -1,5 +0,0 @@
-export * from './balanceUtils.js';
-export * from './blockTag.js';
-export * from './bridgeUtils.js';
-export * from './tokenUtils.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}

package/dist/utils/index.js

@@ -1,5 +0,0 @@
-export * from './balanceUtils.js';
-export * from './blockTag.js';
-export * from './bridgeUtils.js';
-export * from './tokenUtils.js';
-//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}

package/src/tracking/index.ts

@@ -1,36 +0,0 @@
-// Export all store components
-export type { IStore } from './store/index.js';
-export { InMemoryStore } from './store/index.js';
-
-// Export types
-export type {
-  // Base interfaces
-  Identifiable,
-  CrossChainAction,
-  Timestamped,
-  TrackedActionBase,
-  // Status types
-  TransferStatus,
-  RebalanceIntentStatus,
-  RebalanceActionStatus,
-  // Entity types
-  Transfer,
-  RebalanceIntent,
-  RebalanceAction,
-  // Store type aliases
-  ITransferStore,
-  IRebalanceIntentStore,
-  IRebalanceActionStore,
-} from './types.js';
-
-// Export ActionTracker components
-export { ActionTracker, type ActionTrackerConfig } from './ActionTracker.js';
-
-export type {
-  IActionTracker,
-  CreateRebalanceIntentParams,
-  CreateRebalanceActionParams,
-} from './IActionTracker.js';
-
-// Export InflightContextAdapter
-export { InflightContextAdapter } from './InflightContextAdapter.js';

package/src/utils/index.ts

@@ -1,4 +0,0 @@
-export * from './balanceUtils.js';
-export * from './blockTag.js';
-export * from './bridgeUtils.js';
-export * from './tokenUtils.js';