Skip to content

Commit f4a147e

Browse files
shahbaz17shahbaz17
committed
Update MetaMask Connect docs and bump version to 2.1.1
Add comprehensive documentation for account switching, session reconnection, and error handling. Include new troubleshooting guides for cancellation normalization, sign-only dapps, and unexpected account switches. Clarify account ordering behavior, chainChanged event timing, and mobile QR modal handling. Update version requirement from @metamask/connect-evm@^2.1.0 to @metamask/connect-evm@^2.1.1 in wagmi quickstart.
1 parent db42ce0 commit f4a147e

6 files changed

Lines changed: 206 additions & 23 deletions

File tree

‎metamask-connect/evm/guides/manage-user-accounts.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -311,6 +311,30 @@ This one-step flow is unique to MetaMask Connect EVM's `connectWith` method.
311311
It's not part of Wagmi or other wallet libraries.
312312
:::
313313

314+
## Switch or re-select accounts
315+
316+
Persisted sessions reconnect silently with the previously used account, so users don't get a chance
317+
to pick a different one after reconnecting. To re-prompt for account selection, call
318+
[`connect`](../reference/methods.md#connect) with `forceRequest: true`:
319+
320+
```javascript
321+
const { accounts } = await evmClient.connect({
322+
chainIds: ['0x1'],
323+
forceRequest: true,
324+
})
325+
// The user is prompted to select an account, even if a session already exists.
326+
```
327+
328+
:::note `wallet_requestPermissions` and `wallet_revokePermissions`
329+
The SDK provider intercepts these EIP-2255 methods and maps them to client methods:
330+
331+
- `wallet_requestPermissions` maps to `connect({ forceRequest: true })`. If you call it right after
332+
connecting to show the account picker (a common injected-wallet pattern), the user sees a second
333+
connection prompt. Skip this call when the provider is the SDK's.
334+
- `wallet_revokePermissions` maps to `disconnect`.
335+
336+
:::
337+
314338
## Best practices
315339

316340
Follow these best practices when authenticating users.
@@ -351,6 +375,13 @@ The following table lists common authentication errors and their codes:
351375
| `-32002` | Request already pending | Disable the connect button while the request is pending. |
352376
| `-32603` | Internal JSON-RPC error | Check if MetaMask is properly installed. |
353377

378+
:::note
379+
Cancellations from `connect`, `connectAndSign`, and `connectWith` don't always surface as a
380+
top-level `code: 4001`. A cancellation can arrive wrapped with an outer `code: 53` and the wallet's
381+
real code on `err.rpcCode`. Normalize the error before branching on it. See
382+
[Normalize cancellations from `connect`](../../troubleshooting/index.md#normalize-cancellations-from-connect).
383+
:::
384+
354385
## Next steps
355386

356387
See the following guides to add more functionality to your dapp:

‎metamask-connect/evm/guides/sign-data/siwe.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,15 @@ The following HTML displays the SIWE button:
109109
<p class="alert">Result:<span id="siweResult"></span></p>
110110
```
111111

112+
:::caution Sign-only dapps and network configuration
113+
After `connect` resolves, the provider's active chain follows the wallet's selected network.
114+
If that network isn't in `api.supportedNetworks`, the `personal_sign` request throws
115+
`Chain eip155:<id> is not configured in supportedNetworks`.
116+
Because SIWE users can be on any network, list every network they're likely to be on in
117+
`supportedNetworks`, or pin the provider to a supported chain after connecting.
118+
See [Chain not configured in `supportedNetworks`](../../../troubleshooting/index.md#chain-not-configured-in-supportednetworks).
119+
:::
120+
112121
See the [live example](https://metamask.github.io/test-dapp/#siwe) and
113122
[test dapp source code](https://github.com/MetaMask/test-dapp) for more information.
114123

‎metamask-connect/evm/quickstart/wagmi.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -97,11 +97,11 @@ TOD0: Update with new screenshot and link
9797
Install MetaMask Connect EVM along with its peer dependencies to an existing React project:
9898

9999
:::note Version requirements
100-
This quickstart requires `wagmi@^3.6.0`. The `metaMask` connector is imported from the `wagmi/connectors` path (part of the `wagmi` package) and requires `@metamask/connect-evm@^2.1.0`.
100+
This quickstart requires `wagmi@^3.6.0`. The `metaMask` connector is imported from the `wagmi/connectors` path (part of the `wagmi` package) and requires `@metamask/connect-evm@^2.1.1`.
101101
:::
102102

103103
```bash npm2yarn
104-
npm install @metamask/connect-evm@^2.1.0 wagmi@^3.6.0 viem@2.x @tanstack/react-query
104+
npm install @metamask/connect-evm@^2.1.1 wagmi@^3.6.0 viem@2.x @tanstack/react-query
105105
```
106106

107107
### 2. Import required dependencies
@@ -320,7 +320,7 @@ If you previously used `@metamask/sdk` with Wagmi, the MetaMask connector now us
320320
321321
```bash npm2yarn
322322
npm uninstall @metamask/sdk
323-
npm install @metamask/connect-evm@^2.1.0 wagmi@^3.6.0
323+
npm install @metamask/connect-evm@^2.1.1 wagmi@^3.6.0
324324
```
325325
326326
2. Update hook usage for Wagmi v3:

‎metamask-connect/evm/reference/methods.md‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -36,22 +36,22 @@ Creates a new EVM client instance.
3636

3737
### Parameters
3838

39-
| Name | Type | Required | Description |
40-
| -------------------------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
41-
| `dapp.name` | `string` | Yes | Name of your dapp. |
42-
| `dapp.url` | `string` | No | URL of your dapp. In browsers this is often set automatically; required in Node.js and React Native. |
43-
| `dapp.iconUrl` | `string` | No | URL of your dapp icon. |
44-
| `dapp.base64Icon` | `string` | No | Base64-encoded icon when a hosted URL is unavailable (for example, some React Native setups). Use instead of `iconUrl` when needed. |
45-
| `api.supportedNetworks` | `Record<string, string>` | No | Map of hex chain IDs to RPC URLs for read-only requests and transport. Use [`getInfuraRpcUrls`](#getinfurarpcurls) to generate Infura URLs, then merge custom endpoints. |
46-
| `ui.headless` | `boolean` | No | Enables or disables [headless mode](../guides/headless-mode.md). The default is `false`. |
47-
| `ui.preferExtension` | `boolean` | No | Directly connects through the MetaMask extension when it's installed. The default is `true`. |
48-
| `mobile.preferredOpenLink` | `(deeplink: string) => void` | No | A function that's called to open a deeplink to the MetaMask Mobile App. Required in React Native. |
49-
| `mobile.useDeeplink` | `boolean` | No | Controls use of deeplinks for mobile connection flows. |
50-
| `ui.showInstallModal` | `boolean` | No | Shows the MetaMask install modal when the extension isn't detected. |
51-
| `eventHandlers` | `object` | No | Optional callbacks for connection lifecycle and [provider events](provider-api.md#events). |
52-
| `debug` | `boolean` | No | Enables verbose SDK logging. The default is `false`. |
53-
| `skipAutoAnnounce` | `boolean` | No | Opts out of automatic EIP-6963 provider announcement (default since `@metamask/connect-evm` 2.0.0). Call `client.announceProvider()` to announce manually. |
54-
| `analytics.enabled` | `boolean` | No | Set to `false` to opt out of analytics. |
39+
| Name | Type | Required | Description |
40+
| -------------------------- | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41+
| `dapp.name` | `string` | Yes | Name of your dapp. |
42+
| `dapp.url` | `string` | No | URL of your dapp. In browsers this is often set automatically; required in Node.js and React Native. |
43+
| `dapp.iconUrl` | `string` | No | URL of your dapp icon. |
44+
| `dapp.base64Icon` | `string` | No | Base64-encoded icon when a hosted URL is unavailable (for example, some React Native setups). Use instead of `iconUrl` when needed. |
45+
| `api.supportedNetworks` | `Record<string, string>` | No | Map of hex chain IDs to RPC URLs for read-only requests and transport. Use [`getInfuraRpcUrls`](#getinfurarpcurls) to generate Infura URLs, then merge custom endpoints. |
46+
| `ui.headless` | `boolean` | No | Enables or disables [headless mode](../guides/headless-mode.md). The default is `false`. |
47+
| `ui.preferExtension` | `boolean` | No | Directly connects through the MetaMask extension when it's installed. The default is `true`. |
48+
| `mobile.preferredOpenLink` | `(deeplink: string) => void` | No | A function that's called to open a deeplink to the MetaMask Mobile App. Required in React Native. |
49+
| `mobile.useDeeplink` | `boolean` | No | Controls use of deeplinks for mobile connection flows. |
50+
| `ui.showInstallModal` | `boolean` | No | Shows the MetaMask install modal when the extension isn't detected. On mobile web, setting this to `true` also forces the QR/install modal and suppresses the MetaMask app deeplink. Leave at the default `false` for mobile deeplinking. |
51+
| `eventHandlers` | `object` | No | Optional callbacks for connection lifecycle and [provider events](provider-api.md#events). |
52+
| `debug` | `boolean` | No | Enables verbose SDK logging. The default is `false`. |
53+
| `skipAutoAnnounce` | `boolean` | No | Opts out of automatic EIP-6963 provider announcement (default since `@metamask/connect-evm` 2.0.0). Call `client.announceProvider()` to announce manually. |
54+
| `analytics.enabled` | `boolean` | No | Set to `false` to opt out of analytics. |
5555

5656
### Returns
5757

‎metamask-connect/evm/reference/provider-api.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,15 @@ the same permissions.
199199
This means that the provider emits `accountsChanged` when the user's exposed account address changes.
200200
Listen to this event to [handle accounts](../guides/manage-user-accounts.md).
201201

202+
:::note Account ordering in SDK sessions
203+
The "most recently used account first" ordering is the injected-provider convention. When you use
204+
MetaMask Connect, the account order comes from the session's permitted accounts, which isn't a
205+
selection-first guarantee. Sessions also merge across reconnections, accumulating previously used
206+
accounts, so a stale account can appear first. Don't assume `accounts[0]` is the active account, and
207+
don't treat every `accountsChanged` emission as a user-initiated account switch. See
208+
[Unexpected account switch after reconnect](../../troubleshooting/index.md#unexpected-account-switch-after-reconnect).
209+
:::
210+
202211
### `chainChanged`
203212

204213
```typescript
@@ -210,6 +219,13 @@ The provider emits this event when the currently connected chain changes.
210219
The `chainId` is a hex string (for example, `0x1`), not a decimal number.
211220
Listen to this event to [detect a user's network](../guides/manage-networks.md).
212221

222+
:::note
223+
Unlike the injected provider, which emits `chainChanged` only on an actual network switch, MetaMask
224+
Connect also emits `chainChanged` as part of the connect handshake. If you attach a handler that
225+
reacts to network changes (for example, reloading the page), it can fire mid-connection. Guard such
226+
handlers so they don't run during the initial connect.
227+
:::
228+
213229
### `connect`
214230

215231
```typescript

0 commit comments

Comments
 (0)