Skip to content

Commit 72af6d2

Browse files
shahbaz17shahbaz17
authored
docs: align MetaMask Connect docs with current SDK package APIs (#2959)
* docs: update MetaMask Connect v2 guides & API Update docs for MetaMask Connect v2: document that @metamask/connect-evm and @metamask/connect-solana now require explicit @metamask/connect-multichain peer installation; update installation quickstarts and notes. Clarify client behaviors (async createEVMClient/createMultichainClient, singleton merging semantics and that the initial dapp object is never overwritten), add guidance on session restoration (wallet_sessionChanged) and forceRequest option for connect. Revise provider and JSON-RPC notes: provider auto-announcement (EIP-6963) with skipAutoAnnounce, new error codes (-32002, 4902, 1013), eth_coinbase returns a single address, and wallet_requestPermissions result shape. Misc: move/rename options (analytics.enabled, skipAutoAnnounce, ui.showInstallModal, debug), Solana changes (solana_signMessage + .signature result, testnet/devnet availability in extension only), polyfill notes for Event when using wagmi, and other small clarity/formatting fixes across reference and quickstart files. * Docs: update multichain peer-dep and Solana APIs Remove guidance to explicitly install @metamask/connect-multichain for single-ecosystem packages and simplify install commands across EVM and Solana quickstarts. Rename Solana methods and Wallet Standard features (solana_signMessage → signMessage, solana_signAndSendTransaction/signAndSendAllTransactions → signAndSendTransaction) and update batch guidance to use the variadic signAndSendTransaction call. Revise error handling docs to use the new multichain error classes (RPCInvokeMethodErr, RPCHttpErr, RPCReadonlyResponseErr, RPCReadonlyRequestErr) and expose wallet RPC codes on err.rpcCode; remove the internal transport 1013 note from provider docs. Misc: update Wagmi quickstart to require @metamask/connect-evm@^2.1.0 and adjust examples/usages across multichain, evm, solana, reference, and troubleshooting pages to match the new APIs and patterns. * Standardize Wagmi capitalization in docs Add a terminology rule for Wagmi and update docs for consistent capitalization. Changes touch the terminology rules and multiple MetaMask Connect docs (quickstarts, guides, troubleshooting, supported-platforms, and references) to use “Wagmi” consistently and include small copy/formatting fixes (polyfill guidance and minor punctuation/lineflow adjustments). * Clarify Solana network support notes Update Solana quickstart docs to clarify network support: state that Devnet and Testnet are supported only in the MetaMask browser extension and that on mobile (including QR flows) only Solana mainnet is supported. Remove the explicit reference and link to MetaMask Flask. Changes applied to nodejs.md and react-native.md. * Vale fixes
1 parent 7268c44 commit 72af6d2

30 files changed

Lines changed: 331 additions & 193 deletions

‎.cursor/rules/terminology.mdc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ listed on the right unless they appear in code, URLs, or direct quotations from
2222
| sign-in / sign-out (noun or adjective) | log-in, log-out, login, logout (as nouns/adj) |
2323
| onchain / offchain | on-chain, off-chain |
2424
| Wallet Standard, Wallet Adapter | wallet-standard, wallet-adapter (except in URLs) |
25+
| Wagmi | wagmi (except in code, package names, imports, URLs, and file paths) |
2526
| MetaMask Agent Wallet | Agentic CLI, Agentic Wallet (except in code/URLs where `agentic` appears) |
2627
| Agent Wallet (short form) | agent wallet (lowercase product name) |
2728
| Guard Mode | guard mode (capitalize Mode) |

‎metamask-connect/evm/guides/migrate-from-sdk.md‎

Lines changed: 26 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -82,8 +82,8 @@ initialization in a single async step.
8282

8383
:::caution
8484
`createEVMClient` is async, so always `await` it before accessing the client. The client is also a
85-
singleton. Calling `createEVMClient` multiple times merges options into the same instance. Do not
86-
recreate it on every render.
85+
singleton. Calling `createEVMClient` multiple times merges new options into the same instance, but
86+
the `dapp` object from the first call is never overwritten. Do not recreate it on every render.
8787
:::
8888

8989
**Old:**
@@ -150,7 +150,7 @@ options that MetaMask Connect EVM no longer exposes.
150150
| `openDeeplink` | `mobile.preferredOpenLink` | Same signature: `(deeplink: string) => void` |
151151
| `useDeeplink` | `mobile.useDeeplink` | Same behavior |
152152
| `timer` | Removed | No longer configurable |
153-
| `enableAnalytics` | Removed | No longer available |
153+
| `enableAnalytics` | `analytics.enabled` | Replaced by `analytics: { enabled: false }` to opt out |
154154
| `communicationServerUrl` | Removed | Managed internally |
155155
| `storage` | Removed | Managed internally |
156156

@@ -229,8 +229,9 @@ so read `.result` from the returned object to get the RPC response value.
229229

230230
:::tip React Native polyfills
231231
Browser-based setups (Vite, Webpack) work without polyfills. If you are migrating a React Native
232-
app and encounter errors referencing `Buffer`, `crypto`, `stream`, or `Event is not defined`, see
233-
[React Native Metro polyfill issues](../../troubleshooting/metro-polyfill-issues.md).
232+
app and encounter errors referencing `Buffer`, `crypto`, or `stream`, see
233+
[React Native Metro polyfill issues](../../troubleshooting/metro-polyfill-issues.md). The
234+
`Event is not defined` error only occurs when you also use Wagmi, which dispatches DOM events.
234235
:::
235236

236237
### 5. Update provider access
@@ -378,25 +379,26 @@ See the [multichain quickstart](../../multichain/quickstart/javascript.md) for a
378379

379380
<!-- vale off -->
380381

381-
| Old (`@metamask/sdk`) | New (`@metamask/connect-evm`) | Status |
382-
| ------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------- |
383-
| `new MetaMaskSDK(opts)` | `await createEVMClient(opts)` | Renamed, async |
384-
| `sdk.init` | Not needed | Init happens in `createEVMClient` |
385-
| `sdk.connect` | `client.connect({ chainIds })` | Returns `{ accounts, chainId }` |
386-
| `sdk.getProvider` | `client.getProvider` | Returns EIP-1193 provider |
387-
| `sdk.disconnect` | `client.disconnect` | Same, plus partial disconnect support |
388-
| `dappMetadata` | `dapp` | Renamed |
389-
| `infuraAPIKey` | [`getInfuraRpcUrls({ infuraApiKey })`](../reference/methods.md#getinfurarpcurls) in `api.supportedNetworks` | Helper function |
390-
| `readonlyRPCMap` | `api.supportedNetworks` | Merged with Infura URLs |
391-
| `headless` | `ui.headless` | Moved to `ui` namespace |
392-
| `extensionOnly` | `ui.preferExtension` | Renamed, slightly different semantics |
393-
| `openDeeplink` | `mobile.preferredOpenLink` | Moved to `mobile` namespace |
394-
| `useDeeplink` | `mobile.useDeeplink` | Moved to `mobile` namespace |
395-
| `SDKProvider` | `EIP1193Provider` | Standard provider interface |
396-
| `timer` | Removed | — |
397-
| `enableAnalytics` | Removed | — |
398-
| `communicationServerUrl` | Removed | — |
399-
| `storage` | Removed | — |
382+
| Old (`@metamask/sdk`) | New (`@metamask/connect-evm`) | Status |
383+
| ------------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
384+
| `new MetaMaskSDK(opts)` | `await createEVMClient(opts)` | Renamed, async |
385+
| `sdk.init` | Not needed | Init happens in `createEVMClient` |
386+
| `sdk.connect` | `client.connect({ chainIds })` | Returns `{ accounts, chainId }` |
387+
| `sdk.getProvider` | `client.getProvider` | Returns EIP-1193 provider |
388+
| `sdk.disconnect` | `client.disconnect` | Same for EVM; `disconnect(scopes)` enables partial disconnect |
389+
| `sdk.terminate` | `client.disconnect` | `terminate` removed; `disconnect()` with no arguments revokes all scopes and ends the session |
390+
| `dappMetadata` | `dapp` | Renamed |
391+
| `infuraAPIKey` | [`getInfuraRpcUrls({ infuraApiKey })`](../reference/methods.md#getinfurarpcurls) in `api.supportedNetworks` | Helper function |
392+
| `readonlyRPCMap` | `api.supportedNetworks` | Merged with Infura URLs |
393+
| `headless` | `ui.headless` | Moved to `ui` namespace |
394+
| `extensionOnly` | `ui.preferExtension` | Renamed, slightly different semantics |
395+
| `openDeeplink` | `mobile.preferredOpenLink` | Moved to `mobile` namespace |
396+
| `useDeeplink` | `mobile.useDeeplink` | Moved to `mobile` namespace |
397+
| `SDKProvider` | `EIP1193Provider` | Standard provider interface |
398+
| `timer` | Removed | — |
399+
| `enableAnalytics` | `analytics.enabled` | Replaced by `analytics: { enabled: false }` to opt out |
400+
| `communicationServerUrl` | Removed | — |
401+
| `storage` | Removed | — |
400402

401403
<!-- vale on -->
402404

‎metamask-connect/evm/quickstart/react-native.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,10 @@ if (typeof global.CustomEvent === 'undefined') {
142142
}
143143
```
144144

145+
:::note
146+
The `Event` and `CustomEvent` polyfills above are only required if you also use Wagmi, which dispatches DOM events. The `@metamask/connect-*` packages use `eventemitter3` internally and don't need them.
147+
:::
148+
145149
:::tip
146150
For detailed troubleshooting of polyfill issues, see [React Native Metro polyfill issues](../../troubleshooting/metro-polyfill-issues.md).
147151
:::

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Get started with MetaMask Connect EVM in a React and Wagmi dapp.
2727
[Download the quickstart template](#set-up-using-a-template) or [manually set up MetaMask Connect EVM](#set-up-manually) in an existing dapp.
2828

2929
:::tip Migrating from `@metamask/sdk`?
30-
If you are upgrading an existing wagmi project that used `@metamask/sdk`, see the
30+
If you are upgrading an existing Wagmi project that used `@metamask/sdk`, see the
3131
[Wagmi connector migration reference](#migrate-from-metamasksdk) at the bottom of this page
3232
for a parameter mapping table.
3333
:::
@@ -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` and `wagmi/connectors@^8.0.0`
100+
This quickstart requires `wagmi@^3.6.0`. The `metaMask` connector is imported from the `wagmi/connectors` subpath (part of the `wagmi` package) and requires `@metamask/connect-evm@^2.1.0`.
101101
:::
102102

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

107107
### 2. Import required dependencies
@@ -320,12 +320,12 @@ 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 wagmi@^3.6.0 wagmi/connectors@^8.0.0
323+
npm install @metamask/connect-evm@^2.1.0 wagmi@^3.6.0
324324
```
325325
326-
2. Update hook usage for wagmi v3:
326+
2. Update hook usage for Wagmi v3:
327327
328-
| Old (wagmi v2) | New (wagmi v3) | Notes |
328+
| Old (Wagmi v2) | New (Wagmi v3) | Notes |
329329
| --------------------------------- | -------------------------------------- | ------------------------------------------- |
330330
| `useAccount` | `useConnection` | Returns `address`, `isConnected`, `chainId` |
331331
| `useConnect` returns `connectors` | `useConnectors` hook | Connectors are a separate hook |

‎metamask-connect/evm/reference/json-rpc-api/eth_coinbase.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ import SimplifiedApiReference from '@site/src/components/SimplifiedApiReference'
1111

1212
<SimplifiedApiReference
1313
method="eth_coinbase"
14-
description="Returns the client coinbase address."
14+
description="Returns the currently selected account address. Since @metamask/connect-evm 1.3.1, this returns a single address (not an array)."
1515
parameters={[]}
1616
returns={{
1717
type: 'string',

‎metamask-connect/evm/reference/json-rpc-api/wallet_requestPermissions.mdx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,11 @@ import SimplifiedApiReference from '@site/src/components/SimplifiedApiReference'
4545
exampleResponse={`{
4646
"id": 1,
4747
"jsonrpc": "2.0",
48-
"result": {
49-
"eth_accounts": {}
50-
}
48+
"result": [
49+
{
50+
"parentCapability": "eth_accounts",
51+
"caveats": []
52+
}
53+
]
5154
}`}
5255
/>

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,11 @@ Creates a new EVM client instance.
4747
| `ui.preferExtension` | `boolean` | No | Directly connects through the MetaMask extension when it's installed. The default is `true`. |
4848
| `mobile.preferredOpenLink` | `(deeplink: string) => void` | No | A function that's called to open a deeplink to the MetaMask Mobile App. Required in React Native. |
4949
| `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. |
5051
| `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. |
5155

5256
### Returns
5357

@@ -274,6 +278,13 @@ Switches the active chain on the EVM client.
274278
If the chain is not already added to the user's MetaMask wallet, the optional `chainConfiguration`
275279
parameter triggers a `wallet_addEthereumChain` request as a fallback.
276280

281+
:::note
282+
Since `@metamask/connect-evm` 1.2.0, calling `switchChain` without `chainConfiguration` for an
283+
unrecognized chain rejects with the wallet's raw `4902` error (not a "No chain configuration found."
284+
message). Handle `4902` in a `catch` block by retrying with `chainConfiguration` or calling
285+
`wallet_addEthereumChain`.
286+
:::
287+
277288
### Parameters
278289

279290
| Name | Type | Required | Description |
@@ -363,6 +374,11 @@ The EVM client exposes the following read-only properties:
363374
| `selectedChainId` | `Hex \| undefined` | Currently selected chain ID as a hex string. |
364375
| `status` | `ConnectEvmStatus` | Connection status: `'loaded'`, `'pending'`, `'connecting'`, `'connected'`, or `'disconnected'`. |
365376

377+
:::note
378+
On the EVM client, `status` is a `ConnectEvmStatus`. Since `@metamask/connect-evm` 0.11.0 it
379+
reflects the EVM client's own status and no longer proxies `MultichainClient.status`.
380+
:::
381+
366382
### Example
367383

368384
```javascript

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,10 @@ Throughout this documentation, we refer to the selected provider using `provider
3636
When using MetaMask Connect EVM, you get the same EIP-1193 provider via `client.getProvider`.
3737
The provider returned by MetaMask Connect EVM is available immediately after `createEVMClient` resolves
3838
and supports the same methods, properties, and events documented below.
39+
40+
Since `@metamask/connect-evm` 2.0.0, MetaMask Connect EVM announces its provider through EIP-6963 by
41+
default when the native MetaMask extension hasn't already announced one. Pass `skipAutoAnnounce: true`
42+
to `createEVMClient` to opt out, and call `client.announceProvider` to announce manually.
3943
:::
4044

4145
## Properties
@@ -203,6 +207,7 @@ provider // Or window.ethereum if you don't support EIP-6963.
203207
```
204208

205209
The provider emits this event when the currently connected chain changes.
210+
The `chainId` is a hex string (for example, `0x1`), not a decimal number.
206211
Listen to this event to [detect a user's network](../guides/manage-networks.md).
207212

208213
### `connect`
@@ -329,6 +334,8 @@ You can use the error `code` property to determine why the request failed.
329334
Common codes and their meaning include:
330335

331336
- `4001` - The request is rejected by the user.
337+
- `-32002` - A request is already pending. Don't send another request; wait for the user to respond in MetaMask.
338+
- `4902` - The chain isn't recognized by the wallet. Add it with `wallet_addEthereumChain`, or pass `chainConfiguration` to [`switchChain`](methods.md#switchchain).
332339
- `-32602` - The parameters are invalid.
333340
- `-32603` - Internal error.
334341

@@ -340,6 +347,14 @@ The [`eth-rpc-errors`](https://npmjs.com/package/eth-rpc-errors) package impleme
340347
returned by the MetaMask provider, and can help you identify their meaning.
341348
:::
342349

350+
:::note Typed errors
351+
When you use the multichain client, the core (`@metamask/connect-multichain`) exports typed error
352+
classes for `instanceof` checks: `RPCInvokeMethodErr` (wraps wallet `invokeMethod` errors; read the
353+
wallet's original code from `err.rpcCode`), `RPCHttpErr`, `RPCReadonlyResponseErr`, and
354+
`RPCReadonlyRequestErr`. The EVM provider itself rejects with a standard EIP-1193 `ProviderRpcError`
355+
(use `err.code`).
356+
:::
357+
343358
## Next steps
344359

345360
- [JSON-RPC API reference](./json-rpc-api/index.md)

0 commit comments

Comments
 (0)