feat: init AUS watchlist integration (#31734)

gambinish · web-flow · commit 5216c013a787 · 2026-06-29T15:16:59.000Z
## **Description**   Integrates the Perps watchlist with the **Authenticated User Storage (AUS) service**, so a user's watched markets are persisted to remote storage and synced across devices when they are authenticated. ### Changes **`@metamask/perps-controller` bump to `^9.0.0`** (`package.json`, `yarn.lock`) - The new controller version implements optimistic local updates and AUS sync inside `toggleWatchlistMarket`. On add/remove, it writes the updated watchlist into the `perps.watchlistMarkets` field of `NotificationPreferences` via `AuthenticatedUserStorageService:putNotificationPreferences`. It gracefully degrades to local-only when the user is unauthenticated or the preferences blob has not yet been initialised. **Messenger wiring** (`perps-controller-messenger/index.ts`) - Delegates `AuthenticatedUserStorageService:getNotificationPreferences` and `AuthenticatedUserStorageService:putNotificationPreferences` actions to the `PerpsControllerMessenger` so the controller can call them through the root messenger. **`usePerpsWatchlistActions` hook cleanup** (`usePerpsWatchlistActions.ts`) - Removed the `TODO` scaffolding comments for optimistic UI and User Storage API seams — those are now handled inside the controller. - `toggleWatchlistMarket` calls are now properly `await`-ed so errors surface and the error toast works correctly. **Integration tests** (`perps-controller/index.test.ts`, `perps-controller-messenger/index.test.ts`) - New integration test suite (`PerpsController watchlist ↔ AuthenticatedUserStorageService`) covering: add writes the symbol to AUS, remove deletes it, list merges correctly with existing remote symbols, rollback on failed write, and graceful no-op when the preferences blob is `null`. - Messenger test confirms the two new AUS actions are delegated. ## **Changelog**   CHANGELOG entry: Integrate AUS Perps Watchlist ## **Related issues**  Fixes: [TAT-2663](https://consensyssoftware.atlassian.net/browse/TAT-2663) ## **Manual testing steps**  ```gherkin Feature: my feature name Scenario: user [verb for user action] Given [describe expected initial app state] When user [verb for user action] Then [describe expected outcome] ``` ## **Screenshots/Recordings**   ### **Before**  ### **After**  https://github.com/user-attachments/assets/f89061e1-4ce5-41d4-8f77-c9ba5ee4e722 ## **Pre-merge author checklist**   - [x] 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). - [x] I've completed the PR template to the best of my ability - [x] I've included tests if applicable - [x] I've documented my code using [JSDoc](https://jsdoc.app/) format if applicable - [x] 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) - [x] I've tested on Android - Ideally on a mid-range device; emulator is acceptable - [x] 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 - [x] 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**  - [ ] 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.  --- > [!NOTE] > **Medium Risk** > Touches cross-device user preference persistence via Authenticated User Storage; risk is mitigated by controller-owned rollback, skipped writes when prefs are uninitialized, and new integration coverage. > > **Overview** > Wires Perps watchlist persistence to **Authenticated User Storage (AUS)** by adopting **`@metamask/perps-controller` ^9.0.0** (via `package.json` resolution). Watchlist add/remove now runs optimistic local updates and syncs `perps.watchlistMarkets` through `NotificationPreferences`, with local-only behavior when prefs are missing or the user is unauthenticated. > > **`usePerpsWatchlistActions`** drops the old optimistic/AUS TODO scaffolding and documents that **`PerpsController.toggleWatchlistMarket`** owns that behavior. Analytics for favorite/unfavorite only fire after confirming the symbol is actually on or off the list post-toggle (so failed adds or rollbacks do not emit misleading events). > > Adds **integration tests** on the real controller: AUS read/write on toggle, merge with remote symbols, rollback when `putNotificationPreferences` fails, and skipping remote writes when `getNotificationPreferences` is `null`. Messenger test copy is updated to describe AUS notification-preference delegation. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 0bcf1df. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  [TAT-2663]: https://consensyssoftware.atlassian.net/browse/TAT-2663?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
diff --git a/app/components/UI/Perps/hooks/usePerpsWatchlistActions.ts b/app/components/UI/Perps/hooks/usePerpsWatchlistActions.ts
@@ -16,27 +16,22 @@ interface UsePerpsWatchlistActionsResult {
   /**
    * Adds a market to the watchlist.
    *
-   * Currently wraps the asynchronous PerpsController.toggleWatchlistMarket call.
-   *
-   * TODO(TAT-2663 — optimistic UI): Before the await, apply an optimistic local
-   * state update (e.g. pass an onOptimisticUpdate callback from the caller).
-   * On failure, roll back that state and show the addError toast below.
-   *
-   * TODO(TAT-2663 — User Storage API): Replace / augment the controller call
-   * with a POST to the User Storage API once it is available.
+   * Delegates to PerpsController.toggleWatchlistMarket, which performs an
+   * optimistic local update and syncs to AuthenticatedUserStorageService.
+   * Falls back to local-only when unauthenticated.
    */
   addToWatchlist: (symbol: string) => Promise<void>;
   /**
    * Removes a market from the watchlist.
    *
-   * Same optimistic UI and User Storage seams as addToWatchlist above.
+   * Same optimistic-update and AUS sync behaviour as addToWatchlist.
    */
   removeFromWatchlist: (symbol: string) => Promise<void>;
 }
 
 /**
- * Provides add/remove watchlist actions with analytics, error reporting,
- * and structural seams for optimistic UI and the future User Storage API.
+ * Provides add/remove watchlist actions with analytics and error reporting.
+ * The controller handles optimistic UI, AUS sync, and graceful degradation.
  *
  * @param source - Analytics source identifying where the action was triggered
  * (e.g. PERPS_EVENT_VALUE.SOURCE.PERPS_HOME_WATCHLIST).
@@ -57,27 +52,21 @@ export const usePerpsWatchlistActions = (
           return;
         }
 
-        // TODO(TAT-2663 — optimistic UI): Call onOptimisticUpdate?.() here
-        // to instantly reflect the add in the UI before the async call resolves.
-
         await controller.toggleWatchlistMarket(symbol);
 
-        // TODO(TAT-2663 — User Storage API): await userStorageApi.addWatchlistMarket(symbol)
-
-        const watchlistCount = controller.getWatchlistMarkets().length;
-        track(MetaMetricsEvents.PERPS_UI_INTERACTION, {
-          [PERPS_EVENT_PROPERTY.INTERACTION_TYPE]:
-            PERPS_EVENT_VALUE.INTERACTION_TYPE.FAVORITE_TOGGLED,
-          [PERPS_EVENT_PROPERTY.ACTION_TYPE]:
-            PERPS_EVENT_VALUE.ACTION_TYPE.FAVORITE_MARKET,
-          [PERPS_EVENT_PROPERTY.ASSET]: symbol,
-          [PERPS_EVENT_PROPERTY.SOURCE]: source,
-          [PERPS_EVENT_PROPERTY.FAVORITES_COUNT]: watchlistCount,
-        });
+        const watchlistAfter = controller.getWatchlistMarkets();
+        if (watchlistAfter.includes(symbol)) {
+          track(MetaMetricsEvents.PERPS_UI_INTERACTION, {
+            [PERPS_EVENT_PROPERTY.INTERACTION_TYPE]:
+              PERPS_EVENT_VALUE.INTERACTION_TYPE.FAVORITE_TOGGLED,
+            [PERPS_EVENT_PROPERTY.ACTION_TYPE]:
+              PERPS_EVENT_VALUE.ACTION_TYPE.FAVORITE_MARKET,
+            [PERPS_EVENT_PROPERTY.ASSET]: symbol,
+            [PERPS_EVENT_PROPERTY.SOURCE]: source,
+            [PERPS_EVENT_PROPERTY.FAVORITES_COUNT]: watchlistAfter.length,
+          });
+        }
       } catch (error) {
-        // TODO(TAT-2663 — optimistic UI): Roll back the optimistic state
-        // update here (e.g. call onRollback?.()) before showing the error toast.
-
         Logger.error(ensureError(error, 'usePerpsWatchlistActions.add'), {
           tags: {
             feature: PERPS_CONSTANTS.FeatureName,
@@ -99,26 +88,22 @@ export const usePerpsWatchlistActions = (
   const removeFromWatchlist = useCallback(
     async (symbol: string): Promise<void> => {
       try {
-        // TODO(TAT-2663 — optimistic UI): Apply optimistic remove here.
-
         const controller = Engine.context.PerpsController;
         await controller.toggleWatchlistMarket(symbol);
 
-        // TODO(TAT-2663 — User Storage API): await userStorageApi.removeWatchlistMarket(symbol)
-
-        const watchlistCount = controller.getWatchlistMarkets().length;
-        track(MetaMetricsEvents.PERPS_UI_INTERACTION, {
-          [PERPS_EVENT_PROPERTY.INTERACTION_TYPE]:
-            PERPS_EVENT_VALUE.INTERACTION_TYPE.FAVORITE_TOGGLED,
-          [PERPS_EVENT_PROPERTY.ACTION_TYPE]:
-            PERPS_EVENT_VALUE.ACTION_TYPE.UNFAVORITE_MARKET,
-          [PERPS_EVENT_PROPERTY.ASSET]: symbol,
-          [PERPS_EVENT_PROPERTY.SOURCE]: source,
-          [PERPS_EVENT_PROPERTY.FAVORITES_COUNT]: watchlistCount,
-        });
+        const watchlistAfter = controller.getWatchlistMarkets();
+        if (!watchlistAfter.includes(symbol)) {
+          track(MetaMetricsEvents.PERPS_UI_INTERACTION, {
+            [PERPS_EVENT_PROPERTY.INTERACTION_TYPE]:
+              PERPS_EVENT_VALUE.INTERACTION_TYPE.FAVORITE_TOGGLED,
+            [PERPS_EVENT_PROPERTY.ACTION_TYPE]:
+              PERPS_EVENT_VALUE.ACTION_TYPE.UNFAVORITE_MARKET,
+            [PERPS_EVENT_PROPERTY.ASSET]: symbol,
+            [PERPS_EVENT_PROPERTY.SOURCE]: source,
+            [PERPS_EVENT_PROPERTY.FAVORITES_COUNT]: watchlistAfter.length,
+          });
+        }
       } catch (error) {
-        // TODO(TAT-2663 — optimistic UI): Roll back the optimistic remove here.
-
         Logger.error(ensureError(error, 'usePerpsWatchlistActions.remove'), {
           tags: {
             feature: PERPS_CONSTANTS.FeatureName,
diff --git a/app/core/Engine/controllers/perps-controller/index.test.ts b/app/core/Engine/controllers/perps-controller/index.test.ts
@@ -7,9 +7,12 @@ import {
   PerpsControllerState,
   InitializationState,
   MARKET_SORTING_CONFIG,
+  PerpsPlatformDependencies,
 } from '@metamask/perps-controller';
 import { perpsControllerInit } from '.';
 import { MOCK_ANY_NAMESPACE, MockAnyNamespace } from '@metamask/messenger';
+import { getPerpsControllerMessenger } from '../../messengers/perps-controller-messenger';
+import type { NotificationPreferences } from '@metamask/authenticated-user-storage';
 
 // Mock mobile-specific modules that ./index.ts imports to avoid pulling in
 // Engine and React Native dependencies in the test environment
@@ -162,3 +165,256 @@ describe('perps controller init', () => {
     expect(perpsControllerState).toStrictEqual(initialPerpsControllerState);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Integration: watchlist ↔ AuthenticatedUserStorageService
+//
+// The describe block above mocks PerpsController as jest.fn() (needed to test
+// the init wiring).  These tests need the real controller, so they use
+// jest.requireActual to reach the preview build directly.
+// ---------------------------------------------------------------------------
+
+function buildSeedPrefs(
+  overrides: Partial<NotificationPreferences> = {},
+): NotificationPreferences {
+  return {
+    walletActivity: {
+      inAppNotificationsEnabled: false,
+      pushNotificationsEnabled: false,
+      accounts: [],
+    },
+    marketing: {
+      inAppNotificationsEnabled: false,
+      pushNotificationsEnabled: false,
+    },
+    perps: {
+      inAppNotificationsEnabled: false,
+      pushNotificationsEnabled: false,
+      watchlistMarkets: {
+        hyperliquid: { testnet: [], mainnet: [] },
+        myx: { testnet: [], mainnet: [] },
+      },
+    },
+    socialAI: {
+      inAppNotificationsEnabled: false,
+      pushNotificationsEnabled: false,
+      mutedTraderProfileIds: [],
+    },
+    ...overrides,
+  };
+}
+
+function buildTestInfrastructure(): PerpsPlatformDependencies {
+  return {
+    logger: { error: jest.fn() },
+    debugLogger: { log: jest.fn() },
+    metrics: { isEnabled: jest.fn(() => false), trackPerpsEvent: jest.fn() },
+    performance: { now: jest.fn(() => 0) },
+    streamManager: {
+      pauseChannel: jest.fn(),
+      resumeChannel: jest.fn(),
+      clearAllChannels: jest.fn(),
+    },
+    featureFlags: { validateVersionGated: jest.fn(() => false) },
+    marketDataFormatters: {
+      formatVolume: jest.fn(() => ''),
+      formatPerpsFiat: jest.fn(() => ''),
+      formatPercentage: jest.fn(() => ''),
+      priceRangesUniversal: [],
+    },
+    cacheInvalidator: { invalidate: jest.fn(), invalidateAll: jest.fn() },
+    diskCache: {
+      // Called synchronously in the constructor (#hydrateCacheFromDiskSync).
+      getItemSync: jest.fn(() => null),
+      getItem: jest.fn(() => Promise.resolve(null)),
+      setItem: jest.fn(() => Promise.resolve()),
+      removeItem: jest.fn(() => Promise.resolve()),
+    },
+    tracer: {
+      trace: jest.fn(),
+      endTrace: jest.fn(),
+      setMeasurement: jest.fn(),
+      addBreadcrumb: jest.fn(),
+    },
+    rewards: { getPerpsDiscountForAccount: jest.fn(() => Promise.resolve(0)) },
+  };
+}
+
+interface GetNotificationPreferencesAction {
+  type: 'AuthenticatedUserStorageService:getNotificationPreferences';
+  handler: () => Promise<NotificationPreferences | null>;
+}
+
+interface PutNotificationPreferencesAction {
+  type: 'AuthenticatedUserStorageService:putNotificationPreferences';
+  handler: (prefs: NotificationPreferences) => Promise<void>;
+}
+
+function buildRealController(
+  getNotificationPreferencesImpl: () => Promise<NotificationPreferences | null>,
+) {
+  // Use the real PerpsController from the preview build — the top-level
+  // jest.mock replaces it with jest.fn() for the init tests above, so we
+  // reach through with requireActual here.
+  const {
+    PerpsController: RealPerpsController,
+    getDefaultPerpsControllerState,
+  } = jest.requireActual('@metamask/perps-controller/PerpsController') as {
+    PerpsController: typeof PerpsController;
+    getDefaultPerpsControllerState: () => PerpsControllerState;
+  };
+
+  const baseMessenger = new ExtendedMessenger<
+    MockAnyNamespace,
+    GetNotificationPreferencesAction | PutNotificationPreferencesAction
+  >({
+    namespace: MOCK_ANY_NAMESPACE,
+  });
+
+  const getSpy = jest.fn().mockImplementation(getNotificationPreferencesImpl);
+  const putSpy = jest.fn().mockResolvedValue(undefined);
+
+  baseMessenger.registerActionHandler(
+    'AuthenticatedUserStorageService:getNotificationPreferences',
+    getSpy,
+  );
+  baseMessenger.registerActionHandler(
+    'AuthenticatedUserStorageService:putNotificationPreferences',
+    putSpy,
+  );
+
+  const controllerMessenger = getPerpsControllerMessenger(baseMessenger);
+
+  const controller = new RealPerpsController({
+    messenger: controllerMessenger,
+    state: getDefaultPerpsControllerState(),
+    infrastructure: buildTestInfrastructure(),
+    clientConfig: {},
+  });
+
+  return { controller, getSpy, putSpy };
+}
+
+describe('PerpsController watchlist ↔ AuthenticatedUserStorageService', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('toggleWatchlistMarket — add', () => {
+    it('calls putNotificationPreferences with the new symbol in hyperliquid.mainnet', async () => {
+      const { controller, putSpy } = buildRealController(() =>
+        Promise.resolve(buildSeedPrefs()),
+      );
+
+      await controller.toggleWatchlistMarket('BTC');
+
+      expect(putSpy).toHaveBeenCalledTimes(1);
+      expect(putSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          perps: expect.objectContaining({
+            watchlistMarkets: expect.objectContaining({
+              hyperliquid: expect.objectContaining({
+                mainnet: expect.arrayContaining(['BTC']),
+              }),
+            }),
+          }),
+        }),
+      );
+    });
+
+    it('keeps the local watchlist state after a successful AUS write', async () => {
+      const { controller } = buildRealController(() =>
+        Promise.resolve(buildSeedPrefs()),
+      );
+
+      await controller.toggleWatchlistMarket('ETH');
+
+      expect(controller.getWatchlistMarkets()).toContain('ETH');
+    });
+
+    it('merges with existing remote symbols — does not overwrite the whole list', async () => {
+      const seedWithSol = buildSeedPrefs({
+        perps: {
+          inAppNotificationsEnabled: false,
+          pushNotificationsEnabled: false,
+          watchlistMarkets: {
+            hyperliquid: { testnet: [], mainnet: ['SOL'] },
+            myx: { testnet: [], mainnet: [] },
+          },
+        },
+      });
+
+      const { controller, putSpy } = buildRealController(() =>
+        Promise.resolve(seedWithSol),
+      );
+      // Seed local state with SOL first
+      await controller.toggleWatchlistMarket('SOL');
+      putSpy.mockClear();
+
+      await controller.toggleWatchlistMarket('BTC');
+
+      expect(putSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          perps: expect.objectContaining({
+            watchlistMarkets: expect.objectContaining({
+              hyperliquid: expect.objectContaining({
+                mainnet: expect.arrayContaining(['SOL', 'BTC']),
+              }),
+            }),
+          }),
+        }),
+      );
+    });
+  });
+
+  describe('toggleWatchlistMarket — remove', () => {
+    it('calls putNotificationPreferences without the removed symbol', async () => {
+      const { controller, putSpy } = buildRealController(() =>
+        Promise.resolve(buildSeedPrefs()),
+      );
+      await controller.toggleWatchlistMarket('BTC'); // add
+      putSpy.mockClear();
+
+      await controller.toggleWatchlistMarket('BTC'); // remove
+
+      expect(putSpy).toHaveBeenCalledTimes(1);
+      const [calledPrefs] = putSpy.mock.calls[0] as [NotificationPreferences];
+      expect(
+        calledPrefs.perps.watchlistMarkets?.hyperliquid.mainnet,
+      ).not.toContain('BTC');
+    });
+
+    it('reverts local state when the AUS write fails', async () => {
+      const { controller, putSpy } = buildRealController(() =>
+        Promise.resolve(buildSeedPrefs()),
+      );
+      await controller.toggleWatchlistMarket('BTC');
+      expect(controller.getWatchlistMarkets()).toContain('BTC');
+
+      putSpy.mockRejectedValueOnce(new Error('network error'));
+      await controller.toggleWatchlistMarket('BTC'); // remove attempt fails
+
+      expect(controller.getWatchlistMarkets()).toContain('BTC');
+    });
+  });
+
+  describe('AUS write is skipped when preferences blob is not yet initialised', () => {
+    it('does not call putNotificationPreferences when getNotificationPreferences returns null', async () => {
+      const { controller, putSpy } = buildRealController(() =>
+        Promise.resolve(null),
+      );
+
+      await controller.toggleWatchlistMarket('BTC');
+
+      expect(putSpy).not.toHaveBeenCalled();
+    });
+
+    it('keeps the optimistic local update even when the remote write is skipped', async () => {
+      const { controller } = buildRealController(() => Promise.resolve(null));
+
+      await controller.toggleWatchlistMarket('BTC');
+
+      expect(controller.getWatchlistMarkets()).toContain('BTC');
+    });
+  });
+});
diff --git a/app/core/Engine/messengers/perps-controller-messenger/index.test.ts b/app/core/Engine/messengers/perps-controller-messenger/index.test.ts
@@ -86,7 +86,7 @@ describe('PerpsController Messenger', () => {
     );
   });
 
-  it('delegates the AuthenticatedUserStorageService watchlist actions', () => {
+  it('delegates AUS notification-preference actions to the perps controller messenger', () => {
     const baseControllerMessenger = new ExtendedMessenger<MockAnyNamespace>({
       namespace: MOCK_ANY_NAMESPACE,
     });
diff --git a/package.json b/package.json
@@ -168,6 +168,7 @@
     ]
   },
   "resolutions": {
+    "@metamask/perps-controller": "^9.0.0",
     "@metamask/network-controller": "33.0.0",
     "@react-native-community/viewpager": "patch:@react-native-community/viewpager@npm%3A3.3.0#~/.yarn/patches/@react-native-community-viewpager-npm-3.3.0.patch",
     "@solana-mobile/mobile-wallet-adapter-protocol": "^2.2.5",

Original file line number	Diff line number	Diff line change
`@@ -168,6 +168,7 @@`
`168`	`168`	`]`
`169`	`169`	`},`
`170`	`170`	`"resolutions": {`
	`171`	`+ "@metamask/perps-controller": "^9.0.0",`
`171`	`172`	`"@metamask/network-controller": "33.0.0",`
`172`	`173`	`"@react-native-community/viewpager": "patch:@react-native-community/viewpager@npm%3A3.3.0#~/.yarn/patches/@react-native-community-viewpager-npm-3.3.0.patch",`
`173`	`174`	`"@solana-mobile/mobile-wallet-adapter-protocol": "^2.2.5",`