feat: tracking headers

src/SmartTransactionsController.test.ts

@@ -42,7 +42,12 @@ import {
   type SmartTransactionsControllerMessenger,
 } from './SmartTransactionsController';
 import type { SmartTransaction, UnsignedTransaction, Hex } from './types';
-import { SmartTransactionStatuses, ClientId } from './types';
+import {
+  SmartTransactionStatuses,
+  ClientId,
+  TransactionFeature,
+  TransactionKind,
+} from './types';
 import * as utils from './utils';
 
 type AllActions = MessengerActions<SmartTransactionsControllerMessenger>;
@@ -979,6 +984,211 @@ describe('SmartTransactionsController', () => {
         );
       });
     });
+
+    describe('trackingHeaders', () => {
+      it('sends X-Transaction-Feature and X-Transaction-Kind headers when trackingHeaders is provided', async () => {
+        await withController(async ({ controller }) => {
+          const signedTransaction = createSignedTransaction();
+          const submitTransactionsApiResponse =
+            createSubmitTransactionsApiResponse();
+
+          const handleFetchSpy = jest
+            .spyOn(utils, 'handleFetch')
+            .mockResolvedValue(submitTransactionsApiResponse);
+
+          await controller.submitSignedTransactions({
+            signedTransactions: [signedTransaction],
+            txParams: createTxParams(),
+            trackingHeaders: {
+              feature: TransactionFeature.Send,
+              kind: TransactionKind.STX,
+            },
+          });
+
+          expect(handleFetchSpy).toHaveBeenCalledWith(
+            expect.stringContaining('/submitTransactions'),
+            expect.objectContaining({
+              headers: expect.objectContaining({
+                'Content-Type': 'application/json',
+                'X-Client-Id': ClientId.Mobile,
+                'X-Transaction-Feature': 'Send',
+                'X-Transaction-Kind': 'STX',
+              }),
+            }),
+          );
+
+          handleFetchSpy.mockRestore();
+        });
+      });
+
+      it('sends only X-Transaction-Feature header when only feature is provided', async () => {
+        await withController(async ({ controller }) => {
+          const signedTransaction = createSignedTransaction();
+          const submitTransactionsApiResponse =
+            createSubmitTransactionsApiResponse();
+
+          const handleFetchSpy = jest
+            .spyOn(utils, 'handleFetch')
+            .mockResolvedValue(submitTransactionsApiResponse);
+
+          await controller.submitSignedTransactions({
+            signedTransactions: [signedTransaction],
+            txParams: createTxParams(),
+            trackingHeaders: {
+              feature: TransactionFeature.Swap,
+            },
+          });
+
+          expect(handleFetchSpy).toHaveBeenCalledWith(
+            expect.stringContaining('/submitTransactions'),
+            expect.objectContaining({
+              headers: expect.objectContaining({
+                'Content-Type': 'application/json',
+                'X-Client-Id': ClientId.Mobile,
+                'X-Transaction-Feature': 'Swap',
+              }),
+            }),
+          );
+
+          // Ensure X-Transaction-Kind is NOT in the headers
+          const [, options] = handleFetchSpy.mock.calls[0];
+          expect(options?.headers).not.toHaveProperty('X-Transaction-Kind');
+
+          handleFetchSpy.mockRestore();
+        });
+      });
+
+      it('sends only X-Transaction-Kind header when only kind is provided', async () => {
+        await withController(async ({ controller }) => {
+          const signedTransaction = createSignedTransaction();
+          const submitTransactionsApiResponse =
+            createSubmitTransactionsApiResponse();
+
+          const handleFetchSpy = jest
+            .spyOn(utils, 'handleFetch')
+            .mockResolvedValue(submitTransactionsApiResponse);
+
+          await controller.submitSignedTransactions({
+            signedTransactions: [signedTransaction],
+            txParams: createTxParams(),
+            trackingHeaders: {
+              kind: TransactionKind.GaslessSendBundle,
+            },
+          });
+
+          expect(handleFetchSpy).toHaveBeenCalledWith(
+            expect.stringContaining('/submitTransactions'),
+            expect.objectContaining({
+              headers: expect.objectContaining({
+                'Content-Type': 'application/json',
+                'X-Client-Id': ClientId.Mobile,
+                'X-Transaction-Kind': 'GaslessSendBundle',
+              }),
+            }),
+          );
+
+          // Ensure X-Transaction-Feature is NOT in the headers
+          const [, options] = handleFetchSpy.mock.calls[0];
+          expect(options?.headers).not.toHaveProperty('X-Transaction-Feature');
+
+          handleFetchSpy.mockRestore();
+        });
+      });
+
+      it('does not include tracking headers when trackingHeaders is not provided', async () => {
+        await withController(async ({ controller }) => {
+          const signedTransaction = createSignedTransaction();
+          const submitTransactionsApiResponse =
+            createSubmitTransactionsApiResponse();
+
+          const handleFetchSpy = jest
+            .spyOn(utils, 'handleFetch')
+            .mockResolvedValue(submitTransactionsApiResponse);
+
+          await controller.submitSignedTransactions({
+            signedTransactions: [signedTransaction],
+            txParams: createTxParams(),
+            // No trackingHeaders provided
+          });
+
+          const [, options] = handleFetchSpy.mock.calls[0];
+          expect(options?.headers).not.toHaveProperty('X-Transaction-Feature');
+          expect(options?.headers).not.toHaveProperty('X-Transaction-Kind');
+
+          handleFetchSpy.mockRestore();
+        });
+      });
+
+      it('supports all TransactionFeature values', async () => {
+        await withController(async ({ controller }) => {
+          const signedTransaction = createSignedTransaction();
+          const submitTransactionsApiResponse =
+            createSubmitTransactionsApiResponse();
+
+          const handleFetchSpy = jest
+            .spyOn(utils, 'handleFetch')
+            .mockResolvedValue(submitTransactionsApiResponse);
+
+          // Test each feature value
+          const features = Object.values(TransactionFeature);
+          for (const feature of features) {
+            handleFetchSpy.mockClear();
+
+            await controller.submitSignedTransactions({
+              signedTransactions: [signedTransaction],
+              txParams: createTxParams(),
+              trackingHeaders: { feature },
+            });
+
+            expect(handleFetchSpy).toHaveBeenCalledWith(
+              expect.stringContaining('/submitTransactions'),
+              expect.objectContaining({
+                headers: expect.objectContaining({
+                  'X-Transaction-Feature': feature,
+                }),
+              }),
+            );
+          }
+
+          handleFetchSpy.mockRestore();
+        });
+      });
+
+      it('supports all TransactionKind values', async () => {
+        await withController(async ({ controller }) => {
+          const signedTransaction = createSignedTransaction();
+          const submitTransactionsApiResponse =
+            createSubmitTransactionsApiResponse();
+
+          const handleFetchSpy = jest
+            .spyOn(utils, 'handleFetch')
+            .mockResolvedValue(submitTransactionsApiResponse);
+
+          // Test each kind value
+          const kinds = Object.values(TransactionKind);
+          for (const kind of kinds) {
+            handleFetchSpy.mockClear();
+
+            await controller.submitSignedTransactions({
+              signedTransactions: [signedTransaction],
+              txParams: createTxParams(),
+              trackingHeaders: { kind },
+            });
+
+            expect(handleFetchSpy).toHaveBeenCalledWith(
+              expect.stringContaining('/submitTransactions'),
+              expect.objectContaining({
+                headers: expect.objectContaining({
+                  'X-Transaction-Kind': kind,
+                }),
+              }),
+            );
+          }
+
+          handleFetchSpy.mockRestore();
+        });
+      });
+    });
   });
 
   describe('fetchSmartTransactionsStatus', () => {

src/SmartTransactionsController.ts

@@ -47,6 +47,7 @@
   MetaMetricsProps,
   FeatureFlags,
   ClientId,
+  TransactionTrackingHeaders,
 } from './types';
 import { APIType, SmartTransactionStatuses } from './types';
 import {
@@ -240,12 +241,22 @@
   #trace: TraceCallback;
 
   /* istanbul ignore next */
-  async #fetch(request: string, options?: RequestInit) {
+  async #fetch(
+    request: string,
+    options?: RequestInit,
+    trackingHeaders?: TransactionTrackingHeaders,
+  ) {
     const fetchOptions = {
       ...options,
       headers: {
         'Content-Type': 'application/json',
         ...(this.#clientId && { 'X-Client-Id': this.#clientId }),
+        ...(trackingHeaders?.feature && {
+          'X-Transaction-Feature': trackingHeaders.feature,
+        }),
+        ...(trackingHeaders?.kind && {
+          'X-Transaction-Kind': trackingHeaders.kind,
+        }),
       },
     };
 
@@ -335,9 +346,9 @@
       isSmartTransactionPending,
     );
     if (!this.timeoutHandle && pendingTransactions?.length > 0) {
       this.poll();
     } else if (this.timeoutHandle && pendingTransactions?.length === 0) {
       this.stop();
     }
   }
 
@@ -362,7 +373,7 @@
     }
 
     this.timeoutHandle = setInterval(() => {
       safelyExecute(async () => this.updateSmartTransactions());
     }, this.#interval);
     await safelyExecute(async () => this.updateSmartTransactions());
   }
@@ -429,7 +440,7 @@
       ethQuery = new EthQuery(provider);
     }
 
     this.#createOrUpdateSmartTransaction(smartTransaction, {
       chainId,
       ethQuery,
     });
@@ -846,12 +857,14 @@
     signedTransactions,
     signedCanceledTransactions = [],
     networkClientId,
+    trackingHeaders,
   }: {
     signedTransactions: SignedTransaction[];
     signedCanceledTransactions?: SignedCanceledTransaction[];
     transactionMeta?: TransactionMeta;
     txParams?: TransactionParams;
     networkClientId?: NetworkClientId;
+    trackingHeaders?: TransactionTrackingHeaders;
   }) {
     const selectedNetworkClientId =
       networkClientId ??
@@ -874,6 +887,7 @@
               rawCancelTxs: signedCanceledTransactions,
             }),
           },
+          trackingHeaders,
         ),
     );
     const time = Date.now();

src/index.ts

@@ -15,10 +15,13 @@ export {
   type IndividualTxFees,
   type FeatureFlags,
   type SmartTransaction,
+  type TransactionTrackingHeaders,
   SmartTransactionMinedTx,
   SmartTransactionCancellationReason,
   SmartTransactionStatuses,
   ClientId,
+  TransactionFeature,
+  TransactionKind,
 } from './types';
 export { MetaMetricsEventName, MetaMetricsEventCategory } from './constants';
 export {

src/types.ts

@@ -140,3 +140,38 @@ export type FeatureFlags = {
     extensionReturnTxHashAsap?: boolean;
   };
 };
+
+/**
+ * Transaction feature - identifies which MetaMask feature initiated the transaction
+ */
+export enum TransactionFeature {
+  Swap = 'Swap',
+  Bridge = 'Bridge',
+  Send = 'Send',
+  Sell = 'Sell',
+  Perps = 'Perps',
+  Predictions = 'Predictions',
+  Card = 'Card',
+  Pay = 'Pay',
+  DAppTransaction = 'dAppTransaction',
+  Earn = 'Earn',
+  AccountUpgrade = 'AccountUpgrade',
+}
+
+/**
+ * Transaction kind - identifies the type of transaction mechanism used
+ */
+export enum TransactionKind {
+  Regular = 'Regular',
+  STX = 'STX',
+  GaslessSendBundle = 'GaslessSendBundle',
+  GaslessEIP7702 = 'GaslessEIP7702',
+}
+
+/**
+ * Optional headers for tracking transaction feature and kind
+ */
+export type TransactionTrackingHeaders = {
+  feature?: TransactionFeature;
+  kind?: TransactionKind;
+};