@hyperlane-xyz/rebalancer 2.0.0 → 3.0.0

package/src/e2e/harness/BridgeSetup.ts

@@ -1,6 +1,9 @@
 import { BigNumber, ethers, providers } from 'ethers';
 
-import { ERC20__factory } from '@hyperlane-xyz/core';
+import {
+  ERC20__factory,
+  MovableCollateralRouter__factory,
+} from '@hyperlane-xyz/core';
 
 export async function setupCollateralBalances(
   providers: Map<string, providers.JsonRpcProvider>,
@@ -65,3 +68,27 @@ export async function getAllCollateralBalances(
   }
   return balances;
 }
+
+export interface AllowedBridgeConfig {
+  monitoredRouterAddress: string;
+  bridgeAddress: string;
+  destinationDomain: number;
+}
+
+export async function configureAllowedBridges(
+  provider: providers.JsonRpcProvider,
+  configs: AllowedBridgeConfig[],
+  deployerKey: string,
+): Promise<void> {
+  if (configs.length === 0) return;
+
+  const deployer = new ethers.Wallet(deployerKey, provider);
+  const router = MovableCollateralRouter__factory.connect(
+    configs[0].monitoredRouterAddress,
+    deployer,
+  );
+
+  for (const config of configs) {
+    await router.addBridge(config.destinationDomain, config.bridgeAddress);
+  }
+}

package/src/e2e/harness/TestHelpers.ts

@@ -22,9 +22,6 @@ export async function getFirstMonitorEvent(
       reject(error);
     });
 
-    monitor.start().catch((err: unknown) => {
-      clearTimeout(timeout);
-      reject(err instanceof Error ? err : new Error(String(err)));
-    });
+    void monitor.start();
   });
 }

package/src/e2e/harness/TestRebalancer.ts

@@ -21,7 +21,7 @@ import { RebalancerContextFactory } from '../../factories/RebalancerContextFacto
 import type { ConfirmedBlockTags } from '../../interfaces/IMonitor.js';
 import type { IStrategy } from '../../interfaces/IStrategy.js';
 import type { Monitor } from '../../monitor/Monitor.js';
-import type { IActionTracker } from '../../tracking/index.js';
+import type { IActionTracker } from '../../tracking/IActionTracker.js';
 import type { ExplorerMessage } from '../../utils/ExplorerClient.js';
 import {
   ANVIL_TEST_PRIVATE_KEY,
@@ -212,6 +212,7 @@ export class TestRebalancerBuilder {
     const contextFactory = await RebalancerContextFactory.create(
       rebalancerConfig,
       workingMultiProvider,
+      undefined,
       mpp,
       registry,
       this.logger,
@@ -225,18 +226,17 @@ export class TestRebalancerBuilder {
     await tracker.initialize();
     this.logger.info('ActionTracker initialized with mock explorer');
 
-    // In execute mode, create an actual Rebalancer to enable intent creation and execution
-    const rebalancer =
+    // In execute mode, create actual Rebalancers to enable intent creation and execution
+    const rebalancers =
       this.executionMode === 'execute'
-        ? contextFactory.createRebalancer()
-        : undefined;
+        ? (await contextFactory.createRebalancers(tracker)).rebalancers
+        : [];
 
     const orchestratorDeps: RebalancerOrchestratorDeps = {
       strategy,
-      rebalancer,
+      rebalancers,
       actionTracker: tracker,
       inflightContextAdapter: adapter,
-      multiProvider: workingMultiProvider,
       rebalancerConfig,
       logger: this.logger,
     };

package/src/e2e/minAmount.e2e-test.ts

@@ -212,7 +212,7 @@ describe('MinAmountStrategy E2E', function () {
       hyperlaneCore,
       {
         dispatchTx: rebalanceTxReceipt,
-        messageId: actionToArbitrum.messageId,
+        messageId: actionToArbitrum.messageId!,
         origin: 'anvil1',
         destination: 'anvil2',
       },
@@ -236,7 +236,6 @@ describe('MinAmountStrategy E2E', function () {
       activeIntents[0].id,
     );
     expect(completedIntent!.status).to.equal('complete');
-    expect(completedIntent!.fulfilledAmount).to.equal(70000000n);
   });
 
   it('should handle stuck transfer and propose routes to destination', async function () {

package/src/e2e/weighted.e2e-test.ts

@@ -194,7 +194,7 @@ describe('WeightedStrategy E2E', function () {
       hyperlaneCore,
       {
         dispatchTx: rebalanceTxReceipt,
-        messageId: actionToBase.messageId,
+        messageId: actionToBase.messageId!,
         origin: 'anvil1',
         destination: 'anvil3',
       },
@@ -218,7 +218,6 @@ describe('WeightedStrategy E2E', function () {
       activeIntents[0].id,
     );
     expect(completedIntent!.status).to.equal('complete');
-    expect(completedIntent!.fulfilledAmount).to.equal(1000000000n);
 
     // Assert: No more in-progress actions
     const remainingActions = await context.tracker.getInProgressActions();

package/src/factories/RebalancerContextFactory.ts

@@ -11,35 +11,47 @@ import {
   WarpCore,
   type WarpCoreConfig,
 } from '@hyperlane-xyz/sdk';
-import { objMap } from '@hyperlane-xyz/utils';
+import { objMap, toWei } from '@hyperlane-xyz/utils';
 
+import { LiFiBridge } from '../bridges/LiFiBridge.js';
 import { type RebalancerConfig } from '../config/RebalancerConfig.js';
-import { getAllBridges, getStrategyChainNames } from '../config/types.js';
+import {
+  ExecutionType,
+  ExternalBridgeType,
+  getAllBridges,
+  getStrategyChainConfig,
+  getStrategyChainNames,
+} from '../config/types.js';
+import { InventoryRebalancer } from '../core/InventoryRebalancer.js';
 import { Rebalancer } from '../core/Rebalancer.js';
+import { RebalancerOrchestrator } from '../core/RebalancerOrchestrator.js';
+import type { ExternalBridgeRegistry } from '../interfaces/IExternalBridge.js';
 import type { IRebalancer } from '../interfaces/IRebalancer.js';
 import type { IStrategy } from '../interfaces/IStrategy.js';
 import { Metrics } from '../metrics/Metrics.js';
 import { PriceGetter } from '../metrics/PriceGetter.js';
-import { Monitor } from '../monitor/Monitor.js';
+import { type InventoryMonitorConfig, Monitor } from '../monitor/Monitor.js';
 import { StrategyFactory } from '../strategy/StrategyFactory.js';
 import {
   ActionTracker,
   type ActionTrackerConfig,
-  type IActionTracker,
-  InMemoryStore,
-  InflightContextAdapter,
-  type RebalanceAction,
-  type RebalanceActionStatus,
-  type RebalanceIntent,
-  type RebalanceIntentStatus,
-  type Transfer,
-  type TransferStatus,
-} from '../tracking/index.js';
+} from '../tracking/ActionTracker.js';
+import type { IActionTracker } from '../tracking/IActionTracker.js';
+import { InflightContextAdapter } from '../tracking/InflightContextAdapter.js';
+import { InMemoryStore } from '../tracking/store/index.js';
+import type {
+  RebalanceAction,
+  RebalanceActionStatus,
+  RebalanceIntent,
+  RebalanceIntentStatus,
+  Transfer,
+  TransferStatus,
+} from '../tracking/types.js';
 import {
   ExplorerClient,
   type IExplorerClient,
 } from '../utils/ExplorerClient.js';
-import { isCollateralizedTokenEligibleForRebalancing } from '../utils/index.js';
+import { isCollateralizedTokenEligibleForRebalancing } from '../utils/tokenUtils.js';
 
 const DEFAULT_EXPLORER_URL =
   process.env.EXPLORER_API_URL || 'https://explorer4.hasura.app/v1/graphql';
@@ -49,7 +61,8 @@ export class RebalancerContextFactory {
    * @param config - The rebalancer config
    * @param warpCore - An instance of `WarpCore` configured for the specified `warpRouteId`.
    * @param tokensByChainName - A map of chain->token to ease the lookup of token by chain
-   * @param multiProvider - MultiProvider instance
+   * @param multiProvider - MultiProvider instance (for movable collateral operations)
+   * @param inventoryMultiProvider - MultiProvider instance for inventory operations (optional)
    * @param multiProtocolProvider - MultiProtocolProvider instance (with mailbox metadata)
    * @param registry - IRegistry instance
    * @param logger - Logger instance
@@ -59,14 +72,24 @@ export class RebalancerContextFactory {
     private readonly warpCore: WarpCore,
     private readonly tokensByChainName: ChainMap<Token>,
     private readonly multiProvider: MultiProvider,
+    private readonly inventoryMultiProvider: MultiProvider | undefined,
     private readonly multiProtocolProvider: MultiProtocolProvider,
     private readonly registry: IRegistry,
     private readonly logger: Logger,
   ) {}
 
+  /**
+   * @param config - The rebalancer config
+   * @param multiProvider - MultiProvider instance (for movable collateral operations)
+   * @param inventoryMultiProvider - MultiProvider instance for inventory operations (optional)
+   * @param multiProtocolProvider - MultiProtocolProvider instance (optional, created from multiProvider if not provided)
+   * @param registry - IRegistry instance
+   * @param logger - Logger instance
+   */
   public static async create(
     config: RebalancerConfig,
     multiProvider: MultiProvider,
+    inventoryMultiProvider: MultiProvider | undefined,
     multiProtocolProvider: MultiProtocolProvider | undefined,
     registry: IRegistry,
     logger: Logger,
@@ -78,18 +101,15 @@ export class RebalancerContextFactory {
       },
       'Creating RebalancerContextFactory',
     );
+
+    // TODO: should we pull addressed for chains we care about, i.e those in the warp config
     const addresses = await registry.getAddresses();
 
     // The Sealevel warp adapters require the Mailbox address, so we
     // get mailboxes for all chains and merge them with the chain metadata.
     const mailboxes = objMap(addresses, (_, { mailbox }) => ({ mailbox }));
 
-    // Create MultiProtocolProvider (convert from MultiProvider if not provided)
-    const mpp =
-      multiProtocolProvider ??
-      MultiProtocolProvider.fromMultiProvider(multiProvider);
-    const extendedMultiProtocolProvider = mpp.extendChainMetadata(mailboxes);
-
+    // Fetch warp route config FIRST to get chain list
     const warpCoreConfig =
       warpCoreConfigOverride ??
       (await registry.getWarpRoute(config.warpRouteId));
@@ -98,6 +118,22 @@ export class RebalancerContextFactory {
         `Warp route config for ${config.warpRouteId} not found in registry`,
       );
     }
+
+    // Force-initialize providers for all warp route chains
+    // This ensures fromMultiProvider() snapshots actual provider instances
+    const warpChains = [
+      ...new Set(warpCoreConfig.tokens.map((t: any) => t.chainName)),
+    ];
+    for (const chain of warpChains) {
+      multiProvider.getProvider(chain);
+    }
+
+    // Create MultiProtocolProvider (convert from MultiProvider if not provided)
+    const mpp =
+      multiProtocolProvider ??
+      MultiProtocolProvider.fromMultiProvider(multiProvider);
+    const extendedMultiProtocolProvider = mpp.extendChainMetadata(mailboxes);
+
     const warpCore = WarpCore.FromConfig(
       extendedMultiProtocolProvider,
       warpCoreConfig,
@@ -117,6 +153,7 @@ export class RebalancerContextFactory {
       warpCore,
       tokensByChainName,
       multiProvider,
+      inventoryMultiProvider,
       extendedMultiProtocolProvider,
       registry,
       logger,
@@ -154,7 +191,10 @@ export class RebalancerContextFactory {
     );
   }
 
-  public createMonitor(checkFrequency: number): Monitor {
+  public createMonitor(
+    checkFrequency: number,
+    inventoryConfig?: InventoryMonitorConfig,
+  ): Monitor {
     this.logger.debug(
       {
         warpRouteId: this.config.warpRouteId,
@@ -162,7 +202,12 @@ export class RebalancerContextFactory {
       },
       'Creating Monitor',
     );
-    return new Monitor(checkFrequency, this.warpCore, this.logger);
+    return new Monitor(
+      checkFrequency,
+      this.warpCore,
+      this.logger,
+      inventoryConfig,
+    );
   }
 
   public async createStrategy(metrics?: Metrics): Promise<IStrategy> {
@@ -177,16 +222,48 @@ export class RebalancerContextFactory {
       },
       'Creating Strategy',
     );
+
+    // Build minAmountsByChain from chain configs
+    const chainNames = getStrategyChainNames(this.config.strategyConfig);
+    const minAmountsByChain: ChainMap<bigint> = {};
+
+    for (const chainName of chainNames) {
+      const chainConfig = getStrategyChainConfig(
+        this.config.strategyConfig,
+        chainName,
+      );
+      if (chainConfig?.bridgeMinAcceptedAmount) {
+        const token = this.tokensByChainName[chainName];
+        const decimals = token?.decimals ?? 18;
+        minAmountsByChain[chainName] = BigInt(
+          toWei(chainConfig.bridgeMinAcceptedAmount, decimals),
+        );
+      }
+    }
+
+    this.logger.debug(
+      {
+        minAmountsByChain: Object.fromEntries(
+          Object.entries(minAmountsByChain).map(([k, v]) => [k, v.toString()]),
+        ),
+      },
+      'Built minimum amounts by chain for strategy',
+    );
+
     return StrategyFactory.createStrategy(
       this.config.strategyConfig,
       this.tokensByChainName,
       await this.getInitialTotalCollateral(),
       this.logger,
       metrics,
+      minAmountsByChain,
     );
   }
 
-  public createRebalancer(metrics?: Metrics): IRebalancer {
+  private createMovableCollateralRebalancer(
+    actionTracker: IActionTracker,
+    metrics?: Metrics,
+  ): IRebalancer {
     this.logger.debug(
       { warpRouteId: this.config.warpRouteId },
       'Creating Rebalancer',
@@ -197,6 +274,7 @@ export class RebalancerContextFactory {
       this.multiProvider.metadata,
       this.tokensByChainName,
       this.multiProvider,
+      actionTracker,
       this.logger,
       metrics,
     );
@@ -272,6 +350,7 @@ export class RebalancerContextFactory {
       routersByDomain,
       bridges,
       rebalancerAddress,
+      inventorySignerAddress: this.config.inventorySigner,
     };
 
     // 6. Create ActionTracker
@@ -301,6 +380,196 @@ export class RebalancerContextFactory {
     return { tracker, adapter };
   }
 
+  /**
+   * Creates inventory components for inventory-based rebalancing.
+   * Returns null if inventory config is not available.
+   *
+   * @param actionTracker - ActionTracker instance for tracking inventory actions
+   */
+  private async createInventoryRebalancerAndConfig(
+    actionTracker: IActionTracker,
+  ): Promise<{
+    inventoryRebalancer: IRebalancer;
+    externalBridgeRegistry: Partial<ExternalBridgeRegistry>;
+    inventoryConfig: InventoryMonitorConfig;
+  } | null> {
+    const { inventorySigner, externalBridges } = this.config;
+
+    if (!inventorySigner) {
+      this.logger.debug(
+        'Inventory config not available, skipping inventory components creation',
+      );
+      return null;
+    }
+
+    this.logger.debug(
+      { warpRouteId: this.config.warpRouteId, inventorySigner },
+      'Creating inventory components',
+    );
+
+    const inventoryChains = getStrategyChainNames(
+      this.config.strategyConfig,
+    ).filter((chainName) => {
+      const chainConfig = getStrategyChainConfig(
+        this.config.strategyConfig,
+        chainName,
+      );
+      return chainConfig?.executionType === ExecutionType.Inventory;
+    });
+
+    if (inventoryChains.length === 0) {
+      this.logger.debug('No inventory chains configured');
+      return null;
+    }
+
+    // Build registry dynamically from ExternalBridgeType enum
+    const externalBridgeRegistry: Partial<ExternalBridgeRegistry> = {};
+
+    for (const bridgeType of Object.values(ExternalBridgeType)) {
+      switch (bridgeType) {
+        case ExternalBridgeType.LiFi: {
+          const lifiConfig = externalBridges?.lifi;
+          if (lifiConfig?.integrator) {
+            externalBridgeRegistry[ExternalBridgeType.LiFi] = new LiFiBridge(
+              {
+                integrator: lifiConfig.integrator,
+                defaultSlippage: lifiConfig.defaultSlippage,
+                chainMetadata: this.multiProvider.metadata,
+              },
+              this.logger,
+            );
+          }
+          break;
+        }
+        default: {
+          // Exhaustive check - TypeScript will error if new enum value added
+          const _exhaustive: never = bridgeType;
+          throw new Error(`Unknown bridge type: ${_exhaustive}`);
+        }
+      }
+    }
+
+    if (Object.keys(externalBridgeRegistry).length === 0) {
+      this.logger.debug(
+        'No external bridges configured, skipping inventory components',
+      );
+      return null;
+    }
+
+    // 3. Build inventory config
+    const inventoryConfig: InventoryMonitorConfig = {
+      inventoryAddress: inventorySigner,
+      chains: inventoryChains,
+    };
+
+    // 4. Create InventoryRebalancer
+    // Use inventoryMultiProvider for inventory operations if available, otherwise fall back to multiProvider
+    const inventoryRebalancer = new InventoryRebalancer(
+      {
+        inventorySigner,
+        inventoryMultiProvider: this.inventoryMultiProvider,
+        inventoryChains,
+      },
+      actionTracker,
+      externalBridgeRegistry,
+      this.warpCore,
+      this.multiProvider,
+      this.logger,
+    );
+
+    this.logger.info(
+      {
+        inventoryChains,
+        inventorySigner,
+      },
+      'Inventory components created successfully',
+    );
+
+    return { inventoryRebalancer, externalBridgeRegistry, inventoryConfig };
+  }
+
+  /**
+   * Creates all rebalancers based on config execution types.
+   * Returns an array of rebalancers (movableCollateral and/or inventory)
+   * along with metadata needed for monitor and orchestrator.
+   */
+  public async createRebalancers(
+    actionTracker: IActionTracker,
+    metrics?: Metrics,
+  ): Promise<{
+    rebalancers: IRebalancer[];
+    externalBridgeRegistry: Partial<ExternalBridgeRegistry>;
+    inventoryConfig?: InventoryMonitorConfig;
+  }> {
+    const rebalancers: IRebalancer[] = [];
+    let externalBridgeRegistry: Partial<ExternalBridgeRegistry> = {};
+    let inventoryConfig: InventoryMonitorConfig | undefined;
+
+    // Check if any chains use movableCollateral execution type
+    const hasMovableCollateral = this.hasMovableCollateralChains();
+    if (hasMovableCollateral) {
+      const rebalancer = this.createMovableCollateralRebalancer(
+        actionTracker,
+        metrics,
+      );
+      rebalancers.push(rebalancer);
+    }
+
+    // Check if any chains use inventory execution type
+    const inventoryComponents =
+      await this.createInventoryRebalancerAndConfig(actionTracker);
+    if (inventoryComponents) {
+      rebalancers.push(inventoryComponents.inventoryRebalancer);
+      externalBridgeRegistry = inventoryComponents.externalBridgeRegistry;
+      inventoryConfig = inventoryComponents.inventoryConfig;
+    }
+
+    return { rebalancers, externalBridgeRegistry, inventoryConfig };
+  }
+
+  /**
+   * Creates a RebalancerOrchestrator with all required dependencies.
+   */
+  public createOrchestrator(options: {
+    strategy: IStrategy;
+    actionTracker: IActionTracker;
+    inflightContextAdapter: InflightContextAdapter;
+    rebalancers: IRebalancer[];
+    externalBridgeRegistry: Partial<ExternalBridgeRegistry>;
+    metrics?: Metrics;
+  }): RebalancerOrchestrator {
+    this.logger.debug(
+      { warpRouteId: this.config.warpRouteId },
+      'Creating RebalancerOrchestrator',
+    );
+
+    return new RebalancerOrchestrator({
+      strategy: options.strategy,
+      actionTracker: options.actionTracker,
+      inflightContextAdapter: options.inflightContextAdapter,
+      rebalancerConfig: this.config,
+      logger: this.logger,
+      rebalancers: options.rebalancers,
+      externalBridgeRegistry: options.externalBridgeRegistry,
+      metrics: options.metrics,
+    });
+  }
+
+  private hasMovableCollateralChains(): boolean {
+    return getStrategyChainNames(this.config.strategyConfig).some(
+      (chainName) => {
+        const chainConfig = getStrategyChainConfig(
+          this.config.strategyConfig,
+          chainName,
+        );
+        return (
+          chainConfig?.executionType === ExecutionType.MovableCollateral ||
+          chainConfig?.executionType === undefined
+        ); // Default is movableCollateral
+      },
+    );
+  }
+
   private async getInitialTotalCollateral(): Promise<bigint> {
     let initialTotalCollateral = 0n;
 

package/src/index.ts

@@ -57,16 +57,23 @@ export { PriceGetter } from './metrics/PriceGetter.js';
 
 // Interfaces
 export type {
+  ExecutionResult,
+  IInventoryRebalancer,
+  IMovableCollateralRebalancer,
   IRebalancer,
+  InventoryExecutionResult,
+  MovableCollateralExecutionResult,
   PreparedTransaction,
-  RebalanceRoute,
-  RebalanceExecutionResult,
+  RebalancerType,
 } from './interfaces/IRebalancer.js';
 export type {
   IStrategy,
-  StrategyRoute,
-  RawBalances,
   InflightContext,
+  InventoryRoute,
+  MovableCollateralRoute,
+  RawBalances,
+  Route,
+  StrategyRoute,
 } from './interfaces/IStrategy.js';
 export type {
   ConfirmedBlockTag,
@@ -82,10 +89,16 @@ export {
 export type { IMetrics } from './interfaces/IMetrics.js';
 
 // Utils
-export { getBridgeConfig } from './utils/bridgeUtils.js';
+export {
+  getBridgeConfig,
+  isMovableCollateralConfig,
+  isInventoryConfig,
+} from './utils/bridgeUtils.js';
 export type {
   BridgeConfigWithOverride,
   BridgeConfig,
+  MovableCollateralBridgeConfig,
+  InventoryBridgeConfig,
 } from './utils/bridgeUtils.js';
 export { getRawBalances } from './utils/balanceUtils.js';
 export { isCollateralizedTokenEligibleForRebalancing } from './utils/tokenUtils.js';
@@ -102,6 +115,8 @@ export type {
   Transfer,
   RebalanceIntent,
   RebalanceAction,
+  ActionType,
+  PartialInventoryIntent,
 } from './tracking/types.js';
 
 // Factory