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

package/src/core/WithSemaphore.ts

@@ -0,0 +1,92 @@
+import type { Logger } from 'pino';
+
+import { RebalancerConfig } from '../config/RebalancerConfig.js';
+import type { IRebalancer } from '../interfaces/IRebalancer.js';
+import type { RebalancingRoute } from '../interfaces/IStrategy.js';
+
+/**
+ * Prevents frequent rebalancing operations while bridges complete.
+ */
+export class WithSemaphore implements IRebalancer {
+  // Timestamp until which rebalancing should be blocked
+  private waitUntil: number = 0;
+  // Lock to prevent concurrent rebalance execution
+  private executing: boolean = false;
+  private readonly logger: Logger;
+
+  constructor(
+    private readonly config: RebalancerConfig,
+    private readonly rebalancer: IRebalancer,
+    logger: Logger,
+  ) {
+    this.logger = logger.child({ class: WithSemaphore.name });
+  }
+
+  /**
+   * Rebalance with timing control
+   * @param routes - Routes to process
+   */
+  async rebalance(routes: RebalancingRoute[]): Promise<void> {
+    if (this.executing) {
+      this.logger.info('Currently executing rebalance. Skipping.');
+
+      return;
+    }
+
+    // No routes mean the system is balanced so we reset the timer to allow new rebalancing
+    if (!routes.length) {
+      this.logger.info(
+        'No routes to execute. Assuming rebalance is complete. Resetting semaphore timer.',
+      );
+
+      this.waitUntil = 0;
+      return;
+    }
+
+    // Skip if still in waiting period
+    if (Date.now() < this.waitUntil) {
+      this.logger.info('Still in waiting period. Skipping rebalance.');
+
+      return;
+    }
+
+    // The wait period will be determined by the bridge with the highest wait tolerance
+    const highestTolerance = this.getHighestLockTime(routes);
+
+    try {
+      // Execute rebalance
+      this.executing = true;
+      await this.rebalancer.rebalance(routes);
+    } finally {
+      this.executing = false;
+    }
+
+    // Set new waiting period
+    this.waitUntil = Date.now() + highestTolerance;
+
+    this.logger.info(
+      {
+        highestTolerance,
+        waitUntil: this.waitUntil,
+      },
+      'Rebalance semaphore locked',
+    );
+  }
+
+  private getHighestLockTime(routes: RebalancingRoute[]) {
+    return routes.reduce((highest, route) => {
+      const origin = this.config.strategyConfig.chains[route.origin];
+
+      if (!origin) {
+        this.logger.error({ route }, 'Chain not found in config. Skipping.');
+        throw new Error(`Chain ${route.origin} not found in config`);
+      }
+
+      const bridgeLockTime = origin.bridgeLockTime;
+      const overrideLockTime =
+        origin.override?.[route.destination]?.bridgeLockTime ?? 0;
+
+      return Math.max(highest, bridgeLockTime, overrideLockTime);
+    }, 0);
+  }
+}

package/src/factories/RebalancerContextFactory.ts

@@ -0,0 +1,210 @@
+import { Logger } from 'pino';
+
+import { IRegistry } from '@hyperlane-xyz/registry';
+import {
+  type ChainMap,
+  MultiProtocolProvider,
+  MultiProvider,
+  type Token,
+  WarpCore,
+} from '@hyperlane-xyz/sdk';
+import { objMap } from '@hyperlane-xyz/utils';
+
+import { RebalancerConfig } from '../config/RebalancerConfig.js';
+import { Rebalancer } from '../core/Rebalancer.js';
+import { WithSemaphore } from '../core/WithSemaphore.js';
+import type { IRebalancer } from '../interfaces/IRebalancer.js';
+import type { IStrategy } from '../interfaces/IStrategy.js';
+import { Metrics } from '../metrics/Metrics.js';
+import { PriceGetter } from '../metrics/PriceGetter.js';
+import { Monitor } from '../monitor/Monitor.js';
+import { StrategyFactory } from '../strategy/StrategyFactory.js';
+import { isCollateralizedTokenEligibleForRebalancing } from '../utils/index.js';
+
+export class RebalancerContextFactory {
+  /**
+   * @param config - The rebalancer config
+   * @param warpCore - An instance of `WarpCore` configured for the specified `warpRouteId`.
+   * @param tokensByChainName - A map of chain->token to ease the lookup of token by chain
+   * @param multiProvider - MultiProvider instance
+   * @param registry - IRegistry instance
+   * @param logger - Logger instance
+   */
+  private constructor(
+    private readonly config: RebalancerConfig,
+    private readonly warpCore: WarpCore,
+    private readonly tokensByChainName: ChainMap<Token>,
+    private readonly multiProvider: MultiProvider,
+    private readonly registry: IRegistry,
+    private readonly logger: Logger,
+  ) {}
+
+  /**
+   * @param config - The rebalancer config
+   * @param multiProvider - MultiProvider instance
+   * @param multiProtocolProvider - MultiProtocolProvider instance (optional, created from multiProvider if not provided)
+   * @param registry - IRegistry instance
+   * @param logger - Logger instance
+   */
+  public static async create(
+    config: RebalancerConfig,
+    multiProvider: MultiProvider,
+    multiProtocolProvider: MultiProtocolProvider | undefined,
+    registry: IRegistry,
+    logger: Logger,
+  ): Promise<RebalancerContextFactory> {
+    logger.debug(
+      {
+        warpRouteId: config.warpRouteId,
+      },
+      'Creating RebalancerContextFactory',
+    );
+    const addresses = await registry.getAddresses();
+
+    // The Sealevel warp adapters require the Mailbox address, so we
+    // get mailboxes for all chains and merge them with the chain metadata.
+    const mailboxes = objMap(addresses, (_, { mailbox }) => ({ mailbox }));
+
+    // Create MultiProtocolProvider (convert from MultiProvider if not provided)
+    const mpp =
+      multiProtocolProvider ??
+      MultiProtocolProvider.fromMultiProvider(multiProvider);
+    const provider = mpp.extendChainMetadata(mailboxes);
+
+    const warpCoreConfig = await registry.getWarpRoute(config.warpRouteId);
+    if (!warpCoreConfig) {
+      throw new Error(
+        `Warp route config for ${config.warpRouteId} not found in registry`,
+      );
+    }
+    const warpCore = WarpCore.FromConfig(provider, warpCoreConfig);
+    const tokensByChainName = Object.fromEntries(
+      warpCore.tokens.map((t) => [t.chainName, t]),
+    );
+
+    logger.debug(
+      {
+        warpRouteId: config.warpRouteId,
+      },
+      'RebalancerContextFactory created successfully',
+    );
+    return new RebalancerContextFactory(
+      config,
+      warpCore,
+      tokensByChainName,
+      multiProvider,
+      registry,
+      logger,
+    );
+  }
+
+  public getWarpCore(): WarpCore {
+    return this.warpCore;
+  }
+
+  public getTokenForChain(chainName: string): Token | undefined {
+    return this.tokensByChainName[chainName];
+  }
+
+  public async createMetrics(coingeckoApiKey?: string): Promise<Metrics> {
+    this.logger.debug(
+      { warpRouteId: this.config.warpRouteId },
+      'Creating Metrics',
+    );
+    const tokenPriceGetter = PriceGetter.create(
+      this.multiProvider.metadata,
+      this.logger,
+      coingeckoApiKey,
+    );
+    const warpDeployConfig = await this.registry.getWarpDeployConfig(
+      this.config.warpRouteId,
+    );
+
+    return new Metrics(
+      tokenPriceGetter,
+      warpDeployConfig,
+      this.warpCore,
+      this.config.warpRouteId,
+      this.logger,
+    );
+  }
+
+  public createMonitor(checkFrequency: number): Monitor {
+    this.logger.debug(
+      {
+        warpRouteId: this.config.warpRouteId,
+        checkFrequency: checkFrequency,
+      },
+      'Creating Monitor',
+    );
+    return new Monitor(checkFrequency, this.warpCore, this.logger);
+  }
+
+  public async createStrategy(metrics?: Metrics): Promise<IStrategy> {
+    this.logger.debug(
+      {
+        warpRouteId: this.config.warpRouteId,
+        strategyType: this.config.strategyConfig.rebalanceStrategy,
+      },
+      'Creating Strategy',
+    );
+    return StrategyFactory.createStrategy(
+      this.config.strategyConfig,
+      this.tokensByChainName,
+      await this.getInitialTotalCollateral(),
+      this.logger,
+      metrics,
+    );
+  }
+
+  public createRebalancer(metrics?: Metrics): IRebalancer {
+    this.logger.debug(
+      { warpRouteId: this.config.warpRouteId },
+      'Creating Rebalancer',
+    );
+    const rebalancer = new Rebalancer(
+      objMap(this.config.strategyConfig.chains, (_, v) => ({
+        bridge: v.bridge,
+        bridgeMinAcceptedAmount: v.bridgeMinAcceptedAmount ?? 0,
+        bridgeIsWarp: v.bridgeIsWarp ?? false,
+        override: v.override,
+      })),
+      this.warpCore,
+      this.multiProvider.metadata,
+      this.tokensByChainName,
+      this.multiProvider,
+      this.logger,
+      metrics,
+    );
+
+    // Wrap with semaphore for concurrency control
+    const withSemaphore = new WithSemaphore(
+      this.config,
+      rebalancer,
+      this.logger,
+    );
+
+    return withSemaphore;
+  }
+
+  private async getInitialTotalCollateral(): Promise<bigint> {
+    let initialTotalCollateral = 0n;
+
+    const chainNames = new Set(Object.keys(this.config.strategyConfig.chains));
+
+    await Promise.all(
+      this.warpCore.tokens.map(async (token) => {
+        if (
+          isCollateralizedTokenEligibleForRebalancing(token) &&
+          chainNames.has(token.chainName)
+        ) {
+          const adapter = token.getHypAdapter(this.warpCore.multiProvider);
+          const bridgedSupply = await adapter.getBridgedSupply();
+          initialTotalCollateral += bridgedSupply ?? 0n;
+        }
+      }),
+    );
+
+    return initialTotalCollateral;
+  }
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * @hyperlane-xyz/rebalancer
+ *
+ * Hyperlane Warp Route Collateral Rebalancer
+ *
+ * This package provides functionality for automatically rebalancing collateral
+ * across Hyperlane warp routes to maintain optimal token distribution.
+ */
+
+// Core service
+export { RebalancerService } from './core/RebalancerService.js';
+export type {
+  RebalancerServiceConfig,
+  ManualRebalanceRequest,
+} from './core/RebalancerService.js';
+
+// Core rebalancing logic
+export { Rebalancer } from './core/Rebalancer.js';
+export { WithInflightGuard } from './core/WithInflightGuard.js';
+export { WithSemaphore } from './core/WithSemaphore.js';
+
+// Configuration
+export { RebalancerConfig } from './config/RebalancerConfig.js';
+
+// Strategy
+export { BaseStrategy } from './strategy/BaseStrategy.js';
+export { WeightedStrategy } from './strategy/WeightedStrategy.js';
+export { MinAmountStrategy } from './strategy/MinAmountStrategy.js';
+export { StrategyFactory } from './strategy/StrategyFactory.js';
+
+// Monitor
+export { Monitor } from './monitor/Monitor.js';
+
+// Metrics
+export { Metrics } from './metrics/Metrics.js';
+export { PriceGetter } from './metrics/PriceGetter.js';
+
+// Interfaces
+export type {
+  IRebalancer,
+  PreparedTransaction,
+} from './interfaces/IRebalancer.js';
+export type {
+  IStrategy,
+  RebalancingRoute,
+  RawBalances,
+} from './interfaces/IStrategy.js';
+export type { IMonitor } from './interfaces/IMonitor.js';
+export {
+  MonitorEventType,
+  MonitorEvent,
+  MonitorPollingError,
+  MonitorStartError,
+} from './interfaces/IMonitor.js';
+export type { IMetrics } from './interfaces/IMetrics.js';
+
+// Utils
+export { getBridgeConfig } from './utils/bridgeUtils.js';
+export type {
+  BridgeConfigWithOverride,
+  BridgeConfig,
+} from './utils/bridgeUtils.js';
+export { getRawBalances } from './utils/balanceUtils.js';
+export { isCollateralizedTokenEligibleForRebalancing } from './utils/tokenUtils.js';
+export { ExplorerClient } from './utils/ExplorerClient.js';
+
+// Factory
+export { RebalancerContextFactory } from './factories/RebalancerContextFactory.js';

package/src/interfaces/IMetrics.ts

@@ -0,0 +1,5 @@
+import { MonitorEvent } from './IMonitor.js';
+
+export interface IMetrics {
+  processToken(tokenInfo: MonitorEvent['tokensInfo'][number]): Promise<void>;
+}

package/src/interfaces/IMonitor.ts

@@ -0,0 +1,63 @@
+import { Token } from '@hyperlane-xyz/sdk';
+
+import { WrappedError } from '../utils/errors.js';
+
+export class MonitorStartError extends WrappedError {
+  name = 'MonitorStartError';
+}
+
+export class MonitorPollingError extends WrappedError {
+  name = 'MonitorPollingError';
+}
+
+export enum MonitorEventType {
+  TokenInfo = 'TokenInfo',
+  Error = 'Error',
+  Start = 'Start',
+}
+
+/**
+ * Represents an event emitted by the monitor containing bridgedSupply and token information.
+ */
+export type MonitorEvent = {
+  /**
+   * Collection of objects containing the information retrieved by the Monitor.
+   */
+  tokensInfo: {
+    token: Token;
+    bridgedSupply?: bigint;
+  }[];
+};
+
+/**
+ * Interface for a monitoring service that tracks token information across different chains.
+ */
+export interface IMonitor {
+  /**
+   * Allows subscribers to listen to hyperlane's tokens info.
+   */
+  on(
+    eventName: MonitorEventType.TokenInfo,
+    fn: (event: MonitorEvent) => void,
+  ): this;
+
+  /**
+   * Allows subscribers to listen to error events.
+   */
+  on(eventName: MonitorEventType.Error, fn: (event: Error) => void): this;
+
+  /**
+   * Allows subscribers to listen to start events.
+   */
+  on(eventName: MonitorEventType.Start, fn: () => void): this;
+
+  /**
+   * Starts the monitoring long-running process.
+   */
+  start(): Promise<void>;
+
+  /**
+   * Stops the monitoring long-running process.
+   */
+  stop(): void;
+}

package/src/interfaces/IRebalancer.ts

@@ -0,0 +1,20 @@
+import { EvmMovableCollateralAdapter, TokenAmount } from '@hyperlane-xyz/sdk';
+
+import { RebalancingRoute } from './IStrategy.js';
+
+export type PreparedTransaction = {
+  populatedTx: Awaited<
+    ReturnType<EvmMovableCollateralAdapter['populateRebalanceTx']>
+  >;
+  route: RebalancingRoute;
+  originTokenAmount: TokenAmount;
+};
+
+export type RebalanceMetrics = {
+  route: RebalancingRoute;
+  originTokenAmount: TokenAmount;
+};
+
+export interface IRebalancer {
+  rebalance(routes: RebalancingRoute[]): Promise<void>;
+}

package/src/interfaces/IStrategy.ts

@@ -0,0 +1,13 @@
+import { ChainMap, ChainName } from '@hyperlane-xyz/sdk';
+
+export type RawBalances = ChainMap<bigint>;
+
+export type RebalancingRoute = {
+  origin: ChainName;
+  destination: ChainName;
+  amount: bigint;
+};
+
+export interface IStrategy {
+  getRebalancingRoutes(rawBalances: RawBalances): RebalancingRoute[];
+}