Separate concepts and add context (#2808)

* Seperate concepts and add context.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Update metamask-connect/multichain/concepts/sessions.md

* fix typo

* add note about session IDs

---------

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>
Co-authored-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com>
Co-authored-by: Alexandra Carrillo <alexandra.carrillo@consensys.net>
Co-authored-by: Mohammad Shahbaz Alam <shahbaz17@users.noreply.github.com>

Author: 3 people

metamask-connect/multichain/concepts/accounts.md

@@ -0,0 +1,38 @@
+---
+sidebar_label: Account IDs
+description: Learn how CAIP-10 account IDs work in MetaMask Connect Multichain to uniquely identify accounts across chains.
+keywords: [multichain, caip, caip-10, account ID, chain address, eip155, solana account, cross-chain identity]
+---
+
+# Account IDs (CAIP-10)
+
+A plain address like `0xab16...` does not identify which chain it belongs to. The same address can
+exist on Ethereum, Polygon, and other EVM chains. In a multichain context, you need to know which
+account on which chain the user authorized.
+
+Account IDs solve this by combining a [scope](./scopes.md) with an address. After a user connects, the
+[session](./sessions.md) returns account IDs, so you know which chain each address belongs to.
+
+## Format and examples
+
+An account ID uses `namespace:reference:address` format, as defined by
+[CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md).
+
+| Ecosystem | Example                                           |
+| --------- | ------------------------------------------------- |
+| EVM       | `eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb` |
+| Solana    | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:7S3P4HxJpyyigGzodYwHtCxZyUQe9JiBMHyRWXArAaKv` |
+
+Account IDs appear in the [`sessionScopes`](./sessions.md) returned by
+[`getSession`](../reference/methods.md#getsession). To extract the address from a CAIP-10
+account ID:
+
+```javascript
+const accountId = 'eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb'
+const address = accountId.split(':')[2]
+```
+
+## Next steps
+
+- [Scopes](./scopes.md): Understand CAIP-2 chain identifiers used in account IDs.
+- [Sessions](./sessions.md): Learn how accounts are grouped into authorized sessions.

metamask-connect/multichain/concepts/scopes.md

@@ -1,41 +1,59 @@
 ---
-title: "Multichain Scopes and Sessions - MetaMask Connect"
+title: "Multichain Scopes - MetaMask Connect"
 sidebar_label: Scopes
-description: Learn how CAIP-2 scopes, CAIP-10 account IDs, and CAIP-25 sessions work in MetaMask Connect Multichain to identify chains and accounts.
-keywords: [multichain, caip, scope, caip-2, caip-10, caip-25, session, chain id, chain namespace, account ID format, blockchain identifier, eip155, solana scope]
+description: Learn how CAIP-2 scopes work in MetaMask Connect Multichain to identify chains across ecosystems.
+keywords: [multichain, caip, scope, caip-2, chain id, chain namespace, blockchain identifier, eip155, solana scope]
 ---
 
-# Scopes, accounts, and sessions
+# Scopes (CAIP-2)
 
-MetaMask Connect Multichain uses three CAIP standards:
+MetaMask Connect Multichain uses CAIP standards to identify chains, [accounts](./accounts.md),
+and [sessions](./sessions.md).
 
-- **CAIP-2 scopes** (for example, `eip155:1` for Ethereum Mainnet or `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` for Solana Mainnet) to identify chains.
-- **CAIP-10 account IDs** to identify accounts across chains.
-- **CAIP-25 sessions** to group authorized scopes and accounts into a single connection.
+Traditional single-chain dapps identify networks with a numeric chain ID (for example, `1` for
+Ethereum Mainnet). That works within EVM ecosystems, but it does not generalize across ecosystems.
+Solana does not use numeric chain IDs, and a raw value like `1` is ambiguous without an ecosystem
+context.
 
-Understanding these concepts helps you work with the multichain client.
+Scopes solve this by providing a **universal chain identifier** for a chain or set of chains.
+When you [`connect`](../reference/methods.md#connect) to MetaMask, you pass an array of scopes to
+declare exactly which chains your dapp needs. When you call
+[`invokeMethod`](../reference/methods.md#invokemethod), you pass a scope to target the correct chain
+without switching netwoks.
 
-## Scopes (CAIP-2)
+## Format and examples
 
 A scope is a chain identifier in `namespace:reference` format, as defined by
-[CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md). It uniquely identifies
-a blockchain across any ecosystem.
+[CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md). It identifies
+a specific blockchain across any ecosystem.
 
 - The **namespace** identifies the ecosystem or standard (for example, `eip155` for EVM, `solana`
   for Solana).
 - The **reference** identifies a specific chain within that namespace.
 
-You use scopes when connecting and when calling
-[`invokeMethod`](../reference/methods.md#invokemethod) to target a specific chain.
+```javascript
+// Connect to Ethereum, Polygon, and Solana in a single call
+await client.connect([
+  'eip155:1',                                    // Ethereum Mainnet
+  'eip155:137',                                  // Polygon Mainnet
+  'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'     // Solana Mainnet
+], [])
+
+// Send an RPC request to a specific chain using its scope
+const balance = await client.invokeMethod({
+  scope: 'eip155:1',
+  request: { method: 'eth_getBalance', params: ['0xab1...', 'latest'] }
+})
+```
 
-### Supported scopes
+## Supported scopes
 
 | Ecosystem | Format                 | Examples                                                                     |
 | --------- | ---------------------- | ---------------------------------------------------------------------------- |
 | EVM       | `eip155:<chainId>`     | `eip155:1` (Ethereum), `eip155:59144` (Linea), `eip155:137` (Polygon)        |
 | Solana    | `solana:<genesisHash>` | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` (Mainnet), `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` (Devnet) |
 
-### Common EVM scopes
+## Common EVM scopes
 
 | Network          | Scope            |
 | ---------------- | ---------------- |
@@ -47,46 +65,7 @@ You use scopes when connecting and when calling
 | Optimism         | `eip155:10`      |
 | Sepolia testnet  | `eip155:11155111`|
 
-## Account IDs (CAIP-10)
-
-An account ID extends a scope with an address, in `namespace:reference:address` format, as defined
-by [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md). It uniquely
-identifies an account on a specific chain.
-
-| Ecosystem | Example                                           |
-| --------- | ------------------------------------------------- |
-| EVM       | `eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb` |
-| Solana    | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:7S3P4HxJpyyigGzodYwHtCxZyUQe9JiBMHyRWXArAaKv` |
-
-To extract the address from a CAIP-10 account ID:
-
-```javascript
-const accountId = 'eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb'
-const address = accountId.split(':')[2]
-```
-
-## Sessions (CAIP-25)
-
-A session is an authorized connection between your dapp and MetaMask that spans multiple scopes, as
-defined by [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md). When a user
-approves a connection, MetaMask creates a session containing the approved scopes and accounts.
-
-A session includes:
-
-- **`sessionScopes`**: The chains the user approved, each with its associated accounts.
-- **Persistence**: Sessions survive page reloads and new tabs.
-- **Lifecycle methods**: Use [`getSession`](../reference/methods.md#getsession) to retrieve session
-  data and [`disconnect`](../reference/methods.md#disconnect) to end or modify the session.
-
-```javascript
-const session = await client.provider.getSession()
-
-const ethAccounts = session.sessionScopes['eip155:1']?.accounts || []
-const solAccounts = session.sessionScopes['solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp']?.accounts || []
-```
-
 ## Next steps
 
-- [Quickstart](../quickstart/javascript.md): Set up MetaMask Connect Multichain.
-- [Send transactions](../guides/send-transactions.md): Send transactions on EVM and Solana.
-- [API reference](../reference/api.md): Full Multichain API reference.
+- [Accounts](./accounts.md): Learn how CAIP-10 account IDs extend scopes with addresses.
+- [Sessions](./sessions.md): Learn how scopes and accounts are grouped into authorized connections.

metamask-connect/multichain/concepts/sessions.md

@@ -0,0 +1,36 @@
+---
+sidebar_label: Sessions
+description: Learn how CAIP-25 sessions work in MetaMask Connect Multichain to group authorized scopes and accounts into a single connection.
+keywords: [multichain, caip, caip-25, session, sessionScopes, connection, persistence, disconnect, getSession]
+---
+
+# Sessions (CAIP-25)
+
+A session is an authorized connection between your dapp and MetaMask that can span multiple blockchain ecosystems and chains, as defined in
+[CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md).
+When a user approves a connection, MetaMask creates a session including the approved [scopes](./scopes.md) and [accounts](./accounts.md).
+
+MetaMask Connect Multichain provides the method [`getSession`](../reference/methods.md#getsession) to get information about the current session,
+and the method [`disconnect`](../reference/methods.md#disconnect) to end or update the session.
+For more information about the session lifecycle, see [CAIP-316](https://standards.chainagnostic.org/CAIPs/caip-316).
+
+A session is persistent, meaning it survives across page reloads and new tabs.
+
+A session includes `sessionScopes`, which contains the chains the user approved, each with its associated accounts.
+The following example extracts the approved Ethereum Mainnet and Solana Mainnet accounts from `sessionScopes`:
+
+```javascript
+const session = await client.provider.getSession()
+
+const ethAccounts = session.sessionScopes['eip155:1']?.accounts || []
+const solAccounts = session.sessionScopes['solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp']?.accounts || []
+```
+
+:::note
+MetaMask doesn't support session IDs.
+:::
+
+## Next steps
+
+- [Scopes](./scopes.md): Understand CAIP-2 chain identifiers used in sessions.
+- [Accounts](./accounts.md): Learn how CAIP-10 account IDs identify accounts across chains.

metamask-connect/multichain/quickstart/javascript.md

@@ -164,7 +164,7 @@ Use [`invokeMethod()`](../reference/methods.md#invokemethod) to call RPC methods
 | Method                                                                     | Description                                                                                  |
 | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | [`connect(scopes, caipAccountIds)`](../reference/methods.md#connect)       | Connects to MetaMask with multichain [scopes](../concepts/scopes.md)                         |
-| [`getSession()`](../reference/methods.md#getsession)                       | Returns the current [session](../concepts/scopes.md#sessions-caip-25) with approved accounts |
+| [`getSession()`](../reference/methods.md#getsession)                       | Returns the current [session](../concepts/sessions.md) with approved accounts |
 | [`invokeMethod({ scope, request })`](../reference/methods.md#invokemethod) | Calls an RPC method on a specific chain using a [scope](../concepts/scopes.md)               |
 | [`disconnect()`](../reference/methods.md#disconnect)                       | Disconnects all [scopes](../concepts/scopes.md) and ends the session                         |
 | [`disconnect(scopes)`](../reference/methods.md#disconnect)                 | Disconnects specific [scopes](../concepts/scopes.md) without ending the session              |
@@ -174,7 +174,7 @@ Use [`invokeMethod()`](../reference/methods.md#invokemethod) to call RPC methods
 
 ## Next steps
 
-- See [Scopes, accounts, and sessions](../concepts/scopes.md) to understand CAIP-2 chain identifiers and CAIP-25 sessions.
+- Understand [scopes](../concepts/scopes.md), [accounts](../concepts/accounts.md), and [sessions](../concepts/sessions.md) for CAIP-2 chain identifiers, CAIP-10 account IDs, and CAIP-25 sessions.
 - [Send transactions on EVM and Solana](../guides/send-transactions.md) from a single multichain session.
 - [Sign messages on EVM and Solana](../guides/sign-transactions.md) using `invokeMethod`.
 - See [Create a multichain dapp](../tutorials/create-multichain-dapp.md) for a full step-by-step tutorial with React.

metamask-connect/multichain/quickstart/nodejs.md

@@ -179,7 +179,7 @@ client.on('wallet_sessionChanged', session => {
 | Method                                                                           | Description                                                                                   |
 | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | [`connect(scopes, caipAccountIds)`](../reference/methods.md#connect)             | Connects to MetaMask with multichain [scopes](../concepts/scopes.md).                         |
-| [`getSession()`](../reference/methods.md#getsession)                             | Returns the current [session](../concepts/scopes.md#sessions-caip-25) with approved accounts. |
+| [`getSession()`](../reference/methods.md#getsession)                             | Returns the current [session](../concepts/sessions.md) with approved accounts. |
 | [`invokeMethod({ scope, request })`](../reference/methods.md#invokemethod)       | Calls an RPC method on a specific chain using a [scope](../concepts/scopes.md).               |
 | [`disconnect()`](../reference/methods.md#disconnect)                             | Disconnects all [scopes](../concepts/scopes.md) and ends the session.                         |
 | [`disconnect(scopes)`](../reference/methods.md#disconnect)                       | Disconnects specific [scopes](../concepts/scopes.md) without ending the session.              |
@@ -268,7 +268,7 @@ node index.mjs
 
 ## Next steps
 
-- [Understand multichain scopes](../concepts/scopes.md) for CAIP-2 chain identifiers and CAIP-25 sessions.
+- Understand [scopes](../concepts/scopes.md), [accounts](../concepts/accounts.md), and [sessions](../concepts/sessions.md) for CAIP-2 chain identifiers, CAIP-10 account IDs, and CAIP-25 sessions.
 - [Sign multichain transactions](../guides/sign-transactions.md) using `invokeMethod`.
 - [Send multichain transactions](../guides/send-transactions.md) from a single session.
 - See [Create a multichain dapp](../tutorials/create-multichain-dapp.md) for a full step-by-step tutorial with React.

metamask-connect/multichain/quickstart/react-native.md

@@ -460,7 +460,7 @@ npx expo run:ios
 
 ## Next steps
 
-- [Understand multichain scopes.](../concepts/scopes.md)
+- Understand [scopes](../concepts/scopes.md), [accounts](../concepts/accounts.md), and [sessions](../concepts/sessions.md).
 - [Sign multichain transactions.](../guides/sign-transactions.md)
 - [Send multichain transactions.](../guides/send-transactions.md)
 - Follow the [Create a multichain dapp tutorial](../tutorials/create-multichain-dapp.md).

metamask-connect/multichain/reference/api.md

@@ -423,6 +423,6 @@ according to [CAIP-217](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/c
 ## Next steps
 
 - Follow the [JavaScript quickstart](../quickstart/javascript.md) to set up MetaMask Connect Multichain in a dapp.
-- See the [MetaMask Connect Multichain methods](methods.md) for the high-level methods that wrap this API.
-- See [Scopes, accounts, and sessions](../concepts/scopes.md) to understand CAIP-2, CAIP-10, and CAIP-25 identifiers.
+- See the [MetaMask Connect Multichain methods](methods.md) for the client-level methods that wrap this API.
+- Understand [scopes](../concepts/scopes.md), [accounts](../concepts/accounts.md), and [sessions](../concepts/sessions.md) for CAIP-2, CAIP-10, and CAIP-25 identifiers.
 - See [Send transactions on EVM and Solana](../guides/send-transactions.md) for practical usage examples.

metamask-connect/multichain/tutorials/create-multichain-dapp.md

@@ -17,7 +17,7 @@ Your dapp will handle wallet login and logout, read balances across all four cha
 
 ## Key concepts
 
-This tutorial uses [scopes, account IDs, and sessions](../concepts/scopes.md) to identify chains and
+This tutorial uses [scopes](../concepts/scopes.md), [account IDs](../concepts/accounts.md), and [sessions](../concepts/sessions.md) to identify chains and
 accounts across ecosystems. If you're unfamiliar with these concepts, review them before continuing.
 
 This tutorial uses the following scopes:

mm-connect-sidebar.js

@@ -75,6 +75,8 @@ const metamaskConnectSidebar = {
       collapsed: false,
       items: [
         'multichain/concepts/scopes',
+        'multichain/concepts/accounts',
+        'multichain/concepts/sessions',
       ],
     },
     {