feat: persist required assets in transaction meta (#7820)

## Explanation

Adds support for persisting `requiredAssets` on transaction metadata.

Use if available when generating required tokens.

## References

## 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/processes/updating-changelogs.md)
- [x] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Adds a new persisted `requiredAssets` field to transaction/batch
metadata and changes required-token computation to prefer this data when
present, which can affect downstream transaction-pay behavior. Changes
are optional/guarded but touch shared types and request plumbing used by
multiple consumers.
> 
> **Overview**
> **Adds support for persisting `requiredAssets` on transactions and
batches.** `addTransaction` now accepts `requiredAssets` and stores it
on `TransactionMeta`, and the batch (EIP-7702) flow forwards
`requiredAssets` from the batch request into the created transaction.
> 
> **Updates transaction-pay required-token generation to prefer explicit
assets.** `parseRequiredTokens` now builds required tokens from
`transactionMeta.requiredAssets` when provided, falling back to parsing
token transfers/gas fees only when absent/empty; tests and changelogs
were updated accordingly.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
be34464. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: matthewwalsh0

packages/transaction-controller/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add optional `requiredAssets` to `TransactionMeta` ([#7820](https://github.com/MetaMask/core/pull/7820))
+  - Provided by new options in `addTransaction` and `addTransactionBatch`.
+
 ## [62.14.0]
 
 ### Changed

packages/transaction-controller/src/TransactionController.test.ts

@@ -1640,6 +1640,35 @@ describe('TransactionController', () => {
       expect(updateFirstTimeInteractionMock).toHaveBeenCalledTimes(1);
     });
 
+    it('persists requiredAssets on transaction meta', async () => {
+      const { controller } = setupController();
+
+      const requiredAssets = [
+        {
+          address: '0x1234567890123456789012345678901234567890' as Hex,
+          amount: '0x1' as Hex,
+          standard: 'erc20',
+        },
+      ];
+
+      await controller.addTransaction(
+        {
+          from: ACCOUNT_MOCK,
+          to: ACCOUNT_MOCK,
+        },
+        {
+          networkClientId: NETWORK_CLIENT_ID_MOCK,
+          requiredAssets,
+        },
+      );
+
+      await flushPromises();
+
+      const transactionMeta = controller.state.transactions[0];
+
+      expect(transactionMeta.requiredAssets).toStrictEqual(requiredAssets);
+    });
+
     it.each([
       [TransactionEnvelopeType.legacy],
       [

packages/transaction-controller/src/TransactionController.ts

@@ -1285,6 +1285,7 @@ export class TransactionController extends BaseController<
       origin,
       publishHook,
       requestId,
+      requiredAssets,
       requireApproval,
       securityAlertResponse,
       skipInitialGasEstimate,
@@ -1383,6 +1384,7 @@ export class TransactionController extends BaseController<
           networkClientId,
           origin,
           requestId,
+          requiredAssets,
           securityAlertResponse,
           selectedGasFeeToken: gasFeeToken,
           status: TransactionStatus.unapproved as const,

packages/transaction-controller/src/index.ts

@@ -75,6 +75,7 @@ export type {
   PublishBatchHookTransaction,
   PublishHook,
   PublishHookResult,
+  RequiredAsset,
   SavedGasFees,
   SecurityAlertResponse,
   SecurityProviderRequest,
@@ -87,6 +88,7 @@ export type {
   TransactionBatchMeta,
   TransactionBatchRequest,
   TransactionBatchResult,
+  TransactionBatchSingleRequest,
   TransactionError,
   TransactionHistory,
   TransactionHistoryEntry,

packages/transaction-controller/src/types.ts

@@ -394,6 +394,11 @@ export type TransactionMeta = {
    */
   requestId?: string;
 
+  /**
+   * Assets required by the transaction.
+   */
+  requiredAssets?: RequiredAsset[];
+
   /**
    * IDs of any transactions that must be confirmed before this one is submitted.
    * Unlike a transaction batch, these transactions can be on alternate chains.
@@ -1804,6 +1809,9 @@ export type TransactionBatchRequest = {
   /** Whether an approval request should be created to require confirmation from the user. */
   requireApproval?: boolean;
 
+  /** Assets required by the batch transaction. */
+  requiredAssets?: RequiredAsset[];
+
   /** Security alert ID to persist on the transaction. */
   securityAlertId?: string;
 
@@ -2167,6 +2175,9 @@ export type AddTransactionOptions = {
   /** ID of JSON-RPC request from DAPP.  */
   requestId?: string;
 
+  /** Assets required by the transaction. */
+  requiredAssets?: RequiredAsset[];
+
   /** Whether the transaction requires approval by the user, defaults to true unless explicitly disabled. */
   requireApproval?: boolean | undefined;
 
@@ -2218,3 +2229,17 @@ export type GetGasFeeTokensRequest = {
   /** Value of the transaction. */
   value?: Hex;
 };
+
+/**
+ * An asset required by a transaction.
+ */
+export type RequiredAsset = {
+  /** Contract address of the asset. */
+  address: Hex;
+
+  /** Amount of the asset required. */
+  amount: Hex;
+
+  /** Token standard of the asset (e.g., 'erc20'). */
+  standard: string;
+};

packages/transaction-controller/src/utils/batch.test.ts

@@ -40,6 +40,7 @@ import { SequentialPublishBatchHook } from '../hooks/SequentialPublishBatchHook'
 import type {
   GasFeeFlow,
   PublishBatchHook,
+  RequiredAsset,
   TransactionBatchSingleRequest,
 } from '../types';
 
@@ -399,6 +400,46 @@ describe('Batch Utils', () => {
       expect(result.batchId).toMatch(/^0x[0-9a-f]{32}$/u);
     });
 
+    it('passes requiredAssets from batch request to addTransaction for 7702 flow', async () => {
+      isAccountUpgradedToEIP7702Mock.mockResolvedValueOnce({
+        delegationAddress: undefined,
+        isSupported: true,
+      });
+
+      const requiredAssets: RequiredAsset[] = [
+        {
+          address: '0x1234567890123456789012345678901234567890',
+          amount: '0x1',
+          standard: 'erc20',
+        },
+      ];
+
+      addTransactionMock.mockResolvedValueOnce({
+        transactionMeta: TRANSACTION_META_MOCK,
+        result: Promise.resolve(''),
+      });
+
+      await addTransactionBatch({
+        ...request,
+        request: {
+          ...request.request,
+          requiredAssets,
+          transactions: [
+            {
+              params: TRANSACTION_BATCH_PARAMS_MOCK,
+            },
+          ],
+        },
+      });
+
+      expect(addTransactionMock).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.objectContaining({
+          requiredAssets,
+        }),
+      );
+    });
+
     it('preserves nested transaction types when disable7702 is true', async () => {
       const publishBatchHook: jest.MockedFn<PublishBatchHook> = jest.fn();
       mockRequestApproval(MESSENGER_MOCK, {
@@ -1219,6 +1260,7 @@ describe('Batch Utils', () => {
             networkClientId: NETWORK_CLIENT_ID_MOCK,
             origin: ORIGIN_MOCK,
             publishHook: expect.any(Function),
+            requiredAssets: undefined,
             requireApproval: false,
             type: undefined,
           },

packages/transaction-controller/src/utils/batch.ts

@@ -303,6 +303,7 @@ async function addTransactionBatchWith7702(
     origin,
     overwriteUpgrade,
     requestId,
+    requiredAssets,
     requireApproval,
     securityAlertId,
     skipInitialGasEstimate,
@@ -436,6 +437,7 @@ async function addTransactionBatchWith7702(
     origin,
     requestId,
     requireApproval,
+    requiredAssets,
     securityAlertResponse,
     skipInitialGasEstimate,
     type: TransactionType.batch,

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
+
+- Generate required tokens using `requiredAssets` from transaction metadata ([#7820](https://github.com/MetaMask/core/pull/7820))
+
 ## [12.1.0]
 
 ### Changed

packages/transaction-pay-controller/src/utils/required-tokens.test.ts

@@ -36,6 +36,142 @@ describe('Required Tokens Utils', () => {
   });
 
   describe('parseRequiredTokens', () => {
+    describe('with requiredAssets', () => {
+      it('returns tokens from requiredAssets instead of parsing transaction', () => {
+        const tokenAddress = '0xabc123' as Hex;
+
+        getTokenInfoMock.mockReturnValue({ decimals: 6, symbol: 'USDC' });
+        getTokenBalanceMock.mockReturnValue('5000000');
+        getTokenFiatRateMock.mockReturnValue({
+          usdRate: '1',
+          fiatRate: '1',
+        });
+
+        const transactionMeta: TransactionMeta = {
+          ...TRANSACTION_META_MOCK,
+          requiredAssets: [
+            {
+              address: tokenAddress,
+              amount: '0x2DC6C0' as Hex,
+              standard: 'erc20',
+            },
+          ],
+        };
+
+        const result = parseRequiredTokens(transactionMeta, MESSENGER_MOCK);
+
+        expect(result).toStrictEqual([
+          {
+            address: tokenAddress,
+            allowUnderMinimum: false,
+            amountFiat: '3',
+            amountHuman: '3',
+            amountRaw: '3000000',
+            amountUsd: '3',
+            balanceFiat: '5',
+            balanceHuman: '5',
+            balanceRaw: '5000000',
+            balanceUsd: '5',
+            chainId: TRANSACTION_META_MOCK.chainId,
+            decimals: 6,
+            skipIfBalance: false,
+            symbol: 'USDC',
+          },
+        ]);
+      });
+
+      it('returns multiple tokens from requiredAssets', () => {
+        const tokenAddress1 = '0xabc123' as Hex;
+        const tokenAddress2 = '0xdef456' as Hex;
+
+        getTokenInfoMock.mockReturnValue({ decimals: 6, symbol: 'USDC' });
+        getTokenBalanceMock.mockReturnValue('5000000');
+        getTokenFiatRateMock.mockReturnValue({
+          usdRate: '1',
+          fiatRate: '1',
+        });
+
+        const transactionMeta: TransactionMeta = {
+          ...TRANSACTION_META_MOCK,
+          requiredAssets: [
+            {
+              address: tokenAddress1,
+              amount: '0x2DC6C0' as Hex,
+              standard: 'erc20',
+            },
+            {
+              address: tokenAddress2,
+              amount: '0x1E8480' as Hex,
+              standard: 'erc20',
+            },
+          ],
+        };
+
+        const result = parseRequiredTokens(transactionMeta, MESSENGER_MOCK);
+
+        expect(result).toHaveLength(2);
+        expect(result[0].address).toBe(tokenAddress1);
+        expect(result[1].address).toBe(tokenAddress2);
+      });
+
+      it('filters out tokens that cannot be built', () => {
+        const tokenAddress = '0xabc123' as Hex;
+
+        getTokenInfoMock.mockReturnValue(undefined);
+
+        const transactionMeta: TransactionMeta = {
+          ...TRANSACTION_META_MOCK,
+          requiredAssets: [
+            {
+              address: tokenAddress,
+              amount: '0x2DC6C0' as Hex,
+              standard: 'erc20',
+            },
+          ],
+        };
+
+        const result = parseRequiredTokens(transactionMeta, MESSENGER_MOCK);
+
+        expect(result).toStrictEqual([]);
+      });
+
+      it('falls back to parsing transaction when requiredAssets is empty', () => {
+        getTokenInfoMock.mockReturnValue({ decimals: 3, symbol: 'TST' });
+        getTokenBalanceMock.mockReturnValue('789000');
+        getTokenFiatRateMock.mockReturnValue({
+          usdRate: '1.5',
+          fiatRate: '2',
+        });
+
+        const transactionMeta: TransactionMeta = {
+          ...TRANSACTION_META_MOCK,
+          requiredAssets: [],
+        };
+
+        const result = parseRequiredTokens(transactionMeta, MESSENGER_MOCK);
+
+        expect(result).toStrictEqual([
+          {
+            address: TRANSACTION_META_MOCK.txParams.to,
+            allowUnderMinimum: false,
+            amountFiat: '246.912',
+            amountHuman: '123.456',
+            amountRaw: '123456',
+            amountUsd: '185.184',
+            balanceFiat: '1578',
+            balanceHuman: '789',
+            balanceRaw: '789000',
+            balanceUsd: '1183.5',
+            chainId: TRANSACTION_META_MOCK.chainId,
+            decimals: 3,
+            skipIfBalance: false,
+            symbol: 'TST',
+          },
+          expect.anything(),
+        ]);
+      });
+    });
+
     it('returns token transfer required token', () => {
       getTokenInfoMock.mockReturnValue({ decimals: 3, symbol: 'TST' });
       getTokenBalanceMock.mockReturnValue('789000');

packages/transaction-pay-controller/src/utils/required-tokens.ts

@@ -23,6 +23,9 @@ const FOUR_BYTE_TOKEN_TRANSFER = '0xa9059cbb';
 /**
  * Parse required tokens from a transaction.
  *
+ * If the transaction has `requiredAssets`, those are used to determine required tokens.
+ * Otherwise, falls back to parsing the transaction data for token transfers.
+ *
  * @param transaction - Transaction metadata.
  * @param messenger - Controller messenger.
  * @returns An array of required tokens.
@@ -31,6 +34,18 @@ export function parseRequiredTokens(
   transaction: TransactionMeta,
   messenger: TransactionPayControllerMessenger,
 ): TransactionPayRequiredToken[] {
+  const { requiredAssets } = transaction;
+
+  if (requiredAssets?.length) {
+    const assetTokens = requiredAssets
+      .map((asset) =>
+        buildRequiredToken(transaction, asset.address, asset.amount, messenger),
+      )
+      .filter(Boolean) as TransactionPayRequiredToken[];
+
+    return assetTokens;
+  }
+
   return [
     getTokenTransferToken(transaction, messenger),
     getGasFeeToken(transaction, messenger),