SDK: New Docs (#1766)

* feat: intro + wagmi quickstart

* feat: versioning

* remove versioning for now + sidebar structured

* refactor

* review fixes + tidy

* reorg

* improvments

* ui refresh

* tidy

* better copy

* tidy

* tidy

* updated redirects + cleaned up wallet+sdk separation

* addressing review comments

* pr comments

* switch and rename

* update example link

* update to new link

* force vercel to deploy again

* test preview deployment

* pm comments

* partial edit

* full edit

* add, fix, clean up redirects + update what's new

* add missing redirect

---------

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

Author: chakra-guy

CONTRIBUTING.md

@@ -71,9 +71,9 @@ To contribute changes:
 
    > **Notes:**
    >
-   > - All documentation content is located in the `wallet`, `snaps`, `services`, and
+   > - All documentation content is located in the `wallet`, `sdk`, `snaps`, `services`, and
    >   `developer-tools` directories.
-   > - If you add a new documentation page, edit `wallet-sidebar.js`, `snaps-sidebar.js`,
+   > - If you add a new documentation page, edit `wallet-sidebar.js`, `sdk-sidebar.js`, `snaps-sidebar.js`,
    >   `services-sidebar.js`, or `dashboard-sidebar.js` to add the page to the
    >   [sidebar](https://docs-template.consensys.io/create/configure-docusaurus#sidebar).
    > - If you delete, rename, or move a documentation file, add a
@@ -120,7 +120,7 @@ Refer to the [Consensys documentation style guide](https://docs-template.consens
 
 ## Add images
 
-All images are located in the `wallet/assets`, `snaps/assets`, `services/images`, and
+All images are located in the `wallet/assets`, `sdk/_assets`, `snaps/assets`, `services/images`, and
 `developer-tools/images` directories.
 When adding a new image, such as a screenshot or diagram, make sure the image has a white or
 `#1b1b1d` color background in order for it to be compatible with the site's light and dark modes.

docs/whats-new.md

@@ -11,6 +11,8 @@ of the [MetaMask developer page](https://metamask.io/developer/).
 
 ## January 2025
 
+- Added new [MetaMask SDK documentation section](/sdk).
+  ([#1766](https://github.com/MetaMask/metamask-docs/pull/1766))
 - Documented Snaps [`Banner`](/snaps/features/custom-ui/#banner), [`Container`](/snaps/features/custom-ui/#container), [`Footer`](/snaps/features/custom-ui/#footer), [`Skeleton`](/snaps/features/custom-ui/#skeleton), and [`Value`](/snaps/features/custom-ui/#value) UI components.
   ([#1835](https://github.com/MetaMask/metamask-docs/pull/1835))
 
@@ -26,7 +28,7 @@ of the [MetaMask developer page](https://metamask.io/developer/).
 
 - Documented [updated error responses](/services/reference/ethereum/json-rpc-methods) when rate-limiting Infura JSON-RPC API calls. ([#1749](https://github.com/MetaMask/metamask-docs/pull/1749))
 - Documented [Unichain Sepolia](/services/reference/unichain) support. ([#1725](https://github.com/MetaMask/metamask-docs/pull/1725))
-- Updated Snaps [Custom UI documentation](/snaps/features/custom-ui/) for MetaMask Extension version 12.6.
+- Updated Snaps [custom UI documentation](/snaps/features/custom-ui/) for MetaMask Extension version 12.6.
   ([#1715](https://github.com/MetaMask/metamask-docs/pull/1715))
 - Added tutorial for
   [creating a simple Starknet dapp](/wallet/how-to/use-non-evm-networks/starknet/create-a-simple-starknet-dapp).

docusaurus.config.js

@@ -151,6 +151,17 @@ const config = {
         }
       },
     ],
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        id: "sdk",
+        path: "sdk",
+        routeBasePath: "sdk",
+        editUrl: "https://github.com/MetaMask/metamask-docs/edit/main/",
+        sidebarPath: require.resolve("./sdk-sidebar.js"),
+        breadcrumbs: false,
+      },
+    ],
     "./src/plugins/plugin-json-rpc.ts",
     isProd
       ? [
@@ -178,9 +189,13 @@ const config = {
           width: 150,
         },
         items: [
+          {
+            to: "sdk",
+            label: "SDK",
+          },
           {
             to: "wallet",
-            label: "Wallet",
+            label: "Wallet API",
           },
           {
             to: "snaps",
@@ -248,6 +263,10 @@ const config = {
                 label: "Wallet",
                 to: "/wallet",
               },
+              {
+                label: "SDK",
+                to: "/sdk",
+              },
               {
                 label: "Snaps",
                 to: "/snaps",

sdk-sidebar.js

@@ -0,0 +1,68 @@
+// @ts-check
+
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebar = {
+  sdkSidebar: [
+    {
+      type: 'category',
+      label: 'Introduction',
+      collapsible: false,  
+      collapsed: false,
+      items: [
+        'introduction/welcome',
+        'introduction/supported-platforms',
+        'introduction/supported-networks',
+        'introduction/llm-prompt',
+        {
+          type: 'link',
+          label: 'Try demo dapp',
+          href: 'https://metamask-sdk-examples-relink.vercel.app/',
+        },
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Quickstart',
+      collapsible: false,  
+      collapsed: false,
+      items: [
+        'quickstart/javascript-wagmi',
+        'quickstart/javascript',
+        'quickstart/react-native',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Guides',
+      collapsible: false,  
+      collapsed: false,
+      items: [
+        'guides/authenticate-users',
+        'guides/manage-networks',
+        'guides/handle-transactions',
+        'guides/interact-with-contracts',
+        {
+          type: 'category',
+          label: 'Advanced',
+          collapsible: true,  
+          collapsed: true,
+          items: [
+            'guides/advanced/connect-and-sign',
+            'guides/advanced/batch-requests',
+          ],
+        },
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Reference',
+      collapsible: false,  
+      collapsed: false,
+      items: [
+        'reference/sdk-options'
+      ],
+    }
+  ],
+};
+
+module.exports = sidebar;

sdk/_assets/connect.gif

@@ -0,0 +1,132 @@
+---
+description: Batch multiple JSON-RPC requests.
+---
+
+# Batch requests
+
+You can batch multiple JSON-RPC requests in your JavaScript dapp.
+
+The SDK's `metamask_batch` method enables you to batch multiple JSON-RPC requests in a single call,
+providing a streamlined approach for dapps to interact with EVM networks, and enabling complex
+sequences of actions.
+This method enhances performance, usability, and efficiency by reducing the number of network calls
+made to MetaMask.
+
+Use cases include:
+
+- **Batching multiple signatures** - Send multiple signing requests in one batch.
+
+- **Switching networks** - Switch the EVM network, perform an action such as sending a transaction,
+  and switch back, all in one batch.
+
+- **Mixed transactions and signatures** - Combine transaction sending and signing requests in one batch.
+
+`metamask_batch` opens up additional possibilities for sophisticated transaction flows in dapps,
+enhancing the user experience and operational efficiency.
+
+## Prerequisites
+
+Set up MetaMask SDK in your JavaScript dapp.
+
+## Use the `metamask_batch` method
+
+`metamask_batch` takes an array of JSON-RPC requests (`ChainRPC[]`) as its parameter.
+
+Each request in the batch is independent.
+The user receives a prompt for each action within the batch, allowing them to approve or reject
+individual requests.
+If any request is rejected, the entire batch fails and an error is returned, ensuring integrity in
+transactional operations.
+
+The method returns an array of results corresponding to each request.
+
+### React / Next.js / React Native example
+
+The following is an example of using `metamask_batch` to batch
+[`personal_sign`](/wallet/reference/json-rpc-methods/personal_sign) and
+[`eth_sendTransaction`](/wallet/reference/json-rpc-methods/eth_sendtransaction) in React, Next.js, or React Native/Expo:
+
+```javascript title="index.js"
+import { metamask_batch } from "metamask-sdk"
+
+function MyComponent() {
+  const handleBatchRequest = async () => {
+    const batchRequests = [
+      { method: "personal_sign", params: ["message", "address"] },
+      {
+        method: "eth_sendTransaction",
+        params: [
+          {
+            /* Transaction parameters */
+          },
+        ],
+      },
+    ]
+
+    try {
+      const results = await metamask_batch(batchRequests)
+      console.log(results) // Process results.
+    } catch (error) {
+      console.error("Batch request failed", error)
+    }
+  }
+
+  return <button onClick={handleBatchRequest}>Send Batch Request</button>
+}
+```
+
+### Vue.js example
+
+The following is an example of using `metamask_batch` to batch
+[`personal_sign`](/wallet/reference/json-rpc-methods/personal_sign) and
+[`eth_sendTransaction`](/wallet/reference/json-rpc-methods/eth_sendtransaction) in Vue.js:
+
+```javascript title="App.vue"
+<script>
+import { metamask_batch } from "metamask-sdk";
+
+export default {
+  methods: {
+    async sendBatchRequest() {
+      const batchRequests = [
+        { method: "personal_sign", params: ["message", "address"] },
+        {
+          method: "eth_sendTransaction",
+          params: [
+            {
+              /* Transaction parameters */
+            },
+          ],
+        },
+      ];
+
+      try {
+        const results = await metamask_batch(batchRequests);
+        console.log(results);
+      } catch (error) {
+        console.error("Error in batch request", error);
+      }
+    }
+  }
+}
+</script>
+```
+
+### Best practices
+
+Follow these best practices when using `metamask_batch`:
+
+- **Ensure each request in the batch is properly formatted** according to the JSON-RPC specifications.
+
+- **Handle errors appropriately**, especially when a batch request is partially approved.
+
+- **Test batch operations** to ensure consistent behavior across different networks and accounts.
+
+- **Be aware of the dependencies between chained requests.**
+  Avoid creating a dependency where the outcome of one request directly influences the context or
+  validity of a subsequent request within the same batch.
+  For example, avoid chaining a [`wallet_switchEthereumChain`](/wallet/reference/json-rpc-methods/wallet_switchethereumchain)
+  request with [`eth_signTypedData_v4`](/wallet/reference/json-rpc-methods/eth_signtypeddata_v4), because
+  `eth_signTypedData_v4` relies on the current chain ID, which would be altered by `wallet_switchEthereumChain`.
+  This approach ensures that each request in the batch operates independently and maintains its
+  integrity, regardless of changes introduced by preceding requests in the batch.

sdk/_assets/network.gif

@@ -0,0 +1,92 @@
+---
+description: Connect and sign in a single interaction.
+---
+
+# Connect and sign
+
+You can connect to MetaMask and sign data in a single interaction from your JavaScript dapp.
+
+The SDK's `connectAndSign` method provides a streamlined approach for dapps to interact with MetaMask.
+This method combines the [`eth_requestAccounts`](/wallet/reference/json-rpc-methods/eth_requestaccounts)
+and [`personal_sign`](/wallet/reference/json-rpc-methods/personal_sign) RPC methods, executing them sequentially.
+`connectAndSign` takes one parameter, the message string to be signed, and passes the message and
+the output of `eth_requestAccounts` directly to `personal_sign`.
+
+This method enhances dapp user experience, especially on mobile platforms, by allowing users to
+connect to MetaMask and sign a message in a single interaction, requiring only one switch between
+the mobile dapp and MetaMask Mobile.
+This is useful for various purposes such as authentication and transaction verification.
+
+<p align="center">
+  <video width="350" controls>
+    <source src="/connect-and-sign.mp4" type="video/mp4" />
+  </video>
+</p>
+
+## Prerequisites
+
+- MetaMask SDK set up in your JavaScript dapp.
+
+- MetaMask Mobile version 7.10 or later.
+  Your users must have an updated version of MetaMask Mobile for this feature to work correctly.
+  For older versions of MetaMask, this function may not work as expected.
+
+## Use the `connectAndSign` method
+
+Use the `connectAndSign` method as follows:
+
+```javascript
+const connectAndSign = async () => {
+  try {
+    const signResult = await sdk?.connectAndSign({
+      msg: "Connect + Sign message",
+    })
+    setResponse(signResult)
+  } catch (err) {
+    console.warn("failed to connect..", err)
+  }
+}
+```
+
+To invoke `connectAndSign`:
+
+1. Ensure the `MetaMaskSDK` instance (`sdk` in this context) is properly initialized and available.
+2. Call `connectAndSign` with the message to be signed.
+3. Handle the promise to process the response or catch any errors.
+
+## Examples
+
+The following is an example of using the `connectAndSign` method in a React dapp, integrating it
+into a functional component:
+
+```javascript
+import React, { useState } from "react"
+import { useSDK } from "@metamask/sdk-react"
+
+function MyComponent() {
+  const { sdk } = useSDK()
+  const [signedMessage, setSignedMessage] = useState("")
+
+  const handleConnectAndSign = async () => {
+    try {
+      const message = "Your message here"
+      const signature = await sdk.connectAndSign({ msg: message })
+      setSignedMessage(signature)
+    } catch (error) {
+      console.error("Error in signing:", error)
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={handleConnectAndSign}>Connect and Sign</button>
+      {signedMessage && <p>Signed Message: {signedMessage}</p>}
+    </div>
+  )
+}
+```
+
+For examples of using the `connectAndSign` function in Next.js and Vue.js, see the
+[example Next.js dapp](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples/nextjs-demo)
+and [example Vue.js dapp](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples/vuejs)
+on GitHub.