refactor: migrate GatorPermissionsController to @metamask/messenger (#6461)

## Explanation

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->
This PR migrates `GatorPermissionsController` to the new
`@metamask/messenger` message bus, as opposed to the one exported from
`@metamask/base-controller`.

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->
* Related to #5626

## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] 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/contributing.md#updating-changelogs),
highlighting breaking changes as necessary
- [ ] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Migrates `GatorPermissionsController` to `@metamask/messenger`,
updates Base Controller imports/metadata, refactors tests, and wires
package/graph updates.
> 
> - **Breaking changes**:
> - Move from `RestrictedMessenger` (via `@metamask/base-controller`) to
`Messenger` from `@metamask/messenger` in `GatorPermissionsController`
and tests.
> - Rename state metadata key `anonymous` to `includeInDebugSnapshot`;
switch imports to `@metamask/base-controller/next`.
> - **Controller**
(`packages/gator-permissions-controller/src/GatorPermissionsController.ts`):
> - Replace `messagingSystem` usages with `messenger`
(`registerActionHandler`, `call`).
> - Update `GatorPermissionsControllerMessenger` type to use
`Messenger`.
> - Preserve state shape; keep getters/actions; no behavior change
beyond messenger plumbing.
> - **Tests**
(`packages/gator-permissions-controller/src/GatorPermissionsController.test.ts`):
> - Refactor to new `Messenger` types/utilities; introduce
root/delegated messenger setup; update metadata tests to
`includeInDebugSnapshot`.
> - **Package config**:
> - Add dependency `@metamask/messenger` and TypeScript project
references to `packages/messenger`.
> - **Docs/graph**:
> - Update README dependency graph to show `base_controller -->
messenger` and `gator_permissions_controller --> messenger`; add
`eip_7702_internal_rpc_middleware` edge.
> - **Changelog**:
> - Note breaking migration to `@metamask/messenger` and metadata rename
under Unreleased.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
15b0e0c. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: mikesposito

README.md

@@ -250,6 +250,7 @@ linkStyle default opacity:0.5
   gas_fee_controller --> polling_controller;
   gas_fee_controller --> network_controller;
   gator_permissions_controller --> base_controller;
+  gator_permissions_controller --> messenger;
   json_rpc_middleware_stream --> json_rpc_engine;
   keyring_controller --> base_controller;
   logging_controller --> base_controller;

packages/gator-permissions-controller/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **BREAKING:** Use new `Messenger` from `@metamask/messenger` ([#6461](https://github.com/MetaMask/core/pull/6461))
+  - Previously, `GatorPermissionsController` accepted a `RestrictedMessenger` instance from `@metamask/base-controller`.
+- **BREAKING:** Metadata property `anonymous` renamed to `includeInDebugSnapshot` ([#6461](https://github.com/MetaMask/core/pull/6461))
+
 ## [0.2.2]
 
 ### Changed

packages/gator-permissions-controller/package.json

@@ -51,6 +51,7 @@
     "@metamask/base-controller": "^8.4.2",
     "@metamask/delegation-core": "^0.2.0",
     "@metamask/delegation-deployments": "^0.12.0",
+    "@metamask/messenger": "^0.3.0",
     "@metamask/snaps-sdk": "^9.0.0",
     "@metamask/snaps-utils": "^11.0.0",
     "@metamask/utils": "^11.8.1"

packages/gator-permissions-controller/src/GatorPermissionsController.test.ts

@@ -1,5 +1,5 @@
 import type { AccountSigner } from '@metamask/7715-permission-types';
-import { Messenger, deriveStateFromMetadata } from '@metamask/base-controller';
+import { deriveStateFromMetadata } from '@metamask/base-controller/next';
 import {
   createTimestampTerms,
   createNativeTokenStreamingTerms,
@@ -9,6 +9,13 @@ import {
   CHAIN_ID,
   DELEGATOR_CONTRACTS,
 } from '@metamask/delegation-deployments';
+import {
+  MOCK_ANY_NAMESPACE,
+  Messenger,
+  type MessengerActions,
+  type MessengerEvents,
+  type MockAnyNamespace,
+} from '@metamask/messenger';
 import type { HandleSnapRequest, HasSnap } from '@metamask/snaps-controllers';
 import type { SnapId } from '@metamask/snaps-sdk';
 import { hexToBigInt, numberToHex, type Hex } from '@metamask/utils';
@@ -30,10 +37,6 @@ import type {
   StoredGatorPermission,
   PermissionTypesWithCustom,
 } from './types';
-import type {
-  ExtractAvailableAction,
-  ExtractAvailableEvent,
-} from '../../base-controller/tests/helpers';
 
 const MOCK_CHAIN_ID_1: Hex = '0xaa36a7';
 const MOCK_CHAIN_ID_2: Hex = '0x1';
@@ -83,7 +86,7 @@ describe('GatorPermissionsController', () => {
   describe('constructor', () => {
     it('creates GatorPermissionsController with default state', () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       expect(controller.state.isGatorPermissionsEnabled).toBe(false);
@@ -113,7 +116,7 @@ describe('GatorPermissionsController', () => {
       };
 
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
         state: customState,
       });
 
@@ -128,7 +131,7 @@ describe('GatorPermissionsController', () => {
 
     it('creates GatorPermissionsController with default config', () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       expect(controller.permissionsProviderSnapId).toBe(
@@ -140,7 +143,7 @@ describe('GatorPermissionsController', () => {
 
     it('isFetchingGatorPermissions is false on initialization', () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
         state: {
           isFetchingGatorPermissions: true,
         },
@@ -153,7 +156,7 @@ describe('GatorPermissionsController', () => {
   describe('disableGatorPermissions', () => {
     it('disables gator permissions successfully', async () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       await controller.enableGatorPermissions();
@@ -177,7 +180,7 @@ describe('GatorPermissionsController', () => {
   describe('fetchAndUpdateGatorPermissions', () => {
     it('fetches and updates gator permissions successfully', async () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       await controller.enableGatorPermissions();
@@ -224,7 +227,7 @@ describe('GatorPermissionsController', () => {
 
     it('throws error when gator permissions are not enabled', async () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       await controller.disableGatorPermissions();
@@ -240,7 +243,7 @@ describe('GatorPermissionsController', () => {
       });
 
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(rootMessenger),
+        messenger: getGatorPermissionsControllerMessenger(rootMessenger),
       });
 
       await controller.enableGatorPermissions();
@@ -262,7 +265,7 @@ describe('GatorPermissionsController', () => {
       });
 
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(rootMessenger),
+        messenger: getGatorPermissionsControllerMessenger(rootMessenger),
       });
 
       await controller.enableGatorPermissions();
@@ -286,7 +289,7 @@ describe('GatorPermissionsController', () => {
       });
 
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(rootMessenger),
+        messenger: getGatorPermissionsControllerMessenger(rootMessenger),
       });
 
       await controller.enableGatorPermissions();
@@ -302,7 +305,7 @@ describe('GatorPermissionsController', () => {
   describe('gatorPermissionsMap getter tests', () => {
     it('returns parsed gator permissions map', () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       const { gatorPermissionsMap } = controller;
@@ -340,7 +343,7 @@ describe('GatorPermissionsController', () => {
       };
 
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
         state: {
           gatorPermissionsMapSerialized: JSON.stringify(mockState),
         },
@@ -354,7 +357,7 @@ describe('GatorPermissionsController', () => {
 
   describe('message handlers tests', () => {
     it('registers all message handlers', () => {
-      const messenger = getMessenger();
+      const messenger = getGatorPermissionsControllerMessenger();
       const mockRegisterActionHandler = jest.spyOn(
         messenger,
         'registerActionHandler',
@@ -382,7 +385,7 @@ describe('GatorPermissionsController', () => {
   describe('enableGatorPermissions', () => {
     it('enables gator permissions successfully', async () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       await controller.enableGatorPermissions();
@@ -394,21 +397,21 @@ describe('GatorPermissionsController', () => {
   describe('metadata', () => {
     it('includes expected state in debug snapshots', () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       expect(
         deriveStateFromMetadata(
           controller.state,
           controller.metadata,
-          'anonymous',
+          'includeInDebugSnapshot',
         ),
       ).toMatchInlineSnapshot(`Object {}`);
     });
 
     it('includes expected state in state logs', () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       expect(
@@ -429,7 +432,7 @@ describe('GatorPermissionsController', () => {
 
     it('persists expected state', () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       expect(
@@ -448,7 +451,7 @@ describe('GatorPermissionsController', () => {
 
     it('exposes expected state to UI', () => {
       const controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
 
       expect(
@@ -484,7 +487,7 @@ describe('GatorPermissionsController', () => {
 
     beforeEach(() => {
       controller = new GatorPermissionsController({
-        messenger: getMessenger(),
+        messenger: getGatorPermissionsControllerMessenger(),
       });
     });
 
@@ -693,15 +696,23 @@ describe('GatorPermissionsController', () => {
 /**
  * The union of actions that the root messenger allows.
  */
-type RootAction = ExtractAvailableAction<GatorPermissionsControllerMessenger>;
+type AllGatorPermissionsControllerActions =
+  MessengerActions<GatorPermissionsControllerMessenger>;
 
 /**
  * The union of events that the root messenger allows.
  */
-type RootEvent = ExtractAvailableEvent<GatorPermissionsControllerMessenger>;
+type AllGatorPermissionsControllerEvents =
+  MessengerEvents<GatorPermissionsControllerMessenger>;
+
+type RootMessenger = Messenger<
+  MockAnyNamespace,
+  AllGatorPermissionsControllerActions,
+  AllGatorPermissionsControllerEvents
+>;
 
 /**
- * Constructs the unrestricted messenger. This can be used to call actions and
+ * Constructs the root messenger. This can be used to call actions and
  * publish events within the tests for this controller.
  *
  * @param args - The arguments to this function.
@@ -725,8 +736,10 @@ function getRootMessenger({
 }: {
   snapControllerHandleRequestActionHandler?: HandleSnapRequest['handler'];
   snapControllerHasActionHandler?: HasSnap['handler'];
-} = {}): Messenger<RootAction, RootEvent> {
-  const rootMessenger = new Messenger<RootAction, RootEvent>();
+} = {}): RootMessenger {
+  const rootMessenger: RootMessenger = new Messenger({
+    namespace: MOCK_ANY_NAMESPACE,
+  });
 
   rootMessenger.registerActionHandler(
     'SnapController:handleRequest',
@@ -740,18 +753,27 @@ function getRootMessenger({
 }
 
 /**
- * Constructs the messenger which is restricted to relevant SampleGasPricesController
+ * Constructs the messenger supporting relevant SampleGasPricesController
  * actions and events.
  *
  * @param rootMessenger - The root messenger to restrict.
- * @returns The restricted messenger.
+ * @returns The controller messenger.
  */
-function getMessenger(
+function getGatorPermissionsControllerMessenger(
   rootMessenger = getRootMessenger(),
 ): GatorPermissionsControllerMessenger {
-  return rootMessenger.getRestricted({
-    name: 'GatorPermissionsController',
-    allowedActions: ['SnapController:handleRequest', 'SnapController:has'],
-    allowedEvents: [],
+  const gatorPermissionsControllerMessenger = new Messenger<
+    'GatorPermissionsController',
+    AllGatorPermissionsControllerActions,
+    AllGatorPermissionsControllerEvents,
+    RootMessenger
+  >({
+    namespace: 'GatorPermissionsController',
+    parent: rootMessenger,
+  });
+  rootMessenger.delegate({
+    messenger: gatorPermissionsControllerMessenger,
+    actions: ['SnapController:handleRequest', 'SnapController:has'],
   });
+  return gatorPermissionsControllerMessenger;
 }