@hyperlane-xyz/rebalancer 3.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperlane-xyz/rebalancer",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Hyperlane Warp Route Collateral Rebalancer Service",
   "keywords": [
     "blockchain",
@@ -40,11 +40,11 @@
     "yaml": "2.4.5",
     "zod": "^3.21.2",
     "zod-validation-error": "^3.3.0",
-    "@hyperlane-xyz/metrics": "0.1.6",
-    "@hyperlane-xyz/provider-sdk": "1.3.4",
-    "@hyperlane-xyz/sdk": "25.3.0",
     "@hyperlane-xyz/core": "10.1.5",
-    "@hyperlane-xyz/utils": "25.3.0"
+    "@hyperlane-xyz/metrics": "0.1.7",
+    "@hyperlane-xyz/provider-sdk": "1.3.5",
+    "@hyperlane-xyz/sdk": "25.3.1",
+    "@hyperlane-xyz/utils": "25.3.1"
   },
   "devDependencies": {
     "@ethersproject/constants": "*",
@@ -64,8 +64,8 @@
     "testcontainers": "11.7.0",
     "tsx": "^4.19.1",
     "typescript": "5.8.3",
-    "@hyperlane-xyz/relayer": "1.1.1",
-    "@hyperlane-xyz/tsconfig": "^25.3.0"
+    "@hyperlane-xyz/relayer": "1.1.2",
+    "@hyperlane-xyz/tsconfig": "^25.3.1"
   },
   "engines": {
     "node": ">=18"

package/src/config/RebalancerConfig.test.ts

@@ -9,6 +9,7 @@ import { writeYamlOrJson } from '@hyperlane-xyz/utils/fs';
 
 import { RebalancerConfig } from './RebalancerConfig.js';
 import {
+  DEFAULT_INTENT_TTL_MS,
   ExecutionType,
   ExternalBridgeType,
   type RebalancerConfigFileInput,
@@ -100,6 +101,7 @@ describe('RebalancerConfig', () => {
           },
         },
       ],
+      intentTTL: DEFAULT_INTENT_TTL_MS,
       inventorySigner: undefined,
       externalBridges: undefined,
     });

package/src/config/RebalancerConfig.ts

@@ -17,6 +17,7 @@ export class RebalancerConfig {
   constructor(
     public readonly warpRouteId: string,
     public readonly strategyConfig: StrategyConfig[],
+    public readonly intentTTL: number,
     public readonly inventorySigner?: string,
     public readonly externalBridges?: ExternalBridgesConfig,
   ) {}
@@ -34,8 +35,13 @@ export class RebalancerConfig {
       throw new Error(fromZodError(validationResult.error).message);
     }
 
-    const { warpRouteId, strategy, inventorySigner, externalBridges } =
-      validationResult.data;
+    const {
+      warpRouteId,
+      strategy,
+      intentTTL,
+      inventorySigner,
+      externalBridges,
+    } = validationResult.data;
 
     const chainNames = getStrategyChainNames(strategy);
     if (chainNames.length === 0) {
@@ -45,6 +51,7 @@ export class RebalancerConfig {
     return new RebalancerConfig(
       warpRouteId,
       strategy,
+      intentTTL,
       inventorySigner,
       externalBridges,
     );

package/src/config/types.ts

@@ -115,6 +115,9 @@ export const RebalancerStrategySchema = z
   .union([StrategyConfigSchema, z.array(StrategyConfigSchema).min(1)])
   .transform((val) => (Array.isArray(val) ? val : [val]));
 
+export const DEFAULT_INTENT_TTL_S = 604800; // 7 days
+export const DEFAULT_INTENT_TTL_MS = DEFAULT_INTENT_TTL_S * 1_000;
+
 export const LiFiBridgeConfigSchema = z.object({
   integrator: z.string(),
   defaultSlippage: z.number().optional(),
@@ -133,6 +136,14 @@ export const RebalancerConfigSchema = z
       .regex(/0x[a-fA-F0-9]{40}/)
       .optional(),
     externalBridges: ExternalBridgesConfigSchema.optional(),
+    intentTTL: z
+      .number()
+      .positive()
+      .default(DEFAULT_INTENT_TTL_S)
+      .describe(
+        'Max age in seconds before in-progress intent is expired. Default 7 days.',
+      )
+      .transform((val) => val * 1_000),
   })
   .superRefine((config, ctx) => {
     // CollateralDeficitStrategy must be first in composite if it is used

package/src/core/InventoryRebalancer.test.ts

@@ -418,6 +418,7 @@ describe('InventoryRebalancer E2E', () => {
           intent: existingIntent,
           completedAmount: 3000000000n,
           remaining: 7000000000n, // 7k remaining
+          hasInflightDeposit: false,
         },
       ]);
 
@@ -441,6 +442,41 @@ describe('InventoryRebalancer E2E', () => {
       expect(actionTracker.createRebalanceIntent.called).to.be.false;
     });
 
+    it('returns empty when active intent has in-flight deposit (prevents oscillation)', async () => {
+      const existingIntent = createTestIntent({
+        id: 'inflight-deposit-intent',
+        status: 'in_progress',
+        amount: 10000000000n,
+      });
+
+      // Configure mock: active intent WITH in-flight deposit
+      actionTracker.getPartiallyFulfilledInventoryIntents.resolves([
+        {
+          intent: existingIntent,
+          completedAmount: 3000000000n,
+          remaining: 7000000000n,
+          hasInflightDeposit: true,
+        },
+      ]);
+
+      // New routes that WOULD create a new intent or continue
+      const newRoute = createTestRoute({ amount: 5000000000n });
+
+      inventoryRebalancer.setInventoryBalances({
+        [SOLANA_CHAIN]: 10000000000n,
+        [ARBITRUM_CHAIN]: 0n,
+      });
+
+      const results = await inventoryRebalancer.rebalance([newRoute]);
+
+      // Must return empty — wait for in-flight deposit to complete
+      expect(results).to.have.lengthOf(0);
+      // Must NOT create a new intent
+      expect(actionTracker.createRebalanceIntent.called).to.be.false;
+      // Must NOT call createRebalanceAction (proves continueIntent was never reached)
+      expect(actionTracker.createRebalanceAction.called).to.be.false;
+    });
+
     it('returns empty results when no routes provided and no active intent', async () => {
       const results = await inventoryRebalancer.rebalance([]);
 
@@ -463,6 +499,7 @@ describe('InventoryRebalancer E2E', () => {
           intent: existingIntent,
           completedAmount: 0n,
           remaining: 10000000000n,
+          hasInflightDeposit: false,
         },
       ]);
 

package/src/core/InventoryRebalancer.ts

@@ -282,6 +282,16 @@ export class InventoryRebalancer implements IInventoryRebalancer {
     const activeIntent = await this.getActiveInventoryIntent();
 
     if (activeIntent) {
+      if (activeIntent.hasInflightDeposit) {
+        this.logger.info(
+          {
+            intentId: activeIntent.intent.id,
+            remaining: activeIntent.remaining.toString(),
+          },
+          'Active intent has in-flight deposit, waiting for delivery before continuing',
+        );
+        return [];
+      }
       // Continue existing intent, ignore new routes
       this.logger.info(
         {

package/src/core/RebalancerOrchestrator.test.ts

@@ -4,7 +4,11 @@ import { pino } from 'pino';
 import Sinon from 'sinon';
 
 import type { RebalancerConfig } from '../config/RebalancerConfig.js';
-import { ExecutionType, RebalancerStrategyOptions } from '../config/types.js';
+import {
+  DEFAULT_INTENT_TTL_MS,
+  ExecutionType,
+  RebalancerStrategyOptions,
+} from '../config/types.js';
 import type { IExternalBridge } from '../interfaces/IExternalBridge.js';
 import { MonitorEventType } from '../interfaces/IMonitor.js';
 import type { IRebalancer } from '../interfaces/IRebalancer.js';
@@ -43,6 +47,7 @@ function createMockRebalancerConfig(): RebalancerConfig {
         },
       },
     ],
+    intentTTL: DEFAULT_INTENT_TTL_MS,
   } as RebalancerConfig;
 }
 
@@ -372,6 +377,7 @@ describe('RebalancerOrchestrator', () => {
             },
           },
         ],
+        intentTTL: DEFAULT_INTENT_TTL_MS,
       } as RebalancerConfig;
 
       const strategy = createMockStrategy();
@@ -446,6 +452,7 @@ describe('RebalancerOrchestrator', () => {
             },
           },
         ],
+        intentTTL: DEFAULT_INTENT_TTL_MS,
       } as RebalancerConfig;
 
       const strategy = createMockStrategy();
@@ -541,6 +548,7 @@ describe('RebalancerOrchestrator', () => {
             },
           },
         ],
+        intentTTL: DEFAULT_INTENT_TTL_MS,
       } as RebalancerConfig;
 
       const strategy = createMockStrategy();
@@ -591,6 +599,7 @@ describe('RebalancerOrchestrator', () => {
             },
           },
         ],
+        intentTTL: DEFAULT_INTENT_TTL_MS,
       } as RebalancerConfig;
 
       const strategy = createMockStrategy();

package/src/core/RebalancerService.test.ts

@@ -6,7 +6,10 @@ import Sinon from 'sinon';
 import type { MultiProvider, Token, WarpCore } from '@hyperlane-xyz/sdk';
 
 import type { RebalancerConfig } from '../config/RebalancerConfig.js';
-import { RebalancerStrategyOptions } from '../config/types.js';
+import {
+  DEFAULT_INTENT_TTL_MS,
+  RebalancerStrategyOptions,
+} from '../config/types.js';
 import { RebalancerContextFactory } from '../factories/RebalancerContextFactory.js';
 import type { ExternalBridgeRegistry } from '../interfaces/IExternalBridge.js';
 import { MonitorEventType } from '../interfaces/IMonitor.js';
@@ -47,6 +50,7 @@ function createMockRebalancerConfig(): RebalancerConfig {
         },
       },
     ],
+    intentTTL: DEFAULT_INTENT_TTL_MS,
   } as RebalancerConfig;
 }
 
@@ -476,6 +480,7 @@ describe('RebalancerService', () => {
             },
           },
         ],
+        intentTTL: DEFAULT_INTENT_TTL_MS,
       } as RebalancerConfig;
 
       const config: RebalancerServiceConfig = {

package/src/e2e/harness/ForkIndexer.ts

@@ -120,6 +120,7 @@ export class ForkIndexer {
           origin_tx_recipient: event.args.sender,
           is_delivered: false,
           message_body: parsed.body,
+          send_occurred_at: null,
         };
 
         if (

package/src/e2e/harness/TestRebalancer.ts

@@ -10,6 +10,7 @@ import { addressToBytes32 } from '@hyperlane-xyz/utils';
 
 import { RebalancerConfig } from '../../config/RebalancerConfig.js';
 import {
+  DEFAULT_INTENT_TTL_MS,
   type StrategyConfig,
   getStrategyChainNames,
 } from '../../config/types.js';
@@ -203,6 +204,7 @@ export class TestRebalancerBuilder {
     const rebalancerConfig = new RebalancerConfig(
       MONITORED_ROUTE_ID,
       this.strategyConfig,
+      DEFAULT_INTENT_TTL_MS,
     );
 
     const registry = this.deploymentManager.getRegistry();
@@ -325,6 +327,7 @@ export class TestRebalancerBuilder {
         origin_tx_recipient: deployedAddresses.monitoredRoute[params.from],
         is_delivered: false,
         message_body: encodeWarpRouteMessageBody(warpRecipient, params.amount),
+        send_occurred_at: null,
       };
 
       userTransfers.push(mockTransfer);

package/src/factories/RebalancerContextFactory.ts

@@ -351,6 +351,7 @@ export class RebalancerContextFactory {
       bridges,
       rebalancerAddress,
       inventorySignerAddress: this.config.inventorySigner,
+      intentTTL: this.config.intentTTL,
     };
 
     // 6. Create ActionTracker

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,