@hyperlane-xyz/rebalancer 0.1.2 → 1.0.0

package/src/config/RebalancerConfig.ts

@@ -1,18 +1,18 @@
 import { fromZodError } from 'zod-validation-error';
 
-import { isObjEmpty } from '@hyperlane-xyz/utils';
 import { readYamlOrJson } from '@hyperlane-xyz/utils/fs';
 
 import {
   type RebalancerConfigFileInput,
   RebalancerConfigSchema,
   type StrategyConfig,
+  getStrategyChainNames,
 } from './types.js';
 
 export class RebalancerConfig {
   constructor(
     public readonly warpRouteId: string,
-    public readonly strategyConfig: StrategyConfig,
+    public readonly strategyConfig: StrategyConfig[],
   ) {}
 
   /**
@@ -30,7 +30,9 @@ export class RebalancerConfig {
 
     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');
     }
 

package/src/config/types.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 export enum RebalancerStrategyOptions {
   Weighted = 'weighted',
   MinAmount = 'minAmount',
+  CollateralDeficit = 'collateralDeficit',
 }
 
 // Weighted strategy config schema
@@ -36,11 +37,8 @@ const RebalancerBridgeConfigSchema = z.object({
     .number()
     .positive()
     .transform((val) => val * 1_000)
-    .describe('Expected time in seconds for bridge to process a transfer'),
-  bridgeIsWarp: z
-    .boolean()
     .optional()
-    .describe('True if the bridge is another Warp Route'),
+    .describe('Expected time in seconds for bridge to process a transfer'),
 });
 
 export const RebalancerBaseChainConfigSchema =
@@ -59,6 +57,11 @@ const MinAmountChainConfigSchema = RebalancerBaseChainConfigSchema.extend({
   minAmount: RebalancerMinAmountConfigSchema,
 });
 
+const CollateralDeficitChainConfigSchema =
+  RebalancerBaseChainConfigSchema.extend({
+    buffer: z.string().or(z.number()),
+  });
+
 const WeightedStrategySchema = z.object({
   rebalanceStrategy: z.literal(RebalancerStrategyOptions.Weighted),
   chains: z.record(z.string(), WeightedChainConfigSchema),
@@ -69,75 +72,122 @@ const MinAmountStrategySchema = z.object({
   chains: z.record(z.string(), MinAmountChainConfigSchema),
 });
 
+const CollateralDeficitStrategySchema = z.object({
+  rebalanceStrategy: z.literal(RebalancerStrategyOptions.CollateralDeficit),
+  chains: z.record(z.string(), CollateralDeficitChainConfigSchema),
+});
+
 export type WeightedStrategy = z.infer<typeof WeightedStrategySchema>;
 export type MinAmountStrategy = z.infer<typeof MinAmountStrategySchema>;
+export type CollateralDeficitStrategy = z.infer<
+  typeof CollateralDeficitStrategySchema
+>;
 
 export type WeightedStrategyConfig = WeightedStrategy['chains'];
 export type MinAmountStrategyConfig = MinAmountStrategy['chains'];
+export type CollateralDeficitStrategyConfig =
+  CollateralDeficitStrategy['chains'];
 
 export const StrategyConfigSchema = z.discriminatedUnion('rebalanceStrategy', [
   WeightedStrategySchema,
   MinAmountStrategySchema,
+  CollateralDeficitStrategySchema,
 ]);
 
+// Accept either a single strategy (backwards compatible) or an array of strategies
+// Normalizes to array internally so the rest of the code doesn't need to change
+export const RebalancerStrategySchema = z
+  .union([
+    StrategyConfigSchema, // Old format: single object
+    z.array(StrategyConfigSchema).min(1), // New format: array
+  ])
+  .transform((val) => (Array.isArray(val) ? val : [val]));
+
 export const RebalancerConfigSchema = z
   .object({
     warpRouteId: z.string(),
-    strategy: StrategyConfigSchema,
+    strategy: RebalancerStrategySchema,
   })
   .superRefine((config, ctx) => {
-    const chainNames = new Set(Object.keys(config.strategy.chains));
-    // Check each chain's overrides
-    for (const [chainName, chainConfig] of Object.entries(
-      config.strategy.chains,
-    )) {
-      if (chainConfig.override) {
-        for (const overrideChainName of Object.keys(chainConfig.override)) {
-          // Each override key must reference a valid chain
-          if (!chainNames.has(overrideChainName)) {
-            ctx.addIssue({
-              code: z.ZodIssueCode.custom,
-              message: `Chain '${chainName}' has an override for '${overrideChainName}', but '${overrideChainName}' is not defined in the config`,
-              path: [
-                'strategy',
-                'chains',
-                chainName,
-                'override',
-                overrideChainName,
-              ],
-            });
-          }
+    // CollateralDeficitStrategy must be first in composite if it is used
+    if (config.strategy.length > 1) {
+      const hasCollateralDeficit = config.strategy.some(
+        (s) =>
+          s.rebalanceStrategy === RebalancerStrategyOptions.CollateralDeficit,
+      );
+      const collateralDeficitFirst =
+        config.strategy[0].rebalanceStrategy ===
+        RebalancerStrategyOptions.CollateralDeficit;
 
-          // Override shouldn't be self-referencing
-          if (chainName === overrideChainName) {
-            ctx.addIssue({
-              code: z.ZodIssueCode.custom,
-              message: `Chain '${chainName}' has an override for '${chainName}', but '${chainName}' is self-referencing`,
-              path: [
-                'strategy',
-                'chains',
-                chainName,
-                'override',
-                overrideChainName,
-              ],
-            });
-          }
-        }
+      if (hasCollateralDeficit && !collateralDeficitFirst) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            'CollateralDeficitStrategy must be first when used in composite strategy',
+          path: ['strategy'],
+        });
       }
     }
 
-    if (
-      config.strategy.rebalanceStrategy === RebalancerStrategyOptions.MinAmount
+    // Validate each strategy in the array
+    for (
+      let strategyIndex = 0;
+      strategyIndex < config.strategy.length;
+      strategyIndex++
     ) {
-      const minAmountChainsTypes = Object.values(config.strategy.chains).map(
-        (c) => c.minAmount.type,
-      );
-      if (new Set(minAmountChainsTypes).size > 1) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `All chains must use the same minAmount type.`,
-          path: ['strategy', 'chains'],
-        });
+      const strategy = config.strategy[strategyIndex];
+      const chainNames = new Set(Object.keys(strategy.chains));
+
+      // Check each chain's overrides
+      for (const [chainName, chainConfig] of Object.entries(strategy.chains)) {
+        if ('override' in chainConfig && chainConfig.override) {
+          for (const overrideChainName of Object.keys(chainConfig.override)) {
+            // Each override key must reference a valid chain
+            if (!chainNames.has(overrideChainName)) {
+              ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Chain '${chainName}' has an override for '${overrideChainName}', but '${overrideChainName}' is not defined in the config`,
+                path: [
+                  'strategy',
+                  strategyIndex,
+                  'chains',
+                  chainName,
+                  'override',
+                  overrideChainName,
+                ],
+              });
+            }
+
+            // Override shouldn't be self-referencing
+            if (chainName === overrideChainName) {
+              ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Chain '${chainName}' has an override for '${chainName}', but '${chainName}' is self-referencing`,
+                path: [
+                  'strategy',
+                  strategyIndex,
+                  'chains',
+                  chainName,
+                  'override',
+                  overrideChainName,
+                ],
+              });
+            }
+          }
+        }
+      }
+
+      if (strategy.rebalanceStrategy === RebalancerStrategyOptions.MinAmount) {
+        const minAmountChainsTypes = Object.values(strategy.chains).map(
+          (c) => c.minAmount.type,
+        );
+        if (new Set(minAmountChainsTypes).size > 1) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `All chains must use the same minAmount type.`,
+            path: ['strategy', strategyIndex, 'chains'],
+          });
+        }
       }
     }
   });
@@ -149,8 +199,65 @@ export type RebalancerWeightedChainConfig = z.infer<
 export type RebalancerMinAmountChainConfig = z.infer<
   typeof RebalancerMinAmountConfigSchema
 >;
+export type CollateralDeficitChainConfig = z.infer<
+  typeof CollateralDeficitChainConfigSchema
+>;
 
 export type StrategyConfig = z.infer<typeof StrategyConfigSchema>;
 
 export type RebalancerConfig = z.infer<typeof RebalancerConfigSchema>;
 export type RebalancerConfigFileInput = z.input<typeof RebalancerConfigSchema>;
+
+/**
+ * Get all unique chain names from strategy config array.
+ */
+export function getStrategyChainNames(strategies: StrategyConfig[]): string[] {
+  const chainSet = new Set<string>();
+  for (const strategy of strategies) {
+    Object.keys(strategy.chains).forEach((chain) => chainSet.add(chain));
+  }
+  return Array.from(chainSet);
+}
+
+/**
+ * Get chain config from the first strategy that has it.
+ * Returns undefined if no strategy has the chain.
+ */
+export function getStrategyChainConfig(
+  strategies: StrategyConfig[],
+  chainName: string,
+): StrategyConfig['chains'][string] | undefined {
+  for (const strategy of strategies) {
+    if (chainName in strategy.chains) {
+      return strategy.chains[chainName];
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Get all unique bridge addresses from all strategies and their overrides.
+ * This is used by ActionTracker to detect inflight rebalances across all configured bridges.
+ */
+export function getAllBridges(strategies: StrategyConfig[]): string[] {
+  const bridges = new Set<string>();
+
+  for (const strategy of strategies) {
+    for (const chainConfig of Object.values(strategy.chains)) {
+      if (chainConfig.bridge) {
+        bridges.add(chainConfig.bridge);
+      }
+
+      if (chainConfig.override) {
+        for (const overrideConfig of Object.values(chainConfig.override)) {
+          const override = overrideConfig as { bridge?: string };
+          if (override.bridge) {
+            bridges.add(override.bridge);
+          }
+        }
+      }
+    }
+  }
+
+  return Array.from(bridges);
+}