address reviewer feedback

wallet/concepts/multichain-api.md

@@ -4,7 +4,7 @@
   flask_only: true
 ---
 
 # About the Multichain API
 
 :::flaskOnly
 :::
@@ -24,7 +24,7 @@
   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)
@@ -34,25 +34,26 @@
 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 @@
   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
 ```

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

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