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

package/src/core/RebalancerService.ts

@@ -0,0 +1,333 @@
+import { Logger } from 'pino';
+
+import { IRegistry } from '@hyperlane-xyz/registry';
+import {
+  type MultiProtocolProvider,
+  type MultiProvider,
+  Token,
+} from '@hyperlane-xyz/sdk';
+import { assert, toWei } from '@hyperlane-xyz/utils';
+
+import { RebalancerConfig } from '../config/RebalancerConfig.js';
+import { RebalancerContextFactory } from '../factories/RebalancerContextFactory.js';
+import {
+  MonitorEvent,
+  MonitorEventType,
+  MonitorPollingError,
+  MonitorStartError,
+} from '../interfaces/IMonitor.js';
+import type { IRebalancer } from '../interfaces/IRebalancer.js';
+import type { IStrategy } from '../interfaces/IStrategy.js';
+import { Metrics } from '../metrics/Metrics.js';
+import { Monitor } from '../monitor/Monitor.js';
+import { getRawBalances } from '../utils/balanceUtils.js';
+
+export interface RebalancerServiceConfig {
+  /** Execution mode: 'manual' for one-off execution, 'daemon' for continuous monitoring */
+  mode: 'manual' | 'daemon';
+
+  /** Frequency to check balances in milliseconds (daemon mode only) */
+  checkFrequency?: number;
+
+  /** Enable monitor-only mode (no transactions executed) */
+  monitorOnly?: boolean;
+
+  /** Enable Prometheus metrics collection */
+  withMetrics?: boolean;
+
+  /** CoinGecko API key for token price fetching (required for metrics) */
+  coingeckoApiKey?: string;
+
+  /** Logger instance */
+  logger: Logger;
+
+  /** Service version for logging */
+  version?: string;
+}
+
+export interface ManualRebalanceRequest {
+  origin: string;
+  destination: string;
+  amount: string;
+}
+
+/**
+ * RebalancerService is the main orchestrator for the Hyperlane Warp Route Rebalancer.
+ * It supports both manual one-off rebalances and continuous daemon mode.
+ *
+ * @example Manual execution
+ * ```typescript
+ * const service = new RebalancerService(
+ *   multiProvider,
+ *   multiProtocolProvider,
+ *   registry,
+ *   rebalancerConfig,
+ *   {
+ *     mode: 'manual',
+ *     logger: console,
+ *   }
+ * );
+ * await service.executeManual({
+ *   origin: 'ethereum',
+ *   destination: 'arbitrum',
+ *   amount: '1000',
+ * });
+ * ```
+ *
+ * @example Daemon mode
+ * ```typescript
+ * const service = new RebalancerService(
+ *   multiProvider,
+ *   multiProtocolProvider,
+ *   registry,
+ *   rebalancerConfig,
+ *   {
+ *     mode: 'daemon',
+ *     checkFrequency: 60_000,
+ *     withMetrics: true,
+ *     coingeckoApiKey: process.env.COINGECKO_API_KEY,
+ *     logger: console,
+ *   }
+ * );
+ * await service.start();
+ * ```
+ */
+export class RebalancerService {
+  private isExiting = false;
+  private logger: Logger;
+  private contextFactory?: RebalancerContextFactory;
+  private monitor?: Monitor;
+  private strategy?: IStrategy;
+  private rebalancer?: IRebalancer;
+  private metrics?: Metrics;
+  private mode: 'manual' | 'daemon';
+
+  constructor(
+    private readonly multiProvider: MultiProvider,
+    private readonly multiProtocolProvider: MultiProtocolProvider | undefined,
+    private readonly registry: IRegistry,
+    private readonly rebalancerConfig: RebalancerConfig,
+    private readonly config: RebalancerServiceConfig,
+  ) {
+    this.logger = config.logger;
+    this.mode = config.mode;
+  }
+
+  /**
+   * Initialize the service components
+   */
+  private async initialize(): Promise<void> {
+    if (this.contextFactory) {
+      // Already initialized
+      return;
+    }
+
+    this.logger.info('Initializing RebalancerService...');
+
+    // Create context factory
+    this.contextFactory = await RebalancerContextFactory.create(
+      this.rebalancerConfig,
+      this.multiProvider,
+      this.multiProtocolProvider,
+      this.registry,
+      this.logger,
+    );
+
+    // Create monitor (always needed for daemon mode)
+    if (this.mode === 'daemon') {
+      const checkFrequency = this.config.checkFrequency ?? 60_000;
+      this.monitor = this.contextFactory.createMonitor(checkFrequency);
+    }
+
+    // Create metrics if enabled
+    if (this.config.withMetrics) {
+      this.metrics = await this.contextFactory.createMetrics(
+        this.config.coingeckoApiKey,
+      );
+      this.logger.info('Metrics collection enabled');
+    }
+
+    // Create strategy
+    this.strategy = await this.contextFactory.createStrategy(this.metrics);
+
+    // Create rebalancer (unless in monitor-only mode)
+    if (!this.config.monitorOnly) {
+      this.rebalancer = this.contextFactory.createRebalancer(this.metrics);
+    } else {
+      this.logger.warn(
+        'Running in monitorOnly mode: no transactions will be executed.',
+      );
+    }
+
+    this.logger.info('✅ RebalancerService initialized successfully');
+  }
+
+  /**
+   * Execute a manual one-off rebalance
+   */
+  async executeManual(request: ManualRebalanceRequest): Promise<void> {
+    await this.initialize();
+
+    assert(
+      this.rebalancer,
+      'Rebalancer not available. MonitorOnly mode cannot execute manual rebalances.',
+    );
+
+    const { origin, destination, amount } = request;
+
+    this.logger.info(
+      `Manual rebalance strategy selected. Origin: ${origin}, Destination: ${destination}, Amount: ${amount}`,
+    );
+
+    const warpCore = this.contextFactory!.getWarpCore();
+    const originToken = warpCore.tokens.find(
+      (t: Token) => t.chainName === origin,
+    );
+
+    if (!originToken) {
+      const error = `Origin token not found for chain ${origin}`;
+      this.logger.error(error);
+      throw new Error(error);
+    }
+
+    // Validate amount
+    const amountNum = Number(amount);
+    assert(!isNaN(amountNum), 'Amount must be a valid number');
+    assert(amountNum > 0, 'Amount must be greater than 0');
+
+    try {
+      await this.rebalancer.rebalance([
+        {
+          origin,
+          destination,
+          amount: BigInt(toWei(amount, originToken.decimals)),
+        },
+      ]);
+      this.logger.info(
+        `✅ Manual rebalance from ${origin} to ${destination} for amount ${amount} submitted successfully.`,
+      );
+    } catch (error) {
+      this.logger.error(
+        { error },
+        `❌ Manual rebalance from ${origin} to ${destination} failed`,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Start the rebalancer in daemon mode (continuous monitoring)
+   */
+  async start(): Promise<void> {
+    if (this.mode !== 'daemon') {
+      throw new Error('start() can only be called in daemon mode');
+    }
+
+    await this.initialize();
+
+    assert(this.monitor, 'Monitor must be initialized for daemon mode');
+
+    // Setup monitor event listeners
+    this.monitor
+      .on(MonitorEventType.TokenInfo, this.onTokenInfo.bind(this))
+      .on(MonitorEventType.Error, this.onMonitorError.bind(this))
+      .on(MonitorEventType.Start, this.onMonitorStart.bind(this));
+
+    // Set up signal handlers for graceful shutdown
+    process.on('SIGINT', () => this.gracefulShutdown());
+    process.on('SIGTERM', () => this.gracefulShutdown());
+
+    try {
+      await this.monitor.start();
+    } catch (error) {
+      this.logger.error({ error }, 'Rebalancer startup error');
+      throw error;
+    }
+  }
+
+  /**
+   * Stop the rebalancer daemon
+   */
+  async stop(): Promise<void> {
+    if (this.monitor) {
+      await this.monitor.stop();
+    }
+  }
+
+  /**
+   * Gracefully shutdown the service
+   */
+  async gracefulShutdown(): Promise<void> {
+    if (this.isExiting) {
+      return;
+    }
+    this.isExiting = true;
+
+    this.logger.info('Gracefully shutting down rebalancer...');
+    await this.stop();
+
+    // Unregister listeners to prevent them from being called again during shutdown
+    process.removeAllListeners('SIGINT');
+    process.removeAllListeners('SIGTERM');
+
+    this.logger.info('Rebalancer shutdown complete');
+    process.exit(0);
+  }
+
+  /**
+   * Event handler for token info updates from monitor
+   */
+  private async onTokenInfo(event: MonitorEvent): Promise<void> {
+    if (this.metrics) {
+      await Promise.all(
+        event.tokensInfo.map((tokenInfo) =>
+          this.metrics!.processToken(tokenInfo),
+        ),
+      );
+    }
+
+    const rawBalances = getRawBalances(
+      Object.keys(this.rebalancerConfig.strategyConfig.chains),
+      event,
+      this.logger,
+    );
+
+    const rebalancingRoutes = this.strategy!.getRebalancingRoutes(rawBalances);
+
+    this.rebalancer
+      ?.rebalance(rebalancingRoutes)
+      .then(() => {
+        this.metrics?.recordRebalancerSuccess();
+        this.logger.info('Rebalancer completed a cycle successfully');
+      })
+      .catch((error: any) => {
+        this.metrics?.recordRebalancerFailure();
+        this.logger.error({ error }, 'Error while rebalancing');
+      });
+  }
+
+  /**
+   * Event handler for monitor errors
+   */
+  private onMonitorError(error: Error): void {
+    if (error instanceof MonitorPollingError) {
+      this.logger.error(error.message);
+      this.metrics?.recordPollingError();
+    } else if (error instanceof MonitorStartError) {
+      this.logger.error(error.message);
+      throw error;
+    } else {
+      this.logger.error(
+        { error },
+        'An unexpected error occurred in the monitor',
+      );
+    }
+  }
+
+  /**
+   * Event handler for monitor start
+   */
+  private onMonitorStart(): void {
+    this.logger.info('Rebalancer started successfully 🚀');
+  }
+}

package/src/core/WithInflightGuard.test.ts

@@ -0,0 +1,131 @@
+import chai, { expect } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+import { ethers } from 'ethers';
+import { pino } from 'pino';
+import Sinon from 'sinon';
+
+import { chainMetadata } from '@hyperlane-xyz/registry';
+import { ChainMetadataManager } from '@hyperlane-xyz/sdk';
+
+import { RebalancingRoute } from '../interfaces/IStrategy.js';
+import { MockRebalancer, buildTestConfig } from '../test/helpers.js';
+import { ExplorerClient } from '../utils/ExplorerClient.js';
+
+import { WithInflightGuard } from './WithInflightGuard.js';
+
+chai.use(chaiAsPromised);
+
+const testLogger = pino({ level: 'silent' });
+
+describe('WithInflightGuard', () => {
+  it('forwards empty routes without calling Explorer', async () => {
+    const config = buildTestConfig();
+
+    const rebalancer = new MockRebalancer();
+    const rebalanceSpy = Sinon.spy(rebalancer, 'rebalance');
+
+    const explorer = new ExplorerClient('http://localhost');
+    const explorerSpy = Sinon.stub(explorer, 'hasUndeliveredRebalance');
+
+    const guard = new WithInflightGuard(
+      config,
+      rebalancer,
+      explorer,
+      ethers.Wallet.createRandom().address,
+      new ChainMetadataManager(chainMetadata as any),
+      testLogger,
+    );
+
+    await guard.rebalance([]);
+
+    expect(explorerSpy.called).to.be.false;
+    expect(rebalanceSpy.calledOnce).to.be.true;
+    expect(rebalanceSpy.calledWith([])).to.be.true;
+  });
+
+  it('calls underlying rebalancer when no inflight is detected', async () => {
+    const config = buildTestConfig({}, ['ethereum', 'arbitrum']);
+    const routes: RebalancingRoute[] = [{ origin: 'ethereum' } as any];
+
+    const rebalancer = new MockRebalancer();
+    const rebalanceSpy = Sinon.spy(rebalancer, 'rebalance');
+
+    const explorer = new ExplorerClient('http://localhost');
+    const explorerSpy = Sinon.stub(
+      explorer,
+      'hasUndeliveredRebalance',
+    ).resolves(false);
+
+    const guard = new WithInflightGuard(
+      config,
+      rebalancer,
+      explorer,
+      ethers.Wallet.createRandom().address,
+      new ChainMetadataManager(chainMetadata as any),
+      testLogger,
+    );
+
+    await guard.rebalance(routes);
+
+    expect(explorerSpy.calledOnce).to.be.true;
+    expect(rebalanceSpy.calledOnce).to.be.true;
+    expect(rebalanceSpy.calledWith(routes)).to.be.true;
+  });
+
+  it('skips rebalancing when inflight is detected', async () => {
+    const config = buildTestConfig({}, ['ethereum', 'arbitrum']);
+    const routes: RebalancingRoute[] = [{ origin: 'ethereum' } as any];
+
+    const rebalancer = new MockRebalancer();
+    const rebalanceSpy = Sinon.spy(rebalancer, 'rebalance');
+
+    const explorer = new ExplorerClient('http://localhost');
+    const explorerSpy = Sinon.stub(
+      explorer,
+      'hasUndeliveredRebalance',
+    ).resolves(true);
+
+    const guard = new WithInflightGuard(
+      config,
+      rebalancer,
+      explorer,
+      ethers.Wallet.createRandom().address,
+      new ChainMetadataManager(chainMetadata as any),
+      testLogger,
+    );
+
+    await guard.rebalance(routes);
+
+    expect(explorerSpy.calledOnce).to.be.true;
+    expect(rebalanceSpy.called).to.be.false;
+  });
+
+  it('propagates explorer query error', async () => {
+    const config = buildTestConfig({}, ['ethereum', 'arbitrum']);
+    const routes: RebalancingRoute[] = [{ origin: 'ethereum' } as any];
+
+    const rebalancer = new MockRebalancer();
+    const rebalanceSpy = Sinon.spy(rebalancer, 'rebalance');
+
+    const explorer = new ExplorerClient('http://localhost');
+    const explorerSpy = Sinon.stub(explorer, 'hasUndeliveredRebalance').rejects(
+      new Error('Explorer HTTP 405'),
+    );
+
+    const guard = new WithInflightGuard(
+      config,
+      rebalancer,
+      explorer,
+      ethers.Wallet.createRandom().address,
+      new ChainMetadataManager(chainMetadata as any),
+      testLogger,
+    );
+
+    await expect(guard.rebalance(routes)).to.be.rejectedWith(
+      'Explorer HTTP 405',
+    );
+
+    expect(explorerSpy.calledOnce).to.be.true;
+    expect(rebalanceSpy.called).to.be.false;
+  });
+});

package/src/core/WithInflightGuard.ts

@@ -0,0 +1,67 @@
+import type { Logger } from 'pino';
+
+import { ChainMetadataManager } from '@hyperlane-xyz/sdk';
+
+import { RebalancerConfig } from '../config/RebalancerConfig.js';
+import type { IRebalancer } from '../interfaces/IRebalancer.js';
+import type { RebalancingRoute } from '../interfaces/IStrategy.js';
+import { ExplorerClient } from '../utils/ExplorerClient.js';
+
+/**
+ * Prevents rebalancing if there are inflight rebalances for the warp route.
+ */
+export class WithInflightGuard implements IRebalancer {
+  private readonly logger: Logger;
+
+  constructor(
+    private readonly config: RebalancerConfig,
+    private readonly rebalancer: IRebalancer,
+    private readonly explorer: ExplorerClient,
+    private readonly txSender: string,
+    private readonly chainManager: ChainMetadataManager,
+    logger: Logger,
+  ) {
+    this.logger = logger.child({ class: WithInflightGuard.name });
+  }
+
+  async rebalance(routes: RebalancingRoute[]): Promise<void> {
+    // Always enforce the inflight guard
+    if (routes.length === 0) {
+      return this.rebalancer.rebalance(routes);
+    }
+
+    const chains = Object.keys(this.config.strategyConfig.chains);
+    const bridges = chains.map(
+      (chain) => this.config.strategyConfig.chains[chain].bridge,
+    );
+    const domains = chains.map((chain) => this.chainManager.getDomainId(chain));
+
+    let hasInflightRebalances = false;
+    try {
+      hasInflightRebalances = await this.explorer.hasUndeliveredRebalance(
+        {
+          bridges,
+          domains: Array.from(new Set(domains)),
+          txSender: this.txSender,
+          limit: 5,
+        },
+        this.logger,
+      );
+    } catch (e: any) {
+      this.logger.error(
+        { status: e.status, body: e.body },
+        'Explorer inflight query failed',
+      );
+      throw e;
+    }
+
+    if (hasInflightRebalances) {
+      this.logger.info(
+        'Inflight rebalance detected via Explorer; skipping this cycle',
+      );
+      return;
+    }
+
+    return this.rebalancer.rebalance(routes);
+  }
+}

package/src/core/WithSemaphore.test.ts

@@ -0,0 +1,112 @@
+import chai, { expect } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+import { pino } from 'pino';
+import Sinon from 'sinon';
+
+import { RebalancerStrategyOptions } from '@hyperlane-xyz/sdk';
+
+import { RebalancingRoute } from '../interfaces/IStrategy.js';
+import { MockRebalancer, buildTestConfig } from '../test/helpers.js';
+
+import { WithSemaphore } from './WithSemaphore.js';
+
+chai.use(chaiAsPromised);
+
+const testLogger = pino({ level: 'silent' });
+
+describe('WithSemaphore', () => {
+  it('should call the underlying rebalancer', async () => {
+    const config = buildTestConfig();
+
+    const routes = [
+      {
+        origin: 'chain1',
+      } as any as RebalancingRoute,
+    ];
+
+    const rebalancer = new MockRebalancer();
+    const rebalanceSpy = Sinon.spy(rebalancer, 'rebalance');
+    const withSemaphore = new WithSemaphore(config, rebalancer, testLogger);
+    await withSemaphore.rebalance(routes);
+
+    expect(rebalanceSpy.calledOnce).to.be.true;
+    expect(rebalanceSpy.calledWith(routes)).to.be.true;
+  });
+
+  it('should return early if there are no routes', async () => {
+    const config = buildTestConfig();
+
+    const rebalancer = new MockRebalancer();
+    const rebalanceSpy = Sinon.spy(rebalancer, 'rebalance');
+    const withSemaphore = new WithSemaphore(config, rebalancer, testLogger);
+    await withSemaphore.rebalance([]);
+
+    expect(rebalanceSpy.calledOnce).to.be.false;
+  });
+
+  it('should return early if rebalance occurs before waitUntil is reached', async () => {
+    const config = buildTestConfig();
+
+    const routes = [
+      {
+        origin: 'chain1',
+      } as any as RebalancingRoute,
+    ];
+
+    const rebalancer = new MockRebalancer();
+    const rebalanceSpy = Sinon.spy(rebalancer, 'rebalance');
+    const withSemaphore = new WithSemaphore(config, rebalancer, testLogger);
+    await withSemaphore.rebalance(routes);
+
+    expect(rebalanceSpy.calledOnce).to.be.true;
+    expect(rebalanceSpy.calledWith(routes)).to.be.true;
+
+    rebalanceSpy.resetHistory();
+    await withSemaphore.rebalance(routes);
+
+    expect(rebalanceSpy.calledOnce).to.be.false;
+  });
+
+  it('should throw if a chain is missing', async () => {
+    const config = buildTestConfig({
+      strategyConfig: {
+        rebalanceStrategy: RebalancerStrategyOptions.Weighted,
+        chains: {},
+      },
+    });
+
+    const routes = [
+      {
+        origin: 'chain1',
+      } as any as RebalancingRoute,
+    ];
+
+    const rebalancer = new MockRebalancer();
+    const withSemaphore = new WithSemaphore(config, rebalancer, testLogger);
+
+    await expect(withSemaphore.rebalance(routes)).to.be.rejectedWith(
+      `Chain ${routes[0].origin} not found in config`,
+    );
+  });
+
+  it('should not execute if another rebalance is currently executing', async () => {
+    const config = buildTestConfig();
+
+    const routes = [
+      {
+        origin: 'chain1',
+      } as any as RebalancingRoute,
+    ];
+
+    const rebalancer = new MockRebalancer();
+    const rebalanceSpy = Sinon.spy(rebalancer, 'rebalance');
+    const withSemaphore = new WithSemaphore(config, rebalancer, testLogger);
+
+    const rebalancePromise1 = withSemaphore.rebalance(routes);
+    const rebalancePromise2 = withSemaphore.rebalance(routes);
+    await rebalancePromise1;
+    await rebalancePromise2;
+
+    expect(rebalanceSpy.calledOnce).to.be.true;
+  });
+});