refactor!: Migrate `eth-json-rpc-middleware` to `JsonRpcEngineV2` #7065

rekmarks · 2025-11-05T19:39:51Z

Explanation

Migrates @metamask/eth-json-rpc-middleware to the JsonRpcEngineV2 conventions in a total overhaul of the package. The semantics of each middleware should be the same as before.

One potential behavioral difference is that request cloning within middleware now occurs with klona instead of klona/full. This is because klona/full copies property descriptors such that cloned requests are immutable but not frozen in the Object.isFrozen() sense. This is unlikely to make a difference in practice to us, since our request objects have historically been "plain" objects.

As with all #6327-related work up to this point, json-rpc-engine received minor refactors to facilitate the use of the new abstractions in situ.

Incidentally, all lint rule exceptions have been removed and all lint warnings and errors have been resolved for eth-json-rpc-middleware.

Several other packages are changed to support or in consequence of the migration:

network-controller
- The NetworkClient is migrated to JsonRpcEngineV2.
- The RpcService now uses Readonly<JsonRpcRequest> internally for request objects received via its request() method, since the "fetch" middleware now passes it deeply frozen request objects directly.
message-manager and signature-controller
- Minor changes to types in order to harmonize them with the new conventions.

References

Progresses Migrate JSON-RPC stack to JsonRpcEngineV2 #6327

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, highlighting breaking changes as necessary
I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes
- refactor: Bump eth-json-rpc-middleware and related deps metamask-extension#37560
- chore: Bump eth-json-rpc-middleware and related deps metamask-mobile#22218

Note

Migrates @metamask/eth-json-rpc-middleware and the Network Controller’s client to JsonRpcEngineV2, updates APIs to use context and deeply frozen requests, and aligns dependent packages/types and tests.

Middleware (BREAKING):
- Migrate all @metamask/eth-json-rpc-middleware to JsonRpcEngineV2 (createBlockCache/Ref/RefRewrite/TrackerInspector/InflightCache/RetryOnEmpty/Fetch, createWalletMiddleware).
- Add providerAsMiddlewareV2; retain legacy adapter for back-compat.
- Switch to context-based data (origin, skipCache), return values instead of mutating responses; requests are deeply frozen.
- Update wallet method handler signatures to include context; use InternalProvider.
Network Controller:
- NetworkClient pipelines rebuilt on JsonRpcEngineV2; compose V2 middleware; provider created via providerFromMiddlewareV2.
- RpcService.request now accepts Readonly<JsonRpcRequest> and handles frozen requests; tests expanded.
Message/Signature types:
- Rename OriginalRequest → MessageRequest; allow string id values in message/signature requests.
Utils/Tests:
- Normalize EIP-712 data without in-place mutation; support deep-frozen inputs.
- Test helpers and suites rewritten for V2 engine semantics.
Tooling/Meta:
- ESLint config cleanup; remove package-specific overrides.
- Dependencies updated (e.g., deep-freeze-strict, @metamask/message-manager); minor coverage threshold tweak.
- Changelogs updated to document V2 migration and related breaking changes.

^{Written by Cursor Bugbot for commit e7a7768. This will update automatically on new commits. Configure here.}

… methods (#7061) ## Explanation Adds a `MiddlewareContext` parameter to `InternalProvider.request()` and `JsonRpcServer.handle()`. This is essentially a missing feature from the `JsonRpcEngineV2` implementation / migration, since callers are no longer able to add non-JSON-RPC properties to request objects and instead need to use the `context` object. As part of this, permit specifying a plain object as the context to avoid forcing callers to import `MiddlewareContext` whenever they want to make a JSON-RPC call with some particular context. Also opportunistically fixes a bug with the static `isInstance` methods of V2 engine classes, where we wouldn't walk the prototype chain when checking for the symbol property. ## References - Related to #6327 ## 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/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~ - These changes are non-breaking, and will in any event be exhaustively covered via preview builds through #7065.  --- > [!NOTE] > Adds a context option to `InternalProvider.request()`/`JsonRpcServer.handle()`, enables passing plain-object contexts across the V2 engine, makes `PollingBlockTracker` context-generic, and narrows Network Controller’s `Provider` type; updates tests/docs accordingly. > > - **JSON-RPC Engine (v2)**: > - Add `HandleOptions` with `context` (accepts `MiddlewareContext` or plain object) and forward it through `handle()` and `JsonRpcServer.handle()`. > - Enhance `MiddlewareContext` (construct from KeyValues object, `isInstance`) and export `InferKeyValues`; add shared `isInstance` util; minor server refactor (static request coercion). > - Update README and tests for context passing and utils. > - **eth-json-rpc-provider**: > - Make `InternalProvider` generic over `Context`; `request()` accepts `{ context }` and forwards to engine. > - Update tests and CHANGELOG. > - **eth-block-tracker**: > - Genericize `PollingBlockTracker` with `Context`; type provider as `InternalProvider<Context>`; update CHANGELOG. > - **Network Controller**: > - Narrow `Provider` to `InternalProvider<MiddlewareContext<{ origin: string; skipCache: boolean } & Record<string, unknown>>>`. > - Type updates in `create-network-client`, tests, and helpers; update CHANGELOG. > - **Tests/Utilities**: > - Update fakes (`FakeProvider`, `FakeBlockTracker`) and consumers to new generic/context types. > - Bridge controller test now uses `@metamask/network-controller` `Provider`. > - **Deps**: > - Add `@metamask/network-controller` to root `package.json`. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit c853283. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>

packages/network-controller/src/create-network-client.ts

rekmarks · 2025-11-08T01:00:08Z

packages/eth-json-rpc-middleware/tsconfig.json

    }
  ],
-  "include": ["../../types", "./src", "./test", "./types"]
+  "include": ["../../types", "./src", "./test"]


There is no ./types directory.

packages/eth-json-rpc-middleware/src/block-ref-rewrite.ts

rekmarks · 2025-11-08T15:52:48Z

packages/eth-json-rpc-middleware/src/fetch.ts

-          headers,
-        },
-      );
+    const jsonRpcResponse = await rpcService.request(klona(request), {


I naively cloned this, but I'm questioning whether we actually need to. The request is not mutated in rpc-service.ts. Can we just pass the frozen request?

I think we can: 92a672c

rekmarks · 2025-11-08T15:54:39Z

packages/eth-json-rpc-middleware/package.json

    "@metamask/eth-json-rpc-provider": "^5.0.1",
    "@metamask/eth-sig-util": "^8.2.0",
    "@metamask/json-rpc-engine": "^10.1.1",
+    "@metamask/message-manager": "^14.0.0",


Type-only import, but the types appear in the public interface.

packages/eth-json-rpc-middleware/test/util/helpers.ts

packages/eth-json-rpc-middleware/src/wallet.ts

packages/eth-json-rpc-middleware/src/inflight-cache.ts

…ache

packages/eth-json-rpc-middleware/src/wallet.ts

jeffsmale90

I only reviewed the EIP-7715 related wallet-request-execution-permission and wallet-revoke-execution-permission middlewares, which look good!

packages/eth-json-rpc-middleware/src/wallet.ts

mcmire

LGTM! I found some other minor changes we could make, but I can prepare a new PR for those.

mcmire · 2025-11-12T15:55:56Z

packages/eth-json-rpc-middleware/CHANGELOG.md


 ## [Unreleased]

 ### Changed


It looks like we also added a new export: providerAsMiddlewareV2.

I can make sure to add this when we make a new release.

mcmire · 2025-11-12T15:56:21Z

packages/eth-json-rpc-middleware/CHANGELOG.md


+- **BREAKING:** Migrate to `JsonRpcEngineV2` ([#7065](https://github.com/MetaMask/core/pull/7065))
+  - Migrates all middleware from `JsonRpcEngine` to `JsonRpcEngineV2`.
+  - Signatures of various middleware dependencies, e.g. `processTransaction` of `createWalletMiddleware`, have changed


It might be worth it to detail this further to make upgrading easier. I'll do another pass when making a new release.

mcmire · 2025-11-12T16:01:58Z

packages/eth-json-rpc-middleware/src/inflight-cache.ts

+    // allow request to be handled normally
+    log('Carrying original request forward %o', request);
+    try {
+      const result = (await next()) as Json;


I feel that we should use Readonly<Json> here rather than Json, to better match Next<...>. I can make this change in a followup.

mcmire · 2025-11-12T16:02:27Z

packages/eth-json-rpc-middleware/src/inflight-cache.ts

+        activeRequestHandlers.length,
+        request,
+      );
+      runRequestHandlers({ error: error as Error }, activeRequestHandlers);


I don't think we need the type assertion here. I can make a change in a followup.

mcmire · 2025-11-12T16:24:33Z

packages/json-rpc-engine/src/v2/createScaffoldMiddleware.ts

-export function createScaffoldMiddleware(
-  handlers: MiddlewareScaffold,
-): JsonRpcMiddleware<JsonRpcRequest, Json> {
+export function createScaffoldMiddleware<Context extends ContextConstraint>(


Perhaps worth documenting this in the changelog? Need to investigate further.

I guess this is covered under the existing bullet.

mcmire · 2025-11-12T16:26:36Z

packages/message-manager/CHANGELOG.md


+### Changed
+
+- Rename `OriginalRequest` type to `MessageRequest` and permit string `id` values ([#7065](https://github.com/MetaMask/core/pull/7065))


This is a breaking change due to the rename. We should probably retain the old name for backward compatibility, for now. I can handle this in a followup.

mcmire · 2025-11-12T16:28:59Z

packages/network-controller/src/rpc-service/rpc-service.ts


  async request<Params extends JsonRpcParams, Result extends Json>(
-    jsonRpcRequest: JsonRpcRequest<Params>,
+    // The request object may be frozen and must not be mutated.


We should consider adding this to AbstractRpcService as well. I can do this in a followup.

rekmarks force-pushed the rekm/ejrpc-rewrite-2 branch 3 times, most recently from 8bf6c31 to a345102 Compare November 5, 2025 20:41

This comment was marked as outdated.

Sign in to view

rekmarks force-pushed the rekm/ejrpc-rewrite-2 branch from 1e01c22 to 50e1c81 Compare November 6, 2025 03:27

rekmarks mentioned this pull request Nov 6, 2025

feat: Add context parameter to InternalProvider and JsonRpcServer methods #7061

Merged

3 tasks

Base automatically changed from rekm/jrpce-internal-provider-context to main November 6, 2025 20:38

rekmarks force-pushed the rekm/ejrpc-rewrite-2 branch 2 times, most recently from 7e2d0c0 to 78988ea Compare November 6, 2025 21:27

rekmarks added 16 commits November 6, 2025 13:28

refactor: Rewrite block-cache middleware

069132b

refactor: Rewrite block-ref-rewrite

97711cb

refactor: Rewrite block-ref

7c06f11

refactor: Rewrite block-tracker-inspector

b289e7e

refactor: Rewrite fetch

c0274a7

refactor: Rewrite inflight-cache

3a3883e

feat: Add providerAsMiddlewareV2

17bd319

refactor: Rewrite retryOnEmpty

beb94b4

refactor: Rewrite wallet

1f1c491

refactor: Migrate create-network-client

9292180

refactor: Fix getAccounts

a489225

refactor: Fix most lint exceptions

511fb65

refactor: Fix require-jsdoc violations

97db3ae

refactor: Migrate processTransaction

928ada8

refactor: Migrate process encrypt / decrypt message

b833312

docs: Update changelogs

536ed51

rekmarks force-pushed the rekm/ejrpc-rewrite-2 branch from 78988ea to 536ed51 Compare November 6, 2025 21:28

rekmarks commented Nov 7, 2025

View reviewed changes

packages/network-controller/src/create-network-client.ts Outdated Show resolved Hide resolved

rekmarks added 3 commits November 7, 2025 14:04

refactor: Improve asV2Middleware type

836ca74

Merge branch 'main' into rekm/ejrpc-rewrite-2

fa35ac0

chore: Lint

8a63747

rekmarks commented Nov 8, 2025

View reviewed changes

cursor bot reviewed Nov 8, 2025

View reviewed changes

packages/eth-json-rpc-middleware/src/block-ref-rewrite.ts Show resolved Hide resolved

rekmarks commented Nov 8, 2025

View reviewed changes

refactor: Pass original, frozen request to RpcService

92a672c

cursor bot reviewed Nov 8, 2025

View reviewed changes

packages/eth-json-rpc-middleware/test/util/helpers.ts Show resolved Hide resolved

docs: Document engine migration pitfalls

eb33694

rekmarks force-pushed the rekm/ejrpc-rewrite-2 branch from 3225e4a to eb33694 Compare November 8, 2025 17:31

rekmarks added 2 commits November 8, 2025 15:08

test: Cover more cases in fetch.test.ts

5ec9464

refactor: Simplify condition in fetch.ts

393388c

cursor bot reviewed Nov 8, 2025

View reviewed changes

packages/eth-json-rpc-middleware/src/wallet.ts Show resolved Hide resolved

packages/eth-json-rpc-middleware/src/inflight-cache.ts Show resolved Hide resolved

rekmarks added 2 commits November 8, 2025 15:43

refactor: Asynchronously handle both results and errors in inflight-c…

0339e88

…ache

test: Add providerAsMiddleware error test cases

44a680d

cursor bot reviewed Nov 9, 2025

View reviewed changes

packages/eth-json-rpc-middleware/src/wallet.ts Show resolved Hide resolved

docs: Tweak eth-json-rpc-middleware changelog

ae42d6d

rekmarks mentioned this pull request Nov 9, 2025

Migrate JSON-RPC stack to JsonRpcEngineV2 #6327

Open

6 tasks

jeffsmale90 previously approved these changes Nov 9, 2025

View reviewed changes

Merge branch 'main' into rekm/ejrpc-rewrite-2

eadb735

cursor bot reviewed Nov 10, 2025

View reviewed changes

packages/eth-json-rpc-middleware/src/wallet.ts Show resolved Hide resolved

packages/eth-json-rpc-middleware/src/wallet.ts Show resolved Hide resolved

Merge branch 'main' into rekm/ejrpc-rewrite-2

978395a

rekmarks dismissed jeffsmale90’s stale review via 978395a November 10, 2025 20:25

matthewwalsh0 approved these changes Nov 11, 2025

View reviewed changes

mcmire approved these changes Nov 12, 2025

View reviewed changes

Merge branch 'main' into rekm/ejrpc-rewrite-2

e7a7768

mcmire merged commit c26899a into main Nov 12, 2025
277 of 281 checks passed

mcmire deleted the rekm/ejrpc-rewrite-2 branch November 12, 2025 18:18


		### Changed

		- Rename `OriginalRequest` type to `MessageRequest` and permit string `id` values ([#7065](https://github.com/MetaMask/core/pull/7065))

Uh oh!

refactor!: Migrate eth-json-rpc-middleware to JsonRpcEngineV2 #7065

refactor!: Migrate eth-json-rpc-middleware to JsonRpcEngineV2 #7065

Uh oh!

Conversation

rekmarks commented Nov 5, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

References

Checklist

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

rekmarks Nov 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jeffsmale90 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mcmire left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

refactor!: Migrate `eth-json-rpc-middleware` to `JsonRpcEngineV2` #7065

refactor!: Migrate `eth-json-rpc-middleware` to `JsonRpcEngineV2` #7065

rekmarks commented Nov 5, 2025 •

edited by cursor bot

Loading

rekmarks Nov 8, 2025 •

edited

Loading