@humanode-hyperlane/rebalancer 0.0.0-stage → 27.2.2

package/src/tracking/IActionTracker.ts

@@ -0,0 +1,213 @@
+import type { Address, Domain } from '@humanode-hyperlane/utils';
+
+import type { ExternalBridgeType } from '../config/types.js';
+import type { ExternalBridgeRegistry } from '../interfaces/IExternalBridge.js';
+import type { ConfirmedBlockTags } from '../interfaces/IMonitor.js';
+
+import type {
+  ActionType,
+  ExecutionMethod,
+  PartialInventoryIntent,
+  RebalanceAction,
+  RebalanceIntent,
+  Transfer,
+} from './types.js';
+
+export interface CreateRebalanceIntentParams {
+  origin: Domain;
+  destination: Domain;
+  amount: bigint;
+  bridge?: Address;
+  priority?: number;
+  strategyType?: string;
+  executionMethod?: ExecutionMethod;
+  externalBridge?: ExternalBridgeType;
+}
+
+export interface CreateRebalanceActionParams {
+  intentId: string;
+  origin: Domain;
+  destination: Domain;
+  amount: bigint;
+  type: ActionType; // Required - type of action being created
+  messageId?: string; // Optional - not needed for inventory_movement
+  txHash?: string;
+  externalBridgeTransferId?: string; // Optional - for inventory_movement (external transfer bridge ID)
+  externalBridgeId?: ExternalBridgeType; // Optional - for inventory_movement (e.g., 'lifi')
+}
+
+/**
+ * ActionTracker manages the lifecycle of tracked entities:
+ * - Transfers: Inflight user warp transfers
+ * - RebalanceIntents: Intents to move collateral
+ * - RebalanceActions: On-chain actions to fulfill intents
+ */
+export interface IActionTracker {
+  // === Lifecycle ===
+
+  /**
+   * Initialize the tracker by loading state from Explorer and on-chain data.
+   * Called once on startup.
+   */
+  initialize(): Promise<void>;
+
+  // === Sync Operations ===
+
+  /**
+   * Sync inflight user transfers from Explorer and verify delivery status.
+   * @param confirmedBlockTags Optional block tags from Monitor for consistent state queries
+   */
+  syncTransfers(confirmedBlockTags?: ConfirmedBlockTags): Promise<void>;
+
+  /**
+   * Sync rebalance intents by checking fulfillment status.
+   */
+  syncRebalanceIntents(): Promise<void>;
+
+  /**
+   * Sync rebalance actions by verifying on-chain message delivery.
+   * @param confirmedBlockTags Optional block tags from Monitor for consistent state queries
+   */
+  syncRebalanceActions(confirmedBlockTags?: ConfirmedBlockTags): Promise<void>;
+
+  /**
+   * Sync inventory_movement actions by checking their status via external bridge API.
+   * This is separate from syncRebalanceActions because inventory_movement actions
+   * don't use Hyperlane messages and need to query the bridge's status API.
+   *
+   * @param externalBridgeRegistry - Bridge registry to query for status
+   * @returns Count of completed and failed actions
+   */
+  syncInventoryMovementActions(
+    externalBridgeRegistry: Partial<ExternalBridgeRegistry>,
+  ): Promise<{ completed: number; failed: number }>;
+
+  // === Transfer Queries ===
+
+  /**
+   * Get a single transfer by ID.
+   */
+  getTransfer(id: string): Promise<Transfer | undefined>;
+
+  /**
+   * Get all transfers currently in progress.
+   */
+  getInProgressTransfers(): Promise<Transfer[]>;
+
+  /**
+   * Get all transfers destined for a specific domain.
+   */
+  getTransfersByDestination(destination: Domain): Promise<Transfer[]>;
+
+  // === RebalanceIntent Queries ===
+
+  /**
+   * Get a single rebalance intent by ID.
+   */
+  getRebalanceIntent(id: string): Promise<RebalanceIntent | undefined>;
+
+  /**
+   * Get all active rebalance intents (not_started + in_progress).
+   */
+  getActiveRebalanceIntents(): Promise<RebalanceIntent[]>;
+
+  /**
+   * Get all rebalance intents destined for a specific domain.
+   */
+  getRebalanceIntentsByDestination(
+    destination: Domain,
+  ): Promise<RebalanceIntent[]>;
+
+  /**
+   * Returns inventory intents that have remaining work.
+   * Intents with in-flight deposits are included but marked via hasInflightDeposit —
+   * callers must check before continuing.
+   * Returns enriched data with computed values derived from action states.
+   */
+  getPartiallyFulfilledInventoryIntents(): Promise<PartialInventoryIntent[]>;
+
+  // === RebalanceIntent Management ===
+
+  /**
+   * Create a new rebalance intent.
+   * Initial status: 'not_started'
+   */
+  createRebalanceIntent(
+    params: CreateRebalanceIntentParams,
+  ): Promise<RebalanceIntent>;
+
+  /**
+   * Mark a rebalance intent as complete.
+   */
+  completeRebalanceIntent(id: string): Promise<void>;
+
+  /**
+   * Cancel a rebalance intent.
+   * Used for deliberate stops (e.g., stale fulfillment).
+   */
+  cancelRebalanceIntent(id: string): Promise<void>;
+
+  /**
+   * Mark a rebalance intent as failed.
+   * Used when tx execution was attempted but failed.
+   */
+  failRebalanceIntent(id: string): Promise<void>;
+
+  // === RebalanceAction Queries ===
+
+  /**
+   * Get actions filtered by type.
+   * @param type - Action type to filter by
+   */
+  getActionsByType(type: ActionType): Promise<RebalanceAction[]>;
+
+  /**
+   * Get all actions associated with a specific intent.
+   * @param intentId - ID of the intent
+   */
+  getActionsForIntent(intentId: string): Promise<RebalanceAction[]>;
+
+  /**
+   * Get total inflight inventory movement amount from a specific chain.
+   * Returns the sum of amounts for all in_progress inventory_movement actions
+   * that originate from the specified domain.
+   *
+   * @param origin - Domain ID of the origin chain
+   * @returns Total amount being moved out via inventory movements
+   */
+  getInflightInventoryMovements(origin: Domain): Promise<bigint>;
+
+  /**
+   * Get a single rebalance action by ID.
+   */
+  getRebalanceAction(id: string): Promise<RebalanceAction | undefined>;
+
+  /**
+   * Get all rebalance actions currently in progress.
+   */
+  getInProgressActions(): Promise<RebalanceAction[]>;
+
+  // === RebalanceAction Management ===
+
+  createRebalanceAction(
+    params: CreateRebalanceActionParams,
+  ): Promise<RebalanceAction>;
+
+  /**
+   * Mark a rebalance action as complete.
+   * Checks if parent intent is now fully fulfilled and marks it complete if so.
+   */
+  completeRebalanceAction(id: string): Promise<void>;
+
+  /**
+   * Mark a rebalance action as failed.
+   */
+  failRebalanceAction(id: string): Promise<void>;
+
+  // === Debug ===
+
+  /**
+   * Log the contents of all stores for debugging purposes.
+   */
+  logStoreContents(): Promise<void>;
+}

package/src/tracking/InflightContextAdapter.test.ts

@@ -0,0 +1,206 @@
+import { expect } from 'chai';
+import Sinon from 'sinon';
+
+import type { MultiProvider } from '@humanode-hyperlane/sdk';
+
+import type { IActionTracker } from './IActionTracker.js';
+import { InflightContextAdapter } from './InflightContextAdapter.js';
+import type { RebalanceIntent, Transfer } from './types.js';
+
+describe('InflightContextAdapter', () => {
+  let actionTracker: Sinon.SinonStubbedInstance<IActionTracker>;
+  let multiProvider: Sinon.SinonStubbedInstance<MultiProvider>;
+  let adapter: InflightContextAdapter;
+
+  beforeEach(() => {
+    actionTracker = {
+      getActiveRebalanceIntents: Sinon.stub(),
+      getInProgressTransfers: Sinon.stub(),
+      getActionsForIntent: Sinon.stub(),
+    } as any;
+
+    multiProvider = {
+      getChainName: Sinon.stub(),
+    } as any;
+
+    adapter = new InflightContextAdapter(
+      actionTracker as any,
+      multiProvider as any,
+    );
+  });
+
+  afterEach(() => {
+    Sinon.restore();
+  });
+
+  describe('getInflightContext', () => {
+    it('should return both pendingRebalances and pendingTransfers', async () => {
+      const mockIntents: RebalanceIntent[] = [
+        {
+          id: 'intent1',
+          origin: 1,
+          destination: 2,
+          amount: 1000n,
+          status: 'not_started',
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        },
+      ];
+
+      const mockTransfers: Transfer[] = [
+        {
+          id: 'transfer1',
+          origin: 1,
+          destination: 2,
+          amount: 500n,
+          messageId: '0x123',
+          sender: '0xabc' as any,
+          recipient: '0xdef' as any,
+          status: 'in_progress',
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        },
+      ];
+
+      actionTracker.getActiveRebalanceIntents.resolves(mockIntents);
+      actionTracker.getInProgressTransfers.resolves(mockTransfers);
+      actionTracker.getActionsForIntent.resolves([]); // No actions
+      multiProvider.getChainName.withArgs(1).returns('ethereum');
+      multiProvider.getChainName.withArgs(2).returns('arbitrum');
+
+      const result = await adapter.getInflightContext();
+
+      expect(result.pendingRebalances).to.have.lengthOf(1);
+      expect(result.pendingRebalances[0]).to.deep.equal({
+        origin: 'ethereum',
+        destination: 'arbitrum',
+        amount: 1000n,
+        deliveredAmount: 0n,
+        awaitingDeliveryAmount: 0n,
+        executionMethod: undefined,
+        bridge: undefined,
+      });
+
+      expect(result.pendingTransfers).to.have.lengthOf(1);
+      expect(result.pendingTransfers[0]).to.deep.equal({
+        origin: 'ethereum',
+        destination: 'arbitrum',
+        amount: 500n,
+      });
+    });
+
+    it('should handle empty arrays', async () => {
+      actionTracker.getActiveRebalanceIntents.resolves([]);
+      actionTracker.getInProgressTransfers.resolves([]);
+
+      const result = await adapter.getInflightContext();
+
+      expect(result.pendingRebalances).to.be.an('array').that.is.empty;
+      expect(result.pendingTransfers).to.be.an('array').that.is.empty;
+    });
+
+    it('should correctly convert domain IDs to chain names', async () => {
+      const mockIntents: RebalanceIntent[] = [
+        {
+          id: 'intent1',
+          origin: 137,
+          destination: 10,
+          amount: 2000n,
+          status: 'not_started',
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        },
+      ];
+
+      const mockTransfers: Transfer[] = [
+        {
+          id: 'transfer1',
+          origin: 137,
+          destination: 10,
+          amount: 300n,
+          messageId: '0x456',
+          sender: '0x111' as any,
+          recipient: '0x222' as any,
+          status: 'in_progress',
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        },
+      ];
+
+      actionTracker.getActiveRebalanceIntents.resolves(mockIntents);
+      actionTracker.getInProgressTransfers.resolves(mockTransfers);
+      actionTracker.getActionsForIntent.resolves([]);
+      multiProvider.getChainName.withArgs(137).returns('polygon');
+      multiProvider.getChainName.withArgs(10).returns('optimism');
+
+      const result = await adapter.getInflightContext();
+
+      expect(result.pendingRebalances[0].origin).to.equal('polygon');
+      expect(result.pendingRebalances[0].destination).to.equal('optimism');
+      expect(result.pendingTransfers[0].origin).to.equal('polygon');
+      expect(result.pendingTransfers[0].destination).to.equal('optimism');
+    });
+
+    it('should handle multiple intents and transfers', async () => {
+      const mockIntents: RebalanceIntent[] = [
+        {
+          id: 'intent1',
+          origin: 1,
+          destination: 2,
+          amount: 1000n,
+          status: 'not_started',
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        },
+        {
+          id: 'intent2',
+          origin: 2,
+          destination: 3,
+          amount: 1500n,
+          status: 'in_progress',
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        },
+      ];
+
+      const mockTransfers: Transfer[] = [
+        {
+          id: 'transfer1',
+          origin: 1,
+          destination: 2,
+          amount: 500n,
+          messageId: '0x123',
+          sender: '0xabc' as any,
+          recipient: '0xdef' as any,
+          status: 'in_progress',
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        },
+        {
+          id: 'transfer2',
+          origin: 3,
+          destination: 1,
+          amount: 750n,
+          messageId: '0x789',
+          sender: '0x333' as any,
+          recipient: '0x444' as any,
+          status: 'in_progress',
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        },
+      ];
+
+      actionTracker.getActiveRebalanceIntents.resolves(mockIntents);
+      actionTracker.getInProgressTransfers.resolves(mockTransfers);
+      actionTracker.getActionsForIntent.resolves([]);
+      multiProvider.getChainName.withArgs(1).returns('ethereum');
+      multiProvider.getChainName.withArgs(2).returns('arbitrum');
+      multiProvider.getChainName.withArgs(3).returns('optimism');
+
+      const result = await adapter.getInflightContext();
+
+      expect(result.pendingRebalances).to.have.lengthOf(2);
+      expect(result.pendingTransfers).to.have.lengthOf(2);
+    });
+  });
+});

package/src/tracking/InflightContextAdapter.ts

@@ -0,0 +1,75 @@
+import type { MultiProvider } from '@humanode-hyperlane/sdk';
+
+import type {
+  InflightContext,
+  RouteWithContext,
+} from '../interfaces/IStrategy.js';
+
+import type { IActionTracker } from './IActionTracker.js';
+
+/**
+ * Adapter that converts ActionTracker data to strategy-consumable InflightContext.
+ * Handles conversion from Domain IDs (used by ActionTracker) to ChainNames (used by Strategy).
+ */
+export class InflightContextAdapter {
+  constructor(
+    private readonly actionTracker: IActionTracker,
+    private readonly multiProvider: MultiProvider,
+  ) {}
+
+  /**
+   * Get inflight context for strategy decision-making.
+   * Includes active rebalance intents and in-progress user transfers.
+   */
+  async getInflightContext(): Promise<InflightContext> {
+    const intents = await this.actionTracker.getActiveRebalanceIntents();
+    const transfers = await this.actionTracker.getInProgressTransfers();
+
+    const pendingRebalances: RouteWithContext[] = await Promise.all(
+      intents.map(async (intent) => {
+        let deliveredAmount = 0n;
+        let awaitingDeliveryAmount = 0n;
+
+        // For inventory intents, compute delivered and awaiting amounts from actions
+        if (intent.executionMethod === 'inventory') {
+          const actions = await this.actionTracker.getActionsForIntent(
+            intent.id,
+          );
+
+          // Sum of complete inventory_deposit actions (message delivered)
+          deliveredAmount = actions
+            .filter(
+              (a) => a.type === 'inventory_deposit' && a.status === 'complete',
+            )
+            .reduce((sum, a) => sum + a.amount, 0n);
+
+          // Sum of in_progress inventory_deposit actions (tx confirmed, message pending)
+          awaitingDeliveryAmount = actions
+            .filter(
+              (a) =>
+                a.type === 'inventory_deposit' && a.status === 'in_progress',
+            )
+            .reduce((sum, a) => sum + a.amount, 0n);
+        }
+
+        return {
+          origin: this.multiProvider.getChainName(intent.origin),
+          destination: this.multiProvider.getChainName(intent.destination),
+          amount: intent.amount,
+          deliveredAmount,
+          awaitingDeliveryAmount,
+          executionMethod: intent.executionMethod,
+          bridge: intent.bridge,
+        };
+      }),
+    );
+
+    const pendingTransfers = transfers.map((transfer) => ({
+      origin: this.multiProvider.getChainName(transfer.origin),
+      destination: this.multiProvider.getChainName(transfer.destination),
+      amount: transfer.amount,
+    }));
+
+    return { pendingRebalances, pendingTransfers };
+  }
+}

package/src/tracking/store/IStore.ts

@@ -0,0 +1,48 @@
+import type { Domain } from '@humanode-hyperlane/utils';
+
+import type { TrackedActionBase } from '../types.js';
+
+/**
+ * Generic store interface for tracking entities.
+ * Provides CRUD operations and query methods for any tracked entity type.
+ *
+ * @template T - The entity type extending TrackedActionBase
+ * @template Status - The status enum type for this entity
+ */
+export interface IStore<T extends TrackedActionBase, Status extends string> {
+  /**
+   * Save a new entity or update an existing one.
+   */
+  save(entity: T): Promise<void>;
+
+  /**
+   * Retrieve an entity by ID.
+   */
+  get(id: string): Promise<T | undefined>;
+
+  /**
+   * Retrieve all entities.
+   */
+  getAll(): Promise<T[]>;
+
+  /**
+   * Update an entity with partial data.
+   * Automatically updates the `updatedAt` timestamp.
+   */
+  update(id: string, updates: Partial<T>): Promise<void>;
+
+  /**
+   * Delete an entity by ID.
+   */
+  delete(id: string): Promise<void>;
+
+  /**
+   * Query entities by status.
+   */
+  getByStatus(status: Status): Promise<T[]>;
+
+  /**
+   * Query entities by destination domain.
+   */
+  getByDestination(destination: Domain): Promise<T[]>;
+}