From 872198a7d1a38f267515474f50e341384e10d860 Mon Sep 17 00:00:00 2001 From: Christian Montoya Date: Thu, 14 Mar 2024 21:29:26 -0400 Subject: [PATCH 01/11] WIP --- snaps/how-to/connect-to-a-snap.md | 2 +- snaps/how-to/get-allowlisted.md | 59 +++++++++++++++++++++++++++++++ snaps/how-to/publish-a-snap.md | 9 ++--- 3 files changed, 63 insertions(+), 7 deletions(-) create mode 100644 snaps/how-to/get-allowlisted.md diff --git a/snaps/how-to/connect-to-a-snap.md b/snaps/how-to/connect-to-a-snap.md index d6ca78bca6c..0299c66cae8 100644 --- a/snaps/how-to/connect-to-a-snap.md +++ b/snaps/how-to/connect-to-a-snap.md @@ -1,6 +1,6 @@ --- description: Connect your dapp to existing, third-party Snaps. -sidebar_position: 7 +sidebar_position: 8 --- # Connect to a Snap diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md new file mode 100644 index 00000000000..20de69ffcfe --- /dev/null +++ b/snaps/how-to/get-allowlisted.md @@ -0,0 +1,59 @@ +--- +description: Submit your Snap for allowlisting on MetaMask extension. +sidebar_position: 7 +--- + +# Get allowlisted + +You have built your Snap, tested it, published it to npm, and now you are ready to make it available to MetaMask users. +In the MetaMask Snaps Open Beta, an allowlist restricts which Snaps can be installed by users. + +:::note +As part of the launch of MetaMask Snaps, individual Snaps must be put on an allowlist before they can be installed by users. This means that at this time, only selected, audited Snaps can be installed. In the future, this system will be opened up. By including a Snap on the allowlist, Consensys is not endorsing, recommending, or guaranteeing the safety of this Snap for your use or use for any reason. Always do your own research before installing any Snap. +::: + +## Pre-requisites + +To be added to the allowlist, a Snap must: + +- Make the source code publicly available. This does not mean that the Snap source code has to be published with an open-source license, but users should be able to read the source code of the Snap package. +- Be published to npmjs.com. +- Not impair our compliance with laws or regulations. + +Furthermore, any Snap that uses any of the following permissions pertaining to key management must also provide evidence of a third-party audit from an approved auditor covering the Snap source code itself that is to run within the Snaps system along with any modules used for key management, with evidence of the commit hash that was audited and the commit that has any fixes documented in the audit report: + +- `snap_getBip32Entropy` +- `snap_getBip32PublicKey` +- `snap_getBip44Entropy` +- `snap_getEntropy` +- `snap_manageAccounts` + +A list of approved third-party auditors and details about submitting your audit report are available on the [MetaMask Snaps Builder Team Space](https://consensys.notion.site/Audit-process-1acbc67819dc4631b7a3d6c664e387a3). + +## Submit your Snap + +When you are ready to submit your Snap, you should navigate to the [MetaMask Snaps Registry](https://github.com/MetaMask/snaps-registry) repository and open a new issue with "Add Snap Request." You will need to provide the following information: + +- Title: the name of your Snap. This must match the `displayName` from the Snap manifest. +- Snap ID: the npm ID of your published Snap. Example: `npm:@metamask/simple-snap-keyring` +- Description: a detailed explanation of what your Snap does and how to use it. This can be multiple lines and can contain URLs. +- Summary: a brief explanation of what the Snap does, no more than two sentences. +- Category +- Website: if your Snap has an official companion dapp that is required to interact with your Snap, provide the URL here. +- Repository: the URL where your source code is hosted. +- Open Source: check this box if your Snap is published with an open source license. +- Author: the name of the company, team, or individual that developed the Snap. +- Author Website +- Support URL: an email, Discord channel, Telegram channel, or website where users can get support. +- FAQ: a webpage with frequently asked questions. +- Knowledge Base + + + +## Distribute your Snap + +You should deploy a companion dapp where users can learn about your Snap and install it, or +integrate with your existing dapp. + +If your Snap is designed to communicate with dapps, you can encourage other dapp developers to +[connect to your Snap](connect-to-a-snap.md). diff --git a/snaps/how-to/publish-a-snap.md b/snaps/how-to/publish-a-snap.md index beaecd6bd67..fda7ae40d2c 100644 --- a/snaps/how-to/publish-a-snap.md +++ b/snaps/how-to/publish-a-snap.md @@ -32,10 +32,7 @@ Snap location to **npm** and the ID of your Snap. Also, make sure to update the manifest file, icon file, and README to differentiate your Snap from the template. ::: -## Distribute your Snap +## Make it available to users -You should deploy a companion dapp where users can learn about your Snap and install it, or -integrate with your existing dapp. - -If your Snap is designed to communicate with dapps, you can encourage other dapp developers to -[connect to your Snap](connect-to-a-snap.md). +Now that your Snap is published, you probably want to make it available to MetaMask users. +Learn how to [get allowlisted](get-allowlisted.md) so anyone can install your Snap in the MetaMask extension. From f8524329c201787402d2cac1d305060da0f44529 Mon Sep 17 00:00:00 2001 From: Christian Montoya Date: Fri, 15 Mar 2024 00:07:26 -0400 Subject: [PATCH 02/11] Update get-allowlisted.md --- snaps/how-to/get-allowlisted.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md index 20de69ffcfe..48fcb637265 100644 --- a/snaps/how-to/get-allowlisted.md +++ b/snaps/how-to/get-allowlisted.md @@ -28,11 +28,15 @@ Furthermore, any Snap that uses any of the following permissions pertaining to k - `snap_getEntropy` - `snap_manageAccounts` -A list of approved third-party auditors and details about submitting your audit report are available on the [MetaMask Snaps Builder Team Space](https://consensys.notion.site/Audit-process-1acbc67819dc4631b7a3d6c664e387a3). +A list of approved third-party auditors and details about the audit process are available on the +[MetaMask Snaps Builder Team Space](https://consensys.notion.site/Audit-process-1acbc67819dc4631b7a3d6c664e387a3). ## Submit your Snap -When you are ready to submit your Snap, you should navigate to the [MetaMask Snaps Registry](https://github.com/MetaMask/snaps-registry) repository and open a new issue with "Add Snap Request." You will need to provide the following information: +When you are ready to submit your Snap, you should navigate to the +[MetaMask Snaps Registry](https://github.com/MetaMask/snaps-registry) +repository and open a new issue with "Add Snap Request." +You will need to provide the following information: - Title: the name of your Snap. This must match the `displayName` from the Snap manifest. - Snap ID: the npm ID of your published Snap. Example: `npm:@metamask/simple-snap-keyring` @@ -48,7 +52,19 @@ When you are ready to submit your Snap, you should navigate to the [MetaMask Sna - FAQ: a webpage with frequently asked questions. - Knowledge Base +If your Snap has an audit report, you should link to the audit report from the README of your repository or include the audit report file in your repository. +You can also upload the audit report in a comment on the issue after creating the issue. +## Allowlist review + +Your Snap will be reviewed by the MetaMask Snaps team to ensure it is functional and well-designed. +If the Snap requires an audit, the audit report will be reviewed to ensure that all vulnerabilities with "medium" or higher risk have been addressed. +All Snaps will require at least 3 approvals to be allowlisted. + +## Directory listing + +Once your Snap is on the allowlist, it will appear in the [MetaMask Snaps Directory](https://snaps.metamask.io). +You can direct users to the directory to find and install your Snap. ## Distribute your Snap From c3994372002c6c22586bd1b8b175cafaff8cc649 Mon Sep 17 00:00:00 2001 From: Montoya Date: Wed, 17 Apr 2024 23:16:06 -0400 Subject: [PATCH 03/11] Update get-allowlisted.md This conforms to the latest approach which still relies on a webform. --- snaps/how-to/get-allowlisted.md | 58 ++++++++++++++++++++++++++------- 1 file changed, 47 insertions(+), 11 deletions(-) diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md index 48fcb637265..bdec68b28ac 100644 --- a/snaps/how-to/get-allowlisted.md +++ b/snaps/how-to/get-allowlisted.md @@ -9,7 +9,7 @@ You have built your Snap, tested it, published it to npm, and now you are ready In the MetaMask Snaps Open Beta, an allowlist restricts which Snaps can be installed by users. :::note -As part of the launch of MetaMask Snaps, individual Snaps must be put on an allowlist before they can be installed by users. This means that at this time, only selected, audited Snaps can be installed. In the future, this system will be opened up. By including a Snap on the allowlist, Consensys is not endorsing, recommending, or guaranteeing the safety of this Snap for your use or use for any reason. Always do your own research before installing any Snap. +As part of the launch of MetaMask Snaps, individual Snaps must be put on an allowlist before they can be installed by users. This means that at this time, only selected, reviewed Snaps can be installed. In the future, this system will be opened up. By including a Snap on the allowlist, Consensys is not endorsing, recommending, or guaranteeing the safety of this Snap for your use or use for any reason. Always do your own research before installing any Snap. ::: ## Pre-requisites @@ -20,7 +20,7 @@ To be added to the allowlist, a Snap must: - Be published to npmjs.com. - Not impair our compliance with laws or regulations. -Furthermore, any Snap that uses any of the following permissions pertaining to key management must also provide evidence of a third-party audit from an approved auditor covering the Snap source code itself that is to run within the Snaps system along with any modules used for key management, with evidence of the commit hash that was audited and the commit that has any fixes documented in the audit report: +Furthermore, any Snap that uses any of the following permissions pertaining to key management must also provide evidence of a third-party audit from an approved auditor, covering the Snap source code itself that is to run within the Snaps system along with any modules used for key management, with evidence of the commit hash that was audited and the commit that has any fixes documented in the audit report: - `snap_getBip32Entropy` - `snap_getBip32PublicKey` @@ -28,17 +28,16 @@ Furthermore, any Snap that uses any of the following permissions pertaining to k - `snap_getEntropy` - `snap_manageAccounts` -A list of approved third-party auditors and details about the audit process are available on the -[MetaMask Snaps Builder Team Space](https://consensys.notion.site/Audit-process-1acbc67819dc4631b7a3d6c664e387a3). +A list of approved third-party auditors and details about the audit process are available on the MetaMask Snaps Builder Engagement Program: +[Approved Auditors](https://consensys.notion.site/Audit-process-1acbc67819dc4631b7a3d6c664e387a3). ## Submit your Snap -When you are ready to submit your Snap, you should navigate to the -[MetaMask Snaps Registry](https://github.com/MetaMask/snaps-registry) -repository and open a new issue with "Add Snap Request." +When you are ready to submit your Snap, you should fill out the +[MetaMask Snaps Directory Information Form](https://docs.google.com/forms/d/e/1FAIpQLSeDAnk0Di_k8Qgrsj9_ofnf-1d_NfbG3fmSOHD1m8dKun1pXw/viewform). You will need to provide the following information: -- Title: the name of your Snap. This must match the `displayName` from the Snap manifest. +- Title: the name of your Snap. This must match the `proposedName` from the Snap manifest. - Snap ID: the npm ID of your published Snap. Example: `npm:@metamask/simple-snap-keyring` - Description: a detailed explanation of what your Snap does and how to use it. This can be multiple lines and can contain URLs. - Summary: a brief explanation of what the Snap does, no more than two sentences. @@ -52,14 +51,43 @@ You will need to provide the following information: - FAQ: a webpage with frequently asked questions. - Knowledge Base -If your Snap has an audit report, you should link to the audit report from the README of your repository or include the audit report file in your repository. -You can also upload the audit report in a comment on the issue after creating the issue. +- Email + - So we can get in touch with you if we have any questions. +- Snap name + - The name of your Snap. This **must** match the `proposedName` field from the Snap manifest. + - You cannot use these words in the name: MetaMask, Snap, Meta, Mask. +- Snap builder name and URL + - This should match the company, project, or personal site for your brand, where users can learn more about you. +- Snap website URL + - This is a website where users can interact with your Snap. If your Snap does not require a website to be used, this can be left blank. + - If your Snap works with multiple websites, you can include the URLs of additional websites in the _long description_, but this URL should be specifically for an "official" website designed to interact with your Snap. +- Snap short description + - Brief description of the snap, 1 or 2 sentences long. + - Try not to say "is a MetaMask Snap" -- users already know this! +- Snap long description + - Description of the snap features and how to use them. You can use line breaks, lists, and even URLs here. You cannot use HTML. + - If applicable, you should also describe quick steps to onboard and use the Snap. For example: "After installing the Snap, visit the companion dapp at https://voyager-snap.linea.build to connect an account and track your Linea Voyage progress." +- Link to the public GitHub repo and npm package + - If your Snap is hosted on a different site, like GitLab, you can link to that instead. + - Please ensure that you have [correctly published the Snap package itself](../how-to/publish-a-snap.md). +- Snap version number to be allowlisted + - Make sure that the version number in `package.json` and `snap.manifest.json` match, and that the Snap has been built with the correct `shasum`. +- Snap auditor and audit report + - If your Snap uses one or more of the permissions listed above, please provide a PDF or link to where the audit report has been published. Otherwise, leave this field blank. + - Please note: the audit report will be made public. You may ask your auditor to publish the report on their website and provide the link to us. +- Customer support details + - To ensure a smooth user experience, we require customer support details for your Snap. This allows us to escalate any issues that the user is facing with your Snap. You can find more details [here](https://consensys.notion.site/Providing-User-Support-Information-cff79a7d896e4da6a2f8a17ce074e585). The Escalation Contact will be kept confidential between our teams, the rest of the information will be public. You must provide an Escalation Contact and at least one of the remaining items. +- Images + - Here's your opportunity to provide compelling previews of your Snap! These can be screenshots or promotional images to help users get an idea of what your Snap can do. + - Please provide 3 images with the following dimensions: 960w x 540h. PNG or JPG are allowed. +- Demo video + - This will help our team review your Snap. It may also be used by our marketing team. ## Allowlist review Your Snap will be reviewed by the MetaMask Snaps team to ensure it is functional and well-designed. If the Snap requires an audit, the audit report will be reviewed to ensure that all vulnerabilities with "medium" or higher risk have been addressed. -All Snaps will require at least 3 approvals to be allowlisted. +All Snaps will require at least 2 approvals to be allowlisted. ## Directory listing @@ -73,3 +101,11 @@ integrate with your existing dapp. If your Snap is designed to communicate with dapps, you can encourage other dapp developers to [connect to your Snap](connect-to-a-snap.md). + +## Updating your Snap + +The allowlist uses strict versioning for all Snaps. When you have a new version of your Snap published to npm, you will need to submit it for allowlisting again. Users will not be able to install new versions until they are allowlisted. + +Please submit the [Directory Information Form](https://docs.google.com/forms/d/e/1FAIpQLSeDAnk0Di_k8Qgrsj9_ofnf-1d_NfbG3fmSOHD1m8dKun1pXw/viewform) again for any new version of your Snap. You can also update any information about your Snap with this form. For any fields that do not need to be changed, you can leave them blank or enter "n/a." When providing the version to be allowlisted, please also let let us know if previous versions of your Snap can remain allowlisted or should be replaced with this new version. + +If you need to update information about your Snap in the [Snaps Directory](https://snaps.metamask.io) without submitting a new version to the allowlist, [get in touch with our Builder Engagement Program](https://consensys.notion.site/Connect-with-us-7ffcbcc7981b4a4da7f1a1d39f6c127b). From a8169b1a13bbe4efa9114fcd2572fac9ce275e13 Mon Sep 17 00:00:00 2001 From: Montoya Date: Wed, 17 Apr 2024 23:28:04 -0400 Subject: [PATCH 04/11] Update get-allowlisted.md --- snaps/how-to/get-allowlisted.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md index bdec68b28ac..ad11d1acfc9 100644 --- a/snaps/how-to/get-allowlisted.md +++ b/snaps/how-to/get-allowlisted.md @@ -37,20 +37,6 @@ When you are ready to submit your Snap, you should fill out the [MetaMask Snaps Directory Information Form](https://docs.google.com/forms/d/e/1FAIpQLSeDAnk0Di_k8Qgrsj9_ofnf-1d_NfbG3fmSOHD1m8dKun1pXw/viewform). You will need to provide the following information: -- Title: the name of your Snap. This must match the `proposedName` from the Snap manifest. -- Snap ID: the npm ID of your published Snap. Example: `npm:@metamask/simple-snap-keyring` -- Description: a detailed explanation of what your Snap does and how to use it. This can be multiple lines and can contain URLs. -- Summary: a brief explanation of what the Snap does, no more than two sentences. -- Category -- Website: if your Snap has an official companion dapp that is required to interact with your Snap, provide the URL here. -- Repository: the URL where your source code is hosted. -- Open Source: check this box if your Snap is published with an open source license. -- Author: the name of the company, team, or individual that developed the Snap. -- Author Website -- Support URL: an email, Discord channel, Telegram channel, or website where users can get support. -- FAQ: a webpage with frequently asked questions. -- Knowledge Base - - Email - So we can get in touch with you if we have any questions. - Snap name @@ -66,7 +52,7 @@ You will need to provide the following information: - Try not to say "is a MetaMask Snap" -- users already know this! - Snap long description - Description of the snap features and how to use them. You can use line breaks, lists, and even URLs here. You cannot use HTML. - - If applicable, you should also describe quick steps to onboard and use the Snap. For example: "After installing the Snap, visit the companion dapp at https://voyager-snap.linea.build to connect an account and track your Linea Voyage progress." + - If applicable, you should also describe quick steps to onboard and use the Snap. For example: `After installing the Snap, visit the companion dapp at https://voyager-snap.linea.build to connect an account and track your Linea Voyage progress.` - Link to the public GitHub repo and npm package - If your Snap is hosted on a different site, like GitLab, you can link to that instead. - Please ensure that you have [correctly published the Snap package itself](../how-to/publish-a-snap.md). From dc7f9788c131a21314079522da00c33d7a309aee Mon Sep 17 00:00:00 2001 From: Montoya Date: Wed, 17 Apr 2024 23:45:22 -0400 Subject: [PATCH 05/11] Update URL for directory information form --- snaps/how-to/get-allowlisted.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md index ad11d1acfc9..4de52de2ee0 100644 --- a/snaps/how-to/get-allowlisted.md +++ b/snaps/how-to/get-allowlisted.md @@ -34,7 +34,7 @@ A list of approved third-party auditors and details about the audit process are ## Submit your Snap When you are ready to submit your Snap, you should fill out the -[MetaMask Snaps Directory Information Form](https://docs.google.com/forms/d/e/1FAIpQLSeDAnk0Di_k8Qgrsj9_ofnf-1d_NfbG3fmSOHD1m8dKun1pXw/viewform). +[MetaMask Snaps Directory Information Form](https://go.metamask.io/snaps-directory-request). You will need to provide the following information: - Email @@ -88,10 +88,16 @@ integrate with your existing dapp. If your Snap is designed to communicate with dapps, you can encourage other dapp developers to [connect to your Snap](connect-to-a-snap.md). +:::note +While testing your Snap, you may have designed your dapp to require MetaMask Flask. +Once your Snap is allowlisted, you should update your dapp to support any flavor of MetaMask, +and show the orange MetaMask logo instead of the purple Flask logo. +::: + ## Updating your Snap The allowlist uses strict versioning for all Snaps. When you have a new version of your Snap published to npm, you will need to submit it for allowlisting again. Users will not be able to install new versions until they are allowlisted. -Please submit the [Directory Information Form](https://docs.google.com/forms/d/e/1FAIpQLSeDAnk0Di_k8Qgrsj9_ofnf-1d_NfbG3fmSOHD1m8dKun1pXw/viewform) again for any new version of your Snap. You can also update any information about your Snap with this form. For any fields that do not need to be changed, you can leave them blank or enter "n/a." When providing the version to be allowlisted, please also let let us know if previous versions of your Snap can remain allowlisted or should be replaced with this new version. +Please submit the [Directory Information Form](https://go.metamask.io/snaps-directory-request) again for any new version of your Snap. You can also update any information about your Snap with this form. For any fields that do not need to be changed, you can leave them blank or enter "n/a." When providing the version to be allowlisted, please also let let us know if previous versions of your Snap can remain allowlisted or should be replaced with this new version. If you need to update information about your Snap in the [Snaps Directory](https://snaps.metamask.io) without submitting a new version to the allowlist, [get in touch with our Builder Engagement Program](https://consensys.notion.site/Connect-with-us-7ffcbcc7981b4a4da7f1a1d39f6c127b). From 15aa3867782c99cc1e7f02d2efc854dd2a95b54b Mon Sep 17 00:00:00 2001 From: Montoya Date: Wed, 17 Apr 2024 23:50:44 -0400 Subject: [PATCH 06/11] Update get-allowlisted.md --- snaps/how-to/get-allowlisted.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md index 4de52de2ee0..7e27842bb1c 100644 --- a/snaps/how-to/get-allowlisted.md +++ b/snaps/how-to/get-allowlisted.md @@ -55,7 +55,7 @@ You will need to provide the following information: - If applicable, you should also describe quick steps to onboard and use the Snap. For example: `After installing the Snap, visit the companion dapp at https://voyager-snap.linea.build to connect an account and track your Linea Voyage progress.` - Link to the public GitHub repo and npm package - If your Snap is hosted on a different site, like GitLab, you can link to that instead. - - Please ensure that you have [correctly published the Snap package itself](../how-to/publish-a-snap.md). + - Please ensure that you have [correctly published the Snap package](../how-to/publish-a-snap.md). - Snap version number to be allowlisted - Make sure that the version number in `package.json` and `snap.manifest.json` match, and that the Snap has been built with the correct `shasum`. - Snap auditor and audit report From 300dcfc994e0a678ea9a126e8f0480bb4ed0244c Mon Sep 17 00:00:00 2001 From: Montoya Date: Wed, 17 Apr 2024 23:52:19 -0400 Subject: [PATCH 07/11] Don't say please --- snaps/how-to/get-allowlisted.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md index 7e27842bb1c..f797d861054 100644 --- a/snaps/how-to/get-allowlisted.md +++ b/snaps/how-to/get-allowlisted.md @@ -55,17 +55,17 @@ You will need to provide the following information: - If applicable, you should also describe quick steps to onboard and use the Snap. For example: `After installing the Snap, visit the companion dapp at https://voyager-snap.linea.build to connect an account and track your Linea Voyage progress.` - Link to the public GitHub repo and npm package - If your Snap is hosted on a different site, like GitLab, you can link to that instead. - - Please ensure that you have [correctly published the Snap package](../how-to/publish-a-snap.md). + - Ensure that you have [correctly published the Snap package](../how-to/publish-a-snap.md). - Snap version number to be allowlisted - Make sure that the version number in `package.json` and `snap.manifest.json` match, and that the Snap has been built with the correct `shasum`. - Snap auditor and audit report - - If your Snap uses one or more of the permissions listed above, please provide a PDF or link to where the audit report has been published. Otherwise, leave this field blank. - - Please note: the audit report will be made public. You may ask your auditor to publish the report on their website and provide the link to us. + - If your Snap uses one or more of the permissions listed above, provide a PDF or URL to where the audit report has been published. Otherwise, leave this field blank. + - Note: the audit report will be made public. You may ask your auditor to publish the report on their website and provide the link to us. - Customer support details - To ensure a smooth user experience, we require customer support details for your Snap. This allows us to escalate any issues that the user is facing with your Snap. You can find more details [here](https://consensys.notion.site/Providing-User-Support-Information-cff79a7d896e4da6a2f8a17ce074e585). The Escalation Contact will be kept confidential between our teams, the rest of the information will be public. You must provide an Escalation Contact and at least one of the remaining items. - Images - Here's your opportunity to provide compelling previews of your Snap! These can be screenshots or promotional images to help users get an idea of what your Snap can do. - - Please provide 3 images with the following dimensions: 960w x 540h. PNG or JPG are allowed. + - Upload 3 images with the following dimensions: 960w x 540h. PNG or JPG are allowed. - Demo video - This will help our team review your Snap. It may also be used by our marketing team. @@ -98,6 +98,6 @@ and show the orange MetaMask logo instead of the purple Flask logo. The allowlist uses strict versioning for all Snaps. When you have a new version of your Snap published to npm, you will need to submit it for allowlisting again. Users will not be able to install new versions until they are allowlisted. -Please submit the [Directory Information Form](https://go.metamask.io/snaps-directory-request) again for any new version of your Snap. You can also update any information about your Snap with this form. For any fields that do not need to be changed, you can leave them blank or enter "n/a." When providing the version to be allowlisted, please also let let us know if previous versions of your Snap can remain allowlisted or should be replaced with this new version. +Submit the [Directory Information Form](https://go.metamask.io/snaps-directory-request) again for any new version of your Snap. You can also update any information about your Snap with this form. For any fields that do not need to be changed, you can leave them blank or enter "n/a." When providing the version to be allowlisted, you should also let us know if previous versions of your Snap can remain allowlisted or should be replaced with this new version. If you need to update information about your Snap in the [Snaps Directory](https://snaps.metamask.io) without submitting a new version to the allowlist, [get in touch with our Builder Engagement Program](https://consensys.notion.site/Connect-with-us-7ffcbcc7981b4a4da7f1a1d39f6c127b). From 9b12788667eecc67f88f5bb053b9dd0212b316da Mon Sep 17 00:00:00 2001 From: Montoya Date: Wed, 17 Apr 2024 23:59:22 -0400 Subject: [PATCH 08/11] Use correct form for updates --- snaps/how-to/get-allowlisted.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md index f797d861054..09b2b4aab2f 100644 --- a/snaps/how-to/get-allowlisted.md +++ b/snaps/how-to/get-allowlisted.md @@ -96,8 +96,6 @@ and show the orange MetaMask logo instead of the purple Flask logo. ## Updating your Snap -The allowlist uses strict versioning for all Snaps. When you have a new version of your Snap published to npm, you will need to submit it for allowlisting again. Users will not be able to install new versions until they are allowlisted. +The allowlist uses strict versioning for all Snaps. After publishing a new version of your Snap to npm, you will need to submit it for allowlisting. Users will not be able to install new versions until they are allowlisted. -Submit the [Directory Information Form](https://go.metamask.io/snaps-directory-request) again for any new version of your Snap. You can also update any information about your Snap with this form. For any fields that do not need to be changed, you can leave them blank or enter "n/a." When providing the version to be allowlisted, you should also let us know if previous versions of your Snap can remain allowlisted or should be replaced with this new version. - -If you need to update information about your Snap in the [Snaps Directory](https://snaps.metamask.io) without submitting a new version to the allowlist, [get in touch with our Builder Engagement Program](https://consensys.notion.site/Connect-with-us-7ffcbcc7981b4a4da7f1a1d39f6c127b). +Submit the [Directory Information Update Form](https://go.metamask.io/snaps-directory-update-request) for any new version of your Snap. You can also update any information about your Snap with this form. For any fields that do not need to be changed, you can leave them blank or enter "N/A." When providing the version to be allowlisted, you should also let us know if previous versions of your Snap should be removed from the allowlist (effectively replaced with this new version). From 4f89054925820f41650af0e9f9b045c28f98900c Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Thu, 18 Apr 2024 12:55:08 -0700 Subject: [PATCH 09/11] edit content --- docs/whats-new.md | 2 + snaps/how-to/connect-to-a-snap.md | 2 +- snaps/how-to/get-allowlisted.md | 194 +++++++++++++++++++----------- 3 files changed, 124 insertions(+), 74 deletions(-) diff --git a/docs/whats-new.md b/docs/whats-new.md index 13aa3086edb..e49ddf4ee8f 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -11,6 +11,8 @@ of the [MetaMask developer page](https://metamask.io/developer/). ## April 2024 +- Documented [how to get your Snap allowlisted](/snaps/how-to/get-allowlisted). + ([#1222](https://github.com/MetaMask/metamask-docs/pull/1222)) - Documented [Snaps cron jobs](/snaps/features/cron-jobs). ([#1271](https://github.com/MetaMask/metamask-docs/pull/1271)) - Updated [how to connect to MetaMask](/wallet/how-to/connect) with vanilla TypeScript and React diff --git a/snaps/how-to/connect-to-a-snap.md b/snaps/how-to/connect-to-a-snap.md index 9b71809ee05..f40719fd6f8 100644 --- a/snaps/how-to/connect-to-a-snap.md +++ b/snaps/how-to/connect-to-a-snap.md @@ -1,6 +1,6 @@ --- description: Connect your dapp to existing, third-party Snaps. -sidebar_position: 8 +sidebar_position: 9 --- # Connect to a Snap diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md index 09b2b4aab2f..0485cc27ebb 100644 --- a/snaps/how-to/get-allowlisted.md +++ b/snaps/how-to/get-allowlisted.md @@ -1,101 +1,149 @@ --- description: Submit your Snap for allowlisting on MetaMask extension. -sidebar_position: 7 +sidebar_position: 8 --- # Get allowlisted -You have built your Snap, tested it, published it to npm, and now you are ready to make it available to MetaMask users. -In the MetaMask Snaps Open Beta, an allowlist restricts which Snaps can be installed by users. +Once you have built your Snap, tested it, and published it to npm, you can make it available to +MetaMask users. -:::note -As part of the launch of MetaMask Snaps, individual Snaps must be put on an allowlist before they can be installed by users. This means that at this time, only selected, reviewed Snaps can be installed. In the future, this system will be opened up. By including a Snap on the allowlist, Consensys is not endorsing, recommending, or guaranteeing the safety of this Snap for your use or use for any reason. Always do your own research before installing any Snap. +As part of the Snaps Open Beta launch, individual Snaps must be put on an allowlist before MetaMask +users can install them. +This means that users can only install Snaps that the MetaMask Snaps team has selected and reviewed. +In the future, this system will be opened up. + +:::caution Important +By including a Snap on the allowlist, MetaMask is not endorsing, recommending, or guaranteeing the +safety of the Snap for use for any reason. +Always do your own research before installing a Snap. ::: -## Pre-requisites - -To be added to the allowlist, a Snap must: - -- Make the source code publicly available. This does not mean that the Snap source code has to be published with an open-source license, but users should be able to read the source code of the Snap package. -- Be published to npmjs.com. -- Not impair our compliance with laws or regulations. - -Furthermore, any Snap that uses any of the following permissions pertaining to key management must also provide evidence of a third-party audit from an approved auditor, covering the Snap source code itself that is to run within the Snaps system along with any modules used for key management, with evidence of the commit hash that was audited and the commit that has any fixes documented in the audit report: - -- `snap_getBip32Entropy` -- `snap_getBip32PublicKey` -- `snap_getBip44Entropy` -- `snap_getEntropy` -- `snap_manageAccounts` - -A list of approved third-party auditors and details about the audit process are available on the MetaMask Snaps Builder Engagement Program: -[Approved Auditors](https://consensys.notion.site/Audit-process-1acbc67819dc4631b7a3d6c664e387a3). - -## Submit your Snap - -When you are ready to submit your Snap, you should fill out the -[MetaMask Snaps Directory Information Form](https://go.metamask.io/snaps-directory-request). -You will need to provide the following information: - -- Email - - So we can get in touch with you if we have any questions. -- Snap name - - The name of your Snap. This **must** match the `proposedName` field from the Snap manifest. - - You cannot use these words in the name: MetaMask, Snap, Meta, Mask. -- Snap builder name and URL - - This should match the company, project, or personal site for your brand, where users can learn more about you. -- Snap website URL - - This is a website where users can interact with your Snap. If your Snap does not require a website to be used, this can be left blank. - - If your Snap works with multiple websites, you can include the URLs of additional websites in the _long description_, but this URL should be specifically for an "official" website designed to interact with your Snap. -- Snap short description - - Brief description of the snap, 1 or 2 sentences long. - - Try not to say "is a MetaMask Snap" -- users already know this! -- Snap long description - - Description of the snap features and how to use them. You can use line breaks, lists, and even URLs here. You cannot use HTML. - - If applicable, you should also describe quick steps to onboard and use the Snap. For example: `After installing the Snap, visit the companion dapp at https://voyager-snap.linea.build to connect an account and track your Linea Voyage progress.` -- Link to the public GitHub repo and npm package - - If your Snap is hosted on a different site, like GitLab, you can link to that instead. - - Ensure that you have [correctly published the Snap package](../how-to/publish-a-snap.md). -- Snap version number to be allowlisted - - Make sure that the version number in `package.json` and `snap.manifest.json` match, and that the Snap has been built with the correct `shasum`. -- Snap auditor and audit report - - If your Snap uses one or more of the permissions listed above, provide a PDF or URL to where the audit report has been published. Otherwise, leave this field blank. - - Note: the audit report will be made public. You may ask your auditor to publish the report on their website and provide the link to us. -- Customer support details - - To ensure a smooth user experience, we require customer support details for your Snap. This allows us to escalate any issues that the user is facing with your Snap. You can find more details [here](https://consensys.notion.site/Providing-User-Support-Information-cff79a7d896e4da6a2f8a17ce074e585). The Escalation Contact will be kept confidential between our teams, the rest of the information will be public. You must provide an Escalation Contact and at least one of the remaining items. -- Images - - Here's your opportunity to provide compelling previews of your Snap! These can be screenshots or promotional images to help users get an idea of what your Snap can do. - - Upload 3 images with the following dimensions: 960w x 540h. PNG or JPG are allowed. -- Demo video - - This will help our team review your Snap. It may also be used by our marketing team. - -## Allowlist review +## Prerequisites + +- Make your Snap's source code publicly available. + You don't need to publish your Snap with an open source license, but users should be able to read + the source code of the Snap package. + +- [Publish your Snap](publish-a-snap.md) to npmjs.com. + +- Ensure your Snap complies with laws and regulations. + +- If your Snap uses any of the following API methods related to key management, you must provide + evidence of a third-party audit from an approved auditor: + + - [`snap_getBip32Entropy`](../reference/snaps-api.md#snap_getbip32entropy) + - [`snap_getBip32PublicKey`](../reference/snaps-api.md#snap_getbip32publickey) + - [`snap_getBip44Entropy`](../reference/snaps-api.md#snap_getbip44entropy) + - [`snap_getEntropy`](../reference/snaps-api.md#snap_getentropy) + - [`snap_manageAccounts`](../reference/snaps-api.md#snap_manageaccounts) + + The audit must cover the Snap source code that is to run within the Snaps system, and any modules + used for key management. + You must provide the commit that was audited and the commit that has any fixes documented in the + audit report. + + :::info + A list of approved third-party auditors and details about the audit process are available on the + [MetaMask Snaps Builder Engagement Program](https://consensys.notion.site/Audit-process-1acbc67819dc4631b7a3d6c664e387a3). + ::: + +## Steps + +### 1. Submit your Snap + +When you are ready to submit your Snap, fill out the +[MetaMask Snaps Directory Information form](https://go.metamask.io/snaps-directory-request). +The form requests information about your Snap, including the following: + +- **Snap name** - The name of your Snap. + This must match the `proposedName` field in the Snap [manifest file](../learn/about-snaps/files.md#manifest-file). + You cannot use these words in the name: "MetaMask," "Snap," "Meta," or "Mask." + +- **Snap builder name and URL** - The company, project, or personal site for your brand, where users + can learn more about you. + +- **Snap website URL** - A website where users can interact with your Snap. + If your Snap does not require a website to be used, you can leave this blank. + If your Snap works with multiple websites, you can include the URLs of additional websites in the + **long description**, but this URL should be an official website designed to interact with your Snap. + +- **Snap short description** - A one or two sentence description of your Snap. + Try not to say "is a MetaMask Snap" – users already know this! + +- **Snap long description** - A description of your Snap's features and how to use them. + You can use line breaks, lists, and URLs. + You cannot use HTML. + If applicable, describe quick steps to onboard and use the Snap. + For example: "After installing the Snap, visit the companion dapp at + https://voyager-snap.linea.build to connect an account and track your Linea Voyage progress." + +- **GitHub repository and npm package URLs** - The public GitHub repo that hosts your Snap's + source code, and the npm package of your [published Snap](../how-to/publish-a-snap.md). + If your Snap's source code is hosted on a different site, such as GitLab, you can link to that instead. + +- **Snap version number to be allowlisted** - The Snap version number as specified in `package.json` + and `snap.manifest.json`. + Make sure that the version numbers match and that the Snap has been built with the correct `shasum`. + +- **Snap auditor and audit report** - A PDF or URL of the [required audit report](#prerequisites), + if your Snap uses one or more of the key management API methods. + If your Snap doesn't require an audit, leave this field blank. + + :::note + The audit report will be made public. + You can ask your auditor to publish the report on their website and provide the link to us. + ::: + +- **Customer support details** - + [Customer support information](https://consensys.notion.site/Providing-User-Support-Information-cff79a7d896e4da6a2f8a17ce074e585) + to ensure a smooth user experience for your Snap. + This allows MetaMask to escalate any issues that a user might encounter with your Snap. + The escalation contact will be kept confidential within MetaMask, and the rest of the information + will be public. + You must provide an escalation contact and at least one other customer support item. + +- **Images** - Screenshots or promotional images to help users get an idea of what your Snap can do. + Here's your opportunity to provide compelling previews of your Snap! + +- **Demo video** - A video walking through how to use your Snap. + This will help MetaMask review your Snap, and might also be used by the MetaMask marketing team. + +### 2. Allowlist review Your Snap will be reviewed by the MetaMask Snaps team to ensure it is functional and well-designed. -If the Snap requires an audit, the audit report will be reviewed to ensure that all vulnerabilities with "medium" or higher risk have been addressed. -All Snaps will require at least 2 approvals to be allowlisted. +If the Snap requires an audit, the team will review the audit report to ensure that all +vulnerabilities with medium or higher risk have been addressed. +All Snaps require at least two approvals to be allowlisted. -## Directory listing +### 3. Directory listing Once your Snap is on the allowlist, it will appear in the [MetaMask Snaps Directory](https://snaps.metamask.io). You can direct users to the directory to find and install your Snap. -## Distribute your Snap +### 4. Distribute your Snap -You should deploy a companion dapp where users can learn about your Snap and install it, or -integrate with your existing dapp. +You can deploy a companion dapp where users can learn about your Snap and install it, or you can +integrate your Snap with your existing dapp. If your Snap is designed to communicate with dapps, you can encourage other dapp developers to [connect to your Snap](connect-to-a-snap.md). :::note -While testing your Snap, you may have designed your dapp to require MetaMask Flask. +While testing your Snap, you might have designed your dapp to require MetaMask Flask. Once your Snap is allowlisted, you should update your dapp to support any flavor of MetaMask, and show the orange MetaMask logo instead of the purple Flask logo. ::: -## Updating your Snap +### 5. Update your Snap -The allowlist uses strict versioning for all Snaps. After publishing a new version of your Snap to npm, you will need to submit it for allowlisting. Users will not be able to install new versions until they are allowlisted. +The allowlist uses strict versioning for all Snaps. +After publishing a new version of your Snap to npm, you must re-submit it for allowlisting by +filling out the +[MetaMask Snaps Directory Information Update form](https://go.metamask.io/snaps-directory-update-request). +Users will not be able to install a new version until it is allowlisted. -Submit the [Directory Information Update Form](https://go.metamask.io/snaps-directory-update-request) for any new version of your Snap. You can also update any information about your Snap with this form. For any fields that do not need to be changed, you can leave them blank or enter "N/A." When providing the version to be allowlisted, you should also let us know if previous versions of your Snap should be removed from the allowlist (effectively replaced with this new version). +You can also update any information about your Snap using the form. +For fields that you don't need to update, you can leave them blank or enter "N/A." +When providing the new version to be allowlisted, you should also note whether previous versions of +your Snap should be removed from the allowlist (effectively, replaced with the new version). From 423526152b6e86bf1ecd48befb6747a6c0b88af7 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Thu, 18 Apr 2024 13:11:23 -0700 Subject: [PATCH 10/11] more edits --- snaps/how-to/get-allowlisted.md | 7 +++---- snaps/how-to/publish-a-snap.md | 7 ++++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md index 0485cc27ebb..f44f3c22417 100644 --- a/snaps/how-to/get-allowlisted.md +++ b/snaps/how-to/get-allowlisted.md @@ -1,5 +1,5 @@ --- -description: Submit your Snap for allowlisting on MetaMask extension. +description: Submit your Snap for allowlisting on the MetaMask extension. sidebar_position: 8 --- @@ -25,7 +25,7 @@ Always do your own research before installing a Snap. You don't need to publish your Snap with an open source license, but users should be able to read the source code of the Snap package. -- [Publish your Snap](publish-a-snap.md) to npmjs.com. +- [Publish your Snap](publish-a-snap.md) to npm. - Ensure your Snap complies with laws and regulations. @@ -52,8 +52,7 @@ Always do your own research before installing a Snap. ### 1. Submit your Snap -When you are ready to submit your Snap, fill out the -[MetaMask Snaps Directory Information form](https://go.metamask.io/snaps-directory-request). +Fill out the [MetaMask Snaps Directory Information form](https://go.metamask.io/snaps-directory-request). The form requests information about your Snap, including the following: - **Snap name** - The name of your Snap. diff --git a/snaps/how-to/publish-a-snap.md b/snaps/how-to/publish-a-snap.md index 6f21d80e776..4555d9543e2 100644 --- a/snaps/how-to/publish-a-snap.md +++ b/snaps/how-to/publish-a-snap.md @@ -32,7 +32,8 @@ Snap location to **npm** and the ID of your Snap. Also, make sure to update the manifest file, icon file, and README to differentiate your Snap from the template. ::: -## Make it available to users +## Make a Snap available to users -Now that your Snap is published, you probably want to make it available to MetaMask users. -Learn how to [get allowlisted](get-allowlisted.md) so anyone can install your Snap in the MetaMask extension. +After publishing a Snap, you can make it available to MetaMask users by +[getting your Snap allowlisted](get-allowlisted.md). +Once allowlisted, anyone can install your Snap in the MetaMask extension. From c6abad9afbae79449dff009cd15745c2901bbdd1 Mon Sep 17 00:00:00 2001 From: Christian Montoya Date: Fri, 19 Apr 2024 00:16:30 -0400 Subject: [PATCH 11/11] Revert some edits to text --- snaps/how-to/get-allowlisted.md | 45 ++++++++++++++++----------------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/snaps/how-to/get-allowlisted.md b/snaps/how-to/get-allowlisted.md index f44f3c22417..9ba5f484ec3 100644 --- a/snaps/how-to/get-allowlisted.md +++ b/snaps/how-to/get-allowlisted.md @@ -8,28 +8,27 @@ sidebar_position: 8 Once you have built your Snap, tested it, and published it to npm, you can make it available to MetaMask users. -As part of the Snaps Open Beta launch, individual Snaps must be put on an allowlist before MetaMask -users can install them. -This means that users can only install Snaps that the MetaMask Snaps team has selected and reviewed. +As part of the MetaMask Snaps Open Beta launch, individual Snaps must be put on an allowlist before users can install them. +This means that at this time, only selected, reviewed Snaps can be installed. In the future, this system will be opened up. :::caution Important -By including a Snap on the allowlist, MetaMask is not endorsing, recommending, or guaranteeing the -safety of the Snap for use for any reason. +By including a Snap on the allowlist, Consensys is not endorsing, recommending, or guaranteeing the +safety of a Snap for your use or use for any reason. Always do your own research before installing a Snap. ::: ## Prerequisites -- Make your Snap's source code publicly available. - You don't need to publish your Snap with an open source license, but users should be able to read - the source code of the Snap package. - -- [Publish your Snap](publish-a-snap.md) to npm. +To be added to the allowlist, a Snap must: -- Ensure your Snap complies with laws and regulations. +- Have publicly available source code. + You don't need to publish your code with an open source license, but users should be able to read + the source code of the Snap package. +- Be [published](publish-a-snap.md) to npm. +- Not impair our compliance with laws or regulations. -- If your Snap uses any of the following API methods related to key management, you must provide +Furthermore, if your Snap uses any of the following API methods related to key management, you must provide evidence of a third-party audit from an approved auditor: - [`snap_getBip32Entropy`](../reference/snaps-api.md#snap_getbip32entropy) @@ -38,15 +37,15 @@ Always do your own research before installing a Snap. - [`snap_getEntropy`](../reference/snaps-api.md#snap_getentropy) - [`snap_manageAccounts`](../reference/snaps-api.md#snap_manageaccounts) - The audit must cover the Snap source code that is to run within the Snaps system, and any modules - used for key management. - You must provide the commit that was audited and the commit that has any fixes documented in the - audit report. +The audit must cover the Snap source code that is to run within the Snaps system, and any modules +used for key management. +You must provide the commit that was audited and the commit that has any fixes documented in the +audit report. - :::info - A list of approved third-party auditors and details about the audit process are available on the - [MetaMask Snaps Builder Engagement Program](https://consensys.notion.site/Audit-process-1acbc67819dc4631b7a3d6c664e387a3). - ::: +:::info +A list of approved third-party auditors and details about the audit process are available on the +[MetaMask Snaps Builder Engagement Program](https://consensys.notion.site/Audit-process-1acbc67819dc4631b7a3d6c664e387a3). +::: ## Steps @@ -74,8 +73,8 @@ The form requests information about your Snap, including the following: You can use line breaks, lists, and URLs. You cannot use HTML. If applicable, describe quick steps to onboard and use the Snap. - For example: "After installing the Snap, visit the companion dapp at - https://voyager-snap.linea.build to connect an account and track your Linea Voyage progress." + For example: _After installing the Snap, visit the companion dapp at + https://voyager-snap.linea.build to connect an account and track your Linea Voyage progress._ - **GitHub repository and npm package URLs** - The public GitHub repo that hosts your Snap's source code, and the npm package of your [published Snap](../how-to/publish-a-snap.md). @@ -123,7 +122,7 @@ You can direct users to the directory to find and install your Snap. ### 4. Distribute your Snap You can deploy a companion dapp where users can learn about your Snap and install it, or you can -integrate your Snap with your existing dapp. +integrate your Snap with your existing dapp. If your Snap is designed to communicate with dapps, you can encourage other dapp developers to [connect to your Snap](connect-to-a-snap.md).