@hyperlane-xyz/rebalancer 0.1.2 → 1.0.0

package/src/core/RebalancerService.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'crypto';
 import { Logger } from 'pino';
 
 import { IRegistry } from '@hyperlane-xyz/registry';
@@ -9,17 +10,34 @@ import {
 import { assert, toWei } from '@hyperlane-xyz/utils';
 
 import { RebalancerConfig } from '../config/RebalancerConfig.js';
+import {
+  getStrategyChainConfig,
+  getStrategyChainNames,
+} from '../config/types.js';
 import { RebalancerContextFactory } from '../factories/RebalancerContextFactory.js';
 import {
+  type ConfirmedBlockTags,
   MonitorEvent,
   MonitorEventType,
   MonitorPollingError,
   MonitorStartError,
 } from '../interfaces/IMonitor.js';
-import type { IRebalancer } from '../interfaces/IRebalancer.js';
-import type { IStrategy } from '../interfaces/IStrategy.js';
+import type {
+  IRebalancer,
+  RebalanceExecutionResult,
+  RebalanceRoute,
+} from '../interfaces/IRebalancer.js';
+import type {
+  IStrategy,
+  InflightContext,
+  StrategyRoute,
+} from '../interfaces/IStrategy.js';
 import { Metrics } from '../metrics/Metrics.js';
 import { Monitor } from '../monitor/Monitor.js';
+import {
+  type IActionTracker,
+  InflightContextAdapter,
+} from '../tracking/index.js';
 import { getRawBalances } from '../utils/balanceUtils.js';
 
 export interface RebalancerServiceConfig {
@@ -101,6 +119,8 @@ export class RebalancerService {
   private rebalancer?: IRebalancer;
   private metrics?: Metrics;
   private mode: 'manual' | 'daemon';
+  private actionTracker?: IActionTracker;
+  private inflightContextAdapter?: InflightContextAdapter;
 
   constructor(
     private readonly multiProvider: MultiProvider,
@@ -159,7 +179,24 @@ export class RebalancerService {
       );
     }
 
-    this.logger.info('✅ RebalancerService initialized successfully');
+    // Create ActionTracker for tracking inflight actions
+    const { tracker, adapter } =
+      await this.contextFactory.createActionTracker();
+    this.actionTracker = tracker;
+    this.inflightContextAdapter = adapter;
+    await this.actionTracker.initialize();
+    this.logger.info('ActionTracker initialized');
+
+    this.logger.info(
+      {
+        warpRouteId: this.rebalancerConfig.warpRouteId,
+        strategyTypes: this.rebalancerConfig.strategyConfig.map(
+          (s) => s.rebalanceStrategy,
+        ),
+        chains: getStrategyChainNames(this.rebalancerConfig.strategyConfig),
+      },
+      'RebalancerService initialized',
+    );
   }
 
   /**
@@ -195,14 +232,28 @@ export class RebalancerService {
     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 {
-      await this.rebalancer.rebalance([
-        {
-          origin,
-          destination,
-          amount: BigInt(toWei(amount, originToken.decimals)),
-        },
-      ]);
+      const route: RebalanceRoute = {
+        intentId: randomUUID(),
+        origin,
+        destination,
+        amount: BigInt(toWei(amount, originToken.decimals)),
+        bridge,
+      };
+      await this.rebalancer.rebalance([route]);
       this.logger.info(
         `✅ Manual rebalance from ${origin} to ${destination} for amount ${amount} submitted successfully.`,
       );
@@ -274,10 +325,9 @@ export class RebalancerService {
     process.exit(0);
   }
 
-  /**
-   * Event handler for token info updates from monitor
-   */
   private async onTokenInfo(event: MonitorEvent): Promise<void> {
+    this.logger.info('Polling cycle started');
+
     if (this.metrics) {
       await Promise.all(
         event.tokensInfo.map((tokenInfo) =>
@@ -286,24 +336,196 @@ export class RebalancerService {
       );
     }
 
+    await this.syncActionTracker(event.confirmedBlockTags);
+
     const rawBalances = getRawBalances(
-      Object.keys(this.rebalancerConfig.strategyConfig.chains),
+      getStrategyChainNames(this.rebalancerConfig.strategyConfig),
       event,
       this.logger,
     );
 
-    const rebalancingRoutes = this.strategy!.getRebalancingRoutes(rawBalances);
+    this.logger.info(
+      {
+        balances: Object.entries(rawBalances).map(([chain, balance]) => ({
+          chain,
+          balance: balance.toString(),
+        })),
+      },
+      'Router balances',
+    );
+
+    // Get inflight context for strategy decision-making
+    const inflightContext = await this.getInflightContext();
 
-    this.rebalancer
-      ?.rebalance(rebalancingRoutes)
-      .then(() => {
+    const strategyRoutes = this.strategy!.getRebalancingRoutes(
+      rawBalances,
+      inflightContext,
+    );
+
+    if (strategyRoutes.length > 0) {
+      this.logger.info(
+        {
+          routes: strategyRoutes.map((r) => ({
+            from: r.origin,
+            to: r.destination,
+            amount: r.amount.toString(),
+          })),
+        },
+        'Routes proposed',
+      );
+      if (this.rebalancer) {
+        await this.executeWithTracking(strategyRoutes);
+      }
+    } else {
+      this.logger.info('No rebalancing needed');
+    }
+
+    this.logger.info('Polling cycle completed');
+  }
+
+  private async syncActionTracker(
+    confirmedBlockTags?: ConfirmedBlockTags,
+  ): Promise<void> {
+    if (!this.actionTracker) return;
+
+    try {
+      await Promise.all([
+        this.actionTracker.syncTransfers(confirmedBlockTags),
+        this.actionTracker.syncRebalanceIntents(),
+        this.actionTracker.syncRebalanceActions(confirmedBlockTags),
+      ]);
+
+      await this.actionTracker.logStoreContents();
+    } catch (error) {
+      this.logger.warn(
+        { error },
+        'ActionTracker sync failed, using stale data',
+      );
+    }
+  }
+
+  /**
+   * Get inflight context for strategy decision-making
+   */
+  private async getInflightContext(): Promise<InflightContext> {
+    if (!this.inflightContextAdapter) {
+      return { pendingRebalances: [], pendingTransfers: [] };
+    }
+
+    return this.inflightContextAdapter.getInflightContext();
+  }
+
+  /**
+   * Execute rebalancing with intent tracking.
+   * Creates intents and assigns IDs to routes before execution, then processes results by ID.
+   */
+  private async executeWithTracking(
+    strategyRoutes: StrategyRoute[],
+  ): Promise<void> {
+    if (!this.rebalancer || !this.actionTracker) {
+      this.logger.warn('Rebalancer or ActionTracker not available, skipping');
+      return;
+    }
+
+    // 1. Convert strategy routes to rebalance routes with IDs and create intents
+    // The route ID is used as the intent ID for direct matching
+    const rebalanceRoutes: RebalanceRoute[] = [];
+    const intentIds: string[] = [];
+
+    for (const route of strategyRoutes) {
+      const intent = await this.actionTracker.createRebalanceIntent({
+        origin: this.multiProvider.getDomainId(route.origin),
+        destination: this.multiProvider.getDomainId(route.destination),
+        amount: route.amount,
+        bridge: route.bridge,
+      });
+      intentIds.push(intent.id);
+      rebalanceRoutes.push({
+        ...route,
+        intentId: intent.id,
+      });
+    }
+
+    this.logger.debug(
+      { intentCount: rebalanceRoutes.length },
+      'Created rebalance intents',
+    );
+
+    // 2. Execute rebalance with routes that have IDs
+    let results: RebalanceExecutionResult[];
+    try {
+      results = await this.rebalancer.rebalance(rebalanceRoutes);
+      const failedResults = results.filter((r) => !r.success);
+      if (failedResults.length > 0) {
+        this.metrics?.recordRebalancerFailure();
+        this.logger.warn(
+          { failureCount: failedResults.length, total: results.length },
+          'Rebalancer cycle completed with failures',
+        );
+      } else {
         this.metrics?.recordRebalancerSuccess();
         this.logger.info('Rebalancer completed a cycle successfully');
-      })
-      .catch((error: any) => {
-        this.metrics?.recordRebalancerFailure();
-        this.logger.error({ error }, 'Error while rebalancing');
-      });
+      }
+    } catch (error: any) {
+      this.metrics?.recordRebalancerFailure();
+      this.logger.error({ error }, 'Error while rebalancing');
+
+      // Mark all intents as failed
+      await Promise.all(
+        intentIds.map((id) => this.actionTracker!.failRebalanceIntent(id)),
+      );
+      return;
+    }
+
+    // 3. Process results - results have IDs that match intents directly
+    await this.processExecutionResults(results);
+  }
+
+  /**
+   * Process execution results and update tracking state.
+   * Results are matched to intents by the route ID (which equals the intent ID).
+   */
+  private async processExecutionResults(
+    results: RebalanceExecutionResult[],
+  ): Promise<void> {
+    for (const result of results) {
+      const intentId = result.route.intentId;
+
+      if (result.success && result.messageId) {
+        await this.actionTracker!.createRebalanceAction({
+          intentId,
+          origin: this.multiProvider.getDomainId(result.route.origin),
+          destination: this.multiProvider.getDomainId(result.route.destination),
+          amount: result.route.amount,
+          messageId: result.messageId,
+          txHash: result.txHash,
+        });
+
+        this.logger.info(
+          {
+            intentId,
+            messageId: result.messageId,
+            txHash: result.txHash,
+            origin: result.route.origin,
+            destination: result.route.destination,
+          },
+          'Rebalance action created successfully',
+        );
+      } else {
+        await this.actionTracker!.failRebalanceIntent(intentId);
+
+        this.logger.warn(
+          {
+            intentId,
+            success: result.success,
+            error: result.error,
+            origin: result.route.origin,
+            destination: result.route.destination,
+          },
+          'Rebalance intent marked as failed',
+        );
+      }
+    }
   }
 
   /**

package/src/factories/RebalancerContextFactory.ts

@@ -3,6 +3,7 @@ import { type Logger } from 'pino';
 import { IRegistry } from '@hyperlane-xyz/registry';
 import {
   type ChainMap,
+  HyperlaneCore,
   MultiProtocolProvider,
   MultiProvider,
   type Token,
@@ -11,16 +12,33 @@ import {
 import { objMap } from '@hyperlane-xyz/utils';
 
 import { type RebalancerConfig } from '../config/RebalancerConfig.js';
+import { getAllBridges, getStrategyChainNames } from '../config/types.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 {
+  ActionTracker,
+  type ActionTrackerConfig,
+  type IActionTracker,
+  InMemoryStore,
+  InflightContextAdapter,
+  type RebalanceAction,
+  type RebalanceActionStatus,
+  type RebalanceIntent,
+  type RebalanceIntentStatus,
+  type Transfer,
+  type TransferStatus,
+} from '../tracking/index.js';
+import { ExplorerClient } from '../utils/ExplorerClient.js';
 import { isCollateralizedTokenEligibleForRebalancing } from '../utils/index.js';
 
+const DEFAULT_EXPLORER_URL =
+  process.env.EXPLORER_API_URL || 'https://explorer4.hasura.app/v1/graphql';
+
 export class RebalancerContextFactory {
   /**
    * @param config - The rebalancer config
@@ -141,10 +159,14 @@ export class RebalancerContextFactory {
   }
 
   public async createStrategy(metrics?: Metrics): Promise<IStrategy> {
+    const strategyTypes = this.config.strategyConfig.map(
+      (s) => s.rebalanceStrategy,
+    );
     this.logger.debug(
       {
         warpRouteId: this.config.warpRouteId,
-        strategyType: this.config.strategyConfig.rebalanceStrategy,
+        strategyTypes,
+        strategyCount: this.config.strategyConfig.length,
       },
       'Creating Strategy',
     );
@@ -162,13 +184,8 @@ export class RebalancerContextFactory {
       { 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,
@@ -177,20 +194,104 @@ export class RebalancerContextFactory {
       metrics,
     );
 
-    // Wrap with semaphore for concurrency control
-    const withSemaphore = new WithSemaphore(
-      this.config,
-      rebalancer,
+    return rebalancer;
+  }
+
+  /**
+   * Creates an ActionTracker for tracking inflight rebalance actions and user transfers.
+   * Returns both the tracker and adapter for use by RebalancerService.
+   *
+   * @param explorerUrl - Optional explorer URL (defaults to production Hyperlane Explorer)
+   */
+  public async createActionTracker(
+    explorerUrl: string = DEFAULT_EXPLORER_URL,
+  ): Promise<{
+    tracker: IActionTracker;
+    adapter: InflightContextAdapter;
+  }> {
+    this.logger.debug(
+      { warpRouteId: this.config.warpRouteId },
+      'Creating ActionTracker',
+    );
+
+    // 1. Create in-memory stores
+    const transferStore = new InMemoryStore<Transfer, TransferStatus>();
+    const intentStore = new InMemoryStore<
+      RebalanceIntent,
+      RebalanceIntentStatus
+    >();
+    const actionStore = new InMemoryStore<
+      RebalanceAction,
+      RebalanceActionStatus
+    >();
+
+    // 2. Create ExplorerClient
+    const explorerClient = new ExplorerClient(explorerUrl);
+
+    // 3. Get HyperlaneCore from registry
+    const addresses = await this.registry.getAddresses();
+    const hyperlaneCore = HyperlaneCore.fromAddressesMap(
+      addresses,
+      this.multiProvider,
+    );
+
+    // 4. Get rebalancer address from signer
+    // Use the first chain in the strategy to get the signer address
+    const chainNames = getStrategyChainNames(this.config.strategyConfig);
+    if (chainNames.length === 0) {
+      throw new Error('No chains configured in strategy');
+    }
+    const signer = this.multiProvider.getSigner(chainNames[0]);
+    const rebalancerAddress = await signer.getAddress();
+
+    const bridges = getAllBridges(this.config.strategyConfig);
+
+    // Build router→domain mapping (source of truth for routers and domains)
+    const routersByDomain: Record<number, string> = {};
+    for (const token of this.warpCore.tokens) {
+      const domain = this.multiProvider.getDomainId(token.chainName);
+      routersByDomain[domain] = token.addressOrDenom;
+    }
+
+    const trackerConfig: ActionTrackerConfig = {
+      routersByDomain,
+      bridges,
+      rebalancerAddress,
+    };
+
+    // 6. Create ActionTracker
+    const tracker = new ActionTracker(
+      transferStore,
+      intentStore,
+      actionStore,
+      explorerClient,
+      hyperlaneCore,
+      trackerConfig,
       this.logger,
     );
 
-    return withSemaphore;
+    // 7. Create InflightContextAdapter
+    const adapter = new InflightContextAdapter(tracker, this.multiProvider);
+
+    this.logger.debug(
+      {
+        warpRouteId: this.config.warpRouteId,
+        routerCount: Object.keys(routersByDomain).length,
+        bridgeCount: bridges.length,
+        domainCount: Object.keys(routersByDomain).length,
+      },
+      'ActionTracker created successfully',
+    );
+
+    return { tracker, adapter };
   }
 
   private async getInitialTotalCollateral(): Promise<bigint> {
     let initialTotalCollateral = 0n;
 
-    const chainNames = new Set(Object.keys(this.config.strategyConfig.chains));
+    const chainNames = new Set(
+      getStrategyChainNames(this.config.strategyConfig),
+    );
 
     await Promise.all(
       this.warpCore.tokens.map(async (token) => {

package/src/index.ts

@@ -16,17 +16,18 @@ export type {
 
 // 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';
 export {
+  getStrategyChainConfig,
+  getStrategyChainNames,
   RebalancerBaseChainConfigSchema,
   RebalancerConfigSchema,
   RebalancerMinAmountConfigSchema,
   RebalancerMinAmountType,
   RebalancerStrategyOptions,
+  RebalancerStrategySchema,
   RebalancerWeightedChainConfigSchema,
   StrategyConfigSchema,
 } from './config/types.js';
@@ -42,6 +43,7 @@ export type {
 
 // Strategy
 export { BaseStrategy } from './strategy/BaseStrategy.js';
+export { CompositeStrategy } from './strategy/CompositeStrategy.js';
 export { WeightedStrategy } from './strategy/WeightedStrategy.js';
 export { MinAmountStrategy } from './strategy/MinAmountStrategy.js';
 export { StrategyFactory } from './strategy/StrategyFactory.js';
@@ -57,13 +59,20 @@ export { PriceGetter } from './metrics/PriceGetter.js';
 export type {
   IRebalancer,
   PreparedTransaction,
+  RebalanceRoute,
+  RebalanceExecutionResult,
 } from './interfaces/IRebalancer.js';
 export type {
   IStrategy,
-  RebalancingRoute,
+  StrategyRoute,
   RawBalances,
+  InflightContext,
 } from './interfaces/IStrategy.js';
-export type { IMonitor } from './interfaces/IMonitor.js';
+export type {
+  ConfirmedBlockTag,
+  ConfirmedBlockTags,
+  IMonitor,
+} from './interfaces/IMonitor.js';
 export {
   MonitorEventType,
   MonitorEvent,
@@ -82,5 +91,8 @@ export { getRawBalances } from './utils/balanceUtils.js';
 export { isCollateralizedTokenEligibleForRebalancing } from './utils/tokenUtils.js';
 export { ExplorerClient } from './utils/ExplorerClient.js';
 
+// Tracking
+export { InflightContextAdapter } from './tracking/InflightContextAdapter.js';
+
 // Factory
 export { RebalancerContextFactory } from './factories/RebalancerContextFactory.js';

package/src/interfaces/IMonitor.ts

@@ -1,4 +1,8 @@
-import { type Token } from '@hyperlane-xyz/sdk';
+import {
+  type ChainMap,
+  EthJsonRpcBlockParameterTag,
+  type Token,
+} from '@hyperlane-xyz/sdk';
 
 import { WrappedError } from '../utils/errors.js';
 
@@ -16,17 +20,19 @@ export enum MonitorEventType {
   Start = 'Start',
 }
 
-/**
- * Represents an event emitted by the monitor containing bridgedSupply and token information.
- */
+export type ConfirmedBlockTag =
+  | number
+  | EthJsonRpcBlockParameterTag
+  | undefined;
+
+export type ConfirmedBlockTags = ChainMap<ConfirmedBlockTag>;
+
 export type MonitorEvent = {
-  /**
-   * Collection of objects containing the information retrieved by the Monitor.
-   */
   tokensInfo: {
     token: Token;
     bridgedSupply?: bigint;
   }[];
+  confirmedBlockTags: ConfirmedBlockTags;
 };
 
 /**
@@ -35,10 +41,11 @@ export type MonitorEvent = {
 export interface IMonitor {
   /**
    * Allows subscribers to listen to hyperlane's tokens info.
+   * Handler can be async - Monitor will await it before starting next cycle.
    */
   on(
     eventName: MonitorEventType.TokenInfo,
-    fn: (event: MonitorEvent) => void,
+    fn: (event: MonitorEvent) => void | Promise<void>,
   ): this;
 
   /**

package/src/interfaces/IRebalancer.ts

@@ -3,21 +3,39 @@ import {
   type TokenAmount,
 } from '@hyperlane-xyz/sdk';
 
-import { type RebalancingRoute } from './IStrategy.js';
+import type { StrategyRoute } from './IStrategy.js';
+
+/**
+ * RebalanceRoute extends StrategyRoute with a required intentId for tracking.
+ * The intentId is assigned by RebalancerService before execution and links
+ * to the corresponding RebalanceIntent in the tracking system.
+ */
+export type RebalanceRoute = StrategyRoute & {
+  /** Links to the RebalanceIntent that this route fulfills */
+  intentId: string;
+};
 
 export type PreparedTransaction = {
   populatedTx: Awaited<
     ReturnType<EvmMovableCollateralAdapter['populateRebalanceTx']>
   >;
-  route: RebalancingRoute;
+  route: RebalanceRoute;
   originTokenAmount: TokenAmount;
 };
 
 export type RebalanceMetrics = {
-  route: RebalancingRoute;
+  route: RebalanceRoute;
   originTokenAmount: TokenAmount;
 };
 
+export type RebalanceExecutionResult = {
+  route: RebalanceRoute;
+  success: boolean;
+  messageId?: string;
+  txHash?: string;
+  error?: string;
+};
+
 export interface IRebalancer {
-  rebalance(routes: RebalancingRoute[]): Promise<void>;
+  rebalance(routes: RebalanceRoute[]): Promise<RebalanceExecutionResult[]>;
 }

package/src/interfaces/IStrategy.ts

@@ -1,13 +1,34 @@
 import { type ChainMap, type ChainName } from '@hyperlane-xyz/sdk';
+import type { Address } from '@hyperlane-xyz/utils';
 
 export type RawBalances = ChainMap<bigint>;
 
-export type RebalancingRoute = {
+export interface Route {
   origin: ChainName;
   destination: ChainName;
   amount: bigint;
+}
+
+export interface StrategyRoute extends Route {
+  bridge: Address;
+}
+
+export type InflightContext = {
+  /**
+   * In-flight rebalances from ActionTracker.
+   * Uses Route[] because recovered intents (from Explorer startup recovery)
+   * don't have bridge information. Some routes may have bridge at runtime.
+   */
+  pendingRebalances: Route[];
+  pendingTransfers: Route[];
+  /** Routes from earlier strategies - always have bridge */
+  proposedRebalances?: StrategyRoute[];
 };
 
 export interface IStrategy {
-  getRebalancingRoutes(rawBalances: RawBalances): RebalancingRoute[];
+  readonly name: string;
+  getRebalancingRoutes(
+    rawBalances: RawBalances,
+    inflightContext?: InflightContext,
+  ): StrategyRoute[];
 }