Add docs for endowment:rpc (MetaMask#595)

* Add docs for endowment:rpc * Small changes * Run lint:fix * Update docs/guide/snaps-exports.md Co-authored-by: legobeat <[email protected]> * Add warning to development guide too --------- Co-authored-by: legobeat <[email protected]> Co-authored-by: Frederik Bolding <[email protected]>
readyalid · Feb 16, 2023 · 76b9417 · 76b9417
1 parent 3e17184
commit 76b9417
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 5 deletions.
diff --git a/docs/guide/snaps-development-guide.md b/docs/guide/snaps-development-guide.md
@@ -79,6 +79,10 @@ module.exports.onRpcRequest = async ({ origin, request }) => {
 In order to communicate with the outside world, the snap must implement its own JSON-RPC API by exposing an exported function called `onRpcRequest`.
 Whenever the snap receives a JSON-RPC request from an external entity (a dapp or even another snap), this handler function will be called with the above parameters.
 
+::: warning Requesting the JSON-RPC permission
+In order for the extension to call the `onRpcRequest` method of the snap, the `endowment:rpc` permission must be requested. See [Permissions](./snaps-permissions.html#endowment-rpc)
+:::
+
 In addition to being able to expose a JSON-RPC API, snaps can access the global object `wallet`.
 This object exposes a very similar API to the one exposed to dapps via `window.ethereum`.
 Any message sent via `wallet.request()` will be received and processed by MetaMask.

diff --git a/docs/guide/snaps-exports.md b/docs/guide/snaps-exports.md
@@ -20,17 +20,21 @@ In order to communicate with dapps and other snaps, the snap must implement its
 Well, no, that's also up to you! If your snap can do something useful without receiving and responding to JSON-RPC requests, then you can skip exporting onRpcRequest. However, if you want to do something like manage the user's keys for a particular protocol and create a dapp that sends transactions for that protocol via your snap, for example, you need to specify an RPC API.
 :::
 
+::: warning Requesting the JSON-RPC permission
+In order for the extension to call the `onRpcRequest` method of the snap, the `endowment:rpc` permission must be requested. See [Permissions](./snaps-permissions.html#endowment-rpc)
+:::
+
 ### Parameters
 
 - `RpcHandlerArgs` - The origin and the JSON-RPC request.
 
 ```typescript
 import { JsonRpcRequest } from '@metamask/types';
 
-interface RpcHandlerArgs = {
+interface RpcHandlerArgs {
   origin: string;
   request: JsonRpcRequest<unknown[] | { [key: string]: unknown }>;
-};
+}
 ```
 
 ### Returns
@@ -80,7 +84,7 @@ module.exports.onRpcRequest = async ({ origin, request }) => {
 
 If the snap wants to provide transaction insights before a user signs a transaction, the snap must export a function called `onTransaction`. Whenever there is a contract interaction and a transaction is submitted via the extension, this function will be called. The raw unsigned transaction payload will be passed to the `onTransaction` handler function.
 
-::: tip Requesting the transaction insight permission
+::: warning Requesting the transaction insight permission
 In order for the extension to call the `onTransaction` method of the snap, the `endowment:transaction-insight` permission must be requested. see [Permissions](./snaps-permissions.html#endowment-transaction-insight)
 :::
 

diff --git a/docs/guide/snaps-permissions.md b/docs/guide/snaps-permissions.md
@@ -16,6 +16,23 @@ To access certain powerful JavaScript globals or JSON-RPC methods, your snap wil
 
 ## Endowments
 
+### `endowment:rpc`
+
+For snaps that need to handle arbitrary JSON-RPC requests, the `rpc` endowment is required. This permission grants a snap access to JSON-RPC requests sent to the snap, using the `onRpcRequest` method. See [Exports](./snaps-exports.html#onrpcrequest) for more information.
+
+This permission requires an object with a `snaps` or `dapps` property (or both), to signal if the snap can receive JSON-RPC requests from other snaps, or dapps, respectively. Both values default to `false`.
+
+```json
+{
+  "initialPermissions": {
+    "endowment:rpc": {
+      "dapps": true,
+      "snaps": false
+    }
+  }
+}
+```
+
 ### `endowment:long-running`
 
 For snaps that are computationally heavy and can't finish execution within [the snap lifecycle requirements](./snaps-development-guide.md#the-snap-lifecycle), the snap can request the `endowment:long-running` permission.
@@ -31,7 +48,7 @@ For snaps that need to access the internet, the snap can request the `endowment:
 
 ### `endowment:transaction-insight`
 
-For snaps that provide transaction insights, the snap can request the `endowment:transaction-insight` permission. This permission grants a snap read-only access to raw transaction payloads, before they are accepted for signing by the user, by exporting the `onTransaction` method. see [Exports](./snaps-exports.html#ontransaction)
+For snaps that provide transaction insights, the snap can request the `endowment:transaction-insight` permission. This permission grants a snap read-only access to raw transaction payloads, before they are accepted for signing by the user, by exporting the `onTransaction` method. See [Exports](./snaps-exports.html#ontransaction) for more information.
 
 ### `endowment:cronjob`
 
@@ -76,4 +93,4 @@ Cronjobs are specified as follows:
 
 ## RPC Permissions
 
-To use any restricted RPC method, a snap will need to request permissions to access that method. For a list of available RPC methods and thus valid RPC permissions see [JSON-RPC API](./snaps-rpc-api.html#restricted-methods)
+To use any restricted RPC method, a snap will need to request permissions to access that method. For a list of available RPC methods and thus valid RPC permissions see [JSON-RPC API](./snaps-rpc-api.html#restricted-methods).