@humanode-hyperlane/rebalancer 0.0.0-stage → 27.2.2

package/src/tracking/store/InMemoryStore.test.ts

@@ -0,0 +1,338 @@
+import chai, { expect } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+
+import type { Transfer } from '../types.js';
+
+import { InMemoryStore } from './InMemoryStore.js';
+
+chai.use(chaiAsPromised);
+
+describe('InMemoryStore', () => {
+  let store: InMemoryStore<Transfer, 'in_progress' | 'complete'>;
+
+  beforeEach(() => {
+    store = new InMemoryStore<Transfer, 'in_progress' | 'complete'>();
+  });
+
+  describe('save', () => {
+    it('should save a new entity', async () => {
+      const transfer: Transfer = {
+        id: 'transfer-1',
+        status: 'in_progress',
+        messageId: 'msg-1',
+        origin: 1,
+        destination: 2,
+        amount: 100n,
+        sender: '0xsender',
+        recipient: '0xrecipient',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      await store.save(transfer);
+
+      const retrieved = await store.get('transfer-1');
+      expect(retrieved).to.deep.equal(transfer);
+    });
+
+    it('should overwrite an existing entity with the same id', async () => {
+      const transfer1: Transfer = {
+        id: 'transfer-1',
+        status: 'in_progress',
+        messageId: 'msg-1',
+        origin: 1,
+        destination: 2,
+        amount: 100n,
+        sender: '0xsender',
+        recipient: '0xrecipient',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      const transfer2: Transfer = {
+        ...transfer1,
+        status: 'complete',
+        updatedAt: Date.now() + 1000,
+      };
+
+      await store.save(transfer1);
+      await store.save(transfer2);
+
+      const retrieved = await store.get('transfer-1');
+      expect(retrieved?.status).to.equal('complete');
+    });
+  });
+
+  describe('get', () => {
+    it('should return undefined for non-existent entity', async () => {
+      const result = await store.get('non-existent');
+      expect(result).to.be.undefined;
+    });
+
+    it('should retrieve an existing entity', async () => {
+      const transfer: Transfer = {
+        id: 'transfer-1',
+        status: 'in_progress',
+        messageId: 'msg-1',
+        origin: 1,
+        destination: 2,
+        amount: 100n,
+        sender: '0xsender',
+        recipient: '0xrecipient',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      await store.save(transfer);
+      const retrieved = await store.get('transfer-1');
+
+      expect(retrieved).to.deep.equal(transfer);
+    });
+  });
+
+  describe('getAll', () => {
+    it('should return empty array when no entities exist', async () => {
+      const result = await store.getAll();
+      expect(result).to.be.an('array').that.is.empty;
+    });
+
+    it('should return all entities', async () => {
+      const transfer1: Transfer = {
+        id: 'transfer-1',
+        status: 'in_progress',
+        messageId: 'msg-1',
+        origin: 1,
+        destination: 2,
+        amount: 100n,
+        sender: '0xsender1',
+        recipient: '0xrecipient1',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      const transfer2: Transfer = {
+        id: 'transfer-2',
+        status: 'complete',
+        messageId: 'msg-2',
+        origin: 2,
+        destination: 3,
+        amount: 200n,
+        sender: '0xsender2',
+        recipient: '0xrecipient2',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      await store.save(transfer1);
+      await store.save(transfer2);
+
+      const result = await store.getAll();
+      expect(result).to.have.lengthOf(2);
+      expect(result).to.deep.include(transfer1);
+      expect(result).to.deep.include(transfer2);
+    });
+  });
+
+  describe('update', () => {
+    it('should throw error when updating non-existent entity', async () => {
+      await expect(
+        store.update('non-existent', { status: 'complete' }),
+      ).to.be.rejectedWith('Entity non-existent not found');
+    });
+
+    it('should update existing entity', async () => {
+      const transfer: Transfer = {
+        id: 'transfer-1',
+        status: 'in_progress',
+        messageId: 'msg-1',
+        origin: 1,
+        destination: 2,
+        amount: 100n,
+        sender: '0xsender',
+        recipient: '0xrecipient',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      await store.save(transfer);
+      await store.update('transfer-1', { status: 'complete' });
+
+      const updated = await store.get('transfer-1');
+      expect(updated?.status).to.equal('complete');
+      expect(updated?.updatedAt).to.be.at.least(transfer.updatedAt);
+    });
+
+    it('should preserve non-updated fields', async () => {
+      const transfer: Transfer = {
+        id: 'transfer-1',
+        status: 'in_progress',
+        messageId: 'msg-1',
+        origin: 1,
+        destination: 2,
+        amount: 100n,
+        sender: '0xsender',
+        recipient: '0xrecipient',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      await store.save(transfer);
+      await store.update('transfer-1', { status: 'complete' });
+
+      const updated = await store.get('transfer-1');
+      expect(updated?.messageId).to.equal('msg-1');
+      expect(updated?.origin).to.equal(1);
+      expect(updated?.destination).to.equal(2);
+      expect(updated?.amount).to.equal(100n);
+    });
+  });
+
+  describe('delete', () => {
+    it('should delete existing entity', async () => {
+      const transfer: Transfer = {
+        id: 'transfer-1',
+        status: 'in_progress',
+        messageId: 'msg-1',
+        origin: 1,
+        destination: 2,
+        amount: 100n,
+        sender: '0xsender',
+        recipient: '0xrecipient',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      await store.save(transfer);
+      await store.delete('transfer-1');
+
+      const retrieved = await store.get('transfer-1');
+      expect(retrieved).to.be.undefined;
+    });
+
+    it('should not throw when deleting non-existent entity', async () => {
+      await expect(store.delete('non-existent')).to.not.be.rejected;
+    });
+  });
+
+  describe('getByStatus', () => {
+    it('should return empty array when no entities match status', async () => {
+      const result = await store.getByStatus('complete');
+      expect(result).to.be.an('array').that.is.empty;
+    });
+
+    it('should return only entities with matching status', async () => {
+      const transfer1: Transfer = {
+        id: 'transfer-1',
+        status: 'in_progress',
+        messageId: 'msg-1',
+        origin: 1,
+        destination: 2,
+        amount: 100n,
+        sender: '0xsender1',
+        recipient: '0xrecipient1',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      const transfer2: Transfer = {
+        id: 'transfer-2',
+        status: 'complete',
+        messageId: 'msg-2',
+        origin: 2,
+        destination: 3,
+        amount: 200n,
+        sender: '0xsender2',
+        recipient: '0xrecipient2',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      const transfer3: Transfer = {
+        id: 'transfer-3',
+        status: 'in_progress',
+        messageId: 'msg-3',
+        origin: 3,
+        destination: 1,
+        amount: 300n,
+        sender: '0xsender3',
+        recipient: '0xrecipient3',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      await store.save(transfer1);
+      await store.save(transfer2);
+      await store.save(transfer3);
+
+      const inProgress = await store.getByStatus('in_progress');
+      expect(inProgress).to.have.lengthOf(2);
+      expect(inProgress).to.deep.include(transfer1);
+      expect(inProgress).to.deep.include(transfer3);
+
+      const complete = await store.getByStatus('complete');
+      expect(complete).to.have.lengthOf(1);
+      expect(complete).to.deep.include(transfer2);
+    });
+  });
+
+  describe('getByDestination', () => {
+    it('should return empty array when no entities match destination', async () => {
+      const result = await store.getByDestination(999);
+      expect(result).to.be.an('array').that.is.empty;
+    });
+
+    it('should return only entities with matching destination', async () => {
+      const transfer1: Transfer = {
+        id: 'transfer-1',
+        status: 'in_progress',
+        messageId: 'msg-1',
+        origin: 1,
+        destination: 2,
+        amount: 100n,
+        sender: '0xsender1',
+        recipient: '0xrecipient1',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      const transfer2: Transfer = {
+        id: 'transfer-2',
+        status: 'complete',
+        messageId: 'msg-2',
+        origin: 2,
+        destination: 3,
+        amount: 200n,
+        sender: '0xsender2',
+        recipient: '0xrecipient2',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      const transfer3: Transfer = {
+        id: 'transfer-3',
+        status: 'in_progress',
+        messageId: 'msg-3',
+        origin: 3,
+        destination: 2,
+        amount: 300n,
+        sender: '0xsender3',
+        recipient: '0xrecipient3',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+
+      await store.save(transfer1);
+      await store.save(transfer2);
+      await store.save(transfer3);
+
+      const toDomain2 = await store.getByDestination(2);
+      expect(toDomain2).to.have.lengthOf(2);
+      expect(toDomain2).to.deep.include(transfer1);
+      expect(toDomain2).to.deep.include(transfer3);
+
+      const toDomain3 = await store.getByDestination(3);
+      expect(toDomain3).to.have.lengthOf(1);
+      expect(toDomain3).to.deep.include(transfer2);
+    });
+  });
+});

package/src/tracking/store/InMemoryStore.ts

@@ -0,0 +1,59 @@
+import type { Domain } from '@humanode-hyperlane/utils';
+
+import type { TrackedActionBase } from '../types.js';
+
+import type { IStore } from './IStore.js';
+
+/**
+ * In-memory implementation of the IStore interface.
+ * Uses a Map for fast lookups and keeps all data in memory.
+ *
+ * @template T - The entity type extending TrackedActionBase
+ * @template Status - The status enum type for this entity
+ */
+export class InMemoryStore<
+  T extends TrackedActionBase,
+  Status extends string,
+> implements IStore<T, Status> {
+  protected data: Map<string, T> = new Map();
+
+  async save(entity: T): Promise<void> {
+    this.data.set(entity.id, entity);
+  }
+
+  async get(id: string): Promise<T | undefined> {
+    return this.data.get(id);
+  }
+
+  async getAll(): Promise<T[]> {
+    return Array.from(this.data.values());
+  }
+
+  async update(id: string, updates: Partial<T>): Promise<void> {
+    const existing = this.data.get(id);
+    if (!existing) {
+      throw new Error(`Entity ${id} not found`);
+    }
+    this.data.set(id, {
+      ...existing,
+      ...updates,
+      updatedAt: Date.now(),
+    } as T);
+  }
+
+  async delete(id: string): Promise<void> {
+    this.data.delete(id);
+  }
+
+  async getByStatus(status: Status): Promise<T[]> {
+    return Array.from(this.data.values()).filter(
+      (entity) => entity.status === status,
+    );
+  }
+
+  async getByDestination(destination: Domain): Promise<T[]> {
+    return Array.from(this.data.values()).filter(
+      (entity) => entity.destination === destination,
+    );
+  }
+}

package/src/tracking/store/index.ts

@@ -0,0 +1,2 @@
+export type { IStore } from './IStore.js';
+export { InMemoryStore } from './InMemoryStore.js';

package/src/tracking/types.ts

@@ -0,0 +1,118 @@
+import type { Address, Domain } from '@humanode-hyperlane/utils';
+
+import type { ExternalBridgeType } from '../config/types.js';
+import type { BridgeTransferStatus } from '../interfaces/IExternalBridge.js';
+
+import type { IStore } from './store/IStore.js';
+
+// === Base Interfaces ===
+
+export interface Identifiable {
+  id: string;
+}
+
+export interface CrossChainAction {
+  origin: Domain;
+  destination: Domain;
+  amount: bigint;
+}
+
+export interface Timestamped {
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface TrackedActionBase
+  extends Identifiable, CrossChainAction, Timestamped {
+  status: string;
+}
+
+// === Status Types ===
+
+export type TransferStatus = 'in_progress' | 'complete';
+export type RebalanceIntentStatus =
+  | 'not_started'
+  | 'in_progress'
+  | 'complete'
+  | 'cancelled'
+  | 'failed';
+export type RebalanceActionStatus = 'in_progress' | 'complete' | 'failed';
+
+// === Execution Types ===
+
+/**
+ * Execution method for rebalancing:
+ * - `movable_collateral`: Uses MovableCollateralRouter.rebalance() on-chain
+ * - `inventory`: Uses external bridges + transferRemote
+ */
+export type ExecutionMethod = 'movable_collateral' | 'inventory';
+
+/**
+ * Type of rebalance action:
+ * - `rebalance_message`: Standard movable collateral rebalance (Hyperlane message)
+ * - `inventory_movement`: External bridge transfer (e.g., LiFi) to move inventory
+ * - `inventory_deposit`: transferRemote to deposit inventory as collateral
+ */
+export type ActionType =
+  | 'rebalance_message'
+  | 'inventory_movement'
+  | 'inventory_deposit';
+
+// === Entity Types ===
+
+export interface Transfer extends TrackedActionBase {
+  status: TransferStatus;
+  messageId: string;
+  sender: Address;
+  recipient: Address;
+}
+
+export interface RebalanceIntent extends TrackedActionBase {
+  status: RebalanceIntentStatus;
+  bridge?: Address; // Optional - bridge contract used (missing for recovered intents)
+  priority?: number; // Optional - missing for recovered intents
+  strategyType?: string; // Optional - missing for recovered intents
+  executionMethod?: ExecutionMethod; // Optional - defaults to movable_collateral
+  externalBridge?: ExternalBridgeType; // Optional - external bridge type (e.g., LiFi)
+}
+
+export interface RebalanceAction extends TrackedActionBase {
+  status: RebalanceActionStatus;
+  type: ActionType; // Type of action (rebalance_message, inventory_movement, inventory_deposit)
+  intentId: string; // Links to parent RebalanceIntent
+  messageId?: string; // Hyperlane message ID (required for rebalance_message, inventory_deposit)
+  txHash?: string; // Origin transaction hash
+  // Fields for inventory_movement (external bridge)
+  externalBridgeTransferId?: string; // External bridge transfer ID (e.g., LiFi transfer ID)
+  externalBridgeId?: ExternalBridgeType; // External bridge identifier (e.g., 'lifi')
+  lastBridgeStatus?: BridgeTransferStatus['status']; // Last observed external bridge status
+  nonPendingSince?: number; // Timestamp when bridge status first became non-pending
+}
+
+// === Type Aliases for Stores ===
+
+export type ITransferStore = IStore<Transfer, TransferStatus>;
+export type IRebalanceIntentStore = IStore<
+  RebalanceIntent,
+  RebalanceIntentStatus
+>;
+export type IRebalanceActionStore = IStore<
+  RebalanceAction,
+  RebalanceActionStatus
+>;
+
+// === Derived Types ===
+
+/**
+ * Represents an inventory intent that has been partially fulfilled
+ * and can continue execution. Values are derived from action states.
+ */
+export interface PartialInventoryIntent {
+  intent: RebalanceIntent;
+  /** Sum of complete inventory_deposit action amounts */
+  completedAmount: bigint;
+  /** Amount remaining to fulfill (0n when final deposit is fully in-flight). Formula: intent.amount - completedAmount - inflightAmount */
+  remaining: bigint;
+  /** True when intent has in_progress inventory_deposit actions (not safe to continue, but still active) */
+  hasInflightDeposit: boolean;
+}