edit content

wallet-sidebar.js

@@ -102,7 +102,7 @@ const sidebar = {
         },
         {
           type: "doc",
-          id: "reference/multichain-api",
+          id: "reference/multichain-api-events",
         },
       ],
       collapsed: false,

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
 ```

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