@humanode-hyperlane/rebalancer 0.0.0-stage → 27.2.2-humanode.1

package/src/core/RebalancerService.ts

@@ -0,0 +1,412 @@
+import { Logger } from 'pino';
+
+import { IRegistry } from '@humanode-hyperlane/registry';
+import {
+  type MultiProtocolProvider,
+  type MultiProvider,
+  Token,
+} from '@humanode-hyperlane/sdk';
+import { ProtocolType, assert, toWei } from '@humanode-hyperlane/utils';
+
+import { RebalancerConfig } from '../config/RebalancerConfig.js';
+import {
+  getStrategyChainConfig,
+  getStrategyChainNames,
+} from '../config/types.js';
+import { RebalancerContextFactory } from '../factories/RebalancerContextFactory.js';
+import type { ExternalBridgeRegistry } from '../interfaces/IExternalBridge.js';
+import {
+  MonitorEvent,
+  MonitorEventType,
+  MonitorPollingError,
+  MonitorStartError,
+} from '../interfaces/IMonitor.js';
+import type { IRebalancer } from '../interfaces/IRebalancer.js';
+import type {
+  IStrategy,
+  MovableCollateralRoute,
+} from '../interfaces/IStrategy.js';
+import { Metrics } from '../metrics/Metrics.js';
+import { type InventoryMonitorConfig, Monitor } from '../monitor/Monitor.js';
+import type { IActionTracker } from '../tracking/IActionTracker.js';
+import { InflightContextAdapter } from '../tracking/InflightContextAdapter.js';
+
+import type { RebalancerOrchestrator } from './RebalancerOrchestrator.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;
+
+  /**
+   * Optional pre-configured ActionTracker.
+   * If provided, skips ActionTracker creation and uses this directly.
+   * Useful for simulation/testing where tracking is mocked externally.
+   */
+  actionTracker?: IActionTracker;
+}
+
+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';
+  private actionTracker?: IActionTracker;
+  private inflightContextAdapter?: InflightContextAdapter;
+  private orchestrator?: RebalancerOrchestrator;
+  constructor(
+    private readonly multiProvider: MultiProvider,
+    private readonly multiProtocolProvider: MultiProtocolProvider | undefined,
+    private readonly registry: IRegistry,
+    private readonly rebalancerConfig: RebalancerConfig,
+    private readonly config: RebalancerServiceConfig,
+    private readonly inventorySignerKeysByProtocol?: Partial<
+      Record<ProtocolType, string>
+    >,
+  ) {
+    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,
+      this.inventorySignerKeysByProtocol,
+    );
+
+    // 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 or use provided ActionTracker for tracking inflight actions
+    // Must be created BEFORE rebalancer since rebalancer needs it
+    if (this.config.actionTracker) {
+      // Use externally provided ActionTracker (e.g., for simulation/testing)
+      this.actionTracker = this.config.actionTracker;
+      this.inflightContextAdapter = new InflightContextAdapter(
+        this.actionTracker,
+        this.multiProvider,
+      );
+      await this.actionTracker.initialize();
+      this.logger.info('Using externally provided ActionTracker');
+    } else {
+      const { tracker, adapter } =
+        await this.contextFactory.createActionTracker();
+      this.actionTracker = tracker;
+      this.inflightContextAdapter = adapter;
+      await this.actionTracker.initialize();
+      this.logger.info('ActionTracker initialized');
+    }
+
+    // Create rebalancers (both movableCollateral and inventory if configured)
+    let rebalancers: IRebalancer[] = [];
+    let externalBridgeRegistry: Partial<ExternalBridgeRegistry> = {};
+    let inventoryConfig: InventoryMonitorConfig | undefined;
+
+    if (!this.config.monitorOnly) {
+      const result = await this.contextFactory.createRebalancers(
+        this.actionTracker,
+        this.metrics,
+      );
+      rebalancers = result.rebalancers;
+      externalBridgeRegistry = result.externalBridgeRegistry;
+      inventoryConfig = result.inventoryConfig;
+
+      if (rebalancers.length > 0) {
+        this.logger.info(`${rebalancers.length} rebalancer(s) created`);
+      }
+    } else {
+      this.logger.warn(
+        'Running in monitorOnly mode: no transactions will be executed.',
+      );
+    }
+
+    // Set instance variable for backward compatibility with executeManual
+    // (Task 5 will remove this when refactoring executeManual)
+    if (rebalancers.length > 0) {
+      this.rebalancer = rebalancers[0];
+    }
+
+    if (this.mode === 'daemon') {
+      const checkFrequency = this.config.checkFrequency ?? 60_000;
+      this.monitor = this.contextFactory.createMonitor(
+        checkFrequency,
+        inventoryConfig,
+      );
+    }
+
+    this.orchestrator = this.contextFactory.createOrchestrator({
+      strategy: this.strategy,
+      actionTracker: this.actionTracker,
+      inflightContextAdapter: this.inflightContextAdapter,
+      rebalancers,
+      externalBridgeRegistry: externalBridgeRegistry,
+      metrics: this.metrics,
+    });
+
+    this.logger.info(
+      {
+        warpRouteId: this.rebalancerConfig.warpRouteId,
+        strategyTypes: this.rebalancerConfig.strategyConfig.map(
+          (s) => s.rebalanceStrategy,
+        ),
+        chains: getStrategyChainNames(this.rebalancerConfig.strategyConfig),
+      },
+      'RebalancerService initialized',
+    );
+  }
+
+  /**
+   * 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');
+
+    const originConfig = getStrategyChainConfig(
+      this.rebalancerConfig.strategyConfig,
+      origin,
+    );
+    assert(
+      originConfig?.bridge,
+      `No bridge configured for origin chain ${origin}`,
+    );
+
+    // Use destination-specific bridge override if configured, otherwise use default
+    const bridge =
+      originConfig.override?.[destination]?.bridge ?? originConfig.bridge;
+
+    try {
+      const manualRoute: MovableCollateralRoute & { intentId: string } = {
+        origin,
+        destination,
+        amount: BigInt(toWei(amount, originToken.decimals)),
+        executionType: 'movableCollateral',
+        bridge,
+        intentId: `manual-${Date.now()}`,
+      };
+      await this.rebalancer.rebalance([manualRoute]);
+      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);
+  }
+
+  /**
+   * Handle token info events from monitor by delegating to orchestrator
+   */
+  private async onTokenInfo(event: MonitorEvent): Promise<void> {
+    if (!this.orchestrator) {
+      this.logger.error('Orchestrator not initialized');
+      return;
+    }
+
+    await this.orchestrator.executeCycle(event);
+  }
+
+  /**
+   * 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/e2e/E2E_TEST_CONVENTIONS.md

@@ -0,0 +1,222 @@
+# E2E Test Conventions
+
+Guidelines for writing and updating rebalancer e2e tests.
+
+## 1. Assert total action counts at each stage
+
+Don't just filter for the action type you care about. Assert the total count first, then find/filter within it. This catches unexpected extra actions.
+
+```ts
+// Good
+const actionsAfterBridge = await context.tracker.getActionsForIntent(intent.id);
+expect(actionsAfterBridge.length).to.equal(2); // 1 deposit + 1 movement
+const movementAction = actionsAfterBridge.find(
+  (a) => a.type === 'inventory_movement',
+);
+
+// Bad — doesn't catch unexpected extra actions
+const movementActions = actionsAfterBridge.filter(
+  (a) => a.type === 'inventory_movement' && a.status === 'complete',
+);
+expect(movementActions.length).to.equal(1);
+```
+
+## 2. Use `find` + `expect(x).to.exist` for single items
+
+When you expect exactly one action of a type, use `find` instead of `filter` + length check. It reads as "there should be one of these" and gives you a non-null reference.
+
+```ts
+// Good
+const movementAction = actionsAfterBridge.find(
+  (a) => a.type === 'inventory_movement',
+);
+expect(movementAction).to.exist;
+expect(movementAction!.origin).to.equal(DOMAIN_IDS.anvil1);
+
+// Bad — extra ceremony for the same thing
+const completedMovementActions = actionsAfterBridge.filter(
+  (a) => a.type === 'inventory_movement' && a.status === 'complete',
+);
+expect(completedMovementActions.length).to.equal(1);
+expect(completedMovementActions[0].origin).to.equal(DOMAIN_IDS.anvil1);
+```
+
+## 3. Don't over-filter — let aggregate assertions catch problems
+
+Don't add `status === 'complete'` to filter predicates when a downstream assertion (like summing amounts) will fail anyway if an action is in the wrong state. Over-filtering hides bugs.
+
+```ts
+// Good — if a deposit is incomplete, totalDeposited won't match
+const allDeposits = finalActions.filter((a) => a.type === 'inventory_deposit');
+expect(allDeposits.length).to.equal(2);
+const totalDeposited = allDeposits.reduce((sum, a) => sum + a.amount, 0n);
+expect(totalDeposited).to.equal(activeIntent.amount);
+
+// Bad — status filter masks a deposit stuck in 'in_progress'
+const allDeposits = finalActions.filter(
+  (a) => a.type === 'inventory_deposit' && a.status === 'complete',
+);
+expect(allDeposits.length).to.equal(2);
+```
+
+Exception: filter by status when you're specifically testing state transitions (e.g. "after relay, this action should be complete").
+
+## 4. Use `getRouterBalances` helper for balance snapshots
+
+Every test that asserts router balance changes repeats the same loop. Extract it into a shared helper and call it before/after the operation under test.
+
+```ts
+// In test helpers
+async function getRouterBalances(
+  localProviders: Map<string, providers.JsonRpcProvider>,
+  addresses: NativeDeployedAddresses,
+): Promise<Record<string, BigNumber>> {
+  const balances: Record<string, BigNumber> = {};
+  for (const chain of TEST_CHAINS) {
+    const provider = localProviders.get(chain)!;
+    balances[chain] = await provider.getBalance(
+      addresses.monitoredRoute[chain],
+    );
+  }
+  return balances;
+}
+
+// In tests
+const before = await getRouterBalances(localProviders, nativeDeployedAddresses);
+// ... execute cycle, relay, etc.
+const after = await getRouterBalances(localProviders, nativeDeployedAddresses);
+```
+
+## 5. Use `classifyChains` helper for surplus/deficit/neutral
+
+Tests frequently need to identify which chain is the deficit (destination), which funded the transfer (surplus), and which was uninvolved (neutral). Extract this into a helper that derives the classification from a single deposit action rather than hardcoding chain names.
+
+```ts
+interface ChainRoles {
+  deficitChain: string;
+  surplusChain: string;
+  neutralChain?: string;
+}
+
+function classifyChains(
+  deficitChain: string,
+  depositAction: RebalanceAction,
+): ChainRoles {
+  // Surplus chain is where the router pays out on message delivery.
+  // For inventory deposits, that's the action's destination (swapped direction).
+  const surplusChain = chainFromDomain(depositAction.destination);
+  const neutralChain = TEST_CHAINS.find(
+    (c) => c !== deficitChain && c !== surplusChain,
+  );
+  return { deficitChain, surplusChain, neutralChain };
+}
+
+// In tests
+const { surplusChain, neutralChain } = classifyChains('anvil2', depositAction);
+
+expect(after.anvil2.gt(before.anvil2)).to.be.true;
+expect(after[surplusChain].lt(before[surplusChain])).to.be.true;
+if (neutralChain) {
+  expect(after[neutralChain].eq(before[neutralChain])).to.be.true;
+}
+```
+
+## 6. Use `withInventorySignerBalances` for signer wallet setup
+
+Don't call `anvil_setBalance` on the inventory signer directly in tests. Use the builder's `withInventorySignerBalances` method with a preset name or inline config.
+
+```ts
+// Good — preset name from INVENTORY_SIGNER_PRESETS in routes.ts
+const context = await new TestRebalancerBuilder(deploymentManager, multiProvider)
+  .withStrategy(buildInventoryMinAmountStrategyConfig(addresses))
+  .withInventoryConfig({ inventorySignerKey: ANVIL_USER_PRIVATE_KEY, nativeDeployedAddresses })
+  .withInventorySignerBalances('SIGNER_PARTIAL_ANVIL2')
+  .withExecutionMode('execute')
+  .build();
+
+// Also accepted — inline Record<string, BigNumber> for one-off scenarios
+.withInventorySignerBalances({ anvil2: BigNumber.from('500000000000000000') })
+
+// Bad — setting balances outside the builder
+const signer = new ethers.Wallet(ANVIL_USER_PRIVATE_KEY);
+await provider.send('anvil_setBalance', [signer.address, '0x...']);
+```
+
+Available presets: `SIGNER_PARTIAL_ANVIL2`, `SIGNER_LOW_ALL`, `SIGNER_ONLY_ANVIL1`, `SIGNER_SPLIT_SOURCES`, `SIGNER_FUNDED_ANVIL1`, `SIGNER_PARTIAL_ANVIL3`, `SIGNER_ZERO_ANVIL3`, `SIGNER_WEIGHTED_LOW_ALL`, `SIGNER_WEIGHTED_BRIDGE_SOURCES`.
+
+## 7. Use named constants for strategy-derived values
+
+Don't hardcode magic numbers like `2000000000000000000n`. Derive expected values from the strategy config constants exported in `routes.ts`.
+
+```ts
+// Good — derived from strategy config
+import { INVENTORY_MIN_AMOUNT_TARGET_WEI } from './fixtures/routes.js';
+const expectedDeficit = INVENTORY_MIN_AMOUNT_TARGET_WEI.toBigInt();
+expect(activeIntent.amount).to.equal(expectedDeficit);
+
+// Bad — hardcoded magic number
+expect(activeIntent.amount).to.equal(2000000000000000000n);
+```
+
+Available constants: `INVENTORY_MIN_AMOUNT_MIN` (`'1'`), `INVENTORY_MIN_AMOUNT_TARGET` (`'2'`), `INVENTORY_MIN_AMOUNT_TARGET_WEI` (target as wei BigNumber).
+
+## 8. Use balance presets for router balances
+
+Don't inline `BigNumber.from(...)` objects in `.withBalances()` when a preset in `BALANCE_PRESETS` matches your scenario. Add a new preset if the scenario is reusable.
+
+```ts
+// Good — named preset
+.withBalances('INVENTORY_EMPTY_DEST')
+.withBalances('INVENTORY_MULTI_DEFICIT')
+
+// Acceptable — inline for truly one-off scenarios
+.withBalances({
+  anvil1: BigNumber.from('9000000000000000000'),
+  anvil2: BigNumber.from(0),
+  anvil3: BigNumber.from(0),
+})
+
+// Bad — duplicating values that already exist as a preset
+.withBalances({
+  anvil1: BigNumber.from('5000000000000000000'),
+  anvil2: BigNumber.from('0'),
+  anvil3: BigNumber.from('5000000000000000000'),
+})
+// ^ This is INVENTORY_EMPTY_DEST — use the preset.
+```
+
+These helpers and conventions eliminate repeated boilerplate across tests and make intent immediately clear.
+
+## 9. Assert state after each cycle — no loop-to-completion
+
+Multi-cycle tests must check state after **every** cycle. Looping with `for (let i = 0; i < N; i++)` until completion is an antipattern — it hides the per-cycle progression and makes failures impossible to diagnose.
+
+```ts
+// Good — explicit per-cycle assertions
+await executeCycle(context);
+await syncAndRelay(context);
+// Check cycle 1 state
+expect(partialIntents[0].completedAmount > 0n).to.be.true;
+expect(actions.length).to.equal(2);
+
+await executeCycle(context);
+await syncAndRelay(context);
+// Check cycle 2 state
+expect(partialIntents[0].completedAmount > c1Amount).to.be.true;
+expect(actions.length).to.equal(3);
+
+// ... continue until completion
+
+// Bad — loop hides what happens per cycle
+for (let i = 0; i < 5; i++) {
+  await executeCycle(context);
+  await syncAndRelay(context);
+}
+expect(finalIntent.status).to.equal('complete');
+```
+
+Each cycle should assert:
+
+- Active/partial intent state (count, completedAmount, remaining)
+- Action counts by type (deposits, movements)
+- Monotonic progress (completedAmount increasing across cycles)