From 79b421d0bc89ec5db6079233bf9819b351b439cc Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 9 Oct 2024 10:50:19 -0700 Subject: [PATCH 01/16] Initial Multichain API docs --- wallet-sidebar.js | 4 + wallet/concepts/convenience-libraries.md | 2 +- wallet/concepts/multichain-api.md | 135 +++++++++++++++++++++ wallet/concepts/signing-methods.md | 2 +- wallet/concepts/smart-contracts.md | 2 +- wallet/concepts/wallet-interoperability.md | 2 +- wallet/reference/multichain-api.md | 8 ++ 7 files changed, 151 insertions(+), 4 deletions(-) create mode 100644 wallet/concepts/multichain-api.md create mode 100644 wallet/reference/multichain-api.md diff --git a/wallet-sidebar.js b/wallet-sidebar.js index d4cf51e5fbe..d9a56bd7cbe 100644 --- a/wallet-sidebar.js +++ b/wallet-sidebar.js @@ -40,6 +40,10 @@ const sidebar = { type: "doc", id: "reference/provider-api", }, + { + type: "doc", + id: "reference/multichain-api", + }, ], }, ], diff --git a/wallet/concepts/convenience-libraries.md b/wallet/concepts/convenience-libraries.md index 596e519d12c..9ef47347d60 100644 --- a/wallet/concepts/convenience-libraries.md +++ b/wallet/concepts/convenience-libraries.md @@ -1,6 +1,6 @@ --- description: Learn about convenience libraries. -sidebar_position: 4 +sidebar_position: 5 --- # Convenience libraries diff --git a/wallet/concepts/multichain-api.md b/wallet/concepts/multichain-api.md new file mode 100644 index 00000000000..95d7e9b3739 --- /dev/null +++ b/wallet/concepts/multichain-api.md @@ -0,0 +1,135 @@ +--- +description: Learn about the MetaMask Multichain API. +sidebar_position: 4 +--- + +# About the Multichain API + +The Multichain API offers a scalable, generalized web3 wallet API that supports simultaneous interactions across multiple chains. +When integrated with [MetaMask Snaps](/snaps), it enables developers to interact with both popular and emerging networks. +By adhering to open standards, the Multichain API encourages broad adoption and development of tooling higher up in the dev stack. + +The Multichain API supports simultaneous multichain interactions, enabling dapps to create smoother, more integrated user experiences. +It addresses key issues, such as: + +- **Network switching** - Current Ethereum wallet APIs are modeled around a single active network. + Developers must switch between networks in order to make multichain calls, which can be unnecessarily complicated. + The Multichain API eliminates switching by allowing direct interactions with different networks. + Dapps can re-imagine their interfaces to optimize multichain UX flows. + +- **Scaling usage of non-EVM networks** - Developers building protocol Snaps struggle to scale developer usage. + The Multichain API integrates with Snaps and offers a more standardized interface to encourage broad adoption. + +- **Error-prone integrations** - Developers are burdened with navigating different wallet APIs and SDKs. + The Multichain API standardizes the interface, making it easier for dapps to integrate with wallets, + discover their capabilities, and negotiate interfaces. + +See the [Multichain API reference](../reference/multichain-api.md). + +## Technical overview + +The Multichain API follows the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) +standard for dapps to interface with multichain wallets. + +## Multichain session lifecycle + +The following is a lifecycle overview of a multichain session without a `sessionId`: + +```mermaid +%%{ + init: { + 'sequence': { + 'actorMargin': 100, + 'width': 275 + } + } +}%% + +sequenceDiagram + actor Caller + participant Wallet + participant WalletDataStore as Data store (Wallet) + + opt Create session + Caller->>Wallet: wallet_createSession + Wallet->>WalletDataStore: Persist session data + Wallet-->>Caller: {"sessionScopes": {...}} + end + + opt Update session + Caller->>Wallet: wallet_createSession (update auth) + Wallet->>WalletDataStore: Update session data + Wallet-->>Caller: {"sessionScopes": {updatedScopes...}} + end + + opt Connection interrupted with wallet-side session modification + Caller-->Wallet: Connection interrupted + Wallet->>WalletDataStore: User initiated session change + Wallet-->Caller: wallet_sessionChanged (attempt fails) + Caller-->Wallet: Connection re-established + end + + opt Get session + Caller->>Wallet: wallet_getSession + Wallet-->>Caller: {"sessionScopes": {...}} + end + + opt Revoke session + Caller->>Wallet: wallet_revokeSession + Wallet->>WalletDataStore: Update session data + Wallet-->>Caller: {"result": "true"} + end +``` + +The following is a lifecycle overview of a multichain session with a `sessionId`: + +```mermaid +%%{ + init: { + 'sequence': { + 'actorMargin': 75, + 'width': 200 + } + } +}%% + +sequenceDiagram + participant CallerDataStore as Data store (Caller) + actor Caller + participant Wallet + participant WalletDataStore as Data store (Wallet) + + opt Create session + Caller->>Wallet: wallet_createSession + Wallet->>WalletDataStore: Persist session data + Wallet-->>Caller: {"sessionId": "0xdeadbeef", "sessionScopes": {...}} + Caller->>CallerDataStore: Persist session data + end + + opt Update session + Caller->>Wallet: wallet_createSession (sessionId: 0xdeadbeef, {updatedScopes...}) + Wallet->>WalletDataStore: Update session data + Wallet-->>Caller: {"sessionId": "0xdeadbeef", "sessionScopes": {(updated)sessionScopes...}} + Caller->>CallerDataStore: Persist session data + end + + opt User initiated session change + Wallet->>WalletDataStore: User initiated session change + Wallet->>Caller: wallet_sessionChanged (sessionId: 0xdeadbeef) + Caller->>CallerDataStore: Update session data + end + + opt Revoke session + Caller->>Wallet: wallet_createSession (sessionId: 0xnewbeef, no scopes) + Wallet->>WalletDataStore: Create new, empty session 0xnewbeef, clear all older sessions with the same dapp + Wallet-->>Caller: {"result": "true"} (session is revoked) + Caller->>CallerDataStore: Clear session data + end + + alt Revoke session (alternate) + Caller->>Wallet: wallet_revokeSession (sessionId: 0xdeadbeef) + Wallet->>WalletDataStore: Update session data + Wallet-->>Caller: {"result": "true"} (session is revoked) + Caller->>CallerDataStore: Update session data + end +``` diff --git a/wallet/concepts/signing-methods.md b/wallet/concepts/signing-methods.md index 4963e2bbd6c..9a8820aafdc 100644 --- a/wallet/concepts/signing-methods.md +++ b/wallet/concepts/signing-methods.md @@ -1,6 +1,6 @@ --- description: Learn about the RPC methods for signing transactions in MetaMask. -sidebar_position: 5 +sidebar_position: 6 --- # Signing methods diff --git a/wallet/concepts/smart-contracts.md b/wallet/concepts/smart-contracts.md index ac431e636ef..470ab928e0b 100644 --- a/wallet/concepts/smart-contracts.md +++ b/wallet/concepts/smart-contracts.md @@ -1,6 +1,6 @@ --- description: Learn about interacting with smart contracts. -sidebar_position: 7 +sidebar_position: 8 --- # Smart contracts diff --git a/wallet/concepts/wallet-interoperability.md b/wallet/concepts/wallet-interoperability.md index 51d4781f715..1236ec87e72 100644 --- a/wallet/concepts/wallet-interoperability.md +++ b/wallet/concepts/wallet-interoperability.md @@ -1,6 +1,6 @@ --- description: Learn about wallet interoperability. -sidebar_position: 6 +sidebar_position: 7 --- # Wallet interoperability diff --git a/wallet/reference/multichain-api.md b/wallet/reference/multichain-api.md new file mode 100644 index 00000000000..32f7482dbb4 --- /dev/null +++ b/wallet/reference/multichain-api.md @@ -0,0 +1,8 @@ +--- +description: See the Multichain API reference. +--- + +# Multichain API + + +Learn more [about the Multichain API](../concepts/multichain-api.md). \ No newline at end of file From f1d72dc24ed2d16fd43d41da8b1c7cd19bfcb0a9 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Fri, 11 Oct 2024 14:17:31 -0700 Subject: [PATCH 02/16] edit content --- wallet-sidebar.js | 2 +- wallet/concepts/multichain-api.md | 114 ++++++++++++---------- wallet/reference/multichain-api-events.md | 88 +++++++++++++++++ wallet/reference/multichain-api.md | 8 -- 4 files changed, 154 insertions(+), 58 deletions(-) create mode 100644 wallet/reference/multichain-api-events.md delete mode 100644 wallet/reference/multichain-api.md diff --git a/wallet-sidebar.js b/wallet-sidebar.js index 37ab1cdb79d..c031d7b69cf 100644 --- a/wallet-sidebar.js +++ b/wallet-sidebar.js @@ -102,7 +102,7 @@ const sidebar = { }, { type: "doc", - id: "reference/multichain-api", + id: "reference/multichain-api-events", }, ], collapsed: false, diff --git a/wallet/concepts/multichain-api.md b/wallet/concepts/multichain-api.md index 95d7e9b3739..43ac9b9dd07 100644 --- a/wallet/concepts/multichain-api.md +++ b/wallet/concepts/multichain-api.md @@ -5,35 +5,51 @@ sidebar_position: 4 # About the Multichain API -The Multichain API offers a scalable, generalized web3 wallet API that supports simultaneous interactions across multiple chains. -When integrated with [MetaMask Snaps](/snaps), it enables developers to interact with both popular and emerging networks. -By adhering to open standards, the Multichain API encourages broad adoption and development of tooling higher up in the dev stack. +:::warning Developer preview +This is a developer preview of the Multichain API. +It is only available in [MetaMask Flask](/snaps/get-started/install-flask). +::: -The Multichain API supports simultaneous multichain interactions, enabling dapps to create smoother, more integrated user experiences. -It addresses key issues, such as: +The Multichain API is a scalable, generalized web3 wallet API that supports simultaneous +interactions across multiple blockchain networks. +When integrated with [MetaMask Snaps](/snaps), it enables developers to interact with both popular +and emerging networks. +Key benefits include: -- **Network switching** - Current Ethereum wallet APIs are modeled around a single active network. - Developers must switch between networks in order to make multichain calls, which can be unnecessarily complicated. - The Multichain API eliminates switching by allowing direct interactions with different networks. - Dapps can re-imagine their interfaces to optimize multichain UX flows. +- **Seamless network interactions** - The Multichain API allows dapps to interact directly with + multiple networks, without having to switch between single active networks. + This enables smooth, integrated multichain user experience flows. -- **Scaling usage of non-EVM networks** - Developers building protocol Snaps struggle to scale developer usage. - The Multichain API integrates with Snaps and offers a more standardized interface to encourage broad adoption. +- **Scaling usage of non-EVM networks** - The Multichain API integrates with + [interoperability Snaps](https://snaps.metamask.io/explore/), providing a standardized interface + to encouraging broader adoption of non-EVM networks. -- **Error-prone integrations** - Developers are burdened with navigating different wallet APIs and SDKs. - The Multichain API standardizes the interface, making it easier for dapps to integrate with wallets, - discover their capabilities, and negotiate interfaces. - -See the [Multichain API reference](../reference/multichain-api.md). +- **Simplified integrations** - The Multichain API reduces the complexity associated with navigating + different wallet APIs and SDKs, making it easier for dapps to integrate with wallets, discover + capabilities, and negotiate interfaces. ## Technical overview The Multichain API follows the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) standard for dapps to interface with multichain wallets. +The API includes a method [`wallet_createSession`](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) +that dapps can call to create a multichain session with a wallet, with specified properties and +authorization scopes. +The session can be created with or without a `sessionId`, and can be updated using the same method +`wallet_createSession`. + +Dapps can use the method [`wallet_invokeMethod`](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-27.md) +to call a subset of the [Wallet JSON-RPC API methods](/wallet/reference/json-rpc-api) on a specified chain. +Dapps can use [`wallet_getSession`](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-312.md) +to get the scope of the current session, and +[`wallet_revokeSession`](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-285.md) to +revoke the current session. +The API also supports [events](../reference/multichain-api-events.md), allowing wallets to notify +dapps of changes to a session. -## Multichain session lifecycle +The following sequence diagrams illustrate the multichain session lifecycle without and with a `sessionId`. -The following is a lifecycle overview of a multichain session without a `sessionId`: +### Lifecycle without a `sessionId` ```mermaid %%{ @@ -46,42 +62,42 @@ The following is a lifecycle overview of a multichain session without a `session }%% sequenceDiagram - actor Caller + participant Dapp participant Wallet - participant WalletDataStore as Data store (Wallet) + participant WalletDataStore as Wallet data store opt Create session - Caller->>Wallet: wallet_createSession + Dapp->>Wallet: wallet_createSession Wallet->>WalletDataStore: Persist session data - Wallet-->>Caller: {"sessionScopes": {...}} + Wallet-->>Dapp: {"sessionScopes": {...}} end opt Update session - Caller->>Wallet: wallet_createSession (update auth) + Dapp->>Wallet: wallet_createSession (update auth) Wallet->>WalletDataStore: Update session data - Wallet-->>Caller: {"sessionScopes": {updatedScopes...}} + Wallet-->>Dapp: {"sessionScopes": {updatedScopes...}} end opt Connection interrupted with wallet-side session modification - Caller-->Wallet: Connection interrupted + Dapp-->>Wallet: Connection interrupted Wallet->>WalletDataStore: User initiated session change - Wallet-->Caller: wallet_sessionChanged (attempt fails) - Caller-->Wallet: Connection re-established + Wallet-->>Dapp: wallet_sessionChanged (attempt fails) + Dapp-->>Wallet: Connection re-established end opt Get session - Caller->>Wallet: wallet_getSession - Wallet-->>Caller: {"sessionScopes": {...}} + Dapp->>Wallet: wallet_getSession + Wallet-->>Dapp: {"sessionScopes": {...}} end opt Revoke session - Caller->>Wallet: wallet_revokeSession + Dapp->>Wallet: wallet_revokeSession Wallet->>WalletDataStore: Update session data - Wallet-->>Caller: {"result": "true"} + Wallet-->>Dapp: {"result": "true"} end ``` -The following is a lifecycle overview of a multichain session with a `sessionId`: +### Lifecycle with a `sessionId` ```mermaid %%{ @@ -94,42 +110,42 @@ The following is a lifecycle overview of a multichain session with a `sessionId` }%% sequenceDiagram - participant CallerDataStore as Data store (Caller) - actor Caller + participant DappDataStore as Dapp data store + participant Dapp participant Wallet - participant WalletDataStore as Data store (Wallet) + participant WalletDataStore as Wallet data store opt Create session - Caller->>Wallet: wallet_createSession + Dapp->>Wallet: wallet_createSession Wallet->>WalletDataStore: Persist session data - Wallet-->>Caller: {"sessionId": "0xdeadbeef", "sessionScopes": {...}} - Caller->>CallerDataStore: Persist session data + Wallet-->>Dapp: {"sessionId": "0xdeadbeef", "sessionScopes": {...}} + Dapp->>DappDataStore: Persist session data end opt Update session - Caller->>Wallet: wallet_createSession (sessionId: 0xdeadbeef, {updatedScopes...}) + Dapp->>Wallet: wallet_createSession (sessionId: 0xdeadbeef, {updatedScopes...}) Wallet->>WalletDataStore: Update session data - Wallet-->>Caller: {"sessionId": "0xdeadbeef", "sessionScopes": {(updated)sessionScopes...}} - Caller->>CallerDataStore: Persist session data + Wallet-->>Dapp: {"sessionId": "0xdeadbeef", "sessionScopes": {(updated)sessionScopes...}} + Dapp->>DappDataStore: Persist session data end opt User initiated session change Wallet->>WalletDataStore: User initiated session change - Wallet->>Caller: wallet_sessionChanged (sessionId: 0xdeadbeef) - Caller->>CallerDataStore: Update session data + Wallet-->>Dapp: wallet_sessionChanged (sessionId: 0xdeadbeef) + Dapp->>DappDataStore: Update session data end opt Revoke session - Caller->>Wallet: wallet_createSession (sessionId: 0xnewbeef, no scopes) + Dapp->>Wallet: wallet_createSession (sessionId: 0xnewbeef, no scopes) Wallet->>WalletDataStore: Create new, empty session 0xnewbeef, clear all older sessions with the same dapp - Wallet-->>Caller: {"result": "true"} (session is revoked) - Caller->>CallerDataStore: Clear session data + Wallet-->>Dapp: {"result": "true"} (session is revoked) + Dapp->>DappDataStore: Clear session data end alt Revoke session (alternate) - Caller->>Wallet: wallet_revokeSession (sessionId: 0xdeadbeef) + Dapp->>Wallet: wallet_revokeSession (sessionId: 0xdeadbeef) Wallet->>WalletDataStore: Update session data - Wallet-->>Caller: {"result": "true"} (session is revoked) - Caller->>CallerDataStore: Update session data + Wallet-->>Dapp: {"result": "true"} (session is revoked) + Dapp->>DappDataStore: Update session data end ``` diff --git a/wallet/reference/multichain-api-events.md b/wallet/reference/multichain-api-events.md new file mode 100644 index 00000000000..de03e9cb4d5 --- /dev/null +++ b/wallet/reference/multichain-api-events.md @@ -0,0 +1,88 @@ +--- +description: See the Multichain API events reference. +toc_max_heading_level: 2 +--- + +# Multichain API events + +:::warning Developer preview +This is a developer preview of the Multichain API. +It is only available in [MetaMask Flask](/snaps/get-started/install-flask). +::: + +The Multichain API provides events that wallets can send to dapps to notify them of changes to a +[CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) session. +Learn more [about the Multichain API](../concepts/multichain-api.md). + +## `wallet_notify` + +Notifies the dapp of events or state changes related to a specific, previously-authorized network. +Specified by [CAIP-319](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-319.md). + +### Parameters + +- `sessionId`: `string` - (Optional) - The session identifier. +- `scope`: `string` - A valid [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain ID previously authorized to the dapp within a session. +- `notification`: `object` - A notification object containing: + - `method`: `string` - A [JSON-RPC API](/wallet/reference/json-rpc-api) notification method name + previously authorized to the dapp within a session. + - `params`: `object` - The RPC notification method parameters. + +### Example + +```json +{ + "jsonrpc": "2.0", + "method": "wallet_notify", + "params": { + "sessionId": "0xdeadbeef", + "scope": "eip155:1", + "notification": { + "method": "eth_subscription", + "params": { + "subscription": "0x12345678", + "result": { + "blockNumber": "0x1234", + "transactionHash": "0x5678", + "logIndex": "0x9abc" + } + } + } + } +} +``` + +## `wallet_sessionChanged` + +Notifies the dapp of updates to a shared session's authorization scopes. +Specified by [CAIP-311](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-311.md). + +### Parameters + +- `sessionId`: `string` - (Optional) The session identifier. +- `sessionScopes`: `object` - An object containing the full updated session scopes, each formatted + according to [CAIP-217](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-217.md). + +### Example + +```json +{ + "jsonrpc": "2.0", + "method": "wallet_sessionChanged", + "params": { + "sessionScopes": { + "eip155:1": { + "methods": ["eth_signTransaction", "eth_sendTransaction"], + "notifications": ["accountsChanged"], + "accounts": ["eip155:1:0xabc123"] + }, + "eip155:137": { + "methods": ["eth_sendTransaction"], + "notifications": [], + "accounts": ["eip155:137:0xdef456"] + } + } + } +} +``` \ No newline at end of file diff --git a/wallet/reference/multichain-api.md b/wallet/reference/multichain-api.md deleted file mode 100644 index 32f7482dbb4..00000000000 --- a/wallet/reference/multichain-api.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -description: See the Multichain API reference. ---- - -# Multichain API - - -Learn more [about the Multichain API](../concepts/multichain-api.md). \ No newline at end of file From d06c36f60517610f51cf156ac2a1f96996e05d7a Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Tue, 15 Oct 2024 10:03:43 -0700 Subject: [PATCH 03/16] fix typo --- wallet/concepts/multichain-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wallet/concepts/multichain-api.md b/wallet/concepts/multichain-api.md index 43ac9b9dd07..71a6424ad2b 100644 --- a/wallet/concepts/multichain-api.md +++ b/wallet/concepts/multichain-api.md @@ -22,7 +22,7 @@ Key benefits include: - **Scaling usage of non-EVM networks** - The Multichain API integrates with [interoperability Snaps](https://snaps.metamask.io/explore/), providing a standardized interface - to encouraging broader adoption of non-EVM networks. + to encourage broader adoption of non-EVM networks. - **Simplified integrations** - The Multichain API reduces the complexity associated with navigating different wallet APIs and SDKs, making it easier for dapps to integrate with wallets, discover From f984b7d44c584fbf358943fc80e4e3b4d368c07b Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Tue, 22 Oct 2024 15:12:26 -0700 Subject: [PATCH 04/16] edits --- docusaurus.config.js | 14 + wallet-sidebar.js | 2 +- wallet/concepts/multichain-api.md | 86 +---- wallet/reference/multichain-api-events.md | 88 ----- wallet/reference/multichain-api.md | 386 ++++++++++++++++++++++ 5 files changed, 418 insertions(+), 158 deletions(-) delete mode 100644 wallet/reference/multichain-api-events.md create mode 100644 wallet/reference/multichain-api.md diff --git a/docusaurus.config.js b/docusaurus.config.js index a63e234c787..9c147415b56 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -69,6 +69,20 @@ const config = { routeBasePath: "wallet", sidebarPath: require.resolve("./wallet-sidebar.js"), breadcrumbs: false, + admonitions: { + keywords: [ + "info", + "success", + "danger", + "note", + "tip", + "warning", + "important", + "caution", + "security", + "flaskOnly", + ], + }, editUrl: "https://github.com/MetaMask/metamask-docs/edit/main/", remarkPlugins: [ [ diff --git a/wallet-sidebar.js b/wallet-sidebar.js index 258e55228fe..e8db9ca897f 100644 --- a/wallet-sidebar.js +++ b/wallet-sidebar.js @@ -108,7 +108,7 @@ const sidebar = { }, { type: "doc", - id: "reference/multichain-api-events", + id: "reference/multichain-api", }, ], collapsed: false, diff --git a/wallet/concepts/multichain-api.md b/wallet/concepts/multichain-api.md index 71a6424ad2b..7a6deff97b6 100644 --- a/wallet/concepts/multichain-api.md +++ b/wallet/concepts/multichain-api.md @@ -1,13 +1,13 @@ --- description: Learn about the MetaMask Multichain API. sidebar_position: 4 +sidebar_custom_props: + flask_only: true --- # About the Multichain API -:::warning Developer preview -This is a developer preview of the Multichain API. -It is only available in [MetaMask Flask](/snaps/get-started/install-flask). +:::flaskOnly ::: The Multichain API is a scalable, generalized web3 wallet API that supports simultaneous @@ -32,24 +32,25 @@ Key benefits include: The Multichain API follows the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) standard for dapps to interface with multichain wallets. -The API includes a method [`wallet_createSession`](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) +The API includes a method [`wallet_createSession`](../reference/multichain-api.md#wallet_createsession) that dapps can call to create a multichain session with a wallet, with specified properties and authorization scopes. -The session can be created with or without a `sessionId`, and can be updated using the same method -`wallet_createSession`. +Dapps can update the session using the same method `wallet_createSession`. -Dapps can use the method [`wallet_invokeMethod`](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-27.md) -to call a subset of the [Wallet JSON-RPC API methods](/wallet/reference/json-rpc-api) on a specified chain. -Dapps can use [`wallet_getSession`](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-312.md) -to get the scope of the current session, and -[`wallet_revokeSession`](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-285.md) to -revoke the current session. -The API also supports [events](../reference/multichain-api-events.md), allowing wallets to notify -dapps of changes to a session. +Dapps can use [`wallet_invokeMethod`](../reference/multichain-api.md#wallet_invokemethod) to call a +subset of the [Wallet JSON-RPC API methods](/wallet/reference/json-rpc-api) on a specified chain. +Dapps can use [`wallet_getSession`](../reference/multichain-api.md#wallet_getsession) to get the +scopes and properties of the active session, and use [`wallet_revokeSession`](../reference/multichain-api.md#wallet_revokesession) +to revoke the session. +The API also supports the [`wallet_notify`](../reference/multichain-api.md#wallet_notify) and +[`wallet_sessionChanged`](../reference/multichain-api.md#wallet_sessionchanged) events, allowing +wallets to notify dapps of changes to the session. -The following sequence diagrams illustrate the multichain session lifecycle without and with a `sessionId`. +See the [Multichain API reference](../reference/multichain-api.md) for full details. -### Lifecycle without a `sessionId` +### Lifecycle diagram + +The following sequence diagram illustrates the multichain session lifecycle. ```mermaid %%{ @@ -96,56 +97,3 @@ sequenceDiagram Wallet-->>Dapp: {"result": "true"} end ``` - -### Lifecycle with a `sessionId` - -```mermaid -%%{ - init: { - 'sequence': { - 'actorMargin': 75, - 'width': 200 - } - } -}%% - -sequenceDiagram - participant DappDataStore as Dapp data store - participant Dapp - participant Wallet - participant WalletDataStore as Wallet data store - - opt Create session - Dapp->>Wallet: wallet_createSession - Wallet->>WalletDataStore: Persist session data - Wallet-->>Dapp: {"sessionId": "0xdeadbeef", "sessionScopes": {...}} - Dapp->>DappDataStore: Persist session data - end - - opt Update session - Dapp->>Wallet: wallet_createSession (sessionId: 0xdeadbeef, {updatedScopes...}) - Wallet->>WalletDataStore: Update session data - Wallet-->>Dapp: {"sessionId": "0xdeadbeef", "sessionScopes": {(updated)sessionScopes...}} - Dapp->>DappDataStore: Persist session data - end - - opt User initiated session change - Wallet->>WalletDataStore: User initiated session change - Wallet-->>Dapp: wallet_sessionChanged (sessionId: 0xdeadbeef) - Dapp->>DappDataStore: Update session data - end - - opt Revoke session - Dapp->>Wallet: wallet_createSession (sessionId: 0xnewbeef, no scopes) - Wallet->>WalletDataStore: Create new, empty session 0xnewbeef, clear all older sessions with the same dapp - Wallet-->>Dapp: {"result": "true"} (session is revoked) - Dapp->>DappDataStore: Clear session data - end - - alt Revoke session (alternate) - Dapp->>Wallet: wallet_revokeSession (sessionId: 0xdeadbeef) - Wallet->>WalletDataStore: Update session data - Wallet-->>Dapp: {"result": "true"} (session is revoked) - Dapp->>DappDataStore: Update session data - end -``` diff --git a/wallet/reference/multichain-api-events.md b/wallet/reference/multichain-api-events.md deleted file mode 100644 index de03e9cb4d5..00000000000 --- a/wallet/reference/multichain-api-events.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -description: See the Multichain API events reference. -toc_max_heading_level: 2 ---- - -# Multichain API events - -:::warning Developer preview -This is a developer preview of the Multichain API. -It is only available in [MetaMask Flask](/snaps/get-started/install-flask). -::: - -The Multichain API provides events that wallets can send to dapps to notify them of changes to a -[CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) session. -Learn more [about the Multichain API](../concepts/multichain-api.md). - -## `wallet_notify` - -Notifies the dapp of events or state changes related to a specific, previously-authorized network. -Specified by [CAIP-319](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-319.md). - -### Parameters - -- `sessionId`: `string` - (Optional) - The session identifier. -- `scope`: `string` - A valid [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) - chain ID previously authorized to the dapp within a session. -- `notification`: `object` - A notification object containing: - - `method`: `string` - A [JSON-RPC API](/wallet/reference/json-rpc-api) notification method name - previously authorized to the dapp within a session. - - `params`: `object` - The RPC notification method parameters. - -### Example - -```json -{ - "jsonrpc": "2.0", - "method": "wallet_notify", - "params": { - "sessionId": "0xdeadbeef", - "scope": "eip155:1", - "notification": { - "method": "eth_subscription", - "params": { - "subscription": "0x12345678", - "result": { - "blockNumber": "0x1234", - "transactionHash": "0x5678", - "logIndex": "0x9abc" - } - } - } - } -} -``` - -## `wallet_sessionChanged` - -Notifies the dapp of updates to a shared session's authorization scopes. -Specified by [CAIP-311](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-311.md). - -### Parameters - -- `sessionId`: `string` - (Optional) The session identifier. -- `sessionScopes`: `object` - An object containing the full updated session scopes, each formatted - according to [CAIP-217](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-217.md). - -### Example - -```json -{ - "jsonrpc": "2.0", - "method": "wallet_sessionChanged", - "params": { - "sessionScopes": { - "eip155:1": { - "methods": ["eth_signTransaction", "eth_sendTransaction"], - "notifications": ["accountsChanged"], - "accounts": ["eip155:1:0xabc123"] - }, - "eip155:137": { - "methods": ["eth_sendTransaction"], - "notifications": [], - "accounts": ["eip155:137:0xdef456"] - } - } - } -} -``` \ No newline at end of file diff --git a/wallet/reference/multichain-api.md b/wallet/reference/multichain-api.md new file mode 100644 index 00000000000..dfb72069e07 --- /dev/null +++ b/wallet/reference/multichain-api.md @@ -0,0 +1,386 @@ +--- +description: See the Multichain API reference. +sidebar_custom_props: + flask_only: true +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Multichain API + +:::flaskOnly +::: + +Dapps can call Multichain API [methods](#methods) to create and manage +[CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) sessions with MetaMask. +The API also provides [events](#events) that wallets can send to dapps to notify them of changes to +a session. + +Learn more [about the Multichain API](../concepts/multichain-api.md). + +## Methods + +### `wallet_createSession` + +Creates a multichain session with a wallet, authorizing that wallet with the specified set of scopes +and properties. +This method is defined in [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md). + +#### Parameters + +- `optionalScopes`: `object` - Scopes that the wallet can support in order to be used with this dapp. +- `sessionProperties`: `object` - Properties that the wallet can use to determine if the session is valid. +- `requiredScopes`: `object` - (Optional) Scopes that the wallet must support in order to be used + with this dapp. + We don't recommend using `requiredScopes` with MetaMask. + +#### Returns + +The scopes and properties of the created session. + +#### Example + + + + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "method": "wallet_createSession", + "params": { + "optionalScopes": { + "eip155": { + "references": ["1", "137"], + "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "get_balance", "personal_sign"], + "notifications": ["accountsChanged", "chainChanged"] + }, + "eip155:10": { + "methods": ["get_balance"], + "notifications": ["accountsChanged", "chainChanged"] + }, + "eip155:0": { + "methods": ["wallet_getPermissions", "wallet_creds_store", "wallet_creds_verify", "wallet_creds_issue", "wallet_creds_present"], + "notifications": [] + }, + "eip155:42161": { + "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "personal_sign"], + "notifications": ["accountsChanged", "chainChanged"] + } + }, + "sessionProperties": { + "expiry": "2022-12-24T17:07:31+00:00", + "caip154-mandatory": "true" + } + } +} +``` + + + + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "sessionScopes": { + "eip155": { + "references": ["1", "137"], + "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "eth_sign", "personal_sign"], + "notifications": ["accountsChanged", "chainChanged"], + "accounts": ["eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb", "eip155:137:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"] + }, + "eip155:10": { + "methods": ["get_balance"], + "notifications": ["accountsChanged", "chainChanged"], + "accounts": [] + }, + "eip155:42161": { + "methods": ["personal_sign"], + "notifications": ["accountsChanged", "chainChanged"], + "accounts": ["eip155:42161:0x0910e12C68d02B561a34569E1367c9AAb42bd810"], + "rpcDocuments": "https://example.com/wallet_extension.json" + }, + "eip155:0": { + "methods": ["wallet_getPermissions", "wallet_creds_store", "wallet_creds_verify", "wallet_creds_issue", "wallet_creds_present"], + "notifications": [] + } + }, + "sessionProperties": { + "expiry": "2022-11-31T17:07:31+00:00", + "globalConfig": { + "foo": "bar" + } + } + } +} +``` + + + + +### `wallet_getSession` + +Gets the scopes and properties within the active session. +This method is defined in [CAIP-312](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-312.md). + +:::note +MetaMask doesn't support session IDs. +::: + +#### Parameters + +None. + +#### Returns + +The scopes and properties of the session. + +#### Example + + + + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "method": "wallet_getSession", + "params": {} +} +``` + + + + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "sessionScopes": { + "eip155:1": { + "methods": ["eth_signTransaction"], + "notifications": ["accountsChanged"], + "accounts": ["eip155:1:0xabc123"] + }, + "eip155:137": { + "methods": ["eth_sendTransaction"], + "notifications": ["chainChanged"], + "accounts": ["eip155:137:0xdef456"] + }, + "solana:4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZ": { + "methods": ["getBalance", "getAccountInfo", "sendTransaction", "getBlock"], + "notifications": [], + "accounts": ["solana:4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZ:4Nd1mS8AUwK3kU3gdiAM6QCvqhA7Do8rKtMXsGyqrJxy"] + } + } + } +} +``` + + + + +### `wallet_invokeMethod` + +Invokes the specified [JSON-RPC API](/wallet/reference/json-rpc-api) method on the specified network +previously authorized to the dapp within a session. +This method is defined in [CAIP-27](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-27.md). + +:::note +MetaMask doesn't support session IDs. +::: + +#### Parameters + +- `scope`: `string` - A [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain ID previously authorized to the dapp within a session. +- `request`: `object` - A request object containing: + - `method`: `string` - The [JSON-RPC API](/wallet/reference/json-rpc-api) method to invoke, + previously authorized to the dapp within a session. + - `params`: `object` - The RPC method parameters (can be empty). + +#### Returns + +The response from the JSON-RPC method call. + +#### Example + + + + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "method": "wallet_invokeMethod", + "params": { + "scope": "eip155:1", + "request": { + "method": "eth_sendTransaction", + "params": [ + { + "to": "0x4B0897b0513FdBeEc7C469D9aF4fA6C0752aBea7", + "from": "0xDeaDbeefdEAdbeefdEadbEEFdeadbeefDEADbEEF", + "gas": "0x76c0", + "value": "0x8ac7230489e80000", + "data": "0x", + "gasPrice": "0x4a817c800" + } + ] + } + } +} +``` + + + + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "scope": "eip155:1", + "result": { + "method": "eth_sendTransaction", + "result": "0x4e306b5a5a37532e1734503f7d2427a86f2c992fbe471f5be403b9f734e667c8" + } + } +} +``` + + + + +### `wallet_revokeSession` + +Revokes the active session. +This method is defined in [CAIP-285](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-285.md). + +:::note +MetaMask doesn't support session IDs. +::: + +#### Parameters + +None. + +#### Returns + +`true` if the revocation was successful. + +#### Example + + + + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "method": "wallet_revokeSession", + "params": {} +} +``` + + + + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "result": true +} +``` + + + + +## Events + +The Multichain API provides the following events that wallets can send to dapps to notify them of +changes to a session. + +### `wallet_notify` + +Notifies the dapp of events or state changes related to a specific, previously-authorized network. +This event is defined in [CAIP-319](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-319.md). + +:::note +MetaMask doesn't support session IDs. +::: + +#### Parameters + +- `scope`: `string` - A [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain ID previously authorized to the dapp within a session. +- `notification`: `object` - A notification object containing: + - `method`: `string` - A [JSON-RPC API](/wallet/reference/json-rpc-api) notification method name + previously authorized to the dapp within a session. + - `params`: `object` - The RPC notification method parameters. + +#### Example + +```json +{ + "jsonrpc": "2.0", + "method": "wallet_notify", + "params": { + "sessionId": "0xdeadbeef", + "scope": "eip155:1", + "notification": { + "method": "eth_subscription", + "params": { + "subscription": "0x12345678", + "result": { + "blockNumber": "0x1234", + "transactionHash": "0x5678", + "logIndex": "0x9abc" + } + } + } + } +} +``` + +### `wallet_sessionChanged` + +Notifies the dapp of updates to the active session's authorization scopes. +This method is defined in [CAIP-311](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-311.md). + +:::note +MetaMask doesn't support session IDs. +::: + +#### Parameters + +`sessionScopes`: `object` - An object containing the full updated session scopes, each formatted +according to [CAIP-217](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-217.md). + +#### Example + +```json +{ + "jsonrpc": "2.0", + "method": "wallet_sessionChanged", + "params": { + "sessionScopes": { + "eip155:1": { + "methods": ["eth_signTransaction", "eth_sendTransaction"], + "notifications": ["accountsChanged"], + "accounts": ["eip155:1:0xabc123"] + }, + "eip155:137": { + "methods": ["eth_sendTransaction"], + "notifications": [], + "accounts": ["eip155:137:0xdef456"] + } + } + } +} +``` \ No newline at end of file From f83c96f65af673f97624b681bd5bddd1bfeb6d22 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 30 Oct 2024 18:57:26 -0700 Subject: [PATCH 05/16] fixes --- wallet-sidebar.js | 5 +++++ wallet/reference/multichain-api.md | 3 +-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/wallet-sidebar.js b/wallet-sidebar.js index 5fafea3dc43..a59f95637ca 100644 --- a/wallet-sidebar.js +++ b/wallet-sidebar.js @@ -369,6 +369,11 @@ const sidebar = { label: "About the Wallet API", id: "concepts/wallet-api" }, + { + type: "doc", + label: "About the Multichain API", + id: "concepts/multichain-api" + }, { type: "doc", label: "SDK connections", diff --git a/wallet/reference/multichain-api.md b/wallet/reference/multichain-api.md index dfb72069e07..1418e457c13 100644 --- a/wallet/reference/multichain-api.md +++ b/wallet/reference/multichain-api.md @@ -331,7 +331,6 @@ MetaMask doesn't support session IDs. "jsonrpc": "2.0", "method": "wallet_notify", "params": { - "sessionId": "0xdeadbeef", "scope": "eip155:1", "notification": { "method": "eth_subscription", @@ -372,7 +371,7 @@ according to [CAIP-217](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/c "sessionScopes": { "eip155:1": { "methods": ["eth_signTransaction", "eth_sendTransaction"], - "notifications": ["accountsChanged"], + "notifications": ["message"], "accounts": ["eip155:1:0xabc123"] }, "eip155:137": { From e7525693e9111099cbd8f80e354ccd99a8d82ccc Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Fri, 8 Nov 2024 14:53:27 -0800 Subject: [PATCH 06/16] add how-to guide and edits --- snaps/get-started/install-flask.md | 13 +- wallet-sidebar.js | 5 + wallet/concepts/multichain-api.md | 36 ++- .../how-to/manage-networks/use-multichain.md | 248 ++++++++++++++++++ wallet/reference/json-rpc-methods/index.md | 2 +- wallet/reference/multichain-api.md | 11 +- 6 files changed, 295 insertions(+), 20 deletions(-) create mode 100644 wallet/how-to/manage-networks/use-multichain.md diff --git a/snaps/get-started/install-flask.md b/snaps/get-started/install-flask.md index 5493aa5639b..7bde83c05ab 100644 --- a/snaps/get-started/install-flask.md +++ b/snaps/get-started/install-flask.md @@ -5,10 +5,9 @@ sidebar_position: 1 # Install MetaMask Flask -To get started building your own Snaps, install the MetaMask Flask browser extension on -[Google Chrome](https://chromewebstore.google.com/detail/metamask-flask-developmen/ljfoeinjpaedjfecbmggjgodbgkmjkjk) -or -[Mozilla Firefox](https://addons.mozilla.org/en-US/firefox/addon/metamask-flask/). +To build your own Snaps or test upcoming MetaMask features, install the MetaMask Flask browser +extension on [Google Chrome](https://chromewebstore.google.com/detail/metamask-flask-developmen/ljfoeinjpaedjfecbmggjgodbgkmjkjk) +or [Mozilla Firefox](https://addons.mozilla.org/en-US/firefox/addon/metamask-flask/). Install Flask in a new browser profile, or disable any existing installed versions of MetaMask before installing Flask. @@ -27,8 +26,10 @@ If you import accounts with funds into Flask, you do so at your own risk. ## About MetaMask Flask MetaMask Flask is an experimental playground that provides developers access to upcoming MetaMask features. -While a small set of audited Snaps are allowlisted in the stable version of the MetaMask browser extension, MetaMask Flask is intended for developers building and testing Snaps locally or from npm. -Also, new Snaps API features are enabled in Flask for testing and developer feedback before they're enabled in MetaMask stable. +While a small set of audited Snaps are allowlisted in the stable version of the MetaMask browser +extension, MetaMask Flask is intended for developers building and testing Snaps locally or from npm. +Also, new MetaMask features are enabled in Flask for testing and developer feedback before they're +enabled in MetaMask stable. These features appear in the documentation with the **Flask** or **FLASK ONLY** tag. You can also view Flask-specific features by looking for the **\[FLASK\]** label in the [MetaMask Extension changelog](https://github.com/MetaMask/metamask-extension/blob/develop/CHANGELOG.md). diff --git a/wallet-sidebar.js b/wallet-sidebar.js index 05545c0901e..c59385e3b7c 100644 --- a/wallet-sidebar.js +++ b/wallet-sidebar.js @@ -158,6 +158,11 @@ const sidebar = { type: "doc", label: "Add a network", id: "how-to/manage-networks/add-network" + }, + { + type: "doc", + label: "Interact with multiple networks", + id: "how-to/manage-networks/use-multichain" } ] }, diff --git a/wallet/concepts/multichain-api.md b/wallet/concepts/multichain-api.md index 7a6deff97b6..09ca1c2212b 100644 --- a/wallet/concepts/multichain-api.md +++ b/wallet/concepts/multichain-api.md @@ -1,6 +1,5 @@ --- -description: Learn about the MetaMask Multichain API. -sidebar_position: 4 +description: Learn about the Multichain API. sidebar_custom_props: flask_only: true --- @@ -28,6 +27,8 @@ Key benefits include: different wallet APIs and SDKs, making it easier for dapps to integrate with wallets, discover capabilities, and negotiate interfaces. +[**Get started using the Multichain API.**](../how-to/manage-networks/use-multichain.md) + ## Technical overview The Multichain API follows the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) @@ -37,14 +38,15 @@ that dapps can call to create a multichain session with a wallet, with specified authorization scopes. Dapps can update the session using the same method `wallet_createSession`. -Dapps can use [`wallet_invokeMethod`](../reference/multichain-api.md#wallet_invokemethod) to call a -subset of the [Wallet JSON-RPC API methods](/wallet/reference/json-rpc-api) on a specified chain. -Dapps can use [`wallet_getSession`](../reference/multichain-api.md#wallet_getsession) to get the -scopes and properties of the active session, and use [`wallet_revokeSession`](../reference/multichain-api.md#wallet_revokesession) -to revoke the session. +Dapps can use [`wallet_invokeMethod`](../reference/multichain-api.md#wallet_invokemethod) to +call a subset of the [Wallet JSON-RPC API methods](../reference/json-rpc-methods/index.md) on +a specified chain. +Dapps can use [`wallet_getSession`](../reference/multichain-api.md#wallet_getsession) to get +the scopes and properties of the active session, and use +[`wallet_revokeSession`](../reference/multichain-api.md#wallet_revokesession) to revoke the session. The API also supports the [`wallet_notify`](../reference/multichain-api.md#wallet_notify) and -[`wallet_sessionChanged`](../reference/multichain-api.md#wallet_sessionchanged) events, allowing -wallets to notify dapps of changes to the session. +[`wallet_sessionChanged`](../reference/multichain-api.md#wallet_sessionchanged) events, +allowing wallets to notify dapps of changes to the session. See the [Multichain API reference](../reference/multichain-api.md) for full details. @@ -97,3 +99,19 @@ sequenceDiagram Wallet-->>Dapp: {"result": "true"} end ``` + +## Backwards compatibility + +When using the Multichain API, your dapp can still interact with the existing +[Wallet Provider API](wallet-api.md#ethereum-provider-api). +However, the Provider API is not optimized for multichain, and we recommend +[starting directly with the Multichain API](../how-to/manage-networks/use-multichain.md) if possible. +The Multichain API is backwards compatible mainly to support dapps that use third-party libraries +with dependencies on the legacy provider. + +## Get started + +Get started with the Multichain API: + +- Learn how to [use the Multichain API](../how-to/manage-networks/use-multichain.md). +- See the [Multichain API reference](../reference/multichain-api.md) for more details. diff --git a/wallet/how-to/manage-networks/use-multichain.md b/wallet/how-to/manage-networks/use-multichain.md new file mode 100644 index 00000000000..2bedf5e6aeb --- /dev/null +++ b/wallet/how-to/manage-networks/use-multichain.md @@ -0,0 +1,248 @@ +--- +description: Use the Multichain API. +toc_max_heading_level: 4 +sidebar_custom_props: + flask_only: true +--- + +# Interact with multiple networks + +:::flaskOnly +::: + +You can use the Multichain API to interact with multiple blockchain networks in MetaMask simultaneously. +The API allows you to target specific chains as part of each method call, eliminating the need to +detect and switch networks before executing signatures and transactions. + +:::note See also +- [About the Multichain API](../../concepts/multichain-api.md) +- [Multichain API reference](../../reference/multichain-api.md) +::: + +## Prerequisites + +[Install MetaMask Flask.](/snaps/get-started/install-flask) + +## Steps + +### 1. Set up your project + +Establish a connection to MetaMask Flask and set up basic message handling using the +[`wallet_notify`](../../reference/multichain-api.md#wallet_notify) event: + +```javascript +// Initialize the connection to Flask. +const EXTENSION_ID = "ljfoeinjpaedjfecbmggjgodbgkmjkjk"; // Replace this with ID of your Flask extension. +const extensionPort = chrome.runtime.connect(EXTENSION_ID) + +// Set up message listener for events. +extensionPort.onMessage.addListener((msg) => { + // Format wallet_notify events to be able to read them later. + if (msg.data.method === "wallet_notify") { + console.log("wallet_notify:", { + scope: msg.data.params.scope, + method: msg.data.params.notification.method, + subscription: msg.data.params.notification.params.subscription, + number: msg.data.params.notification.params.result.number + }) + return; + } + console.log(msg.data) +}) +``` + +Make sure to replace the `EXTENSION_ID` value with the ID of your Flask extension. +You can find this in your browser's extension manager. + +### 2. Manage sessions + +To interact with multiple networks simultaneously, you'll create and manage +[CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) multichain sessions +with MetaMask. + +#### 2.1. Check existing sessions + +Before creating a new session, check if one already exists using the +[`wallet_getSession`](../../reference/multichain-api.md#wallet_getsession) method. +For example: + +```javascript +extensionPort.postMessage({ + type: "caip-x", + data: { + jsonrpc: "2.0", + method: "wallet_getSession", + params: {} + } +}); +``` + +If the result returns an empty `sessionScopes` parameter, then a multichain session is not active +and you must create a new session. + +#### 2.2. Create a new session + +Create a new session using the [`wallet_createSession`](../../reference/multichain-api.md#wallet_createsession) method. +Specify which chains and methods your dapp needs access to, using the `optionalScopes` parameter. +For example: + +```javascript +extensionPort.postMessage({ + type: "caip-x", + data: { + jsonrpc: "2.0", + method: "wallet_createSession", + params: { + optionalScopes: { + "wallet:eip155": { // General Ethereum wallet functions + methods: ["wallet_addEthereumChain"], + notifications: [], + accounts: [] + }, + "eip155:1": { // Ethereum Mainnet + methods: [ + "personal_sign", + "eth_blockNumber", + "eth_gasPrice", + "eth_getBalance", + "eth_getTransactionCount", + "eth_sendTransaction", + "eth_subscribe" + ], + notifications: ["eth_subscription"], + accounts: [] + }, + "eip155:59141": { // Linea Sepolia + methods: [ + "personal_sign", + "eth_blockNumber", + "eth_gasPrice", + "eth_getBalance", + "eth_getTransactionCount", + "eth_sendTransaction", + "eth_subscribe" + ], + notifications: ["eth_subscription"], + accounts: [] + } + } + } + } +}); +``` + +In `optionalScopes`: + +- Request access to networks that your dapp intends to interact with. + If a requested network is not configured by the MetaMask user, you might need to + [add the network](add-network.md). +- For each network, request access to [Wallet API methods](../../reference/json-rpc-methods/index.md) + that your dapp expects to call at any time. + The methods listed in the `sessionScope` of each Multichain API response indicate which wallet + capabilities your dapp can use during the session. + +#### 2.3. Check for session changes + +To ensure your dapp responds appropriately to changes in the wallet session, such as network or +account updates, check for session changes using the +[`wallet_sessionChanged`](../../reference/multichain-api.md#wallet_sessionchanged) event. +Based on the event data, you can determine whether your dapp needs to request additional permissions +using [`wallet_createSession`](../../reference/multichain-api.md#wallet_createsession). + +```javascript +extensionPort.onMessage.addListener((msg) => { + // Check for wallet_sessionChanged events. + if (msg.data.method === "wallet_sessionChanged") { + // Update permissions if required. + } +}); +``` + +### 3. Invoke Wallet API methods + +You can invoke a subset of the [Wallet JSON-RPC API methods](../../reference/json-rpc-methods/index.md) +on a specified chain using the [`wallet_invokeMethod`](../../reference/multichain-api.md#wallet_invokemethod) +Multichain API method. +The following are example Wallet API functionalities that are compatible with the Multichain API. + +#### 3.1. Sign in with Ethereum + +You can implement Sign-In with Ethereum (SIWE) by invoking +[`personal_sign`](/wallet/reference/json-rpc-methods/personal_sign). +For example: + +```javascript +// Specify an account that the signature will be requested for. +const address = "0xAddress"; +const message = `Sign-in request for ${address} at ${new Date().toLocaleString()}`; + +// Invoke the personal_sign Wallet API method. +const sign = await extensionPort.postMessage({ + type: "caip-x", + data: { + "jsonrpc": "2.0", + method: "wallet_invokeMethod", + params: { + scope: "eip155:1", + request: { + method: "personal_sign", + params: [message, address], + } + } + } +}) +``` + +#### 3.2. Check balances + +You can read gas token balances by invoking +[`eth_getBalance`](/wallet/reference/json-rpc-methods/personal_sign). +For example: + +```javascript +extensionPort.postMessage({ + type: "caip-x", + data: { + jsonrpc: "2.0", + method: "wallet_invokeMethod", + params: { + scope: "eip155:1", + request: { + method: "eth_getBalance", + params: ["0xAddress", "latest"], + } + } + } +}); +``` + +#### 3.3. Send transactions + +You can send transactions on a network where the user has sufficient gas, by invoking +[`eth_sendTransaction`](/wallet/reference/json-rpc-methods/eth_sendtransaction). +For example: + +```javascript +return extensionPort.postMessage({ + type: "caip-x", + data: { + jsonrpc: "2.0", + method: "wallet_invokeMethod", + params: { + // Specify a chain ID where the user has sufficient gas. + scope: "eip155:1", + request: { + method: "eth_sendTransaction", + params: [{ + from: "0xFromAccount", + to: "0xToAccount", + value: "0x0", + gasLimit: "0x5028", + maxPriorityFeePerGas: "0x3b9aca00", + maxFeePerGas: "0x2540be400", + }] + } + } + } +}); +``` diff --git a/wallet/reference/json-rpc-methods/index.md b/wallet/reference/json-rpc-methods/index.md index be59b55949a..076a64bd3f8 100644 --- a/wallet/reference/json-rpc-methods/index.md +++ b/wallet/reference/json-rpc-methods/index.md @@ -11,7 +11,7 @@ View the JSON-RPC API methods by selecting a method in the left sidebar. You can Each method may have one or more of the following labels: - **MetaMask** - The functionalities of these methods are specific to MetaMask, and may or may not be supported by other wallets. -- **Restricted** - These methods are restricted and require requesting permission using [wallet_requestPermissions](/wallet/reference/json-rpc-methods/wallet_requestpermissions). +- **Restricted** - These methods are restricted and require requesting permission using [`wallet_requestPermissions`](/wallet/reference/json-rpc-methods/wallet_requestpermissions). - **Mobile** - These methods are only available on MetaMask Mobile. - **Experimental** - These methods are experimental and may be changed in the future. - **Deprecated** - These methods are deprecated and may be removed in the future. diff --git a/wallet/reference/multichain-api.md b/wallet/reference/multichain-api.md index 1418e457c13..d4b884a3568 100644 --- a/wallet/reference/multichain-api.md +++ b/wallet/reference/multichain-api.md @@ -17,7 +17,10 @@ Dapps can call Multichain API [methods](#methods) to create and manage The API also provides [events](#events) that wallets can send to dapps to notify them of changes to a session. -Learn more [about the Multichain API](../concepts/multichain-api.md). +:::note See also +- [About the Multichain API](../concepts/multichain-api.md) +- [Interact with multiple networks](../how-to/manage-networks/use-multichain.md) +::: ## Methods @@ -186,7 +189,7 @@ The scopes and properties of the session. ### `wallet_invokeMethod` -Invokes the specified [JSON-RPC API](/wallet/reference/json-rpc-api) method on the specified network +Invokes the specified [JSON-RPC API](json-rpc-methods/index.md) method on the specified network previously authorized to the dapp within a session. This method is defined in [CAIP-27](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-27.md). @@ -199,7 +202,7 @@ MetaMask doesn't support session IDs. - `scope`: `string` - A [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) chain ID previously authorized to the dapp within a session. - `request`: `object` - A request object containing: - - `method`: `string` - The [JSON-RPC API](/wallet/reference/json-rpc-api) method to invoke, + - `method`: `string` - The [JSON-RPC API](json-rpc-methods/index.md) method to invoke, previously authorized to the dapp within a session. - `params`: `object` - The RPC method parameters (can be empty). @@ -320,7 +323,7 @@ MetaMask doesn't support session IDs. - `scope`: `string` - A [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) chain ID previously authorized to the dapp within a session. - `notification`: `object` - A notification object containing: - - `method`: `string` - A [JSON-RPC API](/wallet/reference/json-rpc-api) notification method name + - `method`: `string` - A [JSON-RPC API](json-rpc-methods/index.md) notification method name previously authorized to the dapp within a session. - `params`: `object` - The RPC notification method parameters. From 9f3c5bab825064c4d7beb536bbaca3f94986a019 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Mon, 11 Nov 2024 16:12:42 -0800 Subject: [PATCH 07/16] minor fix --- wallet/reference/multichain-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wallet/reference/multichain-api.md b/wallet/reference/multichain-api.md index d4b884a3568..48cef0a8540 100644 --- a/wallet/reference/multichain-api.md +++ b/wallet/reference/multichain-api.md @@ -311,7 +311,7 @@ changes to a session. ### `wallet_notify` -Notifies the dapp of events or state changes related to a specific, previously-authorized network. +Notifies the dapp of events or state changes related to a specific, previously authorized network. This event is defined in [CAIP-319](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-319.md). :::note From 1fec541d9a84b2e3716280883eefbfc98e08cc1a Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 13 Nov 2024 15:17:32 -0800 Subject: [PATCH 08/16] Mention multichain tag --- wallet/reference/json-rpc-methods/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/wallet/reference/json-rpc-methods/index.md b/wallet/reference/json-rpc-methods/index.md index 076a64bd3f8..70b4bb0c088 100644 --- a/wallet/reference/json-rpc-methods/index.md +++ b/wallet/reference/json-rpc-methods/index.md @@ -13,6 +13,7 @@ Each method may have one or more of the following labels: - **MetaMask** - The functionalities of these methods are specific to MetaMask, and may or may not be supported by other wallets. - **Restricted** - These methods are restricted and require requesting permission using [`wallet_requestPermissions`](/wallet/reference/json-rpc-methods/wallet_requestpermissions). - **Mobile** - These methods are only available on MetaMask Mobile. +- **Ethereum API** - These are standard Ethereum JSON-RPC API methods. See the [Ethereum wiki](https://ethereum.org/en/#json-rpc-methods) for more information about these methods. +- **Multichain API** - These methods are compatible with the [Multichain API](../multichain-api.md). - **Experimental** - These methods are experimental and may be changed in the future. -- **Deprecated** - These methods are deprecated and may be removed in the future. -- **Ethereum API** - These are standard Ethereum JSON-RPC API methods. See the [Ethereum wiki](https://ethereum.org/en/#json-rpc-methods) for more information about these methods. \ No newline at end of file +- **Deprecated** - These methods are deprecated and may be removed in the future. \ No newline at end of file From 118b9819f0e3e938c5987ff15d4c8f96431f5a13 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 13 Nov 2024 15:23:22 -0800 Subject: [PATCH 09/16] update what's new --- docs/whats-new.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/whats-new.md b/docs/whats-new.md index 3ede0d5e422..63af349d75e 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -11,6 +11,9 @@ of the [MetaMask developer page](https://metamask.io/developer/). ## November 2024 +- Documented Multichain API [guide](/wallet/how-to/manage-networks/use-multichain), + [concept](/wallet/concepts/multichain-api), and [reference](/wallet/reference/multichain-api). + ([#1621](https://github.com/MetaMask/metamask-docs/pull/1621)) - Added tutorial for [creating a simple Starknet dapp](/wallet/how-to/use-non-evm-networks/starknet/create-a-simple-starknet-dapp). ([#1656](https://github.com/MetaMask/metamask-docs/pull/1656)) From 19df4548e4edd9239358887a2209ae6ecf5b27d2 Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> Date: Mon, 25 Nov 2024 11:37:15 -0800 Subject: [PATCH 10/16] Apply suggestions from code review Co-authored-by: Vandan --- wallet/how-to/manage-networks/use-multichain.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/wallet/how-to/manage-networks/use-multichain.md b/wallet/how-to/manage-networks/use-multichain.md index 2bedf5e6aeb..3692a942cbc 100644 --- a/wallet/how-to/manage-networks/use-multichain.md +++ b/wallet/how-to/manage-networks/use-multichain.md @@ -32,7 +32,7 @@ Establish a connection to MetaMask Flask and set up basic message handling using ```javascript // Initialize the connection to Flask. -const EXTENSION_ID = "ljfoeinjpaedjfecbmggjgodbgkmjkjk"; // Replace this with ID of your Flask extension. +const EXTENSION_ID = "ljfoeinjpaedjfecbmggjgodbgkmjkjk"; // Flask extension ID const extensionPort = chrome.runtime.connect(EXTENSION_ID) // Set up message listener for events. @@ -51,8 +51,6 @@ extensionPort.onMessage.addListener((msg) => { }) ``` -Make sure to replace the `EXTENSION_ID` value with the ID of your Flask extension. -You can find this in your browser's extension manager. ### 2. Manage sessions @@ -114,7 +112,7 @@ extensionPort.postMessage({ }, "eip155:59141": { // Linea Sepolia methods: [ - "personal_sign", + "personal_sign", "eth_blockNumber", "eth_gasPrice", "eth_getBalance", @@ -218,7 +216,7 @@ extensionPort.postMessage({ #### 3.3. Send transactions -You can send transactions on a network where the user has sufficient gas, by invoking +You can send transactions on a specific network, by invoking [`eth_sendTransaction`](/wallet/reference/json-rpc-methods/eth_sendtransaction). For example: From 0d39c1b495ab49a4a760a32ce7084d265e712342 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Mon, 25 Nov 2024 12:03:24 -0800 Subject: [PATCH 11/16] address reviewer feedback --- wallet/concepts/multichain-api.md | 35 ++++++++++--------- .../how-to/manage-networks/use-multichain.md | 25 +++++++------ wallet/reference/multichain-api.md | 31 ++++++++-------- 3 files changed, 45 insertions(+), 46 deletions(-) diff --git a/wallet/concepts/multichain-api.md b/wallet/concepts/multichain-api.md index 09ca1c2212b..ae333318b99 100644 --- a/wallet/concepts/multichain-api.md +++ b/wallet/concepts/multichain-api.md @@ -34,25 +34,26 @@ Key benefits include: The Multichain API follows the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) standard for dapps to interface with multichain wallets. The API includes a method [`wallet_createSession`](../reference/multichain-api.md#wallet_createsession) -that dapps can call to create a multichain session with a wallet, with specified properties and +that dapps can call to create a multichain connection with a wallet, with specified properties and authorization scopes. -Dapps can update the session using the same method `wallet_createSession`. +Dapps can update the connection using the same method `wallet_createSession`. Dapps can use [`wallet_invokeMethod`](../reference/multichain-api.md#wallet_invokemethod) to call a subset of the [Wallet JSON-RPC API methods](../reference/json-rpc-methods/index.md) on a specified chain. Dapps can use [`wallet_getSession`](../reference/multichain-api.md#wallet_getsession) to get -the scopes and properties of the active session, and use -[`wallet_revokeSession`](../reference/multichain-api.md#wallet_revokesession) to revoke the session. -The API also supports the [`wallet_notify`](../reference/multichain-api.md#wallet_notify) and -[`wallet_sessionChanged`](../reference/multichain-api.md#wallet_sessionchanged) events, -allowing wallets to notify dapps of changes to the session. +the scopes and properties of the active connection, and use +[`wallet_revokeSession`](../reference/multichain-api.md#wallet_revokesession) to revoke the connection. +The API also supports the following events: + +- [`wallet_notify`](../reference/multichain-api.md#wallet_notify) notifies dapps of onchain events or state changes they previously subscribed to. +- [`wallet_sessionChanged`](../reference/multichain-api.md#wallet_sessionchanged) notifies dapps of changes to the multichain connection. See the [Multichain API reference](../reference/multichain-api.md) for full details. ### Lifecycle diagram -The following sequence diagram illustrates the multichain session lifecycle. +The following sequence diagram illustrates the multichain connection lifecycle. ```mermaid %%{ @@ -69,33 +70,33 @@ sequenceDiagram participant Wallet participant WalletDataStore as Wallet data store - opt Create session + opt Create connection Dapp->>Wallet: wallet_createSession - Wallet->>WalletDataStore: Persist session data + Wallet->>WalletDataStore: Persist connection data Wallet-->>Dapp: {"sessionScopes": {...}} end - opt Update session + opt Update connection Dapp->>Wallet: wallet_createSession (update auth) - Wallet->>WalletDataStore: Update session data + Wallet->>WalletDataStore: Update connection data Wallet-->>Dapp: {"sessionScopes": {updatedScopes...}} end - opt Connection interrupted with wallet-side session modification + opt Connection interrupted with wallet-side modification Dapp-->>Wallet: Connection interrupted - Wallet->>WalletDataStore: User initiated session change + Wallet->>WalletDataStore: User initiated connection change Wallet-->>Dapp: wallet_sessionChanged (attempt fails) Dapp-->>Wallet: Connection re-established end - opt Get session + opt Get connection Dapp->>Wallet: wallet_getSession Wallet-->>Dapp: {"sessionScopes": {...}} end - opt Revoke session + opt Revoke connection Dapp->>Wallet: wallet_revokeSession - Wallet->>WalletDataStore: Update session data + Wallet->>WalletDataStore: Update connection data Wallet-->>Dapp: {"result": "true"} end ``` diff --git a/wallet/how-to/manage-networks/use-multichain.md b/wallet/how-to/manage-networks/use-multichain.md index 3692a942cbc..48ac9d277b1 100644 --- a/wallet/how-to/manage-networks/use-multichain.md +++ b/wallet/how-to/manage-networks/use-multichain.md @@ -51,16 +51,15 @@ extensionPort.onMessage.addListener((msg) => { }) ``` - -### 2. Manage sessions +### 2. Manage multichain connections To interact with multiple networks simultaneously, you'll create and manage -[CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) multichain sessions +[CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) multichain connections with MetaMask. -#### 2.1. Check existing sessions +#### 2.1. Check existing connections -Before creating a new session, check if one already exists using the +Before creating a new connection, check if one already exists using the [`wallet_getSession`](../../reference/multichain-api.md#wallet_getsession) method. For example: @@ -75,12 +74,12 @@ extensionPort.postMessage({ }); ``` -If the result returns an empty `sessionScopes` parameter, then a multichain session is not active -and you must create a new session. +If the result returns an empty `sessionScopes` parameter, then a multichain connection is not active +and you must create a new connection. -#### 2.2. Create a new session +#### 2.2. Create a new connection -Create a new session using the [`wallet_createSession`](../../reference/multichain-api.md#wallet_createsession) method. +Create a new connection using the [`wallet_createSession`](../../reference/multichain-api.md#wallet_createsession) method. Specify which chains and methods your dapp needs access to, using the `optionalScopes` parameter. For example: @@ -137,12 +136,12 @@ In `optionalScopes`: - For each network, request access to [Wallet API methods](../../reference/json-rpc-methods/index.md) that your dapp expects to call at any time. The methods listed in the `sessionScope` of each Multichain API response indicate which wallet - capabilities your dapp can use during the session. + capabilities your dapp can use during the connection. -#### 2.3. Check for session changes +#### 2.3. Check for connection changes -To ensure your dapp responds appropriately to changes in the wallet session, such as network or -account updates, check for session changes using the +To ensure your dapp responds appropriately to changes in the multichain connection, such as network or +account updates, check for connection changes using the [`wallet_sessionChanged`](../../reference/multichain-api.md#wallet_sessionchanged) event. Based on the event data, you can determine whether your dapp needs to request additional permissions using [`wallet_createSession`](../../reference/multichain-api.md#wallet_createsession). diff --git a/wallet/reference/multichain-api.md b/wallet/reference/multichain-api.md index 48cef0a8540..bcd2423db31 100644 --- a/wallet/reference/multichain-api.md +++ b/wallet/reference/multichain-api.md @@ -13,9 +13,8 @@ import TabItem from "@theme/TabItem"; ::: Dapps can call Multichain API [methods](#methods) to create and manage -[CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) sessions with MetaMask. -The API also provides [events](#events) that wallets can send to dapps to notify them of changes to -a session. +[CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) connections with MetaMask. +The API also provides [events](#events) that wallets can send to dapps to notify them of onchain or connection changes. :::note See also - [About the Multichain API](../concepts/multichain-api.md) @@ -26,21 +25,21 @@ a session. ### `wallet_createSession` -Creates a multichain session with a wallet, authorizing that wallet with the specified set of scopes +Creates a multichain connection with a wallet, authorizing that wallet with the specified set of scopes and properties. This method is defined in [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md). #### Parameters - `optionalScopes`: `object` - Scopes that the wallet can support in order to be used with this dapp. -- `sessionProperties`: `object` - Properties that the wallet can use to determine if the session is valid. +- `sessionProperties`: `object` - Properties that the wallet can use to determine if the connection is valid. - `requiredScopes`: `object` - (Optional) Scopes that the wallet must support in order to be used with this dapp. We don't recommend using `requiredScopes` with MetaMask. #### Returns -The scopes and properties of the created session. +The scopes and properties of the created connection. #### Example @@ -126,7 +125,7 @@ The scopes and properties of the created session. ### `wallet_getSession` -Gets the scopes and properties within the active session. +Gets the scopes and properties within the active connection. This method is defined in [CAIP-312](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-312.md). :::note @@ -139,7 +138,7 @@ None. #### Returns -The scopes and properties of the session. +The scopes and properties of the connection. #### Example @@ -190,7 +189,7 @@ The scopes and properties of the session. ### `wallet_invokeMethod` Invokes the specified [JSON-RPC API](json-rpc-methods/index.md) method on the specified network -previously authorized to the dapp within a session. +previously authorized to the dapp within a connection. This method is defined in [CAIP-27](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-27.md). :::note @@ -200,10 +199,10 @@ MetaMask doesn't support session IDs. #### Parameters - `scope`: `string` - A [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) - chain ID previously authorized to the dapp within a session. + chain ID previously authorized to the dapp within a connection. - `request`: `object` - A request object containing: - `method`: `string` - The [JSON-RPC API](json-rpc-methods/index.md) method to invoke, - previously authorized to the dapp within a session. + previously authorized to the dapp within a connection. - `params`: `object` - The RPC method parameters (can be empty). #### Returns @@ -261,7 +260,7 @@ The response from the JSON-RPC method call. ### `wallet_revokeSession` -Revokes the active session. +Revokes the active connection. This method is defined in [CAIP-285](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-285.md). :::note @@ -321,10 +320,10 @@ MetaMask doesn't support session IDs. #### Parameters - `scope`: `string` - A [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) - chain ID previously authorized to the dapp within a session. + chain ID previously authorized to the dapp within a connection. - `notification`: `object` - A notification object containing: - `method`: `string` - A [JSON-RPC API](json-rpc-methods/index.md) notification method name - previously authorized to the dapp within a session. + previously authorized to the dapp within a connection. - `params`: `object` - The RPC notification method parameters. #### Example @@ -352,7 +351,7 @@ MetaMask doesn't support session IDs. ### `wallet_sessionChanged` -Notifies the dapp of updates to the active session's authorization scopes. +Notifies the dapp of updates to the active connection's authorization scopes. This method is defined in [CAIP-311](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-311.md). :::note @@ -361,7 +360,7 @@ MetaMask doesn't support session IDs. #### Parameters -`sessionScopes`: `object` - An object containing the full updated session scopes, each formatted +`sessionScopes`: `object` - An object containing the full updated authorization scopes, each formatted according to [CAIP-217](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-217.md). #### Example From 6397c3d2bca03b539cf9e3c219363abdc16e3279 Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> Date: Wed, 5 Feb 2025 20:00:41 -0800 Subject: [PATCH 12/16] Apply suggestions from code review Co-authored-by: Vandan --- wallet/concepts/multichain-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/wallet/concepts/multichain-api.md b/wallet/concepts/multichain-api.md index ae333318b99..31a49e00851 100644 --- a/wallet/concepts/multichain-api.md +++ b/wallet/concepts/multichain-api.md @@ -104,8 +104,8 @@ sequenceDiagram ## Backwards compatibility When using the Multichain API, your dapp can still interact with the existing -[Wallet Provider API](wallet-api.md#ethereum-provider-api). -However, the Provider API is not optimized for multichain, and we recommend +[Ethereum Provider API](wallet-api.md#ethereum-provider-api). +However, the Ethereum Provider API is not optimized for multichain usage, and we recommend [starting directly with the Multichain API](../how-to/manage-networks/use-multichain.md) if possible. The Multichain API is backwards compatible mainly to support dapps that use third-party libraries with dependencies on the legacy provider. From 7a6a8e0155855834fb9d91d8f43f534f4d8b406e Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Fri, 14 Feb 2025 15:41:18 -0800 Subject: [PATCH 13/16] Update benefits --- wallet/concepts/multichain-api.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/wallet/concepts/multichain-api.md b/wallet/concepts/multichain-api.md index 31a49e00851..ebd631c7c03 100644 --- a/wallet/concepts/multichain-api.md +++ b/wallet/concepts/multichain-api.md @@ -15,17 +15,15 @@ When integrated with [MetaMask Snaps](/snaps), it enables developers to interact and emerging networks. Key benefits include: -- **Seamless network interactions** - The Multichain API allows dapps to interact directly with - multiple networks, without having to switch between single active networks. - This enables smooth, integrated multichain user experience flows. +- **Elimination of chain switching** - The Multichain API allows dapps to interact with multiple EVM networks without having to request chain switches. + This feature significantly reduces development overhead involved with error handling. -- **Scaling usage of non-EVM networks** - The Multichain API integrates with - [interoperability Snaps](https://snaps.metamask.io/explore/), providing a standardized interface - to encourage broader adoption of non-EVM networks. +- **Extensibility** - The Multichain API can be integrated with + [interoperability Snaps](https://snaps.metamask.io/explore/), providing a standards-based interface + to non-EVM networks that can be broadly adopted across ecosystems. -- **Simplified integrations** - The Multichain API reduces the complexity associated with navigating - different wallet APIs and SDKs, making it easier for dapps to integrate with wallets, discover - capabilities, and negotiate interfaces. +- **Seamless multichain UX** - The Multichain API offers improvements over EIP-1193 and [wallet-standard](https://github.com/wallet-standard/wallet-standard) interfaces. + It allows dapps to create unified multichain wallet connection flows, trigger transactions across disparate networks, and clearly interpret chain-specific addresses. [**Get started using the Multichain API.**](../how-to/manage-networks/use-multichain.md) From 8b8828e300076b16fd1912434e685a6ac7cd9bab Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 5 Mar 2025 14:41:21 -0800 Subject: [PATCH 14/16] update scope properties --- wallet/reference/multichain-api.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/wallet/reference/multichain-api.md b/wallet/reference/multichain-api.md index bcd2423db31..946d599694a 100644 --- a/wallet/reference/multichain-api.md +++ b/wallet/reference/multichain-api.md @@ -31,9 +31,19 @@ This method is defined in [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/ #### Parameters -- `optionalScopes`: `object` - Scopes that the wallet can support in order to be used with this dapp. -- `sessionProperties`: `object` - Properties that the wallet can use to determine if the connection is valid. -- `requiredScopes`: `object` - (Optional) Scopes that the wallet must support in order to be used +- `optionalScopes`: `object` - (Optional) [CAIP-217](https://chainagnostic.org/CAIPs/caip-217) authorization scopes that the wallet can support in order to be used with this dapp. + If scopes are specified, only the following properties are supported: + - `references`: `array` - (Optional) A list of references to specific blockchains for the namespace ID of this scope. + This property is mainly used when there would otherwise be duplicate scopes. + - `methods`: `array` - A list of JSON-RPC methods the dapp or wallet can call. + - `notifications`: `array` - A list of JSON-RPC notifications the dapp or wallet can send. + - `accounts`: `array` - (Optional) A list of [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md) + account IDs valid within this scope. + Dapps should only supply this property when they know the set of accounts they would like the user to permit. + When supplied, these accounts are preselected by default in the account selection process. + Dapps typically omit this property for the user to select their own accounts. +- `sessionProperties`: `object` - (Optional) Properties that the wallet can use to determine if the connection is valid. +- `requiredScopes`: `object` - (Optional) [CAIP-217](https://chainagnostic.org/CAIPs/caip-217) authorization scopes that the wallet must support in order to be used with this dapp. We don't recommend using `requiredScopes` with MetaMask. @@ -102,8 +112,7 @@ The scopes and properties of the created connection. "eip155:42161": { "methods": ["personal_sign"], "notifications": ["accountsChanged", "chainChanged"], - "accounts": ["eip155:42161:0x0910e12C68d02B561a34569E1367c9AAb42bd810"], - "rpcDocuments": "https://example.com/wallet_extension.json" + "accounts": ["eip155:42161:0x0910e12C68d02B561a34569E1367c9AAb42bd810"] }, "eip155:0": { "methods": ["wallet_getPermissions", "wallet_creds_store", "wallet_creds_verify", "wallet_creds_issue", "wallet_creds_present"], From a4f386acb1fce930e0c7f7b1043a0e49199da49d Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 5 Mar 2025 14:57:59 -0800 Subject: [PATCH 15/16] minor edits --- wallet/reference/multichain-api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/wallet/reference/multichain-api.md b/wallet/reference/multichain-api.md index 946d599694a..3f03b6f7cd1 100644 --- a/wallet/reference/multichain-api.md +++ b/wallet/reference/multichain-api.md @@ -31,19 +31,19 @@ This method is defined in [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/ #### Parameters -- `optionalScopes`: `object` - (Optional) [CAIP-217](https://chainagnostic.org/CAIPs/caip-217) authorization scopes that the wallet can support in order to be used with this dapp. +- `optionalScopes`: `object` - (Optional) [CAIP-217](https://chainagnostic.org/CAIPs/caip-217) authorization scopes the wallet can support in order to be used with this dapp. If scopes are specified, only the following properties are supported: - `references`: `array` - (Optional) A list of references to specific blockchains for the namespace ID of this scope. This property is mainly used when there would otherwise be duplicate scopes. - - `methods`: `array` - A list of JSON-RPC methods the dapp or wallet can call. - - `notifications`: `array` - A list of JSON-RPC notifications the dapp or wallet can send. + - `methods`: `array` - A list of JSON-RPC methods the wallet must support in order to be used with this dapp. + - `notifications`: `array` - A list of JSON-RPC notifications the wallet must support in order to be used with this dapp. - `accounts`: `array` - (Optional) A list of [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md) account IDs valid within this scope. Dapps should only supply this property when they know the set of accounts they would like the user to permit. When supplied, these accounts are preselected by default in the account selection process. Dapps typically omit this property for the user to select their own accounts. - `sessionProperties`: `object` - (Optional) Properties that the wallet can use to determine if the connection is valid. -- `requiredScopes`: `object` - (Optional) [CAIP-217](https://chainagnostic.org/CAIPs/caip-217) authorization scopes that the wallet must support in order to be used +- `requiredScopes`: `object` - (Optional) [CAIP-217](https://chainagnostic.org/CAIPs/caip-217) authorization scopes the wallet must support in order to be used with this dapp. We don't recommend using `requiredScopes` with MetaMask. From 93a8cc6b5f6f5a8bf9ab59580cc1ad2e43fa9d97 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 5 Mar 2025 15:06:13 -0800 Subject: [PATCH 16/16] minor edit --- wallet/reference/multichain-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wallet/reference/multichain-api.md b/wallet/reference/multichain-api.md index 3f03b6f7cd1..3cdafbad016 100644 --- a/wallet/reference/multichain-api.md +++ b/wallet/reference/multichain-api.md @@ -33,7 +33,7 @@ This method is defined in [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/ - `optionalScopes`: `object` - (Optional) [CAIP-217](https://chainagnostic.org/CAIPs/caip-217) authorization scopes the wallet can support in order to be used with this dapp. If scopes are specified, only the following properties are supported: - - `references`: `array` - (Optional) A list of references to specific blockchains for the namespace ID of this scope. + - `references`: `array` - (Optional) A list of references to specific blockchains for the namespace of this scope. This property is mainly used when there would otherwise be duplicate scopes. - `methods`: `array` - A list of JSON-RPC methods the wallet must support in order to be used with this dapp. - `notifications`: `array` - A list of JSON-RPC notifications the wallet must support in order to be used with this dapp.