feat(AssetController): add hiddenAssets state (#7777)

## Explanation

This PR adds support for hidden assets in the `AssetsController`,
similar to how `allIgnoredAssets` works in `MultichainAssetsController`.

**Current State:**
Users currently have no way to hide assets they don't want to see or
track in the new AssetsController architecture. The
`MultichainAssetsController` already has this capability via
`allIgnoredAssets`, but the new unified `AssetsController` was missing
this feature.

**Solution:**
Added a `hiddenAssets` field to the `AssetsController` state that stores
hidden assets per account (CAIP-19 asset IDs). This allows users to hide
assets they don't want to track and/or see.

**Changes:**
1. **State**: Added `hiddenAssets: { [accountId: string]: string[] }` to
`AssetsControllerState`
2. **Methods**: Added `hideAsset()`, `unhideAsset()`,
`getHiddenAssets()`, and `isAssetHidden()` methods
3. **Actions**: Added corresponding action types
(`AssetsControllerHideAssetAction`, `AssetsControllerUnhideAssetAction`,
`AssetsControllerGetHiddenAssetsAction`) and registered handlers
4. **Custom Assets Integration**: When a custom asset is added via
`addCustomAsset()`, it's automatically unhidden if it was previously
hidden (matching the behavior of
`MultichainAssetsController.addAssets()`)
5. **RPC Tracking**: Updated `RpcDataSource` and `BalanceFetcher` to
filter out hidden assets from balance polling, so hidden assets won't be
tracked or updated

**Type Updates:**
- Added `hiddenAssets` to `AssetsControllerState`
- Added `hiddenAssets` to `AssetsControllerStateInternal`
- Added `hiddenAssets` to `AssetsBalanceState` in evm-rpc-services types

## References

- Related to the Hide Token feature for the new unified AssetsController
architecture
- Pattern follows `allIgnoredAssets` in `MultichainAssetsController`

## 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
- [ ] 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)
- [ ] 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 `assetPreferences` state slice and changes
`getAssets` to filter hidden assets, which can affect UI output and
downstream consumers relying on prior state shape/types.
> 
> **Overview**
> Adds a new persisted `assetPreferences` state (with
`AssetPreferences`) to store per-asset UI flags like `hidden`, and
introduces `hideAsset`/`unhideAsset` actions to manage this globally.
> 
> Updates `getAssets` to exclude hidden assets from returned results
(while leaving balance/price tracking intact), and ensures
`addCustomAsset` automatically unhides an asset if it was previously
hidden.
> 
> Tightens `AssetsControllerState` typing from generic `Json`/`string[]`
to semantic types (`AssetMetadata`, `AssetBalance`, `AssetPrice`,
`Caip19AssetId[]`), and adjusts `RpcDataSource`/tests to match the
narrowed `AssetsController:getState` expectations.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
a661f7e. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Kriys94

packages/assets-controller/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `assetPreferences` state and `AssetPreferences` type for per-asset UI preferences (e.g. `hidden`), separate from `assetsMetadata` ([#7777](https://github.com/MetaMask/core/pull/7777))
+- Add `hideAsset(assetId)`, `unhideAsset(assetId)` for managing hidden assets globally; hidden assets are excluded from `getAssets` but balance updates continue to be tracked ([#7777](https://github.com/MetaMask/core/pull/7777))
+
+### Changed
+
+- Narrow `AssetsControllerState` types from `Json` to semantic types: `assetsMetadata` → `AssetMetadata`, `assetsBalance` → `AssetBalance`, `assetsPrice` → `AssetPrice`, `assetPreferences` → `AssetPreferences`, `customAssets` → `Caip19AssetId[]` ([#7777](https://github.com/MetaMask/core/pull/7777))
+
 ## [0.1.0]
 
 ### Added

packages/assets-controller/src/AssetsController.test.ts

@@ -201,6 +201,7 @@ describe('AssetsController', () => {
         assetsBalance: {},
         assetsPrice: {},
         customAssets: {},
+        assetPreferences: {},
       });
     });
   });
@@ -213,6 +214,7 @@ describe('AssetsController', () => {
           assetsBalance: {},
           assetsPrice: {},
           customAssets: {},
+          assetPreferences: {},
         });
       });
     });
@@ -291,6 +293,7 @@ describe('AssetsController', () => {
 
       // Controller should still have default state (from super() call)
       expect(controller.state).toStrictEqual({
+        assetPreferences: {},
         assetsMetadata: {},
         assetsBalance: {},
         assetsPrice: {},
@@ -311,6 +314,7 @@ describe('AssetsController', () => {
       await withController(({ controller, messenger }) => {
         // Controller should have default state
         expect(controller.state).toStrictEqual({
+          assetPreferences: {},
           assetsMetadata: {},
           assetsBalance: {},
           assetsPrice: {},

packages/assets-controller/src/AssetsController.ts

@@ -19,7 +19,6 @@ import type {
   NetworkEnablementControllerEvents,
   NetworkEnablementControllerState,
 } from '@metamask/network-enablement-controller';
-import type { Json } from '@metamask/utils';
 import { parseCaipAssetType } from '@metamask/utils';
 import { Mutex } from 'async-mutex';
 import BigNumberJS from 'bignumber.js';
@@ -39,6 +38,7 @@ import { projectLogger, createModuleLogger } from './logger';
 import type { DetectionMiddlewareGetAssetsMiddlewareAction } from './middlewares/DetectionMiddleware';
 import type {
   AccountId,
+  AssetPreferences,
   ChainId,
   Caip19AssetId,
   AssetMetadata,
@@ -75,34 +75,36 @@ const log = createModuleLogger(projectLogger, CONTROLLER_NAME);
 /**
  * State structure for AssetsController.
  *
- * All values are JSON-serializable. The type is widened to satisfy
- * StateConstraint from BaseController, but the actual runtime values
- * conform to AssetMetadata, AssetPrice, and AssetBalance interfaces.
+ * All values are JSON-serializable. UI preferences (e.g. hidden) are in
+ * assetPreferences, not in metadata.
  *
  * @see AssetsControllerStateInternal for the semantic type structure
  */
 export type AssetsControllerState = {
   /** Shared metadata for all assets (stored once per asset) */
-  assetsMetadata: { [assetId: string]: Json };
+  assetsMetadata: { [assetId: string]: AssetMetadata };
   /** Per-account balance data */
-  assetsBalance: { [accountId: string]: { [assetId: string]: Json } };
+  assetsBalance: { [accountId: string]: { [assetId: string]: AssetBalance } };
   /** Price data for assets */
-  assetsPrice: { [assetId: string]: Json };
+  assetsPrice: { [assetId: string]: AssetPrice };
   /** Custom assets added by users per account (CAIP-19 asset IDs) */
-  customAssets: { [accountId: string]: string[] };
+  customAssets: { [accountId: string]: Caip19AssetId[] };
+  /** UI preferences per asset (e.g. hidden) */
+  assetPreferences: { [assetId: string]: AssetPreferences };
 };
 
 /**
  * Returns the default state for AssetsController.
  *
- * @returns The default AssetsController state with empty metadata, balance, price, and customAssets maps.
+ * @returns The default AssetsController state with empty maps.
  */
 export function getDefaultAssetsControllerState(): AssetsControllerState {
   return {
     assetsMetadata: {},
     assetsBalance: {},
     assetsPrice: {},
     customAssets: {},
+    assetPreferences: {},
   };
 }
 
@@ -160,6 +162,16 @@ export type AssetsControllerGetCustomAssetsAction = {
   handler: AssetsController['getCustomAssets'];
 };
 
+export type AssetsControllerHideAssetAction = {
+  type: `${typeof CONTROLLER_NAME}:hideAsset`;
+  handler: AssetsController['hideAsset'];
+};
+
+export type AssetsControllerUnhideAssetAction = {
+  type: `${typeof CONTROLLER_NAME}:unhideAsset`;
+  handler: AssetsController['unhideAsset'];
+};
+
 export type AssetsControllerActions =
   | AssetsControllerGetStateAction
   | AssetsControllerGetAssetsAction
@@ -170,7 +182,9 @@ export type AssetsControllerActions =
   | AssetsControllerAssetsUpdateAction
   | AssetsControllerAddCustomAssetAction
   | AssetsControllerRemoveCustomAssetAction
-  | AssetsControllerGetCustomAssetsAction;
+  | AssetsControllerGetCustomAssetsAction
+  | AssetsControllerHideAssetAction
+  | AssetsControllerUnhideAssetAction;
 
 export type AssetsControllerStateChangeEvent = ControllerStateChangeEvent<
   typeof CONTROLLER_NAME,
@@ -292,6 +306,12 @@ const stateMetadata: StateMetadata<AssetsControllerState> = {
     includeInDebugSnapshot: false,
     usedInUi: true,
   },
+  assetPreferences: {
+    persist: true,
+    includeInStateLogs: false,
+    includeInDebugSnapshot: false,
+    usedInUi: true,
+  },
 };
 
 // ============================================================================
@@ -627,6 +647,16 @@ export class AssetsController extends BaseController<
       'AssetsController:getCustomAssets',
       this.getCustomAssets.bind(this),
     );
+
+    this.messenger.registerActionHandler(
+      'AssetsController:hideAsset',
+      this.hideAsset.bind(this),
+    );
+
+    this.messenger.registerActionHandler(
+      'AssetsController:unhideAsset',
+      this.unhideAsset.bind(this),
+    );
   }
 
   // ============================================================================
@@ -872,6 +902,7 @@ export class AssetsController extends BaseController<
   /**
    * Add a custom asset for an account.
    * Custom assets are included in subscription and fetch operations.
+   * Adding a custom asset also unhides it if it was previously hidden.
    *
    * @param accountId - The account ID to add the custom asset for.
    * @param assetId - The CAIP-19 asset ID to add.
@@ -894,6 +925,15 @@ export class AssetsController extends BaseController<
       if (!customAssets[accountId].includes(normalizedAssetId)) {
         customAssets[accountId].push(normalizedAssetId);
       }
+
+      // Unhide the asset if it was hidden (via assetPreferences)
+      const prefs = state.assetPreferences[normalizedAssetId];
+      if (prefs?.hidden) {
+        delete prefs.hidden;
+        if (Object.keys(prefs).length === 0) {
+          delete state.assetPreferences[normalizedAssetId];
+        }
+      }
     });
 
     // Fetch data for the newly added custom asset
@@ -919,15 +959,14 @@ export class AssetsController extends BaseController<
     log('Removing custom asset', { accountId, assetId: normalizedAssetId });
 
     this.update((state) => {
-      const customAssets = state.customAssets as Record<string, string[]>;
-      if (customAssets[accountId]) {
-        customAssets[accountId] = customAssets[accountId].filter(
+      if (state.customAssets[accountId]) {
+        state.customAssets[accountId] = state.customAssets[accountId].filter(
           (id) => id !== normalizedAssetId,
         );
 
         // Clean up empty arrays
-        if (customAssets[accountId].length === 0) {
-          delete customAssets[accountId];
+        if (state.customAssets[accountId].length === 0) {
+          delete state.customAssets[accountId];
         }
       }
     });
@@ -940,7 +979,52 @@ export class AssetsController extends BaseController<
    * @returns Array of CAIP-19 asset IDs for the account's custom assets.
    */
   getCustomAssets(accountId: AccountId): Caip19AssetId[] {
-    return (this.state.customAssets[accountId] ?? []) as Caip19AssetId[];
+    return this.state.customAssets[accountId] ?? [];
+  }
+
+  // ============================================================================
+  // HIDDEN ASSETS MANAGEMENT
+  // ============================================================================
+
+  /**
+   * Hide an asset globally.
+   * Hidden assets are excluded from the asset list returned by getAssets.
+   * The hidden state is stored in assetPreferences.
+   *
+   * @param assetId - The CAIP-19 asset ID to hide.
+   */
+  hideAsset(assetId: Caip19AssetId): void {
+    const normalizedAssetId = normalizeAssetId(assetId);
+
+    log('Hiding asset', { assetId: normalizedAssetId });
+
+    this.update((state) => {
+      if (!state.assetPreferences[normalizedAssetId]) {
+        state.assetPreferences[normalizedAssetId] = {};
+      }
+      state.assetPreferences[normalizedAssetId].hidden = true;
+    });
+  }
+
+  /**
+   * Unhide an asset globally.
+   *
+   * @param assetId - The CAIP-19 asset ID to unhide.
+   */
+  unhideAsset(assetId: Caip19AssetId): void {
+    const normalizedAssetId = normalizeAssetId(assetId);
+
+    log('Unhiding asset', { assetId: normalizedAssetId });
+
+    this.update((state) => {
+      const prefs = state.assetPreferences[normalizedAssetId];
+      if (prefs) {
+        delete prefs.hidden;
+        if (Object.keys(prefs).length === 0) {
+          delete state.assetPreferences[normalizedAssetId];
+        }
+      }
+    });
   }
 
   // ============================================================================
@@ -1083,16 +1167,13 @@ export class AssetsController extends BaseController<
       const changedMetadata: string[] = [];
 
       this.update((state) => {
-        // Use type assertions to avoid deep type instantiation issues with Draft<Json>
-        const metadata = state.assetsMetadata as unknown as Record<
-          string,
-          unknown
-        >;
-        const balances = state.assetsBalance as unknown as Record<
+        // Use type assertions to avoid deep type instantiation issues with Immer Draft types
+        const metadata = state.assetsMetadata as Record<string, AssetMetadata>;
+        const balances = state.assetsBalance as Record<
           string,
-          Record<string, unknown>
+          Record<string, AssetBalance>
         >;
-        const prices = state.assetsPrice as unknown as Record<string, unknown>;
+        const prices = state.assetsPrice as Record<string, AssetPrice>;
 
         if (normalizedResponse.assetsMetadata) {
           for (const [key, value] of Object.entries(
@@ -1247,11 +1328,6 @@ export class AssetsController extends BaseController<
 
       for (const [assetId, balance] of Object.entries(accountBalances)) {
         const typedAssetId = assetId as Caip19AssetId;
-        const assetChainId = extractChainId(typedAssetId);
-
-        if (!chainIdSet.has(assetChainId)) {
-          continue;
-        }
 
         const metadataRaw = this.state.assetsMetadata[typedAssetId];
 
@@ -1260,16 +1336,28 @@ export class AssetsController extends BaseController<
           continue;
         }
 
-        const metadata = metadataRaw as AssetMetadata;
+        const metadata = metadataRaw;
+
+        // Skip hidden assets (assetPreferences)
+        const prefs = this.state.assetPreferences[typedAssetId];
+        if (prefs?.hidden) {
+          continue;
+        }
+
+        const assetChainId = extractChainId(typedAssetId);
+
+        if (!chainIdSet.has(assetChainId)) {
+          continue;
+        }
 
         // Filter by asset type
         const tokenAssetType = this.#tokenStandardToAssetType(metadata.type);
         if (!assetTypeSet.has(tokenAssetType)) {
           continue;
         }
 
-        const typedBalance = balance as AssetBalance;
-        const priceRaw = this.state.assetsPrice[typedAssetId] as AssetPrice;
+        const typedBalance = balance;
+        const priceRaw = this.state.assetsPrice[typedAssetId];
         const price: AssetPrice = priceRaw ?? {
           price: 0,
           lastUpdated: 0,
@@ -1783,5 +1871,7 @@ export class AssetsController extends BaseController<
       'AssetsController:removeCustomAsset',
     );
     this.messenger.unregisterActionHandler('AssetsController:getCustomAssets');
+    this.messenger.unregisterActionHandler('AssetsController:hideAsset');
+    this.messenger.unregisterActionHandler('AssetsController:unhideAsset');
   }
 }

packages/assets-controller/src/data-sources/RpcDataSource.test.ts

@@ -187,9 +187,6 @@ async function withController<ReturnValue>(
 
   // Mock AssetsController:getState
   messenger.registerActionHandler('AssetsController:getState', () => ({
-    allTokens: {},
-    allDetectedTokens: {},
-    allIgnoredTokens: {},
     assetsMetadata: {},
     assetsBalance: {},
   }));

packages/assets-controller/src/data-sources/RpcDataSource.ts

@@ -170,13 +170,10 @@ type TokenListControllerGetStateAction = {
   };
 };
 
-// AssetsController:getState action (for user tokens state and assets balance)
+// AssetsController:getState action (for assets balance and metadata)
 type AssetsControllerGetStateAction = {
   type: 'AssetsController:getState';
   handler: () => {
-    allTokens: Record<string, Record<string, { address: string }[]>>;
-    allDetectedTokens: Record<string, Record<string, { address: string }[]>>;
-    allIgnoredTokens: Record<string, Record<string, string[]>>;
     assetsMetadata: Record<Caip19AssetId, AssetMetadata>;
     assetsBalance: Record<string, Record<string, { amount: string }>>;
   };
@@ -1304,7 +1301,9 @@ export class RpcDataSource extends BaseController<
    */
   #getExistingAssetsMetadata(): Record<Caip19AssetId, AssetMetadata> {
     try {
-      const state = this.messenger.call('AssetsController:getState');
+      const state = this.messenger.call('AssetsController:getState') as {
+        assetsMetadata?: Record<Caip19AssetId, AssetMetadata>;
+      };
       return (state.assetsMetadata ?? {}) as unknown as Record<
         Caip19AssetId,
         AssetMetadata

packages/assets-controller/src/index.ts

@@ -19,6 +19,8 @@ export type {
   AssetsControllerAddCustomAssetAction,
   AssetsControllerRemoveCustomAssetAction,
   AssetsControllerGetCustomAssetsAction,
+  AssetsControllerHideAssetAction,
+  AssetsControllerUnhideAssetAction,
   AssetsControllerActions,
   AssetsControllerStateChangeEvent,
   AssetsControllerBalanceChangedEvent,