@hyperlane-xyz/rebalancer 0.1.2 → 1.0.0

package/src/strategy/StrategyFactory.ts

@@ -8,40 +8,123 @@ import {
 } 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 { CollateralDeficitStrategy } from './CollateralDeficitStrategy.js';
+import { CompositeStrategy } from './CompositeStrategy.js';
 import { MinAmountStrategy } from './MinAmountStrategy.js';
 import { WeightedStrategy } from './WeightedStrategy.js';
 
 export class StrategyFactory {
   /**
-   * @param strategyConfig A discriminated union of strategy-specific configurations.
-   * @param tokensByChainName - A map of chain->token to ease the lookup of token by chain
-   * @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
+   * Creates a strategy from an array of strategy configs.
+   * - Single strategy (array with 1 element): Creates that strategy directly
+   * - Multiple strategies (array with 2+ elements): Creates CompositeStrategy
+   *
+   * @param strategyConfigs Array of strategy configurations (always array format)
+   * @param tokensByChainName A map of chain->token to ease the lookup of token by chain
+   * @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
    * @returns A concrete strategy implementation
    */
   static createStrategy(
+    strategyConfigs: StrategyConfig[],
+    tokensByChainName: ChainMap<Token>,
+    initialTotalCollateral: bigint,
+    logger: Logger,
+    metrics?: Metrics,
+  ): IStrategy {
+    if (strategyConfigs.length === 0) {
+      throw new Error('At least one strategy must be configured');
+    }
+
+    // Single strategy - create directly without CompositeStrategy wrapper
+    if (strategyConfigs.length === 1) {
+      return this.createSingleStrategy(
+        strategyConfigs[0],
+        tokensByChainName,
+        initialTotalCollateral,
+        logger,
+        metrics,
+      );
+    }
+
+    // Multiple strategies - create CompositeStrategy
+    const subStrategies = strategyConfigs.map((config) =>
+      this.createSingleStrategy(
+        config,
+        tokensByChainName,
+        initialTotalCollateral,
+        logger,
+        metrics,
+      ),
+    );
+    return new CompositeStrategy(subStrategies, logger);
+  }
+
+  /**
+   * Create a single strategy from config.
+   */
+  private static createSingleStrategy(
     strategyConfig: StrategyConfig,
     tokensByChainName: ChainMap<Token>,
     initialTotalCollateral: bigint,
     logger: Logger,
     metrics?: Metrics,
   ): IStrategy {
+    const bridgeConfigs = this.extractBridgeConfigs(strategyConfig);
+
     switch (strategyConfig.rebalanceStrategy) {
-      case RebalancerStrategyOptions.Weighted:
-        return new WeightedStrategy(strategyConfig.chains, logger, metrics);
-      case RebalancerStrategyOptions.MinAmount:
+      case RebalancerStrategyOptions.Weighted: {
+        return new WeightedStrategy(
+          strategyConfig.chains,
+          logger,
+          bridgeConfigs,
+          metrics,
+          tokensByChainName,
+        );
+      }
+      case RebalancerStrategyOptions.MinAmount: {
         return new MinAmountStrategy(
           strategyConfig.chains,
           tokensByChainName,
           initialTotalCollateral,
           logger,
+          bridgeConfigs,
+          metrics,
+        );
+      }
+      case RebalancerStrategyOptions.CollateralDeficit: {
+        return new CollateralDeficitStrategy(
+          strategyConfig.chains,
+          tokensByChainName,
+          logger,
+          bridgeConfigs,
           metrics,
         );
+      }
       default: {
         throw new Error('Unsupported strategy type');
       }
     }
   }
+
+  private static extractBridgeConfigs(
+    strategyConfig: StrategyConfig,
+  ): ChainMap<BridgeConfigWithOverride> {
+    const bridgeConfigs: ChainMap<BridgeConfigWithOverride> = {};
+
+    for (const [chain, config] of Object.entries(strategyConfig.chains)) {
+      bridgeConfigs[chain] = {
+        bridge: config.bridge,
+        bridgeMinAcceptedAmount: config.bridgeMinAcceptedAmount ?? 0,
+        override: config.override as ChainMap<
+          Partial<{ bridge: string; bridgeMinAcceptedAmount: string | number }>
+        >,
+      };
+    }
+
+    return bridgeConfigs;
+  }
 }

package/src/strategy/WeightedStrategy.test.ts

@@ -2,9 +2,10 @@ import { expect } from 'chai';
 import { ethers } from 'ethers';
 import { pino } from 'pino';
 
-import type { ChainName } from '@hyperlane-xyz/sdk';
+import type { ChainMap, ChainName, Token } from '@hyperlane-xyz/sdk';
 
 import type { RawBalances } from '../interfaces/IStrategy.js';
+import { extractBridgeConfigs } from '../test/helpers.js';
 
 import { WeightedStrategy } from './WeightedStrategy.js';
 
@@ -34,6 +35,7 @@ describe('WeightedStrategy', () => {
               },
             },
             testLogger,
+            {},
           ),
       ).to.throw('At least two chains must be configured');
     });
@@ -55,6 +57,7 @@ describe('WeightedStrategy', () => {
               },
             },
             testLogger,
+            {},
           ),
       ).to.throw('Weight (-1) must not be negative for chain2');
     });
@@ -76,6 +79,7 @@ describe('WeightedStrategy', () => {
               },
             },
             testLogger,
+            {},
           ),
       ).to.throw('The total weight for all chains must be greater than 0');
     });
@@ -97,6 +101,7 @@ describe('WeightedStrategy', () => {
               },
             },
             testLogger,
+            {},
           ),
       ).to.throw('Tolerance (-1) must be between 0 and 100 for chain2');
 
@@ -116,6 +121,7 @@ describe('WeightedStrategy', () => {
               },
             },
             testLogger,
+            {},
           ),
       ).to.throw('Tolerance (101) must be between 0 and 100 for chain2');
     });
@@ -138,6 +144,7 @@ describe('WeightedStrategy', () => {
             },
           },
           testLogger,
+          {},
         ).getRebalancingRoutes({
           [chain1]: ethers.utils.parseEther('100').toBigInt(),
           [chain2]: ethers.utils.parseEther('200').toBigInt(),
@@ -162,6 +169,7 @@ describe('WeightedStrategy', () => {
             },
           },
           testLogger,
+          {},
         ).getRebalancingRoutes({
           [chain1]: ethers.utils.parseEther('100').toBigInt(),
           [chain3]: ethers.utils.parseEther('300').toBigInt(),
@@ -185,6 +193,7 @@ describe('WeightedStrategy', () => {
             },
           },
           testLogger,
+          {},
         ).getRebalancingRoutes({
           [chain1]: ethers.utils.parseEther('100').toBigInt(),
           [chain2]: ethers.utils.parseEther('-200').toBigInt(),
@@ -207,6 +216,7 @@ describe('WeightedStrategy', () => {
           },
         },
         testLogger,
+        {},
       );
 
       const rawBalances = {
@@ -220,21 +230,20 @@ describe('WeightedStrategy', () => {
     });
 
     it('should return a single route when a chain is unbalanced', () => {
-      const strategy = new WeightedStrategy(
-        {
-          [chain1]: {
-            weighted: { weight: 100n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
-          [chain2]: {
-            weighted: { weight: 100n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
+      const config = {
+        [chain1]: {
+          weighted: { weight: 100n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
         },
-        testLogger,
-      );
+        [chain2]: {
+          weighted: { weight: 100n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+        },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new WeightedStrategy(config, testLogger, bridgeConfigs);
 
       const rawBalances = {
         [chain1]: ethers.utils.parseEther('100').toBigInt(),
@@ -248,6 +257,7 @@ describe('WeightedStrategy', () => {
           origin: chain2,
           destination: chain1,
           amount: ethers.utils.parseEther('50').toBigInt(),
+          bridge: ethers.constants.AddressZero,
         },
       ]);
     });
@@ -267,6 +277,7 @@ describe('WeightedStrategy', () => {
           },
         },
         testLogger,
+        {},
       );
 
       const rawBalances = {
@@ -280,26 +291,25 @@ describe('WeightedStrategy', () => {
     });
 
     it('should return a single route when two chains are unbalanced and can be solved with a single transfer', () => {
-      const strategy = new WeightedStrategy(
-        {
-          [chain1]: {
-            weighted: { weight: 100n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
-          [chain2]: {
-            weighted: { weight: 100n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
-          [chain3]: {
-            weighted: { weight: 100n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
+      const config = {
+        [chain1]: {
+          weighted: { weight: 100n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
         },
-        testLogger,
-      );
+        [chain2]: {
+          weighted: { weight: 100n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain3]: {
+          weighted: { weight: 100n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+        },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new WeightedStrategy(config, testLogger, bridgeConfigs);
 
       const rawBalances = {
         [chain1]: ethers.utils.parseEther('100').toBigInt(),
@@ -314,30 +324,30 @@ describe('WeightedStrategy', () => {
           origin: chain3,
           destination: chain1,
           amount: ethers.utils.parseEther('100').toBigInt(),
+          bridge: ethers.constants.AddressZero,
         },
       ]);
     });
     it('should return two routes when two chains are unbalanced and cannot be solved with a single transfer', () => {
-      const strategy = new WeightedStrategy(
-        {
-          [chain1]: {
-            weighted: { weight: 100n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
-          [chain2]: {
-            weighted: { weight: 100n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
-          [chain3]: {
-            weighted: { weight: 100n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
+      const config = {
+        [chain1]: {
+          weighted: { weight: 100n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
         },
-        testLogger,
-      );
+        [chain2]: {
+          weighted: { weight: 100n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain3]: {
+          weighted: { weight: 100n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+        },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new WeightedStrategy(config, testLogger, bridgeConfigs);
 
       const rawBalances = {
         [chain1]: ethers.utils.parseEther('100').toBigInt(),
@@ -352,36 +362,37 @@ describe('WeightedStrategy', () => {
           origin: chain3,
           destination: chain1,
           amount: 133333333333333333333n,
+          bridge: ethers.constants.AddressZero,
         },
         {
           origin: chain3,
           destination: chain2,
           amount: 133333333333333333333n,
+          bridge: ethers.constants.AddressZero,
         },
       ]);
     });
 
     it('should return routes to balance different weighted chains', () => {
-      const strategy = new WeightedStrategy(
-        {
-          [chain1]: {
-            weighted: { weight: 50n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
-          [chain2]: {
-            weighted: { weight: 25n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
-          [chain3]: {
-            weighted: { weight: 25n, tolerance: 0n },
-            bridge: ethers.constants.AddressZero,
-            bridgeLockTime: 1,
-          },
+      const config = {
+        [chain1]: {
+          weighted: { weight: 50n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
         },
-        testLogger,
-      );
+        [chain2]: {
+          weighted: { weight: 25n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain3]: {
+          weighted: { weight: 25n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+        },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new WeightedStrategy(config, testLogger, bridgeConfigs);
 
       const rawBalances = {
         [chain1]: ethers.utils.parseEther('100').toBigInt(),
@@ -396,13 +407,117 @@ describe('WeightedStrategy', () => {
           origin: chain2,
           destination: chain1,
           amount: ethers.utils.parseEther('25').toBigInt(),
+          bridge: ethers.constants.AddressZero,
         },
         {
           origin: chain3,
           destination: chain1,
           amount: ethers.utils.parseEther('25').toBigInt(),
+          bridge: ethers.constants.AddressZero,
         },
       ]);
     });
   });
+
+  describe('bridgeMinAcceptedAmount filtering', () => {
+    function createMockToken(chainName: string, decimals = 18): Token {
+      return {
+        chainName,
+        decimals,
+        addressOrDenom: ethers.constants.AddressZero,
+      } as unknown as Token;
+    }
+
+    it('should filter out routes below bridgeMinAcceptedAmount', () => {
+      const chain1 = 'chain1';
+      const chain2 = 'chain2';
+
+      const tokensByChainName: ChainMap<Token> = {
+        [chain1]: createMockToken(chain1),
+        [chain2]: createMockToken(chain2),
+      };
+
+      const config = {
+        [chain1]: {
+          weighted: { weight: 50n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+          bridgeMinAcceptedAmount: '100', // 100 tokens minimum
+        },
+        [chain2]: {
+          weighted: { weight: 50n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+          bridgeMinAcceptedAmount: '100',
+        },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new WeightedStrategy(
+        config,
+        testLogger,
+        bridgeConfigs,
+        undefined,
+        tokensByChainName,
+      );
+
+      // chain1 has 150, chain2 has 50 (total 200, each should have 100)
+      // Would generate route: chain1 -> chain2, amount = 50
+      // But 50 < bridgeMinAcceptedAmount (100), so route should be filtered
+      const rawBalances: RawBalances = {
+        [chain1]: ethers.utils.parseEther('150').toBigInt(),
+        [chain2]: ethers.utils.parseEther('50').toBigInt(),
+      };
+
+      const routes = strategy.getRebalancingRoutes(rawBalances);
+
+      expect(routes).to.have.lengthOf(0);
+    });
+
+    it('should keep routes at or above bridgeMinAcceptedAmount', () => {
+      const chain1 = 'chain1';
+      const chain2 = 'chain2';
+
+      const tokensByChainName: ChainMap<Token> = {
+        [chain1]: createMockToken(chain1),
+        [chain2]: createMockToken(chain2),
+      };
+
+      const config = {
+        [chain1]: {
+          weighted: { weight: 50n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+          bridgeMinAcceptedAmount: '50', // 50 tokens minimum
+        },
+        [chain2]: {
+          weighted: { weight: 50n, tolerance: 0n },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+          bridgeMinAcceptedAmount: '50',
+        },
+      };
+      const bridgeConfigs = extractBridgeConfigs(config);
+      const strategy = new WeightedStrategy(
+        config,
+        testLogger,
+        bridgeConfigs,
+        undefined,
+        tokensByChainName,
+      );
+
+      // chain1 has 200, chain2 has 100 (total 300, each should have 150)
+      // Route: chain1 -> chain2, amount = 50 (equals minAcceptedAmount)
+      const rawBalances: RawBalances = {
+        [chain1]: ethers.utils.parseEther('200').toBigInt(),
+        [chain2]: ethers.utils.parseEther('100').toBigInt(),
+      };
+
+      const routes = strategy.getRebalancingRoutes(rawBalances);
+
+      expect(routes).to.have.lengthOf(1);
+      expect(routes[0].amount).to.equal(
+        ethers.utils.parseEther('50').toBigInt(),
+      );
+    });
+  });
 });

package/src/strategy/WeightedStrategy.ts

@@ -1,8 +1,18 @@
 import { type Logger } from 'pino';
 
-import type { WeightedStrategyConfig } from '../config/types.js';
-import type { RawBalances } from '../interfaces/IStrategy.js';
+import type { ChainMap, Token } from '@hyperlane-xyz/sdk';
+
+import {
+  RebalancerStrategyOptions,
+  type WeightedStrategyConfig,
+} from '../config/types.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';
 
@@ -11,6 +21,7 @@ import { BaseStrategy, type Delta } from './BaseStrategy.js';
  * It distributes funds across chains based on their weights
  */
 export class WeightedStrategy extends BaseStrategy {
+  readonly name = RebalancerStrategyOptions.Weighted;
   private readonly config: WeightedStrategyConfig;
   private readonly totalWeight: bigint;
   protected readonly logger: Logger;
@@ -18,11 +29,13 @@ export class WeightedStrategy extends BaseStrategy {
   constructor(
     config: WeightedStrategyConfig,
     logger: Logger,
+    bridgeConfigs: ChainMap<BridgeConfigWithOverride>,
     metrics?: Metrics,
+    tokensByChainName?: ChainMap<Token>,
   ) {
     const chains = Object.keys(config);
     const log = logger.child({ class: WeightedStrategy.name });
-    super(chains, log, metrics);
+    super(chains, log, bridgeConfigs, metrics, tokensByChainName);
     this.logger = log;
 
     let totalWeight = 0n;
@@ -54,14 +67,35 @@ export class WeightedStrategy extends BaseStrategy {
 
   /**
    * Gets balances categorized by surplus and deficit based on weights
+   *
+   * 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[];
   } {
-    // Get the total balance from all chains
+    // 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 ?? [],
+    );
+    // Get the total balance from all chains (using simulated balances)
     const total = this.chains.reduce(
-      (sum, chain) => sum + rawBalances[chain],
+      (sum, chain) => sum + simulatedBalances[chain],
       0n,
     );
 
@@ -70,7 +104,7 @@ export class WeightedStrategy extends BaseStrategy {
         const { weight, tolerance } = this.config[chain].weighted;
         const target = (total * weight) / this.totalWeight;
         const toleranceAmount = (target * tolerance) / 100n;
-        const balance = rawBalances[chain];
+        const balance = simulatedBalances[chain];
 
         // Apply the tolerance to deficits to prevent small imbalances
         if (balance < target - toleranceAmount) {

package/src/strategy/index.ts

@@ -1,4 +1,6 @@
 export { BaseStrategy } from './BaseStrategy.js';
+export { CollateralDeficitStrategy } from './CollateralDeficitStrategy.js';
+export { CompositeStrategy } from './CompositeStrategy.js';
 export { MinAmountStrategy } from './MinAmountStrategy.js';
 export { StrategyFactory } from './StrategyFactory.js';
 export { WeightedStrategy } from './WeightedStrategy.js';