@humanode-hyperlane/rebalancer 0.0.0-stage → 27.2.2-humanode.1

package/src/index.ts

@@ -0,0 +1,125 @@
+/**
+ * @humanode-hyperlane/rebalancer
+ *
+ * Hyperlane Warp Route Collateral Rebalancer
+ *
+ * This package provides functionality for automatically rebalancing collateral
+ * across Hyperlane warp routes to maintain optimal token distribution.
+ */
+
+// Core service
+export { RebalancerService } from './core/RebalancerService.js';
+export type {
+  RebalancerServiceConfig,
+  ManualRebalanceRequest,
+} from './core/RebalancerService.js';
+
+// Core rebalancing logic
+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,
+  RebalancerConfigSchema,
+  RebalancerMinAmountConfigSchema,
+  RebalancerMinAmountType,
+  RebalancerStrategyOptions,
+  RebalancerStrategySchema,
+  RebalancerWeightedChainConfigSchema,
+  StrategyConfigSchema,
+} from './config/types.js';
+export type {
+  MinAmountStrategyConfig,
+  RebalancerConfig as RebalancerConfigType,
+  RebalancerConfigFileInput,
+  RebalancerMinAmountChainConfig,
+  RebalancerWeightedChainConfig,
+  StrategyConfig,
+  WeightedStrategyConfig,
+} from './config/types.js';
+
+// Strategy
+export { BaseStrategy } from './strategy/BaseStrategy.js';
+export { CompositeStrategy } from './strategy/CompositeStrategy.js';
+export { WeightedStrategy } from './strategy/WeightedStrategy.js';
+export { MinAmountStrategy } from './strategy/MinAmountStrategy.js';
+export { StrategyFactory } from './strategy/StrategyFactory.js';
+
+// Monitor
+export { Monitor } from './monitor/Monitor.js';
+
+// Metrics
+export { Metrics } from './metrics/Metrics.js';
+export { PriceGetter } from './metrics/PriceGetter.js';
+
+// Interfaces
+export type {
+  ExecutionResult,
+  IInventoryRebalancer,
+  IMovableCollateralRebalancer,
+  IRebalancer,
+  InventoryExecutionResult,
+  MovableCollateralExecutionResult,
+  PreparedTransaction,
+  RebalancerType,
+} from './interfaces/IRebalancer.js';
+export type {
+  IStrategy,
+  InflightContext,
+  InventoryRoute,
+  MovableCollateralRoute,
+  RawBalances,
+  Route,
+  StrategyRoute,
+} from './interfaces/IStrategy.js';
+export type {
+  ConfirmedBlockTag,
+  ConfirmedBlockTags,
+  IMonitor,
+} from './interfaces/IMonitor.js';
+export {
+  MonitorEventType,
+  MonitorEvent,
+  MonitorPollingError,
+  MonitorStartError,
+} from './interfaces/IMonitor.js';
+export type { IMetrics } from './interfaces/IMetrics.js';
+
+// Utils
+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';
+export { ExplorerClient } from './utils/ExplorerClient.js';
+
+// Tracking
+export { InflightContextAdapter } from './tracking/InflightContextAdapter.js';
+export type {
+  IActionTracker,
+  CreateRebalanceIntentParams,
+  CreateRebalanceActionParams,
+} from './tracking/IActionTracker.js';
+export type {
+  Transfer,
+  RebalanceIntent,
+  RebalanceAction,
+  ActionType,
+  PartialInventoryIntent,
+} from './tracking/types.js';
+
+// Factory
+export { RebalancerContextFactory } from './factories/RebalancerContextFactory.js';

package/src/interfaces/IExternalBridge.ts

@@ -0,0 +1,117 @@
+import type { Logger } from 'pino';
+
+import type { ChainMap, ChainMetadata } from '@humanode-hyperlane/sdk';
+import { ProtocolType } from '@humanode-hyperlane/utils';
+
+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<R = unknown> {
+  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: R; // Bridge-specific route data for execution
+  requestParams: BridgeQuoteParams; // Original request parameters
+}
+
+/**
+ * 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 privateKeys - Private keys keyed by ProtocolType (e.g., { [ProtocolType.Ethereum]: '0x...' })
+   */
+  execute(
+    quote: BridgeQuote,
+    privateKeys: Partial<Record<ProtocolType, 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/IMetrics.ts

@@ -0,0 +1,5 @@
+import { type MonitorEvent } from './IMonitor.js';
+
+export interface IMetrics {
+  processToken(tokenInfo: MonitorEvent['tokensInfo'][number]): Promise<void>;
+}

package/src/interfaces/IMonitor.ts

@@ -0,0 +1,71 @@
+import {
+  type ChainMap,
+  EthJsonRpcBlockParameterTag,
+  type Token,
+} from '@humanode-hyperlane/sdk';
+
+import { WrappedError } from '../utils/errors.js';
+
+export class MonitorStartError extends WrappedError {
+  name = 'MonitorStartError';
+}
+
+export class MonitorPollingError extends WrappedError {
+  name = 'MonitorPollingError';
+}
+
+export enum MonitorEventType {
+  TokenInfo = 'TokenInfo',
+  Error = 'Error',
+  Start = 'Start',
+}
+
+export type ConfirmedBlockTag =
+  | number
+  | EthJsonRpcBlockParameterTag
+  | undefined;
+
+export type ConfirmedBlockTags = ChainMap<ConfirmedBlockTag>;
+
+export type MonitorEvent = {
+  tokensInfo: {
+    token: Token;
+    bridgedSupply?: bigint;
+  }[];
+  confirmedBlockTags: ConfirmedBlockTags;
+  inventoryBalances?: ChainMap<bigint>;
+};
+
+/**
+ * Interface for a monitoring service that tracks token information across different chains.
+ */
+export interface IMonitor {
+  /**
+   * Allows subscribers to listen to hyperlane's tokens info.
+   * Handler can be async - Monitor will await it before starting next cycle.
+   */
+  on(
+    eventName: MonitorEventType.TokenInfo,
+    fn: (event: MonitorEvent) => void | Promise<void>,
+  ): this;
+
+  /**
+   * Allows subscribers to listen to error events.
+   */
+  on(eventName: MonitorEventType.Error, fn: (event: Error) => void): this;
+
+  /**
+   * Allows subscribers to listen to start events.
+   */
+  on(eventName: MonitorEventType.Start, fn: () => void): this;
+
+  /**
+   * Starts the monitoring long-running process.
+   */
+  start(): Promise<void>;
+
+  /**
+   * Stops the monitoring long-running process.
+   */
+  stop(): void;
+}

package/src/interfaces/IRebalancer.ts

@@ -0,0 +1,57 @@
+import {
+  type EvmMovableCollateralAdapter,
+  type TokenAmount,
+} from '@humanode-hyperlane/sdk';
+
+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: MovableCollateralRoute & { intentId: string };
+  originTokenAmount: TokenAmount;
+};

package/src/interfaces/IStrategy.ts

@@ -0,0 +1,81 @@
+import { type ChainMap, type ChainName } from '@humanode-hyperlane/sdk';
+import type { Address } from '@humanode-hyperlane/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;
+}
+
+/**
+ * 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: RouteWithContext[];
+  pendingTransfers: RouteWithContext[];
+  /** Routes from earlier strategies - always have bridge */
+  proposedRebalances?: StrategyRoute[];
+};
+
+export interface IStrategy {
+  readonly name: string;
+  getRebalancingRoutes(
+    rawBalances: RawBalances,
+    inflightContext?: InflightContext,
+  ): StrategyRoute[];
+}