feat: add watchlist star in token details (#32962)

<!--
Please submit this PR as a draft initially.

Do not mark it as "Ready for review" until this PR meets the canonical
Definition of Ready For Review in `docs/readme/ready-for-review.md`.

In short: the template must be materially complete (not just section
titles
present), all status checks must be currently passing, and the only
expected
follow-up commits must be reviewer-driven.
-->
<!--
mms-check directive vocabulary — read by
.github/scripts/shared/pr-template-checks.ts
at module load to build the validation plan. Directives are invisible in
rendered
markdown and must NOT be removed or edited without updating the
validator registry.

  type=text           Section must contain non-placeholder prose.
  type=changelog      Section must have a valid CHANGELOG entry: line.
type=issue-link Section must have a Fixes:/Closes:/Refs: line with a
value.
type=manual-testing Section must have real testing steps or an explicit
N/A.
type=screenshot Section must have evidence (image/URL) or an explicit
N/A.
type=checklist Section must have all checkboxes consciously checked.
required=true|false Whether a missing/invalid section runs the validator
at all.
blocking=true|false Whether a failure of this check fails the CI
workflow.
Default: false — failures are shown as warnings in the sticky
                      comment but do not block the PR.

Sections without a directive are checked for structural presence only.
-->

## **Description**

<!-- mms-check: type=text required=true -->


Adds a feature-flag-gated star toggle to the Token Details page header,
allowing users to add/remove tokens from their watchlist with a single
tap. The star icon shows outlined when not watched and filled when
watched. Tapping triggers an optimistic UI update, persists to
Authenticated User Storage (AUS), shows a toast notification, and fires
analytics events.
Also fixes a latent query-key conflict between
`useTokenWatchlistMutations` and `useTokenWatchlistQuery` by giving the
hydrated query its own dedicated cache key (`['tokenWatchlist',
'hydrated']`), and consolidates the duplicate query-key files into one.
Additionally corrects a case-sensitivity issue in git where the
`watchlist/` directory was tracked under lowercase `assets/` instead of
capital `Assets/`.


## **Changelog**
<!-- mms-check: type=changelog required=true blocking=true -->
CHANGELOG entry: Added a star icon on the Token Details page to add or
remove tokens from the watchlist


## **Related issues**
<!-- mms-check: type=issue-link required=true -->
Fixes: https://consensyssoftware.atlassian.net/browse/ASSETS-3118


## **Manual testing steps**

<!-- mms-check: type=manual-testing required=true -->

```gherkin
Feature: Watchlist star toggle on Token Details
  Scenario: user adds a token to watchlist
    Given the token watchlist feature flag is enabled
    And the user is on a Token Details page for a token not in their watchlist
    When user taps the star icon in the header
    Then the star icon becomes filled
    And a toast "Added to Watchlist" is shown
    And the token is persisted to watchlist storage
  Scenario: user removes a token from watchlist
    Given the token watchlist feature flag is enabled
    And the user is on a Token Details page for a token already in their watchlist
    When user taps the filled star icon in the header
    Then the star icon becomes outlined
    And a toast "Removed from Watchlist" is shown
    And the token is removed from watchlist storage
  Scenario: star is hidden when feature flag is off
    Given the token watchlist feature flag is disabled
    When user navigates to any Token Details page
    Then no star icon is visible in the header
```

## **Screenshots/Recordings**

<!-- mms-check: type=screenshot required=true -->

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

### **After**

<!-- [screenshots/recordings] -->


https://github.com/user-attachments/assets/62e460ff-6511-459f-90c2-951e237b4d6c



## **Pre-merge author checklist**

<!-- mms-check: type=checklist required=true -->

<!--
Every checklist item must be consciously assessed before marking this PR
as
"Ready for review". A checked box means you deliberately considered that
responsibility, not that you literally performed every action listed.

Unchecked boxes are ambiguous: they are not an implicit "N/A" and they
are not
a silent "skip". See `docs/readme/ready-for-review.md` for the full
checklist
semantics.
-->

- [ ] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [ ] I've completed the PR template to the best of my ability
- [ ] I've included tests if applicable
- [ ] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [ ] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

#### Performance checks (if applicable)

- [ ] I've tested on Android
  - Ideally on a mid-range device; emulator is acceptable
- [ ] I've tested with a power user scenario
- Use these [power-user
SRPs](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/edit-v2/401401446401?draftShareId=9d77e1e1-4bdc-4be1-9ebb-ccd916988d93)
to import wallets with many accounts and tokens
- [ ] I've instrumented key operations with Sentry traces for production
performance metrics
- See [`trace()`](/app/util/trace.ts) for usage and
[`addToken`](/app/components/Views/AddAsset/components/AddCustomToken/AddCustomToken.tsx#L274)
for an example

For performance guidelines and tooling, see the [Performance
Guide](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/400085549067/Performance+Guide+for+Engineers).

## **Pre-merge reviewer checklist**

<!--
Reviewer checklist items follow the same semantics as the author
checklist: an
unchecked box is ambiguous, a checked box means the reviewer consciously
assessed that responsibility. See `docs/readme/ready-for-review.md`.
-->

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches persisted user watchlist state, feature-flag gating, and React
Query cache keys; misalignment on the renamed flag key could hide the UI
in production.
> 
> **Overview**
> Adds a **feature-flag-gated star** on Token Details so users can add
or remove the current token from the global watchlist. The header shows
outline vs filled star, calls a new **`useTokenWatchlist`** hook (blob
cache + add/remove mutations), shows add/remove toasts, and emits
**`WATCHLIST_TOKEN_ADDED` / `WATCHLIST_TOKEN_REMOVED`** analytics with
`source: token_details`.
> 
> Watchlist React Query keys are cleaned up: hydrated list metadata uses
**`tokenWatchlistQueryKeys.hydrated`** instead of sharing the raw blob
key, mutation **`onSettled`** also invalidates hydrated, and query keys
live in **`watchlist-query-keys.ts`** (replacing the old
`useTokenWatchlist.keys` file). The remote flag constant is renamed to
**`assetsGlobalWatchlistV1`** for LaunchDarkly alignment.
> 
> Test API defaults mock **GET/PUT** for `preferences/assets-watchlist`.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
0adf40d. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: sahar-fehri

app/components/UI/Assets/selectors/featureFlags.test.ts

@@ -34,7 +34,7 @@ describe('selectTokenWatchlistEnabled', () => {
   });
 
   it('exposes the LaunchDarkly flag key for registry alignment', () => {
-    expect(ASSET_GLOBAL_WATCHLIST_FLAG_KEY).toBe('assets-global-watchlist-v1');
+    expect(ASSET_GLOBAL_WATCHLIST_FLAG_KEY).toBe('assetsGlobalWatchlistV1');
   });
 
   const testCases: {

app/components/UI/Assets/selectors/featureFlags.ts

@@ -5,7 +5,7 @@ import {
   VersionGatedFeatureFlag,
 } from '../../../../util/remoteFeatureFlag';
 
-export const ASSET_GLOBAL_WATCHLIST_FLAG_KEY = 'assets-global-watchlist-v1';
+export const ASSET_GLOBAL_WATCHLIST_FLAG_KEY = 'assetsGlobalWatchlistV1';
 
 /**
  * Whether the global token watchlist feature is enabled for the current

…nents/UI/assets/watchlist/hooks/index.ts …nents/UI/Assets/watchlist/hooks/index.tsapp/components/UI/assets/watchlist/hooks/index.ts renamed to app/components/UI/Assets/watchlist/hooks/index.ts app/components/UI/assets/watchlist/hooks/index.ts renamed to app/components/UI/Assets/watchlist/hooks/index.ts

@@ -1,4 +1,8 @@
-export { tokenWatchlistQueryKeys } from './useTokenWatchlist.keys';
+export { tokenWatchlistQueryKeys } from './watchlist-query-keys';
+export {
+  useTokenWatchlist,
+  type UseTokenWatchlistResult,
+} from './useTokenWatchlist';
 export {
   tokenWatchlistBatcher,
   useTokenWatchlistAddItemMutation,

…/useSuggestedWatchlistItemsQuery.test.ts …/useSuggestedWatchlistItemsQuery.test.tsapp/components/UI/assets/watchlist/hooks/useSuggestedWatchlistItemsQuery.test.ts renamed to app/components/UI/Assets/watchlist/hooks/useSuggestedWatchlistItemsQuery.test.ts app/components/UI/assets/watchlist/hooks/useSuggestedWatchlistItemsQuery.test.ts renamed to app/components/UI/Assets/watchlist/hooks/useSuggestedWatchlistItemsQuery.test.ts

@@ -0,0 +1,139 @@
+import { renderHook, act } from '@testing-library/react-hooks';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import type { CaipAssetType } from '@metamask/utils';
+
+import { useTokenWatchlist } from './useTokenWatchlist';
+import {
+  useTokenWatchlistAddItemMutation,
+  useTokenWatchlistRemoveItemMutation,
+} from './useTokenWatchlistMutations';
+import { tokenWatchlistQueryKeys } from './watchlist-query-keys';
+
+jest.mock('@tanstack/react-query', () => ({
+  ...jest.requireActual('@tanstack/react-query'),
+  useQueryClient: jest.fn(),
+  useQuery: jest.fn(),
+}));
+
+jest.mock('./useTokenWatchlistMutations', () => ({
+  useTokenWatchlistAddItemMutation: jest.fn(),
+  useTokenWatchlistRemoveItemMutation: jest.fn(),
+}));
+
+const mockGetQueryData = jest.fn();
+const mockMutateAdd = jest.fn();
+const mockMutateRemove = jest.fn();
+
+const ASSET_ID =
+  'eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' as CaipAssetType;
+
+describe('useTokenWatchlist', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (useQueryClient as jest.Mock).mockReturnValue({
+      getQueryData: mockGetQueryData,
+    });
+    (useTokenWatchlistAddItemMutation as jest.Mock).mockReturnValue({
+      mutate: mockMutateAdd,
+      isPending: false,
+    });
+    (useTokenWatchlistRemoveItemMutation as jest.Mock).mockReturnValue({
+      mutate: mockMutateRemove,
+      isPending: false,
+    });
+  });
+
+  const mockBlobQuery = (assets: string[]) => {
+    (useQuery as jest.Mock).mockReturnValue({
+      data: { assets, version: 1 },
+    });
+  };
+
+  it('returns noop result when assetId is null', () => {
+    (useQuery as jest.Mock).mockReturnValue({ data: undefined });
+
+    const { result } = renderHook(() => useTokenWatchlist(null));
+
+    expect(result.current.isWatched).toBe(false);
+    expect(result.current.isLoading).toBe(false);
+
+    act(() => result.current.toggle());
+    expect(mockMutateAdd).not.toHaveBeenCalled();
+    expect(mockMutateRemove).not.toHaveBeenCalled();
+  });
+
+  it('returns isWatched=false when blob is empty', () => {
+    mockBlobQuery([]);
+
+    const { result } = renderHook(() => useTokenWatchlist(ASSET_ID));
+
+    expect(result.current.isWatched).toBe(false);
+    expect(useQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        queryKey: tokenWatchlistQueryKeys.blob,
+      }),
+    );
+  });
+
+  it('returns isWatched=true when asset is in blob', () => {
+    mockBlobQuery([String(ASSET_ID)]);
+
+    const { result } = renderHook(() => useTokenWatchlist(ASSET_ID));
+
+    expect(result.current.isWatched).toBe(true);
+  });
+
+  it('returns isWatched=false when blob has no data (undefined)', () => {
+    (useQuery as jest.Mock).mockReturnValue({ data: undefined });
+
+    const { result } = renderHook(() => useTokenWatchlist(ASSET_ID));
+
+    expect(result.current.isWatched).toBe(false);
+  });
+
+  it('calls addMutation when toggling an unwatched asset', () => {
+    mockBlobQuery([]);
+
+    const { result } = renderHook(() => useTokenWatchlist(ASSET_ID));
+
+    act(() => result.current.toggle());
+
+    expect(mockMutateAdd).toHaveBeenCalledWith(ASSET_ID);
+    expect(mockMutateRemove).not.toHaveBeenCalled();
+  });
+
+  it('calls removeMutation when toggling a watched asset', () => {
+    mockBlobQuery([String(ASSET_ID)]);
+
+    const { result } = renderHook(() => useTokenWatchlist(ASSET_ID));
+
+    act(() => result.current.toggle());
+
+    expect(mockMutateRemove).toHaveBeenCalledWith(ASSET_ID);
+    expect(mockMutateAdd).not.toHaveBeenCalled();
+  });
+
+  it('returns isLoading=true when add mutation is pending', () => {
+    (useTokenWatchlistAddItemMutation as jest.Mock).mockReturnValue({
+      mutate: mockMutateAdd,
+      isPending: true,
+    });
+    mockBlobQuery([]);
+
+    const { result } = renderHook(() => useTokenWatchlist(ASSET_ID));
+
+    expect(result.current.isLoading).toBe(true);
+  });
+
+  it('returns isLoading=true when remove mutation is pending', () => {
+    (useTokenWatchlistRemoveItemMutation as jest.Mock).mockReturnValue({
+      mutate: mockMutateRemove,
+      isPending: true,
+    });
+    mockBlobQuery([String(ASSET_ID)]);
+
+    const { result } = renderHook(() => useTokenWatchlist(ASSET_ID));
+
+    expect(result.current.isLoading).toBe(true);
+  });
+});

…hooks/useSuggestedWatchlistItemsQuery.ts …hooks/useSuggestedWatchlistItemsQuery.tsapp/components/UI/assets/watchlist/hooks/useSuggestedWatchlistItemsQuery.ts renamed to app/components/UI/Assets/watchlist/hooks/useSuggestedWatchlistItemsQuery.ts app/components/UI/assets/watchlist/hooks/useSuggestedWatchlistItemsQuery.ts renamed to app/components/UI/Assets/watchlist/hooks/useSuggestedWatchlistItemsQuery.ts

@@ -0,0 +1,63 @@
+import { useCallback } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import type { CaipAssetType } from '@metamask/utils';
+
+import { readFromTokenWatchList, type WatchlistBlob } from '../storage';
+import {
+  useTokenWatchlistAddItemMutation,
+  useTokenWatchlistRemoveItemMutation,
+} from './useTokenWatchlistMutations';
+import { tokenWatchlistQueryKeys } from './watchlist-query-keys';
+
+export interface UseTokenWatchlistResult {
+  isWatched: boolean;
+  isLoading: boolean;
+  toggle: () => void;
+}
+
+const NOOP_RESULT: UseTokenWatchlistResult = {
+  isWatched: false,
+  isLoading: false,
+  toggle: () => undefined,
+};
+
+/**
+ * Convenience hook that exposes `isWatched` and a `toggle` function for a
+ * single asset. Combines the add/remove mutation hooks with a reactive
+ * cache subscription via useQuery so optimistic updates are reflected
+ * immediately.
+ */
+export function useTokenWatchlist(
+  assetId: CaipAssetType | null,
+): UseTokenWatchlistResult {
+  const addMutation = useTokenWatchlistAddItemMutation();
+  const removeMutation = useTokenWatchlistRemoveItemMutation();
+
+  const { data: blob } = useQuery<WatchlistBlob>({
+    queryKey: tokenWatchlistQueryKeys.blob,
+    queryFn: readFromTokenWatchList,
+    staleTime: Infinity,
+  });
+
+  const assetIdStr = assetId ? String(assetId) : null;
+  const isWatched = assetIdStr
+    ? (blob?.assets.includes(assetIdStr) ?? false)
+    : false;
+
+  const isLoading = addMutation.isPending || removeMutation.isPending;
+
+  const toggle = useCallback(() => {
+    if (!assetId) return;
+    if (isWatched) {
+      removeMutation.mutate(assetId);
+    } else {
+      addMutation.mutate(assetId);
+    }
+  }, [assetId, isWatched, addMutation, removeMutation]);
+
+  if (!assetId) {
+    return NOOP_RESULT;
+  }
+
+  return { isWatched, isLoading, toggle };
+}

app/components/UI/Assets/watchlist/hooks/useTokenWatchlist.test.ts

@@ -14,7 +14,7 @@ import {
   type WatchlistBlob,
   writeToTokenWatchList,
 } from '../storage';
-import { tokenWatchlistQueryKeys } from './useTokenWatchlist.keys';
+import { tokenWatchlistQueryKeys } from './watchlist-query-keys';
 import {
   tokenWatchlistBatcher,
   useTokenWatchlistAddItemMutation,

app/components/UI/Assets/watchlist/hooks/useTokenWatchlist.ts

@@ -8,7 +8,7 @@ import {
   writeToTokenWatchList,
 } from '../storage';
 import { createAsyncBatcher } from '../utils/createAsyncBatcher';
-import { tokenWatchlistQueryKeys } from './useTokenWatchlist.keys';
+import { tokenWatchlistQueryKeys } from './watchlist-query-keys';
 
 export type WatchlistAddInput = CaipAssetType | CaipAssetType[];
 export type WatchlistRemoveInput = CaipAssetType | CaipAssetType[];
@@ -111,6 +111,9 @@ const useWatchlistMutation = <TInput>({
       queryClient.invalidateQueries({
         queryKey: tokenWatchlistQueryKeys.blob,
       });
+      queryClient.invalidateQueries({
+        queryKey: tokenWatchlistQueryKeys.hydrated,
+      });
     },
   });
 };

…ooks/useTokenWatchlistMutations.test.tsx …ooks/useTokenWatchlistMutations.test.tsxapp/components/UI/assets/watchlist/hooks/useTokenWatchlistMutations.test.tsx renamed to app/components/UI/Assets/watchlist/hooks/useTokenWatchlistMutations.test.tsx app/components/UI/assets/watchlist/hooks/useTokenWatchlistMutations.test.tsx renamed to app/components/UI/Assets/watchlist/hooks/useTokenWatchlistMutations.test.tsx

@@ -89,7 +89,7 @@ describe('useTokenWatchlistQuery', () => {
     });
 
     expect(
-      queryClient.getQueryData(tokenWatchlistQueryKeys.blob),
+      queryClient.getQueryData(tokenWatchlistQueryKeys.hydrated),
     ).toStrictEqual([]);
   });
 
@@ -308,7 +308,7 @@ describe('useTokenWatchlistQuery', () => {
         queryClient.getQueryData(tokenWatchlistQueryKeys.suggested),
       ).toStrictEqual([]);
       expect(
-        queryClient.getQueryData(tokenWatchlistQueryKeys.blob),
+        queryClient.getQueryData(tokenWatchlistQueryKeys.hydrated),
       ).toBeUndefined();
     });