@hyperlane-xyz/rebalancer 0.1.2 → 1.0.0

package/src/core/Rebalancer.ts

@@ -1,37 +1,31 @@
-import { type PopulatedTransaction } from 'ethers';
+import { type PopulatedTransaction, type providers } from 'ethers';
 import { type Logger } from 'pino';
 
 import {
   type ChainMap,
   type ChainMetadata,
+  type ChainName,
+  type EthJsonRpcBlockParameterTag,
   EvmMovableCollateralAdapter,
+  HyperlaneCore,
   type InterchainGasQuote,
   type MultiProvider,
   type Token,
   type WarpCore,
 } from '@hyperlane-xyz/sdk';
-import {
-  eqAddress,
-  isNullish,
-  mapAllSettled,
-  toWei,
-} from '@hyperlane-xyz/utils';
+import { eqAddress, isNullish, mapAllSettled } from '@hyperlane-xyz/utils';
 
 import type {
   IRebalancer,
   PreparedTransaction,
+  RebalanceExecutionResult,
+  RebalanceRoute,
 } from '../interfaces/IRebalancer.js';
-import type { RebalancingRoute } from '../interfaces/IStrategy.js';
 import { type Metrics } from '../metrics/Metrics.js';
-import {
-  type BridgeConfigWithOverride,
-  getBridgeConfig,
-} from '../utils/index.js';
 
 export class Rebalancer implements IRebalancer {
   private readonly logger: Logger;
   constructor(
-    private readonly bridges: ChainMap<BridgeConfigWithOverride>,
     private readonly warpCore: WarpCore,
     private readonly chainMetadata: ChainMap<ChainMetadata>,
     private readonly tokensByChainName: ChainMap<Token>,
@@ -42,65 +36,58 @@ export class Rebalancer implements IRebalancer {
     this.logger = logger.child({ class: Rebalancer.name });
   }
 
-  async rebalance(routes: RebalancingRoute[]): Promise<void> {
+  async rebalance(
+    routes: RebalanceRoute[],
+  ): Promise<RebalanceExecutionResult[]> {
     if (routes.length === 0) {
       this.logger.info('No routes to execute, exiting');
-      return;
+      return [];
     }
 
     this.logger.info({ numberOfRoutes: routes.length }, 'Rebalance initiated');
 
-    const { preparedTransactions, preparationFailures } =
+    const { preparedTransactions, preparationFailureResults } =
       await this.prepareTransactions(routes);
 
-    let gasEstimationFailures = 0;
-    let transactionFailures = 0;
-    let successfulTransactions: PreparedTransaction[] = [];
+    let executionResults: RebalanceExecutionResult[] = [];
 
     if (preparedTransactions.length > 0) {
-      const filteredTransactions =
-        this.filterTransactions(preparedTransactions);
-      if (filteredTransactions.length > 0) {
-        ({
-          gasEstimationFailures,
-          transactionFailures,
-          successfulTransactions,
-        } = await this.executeTransactions(filteredTransactions));
+      executionResults = await this.executeTransactions(preparedTransactions);
+    }
+
+    // Combine preparation failures with execution results
+    const allResults = [...preparationFailureResults, ...executionResults];
+
+    // Record metrics for successful transactions
+    const successfulResults = allResults.filter((r) => r.success);
+    if (this.metrics && successfulResults.length > 0) {
+      for (const result of successfulResults) {
+        const token = this.tokensByChainName[result.route.origin];
+        if (token) {
+          this.metrics.recordRebalanceAmount(
+            result.route,
+            token.amount(result.route.amount),
+          );
+        }
       }
     }
 
-    if (
-      preparationFailures > 0 ||
-      gasEstimationFailures > 0 ||
-      transactionFailures > 0
-    ) {
+    const failures = allResults.filter((r) => !r.success);
+    if (failures.length > 0) {
       this.logger.error(
-        {
-          preparationFailures,
-          gasEstimationFailures,
-          transactionFailures,
-        },
-        'A rebalance stage failed.',
+        { failureCount: failures.length, totalRoutes: routes.length },
+        'Some rebalance operations failed.',
       );
-      throw new Error('❌ Some rebalance transaction failed');
-    }
-
-    if (this.metrics && successfulTransactions.length > 0) {
-      for (const transaction of successfulTransactions) {
-        this.metrics.recordRebalanceAmount(
-          transaction.route,
-          transaction.originTokenAmount,
-        );
-      }
+    } else {
+      this.logger.info('✅ Rebalance successful');
     }
 
-    this.logger.info('✅ Rebalance successful');
-    return;
+    return allResults;
   }
 
-  private async prepareTransactions(routes: RebalancingRoute[]): Promise<{
+  private async prepareTransactions(routes: RebalanceRoute[]): Promise<{
     preparedTransactions: PreparedTransaction[];
-    preparationFailures: number;
+    preparationFailureResults: RebalanceExecutionResult[];
   }> {
     this.logger.info(
       { numRoutes: routes.length },
@@ -116,15 +103,32 @@ export class Rebalancer implements IRebalancer {
     const preparedTransactions = Array.from(fulfilled.values()).filter(
       (tx): tx is PreparedTransaction => !isNullish(tx),
     );
-    // Count rejections + null results as failures
-    const preparationFailures =
-      rejected.size + (fulfilled.size - preparedTransactions.length);
 
-    return { preparedTransactions, preparationFailures };
+    // Create failure results for tracking
+    const preparationFailureResults: RebalanceExecutionResult[] = [];
+    for (const [i, error] of rejected) {
+      preparationFailureResults.push({
+        route: routes[i],
+        success: false,
+        error: String(error),
+      });
+    }
+    // Also track null results (validation failures)
+    Array.from(fulfilled.entries()).forEach(([i, tx]) => {
+      if (isNullish(tx)) {
+        preparationFailureResults.push({
+          route: routes[i],
+          success: false,
+          error: 'Preparation returned null',
+        });
+      }
+    });
+
+    return { preparedTransactions, preparationFailureResults };
   }
 
   private async prepareTransaction(
-    route: RebalancingRoute,
+    route: RebalanceRoute,
   ): Promise<PreparedTransaction | null> {
     const { origin, destination, amount } = route;
 
@@ -153,12 +157,8 @@ export class Rebalancer implements IRebalancer {
     const originHypAdapter = originToken.getHypAdapter(
       this.warpCore.multiProvider,
     ) as EvmMovableCollateralAdapter;
-    const { bridge, bridgeIsWarp } = getBridgeConfig(
-      this.bridges,
-      origin,
-      destination,
-      this.logger,
-    );
+
+    const { bridge } = route;
 
     // 2. Get quotes
     let quotes: InterchainGasQuote[];
@@ -168,7 +168,6 @@ export class Rebalancer implements IRebalancer {
         destinationChainMeta.domainId,
         destinationToken.addressOrDenom,
         amount,
-        bridgeIsWarp,
       );
     } catch (error) {
       this.logger.error(
@@ -210,7 +209,7 @@ export class Rebalancer implements IRebalancer {
     return { populatedTx, route, originTokenAmount };
   }
 
-  private async validateRoute(route: RebalancingRoute): Promise<boolean> {
+  private async validateRoute(route: RebalanceRoute): Promise<boolean> {
     const { origin, destination, amount } = route;
     const originToken = this.tokensByChainName[origin];
     const destinationToken = this.tokensByChainName[destination];
@@ -296,12 +295,8 @@ export class Rebalancer implements IRebalancer {
       return false;
     }
 
-    const { bridge } = getBridgeConfig(
-      this.bridges,
-      origin,
-      destination,
-      this.logger,
-    );
+    const { bridge } = route;
+
     if (
       !(await originHypAdapter.isBridgeAllowed(
         destinationDomain.domainId,
@@ -327,149 +322,244 @@ export class Rebalancer implements IRebalancer {
 
   private async executeTransactions(
     transactions: PreparedTransaction[],
-  ): Promise<{
-    gasEstimationFailures: number;
-    transactionFailures: number;
-    successfulTransactions: PreparedTransaction[];
-  }> {
+  ): Promise<RebalanceExecutionResult[]> {
     this.logger.info(
       { numTransactions: transactions.length },
       'Estimating gas for all prepared transactions.',
     );
 
-    // 1. Estimate gas
-    const { fulfilled, rejected } = await mapAllSettled(
-      transactions,
-      async (transaction) => {
+    const results: RebalanceExecutionResult[] = [];
+
+    // 1. Estimate gas for rebalance transactions
+    const gasEstimateResults = await Promise.allSettled(
+      transactions.map(async (transaction) => {
         await this.multiProvider.estimateGas(
           transaction.route.origin,
           transaction.populatedTx,
         );
         return transaction;
-      },
-      (_, i) => i,
+      }),
     );
 
-    // 2. Filter out failed transactions and log errors
-    const validTransactions = Array.from(fulfilled.values());
-    const gasEstimationFailures = rejected.size;
-    for (const [i, error] of rejected) {
-      const failedTransaction = transactions[i];
-      this.logger.error(
-        {
-          origin: failedTransaction.route.origin,
-          destination: failedTransaction.route.destination,
-          amount:
-            failedTransaction.originTokenAmount.getDecimalFormattedAmount(),
-          tokenName: failedTransaction.originTokenAmount.token.name,
-          error,
-        },
-        'Gas estimation failed for route.',
-      );
-    }
+    // 2. Filter out failed transactions and track failures
+    const validTransactions: PreparedTransaction[] = [];
+    gasEstimateResults.forEach((result, i) => {
+      if (result.status === 'fulfilled') {
+        validTransactions.push(result.value);
+      } else {
+        const failedTransaction = transactions[i];
+        this.logger.error(
+          {
+            origin: failedTransaction.route.origin,
+            destination: failedTransaction.route.destination,
+            amount:
+              failedTransaction.originTokenAmount.getDecimalFormattedAmount(),
+            tokenName: failedTransaction.originTokenAmount.token.name,
+            error: result.reason,
+          },
+          'Gas estimation failed for route.',
+        );
+        results.push({
+          route: failedTransaction.route,
+          success: false,
+          error: `Gas estimation failed: ${String(result.reason)}`,
+        });
+      }
+    });
 
     if (validTransactions.length === 0) {
       this.logger.info('No transactions to execute after gas estimation.');
-      return {
-        gasEstimationFailures,
-        transactionFailures: 0,
-        successfulTransactions: [],
-      };
+      return results;
     }
 
-    // 2. Send transactions
+    // 3. Group transactions by origin chain
+    const txsByOrigin = new Map<ChainName, PreparedTransaction[]>();
+    for (const tx of validTransactions) {
+      const origin = tx.route.origin;
+      if (!txsByOrigin.has(origin)) {
+        txsByOrigin.set(origin, []);
+      }
+      txsByOrigin.get(origin)!.push(tx);
+    }
+
+    // 4. Send transactions - parallel across chains, sequential within each chain
     this.logger.info(
-      { numTransactions: validTransactions.length },
-      'Sending valid transactions.',
+      {
+        numChains: txsByOrigin.size,
+        numTransactions: validTransactions.length,
+      },
+      'Sending transactions (parallel across chains, sequential within chain).',
+    );
+
+    const chainSendResults = await Promise.allSettled(
+      Array.from(txsByOrigin.entries()).map(([origin, txs]) =>
+        this.sendTransactionsForChain(origin, txs),
+      ),
     );
-    let transactionFailures = 0;
-    const successfulTransactions: PreparedTransaction[] = [];
-    for (const transaction of validTransactions) {
+
+    // 5. Collect successful sends and record send failures
+    const successfulSends: Array<{
+      transaction: PreparedTransaction;
+      receipt: providers.TransactionReceipt;
+    }> = [];
+
+    chainSendResults.forEach((chainResult) => {
+      if (chainResult.status === 'fulfilled') {
+        for (const txResult of chainResult.value) {
+          if ('receipt' in txResult) {
+            successfulSends.push(txResult);
+          } else {
+            results.push({
+              route: txResult.transaction.route,
+              success: false,
+              error: `Transaction send failed: ${txResult.error}`,
+            });
+            this.metrics?.recordActionAttempt(
+              txResult.transaction.route,
+              false,
+            );
+          }
+        }
+      } else {
+        // This shouldn't happen since sendTransactionsForChain catches errors internally,
+        // but handle it just in case
+        this.logger.error(
+          { error: chainResult.reason },
+          'Unexpected error during chain transaction sending.',
+        );
+      }
+    });
+
+    // 6. Build results from confirmed receipts
+    for (const { transaction, receipt } of successfulSends) {
+      const result = this.buildResult(transaction, receipt);
+      results.push(result);
+      this.metrics?.recordActionAttempt(result.route, result.success);
+    }
+
+    return results;
+  }
+
+  // === Parallel Transaction Sending Methods ===
+
+  /**
+   * Send all transactions for a single origin chain sequentially.
+   * Sequential sending is required to avoid nonce contention when using the same signing key.
+   */
+  private async sendTransactionsForChain(
+    origin: ChainName,
+    transactions: PreparedTransaction[],
+  ): Promise<
+    Array<
+      | {
+          transaction: PreparedTransaction;
+          receipt: providers.TransactionReceipt;
+        }
+      | { transaction: PreparedTransaction; error: string }
+    >
+  > {
+    const results: Array<
+      | {
+          transaction: PreparedTransaction;
+          receipt: providers.TransactionReceipt;
+        }
+      | { transaction: PreparedTransaction; error: string }
+    > = [];
+
+    // Send sequentially to avoid nonce contention
+    for (const transaction of transactions) {
       try {
-        const { origin, destination } = transaction.route;
         const decimalFormattedAmount =
           transaction.originTokenAmount.getDecimalFormattedAmount();
         const tokenName = transaction.originTokenAmount.token.name;
+
+        const reorgPeriod = this.getReorgPeriod(origin);
+
         this.logger.info(
           {
             origin,
-            destination,
+            destination: transaction.route.destination,
             amount: decimalFormattedAmount,
             tokenName,
+            reorgPeriod,
           },
-          'Sending transaction for route.',
+          'Sending rebalance transaction and waiting for reorgPeriod confirmations.',
         );
+
         const receipt = await this.multiProvider.sendTransaction(
           origin,
           transaction.populatedTx,
+          {
+            waitConfirmations: reorgPeriod as
+              | number
+              | EthJsonRpcBlockParameterTag,
+          },
         );
+
         this.logger.info(
           {
             origin,
-            destination,
+            destination: transaction.route.destination,
             amount: decimalFormattedAmount,
             tokenName,
             txHash: receipt.transactionHash,
           },
-          'Transaction confirmed for route.',
+          'Rebalance transaction confirmed at reorgPeriod depth.',
         );
-        successfulTransactions.push(transaction);
+
+        results.push({ transaction, receipt });
       } catch (error) {
-        transactionFailures++;
         this.logger.error(
           {
-            origin: transaction.route.origin,
+            origin,
             destination: transaction.route.destination,
             amount: transaction.originTokenAmount.getDecimalFormattedAmount(),
             tokenName: transaction.originTokenAmount.token.name,
             error,
           },
-          'Transaction failed for route.',
+          'Transaction send failed for route.',
         );
+        results.push({ transaction, error: String(error) });
       }
     }
 
-    return {
-      gasEstimationFailures,
-      transactionFailures,
-      successfulTransactions,
-    };
+    return results;
   }
 
-  private filterTransactions(
-    transactions: PreparedTransaction[],
-  ): PreparedTransaction[] {
-    const filteredTransactions: PreparedTransaction[] = [];
-    for (const transaction of transactions) {
-      const { origin, destination, amount } = transaction.route;
-      const originToken = this.tokensByChainName[origin];
-      const decimalFormattedAmount =
-        transaction.originTokenAmount.getDecimalFormattedAmount();
-
-      // minimum amount check
-      const { bridgeMinAcceptedAmount } = getBridgeConfig(
-        this.bridges,
-        origin,
-        destination,
-        this.logger,
-      );
-      const minAccepted = BigInt(
-        toWei(bridgeMinAcceptedAmount, originToken.decimals),
+  /**
+   * Build the execution result from a confirmed transaction receipt.
+   * Receipt is already confirmed at reorgPeriod depth from sendTransaction.
+   */
+  private buildResult(
+    transaction: PreparedTransaction,
+    receipt: providers.TransactionReceipt,
+  ): RebalanceExecutionResult {
+    const { origin, destination } = transaction.route;
+    const dispatchedMessages = HyperlaneCore.getDispatchedMessages(receipt);
+
+    if (dispatchedMessages.length === 0) {
+      this.logger.error(
+        { origin, destination, txHash: receipt.transactionHash },
+        'No Dispatch event found in confirmed rebalance receipt',
       );
-      if (minAccepted > amount) {
-        this.logger.info(
-          {
-            origin,
-            destination,
-            amount: decimalFormattedAmount,
-            tokenName: originToken.name,
-          },
-          'Route skipped due to minimum threshold amount not met.',
-        );
-        continue;
-      }
-      filteredTransactions.push(transaction);
+      return {
+        route: transaction.route,
+        success: false,
+        error: `Transaction confirmed but no Dispatch event found`,
+        txHash: receipt.transactionHash,
+      };
     }
-    return filteredTransactions;
+
+    return {
+      route: transaction.route,
+      success: true,
+      messageId: dispatchedMessages[0].id,
+      txHash: receipt.transactionHash,
+    };
+  }
+
+  private getReorgPeriod(chainName: string): number | string {
+    const metadata = this.multiProvider.getChainMetadata(chainName);
+    return metadata.blocks?.reorgPeriod ?? 32;
   }
 }