feat: multiple transactions for relay quote (#7089)

## Explanation

Support Relay quotes requiring multiple transactions, such as a token
approval and deposit.

Use fallback gas limit if missing in transaction data.

## References

Related to
[#6184](MetaMask/MetaMask-planning#6184)

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs),
highlighting breaking changes as necessary
- [x] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds multi-transaction support for Relay quotes with batch submission,
fallback gas handling, and shared transaction ID collection utility.
> 
> - **Relay strategy**:
> - Support multiple transactions per quote: submit via
`TransactionController:addTransactionBatch`, collect required IDs with
`collectTransactionIds`, wait for all confirmations, and return last tx
`hash`.
> - Poll Relay status from the last step; set `isIntentComplete` when
`skipTransaction`.
> - Normalize params with fallback `gas` using
`RELAY_FALLBACK_GAS_LIMIT`.
> - Quote fees: compute source network fee using total gas across items
or fallback when missing.
> - **Utils**:
> - Add `utils/transaction#collectTransactionIds` and use it in
Bridge/Relay; remove in-file implementation from Bridge.
> - **Types/Mocks**:
> - Make `RelayQuote.steps[].items[].data.gas` optional; extend
messenger to handle `TransactionController:addTransactionBatch`.
> - **Changelog**:
>   - Note support for Relay quotes with multiple transactions.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
7c30789. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: matthewwalsh0

packages/transaction-pay-controller/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Support Relay quotes with multiple transactions ([#7089](https://github.com/MetaMask/core/pull/7089))
+
 ## [3.1.0]
 
 ### Added

packages/transaction-pay-controller/src/strategy/bridge/bridge-submit.test.ts

@@ -16,9 +16,14 @@ import {
   waitForTransactionConfirmed,
 } from '../../utils/transaction';
 
-jest.mock('../../utils/transaction');
 jest.mock('./bridge-quotes');
 
+jest.mock('../../utils/transaction', () => ({
+  ...jest.requireActual('../../utils/transaction'),
+  updateTransaction: jest.fn(),
+  waitForTransactionConfirmed: jest.fn(),
+}));
+
 const FROM_MOCK = '0x123';
 const CHAIN_ID_MOCK = toHex(123);
 const TRANSACTION_ID_MOCK = '123-456';

packages/transaction-pay-controller/src/strategy/bridge/bridge-submit.ts

@@ -16,6 +16,7 @@ import type {
   TransactionPayQuote,
 } from '../../types';
 import {
+  collectTransactionIds,
   updateTransaction,
   waitForTransactionConfirmed,
 } from '../../utils/transaction';
@@ -222,44 +223,3 @@ async function waitForBridgeCompletion(
     );
   });
 }
-
-/**
- * Collect all new transactions until `end` is called.
- *
- * @param chainId - The chain ID to filter transactions by.
- * @param from - The address to filter transactions by.
- * @param messenger - The controller messenger.
- * @param onTransaction - Callback called with each matching transaction ID.
- * @returns An object with an `end` method to stop collecting transactions.
- */
-function collectTransactionIds(
-  chainId: Hex,
-  from: Hex,
-  messenger: TransactionPayControllerMessenger,
-  onTransaction: (transactionId: string) => void,
-): { end: () => void } {
-  const listener = (tx: TransactionMeta) => {
-    if (
-      tx.chainId !== chainId ||
-      tx.txParams.from.toLowerCase() !== from.toLowerCase()
-    ) {
-      return;
-    }
-
-    onTransaction(tx.id);
-  };
-
-  messenger.subscribe(
-    'TransactionController:unapprovedTransactionAdded',
-    listener,
-  );
-
-  const end = () => {
-    messenger.unsubscribe(
-      'TransactionController:unapprovedTransactionAdded',
-      listener,
-    );
-  };
-
-  return { end };
-}

packages/transaction-pay-controller/src/strategy/relay/constants.ts

@@ -4,3 +4,4 @@ export const CHAIN_ID_ARBITRUM = '0xa4b1';
 export const CHAIN_ID_POLYGON = '0x89';
 export const RELAY_URL_BASE = 'https://api.relay.link';
 export const RELAY_URL_QUOTE = `${RELAY_URL_BASE}/quote`;
+export const RELAY_FALLBACK_GAS_LIMIT = 900000;

packages/transaction-pay-controller/src/strategy/relay/relay-quotes.test.ts

@@ -1,5 +1,6 @@
 import { successfulFetch } from '@metamask/controller-utils';
 import type { TransactionMeta } from '@metamask/transaction-controller';
+import { cloneDeep } from 'lodash';
 
 import {
   ARBITRUM_USDC_ADDRESS,
@@ -85,11 +86,13 @@ const TRANSACTION_META_MOCK = {} as TransactionMeta;
 describe('Relay Quotes Utils', () => {
   const successfulFetchMock = jest.mocked(successfulFetch);
   const getTokenFiatRateMock = jest.mocked(getTokenFiatRate);
+  const calculateGasCostMock = jest.mocked(calculateGasCost);
+  const getNativeTokenMock = jest.mocked(getNativeToken);
+
   const calculateTransactionGasCostMock = jest.mocked(
     calculateTransactionGasCost,
   );
-  const calculateGasCostMock = jest.mocked(calculateGasCost);
-  const getNativeTokenMock = jest.mocked(getNativeToken);
+
   const { messenger, getRemoteFeatureFlagControllerStateMock } =
     getMessengerMock();
 
@@ -271,6 +274,48 @@ describe('Relay Quotes Utils', () => {
       });
     });
 
+    it('includes source network fee in quote using fallback if gas missing', async () => {
+      const quoteMock = cloneDeep(QUOTE_MOCK);
+      delete quoteMock.steps[0].items[0].data.gas;
+
+      successfulFetchMock.mockResolvedValue({
+        json: async () => quoteMock,
+      } as never);
+
+      await getRelayQuotes({
+        messenger,
+        requests: [QUOTE_REQUEST_MOCK],
+        transaction: TRANSACTION_META_MOCK,
+      });
+
+      expect(calculateGasCostMock).toHaveBeenCalledWith(
+        expect.objectContaining({ gas: 900000 }),
+      );
+    });
+
+    it('includes source network fee using gas total from multiple transactions', async () => {
+      const quoteMock = cloneDeep(QUOTE_MOCK);
+      quoteMock.steps[0].items.push({
+        data: {
+          gas: '480000',
+        },
+      } as never);
+
+      successfulFetchMock.mockResolvedValue({
+        json: async () => quoteMock,
+      } as never);
+
+      await getRelayQuotes({
+        messenger,
+        requests: [QUOTE_REQUEST_MOCK],
+        transaction: TRANSACTION_META_MOCK,
+      });
+
+      expect(calculateGasCostMock).toHaveBeenCalledWith(
+        expect.objectContaining({ gas: 501000 }),
+      );
+    });
+
     it('includes target network fee in quote', async () => {
       successfulFetchMock.mockResolvedValue({
         json: async () => QUOTE_MOCK,

packages/transaction-pay-controller/src/strategy/relay/relay-quotes.ts

@@ -6,6 +6,7 @@ import {
   ARBITRUM_USDC_ADDRESS,
   CHAIN_ID_ARBITRUM,
   CHAIN_ID_POLYGON,
+  RELAY_FALLBACK_GAS_LIMIT,
   RELAY_URL_QUOTE,
 } from './constants';
 import type { RelayQuote } from './types';
@@ -309,27 +310,40 @@ function calculateSourceNetworkCost(
   quote: RelayQuote,
   messenger: TransactionPayControllerMessenger,
 ) {
-  const allParams = quote.steps.flatMap((s) => s.items.map((i) => i.data));
-
-  const result = allParams.reduce(
-    (total, params) => {
-      const gasCost = calculateGasCost({
-        ...params,
-        maxFeePerGas: undefined,
-        maxPriorityFeePerGas: undefined,
-        messenger,
-      });
-
-      return {
-        usd: new BigNumber(total.usd).plus(gasCost.usd),
-        fiat: new BigNumber(total.fiat).plus(gasCost.fiat),
-      };
-    },
-    { usd: new BigNumber(0), fiat: new BigNumber(0) },
-  );
+  const allParams = quote.steps[0].items.map((i) => i.data);
+  const totalGasLimit = calculateSourceNetworkGasLimit(allParams);
 
-  return {
-    usd: result.usd.toString(10),
-    fiat: result.fiat.toString(10),
-  };
+  return calculateGasCost({
+    chainId: allParams[0].chainId,
+    gas: totalGasLimit,
+    messenger,
+  });
+}
+
+/**
+ * Calculate the total gas limit for the source network transactions.
+ *
+ * @param params - Array of transaction parameters.
+ * @returns - Total gas limit.
+ */
+function calculateSourceNetworkGasLimit(
+  params: RelayQuote['steps'][0]['items'][0]['data'][],
+): number {
+  const allParamsHasGas = params.every((p) => p.gas !== undefined);
+
+  if (allParamsHasGas) {
+    return params.reduce(
+      (total, p) => total + new BigNumber(p.gas as string).toNumber(),
+      0,
+    );
+  }
+
+  // In future, call `TransactionController:estimateGas`
+  // or `TransactionController:estimateGasBatch` based on params length.
+
+  return params.reduce(
+    (total, p) =>
+      total + new BigNumber(p.gas ?? RELAY_FALLBACK_GAS_LIMIT).toNumber(),
+    0,
+  );
 }

packages/transaction-pay-controller/src/strategy/relay/relay-submit.test.ts

@@ -1,5 +1,8 @@
 import { ORIGIN_METAMASK, successfulFetch } from '@metamask/controller-utils';
-import type { TransactionMeta } from '@metamask/transaction-controller';
+import {
+  TransactionType,
+  type TransactionMeta,
+} from '@metamask/transaction-controller';
 import type { Hex } from '@metamask/utils';
 import { cloneDeep } from 'lodash';
 
@@ -13,6 +16,8 @@ import type {
   TransactionPayQuote,
 } from '../../types';
 import {
+  collectTransactionIds,
+  getTransaction,
   updateTransaction,
   waitForTransactionConfirmed,
 } from '../../utils/transaction';
@@ -28,9 +33,11 @@ const NETWORK_CLIENT_ID_MOCK = 'networkClientIdMock';
 const TRANSACTION_HASH_MOCK = '0x1234';
 const ENDPOINT_MOCK = '/test123';
 const ORIGINAL_TRANSACTION_ID_MOCK = '456-789';
+const FROM_MOCK = '0xabcde' as Hex;
 
 const TRANSACTION_META_MOCK = {
   id: '123-456',
+  hash: TRANSACTION_HASH_MOCK,
 } as TransactionMeta;
 
 const ORIGINAL_QUOTE_MOCK = {
@@ -46,7 +53,7 @@ const ORIGINAL_QUOTE_MOCK = {
           data: {
             chainId: 1,
             data: '0x1234' as Hex,
-            from: '0xabcde' as Hex,
+            from: FROM_MOCK,
             gas: '21000',
             maxFeePerGas: '25000000000',
             maxPriorityFeePerGas: '1000000000',
@@ -76,9 +83,15 @@ const REQUEST_MOCK: PayStrategyExecuteRequest<RelayQuote> = {
 describe('Relay Submit Utils', () => {
   const updateTransactionMock = jest.mocked(updateTransaction);
   const successfulFetchMock = jest.mocked(successfulFetch);
+  const getTransactionMock = jest.mocked(getTransaction);
+  const collectTransactionIdsMock = jest.mocked(collectTransactionIds);
 
-  const { addTransactionMock, findNetworkClientIdByChainIdMock, messenger } =
-    getMessengerMock();
+  const {
+    addTransactionMock,
+    addTransactionBatchMock,
+    findNetworkClientIdByChainIdMock,
+    messenger,
+  } = getMessengerMock();
 
   let request: PayStrategyExecuteRequest<RelayQuote>;
 
@@ -97,6 +110,14 @@ describe('Relay Submit Utils', () => {
     });
 
     waitForTransactionConfirmedMock.mockResolvedValue();
+    getTransactionMock.mockReturnValue(TRANSACTION_META_MOCK);
+
+    collectTransactionIdsMock.mockImplementation(
+      (_chainId, _from, _messenger, fn) => {
+        fn(TRANSACTION_META_MOCK.id);
+        return { end: jest.fn() };
+      },
+    );
 
     successfulFetchMock.mockResolvedValue({
       json: async () => ({ status: 'success' }),
@@ -129,15 +150,54 @@ describe('Relay Submit Utils', () => {
       );
     });
 
+    it('adds batch transaction if multiple params', async () => {
+      request.quotes[0].original.steps[0].items.push({
+        ...request.quotes[0].original.steps[0].items[0],
+      });
+
+      await submitRelayQuotes(request);
+
+      expect(addTransactionBatchMock).toHaveBeenCalledTimes(1);
+      expect(addTransactionBatchMock).toHaveBeenCalledWith({
+        from: FROM_MOCK,
+        networkClientId: NETWORK_CLIENT_ID_MOCK,
+        origin: ORIGIN_METAMASK,
+        requireApproval: false,
+        transactions: [
+          {
+            params: {
+              data: '0x1234',
+              gas: '0x5208',
+              to: '0xfedcb',
+              value: '0x4d2',
+            },
+            type: TransactionType.tokenMethodApprove,
+          },
+          {
+            params: {
+              data: '0x1234',
+              gas: '0x5208',
+              to: '0xfedcb',
+              value: '0x4d2',
+            },
+          },
+        ],
+      });
+    });
+
     it('adds transaction if params missing', async () => {
       request.quotes[0].original.steps[0].items[0].data.value =
         undefined as never;
 
+      request.quotes[0].original.steps[0].items[0].data.gas =
+        undefined as never;
+
       await submitRelayQuotes(request);
 
       expect(addTransactionMock).toHaveBeenCalledTimes(1);
       expect(addTransactionMock).toHaveBeenCalledWith(
         expect.objectContaining({
+          gas: '0xdbba0',
           value: '0x0',
         }),
         expect.anything(),