From 79b421d0bc89ec5db6079233bf9819b351b439cc Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 9 Oct 2024 10:50:19 -0700 Subject: [PATCH 01/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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)