@hyperlane-xyz/rebalancer 2.0.0 → 3.1.0

package/src/strategy/BaseStrategy.ts

@@ -8,12 +8,14 @@ import type {
   InflightContext,
   RawBalances,
   Route,
+  RouteWithContext,
   StrategyRoute,
 } from '../interfaces/IStrategy.js';
 import { type Metrics } from '../metrics/Metrics.js';
 import {
   type BridgeConfig,
   type BridgeConfigWithOverride,
+  createStrategyRoute,
   getBridgeConfig,
 } from '../utils/bridgeUtils.js';
 
@@ -193,13 +195,15 @@ export abstract class BaseStrategy implements IStrategy {
           deficit.chain,
         );
 
-        // Creates the balancing route
-        routes.push({
-          origin: surplus.chain,
-          destination: deficit.chain,
-          amount: transferAmount,
-          bridge: bridgeConfig.bridge,
-        });
+        // Create appropriate route type based on execution type
+        routes.push(
+          createStrategyRoute(
+            bridgeConfig,
+            surplus.chain,
+            deficit.chain,
+            transferAmount,
+          ),
+        );
       }
 
       // Decreases the amounts for the following iterations
@@ -342,11 +346,17 @@ export abstract class BaseStrategy implements IStrategy {
   }
 
   /**
-   * Simulate pending rebalances by adding to destination balances.
+   * Simulate pending rebalances based on execution method.
+   *
+   * For **movable_collateral** (default):
+   * - Add full amount to destination (origin already deducted on-chain)
    *
-   * 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
+   * For **inventory**:
+   * - Simulate the eventual final state as if the entire intent will be fulfilled
+   * - Destination: add unfulfilled amount (total - delivered - awaiting)
+   *   This is what's NOT yet reflected in on-chain balance
+   * - Origin: subtract pending amount (total - delivered)
+   *   This is what WILL decrease when all messages deliver
    *
    * @param rawBalances - Current balances (may already have collateral reserved)
    * @param pendingRebalances - In-flight rebalance operations (in_progress only)
@@ -354,7 +364,7 @@ export abstract class BaseStrategy implements IStrategy {
    */
   protected simulatePendingRebalances(
     rawBalances: RawBalances,
-    pendingRebalances: Route[],
+    pendingRebalances: RouteWithContext[],
   ): RawBalances {
     if (pendingRebalances.length === 0) {
       return rawBalances;
@@ -363,19 +373,59 @@ export abstract class BaseStrategy implements IStrategy {
     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;
+      if (rebalance.executionMethod === 'inventory') {
+        // Inventory: simulate eventual final state
+        const total = rebalance.amount;
+        const delivered = rebalance.deliveredAmount ?? 0n;
+        const awaiting = rebalance.awaitingDeliveryAmount ?? 0n;
+
+        // Destination: add unfulfilled amount (total - delivered - awaiting)
+        // This is what's NOT yet reflected in on-chain balance
+        const destinationAdjustment = total - delivered - awaiting;
+        if (destinationAdjustment > 0n) {
+          simulated[rebalance.destination] =
+            (simulated[rebalance.destination] ?? 0n) + destinationAdjustment;
+
+          this.logger.debug(
+            {
+              context: this.constructor.name,
+              destination: rebalance.destination,
+              destinationAdjustment: destinationAdjustment.toString(),
+            },
+            'Simulated inventory rebalance (destination increase for unfulfilled)',
+          );
+        }
 
-      this.logger.debug(
-        {
-          context: this.constructor.name,
-          destination: rebalance.destination,
-          amount: rebalance.amount.toString(),
-        },
-        'Simulated pending rebalance (destination increase)',
-      );
+        // Origin: subtract pending amount (total - delivered)
+        // This is what WILL decrease when all messages deliver
+        const originAdjustment = total - delivered;
+        if (originAdjustment > 0n) {
+          simulated[rebalance.origin] =
+            (simulated[rebalance.origin] ?? 0n) - originAdjustment;
+
+          this.logger.debug(
+            {
+              context: this.constructor.name,
+              origin: rebalance.origin,
+              originAdjustment: originAdjustment.toString(),
+            },
+            'Simulated inventory rebalance (origin decrease for pending)',
+          );
+        }
+      } else {
+        // Movable collateral: origin already deducted on-chain, add to destination
+        simulated[rebalance.destination] =
+          (simulated[rebalance.destination] ?? 0n) + rebalance.amount;
+
+        this.logger.debug(
+          {
+            context: this.constructor.name,
+            destination: rebalance.destination,
+            amount: rebalance.amount.toString(),
+          },
+          'Simulated movable collateral rebalance (destination increase)',
+        );
+      }
     }
 
     this.logger.info(
@@ -384,6 +434,9 @@ export abstract class BaseStrategy implements IStrategy {
           from: r.origin,
           to: r.destination,
           amount: r.amount.toString(),
+          executionMethod: r.executionMethod ?? 'movable_collateral',
+          deliveredAmount: r.deliveredAmount?.toString() ?? '0',
+          awaitingDeliveryAmount: r.awaitingDeliveryAmount?.toString() ?? '0',
         })),
       },
       'Simulated pending rebalances',

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',
         },
       ]);
     });