fix: Add tolerance to simple strategy

typescript/cli/src/commands/warp.ts

@@ -411,6 +411,7 @@ export const check: CommandModuleWithContext<{
 export const rebalancer: CommandModuleWithContext<{
   warpRouteId: string;
   checkFrequency: number;
+  strategyTolerance: string;
 }> = {
   command: 'rebalancer',
   describe: 'Run a warp route collateral rebalancer',
@@ -426,8 +427,20 @@ export const rebalancer: CommandModuleWithContext<{
       demandOption: true,
       alias: 'v',
     },
+    strategyTolerance: {
+      type: 'string',
+      description:
+        'Tolerance threshold for imbalance detection (specified in token base units; e.g., 1000000 for 1 USDC, 1000000000000000000 for 1 ETH)',
+      demandOption: false,
+      default: '0',
+    },
   },
-  handler: async ({ context, warpRouteId, checkFrequency }) => {
+  handler: async ({
+    context,
+    warpRouteId,
+    checkFrequency,
+    strategyTolerance,
+  }) => {
     logCommandHeader('Hyperlane Warp Rebalancer');
 
     // Instantiates the warp route monitor
@@ -438,7 +451,7 @@ export const rebalancer: CommandModuleWithContext<{
     );
 
     // Instantiates the strategy that will get rebalancing routes based on monitor results
-    const strategy: IStrategy = new Strategy();
+    const strategy: IStrategy = new Strategy(BigInt(strategyTolerance));
 
     // Instantiates the executor that will process rebalancing routes
     const executor: IExecutor = new Executor();

typescript/cli/src/rebalancer/strategy/Strategy.test.ts

@@ -87,7 +87,50 @@ describe('Strategy', () => {
     it('should return no routes', () => {
       const routes = strategy.getRebalancingRoutes(balances);
 
-      expect(routes).to.have.lengthOf(0);
+      expect(routes).to.be.empty;
+    });
+  });
+
+  describe('when tolerance is 10 ether', () => {
+    beforeEach(() => {
+      strategy = new Strategy(ethers.utils.parseEther('10').toBigInt());
+    });
+
+    describe('when balances for chain1, chain2, and chain3 are 80, 90, and 100 respectively', () => {
+      beforeEach(() => {
+        balances = {
+          [chain1]: ethers.utils.parseEther('80').toBigInt(),
+          [chain2]: ethers.utils.parseEther('90').toBigInt(),
+          [chain3]: ethers.utils.parseEther('100').toBigInt(),
+        };
+      });
+
+      it('should return no routes', () => {
+        const routes = strategy.getRebalancingRoutes(balances);
+
+        expect(routes).to.be.empty;
+      });
+    });
+
+    describe('when balances for chain1, chain2, and chain3 are 70, 90, and 110 respectively', () => {
+      beforeEach(() => {
+        balances = {
+          [chain1]: ethers.utils.parseEther('70').toBigInt(),
+          [chain2]: ethers.utils.parseEther('90').toBigInt(),
+          [chain3]: ethers.utils.parseEther('110').toBigInt(),
+        };
+      });
+
+      it('should return one route for 20 from chain3 to chain1', () => {
+        const routes = strategy.getRebalancingRoutes(balances);
+
+        expect(routes).to.have.lengthOf(1);
+        expect(routes[0]).to.deep.equal({
+          fromChain: 'chain3',
+          toChain: 'chain1',
+          amount: ethers.utils.parseEther('20').toBigInt(),
+        });
+      });
     });
   });
 });

typescript/cli/src/rebalancer/strategy/Strategy.ts

@@ -7,6 +7,11 @@ import {
 } from '../interfaces/IStrategy.js';
 
 export class Strategy implements IStrategy {
+  /**
+   * @param tolerance Value used to prevent rebalancing amounts that are already close to the target
+   */
+  constructor(private readonly tolerance: bigint = 0n) {}
+
   /**
    * Get the optimized routes that will rebalance all chains to the same balance
    */
@@ -16,14 +21,21 @@ export class Strategy implements IStrategy {
     const total = entries.reduce((sum, [, balance]) => sum + balance, 0n);
     // Get the average balance
     const target = total / BigInt(entries.length);
+
+    // Skip rebalancing when the average balance is very small
+    if (target < this.tolerance) {
+      return [];
+    }
+
     const surpluss: { chain: ChainName; amount: bigint }[] = [];
     const deficits: { chain: ChainName; amount: bigint }[] = [];
 
-    // Group balances by balances with surplus or deficit
+    // Group balances by balances with surplus or deficit.
+    // The tolerance is used to consider "balanced" chains that are already close to the target
     for (const [chain, balance] of entries) {
-      if (balance < target) {
+      if (balance < target - this.tolerance) {
         deficits.push({ chain, amount: target - balance });
-      } else if (balance > target) {
+      } else if (balance > target + this.tolerance) {
         surpluss.push({ chain, amount: balance - target });
       } else {
         // Do nothing as the balance is already on target

typescript/cli/src/tests/commands/helpers.ts

@@ -20,7 +20,7 @@ import {
   WarpCoreConfig,
   WarpCoreConfigSchema,
 } from '@hyperlane-xyz/sdk';
-import { Address, sleep } from '@hyperlane-xyz/utils';
+import { Address, assert, sleep } from '@hyperlane-xyz/utils';
 
 import { getContext } from '../../context/context.js';
 import { CommandContext } from '../../context/types.js';
@@ -53,6 +53,7 @@ export const CORE_CONFIG_PATH_2 = `${TEMP_PATH}/${CHAIN_NAME_2}/core-config.yaml
 export const CORE_READ_CONFIG_PATH_2 = `${TEMP_PATH}/${CHAIN_NAME_2}/core-config-read.yaml`;
 export const CHAIN_2_METADATA_PATH = `${REGISTRY_PATH}/chains/${CHAIN_NAME_2}/metadata.yaml`;
 export const CHAIN_3_METADATA_PATH = `${REGISTRY_PATH}/chains/${CHAIN_NAME_3}/metadata.yaml`;
+export const CHAIN_4_METADATA_PATH = `${REGISTRY_PATH}/chains/${CHAIN_NAME_4}/metadata.yaml`;
 
 export const WARP_CONFIG_PATH_EXAMPLE = `${EXAMPLES_PATH}/warp-route-deployment.yaml`;
 export const WARP_CONFIG_PATH_2 = `${TEMP_PATH}/${CHAIN_NAME_2}/warp-route-deployment-anvil2.yaml`;
@@ -516,3 +517,38 @@ export function hyperlaneRelayer(chains: string[], warp?: string) {
         --verbosity debug \
         --yes`;
 }
+
+export async function createSnapshot(rpcUrl: string): Promise<string> {
+  return await snapshotBaseCall<string>(rpcUrl, 'evm_snapshot', []);
+}
+
+export async function restoreSnapshot(
+  rpcUrl: string,
+  snapshotId: string,
+): Promise<void> {
+  const result = await snapshotBaseCall<boolean>(rpcUrl, 'evm_revert', [
+    snapshotId,
+  ]);
+  assert(result, 'Failed to restore snapshot');
+}
+
+async function snapshotBaseCall<T>(
+  rpcUrl: string,
+  method: string,
+  params: any[],
+): Promise<T> {
+  const response = await fetch(rpcUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      id: 1337,
+      jsonrpc: '2.0',
+      method,
+      params,
+    }),
+  });
+  const { result } = await response.json();
+  return result;
+}

typescript/cli/src/tests/commands/warp.ts

@@ -159,11 +159,19 @@ export function hyperlaneWarpSendRelay(
 export function hyperlaneWarpRebalancer(
   warpRouteId: string,
   checkFrequency: number,
+  options: {
+    strategyTolerance?: bigint;
+  } = {},
 ): ProcessPromise {
   return $`yarn workspace @hyperlane-xyz/cli run hyperlane warp rebalancer \
         --registry ${REGISTRY_PATH} \
         --warpRouteId ${warpRouteId} \
-        --checkFrequency ${checkFrequency}`;
+        --checkFrequency ${checkFrequency} \
+        ${
+          options.strategyTolerance
+            ? ['--strategyTolerance', options.strategyTolerance]
+            : ''
+        }`;
 }
 
 /**