From 584042baee48ff8e2aa16221f0f2d56ffb08b85b Mon Sep 17 00:00:00 2001 From: Harpal Jadeja Date: Sat, 16 Sep 2023 17:43:21 +0530 Subject: [PATCH 1/3] feat: add KeyringSnapRpcClient documentation --- snaps/how-to/use-keyringsnaprpcclient.md | 175 +++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 snaps/how-to/use-keyringsnaprpcclient.md diff --git a/snaps/how-to/use-keyringsnaprpcclient.md b/snaps/how-to/use-keyringsnaprpcclient.md new file mode 100644 index 00000000000..f7dddc3f82a --- /dev/null +++ b/snaps/how-to/use-keyringsnaprpcclient.md @@ -0,0 +1,175 @@ +--- +description: Use KeyringSnapRpcClient. +sidebar_position: 4 +--- + +# Use KeyringSnapRpcClient + +KeyringSnapRpcClient is to be used on the client side to invoke `keyring_*` rpc methods on the snap. + +Keyring RPC methods can be invoked directly like so: + +```ts +// Creating Keyring Account +window.ethereum.request({ + method: 'wallet_invokeSnap', + params: { + snapId: snapId, + request: { + method: 'keyring_createAccount', + params: + { + name: "KeyringAccount1", + options + }, + , + }, + }, +}); +``` + +But to make it easier for developers we abstracted much of the logic into the `KeyringRpcSnapClient` available in `@metamask/keyring-api` package. + +To use `KeyringSnapRpcClient`, first install `@metamask/keyring-api` using the following command: + +```bash +yarn add @metamask/keyring-api +``` + +Create the `client` as follows: + +```ts +import { KeyringSnapRpcClient } from "@metamask/keyring-api"; + +let client = new KeyringSnapRpcClient(snapId, window.ethereum); +``` + +You can now use the client to invoke the following `Keyring API` methods on your snap: + +- [`keyring_createAccount`](#create-account) +- [`keyring_getAccount`](#get-account) +- [`keyring_listAccounts`](#list-accounts) +- [`keyring_updateAccount`](#update-account) +- [`keyring_deleteAccount`](#delete-account) +- [`keyring_submitRequest`](#submit-request) +- [`keyring_getRequest`](#get-request) +- [`keyring_listRequests`](#list-requests) +- [`keyring_approveRequest`](#approve-request) +- [`keyring_rejectRequest`](#reject-request) +- [`keyring_filterAccountChains`](#filter-account-chains) + +## Create Account + +Creates a Keyring Snap Account. + +```ts +let keyringAccount = await client.createAccount("KeyringAccount1"); +``` + +## Get Account + +Gets a Keyring Snap Account. + +```ts +// Account Id is returned when account is created using `createAccount`. +let keyringAccount = await client.getAccount(accountId); +``` + +## List Accounts + +Lists all Keyring Snap Account created by the Snap with snapId = `snapId` used during `client` creation. + +```ts +let keyringAccounts = await client.listAccounts(); +``` + +## Update Account + +Updates a Keyring Account. + +```ts +let updatedAccount = await client.updateAccount(modifiedKeyringAccount); +``` + +## Delete Account + +Deletes a Keyring Account. + +```ts +let snapResponse = await client.deleteAccount(accountId); +``` + +## Submit Request + +Submits a Keyring Request. + +```ts +import { v4 as uuid } from "uuid"; + +// Example submitting a eth_sendTransaction request. +let submitRequestResponse = await client.submitRequest({ + // Id of the account to which you want to submit this request. + account: accountId, + scope: "eip155:1", // Ethereum Mainnet + request: { + jsonrpc: "2.0", + // Unique Id to identify every request. + id: uuid(), + // The method and params structure is subjective to the KeyringAPI implementation in the snap code. + method: "eth_sendTransaction", + params: + { + from: "", + to: "0xcEF0f7f7ee1650b4A8151f605d9258bA65D733F5", + data, + chainId: "1", + }, + , + }, +}); +``` + +## Get Request + +Gets a Keyring Request. + +```ts +// `requestId` is returned during request submission. +let keyringRequest = await client.getRequest(requestId); +``` + +## List Requests + +Lists all Request submitted submitted to the Snap with snapId = `snapId` used during `client` creation. + +```ts +let requests = await client.listRequests(); +``` + +## Approve Request + +Approves a request. + +```ts +// `requestId` is returned during request submission. +await client.approveRequest(requestId); +``` + +## Reject Request + +Rejects a request. + +```ts +// `requestId` is returned during request submission. +await client.rejectRequest(requestId); +``` + +## Filter Account Chains + +Returns a filtered list of CAIP-2 IDs representing the supported chains. + +```ts +// accountId - ID of the account to be checked. +// chains - List of chains (CAIP-2) to be checked. +let supportedChains = await client.filterAccountChains(accountId, chains); +``` From 6737a40a54953830b925a57a4fc278ea55855301 Mon Sep 17 00:00:00 2001 From: Harpal Jadeja Date: Wed, 20 Sep 2023 16:05:31 +0530 Subject: [PATCH 2/3] fix: add `KeyringSnapRpcClient` reference links --- snaps/how-to/use-keyringsnaprpcclient.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/snaps/how-to/use-keyringsnaprpcclient.md b/snaps/how-to/use-keyringsnaprpcclient.md index f7dddc3f82a..62b9b839cfe 100644 --- a/snaps/how-to/use-keyringsnaprpcclient.md +++ b/snaps/how-to/use-keyringsnaprpcclient.md @@ -5,7 +5,7 @@ sidebar_position: 4 # Use KeyringSnapRpcClient -KeyringSnapRpcClient is to be used on the client side to invoke `keyring_*` rpc methods on the snap. +[`KeyringSnapRpcClient`](../reference/keyring-api/classes/KeyringSnapRpcClient.md) is to be used on the client side to invoke `keyring_*` rpc methods on the snap. Keyring RPC methods can be invoked directly like so: @@ -28,9 +28,9 @@ window.ethereum.request({ }); ``` -But to make it easier for developers we abstracted much of the logic into the `KeyringRpcSnapClient` available in `@metamask/keyring-api` package. +But to make it easier for developers we abstracted much of the logic into the [`KeyringSnapRpcClient`](../reference/keyring-api/classes/KeyringSnapRpcClient.md) available in [`@metamask/keyring-api`](../reference/keyring-api/modules.md) package. -To use `KeyringSnapRpcClient`, first install `@metamask/keyring-api` using the following command: +To use [`KeyringSnapRpcClient`](../reference/keyring-api/classes/KeyringSnapRpcClient.md), first install [`@metamask/keyring-api`](../reference/keyring-api/modules.md) using the following command: ```bash yarn add @metamask/keyring-api @@ -44,7 +44,7 @@ import { KeyringSnapRpcClient } from "@metamask/keyring-api"; let client = new KeyringSnapRpcClient(snapId, window.ethereum); ``` -You can now use the client to invoke the following `Keyring API` methods on your snap: +You can now use the client to invoke the following [`Keyring API`](../reference/keyring-api/index.md) methods on your snap: - [`keyring_createAccount`](#create-account) - [`keyring_getAccount`](#get-account) From 369ebd150d1a8afb19ed61ac8778c528c64d3c73 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Thu, 21 Sep 2023 18:44:40 -0700 Subject: [PATCH 3/3] edit content --- snaps/how-to/troubleshoot.md | 2 +- snaps/how-to/use-keyring-api.md | 163 +++++++++++++++++++++ snaps/how-to/use-keyringsnaprpcclient.md | 175 ----------------------- snaps/how-to/work-with-existing-snaps.md | 2 +- snaps/tutorials/custom-evm-accounts.md | 7 +- 5 files changed, 167 insertions(+), 182 deletions(-) create mode 100644 snaps/how-to/use-keyring-api.md delete mode 100644 snaps/how-to/use-keyringsnaprpcclient.md diff --git a/snaps/how-to/troubleshoot.md b/snaps/how-to/troubleshoot.md index 270f83c62bd..eaf2e6ebf9b 100644 --- a/snaps/how-to/troubleshoot.md +++ b/snaps/how-to/troubleshoot.md @@ -1,6 +1,6 @@ --- description: Solve common issues. -sidebar_position: 6 +sidebar_position: 7 --- # Troubleshoot diff --git a/snaps/how-to/use-keyring-api.md b/snaps/how-to/use-keyring-api.md new file mode 100644 index 00000000000..6b1b1f74d49 --- /dev/null +++ b/snaps/how-to/use-keyring-api.md @@ -0,0 +1,163 @@ +--- +description: Use the KeyringSnapRpcClient from a dapp. +sidebar_label: Use the Keyring API +sidebar_position: 5 +--- + +# Use the Keyring API from a dapp + +Your dapp can use the [Keyring API](../concepts/keyring-api.md) to interact with custom EVM accounts. +Use the [`KeyringSnapRpcClient`](../reference/keyring-api/02-Classes/04-class.KeyringSnapRpcClient.md) +of the Keyring API to invoke Keyring RPC methods on your [Keyring snap](../concepts/keyring-api.md#terminology). + +:::tip tutorial +You can follow the end-to-end tutorial to [create a snap to connect to custom EVM accounts](../tutorials/custom-evm-accounts.md). +::: + +:::info API documentation +See the [Keyring API reference](../reference/keyring-api/index.md) for all the Keyring API methods. +::: + +## Create the KeyringSnapRpcClient + +To use the `KeyringSnapRpcClient`, install `@metamask/keyring-api` in your project directory using +Yarn or npm: + +```bash +yarn add @metamask/keyring-api +``` + +or + +```bash +npm install @metamask/keyring-api +``` + +Create the client by adding the following to your project script: + +```ts +import { KeyringSnapRpcClient } from "@metamask/keyring-api"; + +let client = new KeyringSnapRpcClient(snapId, window.ethereum); +``` + +## Call Keyring API methods + +You can now use the `KeyringSnapRpcClient` to invoke the following +[`Keyring API`](../reference/keyring-api/index.md) methods on your snap. + +### createAccount + +Creates a Keyring account. + +```ts +let keyringAccount = await client.createAccount("KeyringAccount1"); +``` + +### getAccount + +Gets a Keyring account. + +```ts +// accountId is returned when the account is created using createAccount. +let keyringAccount = await client.getAccount(accountId); +``` + +### listAccounts + +Lists all Keyring accounts created by the snap. + +```ts +let keyringAccounts = await client.listAccounts(); +``` + +### updateAccount + +Updates a Keyring account. + +```ts +let updatedAccount = await client.updateAccount(modifiedKeyringAccount); +``` + +### deleteAccount + +Deletes a Keyring account. + +```ts +let snapResponse = await client.deleteAccount(accountId); +``` + +### submitRequest + +Submits a Keyring request. + +```ts +import { v4 as uuid } from "uuid"; + +// Example submitting an eth_sendTransaction request +let submitRequestResponse = await client.submitRequest({ + // ID of the account to which you want to submit this request + account: accountId, + scope: "eip155:1", // Ethereum Mainnet + request: { + jsonrpc: "2.0", + // Unique ID to identify every request + id: uuid(), + // The method and parameter structure is subjective to the Keyring API implementation in the snap code. + method: "eth_sendTransaction", + params: + { + from: "", + to: "0xcEF0f7f7ee1650b4A8151f605d9258bA65D733F5", + data, + chainId: "1", + }, + , + }, +}); +``` + +### getRequest + +Gets a Keyring request. + +```ts +// requestId is returned during request submission. +let keyringRequest = await client.getRequest(requestId); +``` + +### listRequests + +Lists all requests submitted to the snap. + +```ts +let requests = await client.listRequests(); +``` + +### approveRequest + +Approves a request. + +```ts +// requestId is returned during request submission. +await client.approveRequest(requestId); +``` + +### rejectRequest + +Rejects a request. + +```ts +// requestId is returned during request submission. +await client.rejectRequest(requestId); +``` + +### filterAccountChains + +Returns a filtered list of CAIP-2 IDs representing the supported chains. + +```ts +// accountId - ID of the account to be checked +// chains - List of chains (CAIP-2) to be checked +let supportedChains = await client.filterAccountChains(accountId, chains); +``` diff --git a/snaps/how-to/use-keyringsnaprpcclient.md b/snaps/how-to/use-keyringsnaprpcclient.md deleted file mode 100644 index 62b9b839cfe..00000000000 --- a/snaps/how-to/use-keyringsnaprpcclient.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -description: Use KeyringSnapRpcClient. -sidebar_position: 4 ---- - -# Use KeyringSnapRpcClient - -[`KeyringSnapRpcClient`](../reference/keyring-api/classes/KeyringSnapRpcClient.md) is to be used on the client side to invoke `keyring_*` rpc methods on the snap. - -Keyring RPC methods can be invoked directly like so: - -```ts -// Creating Keyring Account -window.ethereum.request({ - method: 'wallet_invokeSnap', - params: { - snapId: snapId, - request: { - method: 'keyring_createAccount', - params: - { - name: "KeyringAccount1", - options - }, - , - }, - }, -}); -``` - -But to make it easier for developers we abstracted much of the logic into the [`KeyringSnapRpcClient`](../reference/keyring-api/classes/KeyringSnapRpcClient.md) available in [`@metamask/keyring-api`](../reference/keyring-api/modules.md) package. - -To use [`KeyringSnapRpcClient`](../reference/keyring-api/classes/KeyringSnapRpcClient.md), first install [`@metamask/keyring-api`](../reference/keyring-api/modules.md) using the following command: - -```bash -yarn add @metamask/keyring-api -``` - -Create the `client` as follows: - -```ts -import { KeyringSnapRpcClient } from "@metamask/keyring-api"; - -let client = new KeyringSnapRpcClient(snapId, window.ethereum); -``` - -You can now use the client to invoke the following [`Keyring API`](../reference/keyring-api/index.md) methods on your snap: - -- [`keyring_createAccount`](#create-account) -- [`keyring_getAccount`](#get-account) -- [`keyring_listAccounts`](#list-accounts) -- [`keyring_updateAccount`](#update-account) -- [`keyring_deleteAccount`](#delete-account) -- [`keyring_submitRequest`](#submit-request) -- [`keyring_getRequest`](#get-request) -- [`keyring_listRequests`](#list-requests) -- [`keyring_approveRequest`](#approve-request) -- [`keyring_rejectRequest`](#reject-request) -- [`keyring_filterAccountChains`](#filter-account-chains) - -## Create Account - -Creates a Keyring Snap Account. - -```ts -let keyringAccount = await client.createAccount("KeyringAccount1"); -``` - -## Get Account - -Gets a Keyring Snap Account. - -```ts -// Account Id is returned when account is created using `createAccount`. -let keyringAccount = await client.getAccount(accountId); -``` - -## List Accounts - -Lists all Keyring Snap Account created by the Snap with snapId = `snapId` used during `client` creation. - -```ts -let keyringAccounts = await client.listAccounts(); -``` - -## Update Account - -Updates a Keyring Account. - -```ts -let updatedAccount = await client.updateAccount(modifiedKeyringAccount); -``` - -## Delete Account - -Deletes a Keyring Account. - -```ts -let snapResponse = await client.deleteAccount(accountId); -``` - -## Submit Request - -Submits a Keyring Request. - -```ts -import { v4 as uuid } from "uuid"; - -// Example submitting a eth_sendTransaction request. -let submitRequestResponse = await client.submitRequest({ - // Id of the account to which you want to submit this request. - account: accountId, - scope: "eip155:1", // Ethereum Mainnet - request: { - jsonrpc: "2.0", - // Unique Id to identify every request. - id: uuid(), - // The method and params structure is subjective to the KeyringAPI implementation in the snap code. - method: "eth_sendTransaction", - params: - { - from: "", - to: "0xcEF0f7f7ee1650b4A8151f605d9258bA65D733F5", - data, - chainId: "1", - }, - , - }, -}); -``` - -## Get Request - -Gets a Keyring Request. - -```ts -// `requestId` is returned during request submission. -let keyringRequest = await client.getRequest(requestId); -``` - -## List Requests - -Lists all Request submitted submitted to the Snap with snapId = `snapId` used during `client` creation. - -```ts -let requests = await client.listRequests(); -``` - -## Approve Request - -Approves a request. - -```ts -// `requestId` is returned during request submission. -await client.approveRequest(requestId); -``` - -## Reject Request - -Rejects a request. - -```ts -// `requestId` is returned during request submission. -await client.rejectRequest(requestId); -``` - -## Filter Account Chains - -Returns a filtered list of CAIP-2 IDs representing the supported chains. - -```ts -// accountId - ID of the account to be checked. -// chains - List of chains (CAIP-2) to be checked. -let supportedChains = await client.filterAccountChains(accountId, chains); -``` diff --git a/snaps/how-to/work-with-existing-snaps.md b/snaps/how-to/work-with-existing-snaps.md index 0e542e9705e..0fe88f6c239 100644 --- a/snaps/how-to/work-with-existing-snaps.md +++ b/snaps/how-to/work-with-existing-snaps.md @@ -1,6 +1,6 @@ --- description: Connect your dapp to existing, third-party snaps. -sidebar_position: 5 +sidebar_position: 6 --- # Work with third-party snaps diff --git a/snaps/tutorials/custom-evm-accounts.md b/snaps/tutorials/custom-evm-accounts.md index d3589dd9588..a122a9a76eb 100644 --- a/snaps/tutorials/custom-evm-accounts.md +++ b/snaps/tutorials/custom-evm-accounts.md @@ -127,11 +127,8 @@ export const onRpcRequest: OnRpcRequestHandler = buildHandlersChain( As you build a companion dapp to provide a user interface for your Keyring snap, you'll need to interact with your snap's JSON-RPC API. While you could do this by making regular RPC calls using -[`wallet_invokeSnap`](../reference/rpc-api.md#wallet_invokesnap), we recommend using the Keyring API. - -From your dapp, use the -[`KeyringSnapRpcClient`](../reference/keyring-api/02-Classes/04-class.KeyringSnapRpcClient.md) as -follows: +[`wallet_invokeSnap`](../reference/rpc-api.md#wallet_invokesnap), we recommend +[using the Keyring API from your dapp](../how-to/use-keyring-api.md): ```typescript import { KeyringSnapRpcClient } from '@metamask/keyring-api';