@humanode-hyperlane/rebalancer 0.0.0-stage → 27.2.2

package/src/strategy/MinAmountStrategy.ts

@@ -0,0 +1,200 @@
+import { BigNumber } from 'bignumber.js';
+import { type Logger } from 'pino';
+
+import { type ChainMap, type Token } from '@humanode-hyperlane/sdk';
+import { fromWei, toWei } from '@humanode-hyperlane/utils';
+
+import {
+  type MinAmountStrategyConfig,
+  RebalancerMinAmountType,
+  RebalancerStrategyOptions,
+} 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';
+
+/**
+ * Strategy implementation that rebalance based on minimum amounts
+ * 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,
+    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, bridgeConfigs, metrics, tokensByChainName);
+    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
+   *
+   * 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,
+    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 + simulatedBalances[chain],
+      0n,
+    );
+
+    return this.chains.reduce(
+      (acc, chain) => {
+        const chainConfig = this.config[chain];
+        const balance = simulatedBalances[chain];
+        let minAmount: bigint;
+        let targetAmount: bigint;
+
+        if (chainConfig.minAmount.type === RebalancerMinAmountType.Absolute) {
+          const token = this.getTokenByChainName(chain);
+
+          minAmount = BigInt(toWei(chainConfig.minAmount.min, token.decimals));
+          targetAmount = BigInt(
+            toWei(chainConfig.minAmount.target, token.decimals),
+          );
+        } else {
+          minAmount = BigInt(
+            BigNumber(totalCollateral.toString())
+              .times(chainConfig.minAmount.min)
+              .toFixed(0, BigNumber.ROUND_FLOOR),
+          );
+          targetAmount = BigInt(
+            BigNumber(totalCollateral.toString())
+              .times(chainConfig.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,108 @@
+import { expect } from 'chai';
+import { ethers } from 'ethers';
+import { pino } from 'pino';
+
+import { type ChainMap, Token, TokenStandard } from '@humanode-hyperlane/sdk';
+
+import {
+  type MinAmountStrategyConfig,
+  RebalancerMinAmountType,
+  RebalancerStrategyOptions,
+  type StrategyConfig,
+  type WeightedStrategyConfig,
+} from '../config/types.js';
+
+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,157 @@
+import { type Logger } from 'pino';
+
+import { type ChainMap, type Token } from '@humanode-hyperlane/sdk';
+
+import {
+  ExecutionType,
+  RebalancerStrategyOptions,
+  type StrategyConfig,
+} from '../config/types.js';
+import { type IStrategy } from '../interfaces/IStrategy.js';
+import { type Metrics } from '../metrics/Metrics.js';
+import type {
+  BridgeConfigWithOverride,
+  InventoryBridgeConfig,
+  MovableCollateralBridgeConfig,
+} 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 {
+  /**
+   * 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
+   * @param minAmountsByChain Optional minimum amounts per chain for filtering routes
+   * @returns A concrete strategy implementation
+   */
+  static createStrategy(
+    strategyConfigs: StrategyConfig[],
+    tokensByChainName: ChainMap<Token>,
+    initialTotalCollateral: bigint,
+    logger: Logger,
+    metrics?: Metrics,
+    minAmountsByChain?: ChainMap<bigint>,
+  ): 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,
+        minAmountsByChain,
+      );
+    }
+
+    // Multiple strategies - create CompositeStrategy
+    const subStrategies = strategyConfigs.map((config) =>
+      this.createSingleStrategy(
+        config,
+        tokensByChainName,
+        initialTotalCollateral,
+        logger,
+        metrics,
+        minAmountsByChain,
+      ),
+    );
+    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,
+    _minAmountsByChain?: ChainMap<bigint>,
+  ): IStrategy {
+    const bridgeConfigs = this.extractBridgeConfigs(strategyConfig);
+
+    switch (strategyConfig.rebalanceStrategy) {
+      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)) {
+      const baseConfig = {
+        bridgeMinAcceptedAmount: config.bridgeMinAcceptedAmount ?? 0,
+      };
+
+      const executionType =
+        config.executionType ?? ExecutionType.MovableCollateral;
+
+      if (executionType === ExecutionType.Inventory) {
+        bridgeConfigs[chain] = {
+          ...baseConfig,
+          executionType: 'inventory',
+          externalBridge: config.externalBridge!, // Validated by config schema
+          override: config.override as ChainMap<Partial<InventoryBridgeConfig>>,
+        };
+      } else {
+        bridgeConfigs[chain] = {
+          ...baseConfig,
+          executionType: 'movableCollateral',
+          bridge: config.bridge!, // Validated by config schema
+          override: config.override as ChainMap<
+            Partial<MovableCollateralBridgeConfig>
+          >,
+        };
+      }
+    }
+
+    return bridgeConfigs;
+  }
+}