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/features/custom-evm-accounts/create-account-snap.md b/snaps/features/custom-evm-accounts/create-account-snap.md index 423682dc090..cd6ceeb172d 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) @@ -29,7 +29,8 @@ Create an account management Snap to connect to custom EVM accounts. ### 1. Install the Keyring API -Install `@metamask/keyring-api` in your project directory using Yarn or npm: +Install the [`@metamask/keyring-api`](https://github.com/MetaMask/keyring-api) module in your +project directory using Yarn or npm: ```bash yarn add @metamask/keyring-api @@ -63,9 +64,10 @@ Specify the following [permissions](../../how-to/request-permissions.md) in your Add a list of dapp URLs allowed to call Keyring API methods on your Snap using the [`endowment:keyring`](../../reference/permissions.md#endowmentkeyring) permission. -### 3. Implement the Keyring API +### 3. Implement the Account Management API -Implement the [required Keyring API methods](security.md#limit-the-methods-exposed-to-dapps) in your Snap: +Implement the [Account Management API](../../reference/keyring-api/account-management/index.md) in your Snap. +Make sure to [limit the methods exposed to dapps](security.md#limit-the-methods-exposed-to-dapps). ```typescript class MySnapKeyring implements Keyring { @@ -75,11 +77,11 @@ class MySnapKeyring implements Keyring { ### 4. Handle requests submitted by MetaMask -MetaMask submits Ethereum sign requests from dapps using the -[`submitRequest`](../../reference/keyring-api/type-aliases/Keyring.md#submitrequest) method of the -Keyring API. -See the methods for [externally owned accounts](index.md#eoa-methods) and -[ERC-4337 accounts](index.md#account-abstraction-erc-4337). +MetaMask submits EVM requests from dapps using the +[`keyring_submitRequest`](../../reference/keyring-api/account-management/index.md#keyring_submitrequest) +method of the Keyring API. +See the EVM methods for [externally owned accounts](../../reference/keyring-api/chain-methods.md#eoa-methods) +and [ERC-4337 accounts](../../reference/keyring-api/chain-methods.md#erc-4337-methods). The following is an example of a `personal_sign` request: @@ -130,88 +132,25 @@ The redirect message and URL is displayed to the user to help them continue the ### 5. Notify MetaMask about events -Notify MetaMask when the following events take place, using the `emitSnapKeyringEvent()` helper function: - -- An account is created: - - ```typescript - try { - emitSnapKeyringEvent(snap, KeyringEvent.AccountCreated, { account }); - // Update your Snap's state... - } catch (error) { - // Handle the error... - } - ``` - - MetaMask returns an error if the account already exists or the account object is invalid. - -- An account is updated: - - ```typescript - try { - emitSnapKeyringEvent(snap, KeyringEvent.AccountUpdated, { account }); - // Update your Snap's state... - } catch (error) { - // Handle the error... - } - ``` - - MetaMask returns an error if the account does not exist, the account object is invalid, or the - account address changes. - -- An account is deleted: - - ```typescript - try { - emitSnapKeyringEvent(snap, KeyringEvent.AccountDeleted, { - id: account.id, - }); - // Update your Snap's state... - } catch (error) { - // Handle the error... - } - ``` - - The delete event is idempotent, so it is safe to emit even if the account does not exist. - -- A request is approved: - - ```typescript - try { - emitSnapKeyringEvent(snap, KeyringEvent.RequestApproved, { - id: request.id, - result, - }); - // Update your Snap's state... - } catch (error) { - // Handle the error... - } - ``` - - MetaMask returns an error if the request does not exist. - This event only applies to Snaps that implement the - [asynchronous transaction flow](index.md#asynchronous-transaction-flow). - -- A request is rejected: - - ```typescript - try { - emitSnapKeyringEvent(snap, KeyringEvent.RequestRejected, { - id: request.id, - }); - // Update your Snap's state... - } catch (error) { - // Handle the error... - } - ``` - - MetaMask returns an error if the request does not exist. - This event only applies to Snaps that implement the - [asynchronous transaction flow](index.md#asynchronous-transaction-flow). - -### 6. Expose the Keyring API - -Create an `onKeyringRequest` entry point handler method to expose the Keyring API methods +Notify MetaMask when [Account Management API events](../../reference/keyring-api/account-management/events.md) +take place, using the `emitSnapKeyringEvent()` helper function. + +For example, when an account is created: + +```typescript +try { + emitSnapKeyringEvent(snap, KeyringEvent.AccountCreated, { account }); + // Update your Snap's state... +} catch (error) { + // Handle the error... +} +``` + +MetaMask returns an error if the account already exists or the account object is invalid. + +### 6. Expose the Account Management API + +Create an `onKeyringRequest` entry point handler method to expose the Account Management API methods to MetaMask and your dapp: ```typescript diff --git a/snaps/features/custom-evm-accounts/create-companion-dapp.md b/snaps/features/custom-evm-accounts/create-companion-dapp.md index a4075c78452..36d9b339af8 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) ::: @@ -27,7 +26,8 @@ An [account management Snap](create-account-snap.md) set up. ### 1. Install the Keyring API -Install `@metamask/keyring-api` in your project directory using Yarn or npm: +Install the [`@metamask/keyring-api`](https://github.com/MetaMask/keyring-api) module in your +project directory using Yarn or npm: ```bash yarn add @metamask/keyring-api @@ -39,9 +39,9 @@ or npm install @metamask/keyring-api ``` -### 2. Create the KeyringSnapRpcClient +### 2. Create a KeyringSnapRpcClient -Create the [`KeyringSnapRpcClient`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md): +Create a `KeyringSnapRpcClient`: ```ts import { KeyringSnapRpcClient } from "@metamask/keyring-api"; @@ -50,12 +50,12 @@ import { defaultSnapOrigin as snapId } from '../config'; let client = new KeyringSnapRpcClient(snapId, window.ethereum); ``` -### 3. Call Keyring API methods +### 3. Call Account Management API methods -You can now use the [`KeyringSnapRpcClient`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md) -to invoke Keyring API methods on your Snap. +You can now use the `KeyringSnapRpcClient` to invoke +[Account Management API](../../reference/keyring-api/account-management/index.md) methods on your Snap. -For example, to call [`keyring_listAccounts`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md#listaccounts): +For example, to call [`keyring_listAccounts`](../../reference/keyring-api/account-management/index.md#keyringlist_accounts): ```typescript const accounts = await client.listAccounts(); diff --git a/snaps/features/custom-evm-accounts/index.md b/snaps/features/custom-evm-accounts/index.md index ee908d5f014..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/classes/KeyringSnapRpcClient.md#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 @@ -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/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. ### 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/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/classes/KeyringSnapRpcClient.md#getrequest). +[`keyring_getRequest`](../../reference/keyring-api/account-management/index.md#keyring_getrequest). It resolves the request using -[`keyring_approveRequest`](../../reference/keyring-api/classes/KeyringSnapRpcClient.md#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`](/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) +- [`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`](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/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,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/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 f1c603bd18f..3701f521ac7 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/account-management/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 +[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/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. @@ -176,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/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-index/index.md b/snaps/reference/keyring-api-index/index.md deleted file mode 100644 index 48f04d81b06..00000000000 --- a/snaps/reference/keyring-api-index/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -description: See the Keyring API reference. -tags: - - Keyring API ---- - -# Keyring API - -This section describes the Keyring API methods. -See the left sidebar for the API categories and methods. - -:::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) -::: diff --git a/snaps/reference/keyring-api/account-management/events.md b/snaps/reference/keyring-api/account-management/events.md new file mode 100644 index 00000000000..f19774c17af --- /dev/null +++ b/snaps/reference/keyring-api/account-management/events.md @@ -0,0 +1,105 @@ +--- +sidebar_position: 2 +toc_max_heading_level: 2 +sidebar_label: Events +--- + +# Account Management API events + +[Account management Snaps](../../../features/custom-evm-accounts/index.md) can notify MetaMask of the +following [Account Management 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/account-management/index.md b/snaps/reference/keyring-api/account-management/index.md new file mode 100644 index 00000000000..ac3f4399935 --- /dev/null +++ b/snaps/reference/keyring-api/account-management/index.md @@ -0,0 +1,621 @@ +--- +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Account Management API + +Dapps can communicate with [account management Snaps](../../../features/custom-evm-accounts/index.md) +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). + +## Account methods + +The following methods are exposed by the Snap for account management. + +### `keyring_createAccount` + +Creates a new account. + +#### Parameters + +An object containing: + +- `options`: `Record` - Snap-defined account options. + +#### Returns + +[An account object.](objects.md#keyringaccount) + +#### 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 + +An object containing: + +- `id`: `string` - ID of the account to be deleted (UUIDv4). + +#### 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 + +An object containing: + +- `id`: `string` - ID of the account to be exported (UUIDv4). + +#### Returns + +An object containing: + +- `privateKey`: `string` - The account's private key. + +#### Example + + + + +```json +{ + "method": "keyring_exportAccount", + "params": { + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a" + } +} +``` + + + + +```json +{ + "privateKey": "66a41d66be6483f1fdfd01fdb66173d449594bbd286149b019504dd72b58bc51" +} +``` + + + + +### `keyring_filterAccountChains` + +Filters for blockchain networks that an account can be used on. + +#### Parameters + +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 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 of blockchain networks that the account can be used on. + +#### Example + + + + +```json +{ + "method": "keyring_filterAccountChains", + "params": { + "id": "091bbc2e-6625-44d0-ac5c-658670ca649a", + "chains": [ + "eip155:W", + "eip155:X", + "eip155:Y", + "eip155:Z" + ] + } +} +``` + + + + +```json +{ + "chains": [ + "eip155:X", + "eip155:Y" + ] +} +``` + + + + +### `keyring_getAccount` + +Gets an account from an ID. + +#### Parameters + +An object containing: + +- `id`: `string` - Account ID (UUIDv4). + +#### Returns + +[An account object.](objects.md#keyringaccount) + +#### 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](objects.md#keyringaccount) handled by the Snap. + +#### 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.](objects.md#keyringaccount) + +#### 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 + +An object containing: + +- `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 + +An object containing: + +- `id`: `string` - Request ID. + +#### Returns + +[A request object.](objects.md#keyringrequest) + +#### 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](objects.md#keyringrequest). + +#### 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 + +An object containing: + +- `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.](objects.md#keyringrequest) + +#### 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/account-management/objects.md b/snaps/reference/keyring-api/account-management/objects.md new file mode 100644 index 00000000000..866ae1e66f9 --- /dev/null +++ b/snaps/reference/keyring-api/account-management/objects.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 1 +toc_max_heading_level: 2 +sidebar_label: Objects +--- + +# Account Management API objects + +[Account management Snaps](../../../features/custom-evm-accounts/index.md) use the following objects +with the [Account Management 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](../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 + [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` - [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) + chain ID of the blockchain network for the request. + +### 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/chain-methods.md b/snaps/reference/keyring-api/chain-methods.md new file mode 100644 index 00000000000..fd6183a622d --- /dev/null +++ b/snaps/reference/keyring-api/chain-methods.md @@ -0,0 +1,475 @@ +--- +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Chain Methods API + +[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 + +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` + +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" +``` + + + diff --git a/snaps/reference/keyring-api/index.md b/snaps/reference/keyring-api/index.md new file mode 100644 index 00000000000..93473cb8acc --- /dev/null +++ b/snaps/reference/keyring-api/index.md @@ -0,0 +1,25 @@ +--- +description: See the Keyring API reference. +sidebar_position: 6 +tags: + - Keyring API +--- + +# Keyring API + +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: + +- [**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) + - [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) +- [Custom EVM accounts](../../features/custom-evm-accounts/index.md) +::: 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..5edf36e357f 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'; @@ -568,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/account-management/objects.md#keyringaccount) #### Returns @@ -632,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/account-management/objects.md#keyringaccount) #### Returns @@ -708,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/account-management/objects.md#keyringaccount). #### Example @@ -737,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/account-management/index.md#keyring_approverequest) method. #### Parameters 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"