diff --git a/docs/guide/snaps-development-guide.md b/docs/guide/snaps-development-guide.md index 60b98773d48..bedbc226e27 100644 --- a/docs/guide/snaps-development-guide.md +++ b/docs/guide/snaps-development-guide.md @@ -1,11 +1,7 @@ # Development Guide -::: tip Only Available in MetaMask Flask -[Snaps](./snaps.html) is only available in [MetaMask Flask](https://metamask.io/flask). -::: - -::: tip Feature Requests -Do you have feature requests? Other ideas? We'd love to hear about them! [Click here](https://community.metamask.io/c/metamask-flask) to join the discussion. +::: tip Developer Preview Software +[Snaps](./snaps.html) is pre-release software. To try Snaps, install [MetaMask Flask](https://metamask.io/flask). ::: Developing a snap is much like developing any JavaScript project, but there are some things that may be new even to a seasoned developer. @@ -27,7 +23,8 @@ Executing `mm-snap --help` will provide detailed usage instructions. This guide assumes that you've completed the ["Getting Started" tutorial](./snaps.html#getting-started). ::: -So, you have installed [MetaMask Flask](https://metamask.io/flask), cloned the [@metamask/template-snap](https://github.com/MetaMask/template-snap) repository, and have served the "Hello, World!" snap locally. It's time to develop your own snap. +So, you have installed [MetaMask Flask](https://metamask.io/flask), cloned the [@metamask/template-snap](https://github.com/MetaMask/template-snap) repository, and have served the "Hello, World!" snap locally. +It's time to develop your own snap. A snap is a JavaScript program that, conceptually, runs in a sandboxed environment inside MetaMask. At the moment, snaps must be distributed as npm packages on the official npm registry (`https://registry.npmjs.org/`), but different distribution mechanisms will be supported in the future. @@ -160,7 +157,7 @@ Snaps exist in order to modify the functionality of MetaMask at runtime while on As we have seen in the [introduction to snaps](./snaps.html) and this guide, snaps can: 1. Extend the dapp-facing MetaMask JSON-RPC API in arbitrary ways. -2. Integrate with and extend the functionality of MetaMask using the [snaps RPC methods and permissions](./snaps-rpc-api.html). +1. Integrate with and extend the functionality of MetaMask using the [snaps RPC methods and permissions](./snaps-rpc-api.html). In this section, we'll go into detail about how to actually develop a snap and overcome common issues encountered during development. @@ -175,7 +172,7 @@ This does not mean that you can't create long-running snaps, but it does mean th A snap is considered "unresponsive" if: 1. It has not received a JSON-RPC request for 30 seconds. -2. It takes more than 60 seconds to process a JSON-RPC request. +1. It takes more than 60 seconds to process a JSON-RPC request. Stopped snaps are started whenever they receive a JSON-RPC request, unless they have been disabled. If a snap is disabled, the user must re-enable it before it can start again. @@ -238,8 +235,8 @@ The execution environment is instrumented in this way to: 1. Prevent snaps from influencing any other running code, including MetaMask itself. - In plain terms, to prevent all snaps from polluting the global environment and malicious snaps from stealing the user's stuff. -2. Prevent snaps from accessing sensitive JavaScript APIs (like `fetch`) without permission. -3. Ensure that the execution environment is "fully virtualizable", i.e. platform-independent. +1. Prevent snaps from accessing sensitive JavaScript APIs (like `fetch`) without permission. +1. Ensure that the execution environment is "fully virtualizable", i.e. platform-independent. This allows us to safely execute snaps anywhere, without the snap needing to worry about where and how it is executed. @@ -307,6 +304,17 @@ Follow these instructions to inspect the background process and view its console - Click on "Details" - Under "Inspect Views", click `background.html` +### Publishing Your Snap + +Snaps are npm packages, so publishing a Snap is as simple as publishing an npm package. +Refer to the [npm cli documentation](https://docs.npmjs.com/cli/v8/commands/npm-publish) for details on publishing to the public registry. +Take note of the following details specific to Snaps: + +- The version in `package.json` and `snap.manifest.json` must match +- The image specified in `iconPath` in the manifest file will be used as the icon displayed when installing and displaying confirmations from the Snap + +After publishing the Snap, any dapp can connect to the Snap by using the snapId `npm:[packageName]`. + ### Distributing Your Snap Since snaps are currently intended for a developer audience, MetaMask does not currently facilitate distributing snaps to a wide audience. @@ -317,12 +325,20 @@ In the future, MetaMask will create some way for users to more easily discover s ## Resources and Tools -You can review the growing number of [example snaps](https://github.com/MetaMask/snaps-skunkworks/tree/main/packages/examples) maintained by MetaMask, and you may wish to check out the first functional key management snap ever made, [the Filecoin Snap, or `filsnap`](https://github.com/Chainsafe/filsnap). +You can review the growing number of [example snaps](https://github.com/MetaMask/snaps-skunkworks/tree/main/packages/examples) maintained by MetaMask, as well as the following reference Snaps. Each one is fully-functional and open-source: + +- [Filsnap for Filecoin support](https://github.com/Chainsafe/filsnap/) +- [BitcoinSnap for Bitcoin support](https://github.com/KeystoneHQ/btcsnap) +- [Password Manager Snap](https://github.com/ritave/snap-passwordManager) + +You can also follow these tutorials which will walk you through the steps to develop and test a Snap: + +- A 5-minute tutorial that uses the `network-access` permission: [Gas Fee Snap Tutorial](https://github.com/Montoya/gas-fee-snap#readme) +- A 30-minute tutorial that uses the `manageState` permission: [Address Book Snap Tutorial](https://github.com/Montoya/address-book-snap-tutorial#readme) -MetaMask also maintains a growing list of tools to help developers debug, build and maintain Snaps: +MetaMask also maintains tools to help developers debug, build and maintain Snaps: - [Snaps Inspector](https://inspector.open-rpc.org/?request[jsonrpc]=2.0&request[method]=confirm&request[params][0]=hello&request[params][1]=more&request[params][2]=lorem%20ipsum&request[id]=0&url=npm:@metamask/test-snap-confirm&customTransport[type]=plugin&customTransport[name]=Snaps&customTransport[transport][type]=postmessageiframe&customTransport[transport][name]=PostMessageIframe&customTransport[uri]=https://xops.github.io/inspector-snaps-transport/) - An API tool to make JSON-RPC requests directly to Snaps. - [Snaps OpenRPC Generator](https://github.com/xops/snaps-openrpc-generator) - A project skeleton generator that creates a Snap and documentation from your [OpenRPC document](https://spec.open-rpc.org/#openrpc-document) -- [5-Minute Snap Tutorial](https://github.com/Montoya/gas-fee-snap#readme) -Finally, if you need help, you can ask for help in the [MetaMask/snaps-skunkworks](https://github.com/MetaMask/snaps-skunkworks) repository. +Finally, if you need help, you can ask for help on our [discussion board](https://github.com/MetaMask/snaps-skunkworks/discussions), and if you encounter any issues, please open an issue in our [issue tracker](https://github.com/MetaMask/snaps-skunkworks/issues).