Restructure and improve docs to highlight connecting via EIP-6963 (#1214

) * Restructure and improve docs to highlight connecting via EIP-6963 * edits * additional edits * minor edits * address reviewer feedback * update admonition
MetaMask · Mar 18, 2024 · a52166d · a52166d
1 parent 6e7f9b2
commit a52166d
Show file tree

Hide file tree

Showing 37 changed files with 617 additions and 746 deletions.
diff --git a/docs/whats-new.md b/docs/whats-new.md
@@ -1,9 +1,9 @@
 ---
-title: "What's new in the documentation"
+title: "What's new in the documentation?"
 description: Summary of the latest updates to this documentation.
 ---
 
-# What's new in the documentation
+# What's new in the documentation?
 
 The latest major MetaMask documentation updates are listed by the month they were added to the documentation. 
 For a comprehensive list of recent product changes, visit the "Release Notes" section at the bottom of the [MetaMask developer page](https://metamask.io/developer/).
@@ -16,4 +16,4 @@ For a comprehensive list of recent product changes, visit the "Release Notes" se
 - Restructured [Snaps documentation](/snaps) for improved readability and accessibility. ([#1129](https://github.com/MetaMask/metamask-docs/pull/1129))
 - Added [Snaps architecture diagrams](/snaps/learn/about-snaps). ([#1123](https://github.com/MetaMask/metamask-docs/pull/1123))
 - Documented [`snap_getClientStatus`](/snaps/reference/snaps-api/#snap_getclientstatus). ([#1119](https://github.com/MetaMask/metamask-docs/pull/1119))
-- Documented [how to detect multiple wallets using EIP-6963](/wallet/how-to/detect-wallet/multiple-wallets). ([#1094](https://github.com/MetaMask/metamask-docs/pull/1094))
+- Documented [how to detect multiple wallets using EIP-6963](/wallet/how-to/connect). ([#1094](https://github.com/MetaMask/metamask-docs/pull/1094))
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -134,45 +134,29 @@ const config = {
             from: ["/guide", "/guide/common-terms", "/guide/contributors", "/wallet/how-to/get-started-building", "/wallet/how-to/set-up-dev-environment", "/guide/create-dapp", "/guide/getting-started", "/wallet/category/get-started", "/wallet/get-started/set-up-dev-environment", "/wallet/how-to/get-started-building/set-up-dev-environment"],
             to: "/wallet",
           },
-          {
-            from: "/wallet/how-to/connect",
-            to: "/wallet/quickstart/javascript",
-          },
           {
             from: "/wallet/category/how-to",
             to: "/wallet/how-to",
           },
           {
-            from: ["/guide/mobile-getting-started", "/guide/site-compatibility-checklist", "/guide/mobile-best-practices", "/wallet/how-to/use-mobile", "/wallet/how-to/integrate-with-mobile", "/sdk"],
-            to: "/wallet/how-to/use-sdk",
-          },
-          {
-            from: "/wallet/how-to/use-3rd-party-integrations/unity-dweb",
-            to: "/wallet/how-to/use-sdk/gaming/unity/dweb",
-          },
-          {
-            from: "/wallet/how-to/use-3rd-party-integrations/unity-infura",
-            to: "/wallet/how-to/use-sdk/gaming/unity/infura",
+            from: ["/wallet/quickstart/javascript", "/wallet/quickstart/react", "/wallet/quickstart/other-platforms", "/wallet/how-to/discover-multiple-wallets", "/wallet/how-to/detect-wallet", "/wallet/how-to/detect-wallet/multiple-wallets", "/guide/metamask-extension-provider", "/wallet/how-to/access-provider"],
+            to: "/wallet/how-to/connect",
           },
           {
-            from: "/wallet/how-to/use-3rd-party-integrations",
-            to: "/wallet/how-to/use-sdk/3rd-party-libraries",
-          },
-          {
-            from: "/wallet/how-to/use-3rd-party-integrations/web3-onboard",
-            to: "/wallet/how-to/use-sdk/3rd-party-libraries/web3-onboard",
+            from: ["/wallet/get-started/detect-metamask", "/wallet/how-to/detect-metamask", "/wallet/how-to/detect-wallet/metamask"],
+            to: "/wallet/how-to/connect/detect-metamask",
           },
           {
-            from: ["/wallet/get-started/detect-metamask", "/wallet/how-to/connect/detect-metamask", "/wallet/how-to/detect-metamask", "/wallet/how-to/discover-multiple-wallets"],
-            to: "/wallet/how-to/detect-wallet",
+            from: ["/guide/accessing-accounts", "/wallet/how-to/access-accounts", "/wallet/get-started/access-accounts"],
+            to: "/wallet/how-to/connect/access-accounts",
           },
           {
-            from: ["/wallet/get-started/detect-network", "/wallet/how-to/connect/detect-network"],
-            to: "/wallet/how-to/detect-network",
+            from: ["/wallet/get-started/detect-network", "/wallet/how-to/connect/detect-network", "/wallet/how-to/detect-network"],
+            to: "/wallet/how-to/manage-networks/detect-network",
           },
           {
-            from: ["/guide/accessing-accounts", "/wallet/how-to/connect/access-accounts", "/wallet/get-started/access-accounts"],
-            to: "/wallet/how-to/access-accounts",
+            from: "/wallet/how-to/add-network",
+            to: "/wallet/how-to/manage-networks/add-network",
           },
           {
             from: "/guide/sending-transactions",
@@ -207,8 +191,24 @@ const config = {
             to: "/wallet/how-to/manage-permissions",
           },
           {
-            from: "/guide/metamask-extension-provider",
-            to: "/wallet/how-to/access-provider",
+            from: ["/guide/mobile-getting-started", "/guide/site-compatibility-checklist", "/guide/mobile-best-practices", "/wallet/how-to/use-mobile", "/wallet/how-to/integrate-with-mobile", "/sdk"],
+            to: "/wallet/how-to/use-sdk",
+          },
+          {
+            from: "/wallet/how-to/use-3rd-party-integrations/unity-dweb",
+            to: "/wallet/how-to/use-sdk/gaming/unity/dweb",
+          },
+          {
+            from: "/wallet/how-to/use-3rd-party-integrations/unity-infura",
+            to: "/wallet/how-to/use-sdk/gaming/unity/infura",
+          },
+          {
+            from: "/wallet/how-to/use-3rd-party-integrations",
+            to: "/wallet/how-to/use-sdk/3rd-party-libraries",
+          },
+          {
+            from: "/wallet/how-to/use-3rd-party-integrations/web3-onboard",
+            to: "/wallet/how-to/use-sdk/3rd-party-libraries/web3-onboard",
           },
           {
             from: ["/guide/initializing-dapps", "/wallet/how-to/interact-with-smart-contracts"],
@@ -411,7 +411,7 @@ const config = {
           },
           {
             to: "whats-new",
-            label: "What's new",
+            label: "What's new?",
             position: "right",
           },
         ],

diff --git a/snaps/how-to/connect-to-a-snap.md b/snaps/how-to/connect-to-a-snap.md
@@ -12,7 +12,7 @@ This is possible because Snaps can expose a [custom JSON-RPC API](../learn/about
 ## Detect wallet
 
 To connect to a Snap, dapps must first detect MetaMask in the user's browser.
-See the Wallet documentation on [how to detect MetaMask](/wallet/how-to/detect-wallet).
+See the Wallet documentation on [how to connect to MetaMask](/wallet/how-to/connect).
 
 ### Detect MetaMask Flask
 
@@ -48,7 +48,7 @@ if (provider && isFlask) {
 See the following resources for detecting multiple wallets (via
 [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963)) in the user's browser:
 
-- [How to detect multiple wallets](/wallet/how-to/detect-wallet/multiple-wallets)
+- [How to connect to MetaMask](/wallet/how-to/connect)
 - [Connect to Snap via EIP-6963 example](https://github.com/Montoya/snap-connect-example)
 
 ## Connect to a Snap

diff --git a/src/components/WalletSection.tsx b/src/components/WalletSection.tsx
@@ -4,9 +4,9 @@ import Card, { type CardItem } from "@site/src/components/Card";
 const CardList: CardItem[] = [
   {
     title: "🏁 Wallet quickstart",
-    link: "/wallet/quickstart",
+    link: "/wallet/how-to/connect",
     description: (<>
-      Get started quickly by integrating your existing JavaScript or React dapp with the MetaMask wallet.
+      Get started quickly by connecting your React dapp to MetaMask and other wallets in your users' browsers.
     </>),
   },
   {
@@ -30,7 +30,7 @@ export default function WalletSection(): JSX.Element {
     <section className="container margin-top--md">
       <h1>Integrate your dapp with the MetaMask wallet</h1>
       <p>
-        Your dapp can use the Wallet API and MetaMask SDK to request users&apos; Ethereum accounts, read data from
+        Your dapp can use the Wallet API to request users&apos; Ethereum accounts, read data from
         connected blockchains, suggest that the user sign messages and transactions,
         and perform other functions on MetaMask from multiple dapp platforms.
       </p>

diff --git a/wallet-sidebar.js b/wallet-sidebar.js
@@ -4,18 +4,12 @@
 const sidebar = {
   walletSidebar: [
     "index",
-    {
-      type: "category",
-      label: "Quickstart",
-      link: { type: "generated-index", slug: "/quickstart" },
-      collapsed: false,
-      items: [{ type: "autogenerated", dirName: "quickstart" }],
-    },
     {
       type: "category",
       label: "How to",
       link: { type: "generated-index", slug: "/how-to" },
       items: [{ type: "autogenerated", dirName: "how-to" }],
+      collapsed: false,
     },
     {
       type: "category",

diff --git a/wallet/concepts/wallet-api.md b/wallet/concepts/wallet-api.md
@@ -23,20 +23,23 @@ This API is specified by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193), an
 request users' Ethereum accounts, read data from blockchains the user is connected to, suggest
 that the user sign messages and transactions, and more.
 
-:::note
+:::info Note
 MetaMask supports [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963), which introduces an
-alternative discovery mechanism to the `window.ethereum` injected provider.
-This alternative mechanism enables dapps to support [wallet interoperability](wallet-interoperabilty.md)
+alternative wallet detection mechanism to the `window.ethereum` injected provider.
+This alternative mechanism enables dapps to support [wallet interoperability](wallet-interoperability.md)
 by discovering multiple injected wallet providers in a user's browser.
-We recommend using this mechanism for provider discovery.
+We recommend [using this mechanism to connect to MetaMask](../how-to/connect/index.md).
+
+You can access the provider API using the selected EIP-6963 provider object.
+Throughout this documentation, we refer to the selected provider using `provider`.
 :::
 
 The MetaMask Ethereum provider API contains the following:
 
 - [Properties](../reference/provider-api.md#properties) - The provider contains a property that
   detects if a user has MetaMask installed.
 - [Methods](../reference/provider-api.md#methods) - The provider contains methods that dapps can call.
-  The [`window.ethereum.request(args)`](../reference/provider-api.md#windowethereumrequestargs)
+  The [`request()`](../reference/provider-api.md#request)
   provider method wraps the [JSON-RPC API](#json-rpc-api); dapps can use this
   provider method to call any RPC method.
 - [Events](../reference/provider-api.md#events) - The provider emits events that dapps can listen to.
@@ -46,7 +49,7 @@ methods, and events.
 
 ## JSON-RPC API
 
-MetaMask uses the [`window.ethereum.request(args)`](../reference/provider-api.md#windowethereumrequestargs)
+MetaMask uses the [`request()`](../reference/provider-api.md#request)
 method of the [provider API](#ethereum-provider-api) to wrap a JSON-RPC API.
 The JSON-RPC API contains standard Ethereum JSON-RPC API methods and MetaMask-specific methods.
 
@@ -55,7 +58,7 @@ The RPC methods are documented in the interactive [JSON-RPC API reference](/wall
 :::note
 All RPC method requests can return errors.
 Make sure to handle errors for every call to
-[`window.ethereum.request(args)`](../reference/provider-api.md#windowethereumrequestargs).
+[`request()`](../reference/provider-api.md#request).
 :::
 
 ### Restricted methods

diff --git a/wallet/concepts/wallet-interoperabilty.md → wallet/concepts/wallet-interoperability.md b/wallet/concepts/wallet-interoperabilty.md → wallet/concepts/wallet-interoperability.md
@@ -5,24 +5,69 @@ sidebar_position: 6
 
 # Wallet interoperability
 
-A web dapp can integrate with multiple wallets simultaneously by adding support for
-[EIP-6963](https://eips.ethereum.org/EIPS/eip-6963), which introduces an alternative discovery
+A web dapp can integrate with multiple installed browser wallets simultaneously by adding support for
+[EIP-6963](https://eips.ethereum.org/EIPS/eip-6963), which introduces an alternative wallet detection
 mechanism to the [`window.ethereum`](wallet-api.md#ethereum-provider-api) injected provider.
-This discovery is enabled by using the standardized events and interfaces defined by EIP-6963.
+This mechanism is enabled by using the standardized interfaces defined by EIP-6963.
 
-The following is a visual demo of the user experience, showing the data provided from each installed wallet:
+The following is a demo of the user experience of detecting multiple wallets, showing the data
+provided from each installed wallet:
 
 <p align="center">
   <video width="100%" controls>
     <source src="/eip-6963.mp4" />
   </video>
 </p>
 
-Learn [how to detect multiple wallets](../how-to/detect-wallet/multiple-wallets.md)
-and see the
+You can [connect to MetaMask using EIP-6963](../how-to/connect/index.md) and see the
 [EIP-6963 Vite React + TypeScript demo](https://github.com/MetaMask/vite-react-ts-eip-6963/tree/main)
 for more information.
 
+## EIP-6963 interfaces
+
+Wallets that support EIP-6963 implement and expose the following standardized interfaces.
+When [connecting to MetaMask using EIP-6963](../how-to/connect/index.md), it's important to review
+and understand these interfaces.
+
+### Provider info
+
+The [`EIP6963ProviderInfo`](https://eips.ethereum.org/EIPS/eip-6963#provider-info) interface
+represents the assets needed to display a wallet:
+
+- `uuid` - The wallet ID ([UUIDv4](https://www.rfc-editor.org/rfc/rfc4122)).
+- `name` - A human-readable name of the wallet.
+- `icon` - A [URI](https://www.rfc-editor.org/rfc/rfc3986) pointing to an icon of the wallet.
+- `rdns` - The wallet's domain name.
+
+### Provider detail
+
+The [`EIP6963ProviderDetail`](https://eips.ethereum.org/EIPS/eip-6963#provider-detail) interface
+represents additional metadata about the wallet:
+
+- `info` - The [`EIP6963ProviderInfo`](#provider-info).
+- `provider` - The `EIP1193Provider` defined by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193).
+
+### Announce and request events
+
+The [`EIP6963AnnounceProviderEvent`](https://eips.ethereum.org/EIPS/eip-6963#announce-and-request-events)
+interface announces an event dispatched by the wallet:
+
+```typescript
+interface EIP6963AnnounceProviderEvent extends CustomEvent {
+    type: "eip6963:announceProvider";
+    detail: EIP6963ProviderDetail;
+}
+```
+
+The [`EIP6963RequestProviderEvent`](https://eips.ethereum.org/EIPS/eip-6963#announce-and-request-events)
+interface requests an event dispatched by a dapp:
+
+```typescript
+interface EIP6963RequestProviderEvent extends Event {
+    type: "eip6963:requestProvider";
+}
+```
+
 ## Third-party library support
 
 The following third-party libraries support EIP-6963:
@@ -72,6 +117,6 @@ See the [list of wallets that support EIP-6963](https://github.com/WalletConnect
 ## Backwards compatibility
 
 Dapps that do not support EIP-6963 can still
-[detect MetaMask using the `window.ethereum` provider](../how-to/detect-wallet/metamask.md).
+[detect MetaMask using the `window.ethereum` provider](../how-to/connect/detect-metamask.md).
 However, we recommend adding support to improve the user experience for multiple installed wallets.
 Read more about [EIP-6963 backwards compatibility](https://eips.ethereum.org/EIPS/eip-6963#backwards-compatibility).
diff --git a/wallet/how-to/access-provider.md b/wallet/how-to/access-provider.md
diff --git a/wallet/how-to/batch-json-rpc-requests.md b/wallet/how-to/batch-json-rpc-requests.md
@@ -1,6 +1,6 @@
 ---
 description: Batch multiple JSON-RPC requests using MetaMask SDK.
-sidebar_position: 10
+sidebar_position: 9
 tags:
   - JavaScript SDK
 ---