@hyperlane-xyz/rebalancer 0.1.2 → 1.0.0

package/src/strategy/BaseStrategy.ts

@@ -1,13 +1,21 @@
 import { type Logger } from 'pino';
 
-import type { ChainName } from '@hyperlane-xyz/sdk';
+import type { ChainMap, ChainName, Token } from '@hyperlane-xyz/sdk';
+import { toWei } from '@hyperlane-xyz/utils';
 
 import type {
   IStrategy,
+  InflightContext,
   RawBalances,
-  RebalancingRoute,
+  Route,
+  StrategyRoute,
 } from '../interfaces/IStrategy.js';
 import { type Metrics } from '../metrics/Metrics.js';
+import {
+  type BridgeConfig,
+  type BridgeConfigWithOverride,
+  getBridgeConfig,
+} from '../utils/bridgeUtils.js';
 
 export type Delta = { chain: ChainName; amount: bigint };
 
@@ -15,41 +23,81 @@ export type Delta = { chain: ChainName; amount: bigint };
  * Base abstract class for rebalancing strategies
  */
 export abstract class BaseStrategy implements IStrategy {
+  abstract readonly name: string;
   protected readonly chains: ChainName[];
   protected readonly metrics?: Metrics;
   protected readonly logger: Logger;
+  protected readonly bridgeConfigs: ChainMap<BridgeConfigWithOverride>;
+  protected readonly tokensByChainName?: ChainMap<Token>;
 
-  constructor(chains: ChainName[], logger: Logger, metrics?: Metrics) {
+  constructor(
+    chains: ChainName[],
+    logger: Logger,
+    bridgeConfigs: ChainMap<BridgeConfigWithOverride>,
+    metrics?: Metrics,
+    tokensByChainName?: ChainMap<Token>,
+  ) {
     // Rebalancing makes sense only with more than one chain.
     if (chains.length < 2) {
       throw new Error('At least two chains must be configured');
     }
     this.chains = chains;
     this.logger = logger;
+    this.bridgeConfigs = bridgeConfigs;
     this.metrics = metrics;
+    this.tokensByChainName = tokensByChainName;
+  }
+
+  protected getBridgeConfigForRoute(
+    origin: ChainName,
+    destination: ChainName,
+  ): BridgeConfig {
+    return getBridgeConfig(this.bridgeConfigs, origin, destination);
   }
 
   /**
    * Main method to get rebalancing routes
    */
-  getRebalancingRoutes(rawBalances: RawBalances): RebalancingRoute[] {
-    this.logger.info(
-      {
-        context: this.constructor.name,
-        rawBalances,
-      },
-      'Input rawBalances',
-    );
+  getRebalancingRoutes(
+    rawBalances: RawBalances,
+    inflightContext?: InflightContext,
+  ): StrategyRoute[] {
+    const pendingRebalances = inflightContext?.pendingRebalances ?? [];
+    const pendingTransfers = inflightContext?.pendingTransfers ?? [];
+    const proposedRebalances = inflightContext?.proposedRebalances ?? [];
+
     this.logger.info(
       {
-        context: this.constructor.name,
+        strategy: this.name,
+        balances: Object.entries(rawBalances).map(([c, b]) => ({
+          chain: c,
+          balance: b.toString(),
+        })),
+        pendingRebalances: pendingRebalances.length,
+        pendingTransfers: pendingTransfers.length,
+        proposedRebalances: proposedRebalances.length,
       },
-      'Calculating rebalancing routes',
+      'Strategy evaluating',
     );
     this.validateRawBalances(rawBalances);
 
+    // Store original balances for filtering step
+    const actualBalances = rawBalances;
+
+    // Step 1: Reserve collateral for pending user transfers
+    // This prevents draining collateral needed for incoming user transfers
+    const effectiveBalances = this.reserveCollateral(
+      rawBalances,
+      pendingTransfers,
+    );
+
     // Get balances categorized by surplus and deficit
-    const { surpluses, deficits } = this.getCategorizedBalances(rawBalances);
+    // Pass pending and proposed rebalances so strategy can account for them
+    const { surpluses, deficits } = this.getCategorizedBalances(
+      effectiveBalances,
+      pendingRebalances,
+      proposedRebalances,
+    );
 
     this.logger.debug(
       {
@@ -126,7 +174,7 @@ export abstract class BaseStrategy implements IStrategy {
     surpluses.sort((a, b) => (a.amount > b.amount ? -1 : 1));
     deficits.sort((a, b) => (a.amount > b.amount ? -1 : 1));
 
-    const routes: RebalancingRoute[] = [];
+    const routes: StrategyRoute[] = [];
 
     // Transfer from surplus to deficit until all deficits are balanced.
     while (deficits.length > 0 && surpluses.length > 0) {
@@ -137,24 +185,34 @@ export abstract class BaseStrategy implements IStrategy {
       const transferAmount =
         surplus.amount > deficit.amount ? deficit.amount : surplus.amount;
 
-      // Creates the balancing route
-      routes.push({
-        origin: surplus.chain,
-        destination: deficit.chain,
-        amount: transferAmount,
-      });
+      // Skip zero-amount routes (can occur after scaling when surpluses < deficits)
+      if (transferAmount > 0n) {
+        // Get bridge config for this route (with destination-specific overrides)
+        const bridgeConfig = this.getBridgeConfigForRoute(
+          surplus.chain,
+          deficit.chain,
+        );
+
+        // Creates the balancing route
+        routes.push({
+          origin: surplus.chain,
+          destination: deficit.chain,
+          amount: transferAmount,
+          bridge: bridgeConfig.bridge,
+        });
+      }
 
       // Decreases the amounts for the following iterations
       deficit.amount -= transferAmount;
       surplus.amount -= transferAmount;
 
-      // Removes the deficit if it is fully balanced
-      if (!deficit.amount) {
+      // Removes the deficit if it is fully balanced (including scaled-to-zero)
+      if (deficit.amount <= 0n) {
         deficits.shift();
       }
 
       // Removes the surplus if it has been drained
-      if (!surplus.amount) {
+      if (surplus.amount <= 0n) {
         surpluses.shift();
       }
     }
@@ -173,14 +231,40 @@ export abstract class BaseStrategy implements IStrategy {
       },
       'Found rebalancing routes',
     );
-    return routes;
+
+    const filteredRoutes = this.filterRoutes(routes, actualBalances);
+
+    this.logger.debug(
+      {
+        context: this.constructor.name,
+        filteredRoutesCount: filteredRoutes.length,
+        droppedCount: routes.length - filteredRoutes.length,
+      },
+      'Filtered rebalancing routes',
+    );
+
+    // Record metrics for each intent that passed filtering
+    for (const route of filteredRoutes) {
+      this.metrics?.recordIntentCreated(route, this.name);
+    }
+
+    return filteredRoutes;
   }
 
   /**
    * Abstract method to get balances categorized by surplus and deficit
    * Each specific strategy should implement its own logic
+   *
+   * @param balances - Effective balances (after collateral reservation)
+   * @param pendingRebalances - In-flight rebalances (origin tx confirmed, balance already deducted)
+   * @param proposedRebalances - Routes from earlier strategies in same cycle (not yet executed)
+   * @returns Categorized surpluses and deficits as Delta arrays
    */
-  protected abstract getCategorizedBalances(rawBalances: RawBalances): {
+  protected abstract getCategorizedBalances(
+    balances: RawBalances,
+    pendingRebalances?: Route[],
+    proposedRebalances?: StrategyRoute[],
+  ): {
     surpluses: Delta[];
     deficits: Delta[];
   };
@@ -207,4 +291,210 @@ export abstract class BaseStrategy implements IStrategy {
       }
     }
   }
+
+  /**
+   * Reserve collateral for pending user transfers.
+   * Subtracts pending transfer amounts from destination balances.
+   * This ensures we don't drain collateral needed for incoming transfers.
+   *
+   * @param rawBalances - Current on-chain balances
+   * @param pendingTransfers - Transfers that will need collateral on destination
+   * @returns Balances with reserved amounts subtracted
+   */
+  protected reserveCollateral(
+    rawBalances: RawBalances,
+    pendingTransfers: Route[],
+  ): RawBalances {
+    if (pendingTransfers.length === 0) {
+      return rawBalances;
+    }
+
+    const reserved = { ...rawBalances };
+
+    for (const transfer of pendingTransfers) {
+      const destBalance = reserved[transfer.destination] ?? 0n;
+      // Reserve the transfer amount from destination
+      // Allow negative values to indicate collateral deficits
+      reserved[transfer.destination] = destBalance - transfer.amount;
+
+      this.logger.debug(
+        {
+          context: this.constructor.name,
+          destination: transfer.destination,
+          amount: transfer.amount.toString(),
+          newBalance: reserved[transfer.destination].toString(),
+        },
+        'Reserved collateral for pending transfer',
+      );
+    }
+
+    this.logger.info(
+      {
+        reservations: pendingTransfers.map((t) => ({
+          destination: t.destination,
+          amount: t.amount.toString(),
+        })),
+      },
+      'Collateral reserved for pending transfers',
+    );
+
+    return reserved;
+  }
+
+  /**
+   * Simulate pending rebalances by adding to destination balances.
+   *
+   * Only adds to destination - does NOT subtract from origin because:
+   * - pendingRebalances only contains in_progress intents (origin tx confirmed)
+   * - Origin balance is already deducted on-chain
+   *
+   * @param rawBalances - Current balances (may already have collateral reserved)
+   * @param pendingRebalances - In-flight rebalance operations (in_progress only)
+   * @returns Simulated future balances after rebalances complete
+   */
+  protected simulatePendingRebalances(
+    rawBalances: RawBalances,
+    pendingRebalances: Route[],
+  ): RawBalances {
+    if (pendingRebalances.length === 0) {
+      return rawBalances;
+    }
+
+    const simulated = { ...rawBalances };
+
+    for (const rebalance of pendingRebalances) {
+      // Only add to destination - origin is already deducted on-chain
+      // (pendingRebalances only contains in_progress intents with confirmed origin tx)
+      simulated[rebalance.destination] =
+        (simulated[rebalance.destination] ?? 0n) + rebalance.amount;
+
+      this.logger.debug(
+        {
+          context: this.constructor.name,
+          destination: rebalance.destination,
+          amount: rebalance.amount.toString(),
+        },
+        'Simulated pending rebalance (destination increase)',
+      );
+    }
+
+    this.logger.info(
+      {
+        simulations: pendingRebalances.map((r) => ({
+          from: r.origin,
+          to: r.destination,
+          amount: r.amount.toString(),
+        })),
+      },
+      'Simulated pending rebalances',
+    );
+
+    return simulated;
+  }
+
+  /**
+   * Simulate proposed rebalances by subtracting from origin AND adding to destination.
+   *
+   * Unlike pendingRebalances, proposedRebalances are routes from earlier strategies
+   * in the same cycle that haven't been executed yet. Therefore:
+   * - Origin balance has NOT been deducted on-chain
+   * - We must simulate both sides to maintain accurate total balance
+   *
+   * @param rawBalances - Current balances (may already have pending rebalances simulated)
+   * @param proposedRebalances - Routes from earlier strategies (not yet executed)
+   * @returns Simulated balances after proposed rebalances complete
+   */
+  protected simulateProposedRebalances(
+    rawBalances: RawBalances,
+    proposedRebalances: Route[],
+  ): RawBalances {
+    if (proposedRebalances.length === 0) {
+      return rawBalances;
+    }
+
+    const simulated = { ...rawBalances };
+
+    for (const rebalance of proposedRebalances) {
+      // Subtract from origin (not yet deducted on-chain)
+      simulated[rebalance.origin] =
+        (simulated[rebalance.origin] ?? 0n) - rebalance.amount;
+
+      // Add to destination
+      simulated[rebalance.destination] =
+        (simulated[rebalance.destination] ?? 0n) + rebalance.amount;
+
+      this.logger.debug(
+        {
+          context: this.constructor.name,
+          origin: rebalance.origin,
+          destination: rebalance.destination,
+          amount: rebalance.amount.toString(),
+        },
+        'Simulated proposed rebalance (origin decrease, destination increase)',
+      );
+    }
+
+    this.logger.info(
+      {
+        simulations: proposedRebalances.map((r) => ({
+          from: r.origin,
+          to: r.destination,
+          amount: r.amount.toString(),
+        })),
+      },
+      'Simulated proposed rebalances',
+    );
+
+    return simulated;
+  }
+
+  protected filterRoutes(
+    routes: StrategyRoute[],
+    actualBalances: RawBalances,
+  ): StrategyRoute[] {
+    return routes.filter((route) => {
+      const balance = actualBalances[route.origin] ?? 0n;
+      if (balance < route.amount) {
+        this.logger.warn(
+          {
+            context: this.constructor.name,
+            origin: route.origin,
+            destination: route.destination,
+            required: route.amount.toString(),
+            available: balance.toString(),
+          },
+          'Dropping route due to insufficient balance',
+        );
+        return false;
+      }
+
+      if (this.tokensByChainName) {
+        const token = this.tokensByChainName[route.origin];
+        if (token) {
+          const bridgeConfig = this.getBridgeConfigForRoute(
+            route.origin,
+            route.destination,
+          );
+          const minAmount = BigInt(
+            toWei(bridgeConfig.bridgeMinAcceptedAmount, token.decimals),
+          );
+          if (route.amount < minAmount) {
+            this.logger.info(
+              {
+                context: this.constructor.name,
+                origin: route.origin,
+                destination: route.destination,
+                amount: route.amount.toString(),
+                minAmount: minAmount.toString(),
+              },
+              'Dropping route below bridgeMinAcceptedAmount',
+            );
+            return false;
+          }
+        }
+      }
+
+      return true;
+    });
+  }
 }