Update permission system documentation (MetaMask#348)

* Update permission system documentation The RPC API documentation about the permission system has been updated to reflect the current terminology we use, and to reflect recent changes. The term "open methods" has been dropped in favor of "unrestricted methods", which is more in-line with "restricted methods" and is what we have been calling them in practice. The wording was updated to no longer imply that a _domain_ is the permission subject. Now it just says "caller" instead, which is just as clear but leaves open the possibility that the caller is not a website. This was done in preparation for Snaps, since snaps can also call RPC methods. The note on the implementation was removed, since the permission system no longer uses `rpc-cap`. I removed it rather than linking the new implementation because it's not really in a state where it would be easy to understand or re-use. The decryption methods were pulled into the "restricted methods" section because they are restricted methods. The "Other RPC Methods" header has been renamed to "Unrestricted Methods". The old title was silly; this section was alongside the header "Restricted Methods" so it always meant to refer to unrestricted methods. * Recategorize encryption methods as unrestricted The decryption-related methods have been moved back to the "Unrestricted Methods" section because they have no corresponding permissions. Instead the definition of "Unrestricted method" was updated to no longer imply that no permissions were needed. Instead it just means that there is no permission directly corresponding with that RPC method. In a later PR we will add more warnings about this constraint. We may reconsider the terminology/categorization as well.
hainguyen99-cdm · Jan 18, 2022 · b4efc2c · b4efc2c
1 parent 30a5161
commit b4efc2c
Show file tree

Hide file tree

Showing 2 changed files with 6 additions and 7 deletions.
diff --git a/docs/guide/provider-migration.md b/docs/guide/provider-migration.md
@@ -136,7 +136,7 @@ ethereum.on('chainChanged', (chainId) => {
 Before the new provider API shipped, we added the `_metamask.isEnabled` and `_metamask.isApproved` methods
 to enable web3 sites to check if they have [access to the user's accounts](./rpc-api.html#eth-requestaccounts).
 `isEnabled` and `isApproved` functioned identically, except that `isApproved` was `async`.
-These methods were arguably never that useful, and they became completely redundant with the introduction of MetaMask's [permission system](./rpc-api.html#permissions).
+These methods were arguably never that useful, and they became completely redundant with the introduction of MetaMask's [permission system](./rpc-api.html#restricted-methods).
 
 We recommend that you check for account access in the following ways:
 

diff --git a/docs/guide/rpc-api.md b/docs/guide/rpc-api.md
@@ -29,12 +29,12 @@ Important methods from this API include:
 - [`eth_sendTransaction`](https://eth.wiki/json-rpc/API#eth_sendtransaction)
 - [`eth_sign`](https://eth.wiki/json-rpc/API#eth_sign)
 
-## Permissions
+## Restricted Methods
 
 MetaMask introduced Web3 Wallet Permissions via [EIP-2255](https://eips.ethereum.org/EIPS/eip-2255).
-In this permissions system, each RPC method is either _restricted_ or _open_.
-If a method is restricted, an external _domain_ (like a web3 site) must have the corresponding permission in order to call it.
-Open methods, meanwhile, do not require permissions to call, but may require confirmation by the user in order to succeed (e.g. `wallet_addEthereumChain`).
+In this permissions system, each RPC method is either _restricted_ or _unrestricted_.
+If a method is restricted, the caller must have the corresponding permission in order to call it.
+Unrestricted methods, meanwhile, have no corresponding permission. Some of them still rely upon permissions to succeed though (e.g. the signing methods require that you have the `eth_accounts` permission for the signer account), and some require confirmation by the user (e.g. `wallet_addEthereumChain`).
 
 Currently, the only permission is `eth_accounts`, which allows you to access the user's Ethereum address(es).
 More permissions will be added in the future.
@@ -52,7 +52,6 @@ interface Web3WalletPermission {
 }
 ```
 
-The permissions system is implemented in the [`rpc-cap` package](https://github.com/MetaMask/rpc-cap).
 If you're interested in learning more about the theory behind this _capability_-inspired permissions system, we encourage you to take a look at [EIP-2255](https://eips.ethereum.org/EIPS/eip-2255).
 
 ### `eth_requestAccounts`
@@ -178,7 +177,7 @@ function requestPermissions() {
 }
 ```
 
-## Other RPC Methods
+## Unrestricted Methods
 
 ### `eth_decrypt`