MetaMask · Kriys94 · Feb 13, 2026 · Feb 9, 2026 · Feb 13, 2026 · salimtb
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add optional `trackMetaMetricsEvent` callback to measure and report first init/fetch historical time (duration in ms) to MetaMetrics when the initial asset fetch completes after unlock or app open ([#7871](https://github.com/MetaMask/core/pull/7871))
 - Add `AccountsApiDataSourceConfig` and `PriceDataSourceConfig` types; add `accountsApiDataSourceConfig` and `priceDataSourceConfig` options to `AssetsControllerOptions` for per-data-source configuration (pollInterval, tokenDetectionEnabled, etc.). When `tokenDetectionEnabled` is false, `AccountsApiDataSource` only returns balances for tokens already in state and does not add new tokens ([#7926](https://github.com/MetaMask/core/pull/7926))
 - Add `useExternalService` option to `TokenDetector`, `TokenDetectionOptions`, `RpcDataSourceConfig`, and `RpcDataSourceOptions`. Token detection runs only when both `tokenDetectionEnabled` and `useExternalService` are true and stops when either is false ([#7924](https://github.com/MetaMask/core/pull/7924))
 - Add basic functionality toggle: `isBasicFunctionality` (getter `() => boolean`); no value is stored in the controller. When the getter returns true (matches UI "Basic functionality" ON), token and price APIs are used; when false, only RPC is used. Optional `subscribeToBasicFunctionalityChange(onChange)` lets the consumer register for toggle changes (e.g. extension subscribes to PreferencesController:stateChange, mobile uses its own mechanism); may return an unsubscribe function for controller destroy ([#7904](https://github.com/MetaMask/core/pull/7904))

@@ -13,6 +13,7 @@ import {
   getDefaultAssetsControllerState,
 } from './AssetsController';
 import type {
+  AssetsControllerFirstInitFetchMetaMetricsPayload,
   AssetsControllerMessenger,
   AssetsControllerState,
 } from './AssetsController';
@@ -56,6 +57,12 @@ function createMockInternalAccount(
 type WithControllerOptions = {
   state?: Partial<AssetsControllerState>;
   isBasicFunctionality?: () => boolean;
+  /** Extra options passed to AssetsController constructor (e.g. trackMetaMetricsEvent). */
+  controllerOptions?: Partial<{
+    trackMetaMetricsEvent: (
+      payload: AssetsControllerFirstInitFetchMetaMetricsPayload,
+    ) => void;
+  }>;
 };
 
 type WithControllerCallback<ReturnValue> = ({
@@ -78,10 +85,15 @@ async function withController<ReturnValue>(
     | [WithControllerOptions, WithControllerCallback<ReturnValue>]
     | [WithControllerCallback<ReturnValue>]
 ): Promise<ReturnValue> {
-  const [{ state = {}, isBasicFunctionality = (): boolean => true }, fn]: [
-    WithControllerOptions,
-    WithControllerCallback<ReturnValue>,
-  ] = args.length === 2 ? args : [{}, args[0]];
+  const [
+    {
+      state = {},
+      isBasicFunctionality = (): boolean => true,
+      controllerOptions = {},
+    },
+    fn,
+  ]: [WithControllerOptions, WithControllerCallback<ReturnValue>] =
+    args.length === 2 ? args : [{}, args[0]];
 
   // Use root messenger (MOCK_ANY_NAMESPACE) so data sources can register their actions.
   const messenger: RootMessenger = new Messenger({
@@ -138,6 +150,7 @@ async function withController<ReturnValue>(
     subscribeToBasicFunctionalityChange: (): void => {
       /* no-op for tests */
     },
+    ...controllerOptions,
   });
 
   return fn({ controller, messenger });
@@ -794,6 +807,51 @@ describe('AssetsController', () => {
         expect(true).toBe(true);
       });
     });
+
+    it('invokes trackMetaMetricsEvent with first init fetch duration on unlock', async () => {
+      const trackMetaMetricsEvent = jest.fn();
+
+      await withController(
+        { controllerOptions: { trackMetaMetricsEvent } },
+        async ({ messenger }) => {
+          messenger.publish('KeyringController:unlock');
+
+          // Allow #start() -> getAssets() to resolve so the callback runs
+          await new Promise((resolve) => setTimeout(resolve, 100));
+
+          expect(trackMetaMetricsEvent).toHaveBeenCalledTimes(1);
+          expect(trackMetaMetricsEvent).toHaveBeenCalledWith(
+            expect.objectContaining({
+              durationMs: expect.any(Number),
+              chainIds: expect.any(Array),
+              durationByDataSource: expect.any(Object),
+            }),
+          );
+          const payload = trackMetaMetricsEvent.mock
+            .calls[0][0] as AssetsControllerFirstInitFetchMetaMetricsPayload;
+          expect(payload.durationMs).toBeGreaterThanOrEqual(0);
+          expect(Array.isArray(payload.chainIds)).toBe(true);
+          expect(typeof payload.durationByDataSource).toBe('object');
+        },
+      );
+    });
+
+    it('invokes trackMetaMetricsEvent only once per session until lock', async () => {
+      const trackMetaMetricsEvent = jest.fn();
+
+      await withController(
+        { controllerOptions: { trackMetaMetricsEvent } },
+        async ({ messenger }) => {
+          messenger.publish('KeyringController:unlock');
+          await new Promise((resolve) => setTimeout(resolve, 100));
+
+          messenger.publish('KeyringController:unlock');
+          await new Promise((resolve) => setTimeout(resolve, 100));
+
+          expect(trackMetaMetricsEvent).toHaveBeenCalledTimes(1);
+        },
+      );
+    });
   });
 
   describe('subscribeAssetsPrice', () => {

@@ -60,6 +60,8 @@ import type {
   DataType,
   DataRequest,
   DataResponse,
+  FetchContext,
+  FetchNextFunction,
   NextFunction,
   Middleware,
   SubscriptionResponse,
@@ -202,6 +204,23 @@ export type AssetsControllerMessenger = Messenger<
 // CONTROLLER OPTIONS
 // ============================================================================
 
+/**
+ * Payload for the first init/fetch MetaMetrics event.
+ * Passed to the optional trackMetaMetricsEvent callback when the initial
+ * asset fetch completes after unlock or app open.
+ */
+export type AssetsControllerFirstInitFetchMetaMetricsPayload = {
+  /** Duration of the first init fetch in milliseconds (wall-clock). */
+  durationMs: number;
+  /** Chain IDs requested in the fetch (e.g. ['eip155:1', 'eip155:137']). */
+  chainIds: string[];
+  /**
+   * Exclusive latency in ms per data source (time spent in that source only).
+   * Sum of values approximates durationMs. Order: same as middleware chain.
+   */
+  durationByDataSource: Record<string, number>;
+};
+
 export type AssetsControllerOptions = {
   messenger: AssetsControllerMessenger;
   state?: Partial<AssetsControllerState>;
@@ -235,6 +254,13 @@ export type AssetsControllerOptions = {
   queryApiClient: ApiPlatformClient;
   /** Optional configuration for RpcDataSource. */
   rpcDataSourceConfig?: RpcDataSourceConfig;
+  /**
+   * Optional callback invoked when the first init/fetch completes (e.g. after unlock).
+   * Use this to track first init fetch duration in MetaMetrics.
+   */
+  trackMetaMetricsEvent?: (
+    payload: AssetsControllerFirstInitFetchMetaMetricsPayload,
+  ) => void;
   /** Optional configuration for AccountsApiDataSource. */
   accountsApiDataSourceConfig?: AccountsApiDataSourceConfig;
   /** Optional configuration for PriceDataSource. */
@@ -390,6 +416,14 @@ export class AssetsController extends BaseController<
   /** Default update interval hint passed to data sources */
   readonly #defaultUpdateInterval: number;
 
+  /** Optional callback for first init/fetch MetaMetrics (duration). */
+  readonly #trackMetaMetricsEvent?: (
+    payload: AssetsControllerFirstInitFetchMetaMetricsPayload,
+  ) => void;
+
+  /** Whether we have already reported first init fetch for this session (reset on #stop). */
+  #firstInitFetchReported = false;
+
   readonly #controllerMutex = new Mutex();
 
   /**
@@ -461,6 +495,7 @@ export class AssetsController extends BaseController<
     subscribeToBasicFunctionalityChange,
     queryApiClient,
     rpcDataSourceConfig,
+    trackMetaMetricsEvent,
     accountsApiDataSourceConfig,
     priceDataSourceConfig,
   }: AssetsControllerOptions) {
@@ -477,7 +512,7 @@ export class AssetsController extends BaseController<
     this.#isEnabled = isEnabled();
     this.#isBasicFunctionality = isBasicFunctionality ?? ((): boolean => true);
     this.#defaultUpdateInterval = defaultUpdateInterval;
-
+    this.#trackMetaMetricsEvent = trackMetaMetricsEvent;
     const rpcConfig = rpcDataSourceConfig ?? {};
 
     const onActiveChainsUpdated = (
@@ -701,18 +736,44 @@ export class AssetsController extends BaseController<
 
   /**
    * Execute middlewares with request/response context.
+   * Returns response and exclusive duration per source (sum ≈ wall time).
    *
-   * @param middlewares - Middlewares to execute in order.
+   * @param sources - Data sources or middlewares with getName() and assetsMiddleware (executed in order).
    * @param request - The data request.
    * @param initialResponse - Optional initial response (for enriching existing data).
-   * @returns The final DataResponse after all middlewares have processed.
+   * @returns Response and durationByDataSource (exclusive ms per source name).
    */
   async #executeMiddlewares(
-    middlewares: Middleware[],
+    sources: { getName(): string; assetsMiddleware: Middleware }[],
     request: DataRequest,
     initialResponse: DataResponse = {},
-  ): Promise<DataResponse> {
-    const chain = middlewares.reduceRight<NextFunction>(
+  ): Promise<{
+    response: DataResponse;
+    durationByDataSource: Record<string, number>;
+  }> {
+    const names = sources.map((source) => source.getName());
+    const middlewares = sources.map((source) => source.assetsMiddleware);
+    const inclusive: number[] = [];
+    const wrapped = middlewares.map(
+      (middleware, i) =>
+        (async (
+          ctx: FetchContext,
+          next: FetchNextFunction,
+        ): Promise<{
+          request: DataRequest;
+          response: DataResponse;
+          getAssetsState: () => AssetsControllerStateInternal;
+        }> => {
+          const start = Date.now();
+          try {
+            return await middleware(ctx, next);
+          } finally {
+            inclusive[i] = Date.now() - start;
+          }
+        }) as Middleware,
+    );
+
+    const chain = wrapped.reduceRight<NextFunction>(
       (next, middleware) =>
         async (
           ctx,
@@ -736,7 +797,17 @@ export class AssetsController extends BaseController<
       response: initialResponse,
       getAssetsState: () => this.state as AssetsControllerStateInternal,
     });
-    return result.response;
+
+    const durationByDataSource: Record<string, number> = {};
+    for (let i = 0; i < inclusive.length; i++) {
+      const nextInc = i + 1 < inclusive.length ? (inclusive[i + 1] ?? 0) : 0;
+      const exclusive = Math.max(0, (inclusive[i] ?? 0) - nextInc);
+      const name = names[i];
+      if (name !== undefined) {
+        durationByDataSource[name] = exclusive;
+      }
+    }
+    return { response: result.response, durationByDataSource };
   }
 
   // ============================================================================
@@ -764,27 +835,37 @@ export class AssetsController extends BaseController<
     }
 
     if (options?.forceUpdate) {
+      const startTime = Date.now();
       const request = this.#buildDataRequest(accounts, chainIds, {
         assetTypes,
         dataTypes,
         customAssets: customAssets.length > 0 ? customAssets : undefined,
         forceUpdate: true,
       });
-      const middlewares = this.#isBasicFunctionality()
+      const sources = this.#isBasicFunctionality()
         ? [
-            this.#accountsApiDataSource.assetsMiddleware,
-            this.#snapDataSource.assetsMiddleware,
-            this.#rpcDataSource.assetsMiddleware,
-            this.#detectionMiddleware.assetsMiddleware,
-            this.#tokenDataSource.assetsMiddleware,
-            this.#priceDataSource.assetsMiddleware,
+            this.#accountsApiDataSource,
+            this.#snapDataSource,
+            this.#rpcDataSource,
+            this.#detectionMiddleware,
+            this.#tokenDataSource,
+            this.#priceDataSource,
           ]
-        : [
-            this.#rpcDataSource.assetsMiddleware,
-            this.#detectionMiddleware.assetsMiddleware,
-          ];
-      const response = await this.#executeMiddlewares(middlewares, request);
+        : [this.#rpcDataSource, this.#detectionMiddleware];
+      const { response, durationByDataSource } = await this.#executeMiddlewares(
+        sources,
+        request,
+      );
       await this.#updateState(response);
+      if (this.#trackMetaMetricsEvent && !this.#firstInitFetchReported) {
+        this.#firstInitFetchReported = true;
+        const durationMs = Date.now() - startTime;
+        this.#trackMetaMetricsEvent({
+          durationMs,
+          chainIds,
+          durationByDataSource,
+        });
+      }
     }
 
     return this.#getAssetsFromState(accounts, chainIds, assetTypes);
@@ -1335,14 +1416,12 @@ export class AssetsController extends BaseController<
     });
 
     this.#subscribeAssets();
-    if (this.#selectedAccounts.length > 0) {
-      this.getAssets(this.#selectedAccounts, {
-        chainIds: [...this.#enabledChains],
-        forceUpdate: true,
-      }).catch((error) => {
-        log('Failed to fetch assets', error);
-      });
-    }
+    this.getAssets(this.#selectedAccounts, {
+      chainIds: [...this.#enabledChains],
+      forceUpdate: true,
+    }).catch((error) => {
+      log('Failed to fetch assets', error);
+    });
   }
 
   /**
@@ -1355,6 +1434,8 @@ export class AssetsController extends BaseController<
       hasPriceSubscription: this.#activeSubscriptions.has('ds:PriceDataSource'),
     });
 
+    this.#firstInitFetchReported = false;
+
     // Stop price subscription first (uses direct messenger call)
     this.unsubscribeAssetsPrice();
 
@@ -1726,12 +1807,8 @@ export class AssetsController extends BaseController<
 
     // Run through enrichment middlewares (Event Stack: Detection → Token → Price)
     // Include 'metadata' in dataTypes so TokenDataSource runs to enrich detected assets
-    const enrichedResponse = await this.#executeMiddlewares(
-      [
-        this.#detectionMiddleware.assetsMiddleware,
-        this.#tokenDataSource.assetsMiddleware,
-        this.#priceDataSource.assetsMiddleware,
-      ],
+    const { response: enrichedResponse } = await this.#executeMiddlewares(
+      [this.#detectionMiddleware, this.#tokenDataSource, this.#priceDataSource],
       request ?? {
         accountsWithSupportedChains: [],
         chainIds: [],

@@ -158,7 +158,7 @@ describe('PriceDataSource', () => {
 
   it('initializes with correct name', () => {
     const { controller } = setupController();
-    expect(controller.name).toBe('PriceDataSource');
+    expect(controller.getName()).toBe('PriceDataSource');
     controller.destroy();
   });
 

@@ -104,7 +104,11 @@ function isValidMarketData(data: unknown): data is SpotPriceMarketData {
  * Usage: Create with queryApiClient; subscribe() requires getAssetsState in the request for balance-based pricing.
  */
 export class PriceDataSource {
-  readonly name = CONTROLLER_NAME;
+  static readonly controllerName = CONTROLLER_NAME;
+
+  getName(): string {
+    return PriceDataSource.controllerName;
+  }
 
   readonly #currency: SupportedCurrency;
 

@@ -109,6 +109,10 @@ function transformV3AssetResponseToMetadata(
 export class TokenDataSource {
   readonly name = CONTROLLER_NAME;
 
+  getName(): string {
+    return this.name;
+  }
+
   /** ApiPlatformClient for cached API calls */
   readonly #apiClient: ApiPlatformClient;
 

@@ -9,6 +9,7 @@ export type {
   AssetsControllerState,
   AssetsControllerMessenger,
   AssetsControllerOptions,
+  AssetsControllerFirstInitFetchMetaMetricsPayload,
   AssetsControllerGetStateAction,
   AssetsControllerActions,
   AssetsControllerStateChangeEvent,