@hyperlane-xyz/rebalancer 2.0.0 → 3.0.0

package/src/strategy/CollateralDeficitStrategy.test.ts

@@ -9,12 +9,15 @@ import {
 } from '@hyperlane-xyz/sdk';
 import type { Address } from '@hyperlane-xyz/utils';
 
+import { ExternalBridgeType } from '../config/types.js';
 import type {
+  InventoryRoute,
   RawBalances,
   Route,
   StrategyRoute,
 } from '../interfaces/IStrategy.js';
 import { extractBridgeConfigs } from '../test/helpers.js';
+import type { BridgeConfigWithOverride } from '../utils/bridgeUtils.js';
 
 import { CollateralDeficitStrategy } from './CollateralDeficitStrategy.js';
 
@@ -183,6 +186,7 @@ describe('CollateralDeficitStrategy', () => {
           origin: chain2,
           destination: chain1,
           amount: 5_000_000n, // 5 USDC pending to chain1
+          executionType: 'movableCollateral',
           bridge: BRIDGE2, // Matches chain2's bridge for chain2->chain1 route
         },
       ];
@@ -229,6 +233,7 @@ describe('CollateralDeficitStrategy', () => {
           origin: chain2,
           destination: chain1,
           amount: 5_000_000n,
+          executionType: 'movableCollateral',
           bridge: OTHER_BRIDGE, // Does NOT match chain2's configured bridge for chain2->chain1
         },
       ];
@@ -271,6 +276,7 @@ describe('CollateralDeficitStrategy', () => {
           origin: chain2,
           destination: chain1,
           amount: 10_000_000n, // 10 USDC pending - more than enough
+          executionType: 'movableCollateral',
           bridge: BRIDGE2, // Matches chain2's configured bridge for chain2->chain1
         },
       ];
@@ -383,7 +389,9 @@ describe('CollateralDeficitStrategy', () => {
       expect(routes).to.have.lengthOf(1);
       expect(routes[0].origin).to.equal(chain2);
       expect(routes[0].destination).to.equal(chain1);
-      expect(routes[0].bridge).to.equal(BRIDGE2); // Uses chain2's (origin) bridge
+      if (routes[0].executionType === 'movableCollateral') {
+        expect(routes[0].bridge).to.equal(BRIDGE2); // Uses chain2's (origin) bridge
+      }
     });
 
     it('should generate routes from surplus to deficit chains', () => {
@@ -473,8 +481,11 @@ describe('CollateralDeficitStrategy', () => {
       const filtered = strategy['filterByConfiguredBridges'](pendingRebalances);
 
       expect(filtered).to.have.lengthOf(2);
-      expect((filtered[0] as StrategyRoute).bridge).to.equal(BRIDGE2);
-      expect((filtered[1] as StrategyRoute).bridge).to.be.undefined;
+      expect((filtered[0] as Route & { bridge?: Address }).bridge).to.equal(
+        BRIDGE2,
+      );
+      expect((filtered[1] as Route & { bridge?: Address }).bridge).to.be
+        .undefined;
     });
 
     it('should include rebalance when bridge matches configured bridge for the route', () => {
@@ -502,7 +513,9 @@ describe('CollateralDeficitStrategy', () => {
 
       const filtered = strategy['filterByConfiguredBridges'](pendingRebalances);
       expect(filtered).to.have.lengthOf(1);
-      expect((filtered[0] as StrategyRoute).bridge).to.equal(BRIDGE2);
+      expect((filtered[0] as Route & { bridge?: Address }).bridge).to.equal(
+        BRIDGE2,
+      );
     });
 
     it('should exclude rebalance when bridge does not match configured bridge for the route', () => {
@@ -525,6 +538,7 @@ describe('CollateralDeficitStrategy', () => {
           origin: chain2,
           destination: chain1,
           amount: 5_000_000n,
+          executionType: 'movableCollateral',
           bridge: BRIDGE1, // Does NOT match configured bridge for chain2->chain1 (should be BRIDGE2)
         },
       ];
@@ -548,4 +562,167 @@ describe('CollateralDeficitStrategy', () => {
       expect(filtered).to.have.lengthOf(0);
     });
   });
+
+  describe('inventory execution type', () => {
+    it('should create inventory route when config is inventory type', () => {
+      const config = {
+        [chain1]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+          buffer: '1000',
+        },
+        [chain2]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+          buffer: '500',
+        },
+      };
+      const bridgeConfigs: ChainMap<BridgeConfigWithOverride> = {
+        [chain1]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+        },
+        [chain2]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+        },
+      };
+
+      const strategy = new CollateralDeficitStrategy(
+        config as any,
+        tokensByChainName,
+        testLogger,
+        bridgeConfigs,
+      );
+
+      // Start with positive balances
+      const rawBalances: RawBalances = {
+        [chain1]: 2_000_000n, // 2 USDC
+        [chain2]: 20_000_000n, // 20 USDC
+      };
+
+      // Pending transfer will drain chain1 to create deficit
+      const inflightContext = {
+        pendingTransfers: [
+          {
+            origin: chain2,
+            destination: chain1,
+            amount: 7_000_000n, // 7 USDC pending to chain1
+          },
+        ],
+        pendingRebalances: [] as StrategyRoute[],
+      };
+
+      // After reserveCollateral: chain1 = 2 - 7 = -5 USDC (deficit)
+      const routes = strategy.getRebalancingRoutes(
+        rawBalances,
+        inflightContext,
+      );
+
+      expect(routes).to.have.lengthOf(1);
+      expect(routes[0].origin).to.equal(chain2);
+      expect(routes[0].destination).to.equal(chain1);
+      expect(routes[0].executionType).to.equal('inventory');
+      expect((routes[0] as InventoryRoute).externalBridge).to.equal(
+        ExternalBridgeType.LiFi,
+      );
+    });
+
+    it('should include pending inventory rebalances with matching externalBridge in filter', () => {
+      const bridgeConfigs: ChainMap<BridgeConfigWithOverride> = {
+        [chain1]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+        },
+        [chain2]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+        },
+      };
+
+      const config = {
+        [chain1]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+          buffer: '1000',
+        },
+        [chain2]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+          buffer: '500',
+        },
+      };
+
+      const strategy = new CollateralDeficitStrategy(
+        config as any,
+        tokensByChainName,
+        testLogger,
+        bridgeConfigs,
+      );
+
+      const pendingRebalances: InventoryRoute[] = [
+        {
+          origin: chain2,
+          destination: chain1,
+          amount: 5_000_000n,
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+        },
+      ];
+
+      const filtered = strategy['filterByConfiguredBridges'](pendingRebalances);
+      expect(filtered).to.have.lengthOf(1);
+      expect((filtered[0] as InventoryRoute).externalBridge).to.equal(
+        ExternalBridgeType.LiFi,
+      );
+    });
+
+    it('should exclude pending inventory rebalances with non-matching externalBridge', () => {
+      const bridgeConfigs: ChainMap<BridgeConfigWithOverride> = {
+        [chain1]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+        },
+        [chain2]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+        },
+      };
+
+      const config = {
+        [chain1]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+          buffer: '1000',
+        },
+        [chain2]: {
+          executionType: 'inventory',
+          externalBridge: ExternalBridgeType.LiFi,
+          buffer: '500',
+        },
+      };
+
+      const strategy = new CollateralDeficitStrategy(
+        config as any,
+        tokensByChainName,
+        testLogger,
+        bridgeConfigs,
+      );
+
+      // Create a route with a different externalBridge value to test mismatch
+      // Using type assertion since we're testing the filtering logic
+      const pendingRebalances = [
+        {
+          origin: chain2,
+          destination: chain1,
+          amount: 5_000_000n,
+          executionType: 'inventory' as const,
+          externalBridge: 'nonexistent_bridge' as ExternalBridgeType, // Different bridge
+        },
+      ];
+
+      const filtered = strategy['filterByConfiguredBridges'](pendingRebalances);
+      expect(filtered).to.have.lengthOf(0);
+    });
+  });
 });

package/src/strategy/CollateralDeficitStrategy.ts

@@ -14,7 +14,12 @@ import type {
   StrategyRoute,
 } from '../interfaces/IStrategy.js';
 import { Metrics } from '../metrics/Metrics.js';
-import type { BridgeConfigWithOverride } from '../utils/bridgeUtils.js';
+import {
+  type BridgeConfigWithOverride,
+  createStrategyRoute,
+  isInventoryConfig,
+  isMovableCollateralConfig,
+} from '../utils/bridgeUtils.js';
 
 import { BaseStrategy, type Delta } from './BaseStrategy.js';
 
@@ -249,12 +254,14 @@ export class CollateralDeficitStrategy extends BaseStrategy {
           surplus.chain,
           deficit.chain,
         );
-        routes.push({
-          origin: surplus.chain,
-          destination: deficit.chain,
-          amount: transferAmount,
-          bridge: bridgeConfig.bridge,
-        });
+        routes.push(
+          createStrategyRoute(
+            bridgeConfig,
+            surplus.chain,
+            deficit.chain,
+            transferAmount,
+          ),
+        );
       }
 
       deficit.amount -= transferAmount;
@@ -275,6 +282,11 @@ export class CollateralDeficitStrategy extends BaseStrategy {
 
     const filteredRoutes = this.filterRoutes(routes, actualBalances);
 
+    // Record metrics for each intent created
+    for (const route of filteredRoutes) {
+      this.metrics?.recordIntentCreated(route, this.name);
+    }
+
     this.logger.debug(
       {
         context: this.constructor.name,
@@ -299,18 +311,33 @@ export class CollateralDeficitStrategy extends BaseStrategy {
     }
 
     return pendingRebalances.filter((rebalance) => {
-      if (!('bridge' in rebalance) || !rebalance.bridge) {
-        this.logger.debug(
-          { origin: rebalance.origin, destination: rebalance.destination },
-          'Including pending rebalance without bridge (recovered intent)',
-        );
-        return true;
-      }
       const bridgeConfig = this.getBridgeConfigForRoute(
         rebalance.origin,
         rebalance.destination,
       );
-      return bridgeConfig?.bridge === rebalance.bridge;
+
+      // For movableCollateral routes: match bridge address
+      if ('bridge' in rebalance && rebalance.bridge) {
+        return (
+          isMovableCollateralConfig(bridgeConfig) &&
+          bridgeConfig.bridge === rebalance.bridge
+        );
+      }
+
+      // For inventory routes: match externalBridge type
+      if ('externalBridge' in rebalance && rebalance.externalBridge) {
+        return (
+          isInventoryConfig(bridgeConfig) &&
+          bridgeConfig.externalBridge === rebalance.externalBridge
+        );
+      }
+
+      // Recovered intents without bridge info - include to be safe
+      this.logger.debug(
+        { origin: rebalance.origin, destination: rebalance.destination },
+        'Including pending rebalance without bridge (recovered intent)',
+      );
+      return true;
     });
   }
 

package/src/strategy/CompositeStrategy.test.ts

@@ -75,12 +75,14 @@ describe('CompositeStrategy', () => {
         origin: chain1,
         destination: chain2,
         amount: 1000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
       const route2: StrategyRoute = {
         origin: chain2,
         destination: chain3,
         amount: 2000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
 
@@ -110,6 +112,7 @@ describe('CompositeStrategy', () => {
         origin: chain1,
         destination: chain2,
         amount: 1000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
 
@@ -147,18 +150,21 @@ describe('CompositeStrategy', () => {
         origin: chain1,
         destination: chain2,
         amount: 1000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
       const route2: StrategyRoute = {
         origin: chain2,
         destination: chain3,
         amount: 2000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
       const route3: StrategyRoute = {
         origin: chain3,
         destination: chain1,
         amount: 3000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
 
@@ -206,6 +212,7 @@ describe('CompositeStrategy', () => {
         origin: chain3,
         destination: chain1,
         amount: 500n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
 
@@ -213,6 +220,7 @@ describe('CompositeStrategy', () => {
         origin: chain1,
         destination: chain2,
         amount: 1000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
 
@@ -306,18 +314,21 @@ describe('CompositeStrategy', () => {
         origin: chain1,
         destination: chain2,
         amount: 1000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
       const route1b: StrategyRoute = {
         origin: chain1,
         destination: chain3,
         amount: 1500n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
       const route2a: StrategyRoute = {
         origin: chain2,
         destination: chain3,
         amount: 2000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
 
@@ -348,6 +359,7 @@ describe('CompositeStrategy', () => {
         origin: chain2,
         destination: chain3,
         amount: 2000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
 
@@ -377,6 +389,7 @@ describe('CompositeStrategy', () => {
         origin: chain1,
         destination: chain2,
         amount: 1000n,
+        executionType: 'movableCollateral',
         bridge: TEST_BRIDGE,
       };
 

package/src/strategy/MinAmountStrategy.test.ts

@@ -410,6 +410,7 @@ describe('MinAmountStrategy', () => {
           destination: chain1,
           amount: BigInt(70e18),
           bridge: AddressZero,
+          executionType: 'movableCollateral',
         },
       ]);
     });
@@ -467,12 +468,14 @@ describe('MinAmountStrategy', () => {
           destination: chain1,
           amount: BigInt(50e18),
           bridge: AddressZero,
+          executionType: 'movableCollateral',
         },
         {
           origin: chain3,
           destination: chain2,
           amount: BigInt(25e18),
           bridge: AddressZero,
+          executionType: 'movableCollateral',
         },
       ]);
     });
@@ -721,6 +724,7 @@ describe('MinAmountStrategy', () => {
           destination: chain1,
           amount: 100n,
           bridge: AddressZero,
+          executionType: 'movableCollateral',
         },
       ]);
     });

package/src/strategy/StrategyFactory.ts

@@ -3,12 +3,17 @@ import { type Logger } from 'pino';
 import { type ChainMap, type Token } from '@hyperlane-xyz/sdk';
 
 import {
+  ExecutionType,
   RebalancerStrategyOptions,
   type StrategyConfig,
 } from '../config/types.js';
 import { type IStrategy } from '../interfaces/IStrategy.js';
 import { type Metrics } from '../metrics/Metrics.js';
-import type { BridgeConfigWithOverride } from '../utils/bridgeUtils.js';
+import type {
+  BridgeConfigWithOverride,
+  InventoryBridgeConfig,
+  MovableCollateralBridgeConfig,
+} from '../utils/bridgeUtils.js';
 
 import { CollateralDeficitStrategy } from './CollateralDeficitStrategy.js';
 import { CompositeStrategy } from './CompositeStrategy.js';
@@ -26,6 +31,7 @@ export class StrategyFactory {
    * @param initialTotalCollateral The initial total collateral of the rebalancer
    * @param logger The logger to use for the strategy
    * @param metrics The metrics to use for the strategy
+   * @param minAmountsByChain Optional minimum amounts per chain for filtering routes
    * @returns A concrete strategy implementation
    */
   static createStrategy(
@@ -34,6 +40,7 @@ export class StrategyFactory {
     initialTotalCollateral: bigint,
     logger: Logger,
     metrics?: Metrics,
+    minAmountsByChain?: ChainMap<bigint>,
   ): IStrategy {
     if (strategyConfigs.length === 0) {
       throw new Error('At least one strategy must be configured');
@@ -47,6 +54,7 @@ export class StrategyFactory {
         initialTotalCollateral,
         logger,
         metrics,
+        minAmountsByChain,
       );
     }
 
@@ -58,6 +66,7 @@ export class StrategyFactory {
         initialTotalCollateral,
         logger,
         metrics,
+        minAmountsByChain,
       ),
     );
     return new CompositeStrategy(subStrategies, logger);
@@ -72,6 +81,7 @@ export class StrategyFactory {
     initialTotalCollateral: bigint,
     logger: Logger,
     metrics?: Metrics,
+    _minAmountsByChain?: ChainMap<bigint>,
   ): IStrategy {
     const bridgeConfigs = this.extractBridgeConfigs(strategyConfig);
 
@@ -116,13 +126,30 @@ export class StrategyFactory {
     const bridgeConfigs: ChainMap<BridgeConfigWithOverride> = {};
 
     for (const [chain, config] of Object.entries(strategyConfig.chains)) {
-      bridgeConfigs[chain] = {
-        bridge: config.bridge,
+      const baseConfig = {
         bridgeMinAcceptedAmount: config.bridgeMinAcceptedAmount ?? 0,
-        override: config.override as ChainMap<
-          Partial<{ bridge: string; bridgeMinAcceptedAmount: string | number }>
-        >,
       };
+
+      const executionType =
+        config.executionType ?? ExecutionType.MovableCollateral;
+
+      if (executionType === ExecutionType.Inventory) {
+        bridgeConfigs[chain] = {
+          ...baseConfig,
+          executionType: 'inventory',
+          externalBridge: config.externalBridge!, // Validated by config schema
+          override: config.override as ChainMap<Partial<InventoryBridgeConfig>>,
+        };
+      } else {
+        bridgeConfigs[chain] = {
+          ...baseConfig,
+          executionType: 'movableCollateral',
+          bridge: config.bridge!, // Validated by config schema
+          override: config.override as ChainMap<
+            Partial<MovableCollateralBridgeConfig>
+          >,
+        };
+      }
     }
 
     return bridgeConfigs;

package/src/strategy/WeightedStrategy.test.ts

@@ -258,6 +258,7 @@ describe('WeightedStrategy', () => {
           destination: chain1,
           amount: ethers.utils.parseEther('50').toBigInt(),
           bridge: ethers.constants.AddressZero,
+          executionType: 'movableCollateral',
         },
       ]);
     });
@@ -325,6 +326,7 @@ describe('WeightedStrategy', () => {
           destination: chain1,
           amount: ethers.utils.parseEther('100').toBigInt(),
           bridge: ethers.constants.AddressZero,
+          executionType: 'movableCollateral',
         },
       ]);
     });
@@ -363,12 +365,14 @@ describe('WeightedStrategy', () => {
           destination: chain1,
           amount: 133333333333333333333n,
           bridge: ethers.constants.AddressZero,
+          executionType: 'movableCollateral',
         },
         {
           origin: chain3,
           destination: chain2,
           amount: 133333333333333333333n,
           bridge: ethers.constants.AddressZero,
+          executionType: 'movableCollateral',
         },
       ]);
     });
@@ -408,12 +412,14 @@ describe('WeightedStrategy', () => {
           destination: chain1,
           amount: ethers.utils.parseEther('25').toBigInt(),
           bridge: ethers.constants.AddressZero,
+          executionType: 'movableCollateral',
         },
         {
           origin: chain3,
           destination: chain1,
           amount: ethers.utils.parseEther('25').toBigInt(),
           bridge: ethers.constants.AddressZero,
+          executionType: 'movableCollateral',
         },
       ]);
     });