docs: first fixes (#1714)

* docs: first fixes

* docs: add headless option

* docs: wip

* docs: cleanup

* fix: removes logger; standerdizes the provider variable name; add connectAndSign feature

* docs: cleanup

* edits

---------

Co-authored-by: Christopher Ferreira <[email protected]>
Co-authored-by: Alexandra Tran <[email protected]>
Co-authored-by: Alexandra Carrillo <[email protected]>

Author: 3 people

wallet/assets/custom-modal.gif

@@ -21,117 +21,57 @@ the MetaMask browser extension and MetaMask Mobile.
 - Set up a project with [Wagmi](https://wagmi.sh/react/getting-started).
 - Create an Infura API key and allowlist to [make read-only requests](../../how-to/make-read-only-requests.md).
 
-## Steps
+## Configure the MetaMask connector
 
-### 1. Configure MetaMask SDK
-
-In your Wagmi project, configure MetaMask SDK with the proper [SDK options](../../reference/sdk-js-options.md).
-
-```javascript
-const MetaMaskOptions = {
-  dappMetadata: {
-    name: "Example Wagmi dapp",
-  },
-  infuraAPIKey: "YOUR-API-KEY",
-  // Other options.
-}
-```
-
-#### Dapp metadata
-
-Specify the [`dappMetadata`](../../reference/sdk-js-options.md#dappmetadata) option to help
-identify your dapp within the MetaMask ecosystem.
-This option is required when configuring the MetaMask connector with Wagmi.
-
-#### Infura API key
-
-We recommend specifying the [`infuraAPIKey`](../../reference/sdk-js-options.md#infuraapikey)
-option to [make read-only requests](../../how-to/make-read-only-requests.md) using the Infura API.
-Read more about the [benefits of using the Infura API with Wagmi](#benefits-of-using-the-infura-api-with-wagmi).
-
-#### Universal links
-
-We recommend using universal links instead of deeplinks to avoid issues on iOS.
-Thus, do not enable the [`useDeeplink`](../../reference/sdk-js-options.md#usedeeplink) option.
-Using universal links ensures a smoother transition for users accessing your dapp from mobile
-devices, providing a better user experience compared to traditional deeplinking methods.
-
-### 2. Configure Wagmi with the MetaMask connector
-
-Configure Wagmi to include MetaMask as a connector and specify the Ethereum chains your dapp will support.
-Use the `MetaMaskOptions` you created in the previous step when adding the `metaMask` connector.
-For example:
+In your Wagmi project, configure the MetaMask connector:
 
 ```javascript
-import { createConfig, http } from "wagmi"
-import { mainnet, sepolia } from "wagmi/chains"
 import { metaMask } from "wagmi/connectors"
 
-const MetaMaskOptions = {
-  dappMetadata: {
-    name: "Example Wagmi dapp",
-  },
-  infuraAPIKey: "YOUR-API-KEY",
-  // Other options.
-}
-
 export const config = createConfig({
   chains: [mainnet, sepolia],
   connectors: [
-    metaMask(MetaMaskOptions),
-    // Other connectors
+    metaMask({
+      infuraAPIKey: import.meta.env.VITE_INFURA_API_KEY,
+    }),
   ],
   transports: {
     [mainnet.id]: http(),
+    // You can also configure the transcripts to use INFURA_API_KEY directly into the Wagmi config
+    // to share with other providers.
+    // [mainnet.id]: http("https://mainnet.infura.io/v3/...")
     [sepolia.id]: http(),
   },
 })
 ```
 
-### 3. Implement contract interaction using `usePrepareContractWrite`
-
-Due to a known issue in Safari where a 500ms timeout can interrupt smart contract interactions, we
-recommend using the [`usePrepareContractWrite`](https://1.x.wagmi.sh/react/prepare-hooks/usePrepareContractWrite)
-hook from Wagmi.
-This approach ensures smooth transactions by preparing the contract write operation ahead of the
-actual execution.
-
-```javascript
-import { usePrepareContractWrite, useContractWrite } from "wagmi"
-
-const { config } = usePrepareContractWrite({
-  address: "0xContractAddress",
-  abi: contractABI,
-  functionName: "functionToCall",
-  args: [arg1, arg2],
-})
+Make sure to configure the MetaMask connector with the proper [SDK options](../../reference/sdk-js-options.md).
 
-const { write } = useContractWrite(config)
+To provide a better mobile user experience, specify the [`infuraAPIKey`](../../reference/sdk-js-options.md#infuraapikey)
+option to [make read-only requests](../../how-to/make-read-only-requests.md) using the Infura API.
+You can set your Infura API key in environment variables:
 
-write()
+```env
+VITE_INFURA_API_KEY=<YOUR-API-KEY>
 ```
 
 ## Benefits of using the Infura API with Wagmi
 
 Read-only requests are blockchain requests that do not require user wallet interaction.
-Mobile dapps can lose their continuous connection with MetaMask, causing read-only requests to fail.
+Mobile dapps can lose their continuous connection with MetaMask, causing read-only requests to fail. 
+When the mobile wallet is disconnected, the dapp must deeplink into the wallet to "wake up" the connection.
 
-These are some errors that might occur in mobile environments:
+Without setting the `infuraAPIKey`, the dapp might experience issues in mobile environments:
 
 ![Wagmi errors](../../assets/wagmi-errors.png)
 
 To overcome this limitation in mobile dapps that rely on a continuous connection with MetaMask,
 use the Infura API to make read-only requests.
-You can do this by [configuring the SDK with an Infura API key](#2-configure-wagmi-with-the-metamask-connector).
 This approach offloads the read operations to Infura's nodes, reducing the load on your own
 infrastructure and ensuring high availability and reliability, independent of the user's wallet connection.
 
 By using the Infura API, you can ensure:
 
-- **Uninterrupted access:** Continuous network access for read-only requests, regardless of MetaMask's state.
-
-- **Enhanced stability:** Stabilized dapp functionality by relying on Infura's robust infrastructure
+- **Uninterrupted access** - Continuous network access for read-only requests, regardless of MetaMask's state.
+- **Enhanced stability** - Stabilized dapp functionality by relying on Infura's robust infrastructure
   rather than the mobile environment's variable connectivity and background processing constraints.
-
-In summary, using the Infura API compensates for Wagmi's lack of mobile optimization by providing a
-stable network backend for read-only operations.

wallet/connect/3rd-party-libraries/wagmi.md

@@ -47,7 +47,6 @@ example, [`dappMetadata`](../../reference/sdk-js-options.md#dappmetadata):
 ```javascript
 const metamaskSDKWallet = metamaskSDK({
   options: {
-    extensionOnly: false,
     dappMetadata: {
       name: "Example Web3-Onboard Dapp",
     },

wallet/connect/3rd-party-libraries/web3-onboard.md

@@ -59,32 +59,28 @@ Instantiate the SDK using any [options](../../../reference/sdk-js-options.md):
 const MMSDK = new MetaMaskSDK({
   dappMetadata: {
     name: "JavaScript example dapp",
-    url: window.location.href,
   },
   infuraAPIKey: process.env.INFURA_API_KEY,
   // Other options.
 })
-
-// You can also access via window.ethereum.
-const ethereum = MMSDK.getProvider()
 ```
 
 - Use [`dappMetadata`](../../../reference/sdk-js-options.md#dappmetadata) to display information
   about your dapp in the MetaMask connection modal.
 - Use [`infuraAPIKey`](../../../reference/sdk-js-options.md#infuraapikey) to
   [make read-only RPC requests](../../../how-to/make-read-only-requests.md) from your dapp.
-- Use [`modals`](../../../reference/sdk-js-options.md#modals) to [customize the logic and UI of
+- Use [`headless`](../../../reference/sdk-js-options.md#headless) to [customize the logic and UI of
   the displayed modals](../../../how-to/display/custom-modals.md).
 
 ### 4. Use the SDK
 
-Use the SDK by calling any [provider API methods](../../../reference/provider-api.md).
-Always call [`eth_requestAccounts`](/wallet/reference/json-rpc-methods/eth_requestaccounts) using
-[`request()`](../../../reference/provider-api.md#request) first, since it
-prompts the installation or connection popup to appear.
+We recommend calling `connect()` first. You can also call [`eth_requestAccounts`](/wallet/reference/json-rpc-methods/eth_requestaccounts) using
+[`request()`](../../../reference/provider-api.md#request) first, which will prompt the installation or connection popup to appear.
 
 ```javascript
-ethereum.request({ method: "eth_requestAccounts", params: [] })
+const accounts = await MMSDK.connect()
+const provider = MMSDK.getProvider()
+provider.request({ method: "eth_accounts", params: [] })
 ```
 
 You can also call the SDK's [`connectAndSign`](../../../how-to/sign-data/connect-and-sign.md) method, and
@@ -106,10 +102,10 @@ const MMSDK = new MetaMaskSDK({
   // Other options.
 })
 
-// You can also access via window.ethereum.
+const accounts = await MMSDK.connect()
+// You can also access the Ethereum provider object but we recommend using the SDK's methods.
 const ethereum = MMSDK.getProvider()
-
-ethereum.request({ method: "eth_requestAccounts", params: [] })
+ethereum.request({ method: "eth_accounts", params: [] })
 ```
 
 See the [example JavaScript dapps](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples)

wallet/connect/metamask-sdk/javascript/index.md

@@ -43,23 +43,17 @@ Instantiate the SDK using any [options](../../../reference/sdk-js-options.md):
 ```javascript title="index.js"
 const MMSDK = new MetaMaskSDK({
   dappMetadata: {
-    name: "Example Node.js Dapp",
-    url: window.location.href,
+    name: "Node.js dapp",
   },
   infuraAPIKey: process.env.INFURA_API_KEY,
   // Other options.
 })
-
-// You can also access via window.ethereum
-const ethereum = MMSDK.getProvider()
 ```
 
 - Use [`dappMetadata`](../../../reference/sdk-js-options.md#dappmetadata) to display information
   about your dapp in the MetaMask connection modal.
 - Use [`infuraAPIKey`](../../../reference/sdk-js-options.md#infuraapikey) to
   [make read-only RPC requests](../../../how-to/make-read-only-requests.md) from your dapp.
-- Use [`modals`](../../../reference/sdk-js-options.md#modals) to [customize the logic and UI of
-  the displayed modals](../../../how-to/display/custom-modals.md).
 
 ### 4. Use the SDK
 
@@ -69,7 +63,12 @@ Always call [`eth_requestAccounts`](/wallet/reference/json-rpc-methods/eth_reque
 prompts the installation or connection popup to appear.
 
 ```javascript
-ethereum.request({ method: "eth_requestAccounts", params: [] })
+const accounts = await sdk.connect();
+console.log("connect request accounts", accounts);
+
+// You can also access the Ethereum provider object.
+const provider = MMSDK.getProvider()
+provider.request({ method: "eth_requestAccounts", params: [] })
 ```
 
 You can also call the SDK's [`connectAndSign`](../../../how-to/sign-data/connect-and-sign.md) method, and
@@ -85,16 +84,14 @@ import { MetaMaskSDK } from "@metamask/sdk"
 const MMSDK = new MetaMaskSDK({
   dappMetadata: {
     name: "Example Node.js Dapp",
-    url: window.location.href,
   },
   infuraAPIKey: process.env.INFURA_API_KEY,
   // Other options.
 })
 
-// You can also access via window.ethereum
-const ethereum = MMSDK.getProvider()
-
-ethereum.request({ method: "eth_requestAccounts", params: [] })
+const accounts = await MMSDK.connect()
+const provider = MMSDK.getProvider()
+provider.request({ method: "eth_accounts", params: [] })
 ```
 
 See the [example Node.js dapp](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples/nodejs)

wallet/connect/metamask-sdk/javascript/nodejs.md

@@ -45,32 +45,27 @@ Instantiate the SDK using any [options](../../../reference/sdk-js-options.md):
 const MMSDK = new MetaMaskSDK({
   dappMetadata: {
     name: "Example JavaScript Dapp",
-    url: window.location.href,
   },
   infuraAPIKey: process.env.INFURA_API_KEY,
   // Other options
 });
 
-// You can also access via window.ethereum
-const ethereum = MMSDK.getProvider();
 ```
 
 - Use [`dappMetadata`](../../../reference/sdk-js-options.md#dappmetadata) to display information
   about your dapp in the MetaMask connection modal.
 - Use [`infuraAPIKey`](../../../reference/sdk-js-options.md#infuraapikey) to
   [make read-only RPC requests](../../../how-to/make-read-only-requests.md) from your dapp.
-- Use [`modals`](../../../reference/sdk-js-options.md#modals) to [customize the logic and UI of
+- Use [`headless`](../../../reference/sdk-js-options.md#headless) to [customize the logic and UI of
   the displayed modals](../../../how-to/display/custom-modals.md).
 
 ### 4. Use the SDK
 
-Use the SDK by calling any [provider API methods](../../../reference/provider-api.md).
-Always call [`eth_requestAccounts`](/wallet/reference/json-rpc-methods/eth_requestaccounts) using
-[`request()`](../../../reference/provider-api.md#request) first, since it
-prompts the installation or connection popup to appear.
+We recommend calling `connect()` first. You can also call [`eth_requestAccounts`](/wallet/reference/json-rpc-methods/eth_requestaccounts) using
+[`request()`](../../../reference/provider-api.md#request) first, which will prompt the installation or connection popup to appear.
 
 ```javascript
-ethereum.request({ method: "eth_requestAccounts", params: [] })
+const accounts = await MMSDK.connect()
 ```
 
 You can also call the SDK's [`connectAndSign`](../../../how-to/sign-data/connect-and-sign.md) method, and
@@ -92,10 +87,11 @@ const MMSDK = new MetaMaskSDK({
   // Other options
 });
 
-// You can also access via window.ethereum
-const ethereum = MMSDK.getProvider();
+// You can also connect MMSDK.init() first to get access to the provider.
+await MMSDK.connect();
 
-ethereum.request({ method: "eth_requestAccounts", params: [] });
+const ethereum = MMSDK.getProvider();
+ethereum.request({ method: "eth_accounts", params: [] });
 ```
 
 See the [example JavaScript dapps](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples)

wallet/connect/metamask-sdk/javascript/other-web-frameworks.md

@@ -22,18 +22,11 @@ To import, instantiate, and use the SDK, you can insert a script in the head sec
     const MMSDK = new MetaMaskSDK.MetaMaskSDK({
       dappMetadata: {
         name: "Example Pure JS Dapp",
-        url: window.location.href,
       },
       infuraAPIKey: process.env.INFURA_API_KEY,
       // Other options.
     });
-    // Because the init process of MetaMask SDK is async.
-    setTimeout(() => {
-      // You can also access via window.ethereum.
-      const ethereum = MMSDK.getProvider();
-
-      ethereum.request({ method: 'eth_requestAccounts' });
-    }, 0);
+    MMSDK.connect()
   </script>
   ...
 </head>
@@ -45,9 +38,9 @@ You can configure the SDK using any [options](../../../reference/sdk-js-options.
   about your dapp in the MetaMask connection modal.
 - Use [`infuraAPIKey`](../../../reference/sdk-js-options.md#infuraapikey) to
   [make read-only RPC requests](../../../how-to/make-read-only-requests.md) from your dapp.
-- Use [`modals`](../../../reference/sdk-js-options.md#modals) to [customize the logic and UI of
+- Use [`headless`](../../../reference/sdk-js-options.md#headless) to [customize the logic and UI of
   the displayed modals](../../../how-to/display/custom-modals.md).
-
+  
 You can call any [provider API methods](../../../reference/provider-api.md) using the SDK.
 Always call [`eth_requestAccounts`](/wallet/reference/json-rpc-methods/eth_requestaccounts) using
 [`request()`](../../../reference/provider-api.md#request) first, since it prompts the installation

wallet/connect/metamask-sdk/javascript/pure-js.md

@@ -63,7 +63,6 @@ const root = ReactDOM.createRoot(
 root.render(
   <React.StrictMode>
     <MetaMaskProvider
-      debug={false}
       sdkOptions={{
         dappMetadata: {
           name: "Example React Dapp",
@@ -79,7 +78,6 @@ root.render(
 );
 ```
 
-When initializing `MetaMaskProvider`, set `debug` to `true` to activate debug mode.
 For the full list of options you can set for `sdkOptions`, see the
 [JavaScript SDK options reference](../../../../reference/sdk-js-options.md).
 Important options include:
@@ -88,7 +86,7 @@ Important options include:
   about your dapp in the MetaMask connection modal.
 - [`infuraAPIKey`](../../../../reference/sdk-js-options.md#infuraapikey) - Use this to
   [make read-only RPC requests](../../../../how-to/make-read-only-requests.md) from your dapp.
-- [`modals`](../../../../reference/sdk-js-options.md#modals) - Use this to [customize the logic and UI of
+- Use [`headless`](../../../../reference/sdk-js-options.md#headless) to [customize the logic and UI of
   the displayed modals](../../../../how-to/display/custom-modals.md).
 
 ### 4. Use the SDK

wallet/connect/metamask-sdk/javascript/react/index.md

@@ -68,7 +68,6 @@ root.render(
       sdkOptions={{
         dappMetadata: {
           name: "Example React UI Dapp",
-          url: window.location.href,
         },
         infuraAPIKey: process.env.INFURA_API_KEY,
         // Other options.
@@ -88,7 +87,7 @@ Important options include:
   about your dapp in the MetaMask connection modal.
 - [`infuraAPIKey`](../../../../reference/sdk-js-options.md#infuraapikey) - Use this to
   [make read-only RPC requests](../../../../how-to/make-read-only-requests.md) from your dapp.
-- [`modals`](../../../../reference/sdk-js-options.md#modals) - Use this to [customize the logic and UI of
+- Use [`headless`](../../../../reference/sdk-js-options.md#headless) to [customize the logic and UI of
   the displayed modals](../../../../how-to/display/custom-modals.md).
 
 ### 4. Use the SDK