@hyperlane-xyz/rebalancer 0.1.2 → 1.0.0

package/src/strategy/MinAmountStrategy.test.ts

@@ -11,6 +11,7 @@ import {
 
 import { RebalancerMinAmountType } from '../config/types.js';
 import type { RawBalances } from '../interfaces/IStrategy.js';
+import { extractBridgeConfigs } from '../test/helpers.js';
 
 import { MinAmountStrategy } from './MinAmountStrategy.js';
 
@@ -58,6 +59,7 @@ describe('MinAmountStrategy', () => {
             tokensByChainName,
             totalCollateral,
             testLogger,
+            {},
           ),
       ).to.throw('At least two chains must be configured');
     });
@@ -87,6 +89,7 @@ describe('MinAmountStrategy', () => {
         tokensByChainName,
         totalCollateral,
         testLogger,
+        {},
       );
     });
 
@@ -115,6 +118,7 @@ describe('MinAmountStrategy', () => {
         tokensByChainName,
         totalCollateral,
         testLogger,
+        {},
       );
     });
 
@@ -145,6 +149,7 @@ describe('MinAmountStrategy', () => {
             tokensByChainName,
             totalCollateral,
             testLogger,
+            {},
           ),
       ).to.throw('Minimum amount (-10) cannot be negative for chain chain2');
     });
@@ -176,6 +181,7 @@ describe('MinAmountStrategy', () => {
             tokensByChainName,
             totalCollateral,
             testLogger,
+            {},
           ),
       ).to.throw(
         'Target (80) must be greater than or equal to min (100) for chain chain1',
@@ -209,6 +215,7 @@ describe('MinAmountStrategy', () => {
             tokensByChainName,
             totalCollateral,
             testLogger,
+            {},
           ),
       ).to.throw(
         'Target (0.4) must be greater than or equal to min (0.5) for chain chain1',
@@ -241,6 +248,7 @@ describe('MinAmountStrategy', () => {
           tokensByChainName,
           totalCollateral,
           testLogger,
+          {},
         ).getRebalancingRoutes({
           [chain1]: 100n,
           [chain2]: 200n,
@@ -275,6 +283,7 @@ describe('MinAmountStrategy', () => {
           tokensByChainName,
           totalCollateral,
           testLogger,
+          {},
         ).getRebalancingRoutes({
           [chain1]: 100n,
           [chain3]: 300n,
@@ -308,6 +317,7 @@ describe('MinAmountStrategy', () => {
           tokensByChainName,
           totalCollateral,
           testLogger,
+          {},
         ).getRebalancingRoutes({
           [chain1]: 100n,
           [chain2]: -2n,
@@ -342,6 +352,7 @@ describe('MinAmountStrategy', () => {
         tokensByChainName,
         totalCollateral,
         testLogger,
+        {},
       );
 
       const rawBalances: RawBalances = {
@@ -355,30 +366,33 @@ describe('MinAmountStrategy', () => {
     });
 
     it('should return a single route when a chain is below minimum amount', () => {
-      const strategy = new MinAmountStrategy(
-        {
-          [chain1]: {
-            minAmount: {
-              min: '100',
-              target: '120',
-              type: RebalancerMinAmountType.Absolute,
-            },
-            bridge: AddressZero,
-            bridgeLockTime: 1,
+      const config = {
+        [chain1]: {
+          minAmount: {
+            min: '100',
+            target: '120',
+            type: RebalancerMinAmountType.Absolute,
           },
-          [chain2]: {
-            minAmount: {
-              min: '100',
-              target: '120',
-              type: RebalancerMinAmountType.Absolute,
-            },
-            bridge: AddressZero,
-            bridgeLockTime: 1,
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain2]: {
+          minAmount: {
+            min: '100',
+            target: '120',
+            type: RebalancerMinAmountType.Absolute,
           },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
         },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new MinAmountStrategy(
+        config,
         tokensByChainName,
         totalCollateral,
         testLogger,
+        bridgeConfigs,
       );
 
       const rawBalances = {
@@ -393,44 +407,48 @@ describe('MinAmountStrategy', () => {
           origin: chain2,
           destination: chain1,
           amount: BigInt(70e18),
+          bridge: AddressZero,
         },
       ]);
     });
 
     it('should return multiple routes for multiple chains below minimum amount', () => {
-      const strategy = new MinAmountStrategy(
-        {
-          [chain1]: {
-            minAmount: {
-              min: '80',
-              target: '100',
-              type: RebalancerMinAmountType.Absolute,
-            },
-            bridge: AddressZero,
-            bridgeLockTime: 1,
+      const config = {
+        [chain1]: {
+          minAmount: {
+            min: '80',
+            target: '100',
+            type: RebalancerMinAmountType.Absolute,
           },
-          [chain2]: {
-            minAmount: {
-              min: '80',
-              target: '100',
-              type: RebalancerMinAmountType.Absolute,
-            },
-            bridge: AddressZero,
-            bridgeLockTime: 1,
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain2]: {
+          minAmount: {
+            min: '80',
+            target: '100',
+            type: RebalancerMinAmountType.Absolute,
           },
-          [chain3]: {
-            minAmount: {
-              min: '80',
-              target: '100',
-              type: RebalancerMinAmountType.Absolute,
-            },
-            bridge: AddressZero,
-            bridgeLockTime: 1,
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain3]: {
+          minAmount: {
+            min: '80',
+            target: '100',
+            type: RebalancerMinAmountType.Absolute,
           },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
         },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new MinAmountStrategy(
+        config,
         tokensByChainName,
         totalCollateral,
         testLogger,
+        bridgeConfigs,
       );
 
       const rawBalances = {
@@ -446,11 +464,13 @@ describe('MinAmountStrategy', () => {
           origin: chain3,
           destination: chain1,
           amount: BigInt(50e18),
+          bridge: AddressZero,
         },
         {
           origin: chain3,
           destination: chain2,
           amount: BigInt(25e18),
+          bridge: AddressZero,
         },
       ]);
     });
@@ -482,6 +502,7 @@ describe('MinAmountStrategy', () => {
             tokensByChainName,
             totalCollateral,
             testLogger,
+            {},
           ),
       ).to.throw(
         `Consider reducing the targets as the sum (340) is greater than sum of collaterals (300)`,
@@ -489,39 +510,42 @@ describe('MinAmountStrategy', () => {
     });
 
     it('should handle case where there is not enough surplus to meet all minimum requirements by scaling down deficits', () => {
-      const strategy = new MinAmountStrategy(
-        {
-          [chain1]: {
-            minAmount: {
-              min: '100',
-              target: '100',
-              type: RebalancerMinAmountType.Absolute,
-            },
-            bridge: AddressZero,
-            bridgeLockTime: 1,
+      const config = {
+        [chain1]: {
+          minAmount: {
+            min: '100',
+            target: '100',
+            type: RebalancerMinAmountType.Absolute,
           },
-          [chain2]: {
-            minAmount: {
-              min: '100',
-              target: '100',
-              type: RebalancerMinAmountType.Absolute,
-            },
-            bridge: AddressZero,
-            bridgeLockTime: 1,
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain2]: {
+          minAmount: {
+            min: '100',
+            target: '100',
+            type: RebalancerMinAmountType.Absolute,
           },
-          [chain3]: {
-            minAmount: {
-              min: '100',
-              target: '100',
-              type: RebalancerMinAmountType.Absolute,
-            },
-            bridge: AddressZero,
-            bridgeLockTime: 1,
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain3]: {
+          minAmount: {
+            min: '100',
+            target: '100',
+            type: RebalancerMinAmountType.Absolute,
           },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
         },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new MinAmountStrategy(
+        config,
         tokensByChainName,
         totalCollateral,
         testLogger,
+        bridgeConfigs,
       );
 
       const rawBalances = {
@@ -542,6 +566,78 @@ describe('MinAmountStrategy', () => {
       expect(routes[1].amount).to.equal(BigInt(25e18));
     });
 
+    it('should not produce zero-amount routes when scaling causes amounts to round to zero', () => {
+      // This test ensures that when deficit scaling produces zero amounts (due to integer division),
+      // these zero-amount routes are NOT included in the output.
+      // Bug scenario: totalSurplus=1, totalDeficit=3 -> each deficit of 1 scales to (1*1)/3 = 0
+      const config = {
+        [chain1]: {
+          minAmount: {
+            min: '90',
+            target: '100',
+            type: RebalancerMinAmountType.Absolute,
+          },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain2]: {
+          minAmount: {
+            min: '90',
+            target: '100',
+            type: RebalancerMinAmountType.Absolute,
+          },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain3]: {
+          minAmount: {
+            min: '90',
+            target: '100',
+            type: RebalancerMinAmountType.Absolute,
+          },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new MinAmountStrategy(
+        config,
+        tokensByChainName,
+        totalCollateral,
+        testLogger,
+        bridgeConfigs,
+      );
+
+      // chain1 and chain2 are at 1 token each (far below min 90)
+      // chain3 has 91 tokens (surplus of 1 above min)
+      // Deficits: chain1 needs 99 (100-1), chain2 needs 99 (100-1), total = 198
+      // Surplus: chain3 has 1 (91-90)
+      // Scaling: each deficit of 99 becomes (99 * 1) / 198 = 0 (integer division!)
+      const rawBalances = {
+        [chain1]: BigInt(1e18),
+        [chain2]: BigInt(1e18),
+        [chain3]: BigInt(91e18),
+      };
+
+      const routes = strategy.getRebalancingRoutes(rawBalances);
+
+      // All routes should have non-zero amounts
+      // (Chai's greaterThan doesn't support BigInt, so use direct comparison)
+      for (const route of routes) {
+        expect(
+          route.amount > 0n,
+          `Route amount should be > 0, got ${route.amount}`,
+        ).to.be.true;
+      }
+
+      // The single token of surplus may produce one route (or none if both scale to 0)
+      // Either way, no zero-amount routes should exist
+      expect(
+        routes.every((r) => r.amount > 0n),
+        'All routes must have non-zero amounts',
+      ).to.be.true;
+    });
+
     it('should have no surplus or deficit when all at min', () => {
       const strategy = new MinAmountStrategy(
         {
@@ -567,6 +663,7 @@ describe('MinAmountStrategy', () => {
         tokensByChainName,
         totalCollateral,
         testLogger,
+        {},
       );
 
       const rawBalances = {
@@ -580,30 +677,33 @@ describe('MinAmountStrategy', () => {
     });
 
     it('should consider the target amount with relative configuration', () => {
-      const strategy = new MinAmountStrategy(
-        {
-          [chain1]: {
-            minAmount: {
-              min: 0.25,
-              target: 0.3,
-              type: RebalancerMinAmountType.Relative,
-            },
-            bridge: AddressZero,
-            bridgeLockTime: 1,
+      const config = {
+        [chain1]: {
+          minAmount: {
+            min: 0.25,
+            target: 0.3,
+            type: RebalancerMinAmountType.Relative,
           },
-          [chain2]: {
-            minAmount: {
-              min: 0.25,
-              target: 0.3,
-              type: RebalancerMinAmountType.Relative,
-            },
-            bridge: AddressZero,
-            bridgeLockTime: 1,
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain2]: {
+          minAmount: {
+            min: 0.25,
+            target: 0.3,
+            type: RebalancerMinAmountType.Relative,
           },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
         },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new MinAmountStrategy(
+        config,
         tokensByChainName,
         totalCollateral,
         testLogger,
+        bridgeConfigs,
       );
 
       const rawBalances: RawBalances = {
@@ -618,6 +718,7 @@ describe('MinAmountStrategy', () => {
           origin: chain2,
           destination: chain1,
           amount: 100n,
+          bridge: AddressZero,
         },
       ]);
     });

package/src/strategy/MinAmountStrategy.ts

@@ -7,9 +7,15 @@ import { fromWei, toWei } from '@hyperlane-xyz/utils';
 import {
   type MinAmountStrategyConfig,
   RebalancerMinAmountType,
+  RebalancerStrategyOptions,
 } from '../config/types.js';
-import type { RawBalances } from '../interfaces/IStrategy.js';
+import type {
+  RawBalances,
+  Route,
+  StrategyRoute,
+} from '../interfaces/IStrategy.js';
 import { type Metrics } from '../metrics/Metrics.js';
+import type { BridgeConfigWithOverride } from '../utils/bridgeUtils.js';
 
 import { BaseStrategy, type Delta } from './BaseStrategy.js';
 
@@ -18,19 +24,21 @@ import { BaseStrategy, type Delta } from './BaseStrategy.js';
  * It ensures each chain has at least the specified minimum amount
  */
 export class MinAmountStrategy extends BaseStrategy {
+  readonly name = RebalancerStrategyOptions.MinAmount;
   private readonly config: MinAmountStrategyConfig = {};
   protected readonly logger: Logger;
 
   constructor(
     config: MinAmountStrategyConfig,
-    private readonly tokensByChainName: ChainMap<Token>,
+    tokensByChainName: ChainMap<Token>,
     initialTotalCollateral: bigint,
     logger: Logger,
+    bridgeConfigs: ChainMap<BridgeConfigWithOverride>,
     metrics?: Metrics,
   ) {
     const chains = Object.keys(config);
     const log = logger.child({ class: MinAmountStrategy.name });
-    super(chains, log, metrics);
+    super(chains, log, bridgeConfigs, metrics, tokensByChainName);
     this.logger = log;
 
     const minAmountType = config[chains[0]].minAmount.type;
@@ -67,37 +75,60 @@ export class MinAmountStrategy extends BaseStrategy {
    * Gets balances categorized by surplus and deficit based on minimum amounts and targets
    * - For absolute values: Uses exact token amounts
    * - For relative values: Uses percentages of total balance across all chains
+   *
+   * Simulates both types of rebalances before calculating surpluses/deficits:
+   * - pendingRebalances: in-flight intents (origin tx confirmed, add to destination only)
+   * - proposedRebalances: routes from earlier strategies (subtract from origin AND add to destination)
+   *
+   * This prevents over-rebalancing when multiple strategies run in sequence.
    */
-  protected getCategorizedBalances(rawBalances: RawBalances): {
+  protected getCategorizedBalances(
+    rawBalances: RawBalances,
+    pendingRebalances?: Route[],
+    proposedRebalances?: StrategyRoute[],
+  ): {
     surpluses: Delta[];
     deficits: Delta[];
   } {
+    // Step 1: Simulate pending rebalances (in-flight, origin already deducted on-chain)
+    let simulatedBalances = this.simulatePendingRebalances(
+      rawBalances,
+      pendingRebalances ?? [],
+    );
+
+    // Step 2: Simulate proposed rebalances (from earlier strategies, not yet executed)
+    simulatedBalances = this.simulateProposedRebalances(
+      simulatedBalances,
+      proposedRebalances ?? [],
+    );
     const totalCollateral = this.chains.reduce(
-      (sum, chain) => sum + rawBalances[chain],
+      (sum, chain) => sum + simulatedBalances[chain],
       0n,
     );
 
     return this.chains.reduce(
       (acc, chain) => {
-        const config = this.config[chain];
-        const balance = rawBalances[chain];
+        const chainConfig = this.config[chain];
+        const balance = simulatedBalances[chain];
         let minAmount: bigint;
         let targetAmount: bigint;
 
-        if (config.minAmount.type === RebalancerMinAmountType.Absolute) {
+        if (chainConfig.minAmount.type === RebalancerMinAmountType.Absolute) {
           const token = this.getTokenByChainName(chain);
 
-          minAmount = BigInt(toWei(config.minAmount.min, token.decimals));
-          targetAmount = BigInt(toWei(config.minAmount.target, token.decimals));
+          minAmount = BigInt(toWei(chainConfig.minAmount.min, token.decimals));
+          targetAmount = BigInt(
+            toWei(chainConfig.minAmount.target, token.decimals),
+          );
         } else {
           minAmount = BigInt(
             BigNumber(totalCollateral.toString())
-              .times(config.minAmount.min)
+              .times(chainConfig.minAmount.min)
               .toFixed(0, BigNumber.ROUND_FLOOR),
           );
           targetAmount = BigInt(
             BigNumber(totalCollateral.toString())
-              .times(config.minAmount.target)
+              .times(chainConfig.minAmount.target)
               .toFixed(0, BigNumber.ROUND_FLOOR),
           );
         }
@@ -123,7 +154,7 @@ export class MinAmountStrategy extends BaseStrategy {
   }
 
   protected getTokenByChainName(chainName: string): Token {
-    const token = this.tokensByChainName[chainName];
+    const token = this.tokensByChainName![chainName];
 
     if (token === undefined) {
       throw new Error(`Token not found for chain ${chainName}`);

package/src/strategy/StrategyFactory.test.ts

@@ -61,7 +61,7 @@ describe('StrategyFactory', () => {
       };
 
       const strategy = StrategyFactory.createStrategy(
-        strategyConfig,
+        [strategyConfig],
         tokensByChainName,
         totalCollateral,
         testLogger,
@@ -97,7 +97,7 @@ describe('StrategyFactory', () => {
       };
 
       const strategy = StrategyFactory.createStrategy(
-        strategyConfig,
+        [strategyConfig],
         tokensByChainName,
         totalCollateral,
         testLogger,