From f046ae09c949f3d333fba47e659b4cbd29bcbfce Mon Sep 17 00:00:00 2001 From: Daniel Rocha Date: Tue, 24 Oct 2023 16:12:28 +0200 Subject: [PATCH] docs: minor fixes to the docs (#174) * docs: remove note about the module style * docs: fix line wrapping * docs: fix capitalization * docs: update `snap_manageAccounts` arguments (`event` -> `notify`) --- README.md | 6 ++---- docs/architecture.md | 48 ++++++++++++++++++++++---------------------- 2 files changed, 26 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 97c49a228..a9510c931 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # MetaMask Keyring API -> This TypeScript module is maintained in the style of the MetaMask team. - This TypeScript module simplifies the integration of Snaps with MetaMask using the Keyring API. @@ -43,8 +41,8 @@ Starting with MetaMask 11.4, Snaps can implement the Keyring API. This allows users to manage their accounts in a more flexible way, and enables developers to build new types of accounts. -> **:point_up: Important**: Before implementing your Snap, please make sure to read the -> [security recommendations](./docs/security.md) and the [architecture +> **:point_up: Important**: Before implementing your Snap, please make sure to +> read the [security recommendations](./docs/security.md) and the [architecture > document](./docs/architecture.md). Follow these steps to implement the Keyring API in your Snap. Please note that diff --git a/docs/architecture.md b/docs/architecture.md index 23266fee5..3bf817126 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -12,16 +12,16 @@ Let's introduce some terminology used across the Keyring API: - **Keyring account**: Is an account model that represents one or more blockchain accounts. -- **Keyring snap**: A snap that implements the Keyring API. +- **Keyring Snap**: A Snap that implements the Keyring API. -- **Keyring request**: A request from MetaMask to a keyring snap, to perform an - action on or using a keyring account. It wraps the original request sent by +- **Keyring request**: A request from MetaMask to a Keyring Snap to perform an + action on, or using, a keyring account. It wraps the original request sent by the dapp and adds some metadata to it. ## Components diagram In most use cases, we will encounter the following components when interacting -with an account managed by a keyring snap: +with an account managed by a Keyring Snap: ```mermaid graph TD @@ -29,27 +29,27 @@ graph TD Dapp -->|Submits a request| MetaMask MetaMask -->|Submits requests
and manages accounts| Snap Site[Snap Dapp] -->|Manages requests
and accounts| Snap - User -.->|Uses for snap-specific logic| Site + User -.->|Uses for Snap-specific logic| Site ``` -- **User**: The web3 user interacting with the snap, the dapp, and MetaMask. +- **User**: The web3 user interacting with the Snap, the dapp, and MetaMask. - **Dapp**: The web3 application that is requesting an action to be performed on an account. - **MetaMask**: The web3 provider that dapps connect to. It routes requests to - the keyring snaps and lets the user perform some level of account management. + the Keyring Snaps and lets the user perform some level of account management. -- **Snap**: A snap that implements the Keyring API to manage the user's +- **Snap**: A Snap that implements the Keyring API to manage the user's accounts, and to handle requests that use these accounts. -- **Snap Dapp**: The snap's UI component that allows the user to interact with - the snap to perform custom operations on accounts and requests. +- **Snap Dapp**: The Snap's UI component that allows the user to interact with + the Snap to perform custom operations on accounts and requests. ## Account creation The account creation flow is the initial process that a user will encounter -when using a keyring snap. It can be triggered by the "Add Snap account" button +when using a Keyring Snap. It can be triggered by the "Add Snap account" button in the accounts list or by the Snap dapp. ```mermaid @@ -61,14 +61,14 @@ participant MetaMask participant Snap participant Site as Snap Dapp -alt If the snap is not installed yet +alt If the Snap is not installed yet User ->>+ MetaMask: Add new Snap account - MetaMask ->> MetaMask: Display suggested snaps - User ->> MetaMask: Select snap + MetaMask ->> MetaMask: Display suggested Snaps + User ->> MetaMask: Select Snap MetaMask ->> Site: Open in a new tab deactivate MetaMask - Site ->>+ MetaMask: Install snap? + Site ->>+ MetaMask: Install Snap? MetaMask ->> MetaMask: Display permissions dialog User ->> MetaMask: Approve permissions MetaMask -->>- Site: OK @@ -78,7 +78,7 @@ User ->>+ Site: Create new account Site ->> Site: Custom logic to create account Site ->>+ Snap: keyring_createAccount(options?) Snap ->> Snap: Custom logic to create account -Snap ->>+ MetaMask: snap_manageAccounts("event:accountCreated", account) +Snap ->>+ MetaMask: snap_manageAccounts("notify:accountCreated", account) User ->> MetaMask: Approve account creation MetaMask -->>- Snap: OK Snap -->>- Site: OK @@ -89,13 +89,13 @@ Site -->>- User: Done The Keyring API supports two different flows for signing transactions: -- **Asynchronous**: MetaMask sends a keyring request to the keyring snap, and - the keyring snap responds with a `{ pending: true, redirect? }` response +- **Asynchronous**: MetaMask sends a keyring request to the Keyring Snap, and + the Keyring Snap responds with a `{ pending: true, redirect? }` response to indicate that the keyring request will be handled asynchronously. This response can optionally contain a `redirect` URL that MetaMask will open in a - new tab to allow the user to interact with the keyring snap dapp. + new tab to allow the user to interact with the Keyring Snap dapp. - Once the keyring snap has completed the request, it sends a notification to + Once the Keyring Snap has completed the request, it sends a notification to MetaMask with the result of the request. ```mermaid @@ -114,7 +114,7 @@ The Keyring API supports two different flows for signing transactions: User ->> MetaMask: Approve request MetaMask ->>+ Snap: keyring_submitRequest(request) - Snap ->> Snap: Save request to snap's state + Snap ->> Snap: Save request to Snap's state Snap -->>- MetaMask: { pending: true, redirect? } alt There is a redirect URL User ->> MetaMask: Acknowledge redirection @@ -133,7 +133,7 @@ The Keyring API supports two different flows for signing transactions: Site ->> Site: Custom logic to handle request Site ->>+ Snap: keyring_approveRequest(id, data?) Snap ->> Snap: Custom logic to handle request - Snap ->>+ MetaMask: snap_manageAccounts("event:requestApproved", { id, result }) + Snap ->>+ MetaMask: snap_manageAccounts("notify:requestApproved", { id, result }) MetaMask -->> Dapp: result MetaMask -->>- Snap: OK @@ -143,8 +143,8 @@ The Keyring API supports two different flows for signing transactions: Dapp -->>- User: Done ``` -- **Synchronous**: MetaMask sends a keyring request to the keyring snap, and - the keyring snap responds with a `{ pending: false, result }` response that +- **Synchronous**: MetaMask sends a keyring request to the Keyring Snap, and + the Keyring Snap responds with a `{ pending: false, result }` response that contains the result of the request. ```mermaid