@hyperlane-xyz/rebalancer 27.2.13 → 27.3.0

package/src/core/InventoryRebalancer.ts

@@ -15,7 +15,13 @@ import {
   getSignerForChain,
   type TypedTransactionReceipt,
 } from '@hyperlane-xyz/sdk';
-import { ProtocolType, assert, ensure0x, fromWei } from '@hyperlane-xyz/utils';
+import {
+  ProtocolType,
+  assert,
+  ensure0x,
+  fromWei,
+  isEVMLike,
+} from '@hyperlane-xyz/utils';
 
 import type { ExternalBridgeType } from '../config/types.js';
 import type {
@@ -74,6 +80,21 @@ type BridgeCapacity = {
   maxTargetOutput: bigint;
 };
 
+type BridgeQuoteMode = 'forward' | 'reverse';
+
+type InventoryMovementExecutionResult =
+  | {
+      success: true;
+      txHash: string;
+      inputRequired: bigint;
+      quotedOutput: bigint;
+      quotedOutputMin: bigint;
+      quoteModeUsed: BridgeQuoteMode;
+    }
+  | {
+      success: false;
+      error: string;
+    };
 const RECOVERABLE_MAX_TRANSFER_ERROR_MESSAGES = [
   'balance may be insufficient',
   'transfer amount exceeds balance',
@@ -910,6 +931,7 @@ export class InventoryRebalancer implements IInventoryRebalancer {
       chain: ChainName;
       maxSourceInput: bigint;
       targetOutput: bigint;
+      quoteMode: BridgeQuoteMode;
     }> = [];
     let totalPlanned = 0n;
 
@@ -921,11 +943,14 @@ export class InventoryRebalancer implements IInventoryRebalancer {
         source.maxTargetOutput >= remaining
           ? remaining
           : source.maxTargetOutput;
+      const quoteMode: BridgeQuoteMode =
+        source.maxTargetOutput > remaining ? 'reverse' : 'forward';
 
       bridgePlans.push({
         chain: source.chain,
         maxSourceInput: source.maxSourceInput,
         targetOutput,
+        quoteMode,
       });
       totalPlanned += targetOutput;
     }
@@ -942,6 +967,7 @@ export class InventoryRebalancer implements IInventoryRebalancer {
           chain: p.chain,
           maxSourceInput: p.maxSourceInput.toString(),
           targetOutput: p.targetOutput.toString(),
+          quoteMode: p.quoteMode,
         })),
         totalPlanned: totalPlanned.toString(),
         shortfall: shortfall.toString(),
@@ -959,6 +985,7 @@ export class InventoryRebalancer implements IInventoryRebalancer {
           destination,
           plan.targetOutput,
           plan.maxSourceInput,
+          plan.quoteMode,
           intent,
           route.externalBridge,
         ),
@@ -967,7 +994,7 @@ export class InventoryRebalancer implements IInventoryRebalancer {
 
     // Process results
     let successCount = 0;
-    let totalBridged = 0n;
+    let totalQuotedOutputMin = 0n;
     const failedErrors: string[] = [];
 
     for (let i = 0; i < bridgeResults.length; i++) {
@@ -976,27 +1003,42 @@ export class InventoryRebalancer implements IInventoryRebalancer {
 
       if (result.status === 'fulfilled' && result.value.success) {
         successCount++;
-        totalBridged += plan.targetOutput;
+        totalQuotedOutputMin += result.value.quotedOutputMin;
         this.logger.info(
           {
             sourceChain: plan.chain,
-            amount: plan.targetOutput.toString(),
+            plannedTargetOutput: plan.targetOutput.toString(),
+            quotedOutput: result.value.quotedOutput.toString(),
+            quotedOutputMin: result.value.quotedOutputMin.toString(),
+            quoteModeUsed: result.value.quoteModeUsed,
             txHash: result.value.txHash,
           },
           'Inventory movement succeeded',
         );
       } else {
-        const error =
-          result.status === 'rejected'
-            ? result.reason?.message
-            : result.value.error;
+        let error: string | undefined;
+        if (result.status === 'rejected') {
+          if (result.reason instanceof Error) {
+            error = result.reason.message;
+          } else if (typeof result.reason === 'string') {
+            error = result.reason;
+          } else {
+            try {
+              error = JSON.stringify(result.reason) ?? String(result.reason);
+            } catch {
+              error = String(result.reason);
+            }
+          }
+        } else if (!result.value.success) {
+          error = result.value.error;
+        }
         if (error) {
           failedErrors.push(`${plan.chain}: ${error}`);
         }
         this.logger.warn(
           {
             sourceChain: plan.chain,
-            amount: plan.targetOutput.toString(),
+            plannedTargetOutput: plan.targetOutput.toString(),
             error,
           },
           'Inventory movement failed',
@@ -1018,7 +1060,7 @@ export class InventoryRebalancer implements IInventoryRebalancer {
       {
         targetChain: destination,
         successCount,
-        totalBridged: totalBridged.toString(),
+        totalQuotedOutputMin: totalQuotedOutputMin.toString(),
         targetAmount: requestedLocalAmount.toString(),
         targetAmountCanonical: amount.toString(),
         intentId: intent.id,
@@ -1184,6 +1226,7 @@ export class InventoryRebalancer implements IInventoryRebalancer {
   ): MultiProtocolSignerSignerAccountInfo {
     void chain;
     switch (protocol) {
+      case ProtocolType.Tron:
       case ProtocolType.Ethereum:
         return { protocol, privateKey: ensure0x(key) };
       case ProtocolType.Sealevel:
@@ -1223,7 +1266,7 @@ export class InventoryRebalancer implements IInventoryRebalancer {
     try {
       const protocol = this.getProtocolForChain(origin);
 
-      if (protocol === ProtocolType.Ethereum) {
+      if (isEVMLike(protocol)) {
         const provider =
           this.warpCore.multiProvider.getEthersV5Provider(origin);
         const receipt = await provider.getTransactionReceipt(txHash);
@@ -1395,13 +1438,15 @@ export class InventoryRebalancer implements IInventoryRebalancer {
   /**
    * Execute inventory movement from source chain to target chain via LiFi bridge.
    *
-   * Uses reverse quotes (`toAmount`) so plans are expressed in target-chain local
-   * units and source-local spend is discovered by the bridge quote.
+   * Quote mode is chosen during planning:
+   * - `reverse`: request an exact target-chain output when the source has headroom
+   * - `forward`: spend the source cap directly when source inventory is the limiter
    *
    * @param sourceChain - Chain to move inventory from
    * @param targetChain - Chain to move inventory to (origin chain for rebalancing)
    * @param targetOutputAmount - Destination-local amount to receive
    * @param maxSourceInput - Maximum source-local amount available for this plan
+   * @param quoteMode - Whether to execute this bridge plan as exact-input or exact-output
    * @param intent - Rebalance intent for tracking
    * @param externalBridgeType - External bridge type to use
    * @returns Result with success status and optional txHash/error
@@ -1411,9 +1456,10 @@ export class InventoryRebalancer implements IInventoryRebalancer {
     targetChain: ChainName,
     targetOutputAmount: bigint,
     maxSourceInput: bigint,
+    quoteMode: BridgeQuoteMode,
     intent: RebalanceIntent,
     externalBridgeType: ExternalBridgeType,
-  ): Promise<{ success: boolean; txHash?: string; error?: string }> {
+  ): Promise<InventoryMovementExecutionResult> {
     const sourceToken = this.getTokenForChain(sourceChain);
     if (!sourceToken) {
       return {
@@ -1461,15 +1507,43 @@ export class InventoryRebalancer implements IInventoryRebalancer {
 
     try {
       const externalBridge = this.getExternalBridge(externalBridgeType);
-      const quote = await externalBridge.quote({
-        fromChain: sourceChainId,
-        toChain: targetChainId,
-        fromToken: fromTokenAddress,
-        toToken: toTokenAddress,
-        toAmount: targetOutputAmount,
-        fromAddress: this.getInventorySignerAddress(sourceChain),
-        toAddress: this.getInventorySignerAddress(targetChain),
-      });
+      const fromAddress = this.getInventorySignerAddress(sourceChain);
+      const toAddress = this.getInventorySignerAddress(targetChain);
+      const quoteWithMode = async (mode: BridgeQuoteMode) =>
+        externalBridge.quote({
+          fromChain: sourceChainId,
+          toChain: targetChainId,
+          fromToken: fromTokenAddress,
+          toToken: toTokenAddress,
+          ...(mode === 'forward'
+            ? { fromAmount: maxSourceInput }
+            : { toAmount: targetOutputAmount }),
+          fromAddress,
+          toAddress,
+        });
+
+      let quoteModeUsed = quoteMode;
+      let quote = await quoteWithMode(quoteModeUsed);
+
+      if (quoteModeUsed === 'reverse' && quote.fromAmount > maxSourceInput) {
+        this.logger.warn(
+          {
+            sourceChain,
+            targetChain,
+            plannedQuoteMode: quoteMode,
+            requestedTargetOutput: targetOutputAmount.toString(),
+            quotedInput: quote.fromAmount.toString(),
+            maxSourceInput: maxSourceInput.toString(),
+            intentId: intent.id,
+          },
+          'Reverse bridge quote exceeded source capacity, retrying with forward quote',
+        );
+
+        // Spend the full source cap on fallback; minor output drift is acceptable
+        // and will be reconciled by later cycles rather than risking livelock.
+        quoteModeUsed = 'forward';
+        quote = await quoteWithMode(quoteModeUsed);
+      }
 
       const inputRequired = quote.fromAmount;
       if (inputRequired > maxSourceInput) {
@@ -1490,22 +1564,30 @@ export class InventoryRebalancer implements IInventoryRebalancer {
             targetOutputAmount,
             targetToken,
           ),
+          quoteModePlanned: quoteMode,
+          quoteModeUsed,
+          retriedAsForward:
+            quoteMode === 'reverse' && quoteModeUsed === 'forward',
           inputRequired: inputRequired.toString(),
           inputRequiredFormatted: this.formatLocalAmount(
             inputRequired,
             sourceToken,
           ),
-          expectedOutput: quote.toAmount.toString(),
-          expectedOutputMin: quote.toAmountMin.toString(),
-          expectedOutputFormatted: this.formatLocalAmount(
+          quotedOutput: quote.toAmount.toString(),
+          quotedOutputMin: quote.toAmountMin.toString(),
+          quotedOutputFormatted: this.formatLocalAmount(
             quote.toAmount,
             targetToken,
           ),
+          quotedOutputMinFormatted: this.formatLocalAmount(
+            quote.toAmountMin,
+            targetToken,
+          ),
           gasCosts: quote.gasCosts.toString(),
           feeCosts: quote.feeCosts.toString(),
           intentId: intent.id,
         },
-        'Executing inventory movement via LiFi reverse quote',
+        'Executing inventory movement via bridge quote',
       );
 
       this.logger.debug(
@@ -1573,22 +1655,31 @@ export class InventoryRebalancer implements IInventoryRebalancer {
         'Updated consumed inventory after LiFi bridge',
       );
 
-      return { success: true, txHash: result.txHash };
+      return {
+        success: true,
+        txHash: result.txHash,
+        inputRequired,
+        quotedOutput: quote.toAmount,
+        quotedOutputMin: quote.toAmountMin,
+        quoteModeUsed,
+      };
     } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
       this.logger.error(
         {
           sourceChain,
           targetChain,
           amount: targetOutputAmount.toString(),
           intentId: intent.id,
-          error: (error as Error).message,
+          error: errorMessage,
         },
         'Failed to execute inventory movement',
       );
 
       return {
         success: false,
-        error: (error as Error).message,
+        error: errorMessage,
       };
     }
   }

package/src/factories/RebalancerContextFactory.test.ts

@@ -218,6 +218,36 @@ describe('RebalancerContextFactory', () => {
       expect(multiProvider.getProvider.firstCall.args[0]).to.equal('ethereum');
     });
 
+    it('should initialize providers for Tron chains (EVM-like)', async () => {
+      const { multiProvider } = createMockMultiProvider([
+        { name: 'ethereum', protocol: ProtocolType.Ethereum },
+        { name: 'tron', protocol: ProtocolType.Tron },
+      ]);
+
+      await callCreate(multiProvider, {
+        tokens: [
+          createToken(
+            'ethereum',
+            TEST_ADDRESSES.ethereum,
+            TokenStandard.EvmHypCollateral,
+          ),
+          createToken(
+            'tron',
+            '0xTronToken1234567890',
+            TokenStandard.TronHypCollateral,
+          ),
+        ],
+      });
+
+      // Tron is EVM-like, so getProvider should be called for both chains
+      expect(multiProvider.getProvider.callCount).to.equal(2);
+      const providerChains = multiProvider.getProvider
+        .getCalls()
+        .map((c) => c.args[0]);
+      expect(providerChains).to.include('ethereum');
+      expect(providerChains).to.include('tron');
+    });
+
     it('should call getProvider for all chains when all are EVM', async () => {
       const { multiProvider } = createMockMultiProvider([
         { name: 'ethereum', protocol: ProtocolType.Ethereum },
@@ -363,7 +393,7 @@ describe('RebalancerContextFactory', () => {
           createToken(
             evmChain,
             TEST_ADDRESSES.ethereum,
-            TokenStandard.EvmHypSynthetic,
+            TokenStandard.EvmHypCollateral,
           ),
           createToken(
             sealevelChain,
@@ -446,6 +476,91 @@ describe('RebalancerContextFactory', () => {
       );
     });
 
+    it('should accept Tron as a supported inventory protocol', async () => {
+      const tronChain = 'tron';
+      const evmChain = 'ethereum';
+      const { multiProvider } = createMockMultiProvider([
+        { name: evmChain, protocol: ProtocolType.Ethereum },
+        { name: tronChain, protocol: ProtocolType.Tron },
+      ]);
+
+      const config = {
+        warpRouteId: 'USDC/tron-route',
+        strategyConfig: [
+          {
+            rebalanceStrategy: RebalancerStrategyOptions.Weighted,
+            chains: {
+              [tronChain]: {
+                bridge: TEST_ADDRESSES.bridge,
+                weighted: { weight: 50n, tolerance: 10n },
+                override: {
+                  [evmChain]: {
+                    executionType: ExecutionType.Inventory,
+                  },
+                },
+              },
+              [evmChain]: {
+                bridge: TEST_ADDRESSES.bridge,
+                weighted: { weight: 50n, tolerance: 10n },
+              },
+            },
+          },
+        ],
+        inventorySigners: {
+          [ProtocolType.Ethereum]: {
+            address: TEST_ADDRESSES.ethereum,
+            key: '0xabc123',
+          },
+          [ProtocolType.Tron]: {
+            address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+            key: '0xdef456',
+          },
+        },
+        intentTTL: DEFAULT_INTENT_TTL_MS,
+      } as RebalancerConfig;
+
+      const factory = await createFactory(config, multiProvider, {
+        tokens: [
+          createToken(
+            evmChain,
+            TEST_ADDRESSES.ethereum,
+            TokenStandard.EvmHypCollateral,
+          ),
+          createToken(
+            tronChain,
+            '0xTronToken123',
+            TokenStandard.TronHypCollateral,
+          ),
+        ],
+      });
+
+      const getChainMetadataStub = factory.getWarpCore().multiProvider
+        .getChainMetadata as Sinon.SinonStub;
+      getChainMetadataStub.callsFake((chainName: string) => ({
+        protocol:
+          chainName === tronChain ? ProtocolType.Tron : ProtocolType.Ethereum,
+      }));
+
+      const result = await (factory as any).createInventoryRebalancerAndConfig(
+        {} as any,
+        {},
+      );
+
+      assert(
+        result,
+        'Expected inventory config to be created for Tron support',
+      );
+      expect(result.inventoryConfig.inventoryAddresses).to.deep.equal({
+        [ProtocolType.Ethereum]: TEST_ADDRESSES.ethereum,
+        [ProtocolType.Tron]: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+      });
+      expect(result.inventoryConfig.chains).to.include.members([
+        evmChain,
+        tronChain,
+      ]);
+      expect(result.inventoryRebalancer).to.exist;
+    });
+
     it('should fail early when inventory chain uses unsupported protocol', async () => {
       const cosmosChain = 'cosmoshub';
       const evmChain = 'ethereum';

package/src/factories/RebalancerContextFactory.ts

@@ -11,7 +11,13 @@ import {
   WarpCore,
   type WarpCoreConfig,
 } from '@hyperlane-xyz/sdk';
-import { Address, assert, ProtocolType, objMap } from '@hyperlane-xyz/utils';
+import {
+  Address,
+  assert,
+  isEVMLike,
+  ProtocolType,
+  objMap,
+} from '@hyperlane-xyz/utils';
 
 import { LiFiBridge } from '../bridges/LiFiBridge.js';
 import { type RebalancerConfig } from '../config/RebalancerConfig.js';
@@ -137,7 +143,7 @@ export class RebalancerContextFactory {
       ...new Set(warpCoreConfig.tokens.map((t) => t.chainName)),
     ];
     for (const chain of warpChains) {
-      if (multiProvider.getProtocol(chain) !== ProtocolType.Ethereum) {
+      if (!isEVMLike(multiProvider.getProtocol(chain))) {
         logger.debug({ chain }, 'Skipping provider init for non-EVM chain');
         continue;
       }
@@ -373,11 +379,12 @@ export class RebalancerContextFactory {
       bridges,
       rebalancerAddress,
       inventorySignerAddresses: this.config.inventorySigners
-        ? (Object.entries(this.config.inventorySigners)
-            .filter(([protocol]) => protocol === ProtocolType.Ethereum)
-            .map(([, signerConfig]) => signerConfig)
-            .map((s) => s.address)
-            .filter(Boolean) as Address[])
+        ? Object.values(ProtocolType)
+            .filter((protocol) => isEVMLike(protocol))
+            .map(
+              (protocol) => this.config.inventorySigners?.[protocol]?.address,
+            )
+            .filter((address): address is Address => Boolean(address))
         : undefined,
       intentTTL: this.config.intentTTL,
     };
@@ -481,6 +488,7 @@ export class RebalancerContextFactory {
     const SUPPORTED_INVENTORY_PROTOCOLS = new Set([
       ProtocolType.Ethereum,
       ProtocolType.Sealevel,
+      ProtocolType.Tron,
     ]);
     for (const protocol of requiredProtocols) {
       const chainsForProtocol = allRelevantChains.filter(
@@ -490,7 +498,7 @@ export class RebalancerContextFactory {
       );
       assert(
         SUPPORTED_INVENTORY_PROTOCOLS.has(protocol),
-        `Inventory rebalancing does not support protocol '${protocol}' (chains: ${chainsForProtocol.join(', ')}). Supported: ethereum, sealevel`,
+        `Inventory rebalancing does not support protocol '${protocol}' (chains: ${chainsForProtocol.join(', ')}). Supported: ethereum, sealevel, tron`,
       );
     }
     for (const protocol of requiredProtocols) {
@@ -532,12 +540,12 @@ export class RebalancerContextFactory {
           'No external bridges configured, skipping inventory components',
         );
       }
-      const inventoryAddresses = Object.fromEntries(
-        Object.entries(inventorySigners).map(([protocol, cfg]) => [
-          protocol,
-          cfg.address,
-        ]),
-      ) as Partial<Record<ProtocolType, Address>>;
+      const inventoryAddresses: Partial<Record<ProtocolType, Address>> = {};
+      for (const protocol of Object.values(ProtocolType)) {
+        const cfg = inventorySigners[protocol];
+        if (!cfg) continue;
+        inventoryAddresses[protocol] = cfg.address;
+      }
       const inventoryConfig: InventoryMonitorConfig = {
         inventoryAddresses,
         chains: allRelevantChains,
@@ -546,11 +554,12 @@ export class RebalancerContextFactory {
       const mergedSigners: Partial<
         Record<ProtocolType, InventorySignerConfig>
       > = {};
-      for (const [protocol, cfg] of Object.entries(inventorySigners)) {
-        const protocolKey = protocol as ProtocolType;
-        mergedSigners[protocolKey] = {
+      for (const protocol of Object.values(ProtocolType)) {
+        const cfg = inventorySigners[protocol];
+        if (!cfg) continue;
+        mergedSigners[protocol] = {
           address: cfg.address,
-          key: cfg.key ?? this.inventorySignerKeysByProtocol?.[protocolKey],
+          key: cfg.key ?? this.inventorySignerKeysByProtocol?.[protocol],
         };
       }
       const inventoryRebalancer = new InventoryRebalancer(
@@ -572,12 +581,12 @@ export class RebalancerContextFactory {
     }
 
     // 3. Build inventory config
-    const inventoryAddresses = Object.fromEntries(
-      Object.entries(inventorySigners).map(([protocol, cfg]) => [
-        protocol,
-        cfg.address,
-      ]),
-    ) as Partial<Record<ProtocolType, Address>>;
+    const inventoryAddresses: Partial<Record<ProtocolType, Address>> = {};
+    for (const protocol of Object.values(ProtocolType)) {
+      const cfg = inventorySigners[protocol];
+      if (!cfg) continue;
+      inventoryAddresses[protocol] = cfg.address;
+    }
     const inventoryConfig: InventoryMonitorConfig = {
       inventoryAddresses,
       chains: allRelevantChains,
@@ -587,11 +596,12 @@ export class RebalancerContextFactory {
     // Merge config addresses with runtime keys
     const mergedSigners: Partial<Record<ProtocolType, InventorySignerConfig>> =
       {};
-    for (const [protocol, cfg] of Object.entries(inventorySigners)) {
-      const protocolKey = protocol as ProtocolType;
-      mergedSigners[protocolKey] = {
+    for (const protocol of Object.values(ProtocolType)) {
+      const cfg = inventorySigners[protocol];
+      if (!cfg) continue;
+      mergedSigners[protocol] = {
         address: cfg.address,
-        key: cfg.key ?? this.inventorySignerKeysByProtocol?.[protocolKey],
+        key: cfg.key ?? this.inventorySignerKeysByProtocol?.[protocol],
       };
     }
     const inventoryRebalancer = new InventoryRebalancer(

package/src/service.ts

@@ -33,6 +33,7 @@ import { MultiProvider } from '@hyperlane-xyz/sdk';
 import {
   applyRpcUrlOverridesFromEnv,
   createServiceLogger,
+  isEVMLike,
   ProtocolType,
   rootLogger,
 } from '@hyperlane-xyz/utils';
@@ -151,12 +152,15 @@ async function main(): Promise<void> {
       Record<ProtocolType, InventorySignerConfig>
     > = {};
 
-    for (const [protocol, privateKey] of Object.entries(inventoryPrivateKeys)) {
+    for (const protocol of Object.values(ProtocolType)) {
+      const privateKey = inventoryPrivateKeys[protocol];
       if (!privateKey) continue;
 
       let derivedAddress: string;
 
-      if (protocol === ProtocolType.Ethereum) {
+      if (isEVMLike(protocol)) {
+        // Tron uses same hex private key format as Ethereum.
+        // Derive 0x-prefixed hex address via ethers Wallet (TronWallet extends Wallet).
         derivedAddress = new Wallet(privateKey).address;
       } else if (protocol === ProtocolType.Sealevel) {
         const keyBytes = parseSolanaPrivateKey(privateKey);
@@ -172,12 +176,11 @@ async function main(): Promise<void> {
 
       // Validate against config if present
       const configuredAddress =
-        rebalancerConfig.inventorySigners?.[protocol as ProtocolType]?.address;
+        rebalancerConfig.inventorySigners?.[protocol]?.address;
       if (configuredAddress) {
-        const mismatch =
-          protocol === ProtocolType.Ethereum
-            ? configuredAddress.toLowerCase() !== derivedAddress.toLowerCase()
-            : configuredAddress !== derivedAddress;
+        const mismatch = isEVMLike(protocol)
+          ? configuredAddress.toLowerCase() !== derivedAddress.toLowerCase()
+          : configuredAddress !== derivedAddress;
         if (mismatch) {
           throw new Error(
             `inventorySigners.${protocol} mismatch: config has ${configuredAddress} but HYP_INVENTORY_KEY_${protocol.toUpperCase()} derives to ${derivedAddress}`,
@@ -185,7 +188,7 @@ async function main(): Promise<void> {
         }
       }
 
-      inventorySigners[protocol as ProtocolType] = {
+      inventorySigners[protocol] = {
         address: derivedAddress,
         key: privateKey,
       };