feat: transaction batch security validation (#5526)

Support triggering security validation in the client while processing
transaction batches.

Specifically:

- Add `ValidateSecurityRequest` type.
- Add optional `validateSecurity` callback to `TransactionBatchRequest`
type.
- Add optional `securityAlertId` to `AddTransactionBatchRequest` type.
- Add optional `securityAlertId` to `SecurityAlertResponse` type.
- Call `validateSecurity` callback after generating EIP-7702
transaction.
- Include `delegationMock` if an EIP-7702 type 4 transaction.

Relates to [

See `CHANGELOG.md`.

- [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 highlighted breaking changes using the "BREAKING" category
above as appropriate
- [x] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

Author: matthewwalsh0

packages/transaction-controller/src/index.ts

@@ -62,6 +62,7 @@ export type {
   TransactionMeta,
   TransactionParams,
   TransactionReceipt,
+  ValidateSecurityRequest,
 } from './types';
 export {
   GasFeeEstimateLevel,

packages/transaction-controller/src/types.ts

@@ -1132,10 +1132,11 @@ export type TransactionError = {
  * Type for security alert response from transaction validator.
  */
 export type SecurityAlertResponse = {
-  reason: string;
   features?: string[];
-  result_type: string;
   providerRequestsCount?: Record<string, number>;
+  reason: string;
+  result_type: string;
+  securityAlertId?: string;
 };
 
 /** Alternate priority levels for which values are provided in gas fee estimates. */
@@ -1474,8 +1475,22 @@ export type TransactionBatchRequest = {
   /** Whether an approval request should be created to require confirmation from the user. */
   requireApproval?: boolean;
 
+  /** Security alert ID to persist on the transaction. */
+  securityAlertId?: string;
+
   /** Transactions to be submitted as part of the batch. */
   transactions: TransactionBatchSingleRequest[];
+
+  /**
+   * Callback to trigger security validation in the client.
+   *
+   * @param request - The JSON-RPC request to validate.
+   * @param chainId - The chain ID of the transaction batch.
+   */
+  validateSecurity?: (
+    request: ValidateSecurityRequest,
+    chainId: Hex,
+  ) => Promise<void>;
 };
 
 /**
@@ -1485,3 +1500,17 @@ export type TransactionBatchResult = {
   /** ID of the batch to locate related transactions. */
   batchId: Hex;
 };
+
+/**
+ * Request to validate security of a transaction in the client.
+ */
+export type ValidateSecurityRequest = {
+  /** JSON-RPC method to validate. */
+  method: string;
+
+  /** Parameters of the JSON-RPC method to validate. */
+  params: unknown[];
+
+  /** Optional EIP-7702 delegation to mock for the transaction sender. */
+  delegationMock?: Hex;
+};

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

@@ -43,8 +43,17 @@ const PUBLIC_KEY_MOCK = '0x112233';
 const BATCH_ID_CUSTOM_MOCK = '0x123456';
 const GET_ETH_QUERY_MOCK = jest.fn();
 const GET_INTERNAL_ACCOUNTS_MOCK = jest.fn().mockReturnValue([]);
-
-const TRANSACTION_META_MOCK = {} as TransactionMeta;
+const SECURITY_ALERT_ID_MOCK = '123-456';
+
+const TRANSACTION_META_MOCK = {
+  id: BATCH_ID_CUSTOM_MOCK,
+  txParams: {
+    from: FROM_MOCK,
+    to: TO_MOCK,
+    data: DATA_MOCK,
+    value: VALUE_MOCK,
+  },
+} as TransactionMeta;
 
 describe('Batch Utils', () => {
   const doesChainSupportEIP7702Mock = jest.mocked(doesChainSupportEIP7702);
@@ -84,6 +93,8 @@ describe('Batch Utils', () => {
         type: TransactionType.simpleSend,
       });
 
+      getChainIdMock.mockReturnValue(CHAIN_ID_MOCK);
+
       request = {
         addTransaction: addTransactionMock,
         getChainId: getChainIdMock,
@@ -383,6 +394,138 @@ describe('Batch Utils', () => {
         'Validation Error',
       );
     });
+
+    it('adds security alert ID to transaction', async () => {
+      doesChainSupportEIP7702Mock.mockReturnValueOnce(true);
+
+      isAccountUpgradedToEIP7702Mock.mockResolvedValueOnce({
+        delegationAddress: undefined,
+        isSupported: true,
+      });
+
+      addTransactionMock.mockResolvedValueOnce({
+        transactionMeta: TRANSACTION_META_MOCK,
+        result: Promise.resolve(''),
+      });
+
+      generateEIP7702BatchTransactionMock.mockReturnValueOnce({
+        to: TO_MOCK,
+        data: DATA_MOCK,
+        value: VALUE_MOCK,
+      });
+
+      request.request.securityAlertId = SECURITY_ALERT_ID_MOCK;
+
+      await addTransactionBatch(request);
+
+      expect(addTransactionMock).toHaveBeenCalledTimes(1);
+      expect(addTransactionMock).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.objectContaining({
+          securityAlertResponse: {
+            securityAlertId: SECURITY_ALERT_ID_MOCK,
+          },
+        }),
+      );
+    });
+
+    describe('validates security', () => {
+      it('using transaction params', async () => {
+        doesChainSupportEIP7702Mock.mockReturnValueOnce(true);
+
+        isAccountUpgradedToEIP7702Mock.mockResolvedValueOnce({
+          delegationAddress: undefined,
+          isSupported: true,
+        });
+
+        addTransactionMock.mockResolvedValueOnce({
+          transactionMeta: TRANSACTION_META_MOCK,
+          result: Promise.resolve(''),
+        });
+
+        generateEIP7702BatchTransactionMock.mockReturnValueOnce({
+          to: TO_MOCK,
+          data: DATA_MOCK,
+          value: VALUE_MOCK,
+        });
+
+        const validateSecurityMock = jest.fn();
+        validateSecurityMock.mockResolvedValueOnce({});
+
+        request.request.validateSecurity = validateSecurityMock;
+
+        await addTransactionBatch(request);
+
+        expect(validateSecurityMock).toHaveBeenCalledTimes(1);
+        expect(validateSecurityMock).toHaveBeenCalledWith(
+          {
+            delegationMock: undefined,
+            method: 'eth_sendTransaction',
+            params: [
+              {
+                authorizationList: undefined,
+                data: DATA_MOCK,
+                from: FROM_MOCK,
+                to: TO_MOCK,
+                type: TransactionEnvelopeType.feeMarket,
+                value: VALUE_MOCK,
+              },
+            ],
+          },
+          CHAIN_ID_MOCK,
+        );
+      });
+
+      it('using delegation mock if not upgraded', async () => {
+        doesChainSupportEIP7702Mock.mockReturnValueOnce(true);
+
+        isAccountUpgradedToEIP7702Mock.mockResolvedValueOnce({
+          delegationAddress: undefined,
+          isSupported: false,
+        });
+
+        addTransactionMock.mockResolvedValueOnce({
+          transactionMeta: TRANSACTION_META_MOCK,
+          result: Promise.resolve(''),
+        });
+
+        generateEIP7702BatchTransactionMock.mockReturnValueOnce({
+          to: TO_MOCK,
+          data: DATA_MOCK,
+          value: VALUE_MOCK,
+        });
+
+        getEIP7702UpgradeContractAddressMock.mockReturnValue(
+          CONTRACT_ADDRESS_MOCK,
+        );
+
+        const validateSecurityMock = jest.fn();
+        validateSecurityMock.mockResolvedValueOnce({});
+
+        request.request.validateSecurity = validateSecurityMock;
+
+        await addTransactionBatch(request);
+
+        expect(validateSecurityMock).toHaveBeenCalledTimes(1);
+        expect(validateSecurityMock).toHaveBeenCalledWith(
+          {
+            delegationMock: CONTRACT_ADDRESS_MOCK,
+            method: 'eth_sendTransaction',
+            params: [
+              {
+                authorizationList: undefined,
+                data: DATA_MOCK,
+                from: FROM_MOCK,
+                to: TO_MOCK,
+                type: TransactionEnvelopeType.feeMarket,
+                value: VALUE_MOCK,
+              },
+            ],
+          },
+          CHAIN_ID_MOCK,
+        );
+      });
+    });
   });
 
   describe('isAtomicBatchSupported', () => {

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

@@ -24,7 +24,9 @@ import {
 import { projectLogger } from '../logger';
 import type {
   NestedTransactionMetadata,
+  SecurityAlertResponse,
   TransactionBatchSingleRequest,
+  ValidateSecurityRequest,
 } from '../types';
 import {
   TransactionEnvelopeType,
@@ -83,7 +85,9 @@ export async function addTransactionBatch(
     from,
     networkClientId,
     requireApproval,
+    securityAlertId,
     transactions,
+    validateSecurity,
   } = userRequest;
 
   log('Adding', userRequest);
@@ -144,15 +148,40 @@ export async function addTransactionBatch(
     txParams.authorizationList = [{ address: upgradeContractAddress }];
   }
 
+  if (validateSecurity) {
+    const securityRequest: ValidateSecurityRequest = {
+      method: 'eth_sendTransaction',
+      params: [
+        {
+          ...txParams,
+          authorizationList: undefined,
+          type: TransactionEnvelopeType.feeMarket,
+        },
+      ],
+      delegationMock: txParams.authorizationList?.[0]?.address,
+    };
+
+    log('Security request', securityRequest);
+
+    validateSecurity(securityRequest, chainId).catch((error) => {
+      log('Security validation failed', error);
+    });
+  }
+
   log('Adding batch transaction', txParams, networkClientId);
 
   const batchId = batchIdOverride ?? generateBatchId();
 
+  const securityAlertResponse = securityAlertId
+    ? ({ securityAlertId } as SecurityAlertResponse)
+    : undefined;
+
   const { result } = await addTransaction(txParams, {
     batchId,
     nestedTransactions,
     networkClientId,
     requireApproval,
+    securityAlertResponse,
     type: TransactionType.batch,
   });