@hyperlane-xyz/rebalancer 0.1.2 → 1.0.0

package/src/tracking/ActionTracker.ts

@@ -0,0 +1,647 @@
+import type { Logger } from 'pino';
+import { v4 as uuidv4 } from 'uuid';
+
+import type { HyperlaneCore } from '@hyperlane-xyz/sdk';
+import type { Address, Domain } from '@hyperlane-xyz/utils';
+import { parseWarpRouteMessage } from '@hyperlane-xyz/utils';
+
+import type {
+  ConfirmedBlockTag,
+  ConfirmedBlockTags,
+} from '../interfaces/IMonitor.js';
+import type {
+  ExplorerClient,
+  ExplorerMessage,
+} from '../utils/ExplorerClient.js';
+
+import type {
+  CreateRebalanceActionParams,
+  CreateRebalanceIntentParams,
+  IActionTracker,
+} from './IActionTracker.js';
+import type {
+  IRebalanceActionStore,
+  IRebalanceIntentStore,
+  ITransferStore,
+  RebalanceAction,
+  RebalanceIntent,
+  Transfer,
+} from './types.js';
+
+export interface ActionTrackerConfig {
+  routersByDomain: Record<number, string>; // Domain ID → router address (source of truth for routers and domains)
+  bridges: Address[]; // Bridge contract addresses for rebalance action queries
+  rebalancerAddress: Address;
+}
+
+/**
+ * ActionTracker implementation managing the lifecycle of tracked entities.
+ */
+export class ActionTracker implements IActionTracker {
+  constructor(
+    private readonly transferStore: ITransferStore,
+    private readonly rebalanceIntentStore: IRebalanceIntentStore,
+    private readonly rebalanceActionStore: IRebalanceActionStore,
+    private readonly explorerClient: ExplorerClient,
+    private readonly core: HyperlaneCore,
+    private readonly config: ActionTrackerConfig,
+    private readonly logger: Logger,
+  ) {}
+
+  // === Lifecycle ===
+
+  async initialize(): Promise<void> {
+    this.logger.info('ActionTracker initializing');
+
+    // Log config for debugging
+    this.logger.debug(
+      {
+        routersByDomain: this.config.routersByDomain,
+        bridges: this.config.bridges,
+        rebalancerAddress: this.config.rebalancerAddress,
+      },
+      'ActionTracker config',
+    );
+
+    // 1. Startup recovery: query Explorer for inflight rebalance messages
+    const inflightMessages =
+      await this.explorerClient.getInflightRebalanceActions(
+        {
+          bridges: this.config.bridges,
+          routersByDomain: this.config.routersByDomain,
+          rebalancerAddress: this.config.rebalancerAddress,
+        },
+        this.logger,
+      );
+
+    this.logger.info(
+      { count: inflightMessages.length },
+      'Found inflight rebalance messages during startup',
+    );
+
+    // 2. For each message, create synthetic intent + action
+    for (const msg of inflightMessages) {
+      await this.recoverAction(msg);
+    }
+
+    // 3. Sync all stores
+    await this.syncTransfers();
+    await this.syncRebalanceIntents();
+    await this.syncRebalanceActions();
+
+    // Log store contents for debugging
+    await this.logStoreContents();
+
+    this.logger.info('ActionTracker initialized');
+  }
+
+  // === Sync Operations ===
+
+  async syncTransfers(confirmedBlockTags?: ConfirmedBlockTags): Promise<void> {
+    this.logger.debug('Syncing transfers');
+
+    const inflightMessages = await this.explorerClient.getInflightUserTransfers(
+      {
+        routersByDomain: this.config.routersByDomain,
+        excludeTxSender: this.config.rebalancerAddress,
+      },
+      this.logger,
+    );
+
+    this.logger.debug(
+      { count: inflightMessages.length },
+      'Received inflight user transfers from Explorer',
+    );
+
+    let newTransfers = 0;
+    let completedTransfers = 0;
+
+    for (const msg of inflightMessages) {
+      const transfer = await this.transferStore.get(msg.msg_id);
+
+      if (!transfer) {
+        this.logger.debug(
+          {
+            msgId: msg.msg_id,
+            origin: msg.origin_domain_id,
+            destination: msg.destination_domain_id,
+            sender: msg.sender,
+            recipient: msg.recipient,
+            messageBodyLength: msg.message_body?.length,
+            messageBodyPreview: msg.message_body?.substring(0, 66),
+          },
+          'Processing new transfer message',
+        );
+
+        try {
+          const { amount } = parseWarpRouteMessage(msg.message_body);
+          const newTransfer: Transfer = {
+            id: msg.msg_id,
+            status: 'in_progress',
+            messageId: msg.msg_id,
+            origin: msg.origin_domain_id,
+            destination: msg.destination_domain_id,
+            sender: msg.sender,
+            recipient: msg.recipient,
+            amount,
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+          };
+          await this.transferStore.save(newTransfer);
+          newTransfers++;
+          this.logger.debug(
+            { id: newTransfer.id, amount: amount.toString() },
+            'Created new transfer',
+          );
+        } catch (error) {
+          this.logger.warn(
+            {
+              msgId: msg.msg_id,
+              messageBody: msg.message_body,
+              messageBodyLength: msg.message_body?.length,
+              origin: msg.origin_domain_id,
+              destination: msg.destination_domain_id,
+              error: error instanceof Error ? error.message : String(error),
+            },
+            'Failed to parse message body, skipping transfer',
+          );
+        }
+      }
+    }
+
+    const existingTransfers = await this.getInProgressTransfers();
+    for (const transfer of existingTransfers) {
+      const chainName = this.core.multiProvider.getChainName(
+        transfer.destination,
+      );
+      const blockTag = confirmedBlockTags?.[chainName];
+
+      const delivered = await this.isMessageDelivered(
+        transfer.messageId,
+        transfer.destination,
+        blockTag,
+      );
+
+      if (delivered) {
+        await this.transferStore.update(transfer.id, { status: 'complete' });
+        completedTransfers++;
+        this.logger.debug({ id: transfer.id }, 'Transfer completed');
+      }
+    }
+
+    const inProgressCount = (await this.getInProgressTransfers()).length;
+    this.logger.info(
+      {
+        newTransfers,
+        completed: completedTransfers,
+        inProgress: inProgressCount,
+      },
+      'Transfers synced',
+    );
+  }
+
+  async syncRebalanceIntents(): Promise<void> {
+    this.logger.debug('Syncing rebalance intents');
+
+    // Check in_progress intents for completion
+    const inProgressIntents =
+      await this.rebalanceIntentStore.getByStatus('in_progress');
+    for (const intent of inProgressIntents) {
+      if (intent.fulfilledAmount >= intent.amount) {
+        await this.rebalanceIntentStore.update(intent.id, {
+          status: 'complete',
+        });
+        this.logger.debug({ id: intent.id }, 'RebalanceIntent completed');
+      }
+    }
+
+    this.logger.debug('Rebalance intents synced');
+  }
+
+  async syncRebalanceActions(
+    confirmedBlockTags?: ConfirmedBlockTags,
+  ): Promise<void> {
+    this.logger.debug('Syncing rebalance actions');
+
+    let discoveredActions = 0;
+    let completedActions = 0;
+
+    const inflightMessages =
+      await this.explorerClient.getInflightRebalanceActions(
+        {
+          bridges: this.config.bridges,
+          routersByDomain: this.config.routersByDomain,
+          rebalancerAddress: this.config.rebalancerAddress,
+        },
+        this.logger,
+      );
+
+    this.logger.debug(
+      { count: inflightMessages.length },
+      'Found inflight rebalance actions from Explorer',
+    );
+
+    const allActions = await this.rebalanceActionStore.getAll();
+
+    for (const msg of inflightMessages) {
+      const existingAction = allActions.find((a) => a.messageId === msg.msg_id);
+
+      if (!existingAction) {
+        this.logger.info(
+          {
+            msgId: msg.msg_id,
+            origin: msg.origin_domain_id,
+            destination: msg.destination_domain_id,
+          },
+          'Discovered new rebalance action, recovering...',
+        );
+        await this.recoverAction(msg);
+        discoveredActions++;
+      }
+    }
+
+    const inProgressActions =
+      await this.rebalanceActionStore.getByStatus('in_progress');
+    for (const action of inProgressActions) {
+      const chainName = this.core.multiProvider.getChainName(
+        action.destination,
+      );
+      const blockTag = confirmedBlockTags?.[chainName];
+
+      const delivered = await this.isMessageDelivered(
+        action.messageId,
+        action.destination,
+        blockTag,
+      );
+
+      if (delivered) {
+        await this.completeRebalanceAction(action.id);
+        completedActions++;
+        this.logger.debug({ id: action.id }, 'RebalanceAction completed');
+      }
+    }
+
+    const inProgressCount = (
+      await this.rebalanceActionStore.getByStatus('in_progress')
+    ).length;
+    this.logger.info(
+      {
+        discovered: discoveredActions,
+        completed: completedActions,
+        inProgress: inProgressCount,
+      },
+      'Actions synced',
+    );
+  }
+
+  // === Transfer Queries ===
+
+  async getInProgressTransfers(): Promise<Transfer[]> {
+    return this.transferStore.getByStatus('in_progress');
+  }
+
+  async getTransfersByDestination(destination: Domain): Promise<Transfer[]> {
+    return this.transferStore.getByDestination(destination);
+  }
+
+  // === RebalanceIntent Queries ===
+
+  async getActiveRebalanceIntents(): Promise<RebalanceIntent[]> {
+    // Only return in_progress intents - their origin tx is confirmed
+    // so simulation only needs to add to destination (origin already deducted on-chain)
+    return this.rebalanceIntentStore.getByStatus('in_progress');
+  }
+
+  async getRebalanceIntentsByDestination(
+    destination: Domain,
+  ): Promise<RebalanceIntent[]> {
+    return this.rebalanceIntentStore.getByDestination(destination);
+  }
+
+  // === RebalanceIntent Management ===
+
+  async createRebalanceIntent(
+    params: CreateRebalanceIntentParams,
+  ): Promise<RebalanceIntent> {
+    const intent: RebalanceIntent = {
+      id: uuidv4(),
+      status: 'not_started',
+      origin: params.origin,
+      destination: params.destination,
+      amount: params.amount,
+      fulfilledAmount: 0n,
+      bridge: params.bridge,
+      priority: params.priority,
+      strategyType: params.strategyType,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+
+    await this.rebalanceIntentStore.save(intent);
+    this.logger.debug(
+      { id: intent.id, origin: intent.origin, destination: intent.destination },
+      'Created RebalanceIntent',
+    );
+
+    return intent;
+  }
+
+  async completeRebalanceIntent(id: string): Promise<void> {
+    await this.rebalanceIntentStore.update(id, { status: 'complete' });
+    this.logger.info({ id }, 'Intent completed');
+  }
+
+  async cancelRebalanceIntent(id: string): Promise<void> {
+    await this.rebalanceIntentStore.update(id, { status: 'cancelled' });
+    this.logger.debug({ id }, 'Cancelled RebalanceIntent');
+  }
+
+  async failRebalanceIntent(id: string): Promise<void> {
+    await this.rebalanceIntentStore.update(id, { status: 'failed' });
+    this.logger.info({ id }, 'Intent failed');
+  }
+
+  // === RebalanceAction Management ===
+
+  async createRebalanceAction(
+    params: CreateRebalanceActionParams,
+  ): Promise<RebalanceAction> {
+    const action: RebalanceAction = {
+      id: uuidv4(),
+      status: 'in_progress',
+      intentId: params.intentId,
+      messageId: params.messageId,
+      txHash: params.txHash,
+      origin: params.origin,
+      destination: params.destination,
+      amount: params.amount,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+
+    await this.rebalanceActionStore.save(action);
+
+    // Transition parent intent from not_started to in_progress
+    const intent = await this.rebalanceIntentStore.get(params.intentId);
+    if (intent && intent.status === 'not_started') {
+      await this.rebalanceIntentStore.update(intent.id, {
+        status: 'in_progress',
+      });
+      this.logger.debug(
+        { intentId: intent.id },
+        'Transitioned RebalanceIntent to in_progress',
+      );
+    }
+
+    this.logger.debug(
+      { id: action.id, intentId: action.intentId },
+      'Created RebalanceAction',
+    );
+
+    return action;
+  }
+
+  async completeRebalanceAction(id: string): Promise<void> {
+    const action = await this.rebalanceActionStore.get(id);
+    if (!action) {
+      throw new Error(`RebalanceAction ${id} not found`);
+    }
+
+    await this.rebalanceActionStore.update(id, { status: 'complete' });
+
+    // Update parent intent's fulfilledAmount
+    const intent = await this.rebalanceIntentStore.get(action.intentId);
+    if (intent) {
+      const newFulfilledAmount = intent.fulfilledAmount + action.amount;
+      const updates: Partial<RebalanceIntent> = {
+        fulfilledAmount: newFulfilledAmount,
+      };
+
+      // Check if intent is now complete
+      if (newFulfilledAmount >= intent.amount) {
+        updates.status = 'complete';
+        this.logger.debug(
+          { intentId: intent.id },
+          'RebalanceIntent fully fulfilled',
+        );
+      }
+
+      await this.rebalanceIntentStore.update(intent.id, updates);
+    }
+
+    this.logger.info({ id, intentId: action.intentId }, 'Action completed');
+  }
+
+  async failRebalanceAction(id: string): Promise<void> {
+    await this.rebalanceActionStore.update(id, { status: 'failed' });
+    this.logger.info({ id }, 'Action failed');
+  }
+
+  // === Debug Helpers ===
+
+  /**
+   * Log the contents of all stores.
+   * Logs each item separately for full visibility (avoids [Object] truncation).
+   */
+  async logStoreContents(): Promise<void> {
+    const transfers = await this.transferStore.getAll();
+    const intents = await this.rebalanceIntentStore.getAll();
+    const actions = await this.rebalanceActionStore.getAll();
+
+    const activeIntents = intents.filter((i) =>
+      ['not_started', 'in_progress'].includes(i.status),
+    );
+    const inProgressTransfers = transfers.filter(
+      (t) => t.status === 'in_progress',
+    );
+    const inProgressActions = actions.filter((a) => a.status === 'in_progress');
+
+    // Log summary
+    this.logger.info(
+      {
+        transfers: inProgressTransfers.length,
+        intents: activeIntents.length,
+        actions: inProgressActions.length,
+      },
+      'Store summary',
+    );
+
+    // Log each transfer separately
+    for (const t of inProgressTransfers) {
+      this.logger.info(
+        {
+          type: 'transfer',
+          origin: t.origin,
+          destination: t.destination,
+          amount: t.amount.toString(),
+          messageId: t.messageId,
+        },
+        'In-progress transfer',
+      );
+    }
+
+    // Log each intent separately
+    for (const i of activeIntents) {
+      this.logger.info(
+        {
+          type: 'intent',
+          id: i.id,
+          origin: i.origin,
+          destination: i.destination,
+          amount: i.amount.toString(),
+          status: i.status,
+          bridge: i.bridge,
+        },
+        'Active intent',
+      );
+    }
+
+    // Log each action separately
+    for (const a of inProgressActions) {
+      this.logger.info(
+        {
+          type: 'action',
+          id: a.id,
+          origin: a.origin,
+          destination: a.destination,
+          amount: a.amount.toString(),
+          messageId: a.messageId,
+          intentId: a.intentId,
+        },
+        'In-progress action',
+      );
+    }
+  }
+
+  // === Private Helpers ===
+
+  private async getConfirmedBlockTag(
+    chainName: string,
+  ): Promise<ConfirmedBlockTag> {
+    try {
+      const metadata = this.core.multiProvider.getChainMetadata(chainName);
+      const reorgPeriod = metadata.blocks?.reorgPeriod ?? 32;
+
+      if (typeof reorgPeriod === 'string') {
+        return reorgPeriod as ConfirmedBlockTag;
+      }
+
+      const provider = this.core.multiProvider.getProvider(chainName);
+      const latestBlock = await provider.getBlockNumber();
+      return Math.max(0, latestBlock - reorgPeriod);
+    } catch (error) {
+      this.logger.warn(
+        { chain: chainName, error: (error as Error).message },
+        'Failed to get confirmed block, using latest',
+      );
+      return undefined;
+    }
+  }
+
+  private async isMessageDelivered(
+    messageId: string,
+    destination: Domain,
+    providedBlockTag?: ConfirmedBlockTag,
+  ): Promise<boolean> {
+    try {
+      const chainName = this.core.multiProvider.getChainName(destination);
+      const mailbox = this.core.getContracts(chainName).mailbox;
+
+      const blockTag =
+        providedBlockTag ?? (await this.getConfirmedBlockTag(chainName));
+      const delivered = await mailbox.delivered(messageId, { blockTag });
+
+      this.logger.debug(
+        { messageId, destination: chainName, blockTag, delivered },
+        'Checked message delivery at confirmed block',
+      );
+
+      return delivered;
+    } catch (error) {
+      this.logger.warn(
+        { messageId, destination, error },
+        'Failed to check message delivery status',
+      );
+      return false;
+    }
+  }
+
+  private async recoverAction(msg: ExplorerMessage): Promise<void> {
+    // Check if action already exists
+    const existing = await this.rebalanceActionStore.get(msg.msg_id);
+    if (existing) {
+      this.logger.debug({ id: msg.msg_id }, 'Action already exists, skipping');
+      return;
+    }
+
+    this.logger.debug(
+      {
+        msgId: msg.msg_id,
+        origin: msg.origin_domain_id,
+        destination: msg.destination_domain_id,
+        sender: msg.sender,
+        recipient: msg.recipient,
+        txHash: msg.origin_tx_hash,
+        messageBodyLength: msg.message_body?.length,
+        messageBodyPreview: msg.message_body?.substring(0, 66),
+      },
+      'Recovering rebalance action',
+    );
+
+    try {
+      // Create synthetic intent
+      const { amount } = parseWarpRouteMessage(msg.message_body);
+      const intent: RebalanceIntent = {
+        id: uuidv4(),
+        status: 'in_progress',
+        origin: msg.origin_domain_id,
+        destination: msg.destination_domain_id,
+        amount,
+        fulfilledAmount: 0n,
+        priority: undefined,
+        strategyType: undefined,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      await this.rebalanceIntentStore.save(intent);
+      this.logger.debug(
+        { id: intent.id, amount: amount.toString() },
+        'Created synthetic RebalanceIntent',
+      );
+
+      // Create action
+      const action: RebalanceAction = {
+        id: msg.msg_id,
+        status: 'in_progress',
+        intentId: intent.id,
+        messageId: msg.msg_id,
+        txHash: msg.origin_tx_hash,
+        origin: msg.origin_domain_id,
+        destination: msg.destination_domain_id,
+        amount,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      await this.rebalanceActionStore.save(action);
+      this.logger.debug(
+        { id: action.id, intentId: action.intentId, amount: amount.toString() },
+        'Recovered RebalanceAction',
+      );
+    } catch (error) {
+      this.logger.warn(
+        {
+          msgId: msg.msg_id,
+          messageBody: msg.message_body,
+          messageBodyLength: msg.message_body?.length,
+          origin: msg.origin_domain_id,
+          destination: msg.destination_domain_id,
+          txHash: msg.origin_tx_hash,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        'Failed to parse message body during recovery, skipping action',
+      );
+    }
+  }
+}