Feat/social controllers leaderboard opt out in (#9354)

## Explanation

Adds `optOutOfLeaderboard` and `optInToLeaderboard` to
`SocialController` and `SocialService`, with their corresponding
messenger actions. `@metamask/social-controllers` previously had no way
to opt a user out of (or back into) the Top Traders leaderboard; the
mobile client needs these to remove/restore a user from the global,
Clicker-backed leaderboard. Each method `POST`s to the existing
social-api endpoint (`/leaderboard/opt-out`, `/leaderboard/opt-in`) with
the JWT already attached by `SocialService`, and resolves to `void` on
the backend's `204`. Purely additive — no existing methods, types, or
behavior change.

  ## References

- Related to
[TSA-830](https://consensyssoftware.atlassian.net/browse/TSA-830) -
leaderboard opt-out: client flow + AUS persistence. Consumed by the
MetaMask mobile client.

  ## 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
- [x] 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

[TSA-830]:
https://consensyssoftware.atlassian.net/browse/TSA-830?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Purely additive API surface with tests; no changes to existing
methods, state, or auth flow beyond new leaderboard preference calls.
> 
> **Overview**
> Adds **`optOutOfLeaderboard`** and **`optInToLeaderboard`** to
`@metamask/social-controllers` so clients (e.g. mobile) can remove or
restore the signed-in user on the Top Traders / PnL leaderboard.
> 
> **`SocialService`** issues JWT-authenticated **`POST`** requests to
**`/api/v1/leaderboard/opt-out`** and **`/api/v1/leaderboard/opt-in`**,
treats success as **`204`**, and surfaces failures via new
**`LEADERBOARD_OPT_OUT_FAILED`** / **`LEADERBOARD_OPT_IN_FAILED`**
messages. **`SocialController`** exposes the same operations as thin
messenger delegates (no controller state changes). Messenger action
types, package exports, changelog, and unit tests are updated
accordingly.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
bdef2c4. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Bigshmow

packages/social-controllers/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `optOutOfLeaderboard` and `optInToLeaderboard` methods to `SocialController` and `SocialService`, with corresponding messenger actions (`SocialController:optOutOfLeaderboard`, `SocialController:optInToLeaderboard`, `SocialService:optOutOfLeaderboard`, `SocialService:optInToLeaderboard`). These call `POST /leaderboard/opt-out` and `POST /leaderboard/opt-in` respectively (JWT-authed, `204 No Content` on success) ([#9354](https://github.com/MetaMask/core/pull/9354))
+
 ### Changed
 
 - Bump `@metamask/controller-utils` from `^12.2.0` to `^12.3.0` ([#9218](https://github.com/MetaMask/core/pull/9218))

packages/social-controllers/src/SocialController-method-action-types.ts

@@ -56,11 +56,29 @@ export type SocialControllerUpdateFollowingAction = {
   handler: SocialController['updateFollowing'];
 };
 
+/**
+ * Opts the current user out of the PnL leaderboard.
+ */
+export type SocialControllerOptOutOfLeaderboardAction = {
+  type: `SocialController:optOutOfLeaderboard`;
+  handler: SocialController['optOutOfLeaderboard'];
+};
+
+/**
+ * Opts the current user back into the PnL leaderboard.
+ */
+export type SocialControllerOptInToLeaderboardAction = {
+  type: `SocialController:optInToLeaderboard`;
+  handler: SocialController['optInToLeaderboard'];
+};
+
 /**
  * Union of all SocialController action types.
  */
 export type SocialControllerMethodActions =
   | SocialControllerUpdateLeaderboardAction
   | SocialControllerFollowTraderAction
   | SocialControllerUnfollowTraderAction
-  | SocialControllerUpdateFollowingAction;
+  | SocialControllerUpdateFollowingAction
+  | SocialControllerOptOutOfLeaderboardAction
+  | SocialControllerOptInToLeaderboardAction;

packages/social-controllers/src/SocialController.test.ts

@@ -58,6 +58,8 @@ function getMessenger(rootMessenger: RootMessenger): SocialControllerMessenger {
       'SocialService:follow',
       'SocialService:unfollow',
       'SocialService:fetchFollowing',
+      'SocialService:optOutOfLeaderboard',
+      'SocialService:optInToLeaderboard',
     ],
     events: [],
     messenger,
@@ -499,6 +501,104 @@ describe('SocialController', () => {
     });
   });
 
+  describe('optOutOfLeaderboard', () => {
+    it('delegates to the service via messenger and resolves to void', async () => {
+      const rootMessenger = getRootMessenger();
+      const optOut = jest.fn().mockResolvedValue(undefined);
+      mockServiceAction(
+        rootMessenger,
+        'SocialService:optOutOfLeaderboard',
+        optOut,
+      );
+
+      const { controller } = createController({ rootMessenger });
+
+      const result = await controller.optOutOfLeaderboard();
+
+      expect(optOut).toHaveBeenCalledTimes(1);
+      expect(result).toBeUndefined();
+    });
+
+    it('is callable via messenger action', async () => {
+      const rootMessenger = getRootMessenger();
+      mockServiceAction(
+        rootMessenger,
+        'SocialService:optOutOfLeaderboard',
+        jest.fn().mockResolvedValue(undefined),
+      );
+
+      const { messenger } = createController({ rootMessenger });
+
+      expect(
+        await messenger.call('SocialController:optOutOfLeaderboard'),
+      ).toBeUndefined();
+    });
+
+    it('propagates service errors', async () => {
+      const rootMessenger = getRootMessenger();
+      mockServiceAction(
+        rootMessenger,
+        'SocialService:optOutOfLeaderboard',
+        jest.fn().mockRejectedValue(new Error('opt-out failed')),
+      );
+
+      const { controller } = createController({ rootMessenger });
+
+      await expect(controller.optOutOfLeaderboard()).rejects.toThrow(
+        'opt-out failed',
+      );
+    });
+  });
+
+  describe('optInToLeaderboard', () => {
+    it('delegates to the service via messenger and resolves to void', async () => {
+      const rootMessenger = getRootMessenger();
+      const optIn = jest.fn().mockResolvedValue(undefined);
+      mockServiceAction(
+        rootMessenger,
+        'SocialService:optInToLeaderboard',
+        optIn,
+      );
+
+      const { controller } = createController({ rootMessenger });
+
+      const result = await controller.optInToLeaderboard();
+
+      expect(optIn).toHaveBeenCalledTimes(1);
+      expect(result).toBeUndefined();
+    });
+
+    it('is callable via messenger action', async () => {
+      const rootMessenger = getRootMessenger();
+      mockServiceAction(
+        rootMessenger,
+        'SocialService:optInToLeaderboard',
+        jest.fn().mockResolvedValue(undefined),
+      );
+
+      const { messenger } = createController({ rootMessenger });
+
+      expect(
+        await messenger.call('SocialController:optInToLeaderboard'),
+      ).toBeUndefined();
+    });
+
+    it('propagates service errors', async () => {
+      const rootMessenger = getRootMessenger();
+      mockServiceAction(
+        rootMessenger,
+        'SocialService:optInToLeaderboard',
+        jest.fn().mockRejectedValue(new Error('opt-in failed')),
+      );
+
+      const { controller } = createController({ rootMessenger });
+
+      await expect(controller.optInToLeaderboard()).rejects.toThrow(
+        'opt-in failed',
+      );
+    });
+  });
+
   describe('error propagation', () => {
     it('propagates service errors from updateLeaderboard', async () => {
       const rootMessenger = getRootMessenger();

packages/social-controllers/src/SocialController.ts

@@ -22,6 +22,8 @@ import type {
   SocialServiceFetchFollowingAction,
   SocialServiceFetchLeaderboardAction,
   SocialServiceFollowAction,
+  SocialServiceOptInToLeaderboardAction,
+  SocialServiceOptOutOfLeaderboardAction,
   SocialServiceUnfollowAction,
 } from './SocialService-method-action-types';
 
@@ -32,6 +34,8 @@ const MESSENGER_EXPOSED_METHODS = [
   'followTrader',
   'unfollowTrader',
   'updateFollowing',
+  'optOutOfLeaderboard',
+  'optInToLeaderboard',
 ] as const;
 
 // === ACTION TYPES ===
@@ -60,7 +64,9 @@ type AllowedActions =
   | SocialServiceFetchLeaderboardAction
   | SocialServiceFollowAction
   | SocialServiceUnfollowAction
-  | SocialServiceFetchFollowingAction;
+  | SocialServiceFetchFollowingAction
+  | SocialServiceOptOutOfLeaderboardAction
+  | SocialServiceOptInToLeaderboardAction;
 
 type AllowedEvents = never;
 
@@ -264,4 +270,18 @@ export class SocialController extends BaseController<
 
     return followingResponse;
   }
+
+  /**
+   * Opts the current user out of the PnL leaderboard.
+   */
+  async optOutOfLeaderboard(): Promise<void> {
+    await this.messenger.call('SocialService:optOutOfLeaderboard');
+  }
+
+  /**
+   * Opts the current user back into the PnL leaderboard.
+   */
+  async optInToLeaderboard(): Promise<void> {
+    await this.messenger.call('SocialService:optInToLeaderboard');
+  }
 }

packages/social-controllers/src/SocialService-method-action-types.ts

@@ -141,6 +141,22 @@ export type SocialServiceUnfollowAction = {
   handler: SocialService['unfollow'];
 };
 
+/**
+ * Opts the current user out of the PnL leaderboard.
+ */
+export type SocialServiceOptOutOfLeaderboardAction = {
+  type: `SocialService:optOutOfLeaderboard`;
+  handler: SocialService['optOutOfLeaderboard'];
+};
+
+/**
+ * Opts the current user back into the PnL leaderboard.
+ */
+export type SocialServiceOptInToLeaderboardAction = {
+  type: `SocialService:optInToLeaderboard`;
+  handler: SocialService['optInToLeaderboard'];
+};
+
 /**
  * Union of all SocialService action types.
  */
@@ -153,4 +169,6 @@ export type SocialServiceMethodActions =
   | SocialServiceFetchPositionByIdAction
   | SocialServiceFetchFollowingAction
   | SocialServiceFollowAction
-  | SocialServiceUnfollowAction;
+  | SocialServiceUnfollowAction
+  | SocialServiceOptOutOfLeaderboardAction
+  | SocialServiceOptInToLeaderboardAction;

packages/social-controllers/src/SocialService.test.ts

@@ -1029,4 +1029,54 @@ describe('SocialService', () => {
       );
     });
   });
+
+  describe('optOutOfLeaderboard', () => {
+    it('sends POST to /leaderboard/opt-out with the bearer token and resolves to void', async () => {
+      mockFetch.mockResolvedValue({ ok: true, status: 204 });
+
+      const service = createService();
+      const result = await service.optOutOfLeaderboard();
+
+      expect(result).toBeUndefined();
+      expect(mockFetch).toHaveBeenCalledWith(`${V1_URL}/leaderboard/opt-out`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${MOCK_TOKEN}` },
+      });
+    });
+
+    it('throws HttpError on non-ok response', async () => {
+      mockFetch.mockResolvedValue({ ok: false, status: 401 });
+
+      const service = createService();
+
+      await expect(service.optOutOfLeaderboard()).rejects.toThrow(
+        `${SocialServiceErrorMessage.LEADERBOARD_OPT_OUT_FAILED}: 401`,
+      );
+    });
+  });
+
+  describe('optInToLeaderboard', () => {
+    it('sends POST to /leaderboard/opt-in with the bearer token and resolves to void', async () => {
+      mockFetch.mockResolvedValue({ ok: true, status: 204 });
+
+      const service = createService();
+      const result = await service.optInToLeaderboard();
+
+      expect(result).toBeUndefined();
+      expect(mockFetch).toHaveBeenCalledWith(`${V1_URL}/leaderboard/opt-in`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${MOCK_TOKEN}` },
+      });
+    });
+
+    it('throws HttpError on non-ok response', async () => {
+      mockFetch.mockResolvedValue({ ok: false, status: 500 });
+
+      const service = createService();
+
+      await expect(service.optInToLeaderboard()).rejects.toThrow(
+        `${SocialServiceErrorMessage.LEADERBOARD_OPT_IN_FAILED}: 500`,
+      );
+    });
+  });
 });

packages/social-controllers/src/SocialService.ts

@@ -186,6 +186,8 @@ const MESSENGER_EXPOSED_METHODS = [
   'fetchPositionById',
   'follow',
   'unfollow',
+  'optOutOfLeaderboard',
+  'optInToLeaderboard',
 ] as const;
 
 export type SocialServiceActions =
@@ -584,6 +586,52 @@ export class SocialService extends BaseDataService<
     return unfollowResponse;
   }
 
+  /**
+   * Opts the current user out of the PnL leaderboard.
+   */
+  async optOutOfLeaderboard(): Promise<void> {
+    await this.fetchQuery({
+      queryKey: [`${this.name}:optOutOfLeaderboard`],
+      staleTime: 0,
+      queryFn: async () => {
+        const url = `${this.#v1Url}/leaderboard/opt-out`;
+        const authHeaders = await this.#getAuthHeaders();
+        const response = await fetch(url, {
+          method: 'POST',
+          headers: authHeaders,
+        });
+        SocialService.#throwIfNotOk(
+          response,
+          SocialServiceErrorMessage.LEADERBOARD_OPT_OUT_FAILED,
+        );
+        return null;
+      },
+    });
+  }
+
+  /**
+   * Opts the current user back into the PnL leaderboard.
+   */
+  async optInToLeaderboard(): Promise<void> {
+    await this.fetchQuery({
+      queryKey: [`${this.name}:optInToLeaderboard`],
+      staleTime: 0,
+      queryFn: async () => {
+        const url = `${this.#v1Url}/leaderboard/opt-in`;
+        const authHeaders = await this.#getAuthHeaders();
+        const response = await fetch(url, {
+          method: 'POST',
+          headers: authHeaders,
+        });
+        SocialService.#throwIfNotOk(
+          response,
+          SocialServiceErrorMessage.LEADERBOARD_OPT_IN_FAILED,
+        );
+        return null;
+      },
+    });
+  }
+
   /**
    * Shared helper for fetching open/closed positions.
    *

packages/social-controllers/src/index.ts

@@ -13,6 +13,8 @@ export {
 
 export type {
   SocialControllerFollowTraderAction,
+  SocialControllerOptInToLeaderboardAction,
+  SocialControllerOptOutOfLeaderboardAction,
   SocialControllerUnfollowTraderAction,
   SocialControllerUpdateFollowingAction,
   SocialControllerUpdateLeaderboardAction,
@@ -34,6 +36,8 @@ export type {
   SocialServiceFetchPositionByIdAction,
   SocialServiceFetchTraderProfileAction,
   SocialServiceFollowAction,
+  SocialServiceOptInToLeaderboardAction,
+  SocialServiceOptOutOfLeaderboardAction,
   SocialServiceUnfollowAction,
 } from './SocialService-method-action-types';
 

packages/social-controllers/src/social-constants.ts

@@ -30,4 +30,7 @@ export const SocialServiceErrorMessage = {
   FETCH_POSITION_BY_ID_FAILED: 'SocialService: Position request failed',
   FETCH_POSITION_BY_ID_INVALID_RESPONSE:
     'SocialService: Position returned invalid response',
+  LEADERBOARD_OPT_OUT_FAILED:
+    'SocialService: Leaderboard opt-out request failed',
+  LEADERBOARD_OPT_IN_FAILED: 'SocialService: Leaderboard opt-in request failed',
 } as const;