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

package/dist/strategy/BaseStrategy.js

@@ -0,0 +1,342 @@
+import { toWei } from '@humanode-hyperlane/utils';
+import { createStrategyRoute, getBridgeConfig, } from '../utils/bridgeUtils.js';
+/**
+ * Base abstract class for rebalancing strategies
+ */
+export class BaseStrategy {
+    chains;
+    metrics;
+    logger;
+    bridgeConfigs;
+    tokensByChainName;
+    constructor(chains, logger, bridgeConfigs, metrics, tokensByChainName) {
+        // Rebalancing makes sense only with more than one chain.
+        if (chains.length < 2) {
+            throw new Error('At least two chains must be configured');
+        }
+        this.chains = chains;
+        this.logger = logger;
+        this.bridgeConfigs = bridgeConfigs;
+        this.metrics = metrics;
+        this.tokensByChainName = tokensByChainName;
+    }
+    getBridgeConfigForRoute(origin, destination) {
+        return getBridgeConfig(this.bridgeConfigs, origin, destination);
+    }
+    /**
+     * Main method to get rebalancing routes
+     */
+    getRebalancingRoutes(rawBalances, inflightContext) {
+        const pendingRebalances = inflightContext?.pendingRebalances ?? [];
+        const pendingTransfers = inflightContext?.pendingTransfers ?? [];
+        const proposedRebalances = inflightContext?.proposedRebalances ?? [];
+        this.logger.info({
+            strategy: this.name,
+            balances: Object.entries(rawBalances).map(([c, b]) => ({
+                chain: c,
+                balance: b.toString(),
+            })),
+            pendingRebalances: pendingRebalances.length,
+            pendingTransfers: pendingTransfers.length,
+            proposedRebalances: proposedRebalances.length,
+        }, 'Strategy evaluating');
+        this.validateRawBalances(rawBalances);
+        // Store original balances for filtering step
+        const actualBalances = rawBalances;
+        // Step 1: Reserve collateral for pending user transfers
+        // This prevents draining collateral needed for incoming user transfers
+        const effectiveBalances = this.reserveCollateral(rawBalances, pendingTransfers);
+        // Get balances categorized by surplus and deficit
+        // Pass pending and proposed rebalances so strategy can account for them
+        const { surpluses, deficits } = this.getCategorizedBalances(effectiveBalances, pendingRebalances, proposedRebalances);
+        this.logger.debug({
+            context: this.constructor.name,
+            surpluses,
+        }, 'Surpluses calculated');
+        this.logger.debug({
+            context: this.constructor.name,
+            deficits,
+        }, 'Deficits calculated');
+        // Calculate sums of surpluses and deficits
+        const totalSurplus = surpluses.reduce((sum, surplus) => sum + surplus.amount, 0n);
+        const totalDeficit = deficits.reduce((sum, deficit) => sum + deficit.amount, 0n);
+        this.logger.debug({
+            context: this.constructor.name,
+            totalSurplus: totalSurplus.toString(),
+        }, 'Total surplus calculated');
+        this.logger.debug({
+            context: this.constructor.name,
+            totalDeficit: totalDeficit.toString(),
+        }, 'Total deficit calculated');
+        // If total surplus is less than total deficit, scale down deficits proportionally
+        if (totalSurplus < totalDeficit) {
+            this.logger.warn({
+                context: this.constructor.name,
+                totalSurplus: totalSurplus.toString(),
+                totalDeficit: totalDeficit.toString(),
+            }, 'Deficits are greater than surpluses. Scaling deficits');
+            // we consider this a failure because we cannot rebalance the route completely
+            // however we can still transfer some amount of the deficit to reduce the imbalances
+            this.metrics?.recordRebalancerFailure();
+            for (const deficit of deficits) {
+                const newAmount = (deficit.amount * totalSurplus) / totalDeficit;
+                deficit.amount = newAmount;
+            }
+            this.logger.debug({
+                context: this.constructor.name,
+                deficits,
+            }, 'Scaled deficits');
+        }
+        // Sort from largest to smallest amounts as to always transfer largest amounts
+        // first and decrease the amount of routes required
+        surpluses.sort((a, b) => (a.amount > b.amount ? -1 : 1));
+        deficits.sort((a, b) => (a.amount > b.amount ? -1 : 1));
+        const routes = [];
+        // Transfer from surplus to deficit until all deficits are balanced.
+        while (deficits.length > 0 && surpluses.length > 0) {
+            const surplus = surpluses[0];
+            const deficit = deficits[0];
+            // Transfers the whole surplus or just the amount to balance the deficit
+            const transferAmount = surplus.amount > deficit.amount ? deficit.amount : surplus.amount;
+            // Skip zero-amount routes (can occur after scaling when surpluses < deficits)
+            if (transferAmount > 0n) {
+                // Get bridge config for this route (with destination-specific overrides)
+                const bridgeConfig = this.getBridgeConfigForRoute(surplus.chain, deficit.chain);
+                // Create appropriate route type based on execution type
+                routes.push(createStrategyRoute(bridgeConfig, surplus.chain, deficit.chain, transferAmount));
+            }
+            // Decreases the amounts for the following iterations
+            deficit.amount -= transferAmount;
+            surplus.amount -= transferAmount;
+            // Removes the deficit if it is fully balanced (including scaled-to-zero)
+            if (deficit.amount <= 0n) {
+                deficits.shift();
+            }
+            // Removes the surplus if it has been drained
+            if (surplus.amount <= 0n) {
+                surpluses.shift();
+            }
+        }
+        this.logger.debug({
+            context: this.constructor.name,
+            routes,
+        }, 'Generated routes');
+        this.logger.info({
+            context: this.constructor.name,
+            numberOfRoutes: routes.length,
+        }, 'Found rebalancing routes');
+        const filteredRoutes = this.filterRoutes(routes, actualBalances);
+        this.logger.debug({
+            context: this.constructor.name,
+            filteredRoutesCount: filteredRoutes.length,
+            droppedCount: routes.length - filteredRoutes.length,
+        }, 'Filtered rebalancing routes');
+        // Record metrics for each intent that passed filtering
+        for (const route of filteredRoutes) {
+            this.metrics?.recordIntentCreated(route, this.name);
+        }
+        return filteredRoutes;
+    }
+    /**
+     * Validates the raw balances against the chains configuration
+     */
+    validateRawBalances(rawBalances) {
+        const rawBalancesChains = Object.keys(rawBalances);
+        if (this.chains.length !== rawBalancesChains.length) {
+            throw new Error('Config chains do not match raw balances chains length');
+        }
+        for (const chain of this.chains) {
+            const balance = rawBalances[chain];
+            if (balance === undefined) {
+                throw new Error(`Raw balance for chain ${chain} not found`);
+            }
+            if (balance < 0n) {
+                throw new Error(`Raw balance for chain ${chain} is negative`);
+            }
+        }
+    }
+    /**
+     * Reserve collateral for pending user transfers.
+     * Subtracts pending transfer amounts from destination balances.
+     * This ensures we don't drain collateral needed for incoming transfers.
+     *
+     * @param rawBalances - Current on-chain balances
+     * @param pendingTransfers - Transfers that will need collateral on destination
+     * @returns Balances with reserved amounts subtracted
+     */
+    reserveCollateral(rawBalances, pendingTransfers) {
+        if (pendingTransfers.length === 0) {
+            return rawBalances;
+        }
+        const reserved = { ...rawBalances };
+        for (const transfer of pendingTransfers) {
+            const destBalance = reserved[transfer.destination] ?? 0n;
+            // Reserve the transfer amount from destination
+            // Allow negative values to indicate collateral deficits
+            reserved[transfer.destination] = destBalance - transfer.amount;
+            this.logger.debug({
+                context: this.constructor.name,
+                destination: transfer.destination,
+                amount: transfer.amount.toString(),
+                newBalance: reserved[transfer.destination].toString(),
+            }, 'Reserved collateral for pending transfer');
+        }
+        this.logger.info({
+            reservations: pendingTransfers.map((t) => ({
+                destination: t.destination,
+                amount: t.amount.toString(),
+            })),
+        }, 'Collateral reserved for pending transfers');
+        return reserved;
+    }
+    /**
+     * Simulate pending rebalances based on execution method.
+     *
+     * For **movable_collateral** (default):
+     * - Add full amount to destination (origin already deducted on-chain)
+     *
+     * For **inventory**:
+     * - Simulate the eventual final state as if the entire intent will be fulfilled
+     * - Destination: add unfulfilled amount (total - delivered - awaiting)
+     *   This is what's NOT yet reflected in on-chain balance
+     * - Origin: subtract pending amount (total - delivered)
+     *   This is what WILL decrease when all messages deliver
+     *
+     * @param rawBalances - Current balances (may already have collateral reserved)
+     * @param pendingRebalances - In-flight rebalance operations (in_progress only)
+     * @returns Simulated future balances after rebalances complete
+     */
+    simulatePendingRebalances(rawBalances, pendingRebalances) {
+        if (pendingRebalances.length === 0) {
+            return rawBalances;
+        }
+        const simulated = { ...rawBalances };
+        for (const rebalance of pendingRebalances) {
+            if (rebalance.executionMethod === 'inventory') {
+                // Inventory: simulate eventual final state
+                const total = rebalance.amount;
+                const delivered = rebalance.deliveredAmount ?? 0n;
+                const awaiting = rebalance.awaitingDeliveryAmount ?? 0n;
+                // Destination: add unfulfilled amount (total - delivered - awaiting)
+                // This is what's NOT yet reflected in on-chain balance
+                const destinationAdjustment = total - delivered - awaiting;
+                if (destinationAdjustment > 0n) {
+                    simulated[rebalance.destination] =
+                        (simulated[rebalance.destination] ?? 0n) + destinationAdjustment;
+                    this.logger.debug({
+                        context: this.constructor.name,
+                        destination: rebalance.destination,
+                        destinationAdjustment: destinationAdjustment.toString(),
+                    }, 'Simulated inventory rebalance (destination increase for unfulfilled)');
+                }
+                // Origin: subtract pending amount (total - delivered)
+                // This is what WILL decrease when all messages deliver
+                const originAdjustment = total - delivered;
+                if (originAdjustment > 0n) {
+                    simulated[rebalance.origin] =
+                        (simulated[rebalance.origin] ?? 0n) - originAdjustment;
+                    this.logger.debug({
+                        context: this.constructor.name,
+                        origin: rebalance.origin,
+                        originAdjustment: originAdjustment.toString(),
+                    }, 'Simulated inventory rebalance (origin decrease for pending)');
+                }
+            }
+            else {
+                // Movable collateral: origin already deducted on-chain, add to destination
+                simulated[rebalance.destination] =
+                    (simulated[rebalance.destination] ?? 0n) + rebalance.amount;
+                this.logger.debug({
+                    context: this.constructor.name,
+                    destination: rebalance.destination,
+                    amount: rebalance.amount.toString(),
+                }, 'Simulated movable collateral rebalance (destination increase)');
+            }
+        }
+        this.logger.info({
+            simulations: pendingRebalances.map((r) => ({
+                from: r.origin,
+                to: r.destination,
+                amount: r.amount.toString(),
+                executionMethod: r.executionMethod ?? 'movable_collateral',
+                deliveredAmount: r.deliveredAmount?.toString() ?? '0',
+                awaitingDeliveryAmount: r.awaitingDeliveryAmount?.toString() ?? '0',
+            })),
+        }, 'Simulated pending rebalances');
+        return simulated;
+    }
+    /**
+     * Simulate proposed rebalances by subtracting from origin AND adding to destination.
+     *
+     * Unlike pendingRebalances, proposedRebalances are routes from earlier strategies
+     * in the same cycle that haven't been executed yet. Therefore:
+     * - Origin balance has NOT been deducted on-chain
+     * - We must simulate both sides to maintain accurate total balance
+     *
+     * @param rawBalances - Current balances (may already have pending rebalances simulated)
+     * @param proposedRebalances - Routes from earlier strategies (not yet executed)
+     * @returns Simulated balances after proposed rebalances complete
+     */
+    simulateProposedRebalances(rawBalances, proposedRebalances) {
+        if (proposedRebalances.length === 0) {
+            return rawBalances;
+        }
+        const simulated = { ...rawBalances };
+        for (const rebalance of proposedRebalances) {
+            // Subtract from origin (not yet deducted on-chain)
+            simulated[rebalance.origin] =
+                (simulated[rebalance.origin] ?? 0n) - rebalance.amount;
+            // Add to destination
+            simulated[rebalance.destination] =
+                (simulated[rebalance.destination] ?? 0n) + rebalance.amount;
+            this.logger.debug({
+                context: this.constructor.name,
+                origin: rebalance.origin,
+                destination: rebalance.destination,
+                amount: rebalance.amount.toString(),
+            }, 'Simulated proposed rebalance (origin decrease, destination increase)');
+        }
+        this.logger.info({
+            simulations: proposedRebalances.map((r) => ({
+                from: r.origin,
+                to: r.destination,
+                amount: r.amount.toString(),
+            })),
+        }, 'Simulated proposed rebalances');
+        return simulated;
+    }
+    filterRoutes(routes, actualBalances) {
+        return routes.filter((route) => {
+            const balance = actualBalances[route.origin] ?? 0n;
+            if (balance < route.amount) {
+                this.logger.warn({
+                    context: this.constructor.name,
+                    origin: route.origin,
+                    destination: route.destination,
+                    required: route.amount.toString(),
+                    available: balance.toString(),
+                }, 'Dropping route due to insufficient balance');
+                return false;
+            }
+            if (this.tokensByChainName) {
+                const token = this.tokensByChainName[route.origin];
+                if (token) {
+                    const bridgeConfig = this.getBridgeConfigForRoute(route.origin, route.destination);
+                    const minAmount = BigInt(toWei(bridgeConfig.bridgeMinAcceptedAmount, token.decimals));
+                    if (route.amount < minAmount) {
+                        this.logger.info({
+                            context: this.constructor.name,
+                            origin: route.origin,
+                            destination: route.destination,
+                            amount: route.amount.toString(),
+                            minAmount: minAmount.toString(),
+                        }, 'Dropping route below bridgeMinAcceptedAmount');
+                        return false;
+                    }
+                }
+            }
+            return true;
+        });
+    }
+}
+//# sourceMappingURL=BaseStrategy.js.map

package/dist/strategy/BaseStrategy.js.map

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

package/dist/strategy/CollateralDeficitStrategy.d.ts

@@ -0,0 +1,65 @@
+import { Logger } from 'pino';
+import { type ChainMap, type Token } from '@humanode-hyperlane/sdk';
+import { type CollateralDeficitStrategyConfig, RebalancerStrategyOptions } from '../config/types.js';
+import type { InflightContext, RawBalances, Route, StrategyRoute } from '../interfaces/IStrategy.js';
+import { Metrics } from '../metrics/Metrics.js';
+import { type BridgeConfigWithOverride } from '../utils/bridgeUtils.js';
+import { BaseStrategy, type Delta } from './BaseStrategy.js';
+/**
+ * Strategy that detects collateral deficits (negative effective balances)
+ * and proposes JIT rebalances using fast bridges.
+ *
+ * Logic:
+ * 1. Filter pendingRebalances to only those using this strategy's configured bridges
+ * 2. Simulate filtered pending rebalances to get projected balances
+ * 3. Negative simulated balance = deficit (magnitude + buffer)
+ * 4. Positive simulated balance = potential surplus
+ */
+export declare class CollateralDeficitStrategy extends BaseStrategy {
+    readonly name = RebalancerStrategyOptions.CollateralDeficit;
+    private readonly config;
+    protected readonly logger: Logger;
+    constructor(config: CollateralDeficitStrategyConfig, tokensByChainName: ChainMap<Token>, logger: Logger, bridgeConfigs: ChainMap<BridgeConfigWithOverride>, metrics?: Metrics);
+    /**
+     * Categorizes balances into surpluses and deficits.
+     *
+     * 1. Filter pendingRebalances/proposedRebalances by configured bridges
+     * 2. Simulate those rebalances to get projected balances
+     * 3. Negative balance = deficit (magnitude + buffer)
+     * 4. Positive balance = potential surplus
+     */
+    protected getCategorizedBalances(rawBalances: RawBalances, pendingRebalances?: Route[], proposedRebalances?: StrategyRoute[]): {
+        surpluses: Delta[];
+        deficits: Delta[];
+    };
+    /**
+     * Override to prefer transfer origins when selecting surplus chains.
+     *
+     * When a user transfer creates a deficit, the origin chain of that transfer
+     * is the natural source of funds (user deposited there). This prevents
+     * unnecessarily draining the largest balance (typically ethereum at 70%).
+     */
+    getRebalancingRoutes(rawBalances: RawBalances, inflightContext?: InflightContext): StrategyRoute[];
+    /**
+     * Filter pending rebalances to only those using this strategy's configured bridges.
+     * A rebalance matches if:
+     * - Its bridge matches the configured bridge (with overrides) for the route, OR
+     * - It has no bridge (recovered from Explorer, can't verify - include to be safe)
+     */
+    private filterByConfiguredBridges;
+    /**
+     * Build a map from deficit chains to their transfer origin chains.
+     * This identifies which surplus chains are "natural" sources for each deficit.
+     */
+    private buildTransferOriginMap;
+    /**
+     * Sort surpluses to prefer transfer origins over largest balances.
+     *
+     * Sorting priority:
+     * 1. Chains that are origins of transfers TO any deficit chain (preferred)
+     * 2. By amount descending (tiebreaker)
+     */
+    private sortSurplusesWithOriginPreference;
+    protected getTokenByChainName(chainName: string): Token;
+}
+//# sourceMappingURL=CollateralDeficitStrategy.d.ts.map

package/dist/strategy/CollateralDeficitStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CollateralDeficitStrategy.d.ts","sourceRoot":"","sources":["../../src/strategy/CollateralDeficitStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAE9B,OAAO,EACL,KAAK,QAAQ,EAEb,KAAK,KAAK,EACX,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,KAAK,+BAA+B,EACpC,yBAAyB,EAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,KAAK,EACL,aAAa,EACd,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EACL,KAAK,wBAAwB,EAI9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,KAAK,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE7D;;;;;;;;;GASG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;IACzD,QAAQ,CAAC,IAAI,+CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGhC,MAAM,EAAE,+BAA+B,EACvC,iBAAiB,EAAE,QAAQ,CAAC,KAAK,CAAC,EAClC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,QAAQ,CAAC,wBAAwB,CAAC,EACjD,OAAO,CAAC,EAAE,OAAO;IAUnB;;;;;;;OAOG;IACH,SAAS,CAAC,sBAAsB,CAC9B,WAAW,EAAE,WAAW,EACxB,iBAAiB,CAAC,EAAE,KAAK,EAAE,EAC3B,kBAAkB,CAAC,EAAE,aAAa,EAAE,GACnC;QACD,SAAS,EAAE,KAAK,EAAE,CAAC;QACnB,QAAQ,EAAE,KAAK,EAAE,CAAC;KACnB;IA4ED;;;;;;OAMG;IACM,oBAAoB,CAC3B,WAAW,EAAE,WAAW,EACxB,eAAe,CAAC,EAAE,eAAe,GAChC,aAAa,EAAE;IAiJlB;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;IAoCjC;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAmB9B;;;;;;OAMG;IACH,OAAO,CAAC,iCAAiC;IAoCzC,SAAS,CAAC,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK;CAOxD"}