@hyperlane-xyz/rebalancer 3.2.1 → 25.5.0

package/src/bridges/LiFiBridge.ts

@@ -1,5 +1,7 @@
 import {
   EVM,
+  type LiFiStep,
+  type Route,
   type RouteExtended,
   convertQuoteToRoute,
   createConfig,
@@ -12,6 +14,7 @@ import type { Logger } from 'pino';
 import { type Chain, createWalletClient, http } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { arbitrum, base, mainnet, optimism } from 'viem/chains';
+import { assert } from '@hyperlane-xyz/utils';
 
 import type {
   BridgeQuote,
@@ -28,41 +31,6 @@ import type {
  */
 const LIFI_API_BASE = 'https://li.quest/v1';
 
-/**
- * LiFi quote response structure (partial, only fields we need).
- */
-interface LiFiQuoteResponse {
-  id: string;
-  tool: string;
-  action: {
-    fromAmount: string;
-    toAmount?: string;
-  };
-  estimate: {
-    fromAmount: string;
-    toAmount: string;
-    toAmountMin: string;
-    executionDuration: number;
-    gasCosts?: Array<{
-      type: string;
-      amount: string;
-      token: {
-        address: string;
-        symbol: string;
-      };
-    }>;
-    feeCosts?: Array<{
-      name: string;
-      amount: string;
-      included: boolean;
-      token: {
-        address: string;
-        symbol: string;
-      };
-    }>;
-  };
-}
-
 /**
  * Known chains for viem - add more as needed.
  * TODO: can we think of a cleaner way to do this?
@@ -111,7 +79,7 @@ function getViemChain(chainId: number, rpcUrl?: string): Chain {
  */
 export class LiFiBridge implements IExternalBridge {
   private static readonly NATIVE_TOKEN_ADDRESS =
-    '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
+    '0x0000000000000000000000000000000000000000';
 
   readonly externalBridgeId = 'lifi';
   readonly logger: Logger;
@@ -164,7 +132,7 @@ export class LiFiBridge implements IExternalBridge {
    *
    * Returns route data ready for execution.
    */
-  async quote(params: BridgeQuoteParams): Promise<BridgeQuote> {
+  async quote(params: BridgeQuoteParams): Promise<BridgeQuote<LiFiStep>> {
     this.initialize();
 
     // Validate that exactly one of fromAmount or toAmount is provided
@@ -177,6 +145,15 @@ export class LiFiBridge implements IExternalBridge {
       throw new Error('Must specify either fromAmount or toAmount');
     }
 
+    assert(
+      params.fromAmount === undefined || params.fromAmount > 0n,
+      'fromAmount must be positive',
+    );
+    assert(
+      params.toAmount === undefined || params.toAmount > 0n,
+      'toAmount must be positive',
+    );
+
     // Dispatch to appropriate quote method
     if (params.toAmount !== undefined) {
       return this.quoteByReceivingAmount(params);
@@ -191,7 +168,7 @@ export class LiFiBridge implements IExternalBridge {
    */
   private async quoteBySpendingAmount(
     params: BridgeQuoteParams,
-  ): Promise<BridgeQuote> {
+  ): Promise<BridgeQuote<LiFiStep>> {
     this.logger.debug({ params }, 'Requesting LiFi quote by spending amount');
 
     const quote = await getQuote({
@@ -207,9 +184,7 @@ export class LiFiBridge implements IExternalBridge {
       order: 'RECOMMENDED',
     });
 
-    const { gasCosts, feeCosts } = this.extractCosts(
-      quote as unknown as LiFiQuoteResponse,
-    );
+    const { gasCosts, feeCosts } = this.extractCosts(quote);
 
     this.logger.info(
       {
@@ -235,6 +210,7 @@ export class LiFiBridge implements IExternalBridge {
       gasCosts,
       feeCosts,
       route: quote, // Store full quote for conversion to route
+      requestParams: { ...params },
     };
   }
 
@@ -244,7 +220,7 @@ export class LiFiBridge implements IExternalBridge {
    */
   private async quoteByReceivingAmount(
     params: BridgeQuoteParams,
-  ): Promise<BridgeQuote> {
+  ): Promise<BridgeQuote<LiFiStep>> {
     this.logger.debug({ params }, 'Requesting LiFi quote by receiving amount');
 
     const queryParams = new URLSearchParams({
@@ -280,7 +256,7 @@ export class LiFiBridge implements IExternalBridge {
       );
     }
 
-    const quote: LiFiQuoteResponse = await response.json();
+    const quote: LiFiStep = await response.json();
     const { gasCosts, feeCosts } = this.extractCosts(quote);
 
     this.logger.info(
@@ -307,6 +283,7 @@ export class LiFiBridge implements IExternalBridge {
       gasCosts,
       feeCosts,
       route: quote, // Store full quote for conversion to route
+      requestParams: { ...params },
     };
   }
 
@@ -315,7 +292,7 @@ export class LiFiBridge implements IExternalBridge {
    * - gasCosts: Sum of all gas costs (transaction fees)
    * - feeCosts: Sum of non-included fee costs (protocol fees not deducted from amount)
    */
-  private extractCosts(quote: LiFiQuoteResponse): {
+  private extractCosts(quote: LiFiStep): {
     gasCosts: bigint;
     feeCosts: bigint;
   } {
@@ -350,15 +327,15 @@ export class LiFiBridge implements IExternalBridge {
    * @param privateKey - Private key hex string (0x-prefixed) for signing the transaction
    */
   async execute(
-    quote: BridgeQuote,
+    quote: BridgeQuote<LiFiStep>,
     privateKey: string,
   ): Promise<BridgeTransferResult> {
     this.initialize();
 
     // Convert quote to route for execution
-    const route = convertQuoteToRoute(
-      quote.route as Parameters<typeof convertQuoteToRoute>[0],
-    );
+    const route = convertQuoteToRoute(quote.route);
+
+    this.validateRouteAgainstRequest(route, quote.requestParams);
 
     const fromChain = route.fromChainId;
     const toChain = route.toChainId;
@@ -478,6 +455,65 @@ export class LiFiBridge implements IExternalBridge {
     };
   }
 
+  /**
+   * Validate that the route returned by LiFi matches the original request parameters.
+   * Prevents execution against wrong chains, tokens, or recipients if the bridge API
+   * returns a route that diverges from what was originally requested.
+   *
+   * TODO: Layer 2 validation — validate transaction calldata in route.steps[].transactionRequest
+   * and route.steps[0].estimate.approvalAddress against a known whitelist.
+   */
+  private validateRouteAgainstRequest(
+    route: Route,
+    requestParams: BridgeQuoteParams,
+  ): void {
+    assert(
+      route.fromChainId === requestParams.fromChain,
+      `Route fromChainId ${route.fromChainId} does not match requested ${requestParams.fromChain}`,
+    );
+    assert(
+      route.toChainId === requestParams.toChain,
+      `Route toChainId ${route.toChainId} does not match requested ${requestParams.toChain}`,
+    );
+    assert(
+      route.fromToken.address.toLowerCase() ===
+        requestParams.fromToken.toLowerCase(),
+      `Route fromToken ${route.fromToken.address} does not match requested ${requestParams.fromToken}`,
+    );
+    assert(
+      route.toToken.address.toLowerCase() ===
+        requestParams.toToken.toLowerCase(),
+      `Route toToken ${route.toToken.address} does not match requested ${requestParams.toToken}`,
+    );
+    const expectedToAddress = (
+      requestParams.toAddress ?? requestParams.fromAddress
+    ).toLowerCase();
+    assert(
+      route.toAddress?.toLowerCase() === expectedToAddress,
+      `Route toAddress ${route.toAddress} does not match requested ${expectedToAddress}`,
+    );
+    assert(
+      route.fromAddress?.toLowerCase() ===
+        requestParams.fromAddress.toLowerCase(),
+      `Route fromAddress ${route.fromAddress} does not match requested ${requestParams.fromAddress}`,
+    );
+    const routeFromAmount = BigInt(route.fromAmount);
+    if (requestParams.fromAmount !== undefined) {
+      assert(
+        routeFromAmount === requestParams.fromAmount,
+        `Route fromAmount ${route.fromAmount} does not match requested ${requestParams.fromAmount}`,
+      );
+    }
+    if (requestParams.toAmount !== undefined) {
+      const routeToAmount = BigInt(route.toAmount);
+      assert(
+        routeToAmount >= requestParams.toAmount,
+        `Route toAmount ${route.toAmount} is less than requested ${requestParams.toAmount}`,
+      );
+    }
+    assert(routeFromAmount > 0n, 'Route fromAmount must be positive');
+  }
+
   /**
    * Get the status of a bridge transfer.
    * Uses SDK's built-in status tracking.

package/src/config/types.ts

@@ -118,6 +118,8 @@ export const RebalancerStrategySchema = z
 export const DEFAULT_INTENT_TTL_S = 604800; // 7 days
 export const DEFAULT_INTENT_TTL_MS = DEFAULT_INTENT_TTL_S * 1_000;
 
+export const DEFAULT_MOVEMENT_STALENESS_MS = 30 * 60 * 1_000; // 30 minutes
+
 export const LiFiBridgeConfigSchema = z.object({
   integrator: z.string(),
   defaultSlippage: z.number().optional(),

package/src/e2e/harness/MockExternalBridge.ts

@@ -105,6 +105,7 @@ export class MockExternalBridge implements IExternalBridge {
       gasCosts,
       feeCosts: 0n,
       route,
+      requestParams: params,
     };
   }
 
@@ -197,6 +198,14 @@ export class MockExternalBridge implements IExternalBridge {
         return { status: 'not_found' };
       }
 
+      const dispatchedMessages =
+        HyperlaneCore.getDispatchedMessages(dispatchTxReceipt);
+      assert(
+        dispatchedMessages.length === 1,
+        `Expected exactly 1 dispatched message, got ${dispatchedMessages.length} for tx ${txHash}`,
+      );
+      const dispatchedMsgId = dispatchedMessages[0].id;
+
       const relayer = new HyperlaneRelayer({ core: this.core });
       const receipts = await relayer.relayAll(dispatchTxReceipt);
 
@@ -206,7 +215,30 @@ export class MockExternalBridge implements IExternalBridge {
         receipts[toChain] ??
         receipts[destinationDomain];
 
+      // If relayAll didn't produce receipts (e.g. message already delivered),
+      // fall back to checking on-chain delivery status directly.
       if (!destinationReceipts || destinationReceipts.length === 0) {
+        const destMailbox = this.core.getContracts(toChainName).mailbox;
+        const isDelivered = await destMailbox.delivered(dispatchedMsgId);
+        if (isDelivered) {
+          const receivedAmount = await this.getTransferredAmount(
+            provider,
+            dispatchTxReceipt,
+          );
+          // Find the actual destination chain process tx
+          const processEvents = await destMailbox.queryFilter(
+            destMailbox.filters.ProcessId(dispatchedMsgId),
+          );
+          assert(
+            processEvents.length > 0,
+            `No ProcessId event found for message ${dispatchedMsgId} on ${toChainName}`,
+          );
+          return {
+            status: 'complete',
+            receivingTxHash: processEvents[0].transactionHash,
+            receivedAmount,
+          };
+        }
         return { status: 'not_found' };
       }
 

package/src/interfaces/IExternalBridge.ts

@@ -35,7 +35,7 @@ export interface BridgeQuoteParams {
 /**
  * Quote response from a bridge.
  */
-export interface BridgeQuote {
+export interface BridgeQuote<R = unknown> {
   id: string; // Unique quote identifier
   tool: string; // Bridge/DEX tool used (e.g., 'stargate', 'across')
   fromAmount: bigint; // Amount being sent (input required)
@@ -44,7 +44,8 @@ export interface BridgeQuote {
   executionDuration: number; // Estimated execution time in seconds
   gasCosts: bigint; // Sum of gas costs for the bridge operation
   feeCosts: bigint; // Sum of non-included fee costs (protocol fees, etc.)
-  route: unknown; // Bridge-specific route data for execution
+  route: R; // Bridge-specific route data for execution
+  requestParams: BridgeQuoteParams; // Original request parameters
 }
 
 /**

package/src/test/lifiMocks.ts

@@ -2,6 +2,7 @@ import Sinon, { type SinonStub } from 'sinon';
 
 import type {
   BridgeQuote,
+  BridgeQuoteParams,
   BridgeTransferStatus,
 } from '../interfaces/IExternalBridge.js';
 
@@ -119,22 +120,58 @@ export function mockLiFiStatus(
 
 /**
  * Create a mock BridgeQuote for testing.
+ * The route structure includes all fields read by validateRouteAgainstRequest.
  */
 export function createMockBridgeQuote(
   overrides?: Partial<BridgeQuote>,
 ): BridgeQuote {
+  const route = overrides?.route as
+    | { action?: { fromChainId?: number; toChainId?: number } }
+    | undefined;
+
+  const defaultRequestParams: BridgeQuoteParams = {
+    fromChain: 42161,
+    toChain: 1399811149,
+    fromToken: '0xCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC',
+    toToken: '0xCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC',
+    fromAddress: '0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+    toAddress: '0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+    fromAmount: 10000000000n,
+  };
+  const requestParams: BridgeQuoteParams = {
+    ...defaultRequestParams,
+    ...overrides?.requestParams,
+  };
+
+  const fromChainId = route?.action?.fromChainId ?? requestParams.fromChain;
+  const toChainId = route?.action?.toChainId ?? requestParams.toChain;
+  const fromAmount =
+    overrides?.fromAmount ?? requestParams.fromAmount ?? 10000000000n;
+  const toAmount = overrides?.toAmount ?? 9950000000n;
+  const toAmountMin = overrides?.toAmountMin ?? 9900000000n;
+
   return {
     id: 'quote-123',
     tool: 'across',
-    fromAmount: 10000000000n,
-    toAmount: 9950000000n,
-    toAmountMin: 9900000000n,
+    fromAmount,
+    toAmount,
+    toAmountMin,
     executionDuration: 300,
-    gasCosts: 50000000n, // Default mock gas costs
-    feeCosts: 0n, // Default mock fee costs
+    gasCosts: 50000000n,
+    feeCosts: 0n,
+    // Route includes all fields read by validateRouteAgainstRequest for validation compatibility
     route: {
-      action: { fromChainId: 42161, toChainId: 1399811149 },
+      action: { fromChainId, toChainId },
+      fromChainId,
+      toChainId,
+      fromToken: { address: requestParams.fromToken },
+      toToken: { address: requestParams.toToken },
+      fromAddress: requestParams.fromAddress,
+      toAddress: requestParams.toAddress ?? requestParams.fromAddress,
+      fromAmount: fromAmount.toString(),
+      toAmount: toAmount.toString(),
     },
+    requestParams,
     ...overrides,
   };
 }