add how-to guide and edits

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).

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"
             }
           ]
         },

wallet/concepts/multichain-api.md

@@ -1,11 +1,10 @@
 ---
-description: Learn about the MetaMask Multichain API.
-sidebar_position: 4
+description: Learn about the Multichain API.
 sidebar_custom_props:
   flask_only: true
 ---
 
 # About the Multichain API
 
 :::flaskOnly
 :::
@@ -25,9 +24,11 @@
   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
   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 @@
 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 @@
   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.

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",
+        }]
+      }
+    }
+  }
+});
+```

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.

wallet/reference/multichain-api.md

@@ -17,7 +17,10 @@
 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 @@
 
 ### `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 @@
 - `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).
 
@@ -308,7 +311,7 @@
 
 ### `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
@@ -320,7 +323,7 @@
 - `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.