Update Keyring API reference (MetaMask#1170)

* Update Keyring API reference * document interface api * document events, objects, and other edits * fix links * add descriptions and example for filterAccountChains * rename and edit APIs * clarify scope and filterAccountChains
chairulakmal · Mar 4, 2024 · 6f3be19 · 6f3be19
1 parent 1d195ae
commit 6f3be19
Show file tree

Hide file tree

Showing 28 changed files with 1,406 additions and 349 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -1,4 +1,3 @@
 /build
 /.yarn
 /static/js/feedback-script.js
-/external/keyring-api
diff --git a/.github/workflows/build-lint.yml b/.github/workflows/build-lint.yml
@@ -12,8 +12,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-        with:
-          submodules: true
       - name: Use Node.js
         uses: actions/setup-node@v3
         with:
@@ -29,8 +27,6 @@ jobs:
       - prepare
     steps:
       - uses: actions/checkout@v3
-        with:
-          submodules: true
       - name: Use Node.js
         uses: actions/setup-node@v3
         with:
@@ -55,8 +51,6 @@ jobs:
       - prepare
     steps:
       - uses: actions/checkout@v3
-        with:
-          submodules: true
       - name: Use Node.js
         uses: actions/setup-node@v3
         with:

diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -23,7 +23,6 @@ jobs:
         uses: actions/checkout@v3
         with:
           ref: ${{ inputs.ref }}
-          submodules: true
       - name: Use Node.js
         uses: actions/setup-node@v3
         with:

diff --git a/.gitignore b/.gitignore
@@ -8,7 +8,6 @@
 .docusaurus
 .cache-loader
 .idea
-/snaps/reference/keyring-api
 
 # yarn v3 (w/o zero-install)
 # See: https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored

diff --git a/.gitmodules b/.gitmodules
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -3,7 +3,6 @@
 
 const codeTheme = require("prism-react-renderer/themes/dracula");
 const remarkCodesandbox = require("remark-codesandbox");
-const path = require("path");
 const isProd = process.env.NODE_ENV === "production";
 
 /** @type {import('@docusaurus/types').Config} */
@@ -114,22 +113,6 @@ const config = {
         breadcrumbs: false,
       },
     ],
-    [
-      "docusaurus-plugin-typedoc",
-      {
-        entryPoints: ["./external/keyring-api/src/index.ts"],
-        tsconfig: "./external/keyring-api/tsconfig.json",
-        readme: "snaps/reference/keyring-api-index/index.md",
-        out: path.join(__dirname, "snaps/reference/keyring-api"),
-        sidebar: {
-          filteredIds: ["reference/keyring-api/index"],
-        },
-        useCodeBlocks: true,
-        expandObjects: true,
-        parametersFormat: "table",
-        hideGenerator: true,
-      },
-    ],
     [
       "@docusaurus/plugin-client-redirects",
       {

diff --git a/external/keyring-api b/external/keyring-api
diff --git a/package.json b/package.json
@@ -15,8 +15,7 @@
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "postinstall": "cd external/keyring-api && yarn install"
+    "lint:fix": "eslint . --fix"
   },
   "dependencies": {
     "@docusaurus/core": "2.4.3",
@@ -28,17 +27,14 @@
     "@metamask/docusaurus-openrpc": "^0.3.1",
     "clsx": "^1.2.1",
     "docusaurus-plugin-segment": "^1.0.4",
-    "docusaurus-plugin-typedoc": "1.0.0-next.17",
     "node-polyfill-webpack-plugin": "^2.0.1",
     "prettier": "^3.0.0",
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
     "react-player": "^2.13.0",
     "remark-codesandbox": "^0.10.1",
-    "remark-docusaurus-tabs": "^0.2.0",
-    "typedoc": "^0.25.1",
-    "typedoc-plugin-markdown": "4.0.0-next.22"
+    "remark-docusaurus-tabs": "^0.2.0"
   },
   "devDependencies": {
     "@docusaurus/eslint-plugin": "2.4.3",

diff --git a/snaps-sidebar.js b/snaps-sidebar.js
@@ -50,56 +50,7 @@ const sidebar = {
       label: "Reference",
       link: { type: "generated-index", slug: "/reference" },
       collapsed: false,
-      items: [
-        {
-          type: "doc",
-          id: "reference/snaps-api",
-        },
-        {
-          type: "doc",
-          id: "reference/entry-points",
-        },
-        {
-          type: "doc",
-          id: "reference/permissions",
-        },
-        {
-          type: "doc",
-          id: "reference/known-errors",
-        },
-        {
-          type: "category",
-          label: "Snaps command line",
-          link: { type: "generated-index", slug: "reference/cli" },
-          items: [
-            {
-              type: "doc",
-              id: "reference/cli/options",
-            },
-            {
-              type: "doc",
-              id: "reference/cli/subcommands",
-            },
-          ],
-        },
-        {
-          type: "doc",
-          id: "reference/jest",
-        },
-        {
-          type: "category",
-          label: "Keyring API",
-          link: {
-            type: "doc",
-            id: "reference/keyring-api/index",
-          },
-          items: require("./snaps/reference/keyring-api/typedoc-sidebar.cjs"),
-        },
-        {
-          type: "doc",
-          id: "reference/resources",
-        },
-      ],
+      items: [{ type: "autogenerated", dirName: "reference" }],
     },
   ],
 };

diff --git a/snaps/features/custom-evm-accounts/create-account-snap.md b/snaps/features/custom-evm-accounts/create-account-snap.md
@@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
 Create an account management Snap to connect to custom EVM accounts.
 
 :::tip see also
-- [About custom EVM accounts](index.md)
+- [Custom EVM accounts](index.md)
 - [Create an account management companion dapp](create-companion-dapp.md)
 - [Account management Snap security guidelines](security.md)
 - [Keyring API reference](../../reference/keyring-api/index.md)
@@ -29,7 +29,8 @@ Create an account management Snap to connect to custom EVM accounts.
 
 ### 1. Install the Keyring API
 
-Install `@metamask/keyring-api` in your project directory using Yarn or npm:
+Install the [`@metamask/keyring-api`](https://github.com/MetaMask/keyring-api) module in your
+project directory using Yarn or npm:
 
 ```bash
 yarn add @metamask/keyring-api
@@ -63,9 +64,10 @@ Specify the following [permissions](../../how-to/request-permissions.md) in your
 Add a list of dapp URLs allowed to call Keyring API methods on your Snap using the
 [`endowment:keyring`](../../reference/permissions.md#endowmentkeyring) permission.
 
-### 3. Implement the Keyring API
+### 3. Implement the Account Management API
 
-Implement the [required Keyring API methods](security.md#limit-the-methods-exposed-to-dapps) in your Snap:
+Implement the [Account Management API](../../reference/keyring-api/account-management/index.md) in your Snap.
+Make sure to [limit the methods exposed to dapps](security.md#limit-the-methods-exposed-to-dapps).
 
 ```typescript
 class MySnapKeyring implements Keyring {
@@ -75,11 +77,11 @@ class MySnapKeyring implements Keyring {
 
 ### 4. Handle requests submitted by MetaMask
 
-MetaMask submits Ethereum sign requests from dapps using the
-[`submitRequest`](../../reference/keyring-api/type-aliases/Keyring.md#submitrequest) method of the
-Keyring API.
-See the methods for [externally owned accounts](index.md#eoa-methods) and
-[ERC-4337 accounts](index.md#account-abstraction-erc-4337).
+MetaMask submits EVM requests from dapps using the
+[`keyring_submitRequest`](../../reference/keyring-api/account-management/index.md#keyring_submitrequest)
+method of the Keyring API.
+See the EVM methods for [externally owned accounts](../../reference/keyring-api/chain-methods.md#eoa-methods)
+and [ERC-4337 accounts](../../reference/keyring-api/chain-methods.md#erc-4337-methods).
 
 The following is an example of a `personal_sign` request:
 
@@ -130,88 +132,25 @@ The redirect message and URL is displayed to the user to help them continue the
 
 ### 5. Notify MetaMask about events
 
-Notify MetaMask when the following events take place, using the `emitSnapKeyringEvent()` helper function:
-
-- An account is created:
-
-   ```typescript
-   try {
-     emitSnapKeyringEvent(snap, KeyringEvent.AccountCreated, { account });
-     // Update your Snap's state...
-   } catch (error) {
-     // Handle the error...
-   }
-   ```
-
-   MetaMask returns an error if the account already exists or the account object is invalid.
-
-- An account is updated:
-
-   ```typescript
-   try {
-     emitSnapKeyringEvent(snap, KeyringEvent.AccountUpdated, { account });
-     // Update your Snap's state...
-   } catch (error) {
-     // Handle the error...
-   }
-   ```
-
-   MetaMask returns an error if the account does not exist, the account object is invalid, or the
-   account address changes.
-
-- An account is deleted:
-
-   ```typescript
-   try {
-     emitSnapKeyringEvent(snap, KeyringEvent.AccountDeleted, {
-       id: account.id,
-     });
-     // Update your Snap's state...
-   } catch (error) {
-     // Handle the error...
-   }
-   ```
-
-   The delete event is idempotent, so it is safe to emit even if the account does not exist.
-
-- A request is approved:
-
-   ```typescript
-   try {
-     emitSnapKeyringEvent(snap, KeyringEvent.RequestApproved, {
-       id: request.id,
-       result,
-     });
-     // Update your Snap's state...
-   } catch (error) {
-     // Handle the error...
-   }
-   ```
-
-   MetaMask returns an error if the request does not exist.
-   This event only applies to Snaps that implement the
-   [asynchronous transaction flow](index.md#asynchronous-transaction-flow).
-
-- A request is rejected:
-
-   ```typescript
-   try {
-     emitSnapKeyringEvent(snap, KeyringEvent.RequestRejected, {
-       id: request.id,
-     });
-     // Update your Snap's state...
-   } catch (error) {
-     // Handle the error...
-   }
-   ```
-
-   MetaMask returns an error if the request does not exist.
-   This event only applies to Snaps that implement the
-   [asynchronous transaction flow](index.md#asynchronous-transaction-flow).
-
-### 6. Expose the Keyring API
-
-Create an `onKeyringRequest` entry point handler method to expose the Keyring API methods
+Notify MetaMask when [Account Management API events](../../reference/keyring-api/account-management/events.md)
+take place, using the `emitSnapKeyringEvent()` helper function.
+
+For example, when an account is created:
+
+```typescript
+try {
+    emitSnapKeyringEvent(snap, KeyringEvent.AccountCreated, { account });
+    // Update your Snap's state...
+} catch (error) {
+    // Handle the error...
+}
+```
+
+MetaMask returns an error if the account already exists or the account object is invalid.
+
+### 6. Expose the Account Management API
+
+Create an `onKeyringRequest` entry point handler method to expose the Account Management API methods
 to MetaMask and your dapp:
 
 ```typescript

diff --git a/snaps/features/custom-evm-accounts/create-companion-dapp.md b/snaps/features/custom-evm-accounts/create-companion-dapp.md
@@ -9,12 +9,11 @@ tags:
 # Create an account management companion dapp
 
 Create a companion dapp to provide a user interface for your account management Snap.
-Use the [`KeyringSnapRpcClient`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md) to
-call Keyring API methods from your companion dapp, enabling users to create and interact with custom
+Call Keyring API methods from your companion dapp, enabling users to create and interact with custom
 EVM accounts.
 
 :::tip see also
-- [About custom EVM accounts](index.md)
+- [Custom EVM accounts](index.md)
 - [Create an account management Snap](create-account-snap.md)
 - [Keyring API reference](../../reference/keyring-api/index.md)
 :::
@@ -27,7 +26,8 @@ An [account management Snap](create-account-snap.md) set up.
 
 ### 1. Install the Keyring API
 
-Install `@metamask/keyring-api` in your project directory using Yarn or npm:
+Install the [`@metamask/keyring-api`](https://github.com/MetaMask/keyring-api) module in your
+project directory using Yarn or npm:
 
 ```bash
 yarn add @metamask/keyring-api
@@ -39,9 +39,9 @@ or
 npm install @metamask/keyring-api
 ```
 
-### 2. Create the KeyringSnapRpcClient
+### 2. Create a KeyringSnapRpcClient
 
-Create the [`KeyringSnapRpcClient`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md):
+Create a `KeyringSnapRpcClient`:
 
 ```ts
 import { KeyringSnapRpcClient } from "@metamask/keyring-api";
@@ -50,12 +50,12 @@ import { defaultSnapOrigin as snapId } from '../config';
 let client = new KeyringSnapRpcClient(snapId, window.ethereum);
 ```
 
-### 3. Call Keyring API methods
+### 3. Call Account Management API methods
 
-You can now use the [`KeyringSnapRpcClient`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md)
-to invoke Keyring API methods on your Snap.
+You can now use the `KeyringSnapRpcClient` to invoke
+[Account Management API](../../reference/keyring-api/account-management/index.md) methods on your Snap.
 
-For example, to call [`keyring_listAccounts`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md#listaccounts):
+For example, to call [`keyring_listAccounts`](../../reference/keyring-api/account-management/index.md#keyringlist_accounts):
 
 ```typescript
 const accounts = await client.listAccounts();