Document snap_getClientStatus (#1119)

MetaMask · Feb 14, 2024 · f53ea78 · f53ea78
1 parent a3d7129
commit f53ea78
Show file tree

Hide file tree

Showing 5 changed files with 89 additions and 32 deletions.
diff --git a/snaps/how-to/use-custom-ui.md b/snaps/how-to/use-custom-ui.md
@@ -36,7 +36,7 @@ return content;
 
 The `NodeType` enum exported by `@metamask/snaps-ui` details the available components.
 
-### copyable
+### `copyable`
 
 Outputs a read-only text field with a copy-to-clipboard shortcut.
 
@@ -48,7 +48,7 @@ import { copyable } from '@metamask/snaps-ui';
 const content = copyable('Text to be copied');
 ```
 
-### divider
+### `divider`
 
 Outputs a horizontal divider.
 
@@ -64,7 +64,7 @@ const content = panel([
 ]);
 ```
 
-### heading
+### `heading`
 
 Outputs a heading.
 This is useful for [panel](#panel) titles.
@@ -80,7 +80,7 @@ const content = panel([
 ]);
 ```
 
-### image
+### `image`
 
 Outputs an image. 
 This component takes an inline SVG. 
@@ -96,7 +96,7 @@ import { image } from '@metamask/snaps-ui';
 const content = image('<svg width="400" height="400" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="m2.514 17.874 9 5c.021.011.043.016.064.026s.051.021.078.031a.892.892 0 0 0 .688 0c.027-.01.052-.019.078-.031s.043-.015.064-.026l9-5A1 1 0 0 0 22 16.9L21 7V2a1 1 0 0 0-1.625-.781L14.649 5h-5.3L4.625 1.219A1 1 0 0 0 3 2v4.9l-1 10a1 1 0 0 0 .514.974ZM5 7V4.081l3.375 2.7A1 1 0 0 0 9 7h6a1 1 0 0 0 .625-.219L19 4.079V7.1l.934 9.345L13 20.3v-2.967l1.42-.946A1.3 1.3 0 0 0 15 15.3a1.3 1.3 0 0 0-1.3-1.3h-3.4A1.3 1.3 0 0 0 9 15.3a1.3 1.3 0 0 0 .58 1.084l1.42.946v2.97l-6.94-3.855Zm3.5 6a2 2 0 1 1 2-2 2 2 0 0 1-2 2Zm5-2a2 2 0 1 1 2 2 2 2 0 0 1-2-2Z"/></svg>');
 ```
 
-### panel
+### `panel`
 
 Outputs a panel, which can be used as a container for other components.
 
@@ -114,7 +114,7 @@ const content = panel([
 ]);
 ```
 
-### spinner
+### `spinner`
 
 Outputs a loading indicator.
 
@@ -126,7 +126,7 @@ import { panel, heading, spinner } from '@metamask/snaps-ui';
 const content = panel([heading('Please wait...'), spinner()]);
 ```
 
-### text
+### `text`
 
 Outputs text.
 

diff --git a/snaps/reference/entry-points.md b/snaps/reference/entry-points.md
@@ -6,7 +6,7 @@ description: See the Snaps entry points reference.
 
 Snaps can expose the following entry points.
 
-## onRpcRequest
+## `onRpcRequest`
 
 To implement a [custom JSON-RPC API](../concepts/apis.md#custom-json-rpc-apis) to communicate with
 dapps and other Snaps, a Snap must expose the `onRpcRequest` entry point.
@@ -67,7 +67,7 @@ module.exports.onRpcRequest = async ({ origin, request }) => {
 
 <!--/tabs-->
 
-## onTransaction
+## `onTransaction`
 
 To provide transaction insights before a user signs a transaction, a Snap must expose the
 `onTransaction` entry point.
@@ -205,7 +205,7 @@ module.exports.onTransaction = async ({
 
 <!--/tabs-->
 
-## onCronjob
+## `onCronjob`
 
 To run periodic actions for the user (cron jobs), a Snap must expose the `onCronjob` entry point.
 MetaMask calls the `onCronjob` handler method at the specified times with the specified payloads
@@ -216,6 +216,11 @@ For MetaMask to call the Snap's `onCronjob` method, you must request the
 [`endowment:cronjob`](permissions.md#endowmentcronjob) permission.
 :::
 
+If the cron job's logic requires access to encrypted state, you can use
+[`snap_getClientStatus`](../reference/snaps-api.md#snap_getclientstatus) to ensure that MetaMask is
+unlocked before accessing state.
+This will prevent an unexpected password request popup, improving the user's experience.
+
 #### Parameters
 
 An object containing an RPC request specified in the `endowment:cronjob` permission.
@@ -268,7 +273,7 @@ module.exports.onCronjob = async ({ request }) => {
 
 <!--/tabs-->
 
-## onInstall
+## `onInstall`
 
 To run an action on installation, a Snap must expose the `onInstall` entry point.
 MetaMask calls the `onInstall` handler method after the Snap is installed successfully. 
@@ -332,7 +337,7 @@ module.exports.onInstall = async () => {
 
 <!--/tabs-->
 
-## onUpdate
+## `onUpdate`
 
 To run an action on update, a Snap must expose the `onUpdate` entry point.
 MetaMask calls the `onUpdate` handler method after the Snap is updated successfully. 
@@ -402,7 +407,7 @@ module.exports.onUpdate = async () => {
 
 <!--/tabs-->
 
-## onHomePage
+## `onHomePage`
 
 :::flaskOnly
 :::

diff --git a/snaps/reference/permissions.md b/snaps/reference/permissions.md
@@ -23,7 +23,7 @@ manifest file:
 
 ## Endowments
 
-### endowment:cronjob
+### `endowment:cronjob`
 
 To run periodic actions for the user (cron jobs), a Snap must request the `endowment:cronjob` permission.
 This permission allows the Snap to specify cron jobs that trigger the
@@ -59,7 +59,7 @@ Specify this permission in the manifest file as follows:
 
 ```
 
-### endowment:ethereum-provider
+### `endowment:ethereum-provider`
 
 To communicate with a node using MetaMask, a Snap must request the `endowment:ethereum-provider` permission.
 This permission exposes the `ethereum` global to the Snap execution environment, allowing Snaps to
@@ -79,7 +79,7 @@ The `ethereum` global available to Snaps has fewer capabilities than `window.eth
 See the [list of methods](../concepts/apis.md#metamask-json-rpc-api) not available to Snaps.
 :::
 
-### endowment:page-home
+### `endowment:page-home`
 
 :::flaskOnly
 :::
@@ -97,7 +97,7 @@ Specify this permission in the manifest file as follows:
 }
 ```
 
-### endowment:keyring
+### `endowment:keyring`
 
 :::flaskOnly
 :::
@@ -117,7 +117,7 @@ Specify this permission in the manifest file as follows:
 }
 ```
 
-### endowment:lifecycle-hooks
+### `endowment:lifecycle-hooks`
 
 To run an action when the user installs or updates the Snap, a Snap must request the `endowment:lifecycle-hooks` permission.
 This permission allows the Snap to expose the 
@@ -133,7 +133,7 @@ Specify this permission in the manifest file as follows:
 }
 ```
 
-### endowment:network-access
+### `endowment:network-access`
 
 To access the internet, a Snap must request the `endowment:network-access` permission.
 This permission exposes the global `fetch` API to the Snaps execution environment.
@@ -161,7 +161,7 @@ For the Snap to be able to read the response, the server must send an
 [`Access-Control-Allow-Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) CORS header
 with the value `*` or `null` in the response.
 
-### endowment:rpc
+### `endowment:rpc`
 
 To handle arbitrary JSON-RPC requests, a Snap must request the `endowment:rpc` permission.
 This permission grants a Snap access to JSON-RPC requests sent to the Snap, using the
@@ -203,7 +203,7 @@ Specify this caveat in the manifest file as follows:
 If you specify `allowedOrigins`, you should not specify `dapps` or `snaps`. 
 :::
 
-### endowment:transaction-insight
+### `endowment:transaction-insight`
 
 To provide transaction insights, a Snap must request the `endowment:transaction-insight` permission.
 This permission grants a Snap read-only access to raw transaction payloads, before they're accepted
@@ -225,7 +225,7 @@ Specify this permission in the manifest file as follows:
 }
 ```
 
-### endowment:webassembly
+### `endowment:webassembly`
 
 To use WebAssembly, a Snap must request the `endowment:webassembly` permission.
 This permission exposes the global `WebAssembly` API to the Snap execution environment.
@@ -240,7 +240,7 @@ Specify this permission in the manifest file as follows:
 
 ## Dynamic permissions
 
-### eth_accounts
+### `eth_accounts`
 
 A Snap can request permission to call the [`eth_accounts`](/wallet/reference/eth_accounts) MetaMask
 JSON-RPC API method by calling [`eth_requestAccounts`](/wallet/reference/eth_requestaccounts).

diff --git a/snaps/reference/snaps-api.md b/snaps/reference/snaps-api.md
@@ -9,12 +9,16 @@ Snaps can communicate with and modify the functionality of MetaMask using the [S
 To call each method, you must first [request permission](../how-to/request-permissions.md) in the Snap
 manifest file.
 
-## snap_dialog
+## `snap_dialog`
 
 Displays a dialog in the MetaMask UI.
 There are three types of dialogs with different parameters and return types: [alert](#alert-dialog),
 [confirmation](#confirmation-dialog), and [prompt](#prompt-dialog).
 
+:::caution
+Dialogs do not work when MetaMask is locked. To check if MetaMask is locked, use [`snap_getClientStatus`](#snap_getclientstatus).
+:::
+
 ### Alert dialog
 
 Displays an alert that can only be acknowledged.
@@ -117,7 +121,7 @@ const walletAddress = await snap.request({
 // `walletAddress` will be a string containing the address entered by the user
 ```
 
-## snap_getBip32Entropy
+## `snap_getBip32Entropy`
 
 :::danger important
 If you call this method, you receive the user's parent key for the derivation path they request.
@@ -205,7 +209,7 @@ const accountKey1 = await dogecoinSlip10Node.derive(["bip32:1'"]);
 
 <!--/tabs-->
 
-## snap_getBip32PublicKey
+## `snap_getBip32PublicKey`
 
 Gets the [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) public key for the
 derivation path specified by the `path` parameter.
@@ -264,7 +268,7 @@ console.log(dogecoinPublicKey);
 
 <!--/tabs-->
 
-## snap_getBip44Entropy
+## `snap_getBip44Entropy`
 
 :::danger important
 If you call this method, you receive the user's parent key for the protocol they request.
@@ -358,7 +362,44 @@ const addressKey1 = await deriveDogecoinAddress(1);
 
 <!--/tabs-->
 
-## snap_getEntropy
+## `snap_getClientStatus`
+
+Gets the locked status of the Snaps client.
+
+It is useful to check if MetaMask is locked in the following situations:
+
+- When running background operations that require MetaMask to be unlocked, for example, [accessing encrypted state](#snap_managestate). If MetaMask is locked, the user gets a popup asking them to enter their password, which might be unexpected or confusing.
+- When [displaying a dialog](#snap_dialog). Dialogs do not work when MetaMask is locked.
+
+### Returns
+
+`true` if MetaMask is locked, `false` if MetaMask is unlocked.
+
+### Example
+
+```typescript
+import type { OnCronjobHandler } from '@metamask/snaps-sdk';
+import { MethodNotFoundError } from '@metamask/snaps-sdk';
+
+export const onCronjob: OnCronjobHandler = async ({ request }) => {
+  switch (request.method) {
+    case 'execute':
+      // Find out if MetaMask is locked
+      const { locked } = await snap.request({
+        method: 'snap_getClientStatus'
+      });
+
+      if (!locked) {
+        // Do something that requires MetaMask to be unlocked, like access encrypted state
+      }
+
+    default:
+      throw new MethodNotFoundError();
+  }
+};
+```
+
+## `snap_getEntropy`
 
 Gets a deterministic 256-bit entropy value, specific to the Snap and the user's account.
 You can use this entropy to generate a private key, or any other value that requires a high level of
@@ -412,7 +453,7 @@ console.log(entropy);
 
 <!--/tabs-->
 
-## snap_getLocale
+## `snap_getLocale`
 
 :::flaskOnly
 :::
@@ -446,7 +487,7 @@ await snap.request({
 });
 ```
 
-## snap_manageAccounts
+## `snap_manageAccounts`
 
 :::flaskOnly
 :::
@@ -675,11 +716,18 @@ class MyKeyring implements Keyring {
 }
 ```
 
-## snap_manageState
+## `snap_manageState`
 
 Allows the Snap to persist up to 100 MB of data to disk and retrieve it at will.
 The data is automatically encrypted using a Snap-specific key and automatically decrypted when retrieved.
 
+:::note
+Accessing encrypted state requires MetaMask to be unlocked.
+If you need to access encrypted state in a background task such as a cron job, you can use
+[`snap_getClientStatus`](#snap_getclientstatus) to ensure that MetaMask is unlocked, preventing an
+unexpected password request popup.
+:::
+
 ### Parameters
 
 An object containing:
@@ -716,7 +764,7 @@ await snap.request({
 });
 ```
 
-## snap_notify
+## `snap_notify`
 
 Displays a notification in MetaMask or natively in the browser.
 Snaps can trigger a short notification text for actionable or time sensitive information.

diff --git a/src/css/custom.css b/src/css/custom.css
@@ -168,4 +168,8 @@ svg {
       font-size: inherit;
     }
   }
+}
+
+.table-of-contents code {
+  font-size: inherit;
 }