diff --git a/docusaurus.config.js b/docusaurus.config.js index 11939d7b5a3..17a88d26aeb 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -284,6 +284,14 @@ const config = { from: "/wallet/how-to/set-icon", to: "/wallet/how-to/display/icon", }, + { + from: "/wallet/concepts/provider-api", + to: "/wallet/concepts/apis", + }, + { + from: "/wallet/concepts/rpc-api", + to: "/wallet/concepts/apis", + }, ].reduce((acc, item) => { acc.push(item); acc.push({ from: item.from + ".html", to: item.to }); diff --git a/wallet/concepts/apis.md b/wallet/concepts/apis.md new file mode 100644 index 00000000000..a9152f75748 --- /dev/null +++ b/wallet/concepts/apis.md @@ -0,0 +1,91 @@ +--- +sidebar_position: 3 +description: Learn about the MetaMask Ethereum provider API. +--- + +# What are the MetaMask APIs? + +MetaMask supports an [Ethereum provider API](#ethereum-provider-api), which wraps a [JSON-RPC API](#json-rpc-api). + +:::tip API documentation +The API methods are documented in the following references: + +- [Ethereum provider API reference](../reference/provider-api.md) +- [JSON-RPC API playground](/wallet/reference/eth_subscribe) +::: + +## Ethereum provider API + +MetaMask injects a global JavaScript API into websites visited by its users using the +`window.ethereum` provider object. +This API is specified by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193), and it allows dapps to +request users' Ethereum accounts, read data from blockchains the user is connected to, suggest +that the user sign messages and transactions, and more. + +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) + 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. + +View the [provider API reference](../reference/provider-api.md) for all the provider properties, +methods, and events. + +:::tip Use MetaMask SDK with the provider API +You can call the provider API from a dapp with or without [MetaMask SDK](sdk.md) installed, but we +recommend using the SDK to enable users to easily connect to the MetaMask browser extension and +MetaMask Mobile. +The SDK supports multiple dapp platforms including mobile and gaming dapps. + +Get started by [setting up the SDK](../how-to/connect/set-up-sdk/index.md). +::: + +## JSON-RPC API + +MetaMask uses the [`window.ethereum.request(args)`](../reference/provider-api.md#windowethereumrequestargs) +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. + +The RPC methods are documented in the interactive +[JSON-RPC API playground](/wallet/reference/eth_subscribe). +Methods in the API playground may have the following tags: + +- **MetaMask** - These methods behave in ways specific to MetaMask, and may or may not be supported + by other wallets. +- **Restricted** - These methods are [restricted](#restricted-methods), which require requesting + permission using [`wallet_requestPermissions`](/wallet/reference/wallet_requestpermissions). +- **Mobile** - These methods are only available on MetaMask Mobile. +- **Ethereum API** - These are standard Ethereum JSON-RPC API methods. + See the [Ethereum wiki](https://eth.wiki/json-rpc/API#json-rpc-methods) for more information on + these methods. + +:::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). +::: + +### Restricted methods + +MetaMask introduced wallet permissions in [EIP-2255](https://eips.ethereum.org/EIPS/eip-2255). +In this permissions system, each RPC method is restricted or unrestricted. +If a method is restricted, a dapp must request permission to call it using +[`wallet_requestPermissions`](/wallet/reference/wallet_requestpermissions). +Under the hood, permissions are plain, JSON-compatible objects, with fields that are mostly used +internally by MetaMask. + +Outside of [Snaps restricted methods](/snaps/reference/rpc-api/#restricted-methods), the only +restricted method is [`eth_accounts`](/wallet/reference/eth_accounts), which allows you to access +the user's Ethereum accounts. +More restricted methods will be added in the future. + +### Unrestricted methods + +Unrestricted methods do not require requesting permission to call them, but they might still rely on +permissions to succeed (for example, the signing methods require calling the restricted +[`eth_accounts`](/wallet/reference/eth_accounts) method), or they might require confirmation by the +user (for example, [`wallet_addEthereumChain`](/wallet/reference/wallet_addethereumchain)). diff --git a/wallet/concepts/architecture.md b/wallet/concepts/architecture.md index a3b1eb37c16..d041cdde686 100644 --- a/wallet/concepts/architecture.md +++ b/wallet/concepts/architecture.md @@ -11,6 +11,6 @@ The following diagram outlines the high-level architecture of the MetaMask web3 Using [MetaMask SDK](sdk.md), dapps built on multiple platforms can connect to their users' Ethereum accounts through the MetaMask browser extension and MetaMask Mobile. -Dapps can send [JSON-RPC API](../reference/rpc-api.md) calls to the users' MetaMask wallet clients. +Dapps can send [JSON-RPC API](apis.md#json-rpc-api) calls to the users' MetaMask wallet clients. MetaMask then responds to these requests directly or uses [Infura](https://www.infura.io/) (or another user-configured node provider) when the call requires access to information on a blockchain network. diff --git a/wallet/concepts/convenience-libraries.md b/wallet/concepts/convenience-libraries.md index 0a83719b15c..0b819ec217a 100644 --- a/wallet/concepts/convenience-libraries.md +++ b/wallet/concepts/convenience-libraries.md @@ -1,6 +1,6 @@ --- description: Learn about convenience libraries. -sidebar_position: 5 +sidebar_position: 4 --- # Convenience libraries diff --git a/wallet/concepts/provider-api.md b/wallet/concepts/provider-api.md deleted file mode 100644 index f8c0025cb43..00000000000 --- a/wallet/concepts/provider-api.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_position: 3 -description: Learn about the MetaMask Ethereum provider API. ---- - -# Ethereum provider API - -MetaMask injects a global JavaScript API into websites visited by its users using the -`window.ethereum` provider object. -This API is specified by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193), and it allows dapps to -request users' Ethereum accounts, read data from blockchains the user is connected to, suggest -that the user sign messages and transactions, and more. - -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) - provider method wraps the [MetaMask JSON-RPC API](rpc-api.md); 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. - -View the [provider API reference](../reference/provider-api.md) for all the provider properties, -methods, and events. - -:::tip Use MetaMask SDK with the provider API -You can call the provider API from a dapp with or without [MetaMask SDK](sdk.md) installed, but we -recommend using the SDK to enable users to easily connect to the MetaMask browser extension and -MetaMask Mobile. -The SDK supports multiple dapp platforms including mobile and gaming dapps. - -Get started by [setting up the SDK](../how-to/connect/set-up-sdk/index.md). -::: diff --git a/wallet/concepts/rpc-api.md b/wallet/concepts/rpc-api.md deleted file mode 100644 index 375b4041786..00000000000 --- a/wallet/concepts/rpc-api.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -sidebar_position: 4 -description: Learn about the MetaMask JSON-RPC API. ---- - -# JSON-RPC API - -MetaMask uses the [`window.ethereum.request(args)`](../reference/provider-api.md#windowethereumrequestargs) -method of the [provider API](provider-api.md) to wrap a JSON-RPC API. -The JSON-RPC API contains standard Ethereum JSON-RPC API methods and MetaMask-specific methods. - -:::tip MetaMask API Playground -The RPC methods are documented in the interactive -[MetaMask JSON-RPC API Playground](/wallet/reference/eth_subscribe). -::: - -Methods in the API playground may have the following tags: - -- **MetaMask** - These methods behave in ways specific to MetaMask, and may or may not be supported - by other wallets. - Some of these methods are documented in more detail on the [JSON-RPC reference](../reference/rpc-api.md). -- **Restricted** - These methods are [restricted](#restricted-methods), which require requesting - permission using [`wallet_requestPermissions`](/wallet/reference/wallet_requestpermissions). -- **Mobile** - These methods are only available on MetaMask Mobile. -- **Ethereum API** - These are standard Ethereum JSON-RPC API methods. - See the [Ethereum wiki](https://eth.wiki/json-rpc/API#json-rpc-methods) for more information on - these methods. - -:::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). -::: - -## Restricted methods - -MetaMask introduced web3 wallet permissions in [EIP-2255](https://eips.ethereum.org/EIPS/eip-2255). -In this permissions system, each RPC method is restricted or unrestricted. -If a method is restricted, a dapp must request permission to call it using -[`wallet_requestPermissions`](/wallet/reference/wallet_requestpermissions). -Under the hood, permissions are plain, JSON-compatible objects, with fields that are mostly used -internally by MetaMask. - -Outside of [Snaps restricted methods](/snaps/reference/rpc-api/#restricted-methods), the only -restricted method is [`eth_accounts`](/wallet/reference/eth_accounts), which allows you to access -the user's Ethereum accounts. -More restricted methods will be added in the future. - -## Unrestricted methods - -Unrestricted methods do not require requesting permission to call them, but they might still rely on -permissions to succeed (for example, the signing methods require calling the restricted -[`eth_accounts`](/wallet/reference/eth_accounts) method), or they might require confirmation by the -user (for example, [`wallet_addEthereumChain`](/wallet/reference/wallet_addethereumchain)). - -See the [JSON-RPC API reference](../reference/rpc-api.md) for some MetaMask-specific unrestricted -methods and examples of how to implement them. -For the full list of MetaMask JSON-RPC API methods, see the -[API playground](/wallet/reference/eth_subscribe). diff --git a/wallet/concepts/sdk.md b/wallet/concepts/sdk.md index c83e9677277..3912b8dc54b 100644 --- a/wallet/concepts/sdk.md +++ b/wallet/concepts/sdk.md @@ -3,11 +3,11 @@ description: Learn about MetaMask SDK. sidebar_position: 2 --- -# MetaMask SDK +# What is MetaMask SDK? MetaMask SDK is a library that provides a reliable, secure, and seamless connection from your dapp to the MetaMask browser extension and MetaMask Mobile. -You can install the SDK in existing dapps, and call any [provider API](provider-api.md) methods from +You can install the SDK in existing dapps, and call any [provider API](apis.md) methods from your dapp. :::tip Get started diff --git a/wallet/concepts/signing-methods.md b/wallet/concepts/signing-methods.md index 406227803ad..b3c1cf05d89 100644 --- a/wallet/concepts/signing-methods.md +++ b/wallet/concepts/signing-methods.md @@ -1,6 +1,6 @@ --- description: Learn about the RPC methods for signing transactions in MetaMask. -sidebar_position: 6 +sidebar_position: 5 --- # Signing methods diff --git a/wallet/how-to/connect/access-accounts.md b/wallet/how-to/connect/access-accounts.md index 3738c4e4b5c..88e8d403f6b 100644 --- a/wallet/how-to/connect/access-accounts.md +++ b/wallet/how-to/connect/access-accounts.md @@ -9,7 +9,7 @@ User accounts are used in a variety of contexts in Ethereum, including as identi [signing transactions](../sign-data/index.md). To request a signature from a user or have a user approve a transaction, your dapp must access the user's accounts using the -[`eth_requestAccounts`](../../reference/rpc-api.md#eth_requestaccounts) RPC method. +[`eth_requestAccounts`](/wallet/reference/eth_requestaccounts) RPC method. When accessing a user's accounts: diff --git a/wallet/how-to/interact-with-smart-contracts.md b/wallet/how-to/interact-with-smart-contracts.md index 102f02d6126..53cdba5f06b 100644 --- a/wallet/how-to/interact-with-smart-contracts.md +++ b/wallet/how-to/interact-with-smart-contracts.md @@ -20,8 +20,8 @@ Many dapp developers deploy their contract to a testnet first, in order to avoid disastrous fees if something goes wrong during development and testing on Mainnet. Regardless of which network you deploy your final dapp on, your users must be able to access it. -Use the [`wallet_switchEthereumChain`](../reference/rpc-api.md#wallet_switchethereumchain) and -[`wallet_addEthereumChain`](../reference/rpc-api.md#wallet_addethereumchain) RPC methods to prompt +Use the [`wallet_switchEthereumChain`](/wallet/reference/wallet_switchethereumchain) and +[`wallet_addEthereumChain`](/wallet/reference/wallet_addethereumchain) RPC methods to prompt the user to add a chain that you suggest, and switch to it using a confirmation dialogue. ## Contract address diff --git a/wallet/index.md b/wallet/index.md index 72dfb7c6398..39830a76f17 100644 --- a/wallet/index.md +++ b/wallet/index.md @@ -17,7 +17,7 @@ You can enable users to connect to their MetaMask wallets from the following dap [MetaMask SDK](concepts/sdk.md) is a library that provides a reliable, secure, and seamless connection from your dapp to the MetaMask browser extension and MetaMask Mobile. -With the SDK installed, your dapp can use the [MetaMask Ethereum provider API](concepts/provider-api.md) +With the SDK installed, your dapp can use the [MetaMask Ethereum provider API](concepts/apis.md) to request users' Ethereum accounts, read data from blockchains the user is connected to, suggest that the user sign messages and transactions, and more. ::: diff --git a/wallet/reference/provider-api.md b/wallet/reference/provider-api.md index d1b52ea22ea..2fc096ccf36 100644 --- a/wallet/reference/provider-api.md +++ b/wallet/reference/provider-api.md @@ -5,8 +5,8 @@ sidebar_position: 2 # Ethereum provider API -MetaMask injects the [provider API](../concepts/provider-api.md) into websites visited by its users -using the `window.ethereum` provider object. +MetaMask injects the [provider API](../concepts/apis.md#ethereum-provider-api) into websites visited +by its users using the `window.ethereum` provider object. You can use the provider [properties](#properties), [methods](#methods), and [events](#events) in your dapp. diff --git a/wallet/reference/rpc-api.md b/wallet/reference/rpc-api.md index 61672bc45be..e2fd9ecc3ec 100644 --- a/wallet/reference/rpc-api.md +++ b/wallet/reference/rpc-api.md @@ -7,7 +7,7 @@ toc_max_heading_level: 2 # JSON-RPC API MetaMask uses the [`window.ethereum.request(args)`](provider-api.md#windowethereumrequestargs) -provider method to wrap a [JSON-RPC API](../concepts/rpc-api.md). +provider method to wrap a [JSON-RPC API](../concepts/apis.md#json-rpc-api). The API contains standard Ethereum JSON-RPC API methods and MetaMask-specific methods. :::tip MetaMask API playground @@ -18,7 +18,7 @@ The RPC methods are documented in the interactive For more information on the standard Ethereum RPC methods, see the [Ethereum wiki](https://eth.wiki/json-rpc/API#json-rpc-methods). -The following are some MetaMask-specific [unrestricted methods](../concepts/rpc-api.md#unrestricted-methods). +The following are some MetaMask-specific [unrestricted methods](../concepts/apis.md#unrestricted-methods). For the full list of MetaMask JSON-RPC API methods, see the [API playground](/wallet/reference/eth_subscribe).