@hyperlane-xyz/rebalancer 0.1.2 → 1.0.0

package/src/tracking/IActionTracker.ts

@@ -0,0 +1,140 @@
+import type { Address, Domain } from '@hyperlane-xyz/utils';
+
+import type { ConfirmedBlockTags } from '../interfaces/IMonitor.js';
+
+import type { RebalanceAction, RebalanceIntent, Transfer } from './types.js';
+
+export interface CreateRebalanceIntentParams {
+  origin: Domain;
+  destination: Domain;
+  amount: bigint;
+  bridge?: Address;
+  priority?: number;
+  strategyType?: string;
+}
+
+export interface CreateRebalanceActionParams {
+  intentId: string;
+  origin: Domain;
+  destination: Domain;
+  amount: bigint;
+  messageId: string;
+  txHash?: string;
+}
+
+/**
+ * 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>;
+
+  // === Transfer Queries ===
+
+  /**
+   * 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 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[]>;
+
+  // === 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 Management ===
+
+  /**
+   * Create a new rebalance action.
+   * Initial status: 'in_progress'
+   * Also transitions parent intent from 'not_started' to 'in_progress'.
+   */
+  createRebalanceAction(
+    params: CreateRebalanceActionParams,
+  ): Promise<RebalanceAction>;
+
+  /**
+   * Mark a rebalance action as complete.
+   * Updates parent intent's fulfilledAmount.
+   */
+  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,203 @@
+import { expect } from 'chai';
+import Sinon from 'sinon';
+
+import type { MultiProvider } from '@hyperlane-xyz/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(),
+    } 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,
+          fulfilledAmount: 0n,
+          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);
+      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,
+        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,
+          fulfilledAmount: 0n,
+          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);
+      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,
+          fulfilledAmount: 0n,
+          status: 'not_started',
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        },
+        {
+          id: 'intent2',
+          origin: 2,
+          destination: 3,
+          amount: 1500n,
+          fulfilledAmount: 0n,
+          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);
+      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,42 @@
+import type { MultiProvider } from '@hyperlane-xyz/sdk';
+
+import type { InflightContext } 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 = intents.map((intent) => ({
+      origin: this.multiProvider.getChainName(intent.origin),
+      destination: this.multiProvider.getChainName(intent.destination),
+      // TODO: Review once inventory rebalancing is implemented and we expect
+      // partially fulfilled intents. May need to use (amount - fulfilledAmount).
+      amount: intent.amount,
+      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/index.ts

@@ -0,0 +1,36 @@
+// Export all store components
+export type { IStore } from './store/index.js';
+export { InMemoryStore } from './store/index.js';
+
+// Export types
+export type {
+  // Base interfaces
+  Identifiable,
+  CrossChainAction,
+  Timestamped,
+  TrackedActionBase,
+  // Status types
+  TransferStatus,
+  RebalanceIntentStatus,
+  RebalanceActionStatus,
+  // Entity types
+  Transfer,
+  RebalanceIntent,
+  RebalanceAction,
+  // Store type aliases
+  ITransferStore,
+  IRebalanceIntentStore,
+  IRebalanceActionStore,
+} from './types.js';
+
+// Export ActionTracker components
+export { ActionTracker, type ActionTrackerConfig } from './ActionTracker.js';
+
+export type {
+  IActionTracker,
+  CreateRebalanceIntentParams,
+  CreateRebalanceActionParams,
+} from './IActionTracker.js';
+
+// Export InflightContextAdapter
+export { InflightContextAdapter } from './InflightContextAdapter.js';

package/src/tracking/store/IStore.ts

@@ -0,0 +1,48 @@
+import type { Domain } from '@hyperlane-xyz/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[]>;
+}