@hyperlane-xyz/rebalancer 2.0.0 → 3.1.0

package/src/index.ts

@@ -20,6 +20,8 @@ export { Rebalancer } from './core/Rebalancer.js';
 // Configuration
 export { RebalancerConfig } from './config/RebalancerConfig.js';
 export {
+  DEFAULT_INTENT_TTL_MS,
+  DEFAULT_INTENT_TTL_S,
   getStrategyChainConfig,
   getStrategyChainNames,
   RebalancerBaseChainConfigSchema,
@@ -57,16 +59,23 @@ export { PriceGetter } from './metrics/PriceGetter.js';
 
 // Interfaces
 export type {
+  ExecutionResult,
+  IInventoryRebalancer,
+  IMovableCollateralRebalancer,
   IRebalancer,
+  InventoryExecutionResult,
+  MovableCollateralExecutionResult,
   PreparedTransaction,
-  RebalanceRoute,
-  RebalanceExecutionResult,
+  RebalancerType,
 } from './interfaces/IRebalancer.js';
 export type {
   IStrategy,
-  StrategyRoute,
-  RawBalances,
   InflightContext,
+  InventoryRoute,
+  MovableCollateralRoute,
+  RawBalances,
+  Route,
+  StrategyRoute,
 } from './interfaces/IStrategy.js';
 export type {
   ConfirmedBlockTag,
@@ -82,10 +91,16 @@ export {
 export type { IMetrics } from './interfaces/IMetrics.js';
 
 // Utils
-export { getBridgeConfig } from './utils/bridgeUtils.js';
+export {
+  getBridgeConfig,
+  isMovableCollateralConfig,
+  isInventoryConfig,
+} from './utils/bridgeUtils.js';
 export type {
   BridgeConfigWithOverride,
   BridgeConfig,
+  MovableCollateralBridgeConfig,
+  InventoryBridgeConfig,
 } from './utils/bridgeUtils.js';
 export { getRawBalances } from './utils/balanceUtils.js';
 export { isCollateralizedTokenEligibleForRebalancing } from './utils/tokenUtils.js';
@@ -102,6 +117,8 @@ export type {
   Transfer,
   RebalanceIntent,
   RebalanceAction,
+  ActionType,
+  PartialInventoryIntent,
 } from './tracking/types.js';
 
 // Factory

package/src/interfaces/IExternalBridge.ts

@@ -0,0 +1,115 @@
+import type { Logger } from 'pino';
+
+import type { ChainMap, ChainMetadata } from '@hyperlane-xyz/sdk';
+
+import type { ExternalBridgeType } from '../config/types.js';
+
+/**
+ * Configuration for an external bridge.
+ */
+export interface ExternalBridgeConfig {
+  integrator: string; // Required: dApp/company name for bridge integration
+  apiKey?: string; // Optional: API key for higher rate limits
+  defaultSlippage?: number; // Default slippage tolerance (e.g., 0.005 = 0.5%)
+  chainMetadata?: ChainMap<ChainMetadata>; // Optional: chain metadata for resolving RPC URLs by chainId
+}
+
+/**
+ * Parameters for requesting a bridge quote.
+ * Either fromAmount OR toAmount must be provided (mutually exclusive).
+ * - fromAmount: "I'm sending X, what do I get?" (standard quote)
+ * - toAmount: "I want X on destination, how much do I send?" (reverse quote)
+ */
+export interface BridgeQuoteParams {
+  fromChain: number; // Source chain ID
+  toChain: number; // Destination chain ID
+  fromToken: string; // Source token address
+  toToken: string; // Destination token address
+  fromAmount?: bigint; // Amount to send (in token decimals) - use for "I'm sending X"
+  toAmount?: bigint; // Amount to receive (in token decimals) - use for "I want X"
+  fromAddress: string; // Sender address
+  toAddress?: string; // Recipient address (defaults to fromAddress)
+  slippage?: number; // Slippage tolerance (overrides default)
+}
+
+/**
+ * Quote response from a bridge.
+ */
+export interface BridgeQuote {
+  id: string; // Unique quote identifier
+  tool: string; // Bridge/DEX tool used (e.g., 'stargate', 'across')
+  fromAmount: bigint; // Amount being sent (input required)
+  toAmount: bigint; // Expected amount to receive
+  toAmountMin: bigint; // Minimum amount to receive (after slippage)
+  executionDuration: number; // Estimated execution time in seconds
+  gasCosts: bigint; // Sum of gas costs for the bridge operation
+  feeCosts: bigint; // Sum of non-included fee costs (protocol fees, etc.)
+  route: unknown; // Bridge-specific route data for execution
+}
+
+/**
+ * Result of executing a bridge transfer.
+ */
+export interface BridgeTransferResult {
+  txHash: string; // Origin chain transaction hash
+  fromChain: number; // Source chain ID
+  toChain: number; // Destination chain ID
+  transferId?: string; // Bridge-specific transfer identifier
+}
+
+/**
+ * Status of a bridge transfer.
+ */
+export type BridgeTransferStatus =
+  | { status: 'pending'; substatus?: string }
+  | { status: 'complete'; receivingTxHash: string; receivedAmount: bigint }
+  | { status: 'failed'; error?: string }
+  | { status: 'not_found' };
+
+/**
+ * Interface for external bridge implementations (e.g., LiFi, Socket).
+ *
+ * External bridges are used for inventory rebalancing when chains don't support
+ * MovableCollateralRouter. The flow is:
+ * 1. quote() - Get a quote for bridging tokens
+ * 2. execute() - Execute the bridge transfer
+ * 3. getStatus() - Poll for transfer completion
+ */
+export interface IExternalBridge {
+  readonly externalBridgeId: string;
+  readonly logger: Logger;
+
+  getNativeTokenAddress?(): string;
+
+  quote(params: BridgeQuoteParams): Promise<BridgeQuote>;
+
+  /**
+   * Execute a bridge transfer using a previously obtained quote.
+   * @param quote - Quote obtained from quote()
+   * @param privateKey - Private key hex string (0x-prefixed) for signing the transaction
+   */
+  execute(
+    quote: BridgeQuote,
+    privateKey: string,
+  ): Promise<BridgeTransferResult>;
+
+  /**
+   * Get the status of a bridge transfer.
+   * @param txHash - Origin chain transaction hash
+   * @param fromChain - Source chain ID
+   * @param toChain - Destination chain ID
+   */
+  getStatus(
+    txHash: string,
+    fromChain: number,
+    toChain: number,
+  ): Promise<BridgeTransferStatus>;
+}
+
+/**
+ * Registry mapping external bridge types to their implementations.
+ */
+export type ExternalBridgeRegistry = Record<
+  ExternalBridgeType,
+  IExternalBridge
+>;

package/src/interfaces/IMonitor.ts

@@ -33,6 +33,7 @@ export type MonitorEvent = {
     bridgedSupply?: bigint;
   }[];
   confirmedBlockTags: ConfirmedBlockTags;
+  inventoryBalances?: ChainMap<bigint>;
 };
 
 /**

package/src/interfaces/IRebalancer.ts

@@ -3,39 +3,55 @@ import {
   type TokenAmount,
 } from '@hyperlane-xyz/sdk';
 
-import type { StrategyRoute } from './IStrategy.js';
-
-/**
- * RebalanceRoute extends StrategyRoute with a required intentId for tracking.
- * The intentId is assigned by RebalancerService before execution and links
- * to the corresponding RebalanceIntent in the tracking system.
- */
-export type RebalanceRoute = StrategyRoute & {
-  /** Links to the RebalanceIntent that this route fulfills */
-  intentId: string;
-};
+import {
+  type InventoryRoute,
+  type MovableCollateralRoute,
+  type Route,
+} from './IStrategy.js';
+
+export type RebalancerType = 'movableCollateral' | 'inventory';
+
+export interface ExecutionResult<R extends Route = Route> {
+  route: R;
+  success: boolean;
+  error?: string;
+  // messageId?: string;
+  txHash?: string;
+  // amountSent?: bigint;
+  reason?: string;
+}
+
+export interface MovableCollateralExecutionResult extends ExecutionResult<MovableCollateralRoute> {
+  messageId: string;
+}
+
+export interface InventoryExecutionResult extends ExecutionResult<InventoryRoute> {
+  messageId?: string;
+  amountSent?: bigint;
+}
+
+export interface IRebalancer<
+  R extends Route = Route,
+  E extends ExecutionResult<R> = ExecutionResult<R>,
+> {
+  readonly rebalancerType: RebalancerType;
+  rebalance(routes: R[]): Promise<E[]>;
+}
+
+export type IMovableCollateralRebalancer = IRebalancer<
+  MovableCollateralRoute,
+  MovableCollateralExecutionResult
+>;
+
+export type IInventoryRebalancer = IRebalancer<
+  InventoryRoute,
+  InventoryExecutionResult
+>;
 
 export type PreparedTransaction = {
   populatedTx: Awaited<
     ReturnType<EvmMovableCollateralAdapter['populateRebalanceTx']>
   >;
-  route: RebalanceRoute;
+  route: MovableCollateralRoute & { intentId: string };
   originTokenAmount: TokenAmount;
 };
-
-export type RebalanceMetrics = {
-  route: RebalanceRoute;
-  originTokenAmount: TokenAmount;
-};
-
-export type RebalanceExecutionResult = {
-  route: RebalanceRoute;
-  success: boolean;
-  messageId?: string;
-  txHash?: string;
-  error?: string;
-};
-
-export interface IRebalancer {
-  rebalance(routes: RebalanceRoute[]): Promise<RebalanceExecutionResult[]>;
-}

package/src/interfaces/IStrategy.ts

@@ -1,26 +1,73 @@
 import { type ChainMap, type ChainName } from '@hyperlane-xyz/sdk';
 import type { Address } from '@hyperlane-xyz/utils';
 
+import { ExternalBridgeType } from '../config/types.js';
+import { ExecutionMethod } from '../tracking/types.js';
+
 export type RawBalances = ChainMap<bigint>;
 
 export interface Route {
   origin: ChainName;
   destination: ChainName;
   amount: bigint;
+  /** Execution method used for this rebalance */
+  executionMethod?: ExecutionMethod;
+}
+
+export interface RouteWithContext extends Route {
+  /** For inventory intents: sum of complete inventory_deposit actions (message delivered) */
+  deliveredAmount?: bigint;
+  /** For inventory intents: sum of in_progress inventory_deposit actions (tx confirmed, message pending) */
+  awaitingDeliveryAmount?: bigint;
 }
 
-export interface StrategyRoute extends Route {
+/**
+ * Route using movable collateral execution (on-chain rebalance via bridge)
+ */
+export interface MovableCollateralRoute extends Route {
+  executionType: 'movableCollateral';
   bridge: Address;
 }
 
+/**
+ * Route using inventory execution (external bridge + transferRemote)
+ */
+export interface InventoryRoute extends Route {
+  executionType: 'inventory';
+  externalBridge: ExternalBridgeType;
+}
+
+/**
+ * Discriminated union of route types by executionType
+ */
+export type StrategyRoute = MovableCollateralRoute | InventoryRoute;
+
+/**
+ * Type guard to check if a route is a MovableCollateralRoute
+ */
+export function isMovableCollateralRoute(
+  route: StrategyRoute,
+): route is MovableCollateralRoute {
+  return route.executionType === 'movableCollateral';
+}
+
+/**
+ * Type guard to check if a route is an InventoryRoute
+ */
+export function isInventoryRoute(
+  route: StrategyRoute,
+): route is InventoryRoute {
+  return route.executionType === 'inventory';
+}
+
 export type InflightContext = {
   /**
    * In-flight rebalances from ActionTracker.
    * Uses Route[] because recovered intents (from Explorer startup recovery)
    * don't have bridge information. Some routes may have bridge at runtime.
    */
-  pendingRebalances: Route[];
-  pendingTransfers: Route[];
+  pendingRebalances: RouteWithContext[];
+  pendingTransfers: RouteWithContext[];
   /** Routes from earlier strategies - always have bridge */
   proposedRebalances?: StrategyRoute[];
 };

package/src/metrics/PriceGetter.ts

@@ -52,7 +52,7 @@ export class PriceGetter extends CoinGeckoTokenPriceGetter {
     const coinGeckoId = token.coinGeckoId;
 
     if (!coinGeckoId) {
-      this.logger.warn(
+      this.logger.debug(
         {
           tokenSymbol: token.symbol,
           chain: token.chainName,

package/src/monitor/Monitor.ts

@@ -1,7 +1,12 @@
 import { type Logger } from 'pino';
 
-import { type Token, type WarpCore } from '@hyperlane-xyz/sdk';
-import { sleep } from '@hyperlane-xyz/utils';
+import {
+  type ChainMap,
+  type ChainName,
+  type Token,
+  type WarpCore,
+} from '@hyperlane-xyz/sdk';
+import { Address, sleep } from '@hyperlane-xyz/utils';
 
 import {
   type ConfirmedBlockTag,
@@ -14,6 +19,14 @@ import {
 } from '../interfaces/IMonitor.js';
 import { getConfirmedBlockTag } from '../utils/blockTag.js';
 
+/**
+ * Configuration for the Monitor's inventory tracking.
+ */
+export interface InventoryMonitorConfig {
+  inventoryAddress: Address;
+  chains: ChainName[];
+}
+
 /**
  * Simple monitor implementation that polls warp route collateral balances and emits them as MonitorEvent.
  * Awaits the TokenInfo handler before starting the next cycle to prevent race conditions.
@@ -33,6 +46,7 @@ export class Monitor implements IMonitor {
     private readonly checkFrequency: number,
     private readonly warpCore: WarpCore,
     private readonly logger: Logger,
+    private readonly inventoryConfig?: InventoryMonitorConfig,
   ) {}
 
   private async computeConfirmedBlockTags(): Promise<ConfirmedBlockTags> {
@@ -123,6 +137,24 @@ export class Monitor implements IMonitor {
             });
           }
 
+          const inventoryBalances = await this.fetchInventoryBalances();
+          if (Object.keys(inventoryBalances).length > 0) {
+            event.inventoryBalances = inventoryBalances;
+            this.logger.info(
+              {
+                chainsMonitored: Object.keys(inventoryBalances).length,
+                balances: Object.entries(inventoryBalances).map(
+                  ([chain, balance]) => ({
+                    chain,
+                    balance: balance.toString(),
+                    balanceEth: (Number(balance) / 1e18).toFixed(6),
+                  }),
+                ),
+              },
+              'Inventory balances fetched',
+            );
+          }
+
           if (this.tokenInfoHandler) {
             await this.tokenInfoHandler(event);
           }
@@ -218,6 +250,53 @@ export class Monitor implements IMonitor {
     return bridgedSupply;
   }
 
+  private async fetchInventoryBalances(): Promise<ChainMap<bigint>> {
+    if (!this.inventoryConfig) return {};
+
+    const balances: ChainMap<bigint> = {};
+
+    const readPromises = this.inventoryConfig.chains.map(async (chainName) => {
+      const token = this.warpCore.tokens.find((t) => t.chainName === chainName);
+      if (!token) {
+        this.logger.warn(
+          { chain: chainName },
+          'No token found for inventory chain',
+        );
+        return { chainName, balance: 0n };
+      }
+
+      try {
+        const adapter = token.getAdapter(this.warpCore.multiProvider);
+        const balance = await adapter.getBalance(
+          this.inventoryConfig!.inventoryAddress,
+        );
+        this.logger.debug(
+          {
+            chain: chainName,
+            token: token.addressOrDenom,
+            balance: balance.toString(),
+          },
+          'Read inventory balance',
+        );
+        return { chainName, balance };
+      } catch (error) {
+        this.logger.error(
+          { chain: chainName, error: (error as Error).message },
+          'Failed to read inventory balance',
+        );
+        return { chainName, balance: 0n };
+      }
+    });
+
+    const results = await Promise.all(readPromises);
+
+    for (const { chainName, balance } of results) {
+      balances[chainName] = balance;
+    }
+
+    return balances;
+  }
+
   stop(): Promise<void> {
     if (!this.isMonitorRunning) return Promise.resolve();
 

package/src/service.ts

@@ -8,7 +8,9 @@
  *
  * Environment Variables:
  * - REBALANCER_CONFIG_FILE: Path to the rebalancer configuration YAML file (required)
- * - HYP_KEY: Private key for signing transactions (required)
+ * - HYP_REBALANCER_KEY: Private key for movable collateral rebalancing operations (preferred)
+ * - HYP_KEY: Fallback private key for HYP_REBALANCER_KEY (optional)
+ * - HYP_INVENTORY_KEY: Private key for inventory operations - LiFi bridges and transferRemote (optional)
  * - COINGECKO_API_KEY: API key for CoinGecko price fetching (optional, for metrics)
  * - CHECK_FREQUENCY: Balance check frequency in ms (default: 60000)
  * - WITH_METRICS: Enable Prometheus metrics (default: "true")
@@ -19,13 +21,13 @@
  *
  * Usage:
  *   node dist/service.js
- *   REBALANCER_CONFIG_FILE=/config/rebalancer.yaml HYP_KEY=0x... node dist/service.js
+ *   REBALANCER_CONFIG_FILE=/config/rebalancer.yaml HYP_REBALANCER_KEY=0x... HYP_INVENTORY_KEY=0x... node dist/service.js
  */
 import { Wallet } from 'ethers';
 
 import { DEFAULT_GITHUB_REGISTRY } from '@hyperlane-xyz/registry';
 import { getRegistry } from '@hyperlane-xyz/registry/fs';
-import { MultiProtocolProvider, MultiProvider } from '@hyperlane-xyz/sdk';
+import { MultiProvider } from '@hyperlane-xyz/sdk';
 import {
   applyRpcUrlOverridesFromEnv,
   createServiceLogger,
@@ -44,12 +46,18 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
-  const privateKey = process.env.HYP_KEY;
-  if (!privateKey) {
-    rootLogger.error('HYP_KEY environment variable is required');
+  const rebalancerPrivateKey =
+    process.env.HYP_REBALANCER_KEY ?? process.env.HYP_KEY;
+  if (!rebalancerPrivateKey) {
+    rootLogger.error(
+      'HYP_REBALANCER_KEY (or HYP_KEY) environment variable is required',
+    );
     process.exit(1);
   }
 
+  // Optional: inventory key for inventory-based operations (LiFi bridges, transferRemote)
+  const inventoryPrivateKey = process.env.HYP_INVENTORY_KEY;
+
   // Parse optional environment variables
   let checkFrequency = 60_000;
   if (process.env.CHECK_FREQUENCY) {
@@ -106,27 +114,60 @@ async function main(): Promise<void> {
     );
 
     // Apply RPC URL overrides from environment variables
-    const overriddenChains = applyRpcUrlOverridesFromEnv(chainMetadata);
-    if (overriddenChains.length > 0) {
+    applyRpcUrlOverridesFromEnv(chainMetadata);
+
+    // Create MultiProvider with signer
+    const multiProvider = new MultiProvider(chainMetadata);
+    const rebalancerSigner = new Wallet(rebalancerPrivateKey);
+    multiProvider.setSharedSigner(rebalancerSigner);
+    logger.info(
+      { rebalancerAddress: rebalancerSigner.address },
+      '✅ Initialized MultiProvider with rebalancer signer',
+    );
+
+    // Create inventory MultiProvider if inventory key is provided
+    let inventoryMultiProvider: MultiProvider | undefined;
+    if (inventoryPrivateKey) {
+      inventoryMultiProvider = new MultiProvider(chainMetadata, {
+        providers: multiProvider.providers,
+      });
+      const inventorySigner = new Wallet(inventoryPrivateKey);
+      inventoryMultiProvider.setSharedSigner(inventorySigner);
+
+      // Validate against config.inventorySigner if present
+      const inventoryAddress = inventorySigner.address;
+      if (
+        rebalancerConfig.inventorySigner &&
+        rebalancerConfig.inventorySigner.toLowerCase() !==
+          inventoryAddress.toLowerCase()
+      ) {
+        throw new Error(
+          `inventorySigner mismatch: config has ${rebalancerConfig.inventorySigner} but HYP_INVENTORY_KEY derives to ${inventoryAddress}`,
+        );
+      }
       logger.info(
-        { chains: overriddenChains, count: overriddenChains.length },
-        'Applied RPC overrides from environment variables',
+        { inventoryAddress },
+        '✅ Initialized inventory MultiProvider',
       );
     }
 
-    // Create MultiProvider with signer
-    const multiProvider = new MultiProvider(chainMetadata);
-    const signer = new Wallet(privateKey);
-    multiProvider.setSharedSigner(signer);
-    logger.info('✅ Initialized MultiProvider with signer');
+    // Fail fast if config references inventorySigner but no HYP_INVENTORY_KEY is provided
+    // Without the matching key, inventory operations would silently use the wrong signer
+    if (rebalancerConfig.inventorySigner && !inventoryPrivateKey) {
+      logger.error(
+        { inventorySigner: rebalancerConfig.inventorySigner },
+        'Config specifies inventorySigner but HYP_INVENTORY_KEY is not set. Provide the key or remove inventorySigner from config.',
+      );
+      process.exit(1);
+    }
 
-    // Create MultiProtocolProvider
-    const multiProtocolProvider = new MultiProtocolProvider(chainMetadata);
-    logger.info('✅ Initialized MultiProtocolProvider');
+    // MultiProtocolProvider will be derived from multiProvider in factory
+    const multiProtocolProvider = undefined;
 
     // Create the rebalancer service
     const service = new RebalancerService(
       multiProvider,
+      inventoryMultiProvider,
       multiProtocolProvider,
       registry,
       rebalancerConfig,