@humanode-hyperlane/rebalancer 0.0.0-stage → 27.2.2

package/dist/core/InventoryRebalancer.d.ts

@@ -0,0 +1,201 @@
+import type { Logger } from 'pino';
+import { type ChainName, type MultiProvider, type WarpCore } from '@humanode-hyperlane/sdk';
+import { ProtocolType } from '@humanode-hyperlane/utils';
+import type { ExternalBridgeRegistry } from '../interfaces/IExternalBridge.js';
+import type { IInventoryRebalancer, InventoryExecutionResult, RebalancerType } from '../interfaces/IRebalancer.js';
+import type { InventoryRoute } from '../interfaces/IStrategy.js';
+import type { IActionTracker } from '../tracking/IActionTracker.js';
+/**
+ * Configuration for the InventoryRebalancer.
+ */
+export interface InventorySignerConfig {
+    /** Signer address for this protocol */
+    address: string;
+    /** Private key for signing (optional - absent in monitor-only mode) */
+    key?: string;
+}
+export interface InventoryRebalancerConfig {
+    /** Signer config per protocol (address + optional key) */
+    inventorySigners: Partial<Record<ProtocolType, InventorySignerConfig>>;
+    /** Chains configured for inventory-based rebalancing (for validation) */
+    inventoryChains: ChainName[];
+}
+/**
+ * Executes inventory-based rebalances for chains that don't support MovableCollateralRouter.
+ *
+ * IMPORTANT: transferRemote ADDS collateral to the ORIGIN chain (where it's called FROM).
+ * So for a strategy route "base (surplus) → arbitrum (deficit)", we must:
+ * 1. Ensure inventory is available on the DESTINATION (deficit) chain - arbitrum
+ * 2. Call transferRemote FROM arbitrum TO base
+ * 3. This ADDS collateral to arbitrum (filling deficit) and releases from base (has surplus)
+ *
+ * The flow is:
+ * 1. Check if inventory is available on the destination (deficit) chain
+ * 2. If available, execute transferRemote from destination to origin (swapped direction)
+ * 3. If not available, bridge inventory to destination via LiFi, then execute transferRemote
+ *
+ * Actions created:
+ * - `inventory_movement`: LiFi bridge to move inventory to deficit chain
+ * - `inventory_deposit`: transferRemote to deposit collateral on deficit chain
+ */
+export declare class InventoryRebalancer implements IInventoryRebalancer {
+    readonly rebalancerType: RebalancerType;
+    private readonly logger;
+    private readonly config;
+    private readonly actionTracker;
+    private readonly externalBridgeRegistry;
+    private readonly warpCore;
+    private readonly multiProvider;
+    /**
+     * Internal balance storage for inventory tracking.
+     * Updated via setInventoryBalances() before each rebalance cycle.
+     */
+    private inventoryBalances;
+    /**
+     * Tracks inventory consumed during the current execution cycle.
+     * Cleared at the start of each execute() call.
+     * Used to prevent over-execution when multiple routes withdraw from the same chain.
+     */
+    private consumedInventory;
+    constructor(config: InventoryRebalancerConfig, actionTracker: IActionTracker, externalBridgeRegistry: Partial<ExternalBridgeRegistry>, warpCore: WarpCore, multiProvider: MultiProvider, logger: Logger);
+    /**
+     * Get bridge instance by type from registry.
+     * Throws if bridge type not found.
+     */
+    private getExternalBridge;
+    private getNativeTokenAddress;
+    /**
+     * Validate that tokens on inventory chains are collateral-backed.
+     * Only checks tokens for chains configured with inventory-based rebalancing.
+     * Throws an error if any synthetic tokens are found on inventory chains.
+     */
+    private validateCollateralBackedTokens;
+    /**
+     * Get the token for a specific chain from WarpCore.
+     */
+    private getTokenForChain;
+    private getProtocolForChain;
+    private getInventorySignerAddress;
+    /**
+     * Set inventory balances from external source.
+     * Called before each rebalance cycle to update internal state.
+     */
+    setInventoryBalances(balances: Record<ChainName, bigint>): void;
+    /**
+     * Get available inventory for a chain.
+     * Returns 0n for unknown chains.
+     */
+    private getAvailableInventory;
+    /**
+     * Get all inventory balances.
+     */
+    private getBalances;
+    /**
+     * Calculate total inventory across all chains, excluding specified chains.
+     */
+    private getTotalInventory;
+    /**
+     * Get the effective available inventory for a chain, accounting for
+     * inventory already consumed during this execution cycle.
+     *
+     * This prevents over-execution when multiple routes withdraw from the same chain.
+     *
+     * @param chain - The chain to check inventory for
+     * @returns Effective available inventory (cached - consumed)
+     */
+    private getEffectiveAvailableInventory;
+    /**
+     * Execute inventory-based rebalances for the given routes.
+     *
+     * Single-intent architecture:
+     * 1. Check for existing in_progress intent
+     * 2. If exists, continue existing intent (ignores new routes)
+     * 3. If not, take only the FIRST route and create a single intent
+     */
+    rebalance(routes: InventoryRoute[]): Promise<InventoryExecutionResult[]>;
+    /**
+     * Get the single active inventory intent (if any).
+     * Returns null if no in_progress inventory intent exists.
+     */
+    private getActiveInventoryIntent;
+    /**
+     * Continue execution of an existing partial intent.
+     * Uses the pre-computed remaining amount from PartialInventoryIntent.
+     */
+    private continueIntent;
+    /**
+     * Execute a single inventory route.
+     *
+     * Strategy provides: origin (surplus) → destination (deficit)
+     * "Move collateral FROM origin TO destination"
+     *
+     * IMPORTANT: transferRemote ADDS collateral to the chain it's called FROM.
+     * So to fill the deficit on destination, we must:
+     * - Call transferRemote FROM destination TO origin (SWAPPED direction)
+     * - This ADDS to destination (deficit filled!) and RELEASES from origin (has surplus)
+     *
+     * Execution flow:
+     * 1. Check inventory on DESTINATION (deficit chain) - need funds there to call transferRemote
+     * 2. If low, LiFi bridge TO destination
+     * 3. Call transferRemote FROM destination TO origin (swapped)
+     */
+    private executeRoute;
+    /**
+     * Execute a transferRemote to deposit collateral.
+     *
+     * IMPORTANT: The route passed here has SWAPPED direction from the strategy route.
+     * - route.origin = the deficit chain (where transferRemote is called FROM)
+     * - route.destination = the surplus chain (where Hyperlane message goes TO)
+     *
+     * transferRemote mechanics:
+     * - Calls _transferFromSender() which ADDS collateral to route.origin
+     * - Sends Hyperlane message to route.destination to RELEASE collateral
+     *
+     * @param route - The transfer route (swapped direction)
+     * @param intent - The rebalance intent being executed
+     * @param gasQuote - Pre-calculated gas quote from calculateTransferCosts
+     */
+    private executeTransferRemote;
+    private sendAndConfirmInventoryTx;
+    private buildSignerAccountConfig;
+    protected extractDispatchedMessageId(origin: ChainName, txHash: string): Promise<string | undefined>;
+    private getTransactionReceipt;
+    /**
+     * Select all source chains with available inventory for bridging.
+     * Returns sources sorted by available amount (highest first).
+     */
+    private selectAllSourceChains;
+    /**
+     * Calculate the maximum amount that can be bridged from a source chain.
+     * Uses LiFi quote to determine gas costs, applies 20x multiplier buffer.
+     * Returns 0 if gas exceeds 10% of inventory (not economically viable).
+     *
+     * This is the key method for the gas-aware planning approach:
+     * - Gets a quote for the full raw inventory to determine actual gas costs
+     * - Applies conservative 20x buffer (LiFi underestimates by ~14x historically)
+     * - Returns 0 if gas > 10% of inventory (not worth bridging)
+     * - Returns inventory - estimatedGas if viable
+     *
+     * @param sourceChain - Chain to bridge from
+     * @param targetChain - Chain to bridge to
+     * @param rawInventory - Raw available inventory on source chain
+     * @param externalBridgeType - External bridge type to use
+     * @returns Maximum viable bridge amount (0 if not viable)
+     */
+    private calculateMaxViableBridgeAmount;
+    /**
+     * Execute inventory movement from source chain to target chain via LiFi bridge.
+     *
+     * IMPORTANT: The amount parameter is now the MAX VIABLE amount (gas already subtracted
+     * by calculateMaxViableBridgeAmount). This method trusts that the amount is pre-validated.
+     *
+     * @param sourceChain - Chain to move inventory from
+     * @param targetChain - Chain to move inventory to (origin chain for rebalancing)
+     * @param amount - Pre-validated amount to bridge (gas already accounted for)
+     * @param intent - Rebalance intent for tracking
+     * @param externalBridgeType - External bridge type to use
+     * @returns Result with success status and optional txHash/error
+     */
+    private executeInventoryMovement;
+}
+//# sourceMappingURL=InventoryRebalancer.d.ts.map

package/dist/core/InventoryRebalancer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InventoryRebalancer.d.ts","sourceRoot":"","sources":["../../src/core/InventoryRebalancer.ts"],"names":[],"mappings":"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"}