refactor!: Add consolidated legacy method middleware by rekmarks · Pull Request #8583 · MetaMask/core

rekmarks · 2026-04-24T22:11:37Z

Explanation

Consolidates the bespoke makeMethodMiddlewareMaker implementations from the
MetaMask extension and mobile clients into a single legacy createMethodMiddleware
exported from @metamask/json-rpc-engine, and removes the unused permitted
method handlers from @metamask/permission-controller.

`@metamask/json-rpc-engine`

Adds a legacy createMethodMiddleware that builds a JsonRpcEngine middleware
from a record of handlers keyed by method name. Hooks are validated against the
union of hookNames declared by the handlers (rejecting both missing and
extraneous hooks), and incoming requests are dispatched by method.
Handlers may declare actionNames and receive a per-handler delegated
Messenger as the sixth argument to implementation, mirroring the v2
createMethodMiddleware.
The legacy and v2 versions share their hook selection / validation and
messenger delegation utilities (assertExpectedHooks, selectHooks,
createHandlerMessenger).
The legacy export is deprecated in favor of the v2 createMethodMiddleware.
It exists only to give the extension and mobile clients a consolidated
migration target before they move to JsonRpcEngineV2.

`@metamask/eip1193-permission-middleware` (BREAKING)

Reshapes the per-method exports (getPermissionsHandler,
requestPermissionsHandler, revokePermissionsHandler) into the new
MethodHandler format and consolidates them into a single methodHandlers
export keyed by method name. The individual handler exports are removed.

`@metamask/multichain-api-middleware` (BREAKING)

Reshapes the per-method exports (walletCreateSession, walletGetSession,
walletInvokeMethod, walletRevokeSession) into the new MethodHandler
format and consolidates them into a single methodHandlers export keyed by
method name. The individual handler exports are removed.

`@metamask/permission-controller` (BREAKING)

Removes the permitted RPC method handler modules (getPermissions,
requestPermissions, revokePermissions) and the related
permissionRpcMethods and PermittedHandlerExport exports. These were unused
in practice. Replacement types are available in
@metamask/[email protected].

References

Related: Migrate JSON-RPC stack to JsonRpcEngineV2 #6327
- We don't migrate anything to v2 in this PR, but it ought to make that migration simpler.
Previews:
- preview: [email protected] metamask-extension#42221
- Mobile forthcoming

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
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note

High Risk
Breaking export and typing changes across multiple published packages plus new middleware dispatch/validation logic could impact downstream integrations and runtime hook wiring.

Overview
Adds a deprecated legacy createMethodMiddleware export to @metamask/json-rpc-engine that dispatches JSON-RPC requests by req.method, enforces exact hook sets (missing/extraneous), and optionally delegates a per-handler Messenger when actionNames are declared; shared utilities (selectHooks, assertExpectedHooks, createHandlerMessenger) are centralized in v2/utils and v2 middleware is updated to support no-messenger/no-hooks handlers.

Introduces breaking API reshapes in @metamask/eip1193-permission-middleware and @metamask/multichain-api-middleware by replacing per-method exports with a single methodHandlers map keyed by method name, updating handlers to the new MethodHandler typing, and adding construction tests via createMethodMiddleware.

Removes @metamask/permission-controller permitted RPC method modules/exports and related types, and tightens a couple of behaviors: wallet_invokeMethod now returns invalidParams when params isn’t an object, and wallet_createSession makes trackSessionCreatedEvent a required hook (nullable to disable).

^{Reviewed by Cursor Bugbot for commit 846bfc4. Bugbot is set up for automated code reviews on this repo. Configure here.}

Add `createMethodMiddlewareFactory` to the legacy (v1) surface, consolidating the near-identical `makeMethodMiddlewareMaker` implementations from metamask-extension and metamask-mobile. The new export is deprecated in favor of the v2 `createMethodMiddleware`. Extract `selectHooks` and `assertExpectedHooks` into a shared `hookUtils.ts` module used by both v1 and v2. v2 now performs the same strict missing/extraneous hook validation as v1 at middleware construction time. Co-Authored-By: Claude Opus 4.7 <[email protected]>

…od middleware

…thod middleware Allow `Messenger<string, never>` in the no-actions branch of `CreateMethodMiddlewareFactoryOptions` so callers may still pass a no-op root messenger when handlers declare no actions. Pre-select hooks per handler at curried-call time and store them on a `ResolvedHandler` entry, mirroring v2's dispatch shape and removing `selectHooks` from the per-request path. Co-Authored-By: Claude Opus 4.7 <[email protected]>

Overload createMethodMiddleware (v1 and v2) so messenger is optional when handlers do not use messenger actions. Move actionNames/root validation into createHandlerMessenger; add tests for no-messenger and missing-root cases. Made-with: Cursor

Add a fifth generic to MethodHandlerImplementation and MethodHandler so callers can type non-standard JSON-RPC request fields (e.g. origin) without widening JsonRpcEngine types. Extras are optionalized on the request parameter so middleware can pass a plain JsonRpcRequest. Add a test and changelog note. Made-with: Cursor

…ttern

…r pattern

rekmarks · 2026-04-28T21:22:52Z

@cursor review

rekmarks · 2026-04-28T21:23:32Z

@metamaskbot publish-preview

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 45a82ea. Configure here.}

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 86dd857. Configure here.}

FrederikBolding · 2026-04-29T07:27:07Z

+    const middleware = createMethodMiddleware({
+      handlers: { callAction: messengerHandler },
+      messenger: rootMessenger,
+      hooks: {},


I'm unsure exactly why but the inference does not work as well as in the v2 version, for example here if you add extraneous hooks you do not get a type error.

Fixed here: f43f664

FrederikBolding · 2026-04-29T07:29:45Z

I wonder why we aren't using this package in the clients 🤔

Great question. Didn't realize that. @jiexi do you know the status of this package?

The package is used in mobile, but its integration was overlooked in the extension. It can be added there once the other changes in this PR have been integrated.

Type the `hooks` property as `Record<string, never>` (rather than collapsing to `unknown` via `UnionToIntersection<never>`) when no handler declares hooks. This forces callers to spell out `hooks: {}` and prevents TypeScript from co-resolving the shared `Handlers` generic in a way that also relaxes the `messenger` requirement. Co-Authored-By: Claude Opus 4.7 <[email protected]>

jiexi · 2026-04-29T18:12:36Z

+        | readonly HandlerActions<Handlers[keyof Handlers]>['type'][]
+        | undefined,


Ahh i see. Because it's too early to type this in AnyMethodHandler itself. fun

jiexi · 2026-04-29T18:49:21Z

nit with the naming of the handler type. For example

type RevokePermissionsHandler = MethodHandler<...>;

export const revokePermissions = {
  ...
} satisfies RevokePermissionsHandler;

export const revokePermissionsHandler = {
  [MethodNames.RevokePermissions]: revokePermissions,
}

This is awkward to me because on first read, revokePermissions should be called revokePermissionsHandler to me, especially since it satisfies RevokePermissionsHandler. But the pattern in this PR has been to define revokePermissionsHandler as the Record<string, MethodHandler> object. I'm not sure what to rename the existing revokePermissionsHandler / the type for revokePermissionsHandler though

Rename the per-method handler constants to `<methodName>Handler` (e.g. `getPermissions` → `getPermissionsHandler`, `walletCreateSession` → `walletCreateSessionHandler`) and export their corresponding type aliases. Drop the per-file `Record<methodName, handler>` wrappers; the consolidated `methodHandlers` map is now built directly in each package's index, using computed property keys from a `MethodNames` const object (or the existing enum, in `eip1193-permission-middleware`) to satisfy the naming-convention lint rule. Co-Authored-By: Claude Opus 4.7 <[email protected]>

rekmarks · 2026-04-29T22:48:38Z

@metamaskbot publish-preview

rekmarks and others added 3 commits April 24, 2026 13:32

refactor(permission-controller)!: Remove unrestricted rpc methods

e785683

refactor(json-rpc-engine)!: Support messenger handlers in legacy meth…

b7faed3

…od middleware

rekmarks had a problem deploying to default-branch April 24, 2026 22:11 — with GitHub Actions Failure

rekmarks changed the title ~~refactor!: Consolidate legacy method middleware implementation~~ refactor!: Add consolidated legacy method middleware Apr 24, 2026

chore: Update changelogs

be9aaca

This comment was marked as resolved.

Sign in to view

FrederikBolding reviewed Apr 27, 2026

View reviewed changes

Comment thread packages/permission-controller/CHANGELOG.md Outdated

FrederikBolding reviewed Apr 27, 2026

View reviewed changes

Comment thread packages/json-rpc-engine/src/v2/index.ts

FrederikBolding reviewed Apr 27, 2026

View reviewed changes

Comment thread packages/json-rpc-engine/src/createMethodMiddleware.ts Outdated

FrederikBolding reviewed Apr 27, 2026

View reviewed changes

Comment thread packages/json-rpc-engine/src/createMethodMiddleware.test.ts Outdated

rekmarks and others added 4 commits April 27, 2026 09:50

refactor: Harmonize legacy middleware with v2 version

09b26c5

Merge branch 'main' into rekm/v2-permitted-handlers

f86425a

chore: Tweak permission-controller changelog

dc38a25

This comment was marked as outdated.

Sign in to view

FrederikBolding reviewed Apr 28, 2026

View reviewed changes

Comment thread packages/json-rpc-engine/src/createMethodMiddleware.ts Outdated

FrederikBolding reviewed Apr 28, 2026

View reviewed changes

Comment thread packages/json-rpc-engine/src/createMethodMiddleware.test.ts Outdated

FrederikBolding reviewed Apr 28, 2026

View reviewed changes

Comment thread packages/json-rpc-engine/src/createMethodMiddleware.test.ts Outdated

FrederikBolding reviewed Apr 28, 2026

View reviewed changes

Comment thread packages/json-rpc-engine/src/createMethodMiddleware.ts Outdated

rekmarks added 6 commits April 28, 2026 08:49

refactor: Address review

fc5c197

refactor(multichain-api-middleware): Migrate to new method handler pa…

afad6dc

…ttern

refactor(eip1193-permission-middleware): Migrate to new method handle…

e7105fc

…r pattern

refactor: Minor fixups

45a82ea

rekmarks marked this pull request as ready for review April 28, 2026 21:21

rekmarks requested a review from a team as a code owner April 28, 2026 21:21

rekmarks requested a review from FrederikBolding April 28, 2026 21:21

cursor Bot reviewed Apr 28, 2026

View reviewed changes

fix: Fix legacy method middleware hook inference

86dd857

cursor Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread packages/multichain-api-middleware/src/handlers/wallet-createSession.ts Outdated

rekmarks added 2 commits April 28, 2026 15:16

chore: Lint

3763b57

refactor: Fix trackSessionCreatedEvent optionality

c4a8339

FrederikBolding reviewed Apr 29, 2026

View reviewed changes

Comment thread packages/multichain-api-middleware/src/handlers/wallet-invokeMethod.ts Outdated

FrederikBolding reviewed Apr 29, 2026

View reviewed changes

Comment thread packages/multichain-api-middleware/src/handlers/wallet-invokeMethod.ts

rekmarks and others added 3 commits April 29, 2026 08:46

test: Round out v2 method middleware test suite

7114b69

chore: lint

897b1ae

jiexi reviewed Apr 29, 2026

View reviewed changes

Comment thread packages/multichain-api-middleware/CHANGELOG.md

jiexi reviewed Apr 29, 2026

View reviewed changes

Comment thread packages/json-rpc-engine/src/v2/utils.ts Outdated

jiexi reviewed Apr 29, 2026

View reviewed changes

Comment thread packages/json-rpc-engine/src/v2/utils.ts

jiexi reviewed Apr 29, 2026

View reviewed changes

Comment thread packages/json-rpc-engine/src/createMethodMiddleware.test.ts Outdated

jiexi previously approved these changes Apr 29, 2026

View reviewed changes

refactor: Address review feedback

846bfc4

rekmarks dismissed jiexi’s stale review via 846bfc4 April 29, 2026 22:27

rekmarks requested a review from FrederikBolding April 29, 2026 22:48

rekmarks enabled auto-merge April 29, 2026 22:50

rekmarks disabled auto-merge April 29, 2026 22:50

		\| readonly HandlerActions<Handlers[keyof Handlers]>['type'][]
		\| undefined,

Uh oh!

Conversation

rekmarks commented Apr 24, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

@metamask/json-rpc-engine

@metamask/eip1193-permission-middleware (BREAKING)

@metamask/multichain-api-middleware (BREAKING)

@metamask/permission-controller (BREAKING)

References

Checklist

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rekmarks commented Apr 28, 2026

Uh oh!

rekmarks commented Apr 28, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

FrederikBolding Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

rekmarks Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

FrederikBolding Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

rekmarks Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

rekmarks Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jiexi Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jiexi commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rekmarks commented Apr 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rekmarks commented Apr 24, 2026 •

edited by cursor Bot

Loading

`@metamask/json-rpc-engine`

`@metamask/eip1193-permission-middleware` (BREAKING)

`@metamask/multichain-api-middleware` (BREAKING)

`@metamask/permission-controller` (BREAKING)

jiexi commented Apr 29, 2026 •

edited

Loading