@hyperlane-xyz/rebalancer 27.2.12 → 27.2.13

package/src/strategy/BaseStrategy.ts

@@ -1,7 +1,6 @@
 import { type Logger } from 'pino';
 
 import type { ChainMap, ChainName, Token } from '@hyperlane-xyz/sdk';
-import { toWei } from '@hyperlane-xyz/utils';
 
 import type {
   IStrategy,
@@ -18,6 +17,7 @@ import {
   createStrategyRoute,
   getBridgeConfig,
 } from '../utils/bridgeUtils.js';
+import { normalizeConfiguredAmount } from '../utils/balanceUtils.js';
 
 export type Delta = { chain: ChainName; amount: bigint };
 
@@ -528,21 +528,24 @@ export abstract class BaseStrategy implements IStrategy {
             route.origin,
             route.destination,
           );
-          const minAmount = BigInt(
-            toWei(bridgeConfig.bridgeMinAcceptedAmount, token.decimals),
-          );
-          if (route.amount < minAmount) {
-            this.logger.info(
-              {
-                context: this.constructor.name,
-                origin: route.origin,
-                destination: route.destination,
-                amount: route.amount.toString(),
-                minAmount: minAmount.toString(),
-              },
-              'Dropping route below bridgeMinAcceptedAmount',
+          if (bridgeConfig.bridgeMinAcceptedAmount != null) {
+            const minAmount = normalizeConfiguredAmount(
+              bridgeConfig.bridgeMinAcceptedAmount,
+              token,
             );
-            return false;
+            if (route.amount < minAmount) {
+              this.logger.info(
+                {
+                  context: this.constructor.name,
+                  origin: route.origin,
+                  destination: route.destination,
+                  amount: route.amount.toString(),
+                  minAmount: minAmount.toString(),
+                },
+                'Dropping route below bridgeMinAcceptedAmount',
+              );
+              return false;
+            }
           }
         }
       }

package/src/strategy/CollateralDeficitStrategy.ts

@@ -1,7 +1,6 @@
 import { Logger } from 'pino';
 
 import { type ChainMap, type ChainName, type Token } from '@hyperlane-xyz/sdk';
-import { toWei } from '@hyperlane-xyz/utils';
 
 import {
   type CollateralDeficitStrategyConfig,
@@ -20,6 +19,7 @@ import {
   isInventoryConfig,
   isMovableCollateralConfig,
 } from '../utils/bridgeUtils.js';
+import { normalizeConfiguredAmount } from '../utils/balanceUtils.js';
 
 import { BaseStrategy, type Delta } from './BaseStrategy.js';
 
@@ -102,8 +102,9 @@ export class CollateralDeficitStrategy extends BaseStrategy {
     for (const chain of this.chains) {
       const balance = simulatedBalances[chain];
       const token = this.getTokenByChainName(chain);
-      const bufferWei = BigInt(
-        toWei(this.config[chain].buffer, token.decimals),
+      const bufferWei = normalizeConfiguredAmount(
+        this.config[chain].buffer,
+        token,
       );
 
       if (balance < 0n) {

package/src/strategy/MinAmountStrategy.test.ts

@@ -10,8 +10,10 @@ import {
 } from '@hyperlane-xyz/sdk';
 
 import { RebalancerMinAmountType } from '../config/types.js';
+import { type MonitorEvent } from '../interfaces/IMonitor.js';
 import type { RawBalances } from '../interfaces/IStrategy.js';
 import { extractBridgeConfigs } from '../test/helpers.js';
+import { getRawBalances } from '../utils/balanceUtils.js';
 
 import { MinAmountStrategy } from './MinAmountStrategy.js';
 
@@ -64,7 +66,6 @@ describe('MinAmountStrategy', () => {
       ).to.throw('At least two chains must be configured');
     });
 
-    // eslint-disable-next-line jest/expect-expect -- testing constructor doesn't throw
     it('should create a strategy with minAmount and target using absolute values', () => {
       new MinAmountStrategy(
         {
@@ -94,7 +95,6 @@ describe('MinAmountStrategy', () => {
       );
     });
 
-    // eslint-disable-next-line jest/expect-expect -- testing constructor doesn't throw
     it('should create a strategy with minAmount and target using relative values', () => {
       new MinAmountStrategy(
         {
@@ -415,6 +415,146 @@ describe('MinAmountStrategy', () => {
       ]);
     });
 
+    it('should normalize absolute thresholds for mixed-decimal routes', () => {
+      const mixedTokensByChainName: ChainMap<Token> = {
+        [chain1]: new Token({
+          ...tokenArgs,
+          chainName: chain1,
+          decimals: 18,
+          scale: { numerator: 1, denominator: 1_000_000_000_000 },
+        }),
+        [chain2]: new Token({
+          ...tokenArgs,
+          chainName: chain2,
+          decimals: 6,
+        }),
+      };
+      const config = {
+        [chain1]: {
+          minAmount: {
+            min: '100',
+            target: '120',
+            type: RebalancerMinAmountType.Absolute,
+          },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain2]: {
+          minAmount: {
+            min: '100',
+            target: '120',
+            type: RebalancerMinAmountType.Absolute,
+          },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+      };
+
+      const strategy = new MinAmountStrategy(
+        config,
+        mixedTokensByChainName,
+        250_000_000n,
+        testLogger,
+        extractBridgeConfigs(config),
+      );
+
+      const routes = strategy.getRebalancingRoutes({
+        [chain1]: 50_000_000n,
+        [chain2]: 200_000_000n,
+      });
+
+      expect(routes).to.deep.equal([
+        {
+          origin: chain2,
+          destination: chain1,
+          amount: 70_000_000n,
+          bridge: AddressZero,
+          executionType: 'movableCollateral',
+        },
+      ]);
+    });
+
+    it('normalizes mixed-decimal local balances before routing', () => {
+      const mixedTokensByChainName: ChainMap<Token> = {
+        [chain1]: new Token({
+          ...tokenArgs,
+          chainName: chain1,
+          standard: TokenStandard.EvmHypCollateral,
+          decimals: 18,
+          scale: { numerator: 1, denominator: 1_000_000_000_000 },
+        }),
+        [chain2]: new Token({
+          ...tokenArgs,
+          chainName: chain2,
+          standard: TokenStandard.EvmHypCollateral,
+          decimals: 6,
+        }),
+      };
+      const config = {
+        [chain1]: {
+          minAmount: {
+            min: '100',
+            target: '120',
+            type: RebalancerMinAmountType.Absolute,
+          },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+        [chain2]: {
+          minAmount: {
+            min: '100',
+            target: '120',
+            type: RebalancerMinAmountType.Absolute,
+          },
+          bridge: AddressZero,
+          bridgeLockTime: 1,
+        },
+      };
+
+      const strategy = new MinAmountStrategy(
+        config,
+        mixedTokensByChainName,
+        250_000_000n,
+        testLogger,
+        extractBridgeConfigs(config),
+      );
+
+      const event: MonitorEvent = {
+        tokensInfo: [
+          {
+            token: mixedTokensByChainName[chain1],
+            bridgedSupply: 50_000_000_000_000_000_000n,
+          },
+          {
+            token: mixedTokensByChainName[chain2],
+            bridgedSupply: 200_000_000n,
+          },
+        ],
+        confirmedBlockTags: {
+          [chain1]: 1,
+          [chain2]: 1,
+        },
+      };
+
+      const rawBalances = getRawBalances([chain1, chain2], event, testLogger);
+      expect(rawBalances).to.deep.equal({
+        [chain1]: 50_000_000n,
+        [chain2]: 200_000_000n,
+      });
+
+      const routes = strategy.getRebalancingRoutes(rawBalances);
+
+      expect(routes).to.deep.equal([
+        {
+          origin: chain2,
+          destination: chain1,
+          amount: 70_000_000n,
+          bridge: AddressZero,
+          executionType: 'movableCollateral',
+        },
+      ]);
+    });
+
     it('should return multiple routes for multiple chains below minimum amount', () => {
       const config = {
         [chain1]: {
@@ -514,6 +654,102 @@ describe('MinAmountStrategy', () => {
       );
     });
 
+    it('should keep minAmount validation errors human-readable for mixed-decimal routes', () => {
+      const mixedTokensByChainName: ChainMap<Token> = {
+        [chain1]: new Token({
+          ...tokenArgs,
+          chainName: chain1,
+          decimals: 18,
+          scale: { numerator: 1, denominator: 1_000_000_000_000 },
+        }),
+        [chain2]: new Token({
+          ...tokenArgs,
+          chainName: chain2,
+          decimals: 6,
+        }),
+      };
+
+      expect(
+        () =>
+          new MinAmountStrategy(
+            {
+              [chain1]: {
+                minAmount: {
+                  min: '100',
+                  target: '120',
+                  type: RebalancerMinAmountType.Absolute,
+                },
+                bridge: AddressZero,
+                bridgeLockTime: 1,
+              },
+              [chain2]: {
+                minAmount: {
+                  min: '100',
+                  target: '120',
+                  type: RebalancerMinAmountType.Absolute,
+                },
+                bridge: AddressZero,
+                bridgeLockTime: 1,
+              },
+            },
+            mixedTokensByChainName,
+            230_000_000n,
+            testLogger,
+            {},
+          ),
+      ).to.throw(
+        `Consider reducing the targets as the sum (240) is greater than sum of collaterals (230)`,
+      );
+    });
+
+    it('should keep fractional minAmount validation errors human-readable across heterogeneous decimals', () => {
+      const mixedTokensByChainName: ChainMap<Token> = {
+        [chain1]: new Token({
+          ...tokenArgs,
+          chainName: chain1,
+          decimals: 6,
+        }),
+        [chain2]: new Token({
+          ...tokenArgs,
+          chainName: chain2,
+          decimals: 18,
+          scale: { numerator: 1, denominator: 1_000_000_000_000 },
+        }),
+      };
+
+      expect(
+        () =>
+          new MinAmountStrategy(
+            {
+              [chain1]: {
+                minAmount: {
+                  min: '100',
+                  target: '120.25',
+                  type: RebalancerMinAmountType.Absolute,
+                },
+                bridge: AddressZero,
+                bridgeLockTime: 1,
+              },
+              [chain2]: {
+                minAmount: {
+                  min: '100',
+                  target: '120.25',
+                  type: RebalancerMinAmountType.Absolute,
+                },
+                bridge: AddressZero,
+                bridgeLockTime: 1,
+              },
+            },
+            mixedTokensByChainName,
+            230_500_000n,
+            testLogger,
+            {},
+          ),
+      ).to.throw(
+        `Consider reducing the targets as the sum (240.5) is greater than sum of collaterals (230.5)`,
+      );
+    });
+
     it('should handle case where there is not enough surplus to meet all minimum requirements by scaling down deficits', () => {
       const config = {
         [chain1]: {

package/src/strategy/MinAmountStrategy.ts

@@ -1,8 +1,12 @@
 import { BigNumber } from 'bignumber.js';
 import { type Logger } from 'pino';
 
-import { type ChainMap, type Token } from '@hyperlane-xyz/sdk';
-import { fromWei, toWei } from '@hyperlane-xyz/utils';
+import {
+  localAmountFromMessage,
+  type ChainMap,
+  type Token,
+} from '@hyperlane-xyz/sdk';
+import { fromWei } from '@hyperlane-xyz/utils';
 
 import {
   type MinAmountStrategyConfig,
@@ -16,6 +20,7 @@ import type {
 } from '../interfaces/IStrategy.js';
 import { type Metrics } from '../metrics/Metrics.js';
 import type { BridgeConfigWithOverride } from '../utils/bridgeUtils.js';
+import { normalizeConfiguredAmount } from '../utils/balanceUtils.js';
 
 import { BaseStrategy, type Delta } from './BaseStrategy.js';
 
@@ -116,9 +121,13 @@ export class MinAmountStrategy extends BaseStrategy {
         if (chainConfig.minAmount.type === RebalancerMinAmountType.Absolute) {
           const token = this.getTokenByChainName(chain);
 
-          minAmount = BigInt(toWei(chainConfig.minAmount.min, token.decimals));
-          targetAmount = BigInt(
-            toWei(chainConfig.minAmount.target, token.decimals),
+          minAmount = normalizeConfiguredAmount(
+            chainConfig.minAmount.min,
+            token,
+          );
+          targetAmount = normalizeConfiguredAmount(
+            chainConfig.minAmount.target,
+            token,
           );
         } else {
           minAmount = BigInt(
@@ -172,29 +181,32 @@ export class MinAmountStrategy extends BaseStrategy {
 
     if (minAmountType === RebalancerMinAmountType.Absolute) {
       let totalTargets = 0n;
-      let decimals: number = 0;
+      const displayToken = this.getTokenByChainName(this.chains[0]);
 
       for (const chainName of this.chains) {
         const token = this.getTokenByChainName(chainName);
-        // all the tokens have the same amount of decimals
-        decimals = token.decimals;
-
-        totalTargets += BigInt(
-          toWei(config[chainName].minAmount.target, token.decimals),
+        totalTargets += normalizeConfiguredAmount(
+          config[chainName].minAmount.target,
+          token,
         );
       }
 
       if (totalTargets > totalCollateral) {
         throw new Error(
-          `Consider reducing the targets as the sum (${fromWei(
-            totalTargets.toString(),
-            decimals,
-          )}) is greater than sum of collaterals (${fromWei(
-            totalCollateral.toString(),
-            decimals,
+          `Consider reducing the targets as the sum (${this.formatCanonicalAmount(
+            totalTargets,
+            displayToken,
+          )}) is greater than sum of collaterals (${this.formatCanonicalAmount(
+            totalCollateral,
+            displayToken,
           )})`,
         );
       }
     }
   }
+
+  private formatCanonicalAmount(amount: bigint, token: Token): string {
+    const localAmount = localAmountFromMessage(amount, token.scale);
+    return fromWei(localAmount.toString(), token.decimals);
+  }
 }

package/src/test/helpers.ts

@@ -6,10 +6,11 @@ import {
   type ChainMetadata,
   type ChainName,
   EvmMovableCollateralAdapter,
+  type IToken,
   type InterchainGasQuote,
   type MultiProvider,
   type Token,
-  type TokenAmount,
+  TokenAmount,
   type WarpCore,
 } from '@hyperlane-xyz/sdk';
 
@@ -115,17 +116,14 @@ export function buildTestPreparedTransaction(
 
 // === Mock Factories ===
 
-export function createMockTokenAmount(amount: bigint): TokenAmount {
-  return {
-    amount,
-    token: {
-      name: 'TestToken',
-      symbol: 'TEST',
-      decimals: 18,
-      addressOrDenom: TEST_ADDRESSES.token,
-    },
-    getDecimalFormattedAmount: () => ethers.utils.formatEther(amount),
-  } as unknown as TokenAmount;
+export function createMockTokenAmount(amount: bigint): TokenAmount<IToken> {
+  const token = {
+    name: 'TestToken',
+    symbol: 'TEST',
+    decimals: 18,
+    addressOrDenom: TEST_ADDRESSES.token,
+  } as IToken;
+  return new TokenAmount(amount, token);
 }
 
 export interface MockAdapterConfig {
@@ -173,6 +171,7 @@ export interface MockTokenConfig {
   name?: string;
   decimals?: number;
   addressOrDenom?: string;
+  scale?: Token['scale'];
   adapter?: ReturnType<typeof createMockAdapter>;
 }
 
@@ -181,6 +180,7 @@ export function createMockToken(config: MockTokenConfig = {}) {
     name = 'TestToken',
     decimals = 18,
     addressOrDenom = TEST_ADDRESSES.token,
+    scale,
     adapter = createMockAdapter(),
   } = config;
 
@@ -188,6 +188,7 @@ export function createMockToken(config: MockTokenConfig = {}) {
     name,
     decimals,
     addressOrDenom,
+    scale,
     amount: (amt: bigint) => createMockTokenAmount(amt),
     getHypAdapter: Sinon.stub().returns(adapter),
   };

package/src/test/lifiMocks.ts

@@ -128,15 +128,18 @@ export function createMockBridgeQuote(
   const route = overrides?.route as
     | { action?: { fromChainId?: number; toChainId?: number } }
     | undefined;
+  const usesReverseQuote = overrides?.requestParams?.toAmount !== undefined;
 
   const defaultRequestParams: BridgeQuoteParams = {
     fromChain: 42161,
     toChain: 1399811149,
     fromToken: '0xCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC',
     toToken: '0xCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC',
-    fromAddress: '0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
     toAddress: '0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
-    fromAmount: 10000000000n,
+    fromAddress: '0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+    ...(usesReverseQuote
+      ? { toAmount: 9950000000n }
+      : { fromAmount: 10000000000n }),
   };
   const requestParams: BridgeQuoteParams = {
     ...defaultRequestParams,

package/src/tracking/ActionTracker.test.ts

@@ -807,6 +807,53 @@ describe('ActionTracker', () => {
       expect(partialIntents[0].remaining).to.equal(600000000000000000n); // 0.6 ETH remaining
     });
 
+    it('ignores inventory_movement amounts when computing remaining', async () => {
+      await rebalanceIntentStore.save({
+        id: 'partial-intent-with-movement',
+        status: 'in_progress',
+        origin: 1,
+        destination: 2,
+        amount: 1000000000000000000n,
+        executionMethod: 'inventory',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      });
+
+      await rebalanceActionStore.save({
+        id: 'action-deposit',
+        type: 'inventory_deposit',
+        status: 'complete',
+        intentId: 'partial-intent-with-movement',
+        origin: 1,
+        destination: 2,
+        amount: 400000000000000000n,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      });
+
+      await rebalanceActionStore.save({
+        id: 'action-movement',
+        type: 'inventory_movement',
+        status: 'complete',
+        intentId: 'partial-intent-with-movement',
+        origin: 3,
+        destination: 2,
+        amount: 9000000000000000000n,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      });
+
+      const partialIntents =
+        await tracker.getPartiallyFulfilledInventoryIntents();
+
+      expect(partialIntents).to.have.lengthOf(1);
+      expect(partialIntents[0].intent.id).to.equal(
+        'partial-intent-with-movement',
+      );
+      expect(partialIntents[0].completedAmount).to.equal(400000000000000000n);
+      expect(partialIntents[0].remaining).to.equal(600000000000000000n);
+    });
+
     it('does not return non-inventory intents', async () => {
       // Create a not_started intent without executionMethod: 'inventory'
       await rebalanceIntentStore.save({

package/src/tracking/ActionTracker.ts

@@ -636,7 +636,8 @@ export class ActionTracker implements IActionTracker {
         );
       }
 
-      // Compute amounts from action states
+      // Only inventory_deposit amounts advance fulfillment. inventory_movement
+      // amounts stay in source-local units and only gate retries/stale cleanup.
       const completedAmount = actions
         .filter(
           (a) => a.status === 'complete' && a.type === 'inventory_deposit',

package/src/utils/balanceUtils.test.ts

@@ -6,7 +6,15 @@ import { type ChainName, type Token, TokenStandard } from '@hyperlane-xyz/sdk';
 
 import { type MonitorEvent } from '../interfaces/IMonitor.js';
 
-import { getRawBalances } from './balanceUtils.js';
+import {
+  alignLocalToCanonical,
+  denormalizeToLocal,
+  getRawBalances,
+  isIdentityScale,
+  getTokenScale,
+  normalizeConfiguredAmount,
+  normalizeToCanonical,
+} from './balanceUtils.js';
 
 const testLogger = pino({ level: 'silent' });
 
@@ -45,6 +53,16 @@ describe('getRawBalances', () => {
     });
   });
 
+  it('should normalize bridged supply to canonical units when token has scale', () => {
+    token.scale = { numerator: 1, denominator: 1_000_000_000_000 };
+    tokenBridgedSupply = 1_000_000_000_000_000_000n;
+    event.tokensInfo[0].bridgedSupply = tokenBridgedSupply;
+
+    expect(getRawBalances(chains, event, testLogger)).to.deep.equal({
+      mainnet: 1_000_000n,
+    });
+  });
+
   it('should return the bridged supply for the token (EvmHypNative)', () => {
     token.standard = TokenStandard.EvmHypNative;
 
@@ -73,3 +91,71 @@ describe('getRawBalances', () => {
     );
   });
 });
+
+describe('scale helpers', () => {
+  const token = {
+    decimals: 18,
+    scale: { numerator: 1, denominator: 1_000_000_000_000 },
+  } as unknown as Token;
+
+  it('normalizes local amount to canonical amount', () => {
+    expect(normalizeToCanonical(1_000_000_000_000_000_000n, token)).to.equal(
+      1_000_000n,
+    );
+  });
+
+  it('denormalizes canonical amount to local amount', () => {
+    expect(denormalizeToLocal(1_000_000n, token)).to.equal(
+      1_000_000_000_000_000_000n,
+    );
+  });
+
+  it('aligns local amount to exact canonical progress', () => {
+    expect(alignLocalToCanonical(999_999_999_999n, token)).to.deep.equal({
+      localAmount: 0n,
+      messageAmount: 0n,
+    });
+    expect(
+      alignLocalToCanonical(1_000_000_000_000_500_000n, token),
+    ).to.deep.equal({
+      localAmount: 1_000_000_000_000_000_000n,
+      messageAmount: 1_000_000n,
+    });
+  });
+
+  it('returns identity scale when scale is undefined', () => {
+    expect(getTokenScale({} as Token)).to.deep.equal({
+      numerator: 1n,
+      denominator: 1n,
+    });
+  });
+
+  it('treats equivalent ratios as identity scale', () => {
+    expect(isIdentityScale({} as Token)).to.be.true;
+    expect(
+      isIdentityScale({
+        scale: { numerator: 1, denominator: 1 },
+      } as Token),
+    ).to.be.true;
+    expect(
+      isIdentityScale({
+        scale: { numerator: 5, denominator: 5 },
+      } as Token),
+    ).to.be.true;
+    expect(
+      isIdentityScale({
+        scale: { numerator: 10, denominator: 20 },
+      } as Token),
+    ).to.be.false;
+  });
+
+  it('normalizes configured amount using token decimals and scale', () => {
+    expect(normalizeConfiguredAmount('1', token)).to.equal(1_000_000n);
+  });
+
+  it('normalizes sub-unit local dust to zero canonical amount', () => {
+    expect(normalizeConfiguredAmount('0.000000000000000001', token)).to.equal(
+      0n,
+    );
+  });
+});