@humanode-hyperlane/rebalancer 0.0.0-stage → 27.2.2

package/src/monitor/Monitor.ts

@@ -0,0 +1,324 @@
+import { type Logger } from 'pino';
+
+import {
+  type ChainMap,
+  type ChainName,
+  type Token,
+  type WarpCore,
+} from '@humanode-hyperlane/sdk';
+import { Address, ProtocolType, sleep } from '@humanode-hyperlane/utils';
+
+import {
+  type ConfirmedBlockTag,
+  type ConfirmedBlockTags,
+  type IMonitor,
+  type MonitorEvent,
+  MonitorEventType,
+  MonitorPollingError,
+  MonitorStartError,
+} from '../interfaces/IMonitor.js';
+import { getConfirmedBlockTag } from '../utils/blockTag.js';
+
+/**
+ * Configuration for the Monitor's inventory tracking.
+ */
+export interface InventoryMonitorConfig {
+  inventoryAddresses: Partial<Record<ProtocolType, Address>>;
+  chains: ChainName[];
+}
+
+/**
+ * Simple monitor implementation that polls warp route collateral balances and emits them as MonitorEvent.
+ * Awaits the TokenInfo handler before starting the next cycle to prevent race conditions.
+ */
+export class Monitor implements IMonitor {
+  private tokenInfoHandler?: (event: MonitorEvent) => void | Promise<void>;
+  private errorHandler?: (event: Error) => void;
+  private startHandler?: () => void;
+  private isMonitorRunning = false;
+  private resolveStop: (() => void) | null = null;
+  private stopPromise: Promise<void> | null = null;
+
+  /**
+   * @param checkFrequency - The frequency to poll balances in ms.
+   */
+  constructor(
+    private readonly checkFrequency: number,
+    private readonly warpCore: WarpCore,
+    private readonly logger: Logger,
+    private readonly inventoryConfig?: InventoryMonitorConfig,
+  ) {}
+
+  private async computeConfirmedBlockTags(): Promise<ConfirmedBlockTags> {
+    const blockTags: ConfirmedBlockTags = {};
+    const chains = new Set(this.warpCore.tokens.map((t) => t.chainName));
+
+    for (const chain of chains) {
+      blockTags[chain] = await getConfirmedBlockTag(
+        this.warpCore.multiProvider,
+        chain,
+        this.logger,
+      );
+    }
+
+    return blockTags;
+  }
+
+  // overloads from IMonitor
+  on(
+    eventName: MonitorEventType.TokenInfo,
+    fn: (event: MonitorEvent) => void | Promise<void>,
+  ): this;
+  on(eventName: MonitorEventType.Error, fn: (event: Error) => void): this;
+  on(eventName: MonitorEventType.Start, fn: () => void): this;
+  on(eventName: string, fn: (...args: any[]) => void | Promise<void>): this {
+    switch (eventName) {
+      case MonitorEventType.TokenInfo:
+        this.tokenInfoHandler = fn as (
+          event: MonitorEvent,
+        ) => void | Promise<void>;
+        break;
+      case MonitorEventType.Error:
+        this.errorHandler = fn as (event: Error) => void;
+        break;
+      case MonitorEventType.Start:
+        this.startHandler = fn as () => void;
+        break;
+    }
+    return this;
+  }
+
+  async start() {
+    if (this.isMonitorRunning) {
+      // Cannot start the same monitor multiple times
+      this.errorHandler?.(new MonitorStartError('Monitor already running'));
+      return;
+    }
+
+    try {
+      this.isMonitorRunning = true;
+      this.logger.debug(
+        { checkFrequency: this.checkFrequency },
+        'Monitor started',
+      );
+      this.startHandler?.();
+
+      while (this.isMonitorRunning) {
+        const cycleStart = Date.now();
+
+        try {
+          this.logger.debug('Polling cycle started');
+
+          const confirmedBlockTags = await this.computeConfirmedBlockTags();
+
+          const event: MonitorEvent = {
+            tokensInfo: [],
+            confirmedBlockTags,
+          };
+
+          for (const token of this.warpCore.tokens) {
+            this.logger.debug(
+              {
+                chain: token.chainName,
+                tokenSymbol: token.symbol,
+                tokenAddress: token.addressOrDenom,
+              },
+              'Checking token',
+            );
+            const blockTag = confirmedBlockTags[token.chainName];
+            const bridgedSupply = await this.getTokenBridgedSupply(
+              token,
+              blockTag,
+            );
+
+            event.tokensInfo.push({
+              token,
+              bridgedSupply,
+            });
+          }
+
+          const inventoryBalances = await this.fetchInventoryBalances();
+          if (Object.keys(inventoryBalances).length > 0) {
+            event.inventoryBalances = inventoryBalances;
+            this.logger.info(
+              {
+                chainsMonitored: Object.keys(inventoryBalances).length,
+                balances: Object.entries(inventoryBalances).map(
+                  ([chain, balance]) => ({
+                    chain,
+                    balance: balance.toString(),
+                    balanceEth: (Number(balance) / 1e18).toFixed(6),
+                  }),
+                ),
+              },
+              'Inventory balances fetched',
+            );
+          }
+
+          if (this.tokenInfoHandler) {
+            await this.tokenInfoHandler(event);
+          }
+          this.logger.debug('Polling cycle completed');
+        } catch (error) {
+          this.errorHandler?.(
+            new MonitorPollingError(
+              `Error during monitor execution cycle: ${(error as Error).message}`,
+              error as Error,
+            ),
+          );
+        }
+
+        // Smart sleep: only wait for remaining time after cycle completes
+        const elapsed = Date.now() - cycleStart;
+        const remaining = this.checkFrequency - elapsed;
+        if (remaining > 0) {
+          await sleep(remaining);
+        }
+        // If elapsed >= checkFrequency, start next cycle immediately
+      }
+    } catch (error) {
+      this.errorHandler?.(
+        new MonitorStartError(
+          `Error starting monitor: ${(error as Error).message}`,
+          error as Error,
+        ),
+      );
+    }
+
+    // After the loop has been gracefully terminated, we can clean up.
+    this.tokenInfoHandler = undefined;
+    this.errorHandler = undefined;
+    this.startHandler = undefined;
+    this.logger.info('Monitor stopped');
+
+    // If stop() was called, resolve the promise to signal that we're done.
+    if (this.resolveStop) {
+      this.resolveStop();
+      this.resolveStop = null;
+      this.stopPromise = null;
+    }
+  }
+
+  private async getTokenBridgedSupply(
+    token: Token,
+    blockTag?: ConfirmedBlockTag,
+  ): Promise<bigint | undefined> {
+    if (!token.isHypToken()) {
+      this.logger.warn(
+        {
+          chain: token.chainName,
+          tokenSymbol: token.symbol,
+          tokenAddress: token.addressOrDenom,
+        },
+        'Cannot get bridged balance for a non-Hyperlane token',
+      );
+      return;
+    }
+
+    const adapter = token.getHypAdapter(this.warpCore.multiProvider);
+    let bridgedSupply: bigint | undefined;
+
+    try {
+      bridgedSupply = await adapter.getBridgedSupply({ blockTag });
+      this.logger.debug(
+        { chain: token.chainName, blockTag },
+        'Queried confirmed balance',
+      );
+    } catch (error) {
+      this.logger.warn(
+        {
+          chain: token.chainName,
+          blockTag,
+          error: (error as Error).message,
+        },
+        'Historical block query failed, falling back to latest',
+      );
+      bridgedSupply = await adapter.getBridgedSupply();
+    }
+
+    if (bridgedSupply === undefined) {
+      this.logger.warn(
+        {
+          chain: token.chainName,
+          tokenSymbol: token.symbol,
+          tokenAddress: token.addressOrDenom,
+        },
+        'Bridged supply not found for token',
+      );
+    }
+
+    return bridgedSupply;
+  }
+
+  private async fetchInventoryBalances(): Promise<ChainMap<bigint>> {
+    if (!this.inventoryConfig) return {};
+
+    const balances: ChainMap<bigint> = {};
+
+    const readPromises = this.inventoryConfig.chains.map(async (chainName) => {
+      const token = this.warpCore.tokens.find((t) => t.chainName === chainName);
+      if (!token) {
+        this.logger.warn(
+          { chain: chainName },
+          'No token found for inventory chain',
+        );
+        return { chainName, balance: 0n };
+      }
+
+      try {
+        const address =
+          this.inventoryConfig!.inventoryAddresses[token.protocol];
+        if (!address) {
+          this.logger.warn(
+            { chain: chainName, protocol: token.protocol },
+            'No inventory address for chain protocol, skipping',
+          );
+          return { chainName, balance: 0n };
+        }
+        const adapter = token.getAdapter(this.warpCore.multiProvider);
+        const balance = await adapter.getBalance(address);
+        this.logger.debug(
+          {
+            chain: chainName,
+            token: token.addressOrDenom,
+            balance: balance.toString(),
+          },
+          'Read inventory balance',
+        );
+        return { chainName, balance };
+      } catch (error) {
+        this.logger.error(
+          { chain: chainName, error: (error as Error).message },
+          'Failed to read inventory balance',
+        );
+        return { chainName, balance: 0n };
+      }
+    });
+
+    const results = await Promise.all(readPromises);
+
+    for (const { chainName, balance } of results) {
+      balances[chainName] = balance;
+    }
+
+    return balances;
+  }
+
+  stop(): Promise<void> {
+    if (!this.isMonitorRunning) return Promise.resolve();
+
+    // If stop is already in progress, return the existing promise
+    if (this.stopPromise) return this.stopPromise;
+
+    this.logger.info('Stopping monitor...');
+    // Signal the while loop to terminate after its current iteration
+    this.isMonitorRunning = false;
+
+    // Create a promise that will be resolved by the start() method
+    // once the loop and cleanup are complete.
+    this.stopPromise = new Promise((resolve) => {
+      this.resolveStop = resolve;
+    });
+    return this.stopPromise;
+  }
+}

package/src/service.ts

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/**
+ * Hyperlane Rebalancer Service Entry Point
+ *
+ * This is the main entry point for running the rebalancer as a standalone service
+ * in Kubernetes or other container environments. It reads configuration from
+ * environment variables and files, then starts the rebalancer in daemon mode.
+ *
+ * Environment Variables:
+ * - REBALANCER_CONFIG_FILE: Path to the rebalancer configuration YAML file (required)
+ * - HYP_REBALANCER_KEY: Private key for movable collateral rebalancing operations (preferred)
+ * - HYP_KEY: Fallback private key for HYP_REBALANCER_KEY (optional)
+ * - HYP_INVENTORY_KEY_<PROTOCOL>: Private key for inventory operations per protocol (e.g., HYP_INVENTORY_KEY_ETHEREUM, HYP_INVENTORY_KEY_SEALEVEL)
+ * - COINGECKO_API_KEY: API key for CoinGecko price fetching (optional, for metrics)
+ * - HYP_INVENTORY_KEY: Backward-compatible fallback for Ethereum inventory signer (optional, use HYP_INVENTORY_KEY_ETHEREUM preferentially)
+ * - CHECK_FREQUENCY: Balance check frequency in ms (default: 60000)
+ * - WITH_METRICS: Enable Prometheus metrics (default: "true")
+ * - MONITOR_ONLY: Run in monitor-only mode without executing transactions (default: "false")
+ * - LOG_LEVEL: Logging level (default: "info") - supported by pino
+ * - REGISTRY_URI: Registry URI for chain metadata. Can include /tree/{commit} to pin version (default: GitHub registry)
+ * - RPC_URL_<CHAIN>: Override RPC URL for a specific chain (e.g., RPC_URL_ETHEREUM, RPC_URL_ARBITRUM)
+ *
+ * Usage:
+ *   node dist/service.js
+ *   REBALANCER_CONFIG_FILE=/config/rebalancer.yaml HYP_REBALANCER_KEY=0x... HYP_INVENTORY_KEY=0x... node dist/service.js
+ */
+import { Wallet } from 'ethers';
+import { Keypair } from '@solana/web3.js';
+
+import { DEFAULT_GITHUB_REGISTRY } from '@humanode-hyperlane/registry';
+import { getRegistry } from '@humanode-hyperlane/registry/fs';
+import { MultiProvider } from '@humanode-hyperlane/sdk';
+import {
+  applyRpcUrlOverridesFromEnv,
+  createServiceLogger,
+  ProtocolType,
+  rootLogger,
+} from '@humanode-hyperlane/utils';
+
+import { RebalancerConfig } from './config/RebalancerConfig.js';
+import { RebalancerService } from './core/RebalancerService.js';
+import { parseSolanaPrivateKey } from './utils/solanaKeyParser.js';
+import type { InventorySignerConfig } from './core/InventoryRebalancer.js';
+
+async function main(): Promise<void> {
+  const VERSION = process.env.SERVICE_VERSION || 'dev';
+  // Validate required environment variables
+  const configFile = process.env.REBALANCER_CONFIG_FILE;
+  if (!configFile) {
+    rootLogger.error('REBALANCER_CONFIG_FILE environment variable is required');
+    process.exit(1);
+  }
+
+  const rebalancerPrivateKey =
+    process.env.HYP_REBALANCER_KEY ?? process.env.HYP_KEY;
+  if (!rebalancerPrivateKey) {
+    rootLogger.error(
+      'HYP_REBALANCER_KEY (or HYP_KEY) environment variable is required',
+    );
+    process.exit(1);
+  }
+
+  // Build per-protocol private key map from env vars.
+  // Naming: HYP_INVENTORY_KEY_<UPPERCASE_PROTOCOL> (e.g., HYP_INVENTORY_KEY_ETHEREUM).
+  // HYP_INVENTORY_KEY (no suffix) is kept as backward-compatible fallback for Ethereum only.
+  const inventoryPrivateKeys: Partial<Record<ProtocolType, string>> = {};
+  for (const protocol of Object.values(ProtocolType)) {
+    const envKey = `HYP_INVENTORY_KEY_${protocol.toUpperCase()}`;
+    const val = process.env[envKey];
+    if (val) {
+      inventoryPrivateKeys[protocol] = val;
+    }
+  }
+  // Backward compat: HYP_INVENTORY_KEY (no suffix) as Ethereum fallback
+  if (
+    !inventoryPrivateKeys[ProtocolType.Ethereum] &&
+    process.env.HYP_INVENTORY_KEY
+  ) {
+    inventoryPrivateKeys[ProtocolType.Ethereum] = process.env.HYP_INVENTORY_KEY;
+  }
+
+  // Parse optional environment variables
+  let checkFrequency = 60_000;
+  if (process.env.CHECK_FREQUENCY) {
+    const parsed = parseInt(process.env.CHECK_FREQUENCY, 10);
+    if (isNaN(parsed) || parsed <= 0) {
+      rootLogger.error(
+        'CHECK_FREQUENCY must be a positive number (milliseconds)',
+      );
+      process.exit(1);
+    }
+    checkFrequency = parsed;
+  }
+
+  const withMetrics = process.env.WITH_METRICS !== 'false';
+  const monitorOnly = process.env.MONITOR_ONLY === 'true';
+  const coingeckoApiKey = process.env.COINGECKO_API_KEY;
+
+  // Create logger (uses LOG_LEVEL environment variable for level configuration)
+  const logger = await createServiceLogger({
+    service: 'rebalancer',
+    version: VERSION,
+  });
+
+  logger.info(
+    {
+      version: VERSION,
+      configFile,
+      checkFrequency,
+      withMetrics,
+      monitorOnly,
+    },
+    'Starting Hyperlane Rebalancer Service',
+  );
+
+  try {
+    // Load rebalancer configuration
+    const rebalancerConfig = RebalancerConfig.load(configFile);
+    logger.info('✅ Loaded rebalancer configuration');
+
+    // Initialize registry (uses env var or defaults to GitHub registry)
+    // For GitHub registries, REGISTRY_URI can include /tree/{commit} to pin to a specific version
+    const registryUri = process.env.REGISTRY_URI || DEFAULT_GITHUB_REGISTRY;
+    const registry = getRegistry({
+      registryUris: [registryUri],
+      enableProxy: true,
+      logger: rootLogger,
+    });
+    logger.info({ registryUri }, '✅ Initialized registry');
+
+    // Get chain metadata from registry
+    const chainMetadata = await registry.getMetadata();
+    logger.info(
+      `✅ Loaded metadata for ${Object.keys(chainMetadata).length} chains`,
+    );
+
+    // Apply RPC URL overrides from environment variables
+    applyRpcUrlOverridesFromEnv(chainMetadata);
+
+    // Create MultiProvider with signer
+    const multiProvider = new MultiProvider(chainMetadata);
+    const rebalancerSigner = new Wallet(rebalancerPrivateKey);
+    multiProvider.setSharedSigner(rebalancerSigner);
+    logger.info(
+      { rebalancerAddress: rebalancerSigner.address },
+      '✅ Initialized MultiProvider with rebalancer signer',
+    );
+
+    // Build consolidated inventory signers with keys embedded
+    const inventorySigners: Partial<
+      Record<ProtocolType, InventorySignerConfig>
+    > = {};
+
+    for (const [protocol, privateKey] of Object.entries(inventoryPrivateKeys)) {
+      if (!privateKey) continue;
+
+      let derivedAddress: string;
+
+      if (protocol === ProtocolType.Ethereum) {
+        derivedAddress = new Wallet(privateKey).address;
+      } else if (protocol === ProtocolType.Sealevel) {
+        const keyBytes = parseSolanaPrivateKey(privateKey);
+        const keypair = Keypair.fromSecretKey(keyBytes);
+        derivedAddress = keypair.publicKey.toBase58();
+      } else {
+        logger.warn(
+          { protocol },
+          `Unsupported protocol for inventory signer derivation, skipping`,
+        );
+        continue;
+      }
+
+      // Validate against config if present
+      const configuredAddress =
+        rebalancerConfig.inventorySigners?.[protocol as ProtocolType]?.address;
+      if (configuredAddress) {
+        const mismatch =
+          protocol === ProtocolType.Ethereum
+            ? configuredAddress.toLowerCase() !== derivedAddress.toLowerCase()
+            : configuredAddress !== derivedAddress;
+        if (mismatch) {
+          throw new Error(
+            `inventorySigners.${protocol} mismatch: config has ${configuredAddress} but HYP_INVENTORY_KEY_${protocol.toUpperCase()} derives to ${derivedAddress}`,
+          );
+        }
+      }
+
+      inventorySigners[protocol as ProtocolType] = {
+        address: derivedAddress,
+        key: privateKey,
+      };
+      logger.info(
+        { protocol, address: derivedAddress },
+        `✅ ${protocol} inventory signer configured`,
+      );
+    }
+
+    // Fail fast if config references protocol-specific inventory signer but key is missing
+    if (!monitorOnly) {
+      for (const protocol of Object.values(ProtocolType)) {
+        if (
+          rebalancerConfig.inventorySigners?.[protocol] &&
+          !inventoryPrivateKeys[protocol]
+        ) {
+          const envKey = `HYP_INVENTORY_KEY_${protocol.toUpperCase()}`;
+          const hint =
+            protocol === ProtocolType.Ethereum
+              ? `${envKey} (or fallback HYP_INVENTORY_KEY)`
+              : envKey;
+          logger.error(
+            {
+              inventorySigner:
+                rebalancerConfig.inventorySigners[protocol]?.address,
+            },
+            `Config specifies inventorySigners.${protocol} but ${hint} is not set.`,
+          );
+          process.exit(1);
+        }
+      }
+    }
+
+    // Merge runtime keys into config — start from YAML config as base, overlay runtime keys per-protocol.
+    // This preserves YAML-only signer addresses (e.g., monitor-only configs) while adding runtime keys.
+    const mergedInventorySigners: Partial<
+      Record<ProtocolType, InventorySignerConfig>
+    > = { ...rebalancerConfig.inventorySigners };
+    for (const protocol of Object.values(ProtocolType)) {
+      const runtimeSigner = inventorySigners[protocol];
+      if (runtimeSigner) {
+        mergedInventorySigners[protocol] = {
+          ...mergedInventorySigners[protocol],
+          ...runtimeSigner,
+        };
+      }
+    }
+
+    const mergedRebalancerConfig =
+      Object.keys(mergedInventorySigners).length > 0
+        ? new RebalancerConfig(
+            rebalancerConfig.warpRouteId,
+            rebalancerConfig.strategyConfig,
+            rebalancerConfig.intentTTL,
+            mergedInventorySigners,
+            rebalancerConfig.externalBridges,
+          )
+        : rebalancerConfig;
+
+    // MultiProtocolProvider will be derived from multiProvider in factory
+    const multiProtocolProvider = undefined;
+
+    // Create the rebalancer service
+    const service = new RebalancerService(
+      multiProvider,
+      multiProtocolProvider,
+      registry,
+      mergedRebalancerConfig,
+      {
+        mode: 'daemon',
+        checkFrequency,
+        monitorOnly,
+        withMetrics,
+        coingeckoApiKey,
+        logger,
+        version: VERSION,
+      },
+    );
+
+    // Start the service
+    await service.start();
+  } catch (error) {
+    const err = error as Error;
+    logger.error(
+      { error: err.message, stack: err.stack },
+      'Failed to start rebalancer service',
+    );
+    process.exit(1);
+  }
+}
+
+// Run the service
+main().catch((error) => {
+  const err = error as Error;
+  rootLogger.error({ error: err.message, stack: err.stack }, 'Fatal error');
+  process.exit(1);
+});