@hyperlane-xyz/rebalancer 27.2.12 → 27.2.13

package/src/core/Rebalancer.test.ts

@@ -229,6 +229,53 @@ describe('Rebalancer', () => {
       expect(results[0].success).to.be.false;
     });
 
+    it('should log scaled route amounts using origin local units', async () => {
+      const ctx = createRebalancerTestContext(['ethereum']);
+      ctx.tokensByChainName.ethereum.scale = {
+        numerator: 1,
+        denominator: 1_000_000_000_000,
+      };
+
+      const logger = {
+        child: Sinon.stub(),
+        info: Sinon.stub(),
+        warn: Sinon.stub(),
+        error: Sinon.stub(),
+      };
+      logger.child.returns(logger);
+
+      const rebalancer = new Rebalancer(
+        ctx.warpCore,
+        ctx.chainMetadata,
+        ctx.tokensByChainName,
+        ctx.multiProvider as any,
+        createMockActionTracker(),
+        logger as any,
+      );
+
+      const route = buildTestMovableCollateralRoute({
+        origin: 'ethereum',
+        destination: 'arbitrum',
+        amount: 1_000_000n,
+      });
+      const results = await rebalancer.rebalance([route]);
+
+      expect(results).to.have.lengthOf(1);
+      expect(results[0].success).to.be.false;
+      const validationErrorCall = logger.error
+        .getCalls()
+        .find(
+          (call) =>
+            call.args[1] ===
+            'Route validation failed: destination token not found.',
+        );
+      expect(validationErrorCall).to.not.be.undefined;
+      expect(validationErrorCall!.args[0].amount).to.equal(1);
+      expect(validationErrorCall!.args[1]).to.equal(
+        'Route validation failed: destination token not found.',
+      );
+    });
+
     it('should fail when signer is not a rebalancer', async () => {
       const ctx = createRebalancerTestContext(['ethereum', 'arbitrum'], {
         ethereum: { isRebalancer: false },
@@ -337,6 +384,43 @@ describe('Rebalancer', () => {
       expect(results).to.have.lengthOf(1);
       expect(results[0].success).to.be.false;
     });
+
+    it('should denormalize canonical route amounts before quote and populate calls', async () => {
+      const ctx = createRebalancerTestContext(['ethereum', 'arbitrum']);
+      ctx.tokensByChainName.ethereum.scale = {
+        numerator: 1,
+        denominator: 1_000_000_000_000,
+      };
+
+      sandbox.stub(HyperlaneCore, 'getDispatchedMessages').returns([
+        {
+          id: '0x1111111111111111111111111111111111111111111111111111111111111111',
+        } as any,
+      ]);
+
+      const rebalancer = new Rebalancer(
+        ctx.warpCore,
+        ctx.chainMetadata,
+        ctx.tokensByChainName,
+        ctx.multiProvider as any,
+        createMockActionTracker(),
+        testLogger,
+      );
+
+      await rebalancer.rebalance([
+        buildTestMovableCollateralRoute({
+          amount: 1_000_000n,
+        }),
+      ]);
+
+      expect(ctx.adapters.ethereum.getRebalanceQuotes.calledOnce).to.be.true;
+      expect(
+        ctx.adapters.ethereum.getRebalanceQuotes.firstCall.args[3],
+      ).to.equal(1_000_000_000_000_000_000n);
+      expect(
+        ctx.adapters.ethereum.populateRebalanceTx.firstCall.args[1],
+      ).to.equal(1_000_000_000_000_000_000n);
+    });
   });
 
   describe('executeTransactions()', () => {

package/src/core/Rebalancer.ts

@@ -25,10 +25,16 @@ import { MovableCollateralRoute } from '../interfaces/IStrategy.js';
 import { type Metrics } from '../metrics/Metrics.js';
 import type { IActionTracker } from '../tracking/IActionTracker.js';
 import type { RebalanceIntent } from '../tracking/types.js';
+import {
+  denormalizeToLocal,
+  normalizeToCanonical,
+} from '../utils/balanceUtils.js';
 
 // Internal types with intentId for tracking
 type InternalExecutionResult = MovableCollateralExecutionResult & {
   intentId: string;
+  canonicalAmount?: bigint;
+  localAmount?: bigint;
 };
 
 type InternalRoute = MovableCollateralRoute & { intentId: string };
@@ -104,7 +110,10 @@ export class Rebalancer implements IMovableCollateralRebalancer {
         if (token) {
           this.metrics.recordRebalanceAmount(
             result.route,
-            token.amount(result.route.amount),
+            token.amount(
+              result.localAmount ??
+                denormalizeToLocal(result.route.amount, token),
+            ),
           );
         }
       }
@@ -150,7 +159,7 @@ export class Rebalancer implements IMovableCollateralRebalancer {
           intentId,
           origin: this.multiProvider.getDomainId(result.route.origin),
           destination: this.multiProvider.getDomainId(result.route.destination),
-          amount: result.route.amount,
+          amount: result.canonicalAmount ?? result.route.amount,
           type: 'rebalance_message',
           messageId: result.messageId,
           txHash: result.txHash,
@@ -264,8 +273,9 @@ export class Rebalancer implements IMovableCollateralRebalancer {
     const originToken = this.tokensByChainName[origin];
     const destinationToken = this.tokensByChainName[destination];
     const destinationChainMeta = this.chainMetadata[destination];
+    const localAmount = denormalizeToLocal(amount, originToken);
 
-    const originTokenAmount = originToken.amount(amount);
+    const originTokenAmount = originToken.amount(localAmount);
     const decimalFormattedAmount =
       originTokenAmount.getDecimalFormattedAmount();
     const originHypAdapter = originToken.getHypAdapter(
@@ -281,7 +291,7 @@ export class Rebalancer implements IMovableCollateralRebalancer {
         bridge,
         destinationChainMeta.domainId,
         destinationToken.addressOrDenom,
-        amount,
+        localAmount,
       );
     } catch (error) {
       this.logger.error(
@@ -302,7 +312,7 @@ export class Rebalancer implements IMovableCollateralRebalancer {
     try {
       populatedTx = await originHypAdapter.populateRebalanceTx(
         destinationChainMeta.domainId,
-        amount,
+        localAmount,
         bridge,
         quotes,
       );
@@ -337,7 +347,8 @@ export class Rebalancer implements IMovableCollateralRebalancer {
       return false;
     }
 
-    const originTokenAmount = originToken.amount(amount);
+    const localAmount = denormalizeToLocal(amount, originToken);
+    const originTokenAmount = originToken.amount(localAmount);
     const decimalFormattedAmount =
       originTokenAmount.getDecimalFormattedAmount();
 
@@ -676,6 +687,11 @@ export class Rebalancer implements IMovableCollateralRebalancer {
       success: true,
       messageId: dispatchedMessages[0].id,
       txHash: receipt.transactionHash,
+      canonicalAmount: normalizeToCanonical(
+        transaction.originTokenAmount.amount,
+        transaction.originTokenAmount.token,
+      ),
+      localAmount: transaction.originTokenAmount.amount,
     };
   }
 

package/src/core/RebalancerOrchestrator.test.ts

@@ -646,7 +646,6 @@ describe('RebalancerOrchestrator', () => {
       expect(inventoryRebalancer.rebalance.calledWith([])).to.be.false;
     });
 
-    // eslint-disable-next-line jest/expect-expect
     it('should NOT call inventoryRebalancer.rebalance([]) when inventoryRebalancer is not in rebalancers', async () => {
       const strategy = createMockStrategy();
       strategy.getRebalancingRoutes.returns([]);

package/src/core/RebalancerService.test.ts

@@ -366,6 +366,41 @@ describe('RebalancerService', () => {
       expect(calledRoutes[0].destination).to.equal('arbitrum');
     });
 
+    it('should normalize manual amount to canonical units when token has scale', async () => {
+      const rebalancer = createMockRebalancer();
+      const warpCore = {
+        tokens: [
+          {
+            ...createMockToken('ethereum'),
+            decimals: 18,
+            scale: { numerator: 1n, denominator: 1_000_000_000_000n },
+          },
+          createMockToken('arbitrum'),
+        ],
+        multiProvider: createMockMultiProvider(),
+      } as unknown as WarpCore;
+
+      const contextFactory = createMockContextFactory({ rebalancer, warpCore });
+      sandbox.stub(RebalancerContextFactory, 'create').resolves(contextFactory);
+
+      const service = new RebalancerService(
+        createMockMultiProvider(),
+        undefined,
+        {} as any,
+        createMockRebalancerConfig(),
+        { mode: 'manual', logger: testLogger },
+      );
+
+      await service.executeManual({
+        origin: 'ethereum',
+        destination: 'arbitrum',
+        amount: '1',
+      });
+
+      const calledRoutes = rebalancer.rebalance.firstCall.args[0];
+      expect(calledRoutes[0].amount).to.equal(1_000_000n);
+    });
+
     it('should throw when origin token not found', async () => {
       const warpCore = {
         tokens: [createMockToken('arbitrum')],

package/src/core/RebalancerService.ts

@@ -1,9 +1,12 @@
 import { Logger } from 'pino';
 
 import { IRegistry } from '@hyperlane-xyz/registry';
-import { type MultiProvider, Token } from '@hyperlane-xyz/sdk';
-import type { MultiProviderAdapter } from '@hyperlane-xyz/sdk/providers/MultiProviderAdapter';
-import { ProtocolType, assert, toWei } from '@hyperlane-xyz/utils';
+import {
+  type MultiProtocolProvider,
+  type MultiProvider,
+  Token,
+} from '@hyperlane-xyz/sdk';
+import { ProtocolType, assert } from '@hyperlane-xyz/utils';
 
 import { RebalancerConfig } from '../config/RebalancerConfig.js';
 import {
@@ -27,6 +30,7 @@ import { Metrics } from '../metrics/Metrics.js';
 import { type InventoryMonitorConfig, Monitor } from '../monitor/Monitor.js';
 import type { IActionTracker } from '../tracking/IActionTracker.js';
 import { InflightContextAdapter } from '../tracking/InflightContextAdapter.js';
+import { normalizeConfiguredAmount } from '../utils/balanceUtils.js';
 
 import type { RebalancerOrchestrator } from './RebalancerOrchestrator.js';
 
@@ -121,7 +125,7 @@ export class RebalancerService {
   private orchestrator?: RebalancerOrchestrator;
   constructor(
     private readonly multiProvider: MultiProvider,
-    private readonly multiProtocolProvider: MultiProviderAdapter | undefined,
+    private readonly multiProtocolProvider: MultiProtocolProvider | undefined,
     private readonly registry: IRegistry,
     private readonly rebalancerConfig: RebalancerConfig,
     private readonly config: RebalancerServiceConfig,
@@ -293,7 +297,7 @@ export class RebalancerService {
       const manualRoute: MovableCollateralRoute & { intentId: string } = {
         origin,
         destination,
-        amount: BigInt(toWei(amount, originToken.decimals)),
+        amount: normalizeConfiguredAmount(amount, originToken),
         executionType: 'movableCollateral',
         bridge,
         intentId: `manual-${Date.now()}`,

package/src/e2e/harness/TestHelpers.ts

@@ -25,9 +25,9 @@ export async function getFirstMonitorEvent(
   return new Promise((resolve, reject) => {
     let settled = false;
 
-    async function finalize(
-      cb: (v: any) => void, // eslint-disable-line @typescript-eslint/no-explicit-any -- accepts both resolve and reject
-      value: unknown,
+    async function finalize<T>(
+      cb: (v: T) => void,
+      value: T,
       timer: ReturnType<typeof setTimeout>,
     ) {
       if (settled) return;

package/src/factories/RebalancerContextFactory.test.ts

@@ -247,6 +247,78 @@ describe('RebalancerContextFactory', () => {
       expect(providerChains).to.include('arbitrum');
     });
 
+    it('should fail fast when bridgeMinAcceptedAmount is configured for a chain without a token', async () => {
+      const { multiProvider } = createMockMultiProvider([
+        { name: 'ethereum', protocol: ProtocolType.Ethereum },
+        { name: 'arbitrum', protocol: ProtocolType.Ethereum },
+      ]);
+
+      const config = createMockConfig();
+      config.strategyConfig[0].chains.arbitrum.bridgeMinAcceptedAmount = 1;
+
+      let error: Error | undefined;
+      try {
+        const factory = await createFactory(config, multiProvider, {
+          tokens: [
+            createToken(
+              'ethereum',
+              TEST_ADDRESSES.ethereum,
+              TokenStandard.EvmHypCollateral,
+            ),
+          ],
+        } as WarpCoreConfig);
+        await factory.createStrategy();
+      } catch (caught) {
+        error = caught as Error;
+      }
+
+      expect(error?.message).to.equal(
+        'No token found for configured strategy chain arbitrum in warp route USDC/paradex',
+      );
+    });
+
+    it('should fail fast when bridged supply is unavailable during initial collateral calculation', async () => {
+      const { multiProvider } = createMockMultiProvider([
+        { name: 'ethereum', protocol: ProtocolType.Ethereum },
+        { name: 'arbitrum', protocol: ProtocolType.Ethereum },
+      ]);
+
+      const factory = await createFactory(createMockConfig(), multiProvider, {
+        tokens: [
+          createToken(
+            'ethereum',
+            TEST_ADDRESSES.ethereum,
+            TokenStandard.EvmHypCollateral,
+          ),
+          createToken(
+            'arbitrum',
+            TEST_ADDRESSES.arbitrum,
+            TokenStandard.EvmHypSynthetic,
+          ),
+        ],
+      });
+
+      const collateralToken = factory
+        .getWarpCore()
+        .tokens.find((token) => token.chainName === 'ethereum');
+      assert(collateralToken, 'Expected ethereum collateral token in test');
+
+      sandbox.stub(collateralToken, 'getHypAdapter').returns({
+        getBridgedSupply: sandbox.stub().resolves(undefined),
+      } as any);
+
+      let error: Error | undefined;
+      try {
+        await factory.createStrategy();
+      } catch (caught) {
+        error = caught as Error;
+      }
+
+      expect(error?.message).to.equal(
+        'Missing bridged supply for ethereum while computing initial total collateral for warp route USDC/paradex',
+      );
+    });
+
     it('should fail early when inventory override origin protocol signer key is missing', async () => {
       const sealevelChain = 'solana';
       const evmChain = 'ethereum';
@@ -310,13 +382,70 @@ describe('RebalancerContextFactory', () => {
             : ProtocolType.Ethereum,
       }));
 
-      await expect(
-        (factory as any).createInventoryRebalancerAndConfig({} as any, {}),
-      ).to.be.rejectedWith(
+      let error: Error | undefined;
+      try {
+        await (factory as any).createInventoryRebalancerAndConfig(
+          {} as any,
+          {},
+        );
+      } catch (caught) {
+        error = caught as Error;
+      }
+
+      expect(error?.message).to.contain(
         `Missing inventory signer key for protocol ${ProtocolType.Sealevel}`,
       );
     });
 
+    it('should fail early when an inventory-relevant chain has no token', async () => {
+      const { multiProvider } = createMockMultiProvider([
+        { name: 'ethereum', protocol: ProtocolType.Ethereum },
+        { name: 'arbitrum', protocol: ProtocolType.Ethereum },
+      ]);
+
+      const config = {
+        ...createMockConfig(),
+        inventorySigners: {
+          [ProtocolType.Ethereum]: {
+            address: TEST_ADDRESSES.ethereum,
+            key: '0xabc123',
+          },
+        },
+      } as RebalancerConfig;
+      config.strategyConfig[0].chains.arbitrum.executionType =
+        ExecutionType.Inventory;
+
+      const factory = await createFactory(config, multiProvider, {
+        tokens: [
+          createToken(
+            'ethereum',
+            TEST_ADDRESSES.ethereum,
+            TokenStandard.EvmHypCollateral,
+          ),
+        ],
+      });
+
+      const getChainMetadataStub = factory.getWarpCore().multiProvider
+        .getChainMetadata as Sinon.SinonStub;
+      getChainMetadataStub.callsFake(() => ({
+        protocol: ProtocolType.Ethereum,
+      }));
+
+      let error: Error | undefined;
+      try {
+        await (factory as any).createInventoryRebalancerAndConfig(
+          {} as any,
+          {},
+        );
+      } catch (caught) {
+        error = caught as Error;
+      }
+
+      expect(error?.message).to.equal(
+        'No token found for inventory-relevant chain arbitrum in warp route USDC/paradex',
+      );
+    });
+
     it('should fail early when inventory chain uses unsupported protocol', async () => {
       const cosmosChain = 'cosmoshub';
       const evmChain = 'ethereum';
@@ -384,9 +513,17 @@ describe('RebalancerContextFactory', () => {
             : ProtocolType.Ethereum,
       }));
 
-      await expect(
-        (factory as any).createInventoryRebalancerAndConfig({} as any, {}),
-      ).to.be.rejectedWith(
+      let error: Error | undefined;
+      try {
+        await (factory as any).createInventoryRebalancerAndConfig(
+          {} as any,
+          {},
+        );
+      } catch (caught) {
+        error = caught as Error;
+      }
+
+      expect(error?.message).to.contain(
         `Inventory rebalancing does not support protocol '${ProtocolType.Cosmos}'`,
       );
     });

package/src/factories/RebalancerContextFactory.ts

@@ -11,14 +11,7 @@ import {
   WarpCore,
   type WarpCoreConfig,
 } from '@hyperlane-xyz/sdk';
-import type { MultiProviderAdapter } from '@hyperlane-xyz/sdk/providers/MultiProviderAdapter';
-import {
-  Address,
-  assert,
-  ProtocolType,
-  objMap,
-  toWei,
-} from '@hyperlane-xyz/utils';
+import { Address, assert, ProtocolType, objMap } from '@hyperlane-xyz/utils';
 
 import { LiFiBridge } from '../bridges/LiFiBridge.js';
 import { type RebalancerConfig } from '../config/RebalancerConfig.js';
@@ -64,6 +57,10 @@ import {
   ExplorerClient,
   type IExplorerClient,
 } from '../utils/ExplorerClient.js';
+import {
+  normalizeConfiguredAmount,
+  normalizeToCanonical,
+} from '../utils/balanceUtils.js';
 import { isCollateralizedTokenEligibleForRebalancing } from '../utils/tokenUtils.js';
 
 const DEFAULT_EXPLORER_URL =
@@ -75,7 +72,7 @@ export class RebalancerContextFactory {
    * @param warpCore - An instance of `WarpCore` configured for the specified `warpRouteId`.
    * @param tokensByChainName - A map of chain->token to ease the lookup of token by chain
    * @param multiProvider - MultiProvider instance (for movable collateral operations)
-   * @param multiProtocolProvider - MultiProviderAdapter instance (with mailbox metadata)
+   * @param multiProtocolProvider - MultiProtocolProvider instance (with mailbox metadata)
    * @param registry - IRegistry instance
    * @param logger - Logger instance
    */
@@ -84,7 +81,7 @@ export class RebalancerContextFactory {
     private readonly warpCore: WarpCore,
     private readonly tokensByChainName: ChainMap<Token>,
     private readonly multiProvider: MultiProvider,
-    private readonly multiProtocolProvider: MultiProviderAdapter,
+    private readonly multiProtocolProvider: MultiProtocolProvider,
     private readonly registry: IRegistry,
     private readonly logger: Logger,
     private readonly inventorySignerKeysByProtocol?: Partial<
@@ -95,14 +92,14 @@ export class RebalancerContextFactory {
   /**
    * @param config - The rebalancer config
    * @param multiProvider - MultiProvider instance (for movable collateral operations)
-   * @param multiProtocolProvider - MultiProviderAdapter instance (optional, created from multiProvider if not provided)
+   * @param multiProtocolProvider - MultiProtocolProvider instance (optional, created from multiProvider if not provided)
    * @param registry - IRegistry instance
    * @param logger - Logger instance
    */
   public static async create(
     config: RebalancerConfig,
     multiProvider: MultiProvider,
-    multiProtocolProvider: MultiProviderAdapter | undefined,
+    multiProtocolProvider: MultiProtocolProvider | undefined,
     registry: IRegistry,
     logger: Logger,
     inventorySignerKeysByProtocol?: Partial<Record<ProtocolType, string>>,
@@ -147,7 +144,7 @@ export class RebalancerContextFactory {
       multiProvider.getProvider(chain);
     }
 
-    // Create MultiProviderAdapter (convert from MultiProvider if not provided)
+    // Create MultiProtocolProvider (convert from MultiProvider if not provided)
     const mpp =
       multiProtocolProvider ??
       MultiProtocolProvider.fromMultiProvider(multiProvider);
@@ -253,9 +250,13 @@ export class RebalancerContextFactory {
       );
       if (chainConfig?.bridgeMinAcceptedAmount) {
         const token = this.tokensByChainName[chainName];
-        const decimals = token?.decimals ?? 18;
-        minAmountsByChain[chainName] = BigInt(
-          toWei(chainConfig.bridgeMinAcceptedAmount, decimals),
+        assert(
+          token,
+          `No token found for configured strategy chain ${chainName} in warp route ${this.config.warpRouteId}`,
+        );
+        minAmountsByChain[chainName] = normalizeConfiguredAmount(
+          chainConfig.bridgeMinAcceptedAmount,
+          token,
         );
       }
     }
@@ -460,6 +461,13 @@ export class RebalancerContextFactory {
       return null;
     }
 
+    for (const chain of allRelevantChains) {
+      assert(
+        this.tokensByChainName[chain],
+        `No token found for inventory-relevant chain ${chain} in warp route ${this.config.warpRouteId}`,
+      );
+    }
+
     const requiredProtocols = new Set(
       allRelevantChains.map((chain) => {
         const metadata = this.warpCore.multiProvider.getChainMetadata(chain);
@@ -762,7 +770,11 @@ export class RebalancerContextFactory {
         ) {
           const adapter = token.getHypAdapter(this.warpCore.multiProvider);
           const bridgedSupply = await adapter.getBridgedSupply();
-          initialTotalCollateral += bridgedSupply ?? 0n;
+          assert(
+            bridgedSupply !== undefined,
+            `Missing bridged supply for ${token.chainName} while computing initial total collateral for warp route ${this.config.warpRouteId}`,
+          );
+          initialTotalCollateral += normalizeToCanonical(bridgedSupply, token);
         }
       }),
     );

package/src/interfaces/IRebalancer.ts

@@ -1,5 +1,6 @@
 import {
   type EvmMovableCollateralAdapter,
+  type IToken,
   type TokenAmount,
 } from '@hyperlane-xyz/sdk';
 
@@ -48,10 +49,12 @@ export type IInventoryRebalancer = IRebalancer<
   InventoryExecutionResult
 >;
 
+type PreparedOriginTokenAmount = TokenAmount<IToken>;
+
 export type PreparedTransaction = {
   populatedTx: Awaited<
     ReturnType<EvmMovableCollateralAdapter['populateRebalanceTx']>
   >;
   route: MovableCollateralRoute & { intentId: string };
-  originTokenAmount: TokenAmount;
+  originTokenAmount: PreparedOriginTokenAmount;
 };

package/src/monitor/Monitor.ts

@@ -6,7 +6,7 @@ import {
   type Token,
   type WarpCore,
 } from '@hyperlane-xyz/sdk';
-import { Address, ProtocolType, sleep } from '@hyperlane-xyz/utils';
+import { Address, ProtocolType, fromWei, sleep } from '@hyperlane-xyz/utils';
 
 import {
   type ConfirmedBlockTag,
@@ -140,16 +140,29 @@ export class Monitor implements IMonitor {
           const inventoryBalances = await this.fetchInventoryBalances();
           if (Object.keys(inventoryBalances).length > 0) {
             event.inventoryBalances = inventoryBalances;
+            const tokensByChain = new Map(
+              this.warpCore.tokens.map((token) => [token.chainName, token]),
+            );
+            // CAST: inventoryBalances keys come from configured monitor chains,
+            // but Object.entries widens them to string.
+            const inventoryBalanceEntries = Object.entries(
+              inventoryBalances,
+            ) as [ChainName, bigint][];
             this.logger.info(
               {
                 chainsMonitored: Object.keys(inventoryBalances).length,
-                balances: Object.entries(inventoryBalances).map(
-                  ([chain, balance]) => ({
+                balances: inventoryBalanceEntries.map(([chain, balance]) => {
+                  const token = tokensByChain.get(chain);
+                  return {
                     chain,
+                    tokenSymbol: token?.symbol,
                     balance: balance.toString(),
-                    balanceEth: (Number(balance) / 1e18).toFixed(6),
-                  }),
-                ),
+                    balanceFormatted: fromWei(
+                      balance.toString(),
+                      token?.decimals,
+                    ),
+                  };
+                }),
               },
               'Inventory balances fetched',
             );