From ca2bf8e6e80b9dc7598d3477d82d73c437092e85 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Sat, 24 Feb 2024 11:09:31 -0800 Subject: [PATCH 1/7] Update Keyring API reference --- .eslintignore | 1 - .github/workflows/build-lint.yml | 6 - .github/workflows/publish-docs.yml | 1 - .gitignore | 1 - .gitmodules | 3 - docusaurus.config.js | 17 - external/keyring-api | 1 - package.json | 8 +- snaps-sidebar.js | 51 +- snaps/reference/cli/_category_.json | 8 + snaps/reference/entry-points.md | 1 + snaps/reference/jest.md | 1 + snaps/reference/keyring-api/client-api.md | 643 ++++++++++++++++++ .../reference/keyring-api/data-structures.md | 11 + snaps/reference/keyring-api/events.md | 5 + .../index.md | 1 + snaps/reference/keyring-api/interface-api.md | 25 + snaps/reference/known-errors.md | 1 + snaps/reference/permissions.md | 1 + snaps/reference/resources.md | 1 + snaps/reference/snaps-api.md | 1 + tsconfig.json | 3 +- yarn.lock | 99 +-- 23 files changed, 705 insertions(+), 185 deletions(-) delete mode 100644 .gitmodules delete mode 160000 external/keyring-api create mode 100644 snaps/reference/cli/_category_.json create mode 100644 snaps/reference/keyring-api/client-api.md create mode 100644 snaps/reference/keyring-api/data-structures.md create mode 100644 snaps/reference/keyring-api/events.md rename snaps/reference/{keyring-api-index => keyring-api}/index.md (96%) create mode 100644 snaps/reference/keyring-api/interface-api.md diff --git a/.eslintignore b/.eslintignore index a304897c9eb..e19d07681a7 100644 --- 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 index 96526bd8c6c..147bb2d2387 100644 --- 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 index 57e1cb0604e..320c52c8769 100644 --- 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 index aae1c6400f8..8dea2eddc4a 100644 --- 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 deleted file mode 100644 index a7e1104515b..00000000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "external/keyring-api"] - path = external/keyring-api - url = git@github.com:MetaMask/keyring-api.git diff --git a/docusaurus.config.js b/docusaurus.config.js index ee811232399..027a7193b18 100644 --- 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 deleted file mode 160000 index 1c8eeb9beef..00000000000 --- a/external/keyring-api +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 1c8eeb9beef7f21ca0bd394b6fe06fea856e3520 diff --git a/package.json b/package.json index 7d7dc73ee4a..6934bfa8084 100644 --- 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,7 +27,6 @@ "@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", @@ -36,9 +34,7 @@ "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 index fb7fe338a3a..bef177df9bb 100644 --- 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/reference/cli/_category_.json b/snaps/reference/cli/_category_.json new file mode 100644 index 00000000000..6dd08fd3b0e --- /dev/null +++ b/snaps/reference/cli/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Snaps command line", + "position": 2, + "link": { + "type": "generated-index", + "slug": "reference/cli" + } +} diff --git a/snaps/reference/entry-points.md b/snaps/reference/entry-points.md index 75ab09a2a50..56adf469e3d 100644 --- a/snaps/reference/entry-points.md +++ b/snaps/reference/entry-points.md @@ -1,5 +1,6 @@ --- description: See the Snaps entry points reference. +sidebar_position: 3 --- import Tabs from '@theme/Tabs'; diff --git a/snaps/reference/jest.md b/snaps/reference/jest.md index de6b7adff58..450430e3850 100644 --- a/snaps/reference/jest.md +++ b/snaps/reference/jest.md @@ -1,5 +1,6 @@ --- description: See the Jest API and options reference. +sidebar_position: 7 --- # Jest API and options diff --git a/snaps/reference/keyring-api/client-api.md b/snaps/reference/keyring-api/client-api.md new file mode 100644 index 00000000000..90a5a6c9f1d --- /dev/null +++ b/snaps/reference/keyring-api/client-api.md @@ -0,0 +1,643 @@ +--- +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Keyring Client API + +Dapps can communicate with [account management Snaps](../../features/custom-evm-accounts/index.md) +using the Keyring Client API. +The dapp must be [allowed to call each +method](../../features/custom-evm-accounts/security.md#limit-the-methods-exposed-to-dapps). + +## Account methods + +The following methods are exposed by the Snap for account management. + +### `keyring_createAccount` + +Creates a new account. + +#### Parameters + +`options`: `Record` - Snap-defined options required for the account creation. + +#### Returns + +An account object containing the following details: + +- `address`: `string` - Account address. +- `id`: `string` - Account ID. +- `methods`: `string[]` - List of supported [Keyring Interface API](interface-api.md) methods. +- `options`: `Record` - Snap-defined options. +- `type`: `string` - `"eip155:eoa"` for an externally owned account (EOA) or `"eip155:erc4337"` for + an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) account. + +#### Example + + + + +```json +{ + "method": "keyring_createAccount", + "params": { + "options": { + "signerCount": 5, + "threshold": 3 + } + } +} +``` + + + + +```json +{ + "address": "0xd1f5279be4b4dd94133a23dee1b23f5bfc0db1d0", + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a", + "methods": [ + "eth_sign", + "eth_signTransaction", + "eth_signTypedData_v4", + "personal_sign" + ], + "options": { + "signerCount": 5, + "threshold": 3 + }, + "type": "eip155:eoa" +} +``` + + + + +### `keyring_deleteAccount` + +Deletes an existing account. + +#### Parameters + +`id`: `string` - ID of the account to be deleted. + +#### Returns + +`null` + +#### Example + + + + +```json +{ + "method": "keyring_deleteAccount", + "params": { + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a" + } +} +``` + + + + +```json +null +``` + + + + +### `keyring_exportAccount` + +Exports the private key of an account managed by the Snap. +A Snap might choose to not support this method. + +#### Parameters + +`id`: `string` - ID of the account to be exported. + +#### Returns + +An object containing `privateKey`, the account's private key. + +#### Example + + + + +```json +{ + "method": "keyring_exportAccount", + "params": { + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a" + } +} +``` + + + + +```json +{ + "privateKey": "66a41d66be6483f1fdfd01fdb66173d449594bbd286149b019504dd72b58bc51" +} +``` + + + + +### `keyring_filterAccountChains` + +TO DO + +#### Parameters + +- `id`: `string` - Account ID. +- `chains`: `string[]` - TO DO + +#### Returns + +TO DO + +#### Example + + + + +```json +{ + "method": "keyring_filterAccountChains", + "params": { + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a", + "chains": // TO DO + } +} +``` + + + + +```json +// TO DO +``` + + + + +### `keyring_getAccount` + +Gets an account from an ID. + +#### Parameters + +`id`: `string` - Account ID. + +#### Returns + +An account object containing the following details: + +- `address`: `string` - Account address. +- `id`: `string` - Account ID. +- `methods`: `string[]` - List of supported [Keyring Interface API](interface-api.md) methods. +- `options`: `Record` - Snap-defined options. +- `type`: `string` - `"eip155:eoa"` for an externally owned account (EOA) or `"eip155:erc4337"` for + an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) account. + +#### Example + + + + +```json +{ + "method": "keyring_getAccount", + "params": { + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a" + } +} +``` + + + + +```json +{ + "address": "0xd1f5279be4b4dd94133a23dee1b23f5bfc0db1d0", + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a", + "methods": [ + "eth_sign", + "eth_signTransaction", + "eth_signTypedData_v4", + "personal_sign" + ], + "options": { + "signerCount": 5, + "threshold": 3 + }, + "type": "eip155:eoa" +} +``` + + + + +### `keyring_listAccounts` + +Lists all accounts handled by the Snap. + +#### Parameters + +None + +#### Returns + +An array of account objects handled by the Snap. +An account object contains the following details: + +- `address`: `string` - Account address. +- `id`: `string` - Account ID. +- `methods`: `string[]` - List of supported [Keyring Interface API](interface-api.md) methods. +- `options`: `Record` - Snap-defined options. +- `type`: `string` - `"eip155:eoa"` for an externally owned account (EOA) or `"eip155:erc4337"` for + an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) account. + +#### Example + + + + +```json +{ + "method": "keyring_listAccounts" +} +``` + + + + +```json +[ + { + "address": "0xd1f5279be4b4dd94133a23dee1b23f5bfc0db1d0", + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a", + "methods": [ + "eth_sign", + "eth_signTransaction", + "eth_signTypedData_v4", + "personal_sign" + ], + "options": { + "signerCount": 5, + "threshold": 3 + }, + "type": "eip155:eoa" + }, + { + "address": "0x84674cffb6146d19b986fc88ec70a441b570a45b", + "id": "17a87b4a-286c-444d-aebb-1fed89021419", + "methods": [ + "eth_prepareUserOperation", + "eth_patchUserOperation", + "eth_signUserOperation" + ], + "type": "eip155:erc4337" + } +] +``` + + + + +### `keyring_updateAccount` + +Updates an account. + +#### Parameters + +An account object containing the following details: + +- `address`: `string` - Account address. +- `id`: `string` - Account ID. +- `methods`: `string[]` - List of supported [Keyring Interface API](interface-api.md) methods. +- `options`: `Record` - Snap-defined options. +- `type`: `string` - `"eip155:eoa"` for an externally owned account (EOA) or `"eip155:erc4337"` for + an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) account. + +#### Returns + +`null` + +#### Example + + + + +```json +{ + "method": "keyring_updateAccount", + "params": { + "address": "0xd1f5279be4b4dd94133a23dee1b23f5bfc0db1d0", + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a", + "methods": [ + "eth_sign", + "eth_signTransaction", + "eth_signTypedData_v4", + "personal_sign" + ], + "options": { + "signerCount": 7, + "threshold": 4 + }, + "type": "eip155:eoa" + } +} +``` + + + + +```json +null +``` + + + + +## Request methods + +The following methods are exposed by the Snap for managing signature requests. + +### `keyring_approveRequest` + +Approves a pending request. + +#### Parameters + +- `id`: `string` - Request ID. +- `data`: `Record` - Optional Snap-defined arguments. + +#### Returns + +`null` + +#### Example + + + + +```json +{ + "method": "keyring_approveRequest", + "params": { + "id": "f84d3a97-b6e1-47ea-8b0c-fd8609efaad4" + } +} +``` + + + + +```json +null +``` + + + + +### `keyring_getRequest` + +Gets a request from an ID. + +#### Parameters + +`id`: `string` - Request ID. + +#### Returns + +A request object containing the following details: + +- `account`: `string` - Account ID. +- `id`: `string` - Request ID. +- `request` - Inner request sent by the client application, containing: + - `method`: `string` - The request method. + - `params`: `Json[]` - Optional method parameters. +- `scope`: `string` - Request's scope ([CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain ID). + +#### Example + + + + +```json +{ + "method": "keyring_getRequest", + "params": { + "id": "f84d3a97-b6e1-47ea-8b0c-fd8609efaad4" + } +} +``` + + + + +```json +{ + "address": "0xd1f5279be4b4dd94133a23dee1b23f5bfc0db1d0", + "id": "f84d3a97-b6e1-47ea-8b0c-fd8609efaad4", + "request": { + "method": "personal_sign", + "params": [ + "0x4578616d706c652060706572736f6e616c5f7369676e60206d657373616765", + "0xe887f3b50232722e6eb4c1d3a03b34c9b345acd1" + ] + }, + "scope": "eip155:1" +} +``` + + + + +### `keyring_listRequests` + +Lists all pending requests. + +#### Parameters + +None + +#### Returns + +An array of pending request objects. +A request object contains the following details: + +- `account`: `string` - Account ID. +- `id`: `string` - Request ID. +- `request` - Inner request sent by the client application, containing: + - `method`: `string` - The request method. + - `params`: `Json[]` - Optional method parameters. +- `scope`: `string` - Request's scope ([CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain ID). + +#### Example + + + + +```json +{ + "method": "keyring_listRequests" +} +``` + + + + +```json +[ + { + "account": "0xd1f5279be4b4dd94133a23dee1b23f5bfc0db1d0", + "id": "f84d3a97-b6e1-47ea-8b0c-fd8609efaad4", + "request": { + "method": "personal_sign", + "params": [ + "0x4578616d706c652060706572736f6e616c5f7369676e60206d657373616765", + "0xe887f3b50232722e6eb4c1d3a03b34c9b345acd1" + ] + }, + "scope": "eip155:1" + }, + { + "account": "0xe887f3b50232722e6eb4c1d3a03b34c9b345acd1", + "id": "f6f302ae-38d7-4b95-ae88-bf2fb7fbee87", + "request": { + "method": "eth_sendTransaction", + "params": [ + { + "from": "0xe887f3b50232722e6eb4c1d3a03b34c9b345acd1", + "nonce": "0x1", + "gasPrice": "0x10", + "gasLimit": "0x5208", + "to": "0x84674cffb6146d19b986fc88ec70a441b570a45b", + "value": "0x10000", + "data": "0x" + } + ] + }, + "scope": "eip155:1" + } +] +``` + + + + +### `keyring_rejectRequest` + +Rejects a pending request and removes it from the list of pending requests. + +#### Parameters + +`id`: `string` - Request ID. + +#### Returns + +`null` + +#### Example + + + + +```json +{ + "method": "keyring_rejectRequest", + "params": { + "id": "f84d3a97-b6e1-47ea-8b0c-fd8609efaad4" + } +} +``` + + + + +```json +null +``` + + + + +### `keyring_submitRequest` + +Submits a new request. + +#### Parameters + +A request object containing the following details: + +- `account`: `string` - Account ID. +- `id`: `string` - Request ID. +- `request` - Inner request sent by the client application, containing: + - `method`: `string` - The request method. + - `params`: `Json[]` - Optional method parameters. +- `scope`: `string` - Request's scope ([CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain ID). + +#### Returns + +If the request is [synchronous](../../features/custom-evm-accounts/index.md#synchronous-transaction-flow), +`keyring_submitRequest` returns an object containing: + +- `pending` - `false` to indicate a synchronous request. +- `result`: `Json` - Request result. + +If the request is [asynchronous](../../features/custom-evm-accounts/index.md#asynchronous-transaction-flow), +`keyring_submitRequest` returns an object containing: + +- `pending` - `true` to indicate that the request will be handled asynchronously. +- `redirect` - An optional redirect object containing: + - `message`: `string` - Redirect message. + - `url`: `string` - Redirect URL. + +#### Example + + + + +```json +{ + "method": "keyring_submitRequest", + "params": { + "address": "0xd1f5279be4b4dd94133a23dee1b23f5bfc0db1d0", + "id": "f84d3a97-b6e1-47ea-8b0c-fd8609efaad4", + "request": { + "method": "personal_sign", + "params": [ + "0x4578616d706c652060706572736f6e616c5f7369676e60206d657373616765", + "0xe887f3b50232722e6eb4c1d3a03b34c9b345acd1" + ] + }, + "scope": "eip155:1" + } +} +``` + + + + +```json +{ + "pending": false, + "result": "0x9aef363b17bc18dfbdcb9ed3ce5f9f96788ce84b353d262099e90c4fa0b513a4e21ee47bafa04c0630750e901b62bd4839b45219c191ec6076d6549637cb1beb4c" +} +``` + + + diff --git a/snaps/reference/keyring-api/data-structures.md b/snaps/reference/keyring-api/data-structures.md new file mode 100644 index 00000000000..42dc5375011 --- /dev/null +++ b/snaps/reference/keyring-api/data-structures.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 3 +--- + +# Keyring API data structures + +## `KeyringAccountStruct` + +## `KeyringRequestStruct` + +## `KeyringResponseStruct` diff --git a/snaps/reference/keyring-api/events.md b/snaps/reference/keyring-api/events.md new file mode 100644 index 00000000000..144e01317b2 --- /dev/null +++ b/snaps/reference/keyring-api/events.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 4 +--- + +# Keyring API events diff --git a/snaps/reference/keyring-api-index/index.md b/snaps/reference/keyring-api/index.md similarity index 96% rename from snaps/reference/keyring-api-index/index.md rename to snaps/reference/keyring-api/index.md index 48f04d81b06..0ee236a5956 100644 --- a/snaps/reference/keyring-api-index/index.md +++ b/snaps/reference/keyring-api/index.md @@ -1,5 +1,6 @@ --- description: See the Keyring API reference. +sidebar_position: 6 tags: - Keyring API --- diff --git a/snaps/reference/keyring-api/interface-api.md b/snaps/reference/keyring-api/interface-api.md new file mode 100644 index 00000000000..f9d167dd0ed --- /dev/null +++ b/snaps/reference/keyring-api/interface-api.md @@ -0,0 +1,25 @@ +--- +sidebar_position: 2 +--- + +# Keyring Interface API + +## EOA methods + +### `eth_sign` + +### `eth_signTransaction` + +### `eth_signTypedData_v4` + +### `personal_sign` + +### Deprecated methods + +## ERC-4337 methods + +### `eth_prepareUserOperation` + +### `eth_patchUserOperation` + +### `eth_signUserOperation` diff --git a/snaps/reference/known-errors.md b/snaps/reference/known-errors.md index a183c994755..83a26790b52 100644 --- a/snaps/reference/known-errors.md +++ b/snaps/reference/known-errors.md @@ -1,5 +1,6 @@ --- description: See the Snaps known errors reference +sidebar_position: 5 --- # Snaps known errors diff --git a/snaps/reference/permissions.md b/snaps/reference/permissions.md index b4a02267ceb..6d5761ed9d7 100644 --- a/snaps/reference/permissions.md +++ b/snaps/reference/permissions.md @@ -1,5 +1,6 @@ --- description: See the Snaps permissions reference. +sidebar_position: 4 --- import Tabs from '@theme/Tabs'; diff --git a/snaps/reference/resources.md b/snaps/reference/resources.md index 6febbada99d..4d96ee8c4c3 100644 --- a/snaps/reference/resources.md +++ b/snaps/reference/resources.md @@ -1,5 +1,6 @@ --- description: See more Snaps resources. +sidebar_position: 8 --- # Resources diff --git a/snaps/reference/snaps-api.md b/snaps/reference/snaps-api.md index d86018c46d1..41e92c3a554 100644 --- a/snaps/reference/snaps-api.md +++ b/snaps/reference/snaps-api.md @@ -1,6 +1,7 @@ --- description: See the Snaps API reference. toc_max_heading_level: 2 +sidebar_position: 1 --- import Tabs from '@theme/Tabs'; diff --git a/tsconfig.json b/tsconfig.json index 262563a3474..72c23e90b63 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -9,7 +9,6 @@ "./**/*" ], "exclude": [ - "node_modules", - "external" + "node_modules" ], } diff --git a/yarn.lock b/yarn.lock index 730c51d1adf..41b2a926c3a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2241,7 +2241,7 @@ __metadata: languageName: node linkType: hard -"@docusaurus/types@npm:2.4.3, @docusaurus/types@npm:^2.4.1": +"@docusaurus/types@npm:2.4.3": version: 2.4.3 resolution: "@docusaurus/types@npm:2.4.3" dependencies: @@ -4708,13 +4708,6 @@ __metadata: languageName: node linkType: hard -"ansi-sequence-parser@npm:^1.1.0": - version: 1.1.1 - resolution: "ansi-sequence-parser@npm:1.1.1" - checksum: ead5b15c596e8e85ca02951a844366c6776769dcc9fd1bd3a0db11bb21364554822c6a439877fb599e7e1ffa0b5f039f1e5501423950457f3dcb2f480c30b188 - languageName: node - linkType: hard - "ansi-styles@npm:^3.2.1": version: 3.2.1 resolution: "ansi-styles@npm:3.2.1" @@ -7440,17 +7433,6 @@ __metadata: languageName: node linkType: hard -"docusaurus-plugin-typedoc@npm:1.0.0-next.17": - version: 1.0.0-next.17 - resolution: "docusaurus-plugin-typedoc@npm:1.0.0-next.17" - dependencies: - "@docusaurus/types": ^2.4.1 - peerDependencies: - typedoc-plugin-markdown: ">=4.0.0-next.22" - checksum: a8103fb2461b59eaf394a159ee6b23777d4994c17f9be8264e18e687e973f6c7fee273f66bf64eef3069f1144b712d1753e9a4709b0f367fde7fe8d52c625ce6 - languageName: node - linkType: hard - "dom-converter@npm:^0.2.0": version: 0.2.0 resolution: "dom-converter@npm:0.2.0" @@ -11097,13 +11079,6 @@ __metadata: languageName: node linkType: hard -"jsonc-parser@npm:^3.2.0": - version: 3.2.0 - resolution: "jsonc-parser@npm:3.2.0" - checksum: 946dd9a5f326b745aa326d48a7257e3f4a4b62c5e98ec8e49fa2bdd8d96cef7e6febf1399f5c7016114fd1f68a1c62c6138826d5d90bc650448e3cf0951c53c7 - languageName: node - linkType: hard - "jsonc-parser@npm:~2.2.1": version: 2.2.1 resolution: "jsonc-parser@npm:2.2.1" @@ -11506,13 +11481,6 @@ __metadata: languageName: node linkType: hard -"lunr@npm:^2.3.9": - version: 2.3.9 - resolution: "lunr@npm:2.3.9" - checksum: 176719e24fcce7d3cf1baccce9dd5633cd8bdc1f41ebe6a180112e5ee99d80373fe2454f5d4624d437e5a8319698ca6837b9950566e15d2cae5f2a543a3db4b8 - languageName: node - linkType: hard - "lz-string@npm:^1.4.4": version: 1.5.0 resolution: "lz-string@npm:1.5.0" @@ -11634,15 +11602,6 @@ __metadata: languageName: node linkType: hard -"marked@npm:^4.3.0": - version: 4.3.0 - resolution: "marked@npm:4.3.0" - bin: - marked: bin/marked.js - checksum: 0db6817893952c3ec710eb9ceafb8468bf5ae38cb0f92b7b083baa13d70b19774674be04db5b817681fa7c5c6a088f61300815e4dd75a59696f4716ad69f6260 - languageName: node - linkType: hard - "md5.js@npm:^1.3.4": version: 1.3.5 resolution: "md5.js@npm:1.3.5" @@ -11976,7 +11935,6 @@ __metadata: "@typescript-eslint/parser": ^5.41.0 clsx: ^1.2.1 docusaurus-plugin-segment: ^1.0.4 - docusaurus-plugin-typedoc: 1.0.0-next.17 eslint: ^8.26.0 eslint-plugin-react: ^7.31.10 eslint-plugin-unused-imports: ^2.0.0 @@ -11988,8 +11946,6 @@ __metadata: 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 typescript: ^4.7.4 languageName: unknown linkType: soft @@ -12449,7 +12405,7 @@ __metadata: languageName: node linkType: hard -"minimatch@npm:^9.0.1, minimatch@npm:^9.0.3": +"minimatch@npm:^9.0.1": version: 9.0.3 resolution: "minimatch@npm:9.0.3" dependencies: @@ -15974,18 +15930,6 @@ __metadata: languageName: node linkType: hard -"shiki@npm:^0.14.1": - version: 0.14.5 - resolution: "shiki@npm:0.14.5" - dependencies: - ansi-sequence-parser: ^1.1.0 - jsonc-parser: ^3.2.0 - vscode-oniguruma: ^1.7.0 - vscode-textmate: ^8.0.0 - checksum: 41d847817cfc9bb6d8bf190316896698d250303656546446659cc02caed8dcc171b10cd113bb5da82425b51d0032e87aafcdc36c3dd61dadc123170b438da736 - languageName: node - linkType: hard - "shortid@npm:^2.2.8": version: 2.2.16 resolution: "shortid@npm:2.2.16" @@ -17146,31 +17090,6 @@ __metadata: languageName: node linkType: hard -"typedoc-plugin-markdown@npm:4.0.0-next.22": - version: 4.0.0-next.22 - resolution: "typedoc-plugin-markdown@npm:4.0.0-next.22" - peerDependencies: - typedoc: ">=0.25.0" - checksum: a27a76ee7c7ef1a46fad0177159c067bb7890bc293fcf207110d2b8354aeba337ada6d9a99cec68ba3745807ab64581282acf8a21532b4d4f4748a6a644501b2 - languageName: node - linkType: hard - -"typedoc@npm:^0.25.1": - version: 0.25.4 - resolution: "typedoc@npm:0.25.4" - dependencies: - lunr: ^2.3.9 - marked: ^4.3.0 - minimatch: ^9.0.3 - shiki: ^0.14.1 - peerDependencies: - typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x - bin: - typedoc: bin/typedoc - checksum: 6d441baa277c0db4d577db2932a7af316d175415841e2faf2e68e3eda6ad60356c54f56374f89c5233d7bd5c057b0337455e5d484d8463e1445e67c37a6d94eb - languageName: node - linkType: hard - "typescript@npm:^4.7.4": version: 4.9.5 resolution: "typescript@npm:4.9.5" @@ -17952,20 +17871,6 @@ __metadata: languageName: node linkType: hard -"vscode-oniguruma@npm:^1.7.0": - version: 1.7.0 - resolution: "vscode-oniguruma@npm:1.7.0" - checksum: 53519d91d90593e6fb080260892e87d447e9b200c4964d766772b5053f5699066539d92100f77f1302c91e8fc5d9c772fbe40fe4c90f3d411a96d5a9b1e63f42 - languageName: node - linkType: hard - -"vscode-textmate@npm:^8.0.0": - version: 8.0.0 - resolution: "vscode-textmate@npm:8.0.0" - checksum: 127780dfea89559d70b8326df6ec344cfd701312dd7f3f591a718693812b7852c30b6715e3cfc8b3200a4e2515b4c96f0843c0eacc0a3020969b5de262c2a4bb - languageName: node - linkType: hard - "wait-on@npm:^6.0.1": version: 6.0.1 resolution: "wait-on@npm:6.0.1" From 991a80296c30038eca90dbd454b620849b46cf10 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Sun, 25 Feb 2024 22:27:51 -0800 Subject: [PATCH 2/7] document interface api --- snaps/reference/keyring-api/client-api.md | 46 +- snaps/reference/keyring-api/interface-api.md | 454 ++++++++++++++++++- 2 files changed, 484 insertions(+), 16 deletions(-) diff --git a/snaps/reference/keyring-api/client-api.md b/snaps/reference/keyring-api/client-api.md index 90a5a6c9f1d..dbd378a2e45 100644 --- a/snaps/reference/keyring-api/client-api.md +++ b/snaps/reference/keyring-api/client-api.md @@ -22,11 +22,13 @@ Creates a new account. #### Parameters -`options`: `Record` - Snap-defined options required for the account creation. +An object containing: + +- `options`: `Record` - Snap-defined options required for the account creation. #### Returns -An account object containing the following details: +An account object containing: - `address`: `string` - Account address. - `id`: `string` - Account ID. @@ -82,7 +84,9 @@ Deletes an existing account. #### Parameters -`id`: `string` - ID of the account to be deleted. +An object containing: + +- `id`: `string` - ID of the account to be deleted. #### Returns @@ -119,11 +123,15 @@ A Snap might choose to not support this method. #### Parameters -`id`: `string` - ID of the account to be exported. +An object containing: + +- `id`: `string` - ID of the account to be exported. #### Returns -An object containing `privateKey`, the account's private key. +An object containing: + +- `privateKey`: `string` - The account's private key. #### Example @@ -157,6 +165,8 @@ TO DO #### Parameters +An object containing: + - `id`: `string` - Account ID. - `chains`: `string[]` - TO DO @@ -195,11 +205,13 @@ Gets an account from an ID. #### Parameters -`id`: `string` - Account ID. +An object containing: + +- `id`: `string` - Account ID. #### Returns -An account object containing the following details: +An account object containing: - `address`: `string` - Account address. - `id`: `string` - Account ID. @@ -257,7 +269,7 @@ None #### Returns An array of account objects handled by the Snap. -An account object contains the following details: +An account object contains: - `address`: `string` - Account address. - `id`: `string` - Account ID. @@ -319,7 +331,7 @@ Updates an account. #### Parameters -An account object containing the following details: +An account object containing: - `address`: `string` - Account address. - `id`: `string` - Account ID. @@ -378,6 +390,8 @@ Approves a pending request. #### Parameters +An object containing: + - `id`: `string` - Request ID. - `data`: `Record` - Optional Snap-defined arguments. @@ -415,11 +429,13 @@ Gets a request from an ID. #### Parameters -`id`: `string` - Request ID. +An object containing: + +- `id`: `string` - Request ID. #### Returns -A request object containing the following details: +A request object containing: - `account`: `string` - Account ID. - `id`: `string` - Request ID. @@ -475,7 +491,7 @@ None #### Returns An array of pending request objects. -A request object contains the following details: +A request object contains: - `account`: `string` - Account ID. - `id`: `string` - Request ID. @@ -544,7 +560,9 @@ Rejects a pending request and removes it from the list of pending requests. #### Parameters -`id`: `string` - Request ID. +An object containing: + +- `id`: `string` - Request ID. #### Returns @@ -580,7 +598,7 @@ Submits a new request. #### Parameters -A request object containing the following details: +A request object containing: - `account`: `string` - Account ID. - `id`: `string` - Request ID. diff --git a/snaps/reference/keyring-api/interface-api.md b/snaps/reference/keyring-api/interface-api.md index f9d167dd0ed..17a95fd9618 100644 --- a/snaps/reference/keyring-api/interface-api.md +++ b/snaps/reference/keyring-api/interface-api.md @@ -2,24 +2,474 @@ sidebar_position: 2 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Keyring Interface API +[Account management Snaps](../../features/custom-evm-accounts) can implement the Keyring Interface +API to support dapp requests. + ## EOA methods -### `eth_sign` +The following methods are used by externally owned accounts (EOAs). + +### `personal_sign` + +Presents a plain text signature challenge to the user and returns the signed response. +Equivalent to `eth_sign` on some other wallets, and prepends a safe prefix to the signed message to +prevent the challenge tricking users into signing a financial transaction. + +#### Parameters + +An array containing: + +1. Message to sign: `string` - Hex-encoded UTF-8 string to present to the user. +2. Address: `string` - Address of the requested signing account. + +#### Returns + +Signature: `string` - Hex-encoded signature. + +#### Example + + + + +```json +{ + "method": "personal_sign", + "params": [ + "0x4578616d706c652060706572736f6e616c5f7369676e60206d657373616765", + "0x5874174dcf1ab6F7Efd8496f4f09404CD1c5bA84" + ] +} +``` + + + + +```json +"0x262d12322b75228d09bbe3c104b91c1df32794126ce6a851e5c2721deb42d60e20b6eff3a1e2b5d29c2680edfb42e8497dbd7e75d0591a390a9385861b40f73d1c" +``` + + + ### `eth_signTransaction` +Signs a transaction that can be submitted to the network later using +[`eth_sendRawTransaction`](https://ethereum.org/developers/docs/apis/json-rpc#eth_sendrawtransaction). + +#### Parameters + +An array containing: + +1. Transaction object to sign, which contains: + - `type`: `string` - [Transaction type.](https://docs.infura.io/api/networks/ethereum/concepts/transaction-types) + - `nonce`: `string` - Anti-replay parameter. + - `to`: `string` - Recipient address, or `null` if this is a contract creation transaction. + - `from`: `string` - Sender address. + - `value`: `string` - Value to be transferred, in wei. + - `data`: `string` - Compiled code of a contract OR hash of the invoked method signature and + encoded parameters. + - `gasLimit`: `string` - Gas provided by the sender. + - `gasPrice`: `string` - (Optional) Gas price, in wei, provided by the sender. + - `maxPriorityFeePerGas`: `string` - (Optional) Maximum fee, in wei, the sender is willing to + pay per gas above the base fee. + - `maxFeePerGas`:`string` - (Optional) Maximum total fee (base fee + priority fee), in wei, the + sender is willing to pay per gas. + - `accessList`: `object[]` - (Optional) List of addresses and storage keys the transaction plans to access. + - `chainId`: `string` - Chain ID. + +#### Returns + +A signature object containing: + +- `v`: `string` - ECDSA Recovery ID. +- `r`: `string` - ECDSA signature r. +- `s`: `string` - ECDSA signature s. + +#### Example + + + + +```json +{ + "method": "eth_signTransaction", + "params": [ + { + "type": "0x2", + "nonce": "0x1", + "to": "0x0c54fccd2e384b4bb6f2e405bf5cbc15a017aafb", + "from": "0x660265edc169bab511a40c0e049cc1e33774443d", + "value": "0x0", + "data": "0x", + "gasLimit": "0x5208", + "maxPriorityFeePerGas": "0x3b9aca00", + "maxFeePerGas": "0x2540be400", + "accessList": [], + "chainId": "0xaa36a7" + } + ] +} +``` + + + + +```json +{ + "method": "eth_signTransaction", + "params": [ + { + "type": "0x0", + "nonce": "0x0", + "to": "0x0c54fccd2e384b4bb6f2e405bf5cbc15a017aafb", + "from": "0x660265edc169bab511a40c0e049cc1e33774443d", + "value": "0x0", + "data": "0x", + "gasLimit": "0x5208", + "gasPrice": "0x2540be400", + "chainId": "0xaa36a7" + } + ] +} +``` + + + + +```json +{ + "v": "0x1", + "r": "0x51991c5099327d3c7eaa745de60c52a93555e5cbc418eb9b405fe92d986dee08", + "s": "0x65b1d20a39360c31de69f872244e23a3549b702e11bc7d8eb3586812ac62be8d" +} +``` + + + + ### `eth_signTypedData_v4` -### `personal_sign` +Presents a data message for the user to sign in a structured and readable format, and returns the +signed response. +Introduced by [EIP-712](https://eips.ethereum.org/EIPS/eip-712). + +#### Parameters + +An array containing: + +1. Address: `string` - Address of the requested signing account. +2. Typed data: `object` - Typed data object containing: + - `types`: `object` - Types object containing: + - `EIP712Domain`: `array` - Array specifying one or more of the following domain separator values: + - `name` - User-readable name of the signing domain, i.e., name of the dapp or the protocol. + - `version` - Current major version of the signing domain. + - `chainId` - Chain ID of the network. + - `verifyingContract` - Address of the contract that will verify the signature. + - `salt` - Disambiguating salt for the protocol. + - `primaryType`: `string` - Primary type. + - `domain`: `object` - Domain separator values specified in the `EIP712Domain` type. + - `message`: `object` - Message to present to the user. + +#### Returns + +Signature: `string` - Hex-encoded signature. + +#### Example + + + + +```json +{ + "method": "eth_signTypedData_v4", + "params": [ + "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826", + { + "types": { + "EIP712Domain": [ + { "name": "name", "type": "string" }, + { "name": "version", "type": "string" }, + { "name": "chainId", "type": "uint256" }, + { "name": "verifyingContract", "type": "address" } + ], + "Person": [ + { "name": "name", "type": "string" }, + { "name": "wallet", "type": "address" } + ], + "Mail": [ + { "name": "from", "type": "Person" }, + { "name": "to", "type": "Person" }, + { "name": "contents", "type": "string" } + ] + }, + "primaryType": "Mail", + "domain": { + "name": "Ether Mail", + "version": "1", + "chainId": 1, + "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC" + }, + "message": { + "from": { + "name": "Cow", + "wallet": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826" + }, + "to": { + "name": "Bob", + "wallet": "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB" + }, + "contents": "Hello, Bob!" + } + } + ] +} +``` + + + + +```json +"0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c" +``` + + + ### Deprecated methods +Snaps can also implement [deprecated signing +methods](/wallet/concepts/signing-methods/#deprecated-signing-methods) that some dapps might use. + ## ERC-4337 methods +:::flaskOnly +::: + +The following methods are used by [ERC-4337 accounts](../../features/custom-evm-accounts/index.md#account-abstraction-erc-4337). + ### `eth_prepareUserOperation` +Prepares a new user operation from transaction data. + +#### Parameters + +An array containing: + +1. Transaction intents object, which contains: + - `to`: `string` - Recipient address, or `null` if this is a contract creation transaction. + - `value`: `string` - Value to be transferred, in wei. + - `data`: `string` - Compiled code of a contract OR hash of the invoked method signature and + encoded parameters. + +#### Returns + +A user operation details object containing: + +- `callData`: `string` - Data to pass to the sender during the main execution call. +- `initCode`: `string` - Account bytecode (needed if and only if the account is not yet on-chain and + needs to be created). +- `nonce`: `string` - Anti-replay parameter. +- `gasLimits` - (Optional) Gas limits object containing: + - `callGasLimit`: `string` - Amount of gas to allocate to the main execution call. + - `verificationGasLimit`: `string` - Amount of gas to allocate to the verification step. + - `preVerificationGas`: `string` - Amount of gas to compensate the bundler for pre-verification + execution, to pay for callData, and to account for overhead that can't be tracked on-chain. +- `dummySignature`: `string` - Dummy `signature`. +- `dummyPaymasterAndData`: `string` - Dummy `paymasterAndData`. +- `bundlerUrl`: `string` - Bundler URL. + +#### Example + + + + +```json +{ + "method": "eth_prepareUserOperation", + "params": [ + { + "to": "0x0c54fccd2e384b4bb6f2e405bf5cbc15a017aafb", + "value": "0x0", + "data": "0x" + }, + { + "to": "0x660265edc169bab511a40c0e049cc1e33774443d", + "value": "0x0", + "data": "0x619a309f" + } + ] +} +``` + + + + +```json +{ + "callData": "0x70641a22000000000000000000000000f3de3c0d654fda23dad170f0f320a921725091270000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000e49871efa4000000000000000000000000dac17f958d2ee523a2206206994597c13d831ec700000000000000000000000000000000000000000000000000000000067fd192000000000000000000000000000000000000000001411a0c3b763237f484fdd70000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000280000000000000003b6d03400d4a11d5eeaac28ec3f61d100daf4d40471f185280000000000000003b6d03408f1b19622a888c53c8ee4f7d7b4dc8f574ff906800000000000000000000000000000000000000000000000000000000", + "initCode": "0x22ff1dc5998258faa1ea45a776b57484f8ab80a2296601cd0000000000000000000000005147ce3947a407c95687131be01a2b8d55fd0a400000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000007d91ea6a0bc4a4238cd72386d935e35e3d8c318400000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000", + "nonce": "0x1", + "gasLimits": { + "callGasLimit": "0x58a83", + "verificationGasLimit": "0xe8c4", + "preVerificationGas": "0xc57c" + }, + "dummySignature": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "dummyPaymasterAndData": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "bundlerUrl": "https://bundler.example.com/rpc" +} +``` + + + + ### `eth_patchUserOperation` +Patches some allowed properties of a user operation. + +#### Parameters + +An array containing: + +1. User operation object, which contains: + - `sender`: `string` - Account making the operation. + - `callData`: `string` - Data to pass to the sender during the main execution call. + - `initCode`: `string` - Account bytecode (needed if and only if the account is not yet on-chain + and needs to be created). + - `nonce`: `string` - Anti-replay parameter. + - `callGasLimit`: `string` - Amount of gas to allocate to the main execution call. + - `verificationGasLimit`: `string` - Amount of gas to allocate to the verification step. + - `preVerificationGas`: `string` - Amount of gas to compensate the bundler for pre-verification + execution, to pay for callData, and to account for overhead that can't be tracked on-chain. + - `maxFeePerGas`: `string` - Maximum total fee the sender is willing to pay per gas. + - `maxPriorityFeePerGas`: `string` - Maximum fee the sender is willing to pay per gas above the + base fee. + - `paymasterAndData`: `string` - Address of the paymaster sponsoring the transaction, followed + by extra data to send to the paymaster (empty for self-sponsored transactions). + - `signature`: `string` - Data passed into the account along with the nonce during the + verification step. + +#### Returns + +A partial user operation object containing: + +- `paymasterAndData`: `string` - Address of the paymaster sponsoring the transaction, followed + by extra data to send to the paymaster (empty for self-sponsored transactions). +- `callGasLimit`: `string` - (Optional) Amount of gas to allocate to the main execution call. +- `verificationGasLimit`: `string` - (Optional) Amount of gas to allocate to the verification step. +- `preVerificationGas`: `string` - (Optional) Amount of gas to compensate the bundler for + pre-verification execution, to pay for callData, and to account for overhead that can't be tracked on-chain. + +#### Example + + + + +```json +{ + "method": "eth_patchUserOperation", + "params": [ + { + "sender": "0x4584d2B4905087A100420AFfCe1b2d73fC69B8E4", + "nonce": "0x1", + "initCode": "0x", + "callData": "0x70641a22000000000000000000000000f3de3c0d654fda23dad170f0f320a921725091270000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000e49871efa4000000000000000000000000dac17f958d2ee523a2206206994597c13d831ec700000000000000000000000000000000000000000000000000000000067fd192000000000000000000000000000000000000000001411a0c3b763237f484fdd70000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000280000000000000003b6d03400d4a11d5eeaac28ec3f61d100daf4d40471f185280000000000000003b6d03408f1b19622a888c53c8ee4f7d7b4dc8f574ff906800000000000000000000000000000000000000000000000000000000", + "callGasLimit": "0x58a83", + "verificationGasLimit": "0xe8c4", + "preVerificationGas": "0xc57c", + "maxFeePerGas": "0x87f0878c0", + "maxPriorityFeePerGas": "0x1dcd6500", + "paymasterAndData": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "signature": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" + } + ] +} +``` + + + + +```json +{ + "paymasterAndData": "0x952514d7cBCB495EACeB86e02154921401dB0Cd9dac17f958d2ee523a2206206994597c13d831ec700000000000000000000000000000000000000000000000000000000779b3fbb00000000000000006565b267000000000000000000000000000000000000000029195b31a9b1c6ccdeff53e359ebbcd5f075a93c1aaed93302e5fde5faf8047028b296b8a3fa4e22b063af5069ae9f656736ffda0ee090c0311155722b905f781b", + "callGasLimit": "0x58a83", + "verificationGasLimit": "0xe8c4", + "preVerificationGas": "0xc57c" +} +``` + + + + ### `eth_signUserOperation` + +Signs a user operation. + +#### Parameters + +An array containing: + +1. User operation object, which contains: + - `sender`: `string` - Account making the operation. + - `callData`: `string` - Data to pass to the sender during the main execution call. + - `initCode`: `string` - Account bytecode (needed if and only if the account is not yet on-chain + and needs to be created). + - `nonce`: `string` - Anti-replay parameter. + - `callGasLimit`: `string` - Amount of gas to allocate to the main execution call. + - `verificationGasLimit`: `string` - Amount of gas to allocate to the verification step. + - `preVerificationGas`: `string` - Amount of gas to compensate the bundler for pre-verification + execution, to pay for callData, and to account for overhead that can't be tracked on-chain. + - `maxFeePerGas`: `string` - Maximum total fee the sender is willing to pay per gas. + - `maxPriorityFeePerGas`: `string` - Maximum fee the sender is willing to pay per gas above the + base fee. + - `paymasterAndData`: `string` - Address of the paymaster sponsoring the transaction, followed + by extra data to send to the paymaster (empty for self-sponsored transactions). + - `signature`: `string` - Data passed into the account along with the nonce during the + verification step. +2. Entry point: `string` - Hash of the entry point contract. + +#### Returns + +Signature: `string` - Hex-encoded signature. + +#### Example + + + + +```json +{ + "method": "eth_signUserOperation", + "params": [ + { + "sender": "0x4584d2B4905087A100420AFfCe1b2d73fC69B8E4", + "nonce": "0x1", + "initCode": "0x", + "callData": "0x70641a22000000000000000000000000f3de3c0d654fda23dad170f0f320a921725091270000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000e49871efa4000000000000000000000000dac17f958d2ee523a2206206994597c13d831ec700000000000000000000000000000000000000000000000000000000067fd192000000000000000000000000000000000000000001411a0c3b763237f484fdd70000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000280000000000000003b6d03400d4a11d5eeaac28ec3f61d100daf4d40471f185280000000000000003b6d03408f1b19622a888c53c8ee4f7d7b4dc8f574ff906800000000000000000000000000000000000000000000000000000000", + "callGasLimit": "0x58a83", + "verificationGasLimit": "0xe8c4", + "preVerificationGas": "0xc57c", + "maxFeePerGas": "0x87f0878c0", + "maxPriorityFeePerGas": "0x1dcd6500", + "paymasterAndData": "0x952514d7cBCB495EACeB86e02154921401dB0Cd9dac17f958d2ee523a2206206994597c13d831ec700000000000000000000000000000000000000000000000000000000779b3fbb00000000000000006565b267000000000000000000000000000000000000000029195b31a9b1c6ccdeff53e359ebbcd5f075a93c1aaed93302e5fde5faf8047028b296b8a3fa4e22b063af5069ae9f656736ffda0ee090c0311155722b905f781b", + "signature": "0x" + }, + "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789" + ] +} +``` + + + + +```json +"0x6565acc7efd3c85e4c0c221c2958ff6c3ae68401b23b33fdcd1a2d49034c30d97b1cfa17487b90253a5dfd54ef5188688592c2fd56ba44ee4d948ea259d636cd550f6dd21b" +``` + + + From 012105728b940eb7661c50494c844340b3747acc Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Mon, 26 Feb 2024 10:58:22 -0800 Subject: [PATCH 3/7] document events, objects, and other edits --- .../create-account-snap.md | 108 ++++-------------- .../create-companion-dapp.md | 15 ++- snaps/features/custom-evm-accounts/index.md | 38 +++--- .../features/custom-evm-accounts/security.md | 43 +++---- .../keyring-api/client-api/events.md | 105 +++++++++++++++++ .../{client-api.md => client-api/index.md} | 86 +++----------- .../keyring-api/client-api/objects.md | 73 ++++++++++++ .../reference/keyring-api/data-structures.md | 11 -- snaps/reference/keyring-api/events.md | 5 - snaps/reference/keyring-api/index.md | 11 +- snaps/reference/keyring-api/interface-api.md | 2 +- 11 files changed, 274 insertions(+), 223 deletions(-) create mode 100644 snaps/reference/keyring-api/client-api/events.md rename snaps/reference/keyring-api/{client-api.md => client-api/index.md} (71%) create mode 100644 snaps/reference/keyring-api/client-api/objects.md delete mode 100644 snaps/reference/keyring-api/data-structures.md delete mode 100644 snaps/reference/keyring-api/events.md diff --git a/snaps/features/custom-evm-accounts/create-account-snap.md b/snaps/features/custom-evm-accounts/create-account-snap.md index 423682dc090..6eae6b72fb7 100644 --- 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) @@ -65,7 +65,8 @@ Add a list of dapp URLs allowed to call Keyring API methods on your Snap using t ### 3. Implement the Keyring API -Implement the [required Keyring API methods](security.md#limit-the-methods-exposed-to-dapps) in your Snap: +Implement the [Keyring Client API](../../reference/keyring-api/client-api/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 +76,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/client-api/index.md#keyring_submitrequest) +method of the Keyring API. +See the EVM methods for [externally owned accounts](../../reference/keyring-api/interface-api.md#eoa-methods) +and [ERC-4337 accounts](../../reference/keyring-api/interface-api.md#erc-4337-methods). The following is an example of a `personal_sign` request: @@ -130,84 +131,21 @@ 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). +Notify MetaMask when [Keyring API events](../../reference/keyring-api/client-api/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 Keyring API diff --git a/snaps/features/custom-evm-accounts/create-companion-dapp.md b/snaps/features/custom-evm-accounts/create-companion-dapp.md index a4075c78452..9baaddd6216 100644 --- 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) ::: @@ -39,9 +38,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"; @@ -52,10 +51,10 @@ let client = new KeyringSnapRpcClient(snapId, window.ethereum); ### 3. Call Keyring 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 +[Keyring Client API](../../reference/keyring-api/client-api/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/client-api/index.md#keyringlist_accounts): ```typescript const accounts = await client.listAccounts(); diff --git a/snaps/features/custom-evm-accounts/index.md b/snaps/features/custom-evm-accounts/index.md index f4d66f5a8c5..7529d23adc4 100644 --- a/snaps/features/custom-evm-accounts/index.md +++ b/snaps/features/custom-evm-accounts/index.md @@ -139,7 +139,7 @@ Site -->>- User: Done ``` The companion dapp presents a user interface allowing the user to configure their custom account. -The dapp creates an account using [`keyring_createAccount`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md#createaccount). +The dapp creates an account using [`keyring_createAccount`](../../reference/keyring-api/client-api/index.md#keyring_createaccount). The Snap keeps track of the accounts that it creates using [`snap_manageState`](../../reference/snaps-api.md#snap_managestate). Once the Snap has created an account, it notifies MetaMask using @@ -193,15 +193,14 @@ MetaMask -->>- Dapp: result Dapp -->>- User: Done ``` -The flow starts when a user or dapp initiates a [sign request](#supported-signing-methods). +The flow starts when a user or dapp initiates a sign request. At that point, MetaMask detects that this interaction is requested for an account controlled by the account management Snap. After the user approves the transaction in MetaMask, MetaMask calls -[`keyring_submitRequest`](../../reference/keyring-api/type-aliases/Keyring.md#submitrequest), which -receives the original RPC request and returns a -[`SubmitRequestResponse`](../../reference/keyring-api/variables/SubmitRequestResponseStruct.md) -with `pending` set to `false`, and `result` set to the requested signature. +[`keyring_submitRequest`](../../reference/keyring-api/client-api/index.md#keyring_submitrequest), +which receives the original RPC request and returns a response with `pending` set to `false`, and +`result` set to the requested signature. ### Asynchronous transaction flow @@ -257,8 +256,9 @@ Dapp -->>- User: Done ``` The flow starts the same way as the [synchronous flow](#synchronous-transaction-flow): a user or -dapp initiates a [sign request](#supported-signing-methods). -After approval, MetaMask calls [`keyring_submitRequest`](../../reference/keyring-api/type-aliases/Keyring.md#submitrequest). +dapp initiates a sign request. +After approval, MetaMask calls +[`keyring_submitRequest`](../../reference/keyring-api/client-api/index.md#keyring_submitrequest). Since the Snap doesn't answer the request directly, it stores the pending request in its internal state using [`snap_manageState`](../../reference/snaps-api.md#snap_managestate). @@ -268,9 +268,9 @@ This response can optionally contain a redirect URL that MetaMask will open in a the user to interact with the Snap companion dapp. The companion dapp gets the Snap's pending request using -[`keyring_getRequest`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md#getrequest). +[`keyring_getRequest`](../../reference/keyring-api/client-api/index.md#keyring_getrequest). It resolves the request using -[`keyring_approveRequest`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md#approverequest), +[`keyring_approveRequest`](../../reference/keyring-api/client-api/index.md#keyring_approverequest), and the Snap resolves the request using [`snap_manageAccounts`](../../reference/snaps-api.md#snap_manageaccounts), notifying MetaMask of the result. @@ -279,10 +279,10 @@ notifying MetaMask of the result. An account management Snap can implement the following methods to support dapp requests from externally owned accounts (EOAs): -- [`personal_sign`](/wallet/reference/personal_sign) -- [`eth_signTypedData_v4`](/wallet/reference/eth_signtypeddata_v4) -- [`eth_signTransaction`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_signtransaction) -- [Deprecated signing methods](/wallet/concepts/signing-methods/#deprecated-signing-methods) +- [`personal_sign`](../../reference/keyring-api/interface-api.md#personal_sign) +- [`eth_signTypedData_v4`](../../reference/keyring-api/interface-api.md#eth_signtypeddata_v4) +- [`eth_signTransaction`](../../reference/keyring-api/interface-api.md#eth_signtransaction) +- [Deprecated signing methods](../../reference/keyring-api/interface-api.md#deprecated-methods) ## Account abstraction (ERC-4337) @@ -297,9 +297,9 @@ Users can use these ERC-4337 accounts instead of externally owned accounts as pr An account management Snap can implement the following methods to support dapp requests from ERC-4337 accounts: -- [`eth_prepareUserOperation`](https://github.com/MetaMask/keyring-api/blob/main/docs/evm_methods_userOp.md#eth_prepareuseroperation) -- [`eth_patchUserOperation`](https://github.com/MetaMask/keyring-api/blob/main/docs/evm_methods_userOp.md#eth_patchuseroperation) -- [`eth_signUserOperation`](https://github.com/MetaMask/keyring-api/blob/main/docs/evm_methods_userOp.md#eth_signuseroperation) +- [`eth_prepareUserOperation`](../../reference/keyring-api/interface-api.md#eth_prepareuseroperation) +- [`eth_patchUserOperation`](../../reference/keyring-api/interface-api.md#eth_patchuseroperation) +- [`eth_signUserOperation`](../../reference/keyring-api/interface-api.md#eth_signuseroperation) The user operation signing flow in an ERC-4337 compatible account Snap looks like the following: @@ -348,8 +348,8 @@ MetaMask ->> MetaMask: Submit userOp to bundler and wait for transaction hash MetaMask -->>- Dapp: Transaction hash ``` -See the [ERC-4337 methods](https://github.com/MetaMask/keyring-api/blob/main/docs/evm_methods_userOp.md) -for more information about their parameters and response details. +See the [ERC-4337 methods](../../reference/keyring-api/interface-api.md#erc-4337-methods) for more +information about their parameters and response details. ## Examples diff --git a/snaps/features/custom-evm-accounts/security.md b/snaps/features/custom-evm-accounts/security.md index f1c603bd18f..02e9a19ecbb 100644 --- a/snaps/features/custom-evm-accounts/security.md +++ b/snaps/features/custom-evm-accounts/security.md @@ -11,7 +11,7 @@ tags: Refer to the following security guidelines when [creating an account management Snap](create-account-snap.md). :::tip see also -- [About custom EVM accounts](index.md) +- [Custom EVM accounts](index.md) - [Create an account management Snap](create-account-snap.md) - [Create an account management companion dapp](create-companion-dapp.md) - [Keyring API reference](../../reference/keyring-api/index.md) @@ -19,9 +19,9 @@ Refer to the following security guidelines when [creating an account management ## Do not add secret information to account objects -Ensure that you do not store any secret information in account objects -([`KeyringAccount`](../../reference/keyring-api/type-aliases/KeyringAccount.md) instances), since -they are exposed to dapps and MetaMask. +Ensure that you do not store any secret information in +[account objects](../../reference/keyring-api/client-api/objects.md#keyringaccount), since they are +exposed to dapps and MetaMask. For example: - ❌ **Do NOT do this:** @@ -64,23 +64,24 @@ For example: ## Limit the methods exposed to dapps -By default, MetaMask enforces the following restrictions on calling Keyring API methods on your Snap -based on the caller origin: - -| Method | MetaMask origin | Dapp origin | -|:------------------------------|:------------------:|:------------------:| -| `keyring_listAccounts` | :white_check_mark: | :white_check_mark: | -| `keyring_getAccount` | :white_check_mark: | :white_check_mark: | -| `keyring_createAccount` | :x: | :white_check_mark: | -| `keyring_filterAccountChains` | :white_check_mark: | :white_check_mark: | -| `keyring_updateAccount` | :x: | :white_check_mark: | -| `keyring_deleteAccount` | :white_check_mark: | :white_check_mark: | -| `keyring_exportAccount` | :x: | :white_check_mark: | -| `keyring_listRequests` | :white_check_mark: | :white_check_mark: | -| `keyring_getRequest` | :white_check_mark: | :white_check_mark: | -| `keyring_submitRequest` | :white_check_mark: | :x: | -| `keyring_approveRequest` | :x: | :white_check_mark: | -| `keyring_rejectRequest` | :white_check_mark: | :white_check_mark: | +By default, MetaMask enforces the following restrictions on calling +[Keyring Client API](../../reference/keyring-api/client-api/index.md) methods on your Snap based on +the caller origin: + +| Method | MetaMask origin | Dapp origin | +|:-------------------------------------------------------------------------------------------------------------|:------------------:|:------------------:| +| [`keyring_listAccounts`](../../reference/keyring-api/client-api/index.md#keyring_listaccounts) | :white_check_mark: | :white_check_mark: | +| [`keyring_getAccount`](../../reference/keyring-api/client-api/index.md#keyring_getaccount) | :white_check_mark: | :white_check_mark: | +| [`keyring_createAccount`](../../reference/keyring-api/client-api/index.md#keyring_createaccount) | :x: | :white_check_mark: | +| [`keyring_filterAccountChains`](../../reference/keyring-api/client-api/index.md#keyring_filteraccountchains) | :white_check_mark: | :white_check_mark: | +| [`keyring_updateAccount`](../../reference/keyring-api/client-api/index.md#keyring_updateaccount) | :x: | :white_check_mark: | +| [`keyring_deleteAccount`](../../reference/keyring-api/client-api/index.md#keyring_deleteaccount) | :white_check_mark: | :white_check_mark: | +| [`keyring_exportAccount`](../../reference/keyring-api/client-api/index.md#keyring_exportaccount) | :x: | :white_check_mark: | +| [`keyring_listRequests`](../../reference/keyring-api/client-api/index.md#keyring_listrequests) | :white_check_mark: | :white_check_mark: | +| [`keyring_getRequest`](../../reference/keyring-api/client-api/index.md#keyring_getrequest) | :white_check_mark: | :white_check_mark: | +| [`keyring_submitRequest`](../../reference/keyring-api/client-api/index.md#keyring_submitrequest) | :white_check_mark: | :x: | +| [`keyring_approveRequest`](../../reference/keyring-api/client-api/index.md#keyring_approverequest) | :x: | :white_check_mark: | +| [`keyring_rejectRequest`](../../reference/keyring-api/client-api/index.md#keyring_rejectrequest) | :white_check_mark: | :white_check_mark: | For example, a dapp is not allowed to call the `keyring_submitRequest` method of your Snap, and MetaMask is not allowed to call the `keyring_createAccount` method of your Snap. diff --git a/snaps/reference/keyring-api/client-api/events.md b/snaps/reference/keyring-api/client-api/events.md new file mode 100644 index 00000000000..281ecbd088d --- /dev/null +++ b/snaps/reference/keyring-api/client-api/events.md @@ -0,0 +1,105 @@ +--- +sidebar_position: 2 +toc_max_heading_level: 2 +sidebar_label: Events +--- + +# Keyring Client API events + +[Account management Snaps](../../../features/custom-evm-accounts/index.md) can notify MetaMask of the +following [Keyring Client API](index.md) events. + +## `AccountCreated` + +An account is created. +MetaMask returns an error if the account already exists or the account object is invalid. + +### Example + +```typescript +try { + emitSnapKeyringEvent(snap, KeyringEvent.AccountCreated, { account }); + // Update your Snap's state... +} catch (error) { + // Handle the error... +} +``` + +## `AccountUpdated` + +An account is updated. +MetaMask returns an error if one of the following is true: + +- The account does not exist. +- The account object is invalid. +- The account address is updated. + +### Example + +```typescript +try { + emitSnapKeyringEvent(snap, KeyringEvent.AccountUpdated, { account }); + // Update your Snap's state... +} catch (error) { + // Handle the error... +} +``` + +## `AccountDeleted` + +An account is deleted. +The delete event is idempotent, so it is safe to emit even if the account does not exist. + +### Example + +```typescript +try { + emitSnapKeyringEvent(snap, KeyringEvent.AccountDeleted, { + id: account.id, + }); + // Update your Snap's state... +} catch (error) { + // Handle the error... +} +``` + +## `RequestApproved` + +A request is approved. +MetaMask returns an error if the request does not exist. +This event only applies to Snaps that +[handle requests asynchronously](../../../features/custom-evm-accounts/index.md#asynchronous-transaction-flow). + +### Example + +```typescript +try { + emitSnapKeyringEvent(snap, KeyringEvent.RequestApproved, { + id: request.id, + result, + }); + // Update your Snap's state... +} catch (error) { + // Handle the error... +} +``` + +## `RequestRejected` + +A request is rejected. +MetaMask returns an error if the request does not exist. +This event only applies to Snaps that +[handle requests asynchronously](../../../features/custom-evm-accounts/index.md#asynchronous-transaction-flow). + +### Example + +```typescript +try { + emitSnapKeyringEvent(snap, KeyringEvent.RequestRejected, { + id: request.id, + }); + // Update your Snap's state... +} catch (error) { + // Handle the error... +} +``` diff --git a/snaps/reference/keyring-api/client-api.md b/snaps/reference/keyring-api/client-api/index.md similarity index 71% rename from snaps/reference/keyring-api/client-api.md rename to snaps/reference/keyring-api/client-api/index.md index dbd378a2e45..c79fc069318 100644 --- a/snaps/reference/keyring-api/client-api.md +++ b/snaps/reference/keyring-api/client-api/index.md @@ -7,10 +7,10 @@ import TabItem from '@theme/TabItem'; # Keyring Client API -Dapps can communicate with [account management Snaps](../../features/custom-evm-accounts/index.md) +Dapps can communicate with [account management Snaps](../../../features/custom-evm-accounts/index.md) using the Keyring Client API. The dapp must be [allowed to call each -method](../../features/custom-evm-accounts/security.md#limit-the-methods-exposed-to-dapps). +method](../../../features/custom-evm-accounts/security.md#limit-the-methods-exposed-to-dapps). ## Account methods @@ -24,18 +24,11 @@ Creates a new account. An object containing: -- `options`: `Record` - Snap-defined options required for the account creation. +- `options`: `Record` - Snap-defined account options. #### Returns -An account object containing: - -- `address`: `string` - Account address. -- `id`: `string` - Account ID. -- `methods`: `string[]` - List of supported [Keyring Interface API](interface-api.md) methods. -- `options`: `Record` - Snap-defined options. -- `type`: `string` - `"eip155:eoa"` for an externally owned account (EOA) or `"eip155:erc4337"` for - an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) account. +[An account object.](objects.md#keyringaccount) #### Example @@ -86,7 +79,7 @@ Deletes an existing account. An object containing: -- `id`: `string` - ID of the account to be deleted. +- `id`: `string` - ID of the account to be deleted (UUIDv4). #### Returns @@ -125,7 +118,7 @@ A Snap might choose to not support this method. An object containing: -- `id`: `string` - ID of the account to be exported. +- `id`: `string` - ID of the account to be exported (UUIDv4). #### Returns @@ -167,7 +160,7 @@ TO DO An object containing: -- `id`: `string` - Account ID. +- `id`: `string` - Account ID (UUIDv4). - `chains`: `string[]` - TO DO #### Returns @@ -207,18 +200,11 @@ Gets an account from an ID. An object containing: -- `id`: `string` - Account ID. +- `id`: `string` - Account ID (UUIDv4). #### Returns -An account object containing: - -- `address`: `string` - Account address. -- `id`: `string` - Account ID. -- `methods`: `string[]` - List of supported [Keyring Interface API](interface-api.md) methods. -- `options`: `Record` - Snap-defined options. -- `type`: `string` - `"eip155:eoa"` for an externally owned account (EOA) or `"eip155:erc4337"` for - an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) account. +[An account object.](objects.md#keyringaccount) #### Example @@ -268,15 +254,7 @@ None #### Returns -An array of account objects handled by the Snap. -An account object contains: - -- `address`: `string` - Account address. -- `id`: `string` - Account ID. -- `methods`: `string[]` - List of supported [Keyring Interface API](interface-api.md) methods. -- `options`: `Record` - Snap-defined options. -- `type`: `string` - `"eip155:eoa"` for an externally owned account (EOA) or `"eip155:erc4337"` for - an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) account. +An array of [account objects](objects.md#keyringaccount) handled by the Snap. #### Example @@ -331,14 +309,7 @@ Updates an account. #### Parameters -An account object containing: - -- `address`: `string` - Account address. -- `id`: `string` - Account ID. -- `methods`: `string[]` - List of supported [Keyring Interface API](interface-api.md) methods. -- `options`: `Record` - Snap-defined options. -- `type`: `string` - `"eip155:eoa"` for an externally owned account (EOA) or `"eip155:erc4337"` for - an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) account. +[An account object.](objects.md#keyringaccount) #### Returns @@ -435,15 +406,7 @@ An object containing: #### Returns -A request object containing: - -- `account`: `string` - Account ID. -- `id`: `string` - Request ID. -- `request` - Inner request sent by the client application, containing: - - `method`: `string` - The request method. - - `params`: `Json[]` - Optional method parameters. -- `scope`: `string` - Request's scope ([CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) - chain ID). +[A request object.](objects.md#keyringrequest) #### Example @@ -490,16 +453,7 @@ None #### Returns -An array of pending request objects. -A request object contains: - -- `account`: `string` - Account ID. -- `id`: `string` - Request ID. -- `request` - Inner request sent by the client application, containing: - - `method`: `string` - The request method. - - `params`: `Json[]` - Optional method parameters. -- `scope`: `string` - Request's scope ([CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) - chain ID). +An array of pending [request objects](objects.md#keyringrequest). #### Example @@ -598,25 +552,17 @@ Submits a new request. #### Parameters -A request object containing: - -- `account`: `string` - Account ID. -- `id`: `string` - Request ID. -- `request` - Inner request sent by the client application, containing: - - `method`: `string` - The request method. - - `params`: `Json[]` - Optional method parameters. -- `scope`: `string` - Request's scope ([CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) - chain ID). +[A request object.](objects.md#keyringrequest) #### Returns -If the request is [synchronous](../../features/custom-evm-accounts/index.md#synchronous-transaction-flow), +If the request is [synchronous](../../../features/custom-evm-accounts/index.md#synchronous-transaction-flow), `keyring_submitRequest` returns an object containing: - `pending` - `false` to indicate a synchronous request. - `result`: `Json` - Request result. -If the request is [asynchronous](../../features/custom-evm-accounts/index.md#asynchronous-transaction-flow), +If the request is [asynchronous](../../../features/custom-evm-accounts/index.md#asynchronous-transaction-flow), `keyring_submitRequest` returns an object containing: - `pending` - `true` to indicate that the request will be handled asynchronously. diff --git a/snaps/reference/keyring-api/client-api/objects.md b/snaps/reference/keyring-api/client-api/objects.md new file mode 100644 index 00000000000..2b4b0c985a6 --- /dev/null +++ b/snaps/reference/keyring-api/client-api/objects.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 1 +toc_max_heading_level: 2 +sidebar_label: Objects +--- + +# Keyring Client API objects + +[Account management Snaps](../../../features/custom-evm-accounts/index.md) use the following objects +with the [Keyring Client API](index.md). + +## `KeyringAccount` + +An object representing an account with its properties and capabilities. +An account object contains: + +- `address`: `string` - Account address or next receive address (UTXO). +- `id`: `string` - Account ID (UUIDv4). +- `methods`: `string[]` - List of supported [Keyring Interface API](../interface-api.md) methods. +- `options`: `Record` - Snap-defined account options. +- `type`: `string` - Account type. + `"eip155:eoa"` for an externally owned account (EOA) or `"eip155:erc4337"` for an + [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) account. + +### Example + +```json +{ + "address": "0xd1f5279be4b4dd94133a23dee1b23f5bfc0db1d0", + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a", + "methods": [ + "eth_sign", + "eth_signTransaction", + "eth_signTypedData_v4", + "personal_sign" + ], + "options": { + "signerCount": 5, + "threshold": 3 + }, + "type": "eip155:eoa" +} +``` + +## `KeyringRequest` + +An object representing a request made to the account management Snap for account-related operations. +A request object contains: + +- `account`: `string` - Account ID (UUIDv4). +- `id`: `string` - Request ID (UUIDv4). +- `request` - Inner request sent by the client application, containing: + - `method`: `string` - The request method. + - `params`: `Json[]` - Optional method parameters. +- `scope`: `string` - Request's scope ([CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain ID). + +### Example + +```json +{ + "address": "0xd1f5279be4b4dd94133a23dee1b23f5bfc0db1d0", + "id": "f84d3a97-b6e1-47ea-8b0c-fd8609efaad4", + "request": { + "method": "personal_sign", + "params": [ + "0x4578616d706c652060706572736f6e616c5f7369676e60206d657373616765", + "0xe887f3b50232722e6eb4c1d3a03b34c9b345acd1" + ] + }, + "scope": "eip155:1" +} +``` diff --git a/snaps/reference/keyring-api/data-structures.md b/snaps/reference/keyring-api/data-structures.md deleted file mode 100644 index 42dc5375011..00000000000 --- a/snaps/reference/keyring-api/data-structures.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Keyring API data structures - -## `KeyringAccountStruct` - -## `KeyringRequestStruct` - -## `KeyringResponseStruct` diff --git a/snaps/reference/keyring-api/events.md b/snaps/reference/keyring-api/events.md deleted file mode 100644 index 144e01317b2..00000000000 --- a/snaps/reference/keyring-api/events.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Keyring API events diff --git a/snaps/reference/keyring-api/index.md b/snaps/reference/keyring-api/index.md index 0ee236a5956..b7360cd140e 100644 --- a/snaps/reference/keyring-api/index.md +++ b/snaps/reference/keyring-api/index.md @@ -7,12 +7,17 @@ tags: # Keyring API -This section describes the Keyring API methods. -See the left sidebar for the API categories and methods. +This section provides a detailed reference on the Keyring API methods, objects, and events that +enable [custom EVM accounts](../../features/custom-evm-accounts/index.md). +The Keyring API consists of: + +- [**Keyring Client API**](client-api) – An API for dapps to communicate with account management Snaps. +- [**Keyring Interface API**](interface-api.md) - EVM methods that account management Snaps can + implement to support dapp requests from custom accounts. :::tip See also - [Create an account management Snap](../../features/custom-evm-accounts/create-account-snap.md) - [Account management Snap security guidelines](../../features/custom-evm-accounts/security.md) - [Create an account management companion dapp](../../features/custom-evm-accounts/create-companion-dapp.md) -- [About the Keyring API](../../features/custom-evm-accounts/index.md) +- [Custom EVM accounts](../../features/custom-evm-accounts/index.md) ::: diff --git a/snaps/reference/keyring-api/interface-api.md b/snaps/reference/keyring-api/interface-api.md index 17a95fd9618..8df11332051 100644 --- a/snaps/reference/keyring-api/interface-api.md +++ b/snaps/reference/keyring-api/interface-api.md @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem'; # Keyring Interface API [Account management Snaps](../../features/custom-evm-accounts) can implement the Keyring Interface -API to support dapp requests. +API to support dapp requests from custom accounts. ## EOA methods From f4608846408d2b8124501b7c2e9dd86b2ae0bf45 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Mon, 26 Feb 2024 11:21:50 -0800 Subject: [PATCH 4/7] fix links --- snaps/features/custom-evm-accounts/index.md | 2 +- snaps/reference/keyring-api/client-api/events.md | 8 ++++---- snaps/reference/keyring-api/client-api/index.md | 10 +++++++--- snaps/reference/keyring-api/interface-api.md | 6 +++--- snaps/reference/snaps-api.md | 10 +++++----- 5 files changed, 20 insertions(+), 16 deletions(-) diff --git a/snaps/features/custom-evm-accounts/index.md b/snaps/features/custom-evm-accounts/index.md index b549a4e5f80..94c2de4803a 100644 --- a/snaps/features/custom-evm-accounts/index.md +++ b/snaps/features/custom-evm-accounts/index.md @@ -282,7 +282,7 @@ externally owned accounts (EOAs): - [`personal_sign`](../../reference/keyring-api/interface-api.md#personal_sign) - [`eth_signTypedData_v4`](../../reference/keyring-api/interface-api.md#eth_signtypeddata_v4) - [`eth_signTransaction`](../../reference/keyring-api/interface-api.md#eth_signtransaction) -- [Deprecated signing methods](../../reference/keyring-api/interface-api.md#deprecated-methods) +- [Deprecated signing methods](/wallet/concepts/signing-methods/#deprecated-signing-methods) ## Account abstraction (ERC-4337) diff --git a/snaps/reference/keyring-api/client-api/events.md b/snaps/reference/keyring-api/client-api/events.md index 281ecbd088d..01513b7898c 100644 --- a/snaps/reference/keyring-api/client-api/events.md +++ b/snaps/reference/keyring-api/client-api/events.md @@ -55,7 +55,7 @@ The delete event is idempotent, so it is safe to emit even if the account does n ```typescript try { emitSnapKeyringEvent(snap, KeyringEvent.AccountDeleted, { - id: account.id, + id: account.id, }); // Update your Snap's state... } catch (error) { @@ -75,8 +75,8 @@ This event only applies to Snaps that ```typescript try { emitSnapKeyringEvent(snap, KeyringEvent.RequestApproved, { - id: request.id, - result, + id: request.id, + result, }); // Update your Snap's state... } catch (error) { @@ -96,7 +96,7 @@ This event only applies to Snaps that ```typescript try { emitSnapKeyringEvent(snap, KeyringEvent.RequestRejected, { - id: request.id, + id: request.id, }); // Update your Snap's state... } catch (error) { diff --git a/snaps/reference/keyring-api/client-api/index.md b/snaps/reference/keyring-api/client-api/index.md index c79fc069318..6d809ce7155 100644 --- a/snaps/reference/keyring-api/client-api/index.md +++ b/snaps/reference/keyring-api/client-api/index.md @@ -165,7 +165,9 @@ An object containing: #### Returns -TO DO +An object containing: + +- `chains`: `string[]` - TO DO #### Example @@ -186,7 +188,9 @@ TO DO ```json -// TO DO +{ + "chains": // TO DO +} ``` @@ -377,7 +381,7 @@ An object containing: ```json { - "method": "keyring_approveRequest", + "method": "keyring_approveRequest", "params": { "id": "f84d3a97-b6e1-47ea-8b0c-fd8609efaad4" } diff --git a/snaps/reference/keyring-api/interface-api.md b/snaps/reference/keyring-api/interface-api.md index 8df11332051..d2ed253d8fb 100644 --- a/snaps/reference/keyring-api/interface-api.md +++ b/snaps/reference/keyring-api/interface-api.md @@ -7,8 +7,8 @@ import TabItem from '@theme/TabItem'; # Keyring Interface API -[Account management Snaps](../../features/custom-evm-accounts) can implement the Keyring Interface -API to support dapp requests from custom accounts. +[Account management Snaps](../../features/custom-evm-accounts/index.md) can implement the Keyring +Interface API to support dapp requests from custom accounts. ## EOA methods @@ -278,7 +278,7 @@ A user operation details object containing: - `callGasLimit`: `string` - Amount of gas to allocate to the main execution call. - `verificationGasLimit`: `string` - Amount of gas to allocate to the verification step. - `preVerificationGas`: `string` - Amount of gas to compensate the bundler for pre-verification - execution, to pay for callData, and to account for overhead that can't be tracked on-chain. + execution, to pay for `callData`, and to account for overhead that can't be tracked on-chain. - `dummySignature`: `string` - Dummy `signature`. - `dummyPaymasterAndData`: `string` - Dummy `paymasterAndData`. - `bundlerUrl`: `string` - Bundler URL. diff --git a/snaps/reference/snaps-api.md b/snaps/reference/snaps-api.md index 41e92c3a554..5932025be7c 100644 --- a/snaps/reference/snaps-api.md +++ b/snaps/reference/snaps-api.md @@ -569,7 +569,7 @@ This can be done using [`snap_manageState`](#snap_managestate). #### Parameters -`account` - A [`KeyringAccount`](./keyring-api/variables/KeyringAccountStruct.md) object. +`account` - [An account object.](keyring-api/client-api/objects.md#keyringaccount) #### Returns @@ -633,7 +633,7 @@ This can be done using [`snap_manageState`](#snap_managestate). #### Parameters -`account` - A [`KeyringAccount`](./keyring-api/variables/KeyringAccountStruct.md) object. +`account` - [An account object.](keyring-api/client-api/objects.md#keyringaccount) #### Returns @@ -709,7 +709,7 @@ state of accounts and the state known to MetaMask. #### Returns -An array of [keyring accounts](./keyring-api/variables/KeyringAccountStruct.md). +An array of [account objects](keyring-api/client-api/objects.md#keyringaccount). #### Example @@ -738,8 +738,8 @@ class MyKeyring implements Keyring { ### submitResponse Finalizes a signing request. -This is usually called as part of the `approveRequest` method of the -[`Keyring`](keyring-api/type-aliases/Keyring.md) interface. +This is usually called as part of the +[`keyring_approveRequest`](keyring-api/client-api/index.md#keyring_approverequest) method. #### Parameters From 8ecfcf963f4c63a62cedfcfd57eedd674ee0185b Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 28 Feb 2024 14:30:18 -0800 Subject: [PATCH 5/7] add descriptions and example for filterAccountChains --- .../reference/keyring-api/client-api/index.md | 20 ++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/snaps/reference/keyring-api/client-api/index.md b/snaps/reference/keyring-api/client-api/index.md index 6d809ce7155..bff6f5a9681 100644 --- a/snaps/reference/keyring-api/client-api/index.md +++ b/snaps/reference/keyring-api/client-api/index.md @@ -154,20 +154,22 @@ An object containing: ### `keyring_filterAccountChains` -TO DO +Filters for chains that an account can be used on. #### Parameters An object containing: - `id`: `string` - Account ID (UUIDv4). -- `chains`: `string[]` - TO DO +- `chains`: `string[]` - List of [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain IDs to filter. #### Returns An object containing: -- `chains`: `string[]` - TO DO +- `chains`: `string[]` - List of [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain IDs that the account can be used on. #### Example @@ -179,7 +181,12 @@ An object containing: "method": "keyring_filterAccountChains", "params": { "id": "091bbc2e-6625-44d0-ac5c-658670ca649a", - "chains": // TO DO + "chains": [ + "eip155:W", + "eip155:X", + "eip155:Y", + "eip155:Z" + ] } } ``` @@ -189,7 +196,10 @@ An object containing: ```json { - "chains": // TO DO + "chains": [ + "eip155:X", + "eip155:Y" + ] } ``` From d9c70bf8433fc000fa50314cf78441f054572cad Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Thu, 29 Feb 2024 11:23:13 -0800 Subject: [PATCH 6/7] rename and edit APIs --- .../create-account-snap.md | 21 ++++++------ .../create-companion-dapp.md | 9 +++--- snaps/features/custom-evm-accounts/index.md | 24 +++++++------- .../features/custom-evm-accounts/security.md | 32 +++++++++---------- .../events.md | 4 +-- .../index.md | 4 +-- .../objects.md | 6 ++-- .../{interface-api.md => chain-methods.md} | 6 ++-- snaps/reference/keyring-api/index.md | 8 +++-- snaps/reference/snaps-api.md | 8 ++--- 10 files changed, 63 insertions(+), 59 deletions(-) rename snaps/reference/keyring-api/{client-api => account-management}/events.md (96%) rename snaps/reference/keyring-api/{client-api => account-management}/index.md (99%) rename snaps/reference/keyring-api/{client-api => account-management}/objects.md (94%) rename snaps/reference/keyring-api/{interface-api.md => chain-methods.md} (99%) diff --git a/snaps/features/custom-evm-accounts/create-account-snap.md b/snaps/features/custom-evm-accounts/create-account-snap.md index 6eae6b72fb7..cd6ceeb172d 100644 --- a/snaps/features/custom-evm-accounts/create-account-snap.md +++ b/snaps/features/custom-evm-accounts/create-account-snap.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,9 @@ 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 [Keyring Client API](../../reference/keyring-api/client-api/index.md) 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 @@ -77,10 +78,10 @@ class MySnapKeyring implements Keyring { ### 4. Handle requests submitted by MetaMask MetaMask submits EVM requests from dapps using the -[`keyring_submitRequest`](../../reference/keyring-api/client-api/index.md#keyring_submitrequest) +[`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/interface-api.md#eoa-methods) -and [ERC-4337 accounts](../../reference/keyring-api/interface-api.md#erc-4337-methods). +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: @@ -131,8 +132,8 @@ The redirect message and URL is displayed to the user to help them continue the ### 5. Notify MetaMask about events -Notify MetaMask when [Keyring API events](../../reference/keyring-api/client-api/events.md) take -place, using the `emitSnapKeyringEvent()` helper function. +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: @@ -147,9 +148,9 @@ try { MetaMask returns an error if the account already exists or the account object is invalid. -### 6. Expose the Keyring API +### 6. Expose the Account Management API -Create an `onKeyringRequest` entry point handler method to expose the Keyring API methods +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 index 9baaddd6216..36d9b339af8 100644 --- a/snaps/features/custom-evm-accounts/create-companion-dapp.md +++ b/snaps/features/custom-evm-accounts/create-companion-dapp.md @@ -26,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 @@ -49,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` to invoke -[Keyring Client API](../../reference/keyring-api/client-api/index.md) methods on your Snap. +[Account Management API](../../reference/keyring-api/account-management/index.md) methods on your Snap. -For example, to call [`keyring_listAccounts`](../../reference/keyring-api/client-api/index.md#keyringlist_accounts): +For example, to call [`keyring_listAccounts`](../../reference/keyring-api/account-management/index.md#keyringlist_accounts): ```typescript const accounts = await client.listAccounts(); diff --git a/snaps/features/custom-evm-accounts/index.md b/snaps/features/custom-evm-accounts/index.md index 94c2de4803a..91ce16cf975 100644 --- a/snaps/features/custom-evm-accounts/index.md +++ b/snaps/features/custom-evm-accounts/index.md @@ -139,7 +139,7 @@ Site -->>- User: Done ``` The companion dapp presents a user interface allowing the user to configure their custom account. -The dapp creates an account using [`keyring_createAccount`](../../reference/keyring-api/client-api/index.md#keyring_createaccount). +The dapp creates an account using [`keyring_createAccount`](../../reference/keyring-api/account-management/index.md#keyring_createaccount). The Snap keeps track of the accounts that it creates using [`snap_manageState`](../../reference/snaps-api.md#snap_managestate). Once the Snap has created an account, it notifies MetaMask using @@ -198,7 +198,7 @@ At that point, MetaMask detects that this interaction is requested for an accoun account management Snap. After the user approves the transaction in MetaMask, MetaMask calls -[`keyring_submitRequest`](../../reference/keyring-api/client-api/index.md#keyring_submitrequest), +[`keyring_submitRequest`](../../reference/keyring-api/account-management/index.md#keyring_submitrequest), which receives the original RPC request and returns a response with `pending` set to `false`, and `result` set to the requested signature. @@ -258,7 +258,7 @@ Dapp -->>- User: Done The flow starts the same way as the [synchronous flow](#synchronous-transaction-flow): a user or dapp initiates a sign request. After approval, MetaMask calls -[`keyring_submitRequest`](../../reference/keyring-api/client-api/index.md#keyring_submitrequest). +[`keyring_submitRequest`](../../reference/keyring-api/account-management/index.md#keyring_submitrequest). Since the Snap doesn't answer the request directly, it stores the pending request in its internal state using [`snap_manageState`](../../reference/snaps-api.md#snap_managestate). @@ -268,9 +268,9 @@ This response can optionally contain a redirect URL that MetaMask will open in a the user to interact with the Snap companion dapp. The companion dapp gets the Snap's pending request using -[`keyring_getRequest`](../../reference/keyring-api/client-api/index.md#keyring_getrequest). +[`keyring_getRequest`](../../reference/keyring-api/account-management/index.md#keyring_getrequest). It resolves the request using -[`keyring_approveRequest`](../../reference/keyring-api/client-api/index.md#keyring_approverequest), +[`keyring_approveRequest`](../../reference/keyring-api/account-management/index.md#keyring_approverequest), and the Snap resolves the request using [`snap_manageAccounts`](../../reference/snaps-api.md#snap_manageaccounts), notifying MetaMask of the result. @@ -279,9 +279,9 @@ notifying MetaMask of the result. An account management Snap can implement the following methods to support dapp requests from externally owned accounts (EOAs): -- [`personal_sign`](../../reference/keyring-api/interface-api.md#personal_sign) -- [`eth_signTypedData_v4`](../../reference/keyring-api/interface-api.md#eth_signtypeddata_v4) -- [`eth_signTransaction`](../../reference/keyring-api/interface-api.md#eth_signtransaction) +- [`personal_sign`](../../reference/keyring-api/chain-methods.md#personal_sign) +- [`eth_signTypedData_v4`](../../reference/keyring-api/chain-methods.md#eth_signtypeddata_v4) +- [`eth_signTransaction`](../../reference/keyring-api/chain-methods.md#eth_signtransaction) - [Deprecated signing methods](/wallet/concepts/signing-methods/#deprecated-signing-methods) ## Account abstraction (ERC-4337) @@ -297,9 +297,9 @@ Users can use these ERC-4337 accounts instead of externally owned accounts as pr An account management Snap can implement the following methods to support dapp requests from ERC-4337 accounts: -- [`eth_prepareUserOperation`](../../reference/keyring-api/interface-api.md#eth_prepareuseroperation) -- [`eth_patchUserOperation`](../../reference/keyring-api/interface-api.md#eth_patchuseroperation) -- [`eth_signUserOperation`](../../reference/keyring-api/interface-api.md#eth_signuseroperation) +- [`eth_prepareUserOperation`](../../reference/keyring-api/chain-methods.md#eth_prepareuseroperation) +- [`eth_patchUserOperation`](../../reference/keyring-api/chain-methods.md#eth_patchuseroperation) +- [`eth_signUserOperation`](../../reference/keyring-api/chain-methods.md#eth_signuseroperation) The user operation signing flow in an ERC-4337 compatible account Snap looks like the following: @@ -348,7 +348,7 @@ MetaMask ->> MetaMask: Submit userOp to bundler and wait for transaction hash MetaMask -->>- Dapp: Transaction hash ``` -See the [ERC-4337 methods](../../reference/keyring-api/interface-api.md#erc-4337-methods) for more +See the [ERC-4337 methods](../../reference/keyring-api/chain-methods.md#erc-4337-methods) for more information about their parameters and response details. ## Examples diff --git a/snaps/features/custom-evm-accounts/security.md b/snaps/features/custom-evm-accounts/security.md index 02e9a19ecbb..3701f521ac7 100644 --- a/snaps/features/custom-evm-accounts/security.md +++ b/snaps/features/custom-evm-accounts/security.md @@ -20,7 +20,7 @@ Refer to the following security guidelines when [creating an account management ## Do not add secret information to account objects Ensure that you do not store any secret information in -[account objects](../../reference/keyring-api/client-api/objects.md#keyringaccount), since they are +[account objects](../../reference/keyring-api/account-management/objects.md#keyringaccount), since they are exposed to dapps and MetaMask. For example: @@ -65,23 +65,23 @@ For example: ## Limit the methods exposed to dapps By default, MetaMask enforces the following restrictions on calling -[Keyring Client API](../../reference/keyring-api/client-api/index.md) methods on your Snap based on +[Account Management API](../../reference/keyring-api/account-management/index.md) methods on your Snap based on the caller origin: | Method | MetaMask origin | Dapp origin | |:-------------------------------------------------------------------------------------------------------------|:------------------:|:------------------:| -| [`keyring_listAccounts`](../../reference/keyring-api/client-api/index.md#keyring_listaccounts) | :white_check_mark: | :white_check_mark: | -| [`keyring_getAccount`](../../reference/keyring-api/client-api/index.md#keyring_getaccount) | :white_check_mark: | :white_check_mark: | -| [`keyring_createAccount`](../../reference/keyring-api/client-api/index.md#keyring_createaccount) | :x: | :white_check_mark: | -| [`keyring_filterAccountChains`](../../reference/keyring-api/client-api/index.md#keyring_filteraccountchains) | :white_check_mark: | :white_check_mark: | -| [`keyring_updateAccount`](../../reference/keyring-api/client-api/index.md#keyring_updateaccount) | :x: | :white_check_mark: | -| [`keyring_deleteAccount`](../../reference/keyring-api/client-api/index.md#keyring_deleteaccount) | :white_check_mark: | :white_check_mark: | -| [`keyring_exportAccount`](../../reference/keyring-api/client-api/index.md#keyring_exportaccount) | :x: | :white_check_mark: | -| [`keyring_listRequests`](../../reference/keyring-api/client-api/index.md#keyring_listrequests) | :white_check_mark: | :white_check_mark: | -| [`keyring_getRequest`](../../reference/keyring-api/client-api/index.md#keyring_getrequest) | :white_check_mark: | :white_check_mark: | -| [`keyring_submitRequest`](../../reference/keyring-api/client-api/index.md#keyring_submitrequest) | :white_check_mark: | :x: | -| [`keyring_approveRequest`](../../reference/keyring-api/client-api/index.md#keyring_approverequest) | :x: | :white_check_mark: | -| [`keyring_rejectRequest`](../../reference/keyring-api/client-api/index.md#keyring_rejectrequest) | :white_check_mark: | :white_check_mark: | +| [`keyring_listAccounts`](../../reference/keyring-api/account-management/index.md#keyring_listaccounts) | :white_check_mark: | :white_check_mark: | +| [`keyring_getAccount`](../../reference/keyring-api/account-management/index.md#keyring_getaccount) | :white_check_mark: | :white_check_mark: | +| [`keyring_createAccount`](../../reference/keyring-api/account-management/index.md#keyring_createaccount) | :x: | :white_check_mark: | +| [`keyring_filterAccountChains`](../../reference/keyring-api/account-management/index.md#keyring_filteraccountchains) | :white_check_mark: | :white_check_mark: | +| [`keyring_updateAccount`](../../reference/keyring-api/account-management/index.md#keyring_updateaccount) | :x: | :white_check_mark: | +| [`keyring_deleteAccount`](../../reference/keyring-api/account-management/index.md#keyring_deleteaccount) | :white_check_mark: | :white_check_mark: | +| [`keyring_exportAccount`](../../reference/keyring-api/account-management/index.md#keyring_exportaccount) | :x: | :white_check_mark: | +| [`keyring_listRequests`](../../reference/keyring-api/account-management/index.md#keyring_listrequests) | :white_check_mark: | :white_check_mark: | +| [`keyring_getRequest`](../../reference/keyring-api/account-management/index.md#keyring_getrequest) | :white_check_mark: | :white_check_mark: | +| [`keyring_submitRequest`](../../reference/keyring-api/account-management/index.md#keyring_submitrequest) | :white_check_mark: | :x: | +| [`keyring_approveRequest`](../../reference/keyring-api/account-management/index.md#keyring_approverequest) | :x: | :white_check_mark: | +| [`keyring_rejectRequest`](../../reference/keyring-api/account-management/index.md#keyring_rejectrequest) | :white_check_mark: | :white_check_mark: | For example, a dapp is not allowed to call the `keyring_submitRequest` method of your Snap, and MetaMask is not allowed to call the `keyring_createAccount` method of your Snap. @@ -177,11 +177,11 @@ For example: } ``` -## Expose Keyring API methods using the onKeyringRequest entry point +## Expose Account Management API methods using the onKeyringRequest entry point The [`onRpcRequest`](../../reference/entry-points.md#onrpcrequest) entry point is a general-purpose entry point and has no restrictions on the methods that can be called. -Ensure that you only expose Keyring API methods using the `onKeyringRequest` entry point, which has +Ensure that you only expose Account Management API methods using the `onKeyringRequest` entry point, which has extra security checks. For example: diff --git a/snaps/reference/keyring-api/client-api/events.md b/snaps/reference/keyring-api/account-management/events.md similarity index 96% rename from snaps/reference/keyring-api/client-api/events.md rename to snaps/reference/keyring-api/account-management/events.md index 01513b7898c..f19774c17af 100644 --- a/snaps/reference/keyring-api/client-api/events.md +++ b/snaps/reference/keyring-api/account-management/events.md @@ -4,10 +4,10 @@ toc_max_heading_level: 2 sidebar_label: Events --- -# Keyring Client API events +# Account Management API events [Account management Snaps](../../../features/custom-evm-accounts/index.md) can notify MetaMask of the -following [Keyring Client API](index.md) events. +following [Account Management API](index.md) events. ## `AccountCreated` diff --git a/snaps/reference/keyring-api/client-api/index.md b/snaps/reference/keyring-api/account-management/index.md similarity index 99% rename from snaps/reference/keyring-api/client-api/index.md rename to snaps/reference/keyring-api/account-management/index.md index bff6f5a9681..f80d5e62b41 100644 --- a/snaps/reference/keyring-api/client-api/index.md +++ b/snaps/reference/keyring-api/account-management/index.md @@ -5,10 +5,10 @@ sidebar_position: 1 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Keyring Client API +# Account Management API Dapps can communicate with [account management Snaps](../../../features/custom-evm-accounts/index.md) -using the Keyring Client API. +using the Account Management API. The dapp must be [allowed to call each method](../../../features/custom-evm-accounts/security.md#limit-the-methods-exposed-to-dapps). diff --git a/snaps/reference/keyring-api/client-api/objects.md b/snaps/reference/keyring-api/account-management/objects.md similarity index 94% rename from snaps/reference/keyring-api/client-api/objects.md rename to snaps/reference/keyring-api/account-management/objects.md index 2b4b0c985a6..3a98ec8cc48 100644 --- a/snaps/reference/keyring-api/client-api/objects.md +++ b/snaps/reference/keyring-api/account-management/objects.md @@ -4,10 +4,10 @@ toc_max_heading_level: 2 sidebar_label: Objects --- -# Keyring Client API objects +# Account Management API objects [Account management Snaps](../../../features/custom-evm-accounts/index.md) use the following objects -with the [Keyring Client API](index.md). +with the [Account Management API](index.md). ## `KeyringAccount` @@ -16,7 +16,7 @@ An account object contains: - `address`: `string` - Account address or next receive address (UTXO). - `id`: `string` - Account ID (UUIDv4). -- `methods`: `string[]` - List of supported [Keyring Interface API](../interface-api.md) methods. +- `methods`: `string[]` - List of supported [Keyring Interface API](../chain-methods.md) methods. - `options`: `Record` - Snap-defined account options. - `type`: `string` - Account type. `"eip155:eoa"` for an externally owned account (EOA) or `"eip155:erc4337"` for an diff --git a/snaps/reference/keyring-api/interface-api.md b/snaps/reference/keyring-api/chain-methods.md similarity index 99% rename from snaps/reference/keyring-api/interface-api.md rename to snaps/reference/keyring-api/chain-methods.md index d2ed253d8fb..fd6183a622d 100644 --- a/snaps/reference/keyring-api/interface-api.md +++ b/snaps/reference/keyring-api/chain-methods.md @@ -5,10 +5,10 @@ sidebar_position: 2 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Keyring Interface API +# Chain Methods API -[Account management Snaps](../../features/custom-evm-accounts/index.md) can implement the Keyring -Interface API to support dapp requests from custom accounts. +[Account management Snaps](../../features/custom-evm-accounts/index.md) can choose to implement the +following EVM methods to support dapp requests from custom accounts. ## EOA methods diff --git a/snaps/reference/keyring-api/index.md b/snaps/reference/keyring-api/index.md index b7360cd140e..93473cb8acc 100644 --- a/snaps/reference/keyring-api/index.md +++ b/snaps/reference/keyring-api/index.md @@ -11,9 +11,11 @@ This section provides a detailed reference on the Keyring API methods, objects, enable [custom EVM accounts](../../features/custom-evm-accounts/index.md). The Keyring API consists of: -- [**Keyring Client API**](client-api) – An API for dapps to communicate with account management Snaps. -- [**Keyring Interface API**](interface-api.md) - EVM methods that account management Snaps can - implement to support dapp requests from custom accounts. +- [**Account Management API**](account-management/index.md) – An API for dapps to communicate with + account management Snaps. + Dapps can manage accounts and signature requests using this API. +- [**Chain Methods API**](chain-methods.md) - An API that contains chain-specific EVM methods that + account management Snaps can choose to implement to support dapp requests from custom accounts. :::tip See also - [Create an account management Snap](../../features/custom-evm-accounts/create-account-snap.md) diff --git a/snaps/reference/snaps-api.md b/snaps/reference/snaps-api.md index 5932025be7c..5edf36e357f 100644 --- a/snaps/reference/snaps-api.md +++ b/snaps/reference/snaps-api.md @@ -569,7 +569,7 @@ This can be done using [`snap_manageState`](#snap_managestate). #### Parameters -`account` - [An account object.](keyring-api/client-api/objects.md#keyringaccount) +`account` - [An account object.](keyring-api/account-management/objects.md#keyringaccount) #### Returns @@ -633,7 +633,7 @@ This can be done using [`snap_manageState`](#snap_managestate). #### Parameters -`account` - [An account object.](keyring-api/client-api/objects.md#keyringaccount) +`account` - [An account object.](keyring-api/account-management/objects.md#keyringaccount) #### Returns @@ -709,7 +709,7 @@ state of accounts and the state known to MetaMask. #### Returns -An array of [account objects](keyring-api/client-api/objects.md#keyringaccount). +An array of [account objects](keyring-api/account-management/objects.md#keyringaccount). #### Example @@ -739,7 +739,7 @@ class MyKeyring implements Keyring { Finalizes a signing request. This is usually called as part of the -[`keyring_approveRequest`](keyring-api/client-api/index.md#keyring_approverequest) method. +[`keyring_approveRequest`](keyring-api/account-management/index.md#keyring_approverequest) method. #### Parameters From e5285e796b5f56db97e183bc7e44575c79455b59 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Fri, 1 Mar 2024 13:55:53 -0800 Subject: [PATCH 7/7] clarify scope and filterAccountChains --- snaps/reference/keyring-api/account-management/index.md | 6 +++--- snaps/reference/keyring-api/account-management/objects.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/snaps/reference/keyring-api/account-management/index.md b/snaps/reference/keyring-api/account-management/index.md index f80d5e62b41..ac3f4399935 100644 --- a/snaps/reference/keyring-api/account-management/index.md +++ b/snaps/reference/keyring-api/account-management/index.md @@ -154,7 +154,7 @@ An object containing: ### `keyring_filterAccountChains` -Filters for chains that an account can be used on. +Filters for blockchain networks that an account can be used on. #### Parameters @@ -162,14 +162,14 @@ An object containing: - `id`: `string` - Account ID (UUIDv4). - `chains`: `string[]` - List of [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) - chain IDs to filter. + chain IDs of blockchain networks to filter. #### Returns An object containing: - `chains`: `string[]` - List of [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) - chain IDs that the account can be used on. + chain IDs of blockchain networks that the account can be used on. #### Example diff --git a/snaps/reference/keyring-api/account-management/objects.md b/snaps/reference/keyring-api/account-management/objects.md index 3a98ec8cc48..866ae1e66f9 100644 --- a/snaps/reference/keyring-api/account-management/objects.md +++ b/snaps/reference/keyring-api/account-management/objects.md @@ -52,8 +52,8 @@ A request object contains: - `request` - Inner request sent by the client application, containing: - `method`: `string` - The request method. - `params`: `Json[]` - Optional method parameters. -- `scope`: `string` - Request's scope ([CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) - chain ID). +- `scope`: `string` - [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain ID of the blockchain network for the request. ### Example