docs(multichain-api-middleware): add wallet-side Multichain API reference#9258
Open
adonesky1 wants to merge 11 commits into
Open
docs(multichain-api-middleware): add wallet-side Multichain API reference#9258adonesky1 wants to merge 11 commits into
adonesky1 wants to merge 11 commits into
Conversation
…ence Adds MULTICHAIN_API.md, a readable reference for the CAIP-25 / CAIP-27 Multichain API as actually implemented by this package and @metamask/chain-agnostic-permission: wallet_createSession inputs/outputs, the other session methods, supported methods per namespace (static EVM vs Snap-resolved non-EVM), sessionProperties allowlist (incl. the eip1193-compatible flow), error codes, and divergences from the current upstream CAIP-25 spec. Links it from the package README.
- wallet_createSession: note that at least one of requiredScopes / optionalScopes must resolve to a supported scope (neither -> 5100). - Remove the standalone "eip1193-compatible session property" section; the allowlist table entry and version note cover it without the extra depth.
- Split error table into codes actually thrown (5100, 5302, 4100) vs codes defined-but-not-returned by the handler: - 5101/5102 are filtered out during scope bucketing, not rejected - 5201/5202 are a TODO and never thrown - 5300/5301 are schema-only; the handler never reads scopedProperties - Fix divergence row claiming scopedProperties "errors 5300/5301" — the field is accepted and ignored; note this in Concepts too. - Clarify partial-revoke is middleware (not extension-specific) behavior. - Soften the eip1193-compatible claim: migration 211 backfills it onto pre-existing eip155 connections, so older Multichain-only sessions may carry it. - Fix CAIP-25 date attribution for the optionalScopes->scopes rename (2025-07-30).
Remove scopedProperties from Concepts/intro (it's not actually implemented) and add a dedicated bottom section explaining it was partially implemented for EIP-3085, deprioritized, and has since been removed from the request in upstream CAIP-25 (scopedProperties -> capabilities -> dropped). Update the divergence row accordingly.
- Remove the standalone scopedProperties section and fold it into the divergence-table row. - Apply repo oxfmt formatting (table alignment, jsonc trailing commas).
- Remove the eip1193-compatible version note and the 5100 wording note. - Condense the "defined but not thrown" error table to a single sentence (keep signal: callers shouldn't expect those codes on the wire). - Replace em dashes with colons/semicolons/parentheses throughout; oxfmt.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Explanation
@metamask/multichain-api-middlewareis the implementation of MetaMask's CAIP-25 / CAIP-27 Multichain API, but it has had no prose documentation — only a stub README pointing at MIP-5. The machine-readable OpenRPC schema (@metamask/api-specs) is the source of truth but isn't easy to read, and upstream CAIP-25 has since diverged from what we implement.This adds
MULTICHAIN_API.md, a readable wallet-side reference, and links it from the package README.It covers:
wallet_createSessioninputs/outputs (params, result shape, examples, behavior), pluswallet_getSession,wallet_revokeSession,wallet_invokeMethod, and thewallet_sessionChanged/wallet_notifynotifications.@metamask/chain-agnostic-permission/@metamask/api-specs) vs. Snap-resolved non-EVM methods (viaMultichainRoutingService.getSupportedMethods= account-Snap ∪ protocol-Snap methods).sessionPropertiesallowlist, including a full walkthrough of theeip1193-compatibleflow (set byconnect-evm/ injected EIP-1193 middleware, gates the EVM network picker, backfilled by extension migration 211) and the 1.6.0 allowlist addition.scopes,properties/capabilitiesrenames, bare accounts, chain-only keys,sessionId, etc.).Behavior is described from the handler source; the doc notes that handler code is authoritative where it disagrees with the OpenRPC schema.
References
MetaMask/api-specsandMetaMask/connect-monorepo.Checklist
Note
Low Risk
Documentation-only changes with no production code or API behavior modifications.
Overview
Adds
MULTICHAIN_API.md, a wallet-side JSON-RPC reference for MetaMask’s CAIP-25 / CAIP-27 Multichain API (session methods, notifications, namespace method lists, error codes, MetaMask-specific behavior, and a divergence table vs. current upstream CAIP-25). The doc states that handler code insrc/handlers/*.tsis authoritative when it disagrees with OpenRPC.README.mdgains a Documentation section linking to that file and pointing integrators at@metamask/api-specsfor the machine-readable schema.CHANGELOG.mdrecords the addition under Unreleased.No runtime or handler code changes—documentation only.
Reviewed by Cursor Bugbot for commit fb2ec4a. Bugbot is set up for automated code reviews on this repo. Configure here.