@hyperlane-xyz/rebalancer 0.1.2 → 1.0.0

package/README.md

@@ -9,11 +9,13 @@ The rebalancer monitors collateral balances across warp route deployments and au
 ## Features
 
 - **Multi-Protocol Support**: Protocol-agnostic design supporting EVM chains (Cosmos, Sealevel, etc. when movable collateral contracts available)
-- **Flexible Strategies**: Weighted and minimum-amount rebalancing strategies
-- **Safety Features**: Inflight guards, semaphores, and comprehensive validation
+- **Flexible Strategies**: Weighted, minimum-amount, and collateral-deficit rebalancing strategies
+- **Composite Strategies**: Combine multiple strategies with different bridges for layered rebalancing
+- **Inflight Tracking**: Monitors pending rebalances to prevent duplicate transfers
+- **Safety Features**: Inflight message tracking and comprehensive validation
 - **Observability**: Built-in Prometheus metrics and structured logging
 - **Dual Mode**: Manual CLI execution or continuous daemon service
-- **Bridge Support**: Integration with Portal, Hyperlane, and other bridge providers
+- **Bridge Support**: Integration with Hyperlane warp routes and external bridges
 
 ## Installation
 
@@ -90,7 +92,9 @@ await service.executeManual({
 
 ## Configuration
 
-The rebalancer uses a YAML configuration file. See example:
+The rebalancer uses a YAML configuration file with a `warpRouteId` and `strategy` field.
+
+### Basic Example (Single Strategy)
 
 ```yaml
 warpRouteId: ETH/ethereum-arbitrum-optimism
@@ -99,13 +103,129 @@ strategy:
   chains:
     ethereum:
       weight: 60
-      bridge: hyperlane
+      tolerance: 5
+      bridge: '0x1234...abcd'
     arbitrum:
       weight: 20
-      bridge: hyperlane
-    optimism:
-      weight: 20
-      bridge: portal
+      tolerance: 5
+      bridge: '0x5678...efgh'
+```
+
+### Composite Strategy (v1.0.0+)
+
+The `strategy` field accepts an array of strategies for composite rebalancing. Strategies are evaluated in order - the first strategy that produces routes is used.
+
+```yaml
+warpRouteId: USDC/base-ethereum-arbitrum
+strategy:
+  # First: CollateralDeficitStrategy with fast bridges for reactive rebalancing
+  - rebalanceStrategy: collateralDeficit
+    chains:
+      base:
+        buffer: 0
+        bridge: '0x584244d02b0fBf9054A5D5C9e9cE9A2E8adA0e28'
+      ethereum:
+        buffer: 0
+        bridge: '0xEE4a09db2C25592C04b8b342CB89f9a7f5E20BD2'
+
+  # Second: MinAmountStrategy with standard bridges for baseline floors
+  - rebalanceStrategy: minAmount
+    chains:
+      base:
+        minAmount:
+          min: 0.1
+          target: 0.11
+          type: 'absolute'
+        bridgeLockTime: 1800
+        bridge: '0x33e94B6D2ae697c16a750dB7c3d9443622C4405a'
+      ethereum:
+        minAmount:
+          min: 0.1
+          target: 0.11
+          type: 'absolute'
+        bridgeLockTime: 1800
+        bridge: '0x8c8D831E1e879604b4B304a2c951B8AEe3aB3a23'
+```
+
+> **Note**: When using `collateralDeficit` in a composite strategy, it must be the first strategy in the array.
+
+### Strategy Types
+
+| Strategy            | Use Case                                               | Chain Config Fields              |
+| ------------------- | ------------------------------------------------------ | -------------------------------- |
+| `weighted`          | Maintain percentage distribution across chains         | `weight`, `tolerance`            |
+| `minAmount`         | Trigger rebalance when balance falls below floor       | `minAmount: {min, target, type}` |
+| `collateralDeficit` | React to bridged supply gaps (synthetic vs collateral) | `buffer`                         |
+
+#### Weighted Strategy
+
+Maintains target weight percentages across chains. Rebalances when deviation exceeds tolerance.
+
+```yaml
+strategy:
+  rebalanceStrategy: weighted
+  chains:
+    ethereum:
+      weight: 60 # Target 60% of total supply
+      tolerance: 5 # Rebalance if >5% deviation
+      bridge: '0x...'
+```
+
+#### MinAmount Strategy
+
+Triggers rebalance when a chain's balance falls below the minimum threshold.
+
+```yaml
+strategy:
+  rebalanceStrategy: minAmount
+  chains:
+    ethereum:
+      minAmount:
+        min: 100 # Trigger rebalance below this
+        target: 110 # Rebalance up to this amount
+        type: 'absolute' # or 'relative' (percentage of total)
+      bridge: '0x...'
+```
+
+#### CollateralDeficit Strategy
+
+Monitors bridged (synthetic) supply vs collateral and rebalances to cover deficits.
+
+```yaml
+strategy:
+  rebalanceStrategy: collateralDeficit
+  chains:
+    ethereum:
+      buffer: 1000 # Extra collateral buffer above deficit
+      bridge: '0x...'
+```
+
+### Chain Config Reference
+
+| Field                     | Type             | Required | Description                                                    |
+| ------------------------- | ---------------- | -------- | -------------------------------------------------------------- |
+| `bridge`                  | `0x...` address  | Yes      | Bridge contract address for this chain                         |
+| `bridgeLockTime`          | number (seconds) | No       | Expected bridge transfer duration (used for inflight tracking) |
+| `bridgeMinAcceptedAmount` | number           | No       | Skip routes with amounts below this threshold                  |
+| `override`                | object           | No       | Per-destination bridge overrides (see below)                   |
+
+#### Per-Destination Overrides
+
+Use `override` to specify different bridge configs for specific destination chains:
+
+```yaml
+strategy:
+  rebalanceStrategy: minAmount
+  chains:
+    ethereum:
+      minAmount: { min: 100, target: 110, type: 'absolute' }
+      bridge: '0xDefaultBridge...'
+      override:
+        arbitrum:
+          bridge: '0xFastArbitrumBridge...'
+          bridgeLockTime: 600
+        optimism:
+          bridge: '0xOptimismBridge...'
 ```
 
 ## Architecture
@@ -117,12 +237,12 @@ typescript/rebalancer/
 ├── src/
 │   ├── core/
 │   │   ├── RebalancerService.ts    # Main orchestrator
-│   │   ├── Rebalancer.ts           # Core rebalancing logic
-│   │   ├── WithInflightGuard.ts    # Concurrency protection
-│   │   └── WithSemaphore.ts        # Semaphore wrapper
+│   │   └── Rebalancer.ts           # Core rebalancing logic
 │   ├── strategy/
-│   │   ├── WeightedStrategy.ts     # Weighted distribution
-│   │   └── MinAmountStrategy.ts    # Minimum threshold strategy
+│   │   ├── WeightedStrategy.ts          # Weighted distribution
+│   │   ├── MinAmountStrategy.ts         # Minimum threshold strategy
+│   │   ├── CollateralDeficitStrategy.ts # Bridged supply deficit strategy
+│   │   └── CompositeStrategy.ts         # Combines multiple strategies
 │   ├── monitor/
 │   │   └── Monitor.ts              # Balance monitoring
 │   ├── metrics/

package/dist/config/RebalancerConfig.d.ts

@@ -1,8 +1,8 @@
 import { type StrategyConfig } from './types.js';
 export declare class RebalancerConfig {
     readonly warpRouteId: string;
-    readonly strategyConfig: StrategyConfig;
-    constructor(warpRouteId: string, strategyConfig: StrategyConfig);
+    readonly strategyConfig: StrategyConfig[];
+    constructor(warpRouteId: string, strategyConfig: StrategyConfig[]);
     /**
      * Loads config from a file
      * @param configFilePath Path to the config file

package/dist/config/RebalancerConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RebalancerConfig.d.ts","sourceRoot":"","sources":["../../src/config/RebalancerConfig.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB,qBAAa,gBAAgB;aAET,WAAW,EAAE,MAAM;aACnB,cAAc,EAAE,cAAc;gBAD9B,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,cAAc;IAGhD;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM;CAiBnC"}
+{"version":3,"file":"RebalancerConfig.d.ts","sourceRoot":"","sources":["../../src/config/RebalancerConfig.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AAEpB,qBAAa,gBAAgB;aAET,WAAW,EAAE,MAAM;aACnB,cAAc,EAAE,cAAc,EAAE;gBADhC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,cAAc,EAAE;IAGlD;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM;CAmBnC"}

package/dist/config/RebalancerConfig.js

@@ -1,7 +1,6 @@
 import { fromZodError } from 'zod-validation-error';
-import { isObjEmpty } from '@hyperlane-xyz/utils';
 import { readYamlOrJson } from '@hyperlane-xyz/utils/fs';
-import { RebalancerConfigSchema, } from './types.js';
+import { RebalancerConfigSchema, getStrategyChainNames, } from './types.js';
 export class RebalancerConfig {
     warpRouteId;
     strategyConfig;
@@ -20,7 +19,9 @@ export class RebalancerConfig {
             throw new Error(fromZodError(validationResult.error).message);
         }
         const { warpRouteId, strategy } = validationResult.data;
-        if (isObjEmpty(strategy.chains)) {
+        // Check that at least one chain is configured across all strategies
+        const chainNames = getStrategyChainNames(strategy);
+        if (chainNames.length === 0) {
             throw new Error('No chains configured');
         }
         return new RebalancerConfig(warpRouteId, strategy);

package/dist/config/RebalancerConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"RebalancerConfig.js","sourceRoot":"","sources":["../../src/config/RebalancerConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,EAEL,sBAAsB,GAEvB,MAAM,YAAY,CAAC;AAEpB,MAAM,OAAO,gBAAgB;IAET;IACA;IAFlB,YACkB,WAAmB,EACnB,cAA8B;QAD9B,gBAAW,GAAX,WAAW,CAAQ;QACnB,mBAAc,GAAd,cAAc,CAAgB;IAC7C,CAAC;IAEJ;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,cAAsB;QAChC,MAAM,MAAM,GAA8B,cAAc,CAAC,cAAc,CAAC,CAAC;QAEzE,MAAM,gBAAgB,GAAG,sBAAsB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAElE,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC;QAChE,CAAC;QAED,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC;QAExD,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC1C,CAAC;QAED,OAAO,IAAI,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrD,CAAC;CACF"}
+{"version":3,"file":"RebalancerConfig.js","sourceRoot":"","sources":["../../src/config/RebalancerConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,EAEL,sBAAsB,EAEtB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAEpB,MAAM,OAAO,gBAAgB;IAET;IACA;IAFlB,YACkB,WAAmB,EACnB,cAAgC;QADhC,gBAAW,GAAX,WAAW,CAAQ;QACnB,mBAAc,GAAd,cAAc,CAAkB;IAC/C,CAAC;IAEJ;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,cAAsB;QAChC,MAAM,MAAM,GAA8B,cAAc,CAAC,cAAc,CAAC,CAAC;QAEzE,MAAM,gBAAgB,GAAG,sBAAsB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAElE,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC;QAChE,CAAC;QAED,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC;QAExD,oEAAoE;QACpE,MAAM,UAAU,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC1C,CAAC;QAED,OAAO,IAAI,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrD,CAAC;CACF"}