@hyperlane-xyz/rebalancer 2.0.0 → 3.1.0

package/src/tracking/InflightContextAdapter.ts

@@ -1,6 +1,9 @@
 import type { MultiProvider } from '@hyperlane-xyz/sdk';
 
-import type { InflightContext } from '../interfaces/IStrategy.js';
+import type {
+  InflightContext,
+  RouteWithContext,
+} from '../interfaces/IStrategy.js';
 
 import type { IActionTracker } from './IActionTracker.js';
 
@@ -22,14 +25,44 @@ export class InflightContextAdapter {
     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 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),

package/src/tracking/types.ts

@@ -1,5 +1,7 @@
 import type { Address, Domain } from '@hyperlane-xyz/utils';
 
+import type { ExternalBridgeType } from '../config/types.js';
+
 import type { IStore } from './store/IStore.js';
 
 // === Base Interfaces ===
@@ -35,6 +37,26 @@ export type RebalanceIntentStatus =
   | '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 {
@@ -46,17 +68,22 @@ export interface Transfer extends TrackedActionBase {
 
 export interface RebalanceIntent extends TrackedActionBase {
   status: RebalanceIntentStatus;
-  fulfilledAmount: bigint;
   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
+  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')
 }
 
 // === Type Aliases for Stores ===
@@ -70,3 +97,19 @@ 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;
+}

package/src/utils/ExplorerClient.ts

@@ -9,14 +9,15 @@ export type InflightRebalanceQueryParams = {
 
 export type UserTransferQueryParams = {
   routersByDomain: Record<number, string>; // Domain ID → router address (derive routers and domains from this)
-  excludeTxSender: string; // Rebalancer address to exclude
+  excludeTxSenders: string[]; // Addresses to exclude (rebalancer + inventory signer)
   limit?: number;
 };
 
 export type RebalanceActionQueryParams = {
   bridges: string[]; // Bridge contract addresses
   routersByDomain: Record<number, string>; // Domain ID → router address (derive routers and domains from this)
-  rebalancerAddress: string; // Only include rebalancer's txs
+  rebalancerAddress: string; // Include rebalancer's txs
+  inventorySignerAddress?: string; // Optional: also include inventory signer's txs (for inventory_deposit actions)
   limit?: number;
 };
 
@@ -31,6 +32,7 @@ export type ExplorerMessage = {
   origin_tx_recipient: string;
   is_delivered: boolean;
   message_body: string;
+  send_occurred_at: string | null;
 };
 
 export interface IExplorerClient {
@@ -71,6 +73,7 @@ export class ExplorerClient implements IExplorerClient {
       origin_tx_recipient: normalizeHex(msg.origin_tx_recipient),
       is_delivered: msg.is_delivered,
       message_body: normalizeHex(msg.message_body),
+      send_occurred_at: msg.send_occurred_at ?? null,
     };
   }
 
@@ -191,7 +194,7 @@ export class ExplorerClient implements IExplorerClient {
     params: UserTransferQueryParams,
     logger: Logger,
   ): Promise<ExplorerMessage[]> {
-    const { routersByDomain, excludeTxSender, limit = 100 } = params;
+    const { routersByDomain, excludeTxSenders, limit = 100 } = params;
 
     // Derive routers and domains from routersByDomain
     const routers = Object.values(routersByDomain);
@@ -202,7 +205,7 @@ export class ExplorerClient implements IExplorerClient {
       recipients: routers.map((a) => this.toBytea(a)),
       originDomains: domains,
       destDomains: domains,
-      excludeTxSender: this.toBytea(excludeTxSender),
+      excludeTxSenders: excludeTxSenders.map((a) => this.toBytea(a)),
       limit,
     };
 
@@ -214,7 +217,7 @@ export class ExplorerClient implements IExplorerClient {
         $recipients: [bytea!],
         $originDomains: [Int!],
         $destDomains: [Int!],
-        $excludeTxSender: bytea!,
+        $excludeTxSenders: [bytea!],
         $limit: Int = 100
       ) {
         message_view(
@@ -225,7 +228,7 @@ export class ExplorerClient implements IExplorerClient {
               { recipient: { _in: $recipients } },
               { origin_domain_id: { _in: $originDomains } },
               { destination_domain_id: { _in: $destDomains } },
-              { origin_tx_sender: { _neq: $excludeTxSender } }
+              { origin_tx_sender: { _nin: $excludeTxSenders } }
             ]
           }
           order_by: { origin_tx_id: desc }
@@ -241,6 +244,7 @@ export class ExplorerClient implements IExplorerClient {
           origin_tx_recipient
           is_delivered
           message_body
+          send_occurred_at
         }
       }`;
 
@@ -284,19 +288,31 @@ export class ExplorerClient implements IExplorerClient {
     params: RebalanceActionQueryParams,
     logger: Logger,
   ): Promise<ExplorerMessage[]> {
-    const { bridges, routersByDomain, rebalancerAddress, limit = 100 } = params;
+    const {
+      bridges,
+      routersByDomain,
+      rebalancerAddress,
+      inventorySignerAddress,
+      limit = 100,
+    } = params;
 
     // Derive routers and domains from routersByDomain
     const routers = Object.values(routersByDomain);
     const domains = Object.keys(routersByDomain).map(Number);
 
+    // Build list of tx senders to include (rebalancer + optional inventory signer)
+    const txSenders = [this.toBytea(rebalancerAddress)];
+    if (inventorySignerAddress) {
+      txSenders.push(this.toBytea(inventorySignerAddress));
+    }
+
     const variables = {
       senders: bridges.map((a) => this.toBytea(a)),
       recipients: bridges.map((a) => this.toBytea(a)),
       originTxRecipients: routers.map((a) => this.toBytea(a)),
       originDomains: domains,
       destDomains: domains,
-      txSender: this.toBytea(rebalancerAddress),
+      txSenders,
       limit,
     };
 
@@ -309,7 +325,7 @@ export class ExplorerClient implements IExplorerClient {
         $originTxRecipients: [bytea!],
         $originDomains: [Int!],
         $destDomains: [Int!],
-        $txSender: bytea!,
+        $txSenders: [bytea!],
         $limit: Int = 100
       ) {
         message_view(
@@ -321,7 +337,7 @@ export class ExplorerClient implements IExplorerClient {
               { origin_tx_recipient: { _in: $originTxRecipients } },
               { origin_domain_id: { _in: $originDomains } },
               { destination_domain_id: { _in: $destDomains } },
-              { origin_tx_sender: { _eq: $txSender } }
+              { origin_tx_sender: { _in: $txSenders } }
             ]
           }
           order_by: { origin_tx_id: desc }
@@ -337,6 +353,7 @@ export class ExplorerClient implements IExplorerClient {
           origin_tx_recipient
           is_delivered
           message_body
+          send_occurred_at
         }
       }`;
 

package/src/utils/bridgeUtils.test.ts

@@ -11,10 +11,12 @@ describe('bridgeConfig', () => {
   it('should return the base bridge config when no overrides exist', () => {
     const bridges: ChainMap<BridgeConfigWithOverride> = {
       chain1: {
+        executionType: 'movableCollateral',
         bridge: '0x1234567890123456789012345678901234567890',
         bridgeMinAcceptedAmount: 1000,
       },
       chain2: {
+        executionType: 'movableCollateral',
         bridge: '0x0987654321098765432109876543210987654321',
         bridgeMinAcceptedAmount: 2000,
       },
@@ -23,6 +25,7 @@ describe('bridgeConfig', () => {
     const result = getBridgeConfig(bridges, 'chain1', 'chain2');
 
     expect(result).to.deep.equal({
+      executionType: 'movableCollateral',
       bridge: '0x1234567890123456789012345678901234567890',
       bridgeMinAcceptedAmount: 1000,
     });
@@ -31,6 +34,7 @@ describe('bridgeConfig', () => {
   it('should merge base config with overrides when they exist', () => {
     const bridges: ChainMap<BridgeConfigWithOverride> = {
       chain1: {
+        executionType: 'movableCollateral',
         bridge: '0x1234567890123456789012345678901234567890',
         bridgeMinAcceptedAmount: 1000,
         override: {
@@ -40,6 +44,7 @@ describe('bridgeConfig', () => {
         },
       },
       chain2: {
+        executionType: 'movableCollateral',
         bridge: '0x0987654321098765432109876543210987654321',
         bridgeMinAcceptedAmount: 2000,
       },
@@ -48,6 +53,7 @@ describe('bridgeConfig', () => {
     const result = getBridgeConfig(bridges, 'chain1', 'chain2');
 
     expect(result).to.deep.equal({
+      executionType: 'movableCollateral',
       bridge: '0x1234567890123456789012345678901234567890',
       bridgeMinAcceptedAmount: 5000,
     });
@@ -56,6 +62,7 @@ describe('bridgeConfig', () => {
   it('should handle overrides that change the bridge address', () => {
     const bridges: ChainMap<BridgeConfigWithOverride> = {
       chain1: {
+        executionType: 'movableCollateral',
         bridge: '0x1234567890123456789012345678901234567890',
         bridgeMinAcceptedAmount: 1000,
         override: {
@@ -65,6 +72,7 @@ describe('bridgeConfig', () => {
         },
       },
       chain2: {
+        executionType: 'movableCollateral',
         bridge: '0x0987654321098765432109876543210987654321',
         bridgeMinAcceptedAmount: 2000,
       },
@@ -73,6 +81,7 @@ describe('bridgeConfig', () => {
     const result = getBridgeConfig(bridges, 'chain1', 'chain2');
 
     expect(result).to.deep.equal({
+      executionType: 'movableCollateral',
       bridge: '0xABCDEF0123456789ABCDEF0123456789ABCDEF01',
       bridgeMinAcceptedAmount: 1000,
     });

package/src/utils/bridgeUtils.ts

@@ -1,12 +1,41 @@
 import type { ChainMap, ChainName } from '@hyperlane-xyz/sdk';
+import type { Address } from '@hyperlane-xyz/utils';
 
-export type BridgeConfigWithOverride = BridgeConfig & {
-  override?: ChainMap<Partial<BridgeConfig>>;
+import type { ExternalBridgeType } from '../config/types.js';
+import type { StrategyRoute } from '../interfaces/IStrategy.js';
+
+type BaseBridgeConfig = {
+  bridgeMinAcceptedAmount?: string | number;
+};
+
+export type MovableCollateralBridgeConfig = BaseBridgeConfig & {
+  executionType: 'movableCollateral';
+  bridge: Address;
 };
 
-export type BridgeConfig = {
-  bridge: string;
-  bridgeMinAcceptedAmount: string | number;
+export type InventoryBridgeConfig = BaseBridgeConfig & {
+  executionType: 'inventory';
+  externalBridge: ExternalBridgeType;
+};
+
+export type BridgeConfig =
+  | MovableCollateralBridgeConfig
+  | InventoryBridgeConfig;
+
+export function isMovableCollateralConfig(
+  config: BridgeConfig,
+): config is MovableCollateralBridgeConfig {
+  return config.executionType === 'movableCollateral';
+}
+
+export function isInventoryConfig(
+  config: BridgeConfig,
+): config is InventoryBridgeConfig {
+  return config.executionType === 'inventory';
+}
+
+export type BridgeConfigWithOverride = BridgeConfig & {
+  override?: ChainMap<Partial<BridgeConfig>>;
 };
 
 /**
@@ -28,5 +57,45 @@ export function getBridgeConfig(
   const { override: _, ...baseConfig } = fromConfig;
 
   // Return a new object with the base config and any overrides
-  return { ...baseConfig, ...routeSpecificOverrides };
+  return { ...baseConfig, ...routeSpecificOverrides } as BridgeConfig;
+}
+
+/**
+ * Creates a StrategyRoute from a BridgeConfig with exhaustive type checking
+ * @param bridgeConfig The bridge configuration
+ * @param origin The origin chain
+ * @param destination The destination chain
+ * @param amount The amount to transfer
+ * @returns A StrategyRoute with the appropriate execution type
+ */
+export function createStrategyRoute(
+  bridgeConfig: BridgeConfig,
+  origin: ChainName,
+  destination: ChainName,
+  amount: bigint,
+): StrategyRoute {
+  switch (bridgeConfig.executionType) {
+    case 'inventory':
+      return {
+        origin,
+        destination,
+        amount,
+        executionType: 'inventory',
+        externalBridge: bridgeConfig.externalBridge,
+      };
+    case 'movableCollateral':
+      return {
+        origin,
+        destination,
+        amount,
+        executionType: 'movableCollateral',
+        bridge: bridgeConfig.bridge,
+      };
+    default: {
+      const _exhaustive: never = bridgeConfig;
+      throw new Error(
+        `Unknown execution type: ${(_exhaustive as BridgeConfig).executionType}`,
+      );
+    }
+  }
 }