Skip to content

Commit 988baa9

Browse files
shahbaz17shahbaz17
authored
Update MetaMask Connect docs and bump version to 2.1.1 (#2984)
1 parent db42ce0 commit 988baa9

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)