@humanode-hyperlane/rebalancer 27.2.2 → 1029.1.0

package/src/config/RebalancerConfig.test.ts

@@ -12,6 +12,7 @@ import {
   DEFAULT_INTENT_TTL_MS,
   ExecutionType,
   ExternalBridgeType,
+  PendingTransferMiddlewareType,
   type RebalancerConfigFileInput,
   RebalancerMinAmountType,
   RebalancerStrategyOptions,
@@ -104,6 +105,7 @@ describe('RebalancerConfig', () => {
       intentTTL: DEFAULT_INTENT_TTL_MS,
       inventorySigners: undefined,
       externalBridges: undefined,
+      pendingTransferMiddlewares: undefined,
     });
   });
 
@@ -124,7 +126,18 @@ describe('RebalancerConfig', () => {
     writeYamlOrJson(TEST_CONFIG_PATH, data);
 
     expect(() => RebalancerConfig.load(TEST_CONFIG_PATH)).to.throw(
-      'Validation error: Required at "warpRouteId"',
+      'Invalid input: expected string, received undefined',
+    );
+  });
+
+  it('reports an invalid bridge before running cross-field rules', () => {
+    const strategy = getStrategyArray(data)[0];
+    strategy.chains.chain1.bridge = 'bridge';
+    data.strategy = strategy;
+    writeYamlOrJson(TEST_CONFIG_PATH, data);
+
+    expect(() => RebalancerConfig.load(TEST_CONFIG_PATH)).to.throw(
+      'Invalid string: must match pattern',
     );
   });
 
@@ -572,6 +585,141 @@ describe('RebalancerConfig', () => {
   });
 });
 
+describe('Tron inventorySigners validation', () => {
+  const TEST_CONFIG_PATH_TRON = join(tmpdir(), 'rebalancer-tron-test.yaml');
+
+  afterEach(() => {
+    rmSync(TEST_CONFIG_PATH_TRON, { force: true });
+  });
+
+  it('should reject Tron T-prefix base58 address in inventorySigners', () => {
+    const data: RebalancerConfigFileInput = {
+      warpRouteId: 'test-tron-route',
+      strategy: [
+        {
+          rebalanceStrategy: RebalancerStrategyOptions.Weighted,
+          chains: {
+            tron: {
+              weighted: { weight: 50, tolerance: 5 },
+              executionType: ExecutionType.Inventory,
+              externalBridge: ExternalBridgeType.LiFi,
+            },
+            ethereum: {
+              weighted: { weight: 50, tolerance: 5 },
+              executionType: ExecutionType.Inventory,
+              externalBridge: ExternalBridgeType.LiFi,
+            },
+          },
+        },
+      ],
+      inventorySigners: {
+        tron: {
+          address: 'TJRabPrwbZy45sbavfcjinPJC18kjpRTv8',
+          key: '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+        },
+        ethereum: {
+          address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+          key: '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+        },
+      },
+      externalBridges: {
+        lifi: {
+          integrator: 'test-app',
+        },
+      },
+    };
+
+    writeYamlOrJson(TEST_CONFIG_PATH_TRON, data);
+    expect(() => RebalancerConfig.load(TEST_CONFIG_PATH_TRON)).to.throw(
+      /must be a valid 0x hex address/,
+    );
+  });
+
+  it('should accept valid 0x hex address for Tron inventorySigners', () => {
+    const data: RebalancerConfigFileInput = {
+      warpRouteId: 'test-tron-route',
+      strategy: [
+        {
+          rebalanceStrategy: RebalancerStrategyOptions.Weighted,
+          chains: {
+            tron: {
+              weighted: { weight: 50, tolerance: 5 },
+              executionType: ExecutionType.Inventory,
+              externalBridge: ExternalBridgeType.LiFi,
+            },
+            ethereum: {
+              weighted: { weight: 50, tolerance: 5 },
+              executionType: ExecutionType.Inventory,
+              externalBridge: ExternalBridgeType.LiFi,
+            },
+          },
+        },
+      ],
+      inventorySigners: {
+        tron: {
+          address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+          key: '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+        },
+        ethereum: {
+          address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+          key: '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+        },
+      },
+      externalBridges: {
+        lifi: {
+          integrator: 'test-app',
+        },
+      },
+    };
+
+    writeYamlOrJson(TEST_CONFIG_PATH_TRON, data);
+    expect(() => RebalancerConfig.load(TEST_CONFIG_PATH_TRON)).to.not.throw();
+  });
+
+  it('should reject invalid Tron address in inventorySigners', () => {
+    const data: RebalancerConfigFileInput = {
+      warpRouteId: 'test-tron-route',
+      strategy: [
+        {
+          rebalanceStrategy: RebalancerStrategyOptions.Weighted,
+          chains: {
+            tron: {
+              weighted: { weight: 50, tolerance: 5 },
+              executionType: ExecutionType.Inventory,
+              externalBridge: ExternalBridgeType.LiFi,
+            },
+            ethereum: {
+              weighted: { weight: 50, tolerance: 5 },
+              executionType: ExecutionType.Inventory,
+              externalBridge: ExternalBridgeType.LiFi,
+            },
+          },
+        },
+      ],
+      inventorySigners: {
+        tron: {
+          address: 'INVALID_TRON_ADDRESS',
+          key: '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+        },
+        ethereum: {
+          address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+          key: '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+        },
+      },
+      externalBridges: {
+        lifi: {
+          integrator: 'test-app',
+        },
+      },
+    };
+
+    writeYamlOrJson(TEST_CONFIG_PATH_TRON, data);
+    expect(() => RebalancerConfig.load(TEST_CONFIG_PATH_TRON)).to.throw(
+      /must be a valid 0x hex address/,
+    );
+  });
+});
+
 describe('per-chain bridge configuration', () => {
   const TEST_CONFIG_PATH_BRIDGE = join(tmpdir(), 'rebalancer-bridge-test.yaml');
 
@@ -919,3 +1067,169 @@ describe('getAllBridges', () => {
     expect(result).to.deep.equal([BRIDGE_A]);
   });
 });
+
+describe('pendingTransferMiddlewares configuration', () => {
+  const TEST_CONFIG_PATH_MIDDLEWARES = join(
+    tmpdir(),
+    'rebalancer-pending-transfer-middlewares-test.yaml',
+  );
+
+  function writeConfig(pendingTransferMiddlewares: unknown): void {
+    writeYamlOrJson(TEST_CONFIG_PATH_MIDDLEWARES, {
+      warpRouteId: 'USDC/radix',
+      strategy: [
+        {
+          rebalanceStrategy: RebalancerStrategyOptions.Weighted,
+          chains: {
+            ethereum: {
+              weighted: { weight: 50, tolerance: 10 },
+              bridge: ethers.constants.AddressZero,
+              bridgeLockTime: 1800,
+            },
+            arbitrum: {
+              weighted: { weight: 50, tolerance: 10 },
+              bridge: ethers.constants.AddressZero,
+              bridgeLockTime: 1800,
+            },
+          },
+        },
+      ],
+      pendingTransferMiddlewares,
+    });
+  }
+
+  afterEach(() => {
+    rmSync(TEST_CONFIG_PATH_MIDDLEWARES, { force: true });
+  });
+
+  it('leaves middlewares unset when the field is absent', () => {
+    writeConfig(undefined);
+
+    expect(
+      RebalancerConfig.load(TEST_CONFIG_PATH_MIDDLEWARES)
+        .pendingTransferMiddlewares,
+    ).to.equal(undefined);
+  });
+
+  it('loads middlewares in order, with defaults and duplicate types', () => {
+    writeConfig([
+      {
+        type: 'relayerDenylist',
+        url: 'https://raw.githubusercontent.com/hyperlane-xyz/hyperlane-registry/main/deployments/relayer/mainnet-denylist.json',
+      },
+      { type: 'blacklistIsm', refreshIntervalSecs: 300 },
+      {
+        type: 'relayerDenylist',
+        url: 'file:///etc/rebalancer/denylist.json',
+        refreshIntervalSecs: 30,
+      },
+      { type: 'blacklistIsm' },
+    ]);
+
+    expect(
+      RebalancerConfig.load(TEST_CONFIG_PATH_MIDDLEWARES)
+        .pendingTransferMiddlewares,
+    ).to.deep.equal([
+      {
+        type: PendingTransferMiddlewareType.RelayerDenylist,
+        url: 'https://raw.githubusercontent.com/hyperlane-xyz/hyperlane-registry/main/deployments/relayer/mainnet-denylist.json',
+        refreshIntervalSecs: 60,
+      },
+      {
+        type: PendingTransferMiddlewareType.BlacklistIsm,
+        refreshIntervalSecs: 300,
+      },
+      {
+        type: PendingTransferMiddlewareType.RelayerDenylist,
+        url: 'file:///etc/rebalancer/denylist.json',
+        refreshIntervalSecs: 30,
+      },
+      {
+        type: PendingTransferMiddlewareType.BlacklistIsm,
+        refreshIntervalSecs: 600,
+      },
+    ]);
+  });
+
+  interface InvalidMiddlewareCase {
+    name: string;
+    middlewares: unknown;
+    error: RegExp;
+  }
+  const invalidCases: InvalidMiddlewareCase[] = [
+    {
+      name: 'an unknown type',
+      middlewares: [{ type: 'ageCap' }],
+      error: /pendingTransferMiddlewares/,
+    },
+    {
+      name: 'a denylist without url',
+      middlewares: [{ type: 'relayerDenylist' }],
+      error: /url/,
+    },
+    {
+      name: 'a denylist url with an unsupported protocol',
+      middlewares: [
+        { type: 'relayerDenylist', url: 'ftp://example.com/x.json' },
+      ],
+      error: /url must be an https:\/\/, http:\/\/ or file:\/\/ URL/,
+    },
+    {
+      name: 'a denylist url with credentials',
+      middlewares: [
+        {
+          type: 'relayerDenylist',
+          url: 'https://user:hunter2@example.com/x.json',
+        },
+      ],
+      error: /url must not contain credentials/,
+    },
+    {
+      name: 'a non-positive refresh interval',
+      middlewares: [
+        {
+          type: 'relayerDenylist',
+          url: 'https://example.com/x.json',
+          refreshIntervalSecs: 0,
+        },
+      ],
+      error: /refreshIntervalSecs/,
+    },
+    {
+      name: 'a non-integer blacklistIsm refresh interval',
+      middlewares: [{ type: 'blacklistIsm', refreshIntervalSecs: 1.5 }],
+      error: /refreshIntervalSecs/,
+    },
+    {
+      name: 'a misspelled denylist key',
+      middlewares: [
+        {
+          type: 'relayerDenylist',
+          url: 'https://example.com/x.json',
+          refreshIntervalSec: 30,
+        },
+      ],
+      error: /Unrecognized key: "refreshIntervalSec"/,
+    },
+    {
+      name: 'a misspelled blacklistIsm key',
+      middlewares: [{ type: 'blacklistIsm', refreshIntervalSec: 300 }],
+      error: /Unrecognized key: "refreshIntervalSec"/,
+    },
+    {
+      name: 'a non-array value',
+      middlewares: { blacklistIsm: {} },
+      error: /pendingTransferMiddlewares/,
+    },
+  ];
+  for (const c of invalidCases) {
+    it(`rejects ${c.name}`, () => {
+      writeConfig(c.middlewares);
+
+      expect(() => RebalancerConfig.load(TEST_CONFIG_PATH_MIDDLEWARES))
+        .to.throw(c.error)
+        .with.property('message')
+        .that.does.not.include('hunter2');
+    });
+  }
+});

package/src/config/RebalancerConfig.ts

@@ -1,5 +1,4 @@
-import type { z } from 'zod';
-import { fromZodError } from 'zod-validation-error';
+import { z } from 'zod';
 
 import type { ProtocolType } from '@humanode-hyperlane/utils';
 import { readYamlOrJson } from '@humanode-hyperlane/utils/fs';
@@ -7,6 +6,7 @@ import { readYamlOrJson } from '@humanode-hyperlane/utils/fs';
 import type { InventorySignerConfig } from '../core/InventoryRebalancer.js';
 import {
   type ExternalBridgesConfigSchema,
+  type PendingTransferMiddlewareConfig,
   type RebalancerConfigFileInput,
   RebalancerConfigSchema,
   type StrategyConfig,
@@ -24,6 +24,7 @@ export class RebalancerConfig {
       Record<ProtocolType, InventorySignerConfig>
     >,
     public readonly externalBridges?: ExternalBridgesConfig,
+    public readonly pendingTransferMiddlewares?: PendingTransferMiddlewareConfig[],
   ) {}
 
   /**
@@ -36,7 +37,7 @@ export class RebalancerConfig {
     const validationResult = RebalancerConfigSchema.safeParse(config);
 
     if (!validationResult.success) {
-      throw new Error(fromZodError(validationResult.error).message);
+      throw new Error(z.prettifyError(validationResult.error));
     }
 
     const {
@@ -45,6 +46,7 @@ export class RebalancerConfig {
       intentTTL,
       inventorySigners,
       externalBridges,
+      pendingTransferMiddlewares,
     } = validationResult.data;
 
     const chainNames = getStrategyChainNames(strategy);
@@ -58,6 +60,7 @@ export class RebalancerConfig {
       intentTTL,
       inventorySigners,
       externalBridges,
+      pendingTransferMiddlewares,
     );
   }
 }

package/src/config/types.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import { ProtocolType, isAddressEvm } from '@humanode-hyperlane/utils';
 
+const SEALEVEL_ADDRESS_REGEX = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
 export enum RebalancerStrategyOptions {
   Weighted = 'weighted',
   MinAmount = 'minAmount',
@@ -41,7 +43,7 @@ export enum ExternalBridgeType {
 export const RebalancerMinAmountConfigSchema = z.object({
   min: z.string().or(z.number()),
   target: z.string().or(z.number()),
-  type: z.nativeEnum(RebalancerMinAmountType),
+  type: z.enum(RebalancerMinAmountType),
 });
 
 const RebalancerBridgeConfigSchema = z.object({
@@ -49,8 +51,8 @@ const RebalancerBridgeConfigSchema = z.object({
     .string()
     .regex(/0x[a-fA-F0-9]{40}/)
     .optional(),
-  executionType: z.nativeEnum(ExecutionType).optional(),
-  externalBridge: z.nativeEnum(ExternalBridgeType).optional(),
+  executionType: z.enum(ExecutionType).optional(),
+  externalBridge: z.enum(ExternalBridgeType).optional(),
   bridgeMinAcceptedAmount: z.string().or(z.number()).optional(),
   bridgeLockTime: z
     .number()
@@ -62,7 +64,10 @@ const RebalancerBridgeConfigSchema = z.object({
 export const RebalancerBaseChainConfigSchema =
   RebalancerBridgeConfigSchema.extend({
     override: z
-      .record(z.string(), RebalancerBridgeConfigSchema.partial().passthrough())
+      .record(
+        z.string(),
+        z.looseObject(RebalancerBridgeConfigSchema.partial().shape),
+      )
       .optional(),
   });
 
@@ -130,13 +135,82 @@ export const ExternalBridgesConfigSchema = z.object({
   lifi: LiFiBridgeConfigSchema.optional(),
 });
 
+export const PendingTransferMiddlewareType = {
+  RelayerDenylist: 'relayerDenylist',
+  BlacklistIsm: 'blacklistIsm',
+} as const;
+
+export type PendingTransferMiddlewareType =
+  (typeof PendingTransferMiddlewareType)[keyof typeof PendingTransferMiddlewareType];
+
+const DEFAULT_RELAYER_DENYLIST_REFRESH_INTERVAL_IN_SECONDS = 60;
+const DEFAULT_BLACKLIST_ISM_REFRESH_INTERVAL_IN_SECONDS = 600;
+
+const RELAYER_DENYLIST_URL_PROTOCOLS = ['https:', 'http:', 'file:'];
+
+const RelayerDenylistMiddlewareConfigSchema = z
+  .strictObject({
+    type: z.literal(PendingTransferMiddlewareType.RelayerDenylist),
+    url: z
+      .string()
+      .refine(
+        (url) =>
+          URL.canParse(url) &&
+          RELAYER_DENYLIST_URL_PROTOCOLS.includes(new URL(url).protocol),
+        'url must be an https://, http:// or file:// URL',
+      )
+      .refine(
+        (url) =>
+          !URL.canParse(url) ||
+          (new URL(url).username === '' && new URL(url).password === ''),
+        'url must not contain credentials',
+      )
+      .describe(
+        'https://, http:// or file:// URL of the relayer denylist JSON.',
+      ),
+    refreshIntervalSecs: z
+      .number()
+      .int()
+      .positive()
+      .default(DEFAULT_RELAYER_DENYLIST_REFRESH_INTERVAL_IN_SECONDS)
+      .describe('Seconds between denylist re-fetches.'),
+  })
+  .describe(
+    'Ignores messages the relayer runtime denylist blocks. Startup retries a failed fetch twice and fails if every attempt fails or the file is invalid. Only messageId-only rules apply to rebalance messages: deny one only after its funds settled another way, since a denied rebalance stops counting as incoming collateral until its rule is removed or expires.',
+  );
+
+const BlacklistIsmMiddlewareConfigSchema = z
+  .strictObject({
+    type: z.literal(PendingTransferMiddlewareType.BlacklistIsm),
+    refreshIntervalSecs: z
+      .number()
+      .int()
+      .positive()
+      .default(DEFAULT_BLACKLIST_ISM_REFRESH_INTERVAL_IN_SECONDS)
+      .describe(
+        'Minimum seconds between refreshes, which re-resolve the router ISMs and re-read their BlacklistIsm ids.',
+      ),
+  })
+  .describe(
+    'Ignores messages a BlacklistIsm in the destination router ISM rejects. Router ISMs are re-resolved on each refresh, and a destination whose refresh fails keeps its previous BlacklistIsms and ids; startup fails if no route pair has a BlacklistIsm that can block.',
+  );
+
+const PendingTransferMiddlewareConfigSchema = z.discriminatedUnion('type', [
+  RelayerDenylistMiddlewareConfigSchema,
+  BlacklistIsmMiddlewareConfigSchema,
+]);
+
+export type PendingTransferMiddlewareConfig = z.infer<
+  typeof PendingTransferMiddlewareConfigSchema
+>;
+
 export const RebalancerConfigSchema = z
   .object({
     warpRouteId: z.string(),
     strategy: RebalancerStrategySchema,
     inventorySigners: z
-      .record(
-        z.nativeEnum(ProtocolType),
+      .partialRecord(
+        z.enum(ProtocolType),
         z.union([
           z.object({ address: z.string(), key: z.string().optional() }),
           z.string().transform((address) => ({ address })),
@@ -144,6 +218,12 @@ export const RebalancerConfigSchema = z
       )
       .optional(),
     externalBridges: ExternalBridgesConfigSchema.optional(),
+    pendingTransferMiddlewares: z
+      .array(PendingTransferMiddlewareConfigSchema)
+      .optional()
+      .describe(
+        'Ordered middlewares applied to pending user transfers read from the Explorer; item 0 runs first on the raw result. Omit to disable.',
+      ),
     intentTTL: z
       .number()
       .positive()
@@ -153,7 +233,7 @@ export const RebalancerConfigSchema = z
       )
       .transform((val) => val * 1_000),
   })
-  .superRefine((config, ctx) => {
+  .transform((config, ctx) => {
     // CollateralDeficitStrategy must be first in composite if it is used
     if (config.strategy.length > 1) {
       const hasCollateralDeficit = config.strategy.some(
@@ -354,13 +434,21 @@ export const RebalancerConfigSchema = z
               });
             }
           } else if (protocol === ProtocolType.Sealevel) {
-            if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(signerConfig.address)) {
+            if (!SEALEVEL_ADDRESS_REGEX.test(signerConfig.address)) {
               ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 message: `inventorySigners.${protocol} must be a valid Solana base58 address (32-44 chars), got: ${signerConfig.address}`,
                 path: ['inventorySigners', protocol],
               });
             }
+          } else if (protocol === ProtocolType.Tron) {
+            if (!isAddressEvm(signerConfig.address)) {
+              ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `inventorySigners.${protocol} must be a valid 0x hex address, got: ${signerConfig.address}`,
+                path: ['inventorySigners', protocol],
+              });
+            }
           }
           // Other protocols: accept any non-empty string (future-proof)
         }
@@ -428,6 +516,8 @@ export const RebalancerConfigSchema = z
         }
       }
     }
+
+    return config;
   });
 
 // Define separate types for each strategy config