feat: Add Multichain API to @metamask/multichain

[jiexi]

Explanation

This PR updates @metamask/multichain to add method handlers and middleware specific to the new Multichain API and which can be shared across the extension & mobile clients. The package includes implementations for managing multichain sessions, handling multichain RPC methods, and integrating multichain functionalities into the MetaMask extension. Key features of this package include:

• Method Handlers: Implementations of the new RPC method handlers like wallet_createSession, wallet_invokeMethod, wallet_revokeSession, and wallet_getSession.
• ScopesObject Transforms: Adds helpers that transform between NormalizedScopesObject and InternalScopesObject
• Concurrent Eth Subscriptions: Adds helpers that orchestrate eth_subscriptions to numerous chains concurrently

These tools and utilities will be used in both clients (mobile + extension)'s multichain API implementations.

File Overview

• packages/multichain/src/adapters/caip-permission-adapter-middleware.ts: Middleware for the EIP-1193 API that enforces a CAIP-25 permission for each request if that CAIP-25 permission was granted via wallet_createSession
• packages/multichain/src/handlers/wallet-getSession.ts: Handlers for CAIP Multichain lifecycle methods except for wallet_createSession which seemed a little too platform specific to belong in a shared package currently
• packages/multichain/src/middlewares/: Middleware for the Multichain API that helps facilitate concurrent eth subscriptions and for using @metamask/api-specs for method param validation for new CAIP Multichain methods
• packages/multichain/src/scope/authorization.ts: Adds helpers that sort scopes based on if they are currently supported by the wallet (i.e. a network already exists the eip155 scope), if they could be supported by the wallet (i.e. the network does not already exist for the eip155 scope, but the dapp has provided EIP-3085 details for adding the network in the scopedProperties property of the wallet_createSession request), or if they cannot be served.
• packages/multichain/src/scope/filter.ts: provides helpers used for the bucketing above in authorization.ts
• types/@metamask/eth-json-rpc-filters.d.ts: Typedef for missing types in @metamask/eth-json-rpc-filters/subscriptionManager

References

Upstream: #4784
Downstream: None. This is the end.

Key Multichain API Standards implemented here:

• CAIP-25 - wallet_creatSession
• CAIP-27 - wallet_invokeMethod
• CAIP-285 - wallet_revokeSession
• CAIP-311 - wallet_sessionChanged
• CAIP-312 - wallet_getSession

Open PR that uses this new package for exposing the multichain API in the extension: MetaMask/metamask-extension#27782

Changelog

@metamask/multichain

• ADDED: Adds getInternalScopesObject and getSessionScopes helpers for transforming between NormalizedScopesObject and InternalScopesObject.
• ADDED: Adds caipPermissionAdapterMiddleware for enforcing CAIP-25 permission on the EIP-1193 API.
• ADDED: Adds walletGetSession, walletInvokeMethod, and walletRevokeSession handlers.
• ADDED: Adds multichainMethodCallValidatorMiddleware for validating Multichain API method params as defined in @metamask/api-specs.
• ADDED: Adds MultichainMiddlewareManager to multiplex a request to other middleware based on requested scope.
• ADDED: Adds MultichainSubscriptionManager to handle concurrent subscriptions across multiple scopes.
• ADDED: Adds bucketScopes which groups the scopes in a NormalizedScopesObject based on if the scopes are already supported, could be supported, or are not supportable.
• ADDED: Adds getSupportedScopeObjects helper for getting only the supported methods and notifications from each NormalizedScopeObject in a NormalizedScopesObject.

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 highlighted breaking changes using the "BREAKING" category above as appropriate
• I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes

[mcmire]

A lot of my comments were minor. Surprisingly this was easier to review than the extension PR.

That said it wasn't clear to me how the middleware and subscription managers were intended to be used, perhaps it's worth adding some documentation for those or otherwise providing more context? I think that would help me review them better.

[mcmire]

Perhaps a dumb question, but I noticed — both here and in the extension PR — that we are calling end explicitly. Isn't that an optional step in async middleware because it happens implicitly? (i.e. when a middleware throws an error, it ends with that error, otherwise it just ends)

[jiexi]

I didn't really find consistent usage throughout the handler implementations I've seen. Not a dumb question at all! The middleware pipeline is flexible, and maybe it shouldn't be so flexible. Do you have a preferred approach/pattern?

[mcmire]

I think I assumed that handlers would always be used inside of async middleware, because if they were, we would be able to take advantage of the fact that async middleware don't require calling end:

 * Async middleware have no "end" function. Instead, they "end" if they return
 * without calling "next". Rather than passing in explicit return handlers,
 * async middleware can simply await "next", and perform operations on the
 * response object when execution resumes.

Looking back at this, though, I see that 1) handlers aren't middleware themselves and 2) handlers can't assume that they are used inside of async middleware. Maybe when we refactor json-rpc-engine to use async middleware everywhere we can simplify this, but it seems like we have to have the handlers take end and call it manually.

[mcmire]

Above on line 51 we treated methodToCheck as a ContentDescriptorObject, now we treat it as a MethodObject. Which one is it?

[jiexi]

I've updated this to be MethodObject e77e87f