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

package/src/strategy/MinAmountStrategy.ts

@@ -0,0 +1,170 @@
+import { BigNumber } from 'bignumber.js';
+import { Logger } from 'pino';
+
+import {
+  type ChainMap,
+  type MinAmountStrategyConfig,
+  RebalancerMinAmountType,
+  type Token,
+} from '@hyperlane-xyz/sdk';
+import { fromWei, toWei } from '@hyperlane-xyz/utils';
+
+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 minimum amounts
+ * It ensures each chain has at least the specified minimum amount
+ */
+export class MinAmountStrategy extends BaseStrategy {
+  private readonly config: MinAmountStrategyConfig = {};
+  protected readonly logger: Logger;
+
+  constructor(
+    config: MinAmountStrategyConfig,
+    private readonly tokensByChainName: ChainMap<Token>,
+    initialTotalCollateral: bigint,
+    logger: Logger,
+    metrics?: Metrics,
+  ) {
+    const chains = Object.keys(config);
+    const log = logger.child({ class: MinAmountStrategy.name });
+    super(chains, log, metrics);
+    this.logger = log;
+
+    const minAmountType = config[chains[0]].minAmount.type;
+    this.validateAmounts(initialTotalCollateral, minAmountType, config);
+
+    for (const chain of chains) {
+      const { min, target } = config[chain].minAmount;
+
+      // check range constraints
+      if (BigNumber(target).lt(min)) {
+        throw new Error(
+          `Target (${target}) must be greater than or equal to min (${min}) for chain ${chain}`,
+        );
+      }
+
+      if (BigNumber(min).lt(0)) {
+        throw new Error(
+          `Minimum amount (${min}) cannot be negative for chain ${chain}`,
+        );
+      }
+
+      if (BigNumber(target).lt(0)) {
+        throw new Error(
+          `Target amount (${target}) cannot be negative for chain ${chain}`,
+        );
+      }
+    }
+
+    this.config = config;
+    this.logger.info('MinAmountStrategy created');
+  }
+
+  /**
+   * 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
+   */
+  protected getCategorizedBalances(rawBalances: RawBalances): {
+    surpluses: Delta[];
+    deficits: Delta[];
+  } {
+    const totalCollateral = this.chains.reduce(
+      (sum, chain) => sum + rawBalances[chain],
+      0n,
+    );
+
+    return this.chains.reduce(
+      (acc, chain) => {
+        const config = this.config[chain];
+        const balance = rawBalances[chain];
+        let minAmount: bigint;
+        let targetAmount: bigint;
+
+        if (config.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));
+        } else {
+          minAmount = BigInt(
+            BigNumber(totalCollateral.toString())
+              .times(config.minAmount.min)
+              .toFixed(0, BigNumber.ROUND_FLOOR),
+          );
+          targetAmount = BigInt(
+            BigNumber(totalCollateral.toString())
+              .times(config.minAmount.target)
+              .toFixed(0, BigNumber.ROUND_FLOOR),
+          );
+        }
+
+        // If balance is less than minAmount, it has a deficit
+        if (balance < minAmount) {
+          acc.deficits.push({ chain, amount: targetAmount - balance });
+        } else {
+          // Any chain with more than minAmount potentially has surplus
+          const surplus = balance - minAmount;
+          if (surplus > 0n) {
+            acc.surpluses.push({ chain, amount: surplus });
+          }
+        }
+
+        return acc;
+      },
+      {
+        surpluses: [] as Delta[],
+        deficits: [] as Delta[],
+      },
+    );
+  }
+
+  protected getTokenByChainName(chainName: string): Token {
+    const token = this.tokensByChainName[chainName];
+
+    if (token === undefined) {
+      throw new Error(`Token not found for chain ${chainName}`);
+    }
+
+    return token;
+  }
+
+  private validateAmounts(
+    totalCollateral: bigint,
+    minAmountType: RebalancerMinAmountType,
+    config?: MinAmountStrategyConfig,
+  ): void {
+    config ??= this.config;
+
+    if (minAmountType === RebalancerMinAmountType.Absolute) {
+      let totalTargets = 0n;
+      let decimals: number = 0;
+
+      for (const chainName of this.chains) {
+        const token = this.getTokenByChainName(chainName);
+        // all the tokens have the same amount of decimals
+        decimals = token.decimals;
+
+        totalTargets += BigInt(
+          toWei(config[chainName].minAmount.target, token.decimals),
+        );
+      }
+
+      if (totalTargets > totalCollateral) {
+        throw new Error(
+          `Consider reducing the targets as the sum (${fromWei(
+            totalTargets.toString(),
+            decimals,
+          )}) is greater than sum of collaterals (${fromWei(
+            totalCollateral.toString(),
+            decimals,
+          )})`,
+        );
+      }
+    }
+  }
+}

package/src/strategy/StrategyFactory.test.ts

@@ -0,0 +1,109 @@
+import { expect } from 'chai';
+import { ethers } from 'ethers';
+import { pino } from 'pino';
+
+import {
+  type ChainMap,
+  MinAmountStrategyConfig,
+  RebalancerMinAmountType,
+  RebalancerStrategyOptions,
+  StrategyConfig,
+  Token,
+  TokenStandard,
+  WeightedStrategyConfig,
+} from '@hyperlane-xyz/sdk';
+
+import { MinAmountStrategy } from './MinAmountStrategy.js';
+import { StrategyFactory } from './StrategyFactory.js';
+import { WeightedStrategy } from './WeightedStrategy.js';
+
+const testLogger = pino({ level: 'silent' });
+
+describe('StrategyFactory', () => {
+  const chain1 = 'chain1';
+  const chain2 = 'chain2';
+  const totalCollateral = BigInt(20e18);
+
+  const tokensByChainName: ChainMap<Token> = {};
+  const tokenArgs = {
+    name: 'token',
+    decimals: 18,
+    symbol: 'TOKEN',
+    standard: TokenStandard.ERC20,
+    addressOrDenom: '',
+  };
+  tokensByChainName[chain1] = new Token({ ...tokenArgs, chainName: chain1 });
+  tokensByChainName[chain2] = new Token({ ...tokenArgs, chainName: chain2 });
+
+  describe('createStrategy', () => {
+    it('creates a WeightedStrategy when given weighted configuration', () => {
+      const config: WeightedStrategyConfig = {
+        [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 strategyConfig: StrategyConfig = {
+        rebalanceStrategy: RebalancerStrategyOptions.Weighted,
+        chains: config,
+      };
+
+      const strategy = StrategyFactory.createStrategy(
+        strategyConfig,
+        tokensByChainName,
+        totalCollateral,
+        testLogger,
+      );
+      expect(strategy).to.be.instanceOf(WeightedStrategy);
+    });
+
+    it('creates a MinAmountStrategy when given minAmount configuration', () => {
+      const config: MinAmountStrategyConfig = {
+        [chain1]: {
+          minAmount: {
+            min: 8,
+            target: 10,
+            type: RebalancerMinAmountType.Absolute,
+          },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain2]: {
+          minAmount: {
+            min: 8,
+            target: 10,
+            type: RebalancerMinAmountType.Absolute,
+          },
+          bridge: ethers.constants.AddressZero,
+          bridgeLockTime: 1,
+        },
+      };
+
+      const strategyConfig: StrategyConfig = {
+        rebalanceStrategy: RebalancerStrategyOptions.MinAmount,
+        chains: config,
+      };
+
+      const strategy = StrategyFactory.createStrategy(
+        strategyConfig,
+        tokensByChainName,
+        totalCollateral,
+        testLogger,
+      );
+      expect(strategy).to.be.instanceOf(MinAmountStrategy);
+    });
+  });
+});

package/src/strategy/StrategyFactory.ts

@@ -0,0 +1,48 @@
+import { Logger } from 'pino';
+
+import {
+  ChainMap,
+  RebalancerStrategyOptions,
+  StrategyConfig,
+  Token,
+} from '@hyperlane-xyz/sdk';
+
+import { type IStrategy } from '../interfaces/IStrategy.js';
+import { Metrics } from '../metrics/Metrics.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
+   * @returns A concrete strategy implementation
+   */
+  static createStrategy(
+    strategyConfig: StrategyConfig,
+    tokensByChainName: ChainMap<Token>,
+    initialTotalCollateral: bigint,
+    logger: Logger,
+    metrics?: Metrics,
+  ): IStrategy {
+    switch (strategyConfig.rebalanceStrategy) {
+      case RebalancerStrategyOptions.Weighted:
+        return new WeightedStrategy(strategyConfig.chains, logger, metrics);
+      case RebalancerStrategyOptions.MinAmount:
+        return new MinAmountStrategy(
+          strategyConfig.chains,
+          tokensByChainName,
+          initialTotalCollateral,
+          logger,
+          metrics,
+        );
+      default: {
+        throw new Error('Unsupported strategy type');
+      }
+    }
+  }
+}