@hyperlane-xyz/rebalancer 0.1.0-beta.5a8bd28ab

package/src/strategy/WeightedStrategy.test.ts

@@ -0,0 +1,408 @@
+import { expect } from 'chai';
+import { ethers } from 'ethers';
+import { pino } from 'pino';
+
+import type { ChainName } from '@hyperlane-xyz/sdk';
+
+import type { RawBalances } from '../interfaces/IStrategy.js';
+
+import { WeightedStrategy } from './WeightedStrategy.js';
+
+const testLogger = pino({ level: 'silent' });
+
+describe('WeightedStrategy', () => {
+  let chain1: ChainName;
+  let chain2: ChainName;
+  let chain3: ChainName;
+
+  beforeEach(() => {
+    chain1 = 'chain1';
+    chain2 = 'chain2';
+    chain3 = 'chain3';
+  });
+
+  describe('constructor', () => {
+    it('should throw an error when less than two chains are configured', () => {
+      expect(
+        () =>
+          new WeightedStrategy(
+            {
+              [chain1]: {
+                weighted: { weight: 100n, tolerance: 0n },
+                bridge: ethers.constants.AddressZero,
+                bridgeLockTime: 1,
+              },
+            },
+            testLogger,
+          ),
+      ).to.throw('At least two chains must be configured');
+    });
+
+    it('should throw an error when weight is negative', () => {
+      expect(
+        () =>
+          new WeightedStrategy(
+            {
+              [chain1]: {
+                weighted: { weight: 100n, tolerance: 0n },
+                bridge: ethers.constants.AddressZero,
+                bridgeLockTime: 1,
+              },
+              [chain2]: {
+                weighted: { weight: -1n, tolerance: 0n },
+                bridge: ethers.constants.AddressZero,
+                bridgeLockTime: 1,
+              },
+            },
+            testLogger,
+          ),
+      ).to.throw('Weight (-1) must not be negative for chain2');
+    });
+
+    it('should throw an error when the total weight is 0', () => {
+      expect(
+        () =>
+          new WeightedStrategy(
+            {
+              [chain1]: {
+                weighted: { weight: 0n, tolerance: 0n },
+                bridge: ethers.constants.AddressZero,
+                bridgeLockTime: 1,
+              },
+              [chain2]: {
+                weighted: { weight: 0n, tolerance: 0n },
+                bridge: ethers.constants.AddressZero,
+                bridgeLockTime: 1,
+              },
+            },
+            testLogger,
+          ),
+      ).to.throw('The total weight for all chains must be greater than 0');
+    });
+
+    it('should throw an error when tolerance is less than 0 or greater than 100', () => {
+      expect(
+        () =>
+          new WeightedStrategy(
+            {
+              [chain1]: {
+                weighted: { weight: 100n, tolerance: 0n },
+                bridge: ethers.constants.AddressZero,
+                bridgeLockTime: 1,
+              },
+              [chain2]: {
+                weighted: { weight: 100n, tolerance: -1n },
+                bridge: ethers.constants.AddressZero,
+                bridgeLockTime: 1,
+              },
+            },
+            testLogger,
+          ),
+      ).to.throw('Tolerance (-1) must be between 0 and 100 for chain2');
+
+      expect(
+        () =>
+          new WeightedStrategy(
+            {
+              [chain1]: {
+                weighted: { weight: 100n, tolerance: 100n },
+                bridge: ethers.constants.AddressZero,
+                bridgeLockTime: 1,
+              },
+              [chain2]: {
+                weighted: { weight: 100n, tolerance: 101n },
+                bridge: ethers.constants.AddressZero,
+                bridgeLockTime: 1,
+              },
+            },
+            testLogger,
+          ),
+      ).to.throw('Tolerance (101) must be between 0 and 100 for chain2');
+    });
+  });
+
+  describe('getRebalancingRoutes', () => {
+    it('should throw an error when raw balances chains length does not match configured chains length', () => {
+      expect(() =>
+        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,
+            },
+          },
+          testLogger,
+        ).getRebalancingRoutes({
+          [chain1]: ethers.utils.parseEther('100').toBigInt(),
+          [chain2]: ethers.utils.parseEther('200').toBigInt(),
+          [chain3]: ethers.utils.parseEther('300').toBigInt(),
+        }),
+      ).to.throw('Config chains do not match raw balances chains length');
+    });
+
+    it('should throw an error when a raw balance is missing', () => {
+      expect(() =>
+        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,
+            },
+          },
+          testLogger,
+        ).getRebalancingRoutes({
+          [chain1]: ethers.utils.parseEther('100').toBigInt(),
+          [chain3]: ethers.utils.parseEther('300').toBigInt(),
+        } as RawBalances),
+      ).to.throw('Raw balance for chain chain2 not found');
+    });
+
+    it('should throw an error when a raw balance is negative', () => {
+      expect(() =>
+        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,
+            },
+          },
+          testLogger,
+        ).getRebalancingRoutes({
+          [chain1]: ethers.utils.parseEther('100').toBigInt(),
+          [chain2]: ethers.utils.parseEther('-200').toBigInt(),
+        }),
+      ).to.throw('Raw balance for chain chain2 is negative');
+    });
+
+    it('should return an empty array when all chains are balanced', () => {
+      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,
+          },
+        },
+        testLogger,
+      );
+
+      const rawBalances = {
+        [chain1]: ethers.utils.parseEther('100').toBigInt(),
+        [chain2]: ethers.utils.parseEther('100').toBigInt(),
+      };
+
+      const routes = strategy.getRebalancingRoutes(rawBalances);
+
+      expect(routes).to.be.empty;
+    });
+
+    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,
+          },
+        },
+        testLogger,
+      );
+
+      const rawBalances = {
+        [chain1]: ethers.utils.parseEther('100').toBigInt(),
+        [chain2]: ethers.utils.parseEther('200').toBigInt(),
+      };
+
+      const routes = strategy.getRebalancingRoutes(rawBalances);
+
+      expect(routes).to.deep.equal([
+        {
+          origin: chain2,
+          destination: chain1,
+          amount: ethers.utils.parseEther('50').toBigInt(),
+        },
+      ]);
+    });
+
+    it('should return an empty array when a chain is unbalanced but has tolerance', () => {
+      const strategy = new WeightedStrategy(
+        {
+          [chain1]: {
+            weighted: { weight: 100n, tolerance: 1n },
+            bridge: ethers.constants.AddressZero,
+            bridgeLockTime: 1,
+          },
+          [chain2]: {
+            weighted: { weight: 100n, tolerance: 1n },
+            bridge: ethers.constants.AddressZero,
+            bridgeLockTime: 1,
+          },
+        },
+        testLogger,
+      );
+
+      const rawBalances = {
+        [chain1]: ethers.utils.parseEther('100').toBigInt(),
+        [chain2]: ethers.utils.parseEther('101').toBigInt(),
+      };
+
+      const routes = strategy.getRebalancingRoutes(rawBalances);
+
+      expect(routes).to.be.empty;
+    });
+
+    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,
+          },
+        },
+        testLogger,
+      );
+
+      const rawBalances = {
+        [chain1]: ethers.utils.parseEther('100').toBigInt(),
+        [chain2]: ethers.utils.parseEther('200').toBigInt(),
+        [chain3]: ethers.utils.parseEther('300').toBigInt(),
+      };
+
+      const routes = strategy.getRebalancingRoutes(rawBalances);
+
+      expect(routes).to.deep.equal([
+        {
+          origin: chain3,
+          destination: chain1,
+          amount: ethers.utils.parseEther('100').toBigInt(),
+        },
+      ]);
+    });
+    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,
+          },
+        },
+        testLogger,
+      );
+
+      const rawBalances = {
+        [chain1]: ethers.utils.parseEther('100').toBigInt(),
+        [chain2]: ethers.utils.parseEther('100').toBigInt(),
+        [chain3]: ethers.utils.parseEther('500').toBigInt(),
+      };
+
+      const routes = strategy.getRebalancingRoutes(rawBalances);
+
+      expect(routes).to.deep.equal([
+        {
+          origin: chain3,
+          destination: chain1,
+          amount: 133333333333333333333n,
+        },
+        {
+          origin: chain3,
+          destination: chain2,
+          amount: 133333333333333333333n,
+        },
+      ]);
+    });
+
+    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,
+          },
+        },
+        testLogger,
+      );
+
+      const rawBalances = {
+        [chain1]: ethers.utils.parseEther('100').toBigInt(),
+        [chain2]: ethers.utils.parseEther('100').toBigInt(),
+        [chain3]: ethers.utils.parseEther('100').toBigInt(),
+      };
+
+      const routes = strategy.getRebalancingRoutes(rawBalances);
+
+      expect(routes).to.deep.equal([
+        {
+          origin: chain2,
+          destination: chain1,
+          amount: ethers.utils.parseEther('25').toBigInt(),
+        },
+        {
+          origin: chain3,
+          destination: chain1,
+          amount: ethers.utils.parseEther('25').toBigInt(),
+        },
+      ]);
+    });
+  });
+});

package/src/strategy/WeightedStrategy.ts

@@ -0,0 +1,93 @@
+import { Logger } from 'pino';
+
+import type { WeightedStrategyConfig } from '@hyperlane-xyz/sdk';
+
+import type { RawBalances } from '../interfaces/IStrategy.js';
+import { Metrics } from '../metrics/Metrics.js';
+
+import { BaseStrategy, type Delta } from './BaseStrategy.js';
+
+/**
+ * Strategy implementation that rebalance based on weights
+ * It distributes funds across chains based on their weights
+ */
+export class WeightedStrategy extends BaseStrategy {
+  private readonly config: WeightedStrategyConfig;
+  private readonly totalWeight: bigint;
+  protected readonly logger: Logger;
+
+  constructor(
+    config: WeightedStrategyConfig,
+    logger: Logger,
+    metrics?: Metrics,
+  ) {
+    const chains = Object.keys(config);
+    const log = logger.child({ class: WeightedStrategy.name });
+    super(chains, log, metrics);
+    this.logger = log;
+
+    let totalWeight = 0n;
+
+    for (const chain of chains) {
+      const { weight, tolerance } = config[chain].weighted;
+
+      if (weight < 0n) {
+        throw new Error(`Weight (${weight}) must not be negative for ${chain}`);
+      }
+
+      if (tolerance < 0n || tolerance > 100n) {
+        throw new Error(
+          `Tolerance (${tolerance}) must be between 0 and 100 for ${chain}`,
+        );
+      }
+
+      totalWeight += weight;
+    }
+
+    if (totalWeight <= 0n) {
+      throw new Error('The total weight for all chains must be greater than 0');
+    }
+
+    this.config = config;
+    this.totalWeight = totalWeight;
+    this.logger.info('WeightedStrategy created');
+  }
+
+  /**
+   * Gets balances categorized by surplus and deficit based on weights
+   */
+  protected getCategorizedBalances(rawBalances: RawBalances): {
+    surpluses: Delta[];
+    deficits: Delta[];
+  } {
+    // Get the total balance from all chains
+    const total = this.chains.reduce(
+      (sum, chain) => sum + rawBalances[chain],
+      0n,
+    );
+
+    return this.chains.reduce(
+      (acc, chain) => {
+        const { weight, tolerance } = this.config[chain].weighted;
+        const target = (total * weight) / this.totalWeight;
+        const toleranceAmount = (target * tolerance) / 100n;
+        const balance = rawBalances[chain];
+
+        // Apply the tolerance to deficits to prevent small imbalances
+        if (balance < target - toleranceAmount) {
+          acc.deficits.push({ chain, amount: target - balance });
+        } else if (balance > target) {
+          acc.surpluses.push({ chain, amount: balance - target });
+        } else {
+          // Do nothing as the balance is already on target
+        }
+
+        return acc;
+      },
+      {
+        surpluses: [] as Delta[],
+        deficits: [] as Delta[],
+      },
+    );
+  }
+}

package/src/strategy/index.ts

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

package/src/test/helpers.ts

@@ -0,0 +1,46 @@
+import { ethers } from 'ethers';
+
+import { RebalancerStrategyOptions } from '@hyperlane-xyz/sdk';
+
+import type { RebalancerConfig } from '../config/RebalancerConfig.js';
+import type { IRebalancer } from '../interfaces/IRebalancer.js';
+import type { RebalancingRoute } from '../interfaces/IStrategy.js';
+
+export class MockRebalancer implements IRebalancer {
+  rebalance(_routes: RebalancingRoute[]): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+export function buildTestConfig(
+  overrides: Partial<RebalancerConfig> = {},
+  chains: string[] = ['chain1'],
+): RebalancerConfig {
+  const baseChains = chains.reduce(
+    (acc, chain) => {
+      (acc as any)[chain] = {
+        bridgeLockTime: 60 * 1000,
+        bridge: ethers.constants.AddressZero,
+        weighted: {
+          weight: BigInt(1),
+          tolerance: BigInt(0),
+        },
+      };
+      return acc;
+    },
+    {} as Record<string, any>,
+  );
+
+  return {
+    warpRouteId: 'test-route',
+    strategyConfig: {
+      rebalanceStrategy: RebalancerStrategyOptions.Weighted,
+      chains: {
+        ...baseChains,
+        ...(overrides.strategyConfig?.chains ?? {}),
+      },
+      ...overrides.strategyConfig,
+    },
+    ...overrides,
+  } as any as RebalancerConfig;
+}

package/src/utils/ExplorerClient.ts

@@ -0,0 +1,99 @@
+import type { Logger } from 'pino';
+
+export type InflightRebalanceQueryParams = {
+  bridges: string[];
+  domains: number[];
+  txSender: string;
+  limit?: number;
+};
+
+export class ExplorerClient {
+  constructor(private readonly baseUrl: string) {}
+
+  private toBytea(addr: string): string {
+    return addr.replace(/^0x/i, '\\x').toLowerCase();
+  }
+
+  async hasUndeliveredRebalance(
+    params: InflightRebalanceQueryParams,
+    logger: Logger,
+  ): Promise<boolean> {
+    const { bridges, domains, txSender, limit = 5 } = params;
+
+    const variables = {
+      senders: bridges.map((a) => this.toBytea(a)),
+      recipients: bridges.map((a) => this.toBytea(a)),
+      originDomains: domains,
+      destDomains: domains,
+      txSenders: [this.toBytea(txSender)],
+      limit,
+    };
+
+    logger.debug({ variables }, 'Explorer query variables');
+
+    const query = `
+      query InflightRebalancesForRoute(
+        $senders: [bytea!],
+        $recipients: [bytea!],
+        $originDomains: [Int!],
+        $destDomains: [Int!],
+        $txSenders: [bytea!],
+        $limit: Int = 25
+      ) {
+        message_view(
+          where: {
+            _and: [
+              { is_delivered: { _eq: false } },
+              { sender: { _in: $senders } },
+              { recipient: { _in: $recipients } },
+              { origin_domain_id: { _in: $originDomains } },
+              { destination_domain_id: { _in: $destDomains } },
+              { origin_tx_sender: { _in: $txSenders } }
+            ]
+          }
+          order_by: { origin_tx_id: desc }
+          limit: $limit
+        ) {
+          msg_id
+          origin_domain_id
+          destination_domain_id
+          sender
+          recipient
+          origin_tx_hash
+          origin_tx_sender
+          is_delivered
+        }
+      }`;
+
+    const res = await fetch(this.baseUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query, variables }),
+    });
+
+    logger.debug({ status: res.status }, 'Explorer query response');
+
+    if (!res.ok) {
+      let errorDetails: string;
+      try {
+        const errorJson = await res.json();
+        errorDetails = JSON.stringify(errorJson);
+      } catch (_e) {
+        try {
+          // Fallback to text if JSON parsing fails
+          errorDetails = await res.text();
+        } catch (_textError) {
+          errorDetails = 'Unable to read response body';
+        }
+      }
+      throw new Error(`Explorer query failed: ${res.status} ${errorDetails}`);
+    }
+
+    const json = await res.json();
+    const rows = json?.data?.message_view ?? [];
+
+    logger.debug({ rows }, 'Explorer query rows');
+
+    return rows.length > 0;
+  }
+}