@humanode-hyperlane/rebalancer 27.2.2 → 1029.1.0

package/src/tracking/pendingTransferMiddlewares/types.ts

@@ -0,0 +1,3 @@
+export function normalizeMessageId(messageId: string): string {
+  return messageId.toLowerCase();
+}

package/src/utils/ExplorerClient.test.ts

@@ -160,6 +160,48 @@ describe('ExplorerClient', () => {
   });
 
   describe('getInflightRebalanceActions address encoding', () => {
+    it('skips empty bridge discovery and queries freshly for supplied bridges', async () => {
+      const client = new ExplorerClient(
+        'https://explorer.test',
+        () => ProtocolType.Ethereum,
+      );
+      const bridges: string[] = [];
+      const params = {
+        bridges,
+        routersByDomain: { 1: '0x1234567890abcdef1234567890abcdef12345678' },
+        rebalancerAddress: '0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',
+      };
+      fetchStub.rejects(new Error('offline'));
+      expect(
+        await client.getInflightRebalanceActions(params, testLogger),
+      ).to.deep.equal([]);
+      expect(fetchStub.called).to.be.false;
+      bridges.push('0x1234567890abcdef1234567890abcdef12345678');
+      await expect(
+        client.getInflightRebalanceActions(params, testLogger),
+      ).to.be.rejectedWith('offline');
+      expect(fetchStub.calledOnce).to.be.true;
+    });
+
+    it('preserves HTTP failures for nonempty bridge discovery', async () => {
+      const client = new ExplorerClient(
+        'https://explorer.test',
+        () => ProtocolType.Ethereum,
+      );
+      fetchStub.resolves(new Response('unavailable', { status: 503 }));
+      await expect(
+        client.getInflightRebalanceActions(
+          {
+            bridges: ['0x1234567890abcdef1234567890abcdef12345678'],
+            routersByDomain: {},
+            rebalancerAddress: '0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',
+          },
+          testLogger,
+        ),
+      ).to.be.rejectedWith('Explorer query failed: 503');
+      expect(fetchStub.calledOnce).to.be.true;
+    });
+
     it('encodes mixed EVM+Solana routersByDomain in originTxRecipients', async () => {
       const evmAddr = '0x5a0e13290ec57f5e9031d01d03c6a40029cc24ea';
       const solAddr = 'E5rVV8zXwtc4TKGypCJvSBaYbgxa4XaYg5MS6N9QGdeo';

package/src/utils/ExplorerClient.ts

@@ -6,6 +6,10 @@ import {
   ProtocolType,
 } from '@humanode-hyperlane/utils';
 
+const HEX_PREFIX_REGEX = /^0x/i;
+
+export const DEFAULT_INFLIGHT_USER_TRANSFER_LIMIT = 100;
+
 export type InflightRebalanceQueryParams = {
   bridges: string[];
   routersByDomain: Record<number, string>; // Domain ID → router address (derive routers and domains from this)
@@ -71,9 +75,9 @@ export class ExplorerClient implements IExplorerClient {
       domain !== undefined ? this.getProtocol(domain) : undefined;
     if (protocol && !isEVMLike(protocol)) {
       const hex = addressToByteHexString(addr, protocol);
-      return hex.replace(/^0x/i, '\\x').toLowerCase();
+      return hex.replace(HEX_PREFIX_REGEX, '\\x').toLowerCase();
     }
-    return addr.replace(/^0x/i, '\\x').toLowerCase();
+    return addr.replace(HEX_PREFIX_REGEX, '\\x').toLowerCase();
   }
 
   /**
@@ -230,7 +234,11 @@ export class ExplorerClient implements IExplorerClient {
     params: UserTransferQueryParams,
     logger: Logger,
   ): Promise<ExplorerMessage[]> {
-    const { routersByDomain, excludeTxSenders, limit = 100 } = params;
+    const {
+      routersByDomain,
+      excludeTxSenders,
+      limit = DEFAULT_INFLIGHT_USER_TRANSFER_LIMIT,
+    } = params;
 
     // Derive routers and domains from routersByDomain
     const routerEntries = Object.entries(routersByDomain);
@@ -337,6 +345,9 @@ export class ExplorerClient implements IExplorerClient {
       limit = 100,
     } = params;
 
+    // Both sender and recipient must belong to bridges; an empty set cannot match.
+    if (bridges.length === 0) return [];
+
     // Derive routers and domains from routersByDomain
     const routerEntries = Object.entries(routersByDomain);
     const domains = Object.keys(routersByDomain).map(Number);

package/src/utils/balanceUtils.test.ts

@@ -10,7 +10,15 @@ import {
 
 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' });
 
@@ -49,6 +57,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;
 
@@ -77,3 +95,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,
+    );
+  });
+});

package/src/utils/balanceUtils.ts

@@ -1,12 +1,68 @@
 import { type Logger } from 'pino';
 
-import { type ChainName } from '@humanode-hyperlane/sdk';
+import {
+  type IToken,
+  alignLocalAmountToMessage,
+  messageAmountFromLocal,
+  minLocalAmountForMessage,
+  normalizeScale,
+  scalesEqual,
+  type ChainName,
+  type NormalizedScale,
+  type ScaleAlignment,
+  type Token,
+} from '@humanode-hyperlane/sdk';
+import { toWei } from '@humanode-hyperlane/utils';
 
 import { type MonitorEvent } from '../interfaces/IMonitor.js';
 import { type RawBalances } from '../interfaces/IStrategy.js';
 
 import { isCollateralizedTokenEligibleForRebalancing } from './tokenUtils.js';
 
+export function getTokenScale(token: Token): NormalizedScale {
+  return normalizeScale(token.scale);
+}
+
+export function isIdentityScale(token: Token): boolean {
+  return scalesEqual(token.scale, undefined);
+}
+
+export function normalizeToCanonical(
+  localAmount: bigint,
+  tokenOrScale: Token | IToken | NormalizedScale,
+): bigint {
+  return messageAmountFromLocal(localAmount, getScaleInput(tokenOrScale));
+}
+
+export function denormalizeToLocal(
+  canonicalAmount: bigint,
+  tokenOrScale: Token | IToken | NormalizedScale,
+): bigint {
+  // Use ceil semantics so the returned local amount always produces at least
+  // the requested canonical progress once the token router floors on outbound.
+  return minLocalAmountForMessage(canonicalAmount, getScaleInput(tokenOrScale));
+}
+
+export function alignLocalToCanonical(
+  localAmount: bigint,
+  tokenOrScale: Token | IToken | NormalizedScale,
+): ScaleAlignment {
+  return alignLocalAmountToMessage(localAmount, getScaleInput(tokenOrScale));
+}
+
+export function normalizeConfiguredAmount(
+  amount: string | number,
+  token: Token,
+): bigint {
+  return normalizeToCanonical(BigInt(toWei(amount, token.decimals)), token);
+}
+
+function getScaleInput(tokenOrScale: Token | IToken | NormalizedScale) {
+  return 'numerator' in tokenOrScale && 'denominator' in tokenOrScale
+    ? tokenOrScale
+    : tokenOrScale.scale;
+}
+
 /**
  * Returns the raw balances required by the strategies from the monitor event
  * @param chains - The chains that should be included in the raw balances (e.g. the chains in the rebalancer config)
@@ -58,7 +114,22 @@ export function getRawBalances(
       );
     }
 
-    balances[token.chainName] = bridgedSupply;
+    const normalizedBalance = normalizeToCanonical(bridgedSupply, token);
+    balances[token.chainName] = normalizedBalance;
+
+    if (!isIdentityScale(token)) {
+      logger.debug(
+        {
+          context: getRawBalances.name,
+          chain: token.chainName,
+          tokenSymbol: token.symbol,
+          bridgedSupply: bridgedSupply.toString(),
+          normalizedBalance: normalizedBalance.toString(),
+          scale: getTokenScale(token),
+        },
+        'Normalized bridged supply to canonical units',
+      );
+    }
   }
 
   return balances;

package/src/utils/blockTag.test.ts

@@ -0,0 +1,173 @@
+import chai, { expect } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+import { providers } from 'ethers';
+import { pino } from 'pino';
+import Sinon from 'sinon';
+
+import {
+  type ChainMetadata,
+  EthJsonRpcBlockParameterTag,
+  MultiProtocolProvider,
+} from '@humanode-hyperlane/sdk';
+import { ProtocolType } from '@humanode-hyperlane/utils';
+
+import { getConfirmedBlockTag } from './blockTag.js';
+
+chai.use(chaiAsPromised);
+
+const tronMetadata: ChainMetadata = {
+  protocol: ProtocolType.Tron,
+  name: 'tron',
+  chainId: 728126428,
+  domainId: 728126428,
+  rpcUrls: [{ http: 'http://unused' }],
+  blocks: { reorgPeriod: 20, confirmations: 1 },
+};
+
+const logger = pino({ level: 'silent' });
+
+describe('getConfirmedBlockTag', () => {
+  let mpp: Sinon.SinonStubbedInstance<MultiProtocolProvider>;
+  let provider: Sinon.SinonStubbedInstance<providers.JsonRpcProvider>;
+
+  beforeEach(() => {
+    mpp = Sinon.createStubInstance(MultiProtocolProvider);
+    provider = Sinon.createStubInstance(providers.JsonRpcProvider);
+    mpp.getChainMetadata.returns(tronMetadata);
+    mpp.getEthersV5Provider.returns(provider);
+    provider.send.resolves('0x64');
+  });
+
+  afterEach(() => {
+    Sinon.restore();
+  });
+
+  it('returns a confirmed block number for a numeric Tron reorg period', async () => {
+    expect(await getConfirmedBlockTag(mpp, 'tron')).to.equal(80);
+  });
+
+  it('clamps a confirmed block number to zero', async () => {
+    provider.send.resolves('0x0a');
+    expect(await getConfirmedBlockTag(mpp, 'tron')).to.equal(0);
+  });
+
+  it('uses the default numeric reorg period for Tron', async () => {
+    mpp.getChainMetadata.returns({ ...tronMetadata, blocks: undefined });
+    expect(await getConfirmedBlockTag(mpp, 'tron')).to.equal(68);
+  });
+
+  it('returns undefined for a non-EVM-like chain without querying blocks', async () => {
+    mpp.getChainMetadata.returns({
+      ...tronMetadata,
+      protocol: ProtocolType.Sealevel,
+      name: 'solana',
+    });
+
+    expect(await getConfirmedBlockTag(mpp, 'solana')).to.equal(undefined);
+    expect(mpp.getEthersV5Provider.notCalled).to.equal(true);
+  });
+
+  it('preserves the optional Tron tag for unsupported named reorg periods', async () => {
+    const warn = Sinon.stub(logger, 'warn');
+    mpp.getChainMetadata.returns({
+      ...tronMetadata,
+      blocks: {
+        reorgPeriod: EthJsonRpcBlockParameterTag.Finalized,
+        confirmations: 1,
+      },
+    });
+
+    expect(await getConfirmedBlockTag(mpp, 'tron', logger)).to.equal(undefined);
+    expect(mpp.getEthersV5Provider.notCalled).to.equal(true);
+    expect(warn.calledOnce).to.equal(true);
+    expect(warn.firstCall.args[1]).to.include(
+      'Tron does not support named block tags',
+    );
+  });
+
+  it('propagates failed numeric Tron block reads', async () => {
+    const failure = new Error('block unavailable');
+    const warn = Sinon.stub(logger, 'warn');
+    provider.send.rejects(failure);
+
+    await expect(getConfirmedBlockTag(mpp, 'tron', logger)).to.be.rejectedWith(
+      failure,
+    );
+    expect(warn.calledOnce).to.equal(true);
+    expect(warn.firstCall.args[1]).to.equal('Failed to get confirmed block');
+  });
+
+  it('propagates provider lookup failures in numeric Tron mode', async () => {
+    const failure = new Error('provider unavailable');
+    mpp.getEthersV5Provider.throws(failure);
+
+    await expect(getConfirmedBlockTag(mpp, 'tron')).to.be.rejectedWith(failure);
+  });
+
+  for (const invalidResponse of [
+    undefined,
+    null,
+    100,
+    '100',
+    '0x',
+    '0xgg',
+    '0x10000000000000000',
+    `0x${'f'.repeat(300)}`,
+  ]) {
+    it(`rejects an invalid Tron block response (${typeof invalidResponse}): ${String(invalidResponse).slice(0, 32)}`, async () => {
+      provider.send.resolves(invalidResponse);
+      await expect(getConfirmedBlockTag(mpp, 'tron')).to.be.rejectedWith(
+        'Invalid',
+      );
+    });
+  }
+
+  it('rejects an invalid numeric block from a non-JSON-RPC provider', async () => {
+    const fallbackProvider = Sinon.createStubInstance(providers.BaseProvider);
+    fallbackProvider.getBlockNumber.resolves(Number.NaN);
+    mpp.getEthersV5Provider.returns(fallbackProvider);
+
+    await expect(getConfirmedBlockTag(mpp, 'tron')).to.be.rejectedWith(
+      'Invalid block number for tron: NaN',
+    );
+  });
+
+  it('preserves undefined on an Ethereum lookup failure', async () => {
+    mpp.getChainMetadata.returns({
+      ...tronMetadata,
+      protocol: ProtocolType.Ethereum,
+      name: 'ethereum',
+    });
+    provider.send.rejects(new Error('block unavailable'));
+
+    expect(await getConfirmedBlockTag(mpp, 'ethereum')).to.equal(undefined);
+  });
+
+  it('preserves Ethereum named block tags', async () => {
+    mpp.getChainMetadata.returns({
+      ...tronMetadata,
+      protocol: ProtocolType.Ethereum,
+      name: 'ethereum',
+      blocks: {
+        reorgPeriod: EthJsonRpcBlockParameterTag.Finalized,
+        confirmations: 1,
+      },
+    });
+
+    expect(await getConfirmedBlockTag(mpp, 'ethereum')).to.equal(
+      EthJsonRpcBlockParameterTag.Finalized,
+    );
+    expect(mpp.getEthersV5Provider.notCalled).to.equal(true);
+  });
+
+  it('preserves undefined on metadata lookup failures', async () => {
+    const failure = new Error('metadata unavailable');
+    mpp.getChainMetadata.throws(failure);
+
+    const warn = Sinon.stub(logger, 'warn');
+    expect(await getConfirmedBlockTag(mpp, 'tron', logger)).to.equal(undefined);
+    expect(warn.calledOnce).to.equal(true);
+    expect(warn.firstCall.args[1]).to.equal('Failed to get confirmed block');
+    expect(mpp.getEthersV5Provider.notCalled).to.equal(true);
+  });
+});

package/src/utils/blockTag.ts

@@ -4,65 +4,85 @@ import { providers } from 'ethers';
 
 import {
   EthJsonRpcBlockParameterTag,
-  MultiProtocolProvider,
+  type MultiProtocolProvider,
 } from '@humanode-hyperlane/sdk';
-import { ProtocolType } from '@humanode-hyperlane/utils';
+import { isEVMLike, ProtocolType } from '@humanode-hyperlane/utils';
 import type { ConfirmedBlockTag } from '../interfaces/IMonitor.js';
 
+const HEX_BLOCK_NUMBER_REGEX = /^0x[0-9a-fA-F]+$/;
+
 /**
  * Get the confirmed block tag for a chain, accounting for reorg period.
  * Returns a block number that is safe from reorgs, or a named tag like 'finalized'.
  *
- * @param multiProvider - MultiProtocolProvider instance
+ * @param multiProvider - Provider registry with chain metadata and ethers access
  * @param chainName - Name of the chain
  * @param logger - Optional logger for warnings
- * @returns Confirmed block tag (number, named tag, or undefined on error)
+ * @returns Confirmed block tag, or undefined for optional tags, metadata errors or failed Ethereum lookups.
+ * @throws If a numeric Tron block lookup fails.
  */
 export async function getConfirmedBlockTag(
-  multiProvider: MultiProtocolProvider,
+  multiProvider: Pick<
+    MultiProtocolProvider,
+    'getChainMetadata' | 'getEthersV5Provider'
+  >,
   chainName: string,
   logger?: Logger,
 ): Promise<ConfirmedBlockTag> {
+  let numericTronLookup = false;
   try {
     const metadata = multiProvider.getChainMetadata(chainName);
 
-    // Only EVM chains support block tag queries
-    if (metadata.protocol !== ProtocolType.Ethereum) {
+    // Only EVM-like chains support block tag queries (e.g., Ethereum, Tron).
+    // Tron uses TronJsonRpcProvider which supports eth_blockNumber
+    if (!isEVMLike(metadata.protocol)) {
       return undefined;
     }
 
     const reorgPeriod = metadata.blocks?.reorgPeriod ?? 32;
     if (typeof reorgPeriod === 'string') {
+      if (metadata.protocol === ProtocolType.Tron) {
+        logger?.warn(
+          { chain: chainName, reorgPeriod },
+          'Tron does not support named block tags — ignoring string reorgPeriod, using latest block',
+        );
+        return undefined;
+      }
       return reorgPeriod as EthJsonRpcBlockParameterTag;
     }
 
+    numericTronLookup = metadata.protocol === ProtocolType.Tron;
     const provider = multiProvider.getEthersV5Provider(chainName);
     let latestBlock: number;
     if (provider instanceof providers.JsonRpcProvider) {
       const latestBlockHex = await provider.send('eth_blockNumber', []);
       if (
         typeof latestBlockHex !== 'string' ||
-        !/^0x[0-9a-fA-F]+$/.test(latestBlockHex)
+        !HEX_BLOCK_NUMBER_REGEX.test(latestBlockHex)
       ) {
         throw new Error(
           `Invalid eth_blockNumber response for ${chainName}: ${latestBlockHex}`,
         );
       }
       latestBlock = parseInt(latestBlockHex, 16);
-      if (!Number.isFinite(latestBlock)) {
-        throw new Error(
-          `Parsed block number is not finite for ${chainName}: ${latestBlockHex}`,
-        );
-      }
     } else {
       latestBlock = await provider.getBlockNumber();
     }
+    if (!Number.isSafeInteger(latestBlock) || latestBlock < 0) {
+      throw new Error(`Invalid block number for ${chainName}: ${latestBlock}`);
+    }
     return Math.max(0, latestBlock - reorgPeriod);
   } catch (error) {
     logger?.warn(
-      { chain: chainName, error: (error as Error).message },
-      'Failed to get confirmed block, using latest',
+      {
+        chain: chainName,
+        error: error instanceof Error ? error.message : String(error),
+      },
+      'Failed to get confirmed block',
     );
+    // For Tron, undefined is intentional only in named-tag mode. A failed
+    // numeric lookup must not silently query supply at latest instead.
+    if (numericTronLookup) throw error;
     return undefined;
   }
 }