In an effort to make the preparation for a SNS launch smooth, we have created a checklist with the documentation, technical preparation and testing that should be completed before the launch. The checklist may not cover the process of every launch, since different projects may have different requirements, but can provide general guidance.
Feedback is appreciated!
NOTE: For the latest version of this checklist, see the documentation
This guide is intended for informational purposes only and may be modified over time as it deems appropriate. It is aimed to provide general guidance for projects that are planning to launch an SNS but should not be construed as the definitive list of action items that need to be taken in preparation of any such launch. Following this guide is not a guarantee of a successful SNS launch – that is a decision by the NNS DAO. Ultimately, following this guide and/or launching an SNS is done at your own risk.
There’s a also worksheet version available of this document, which can be used for documenting the SNS launch steps.
- Documentation / Preparation
- 1.1. Tokenomics specification
- 1.2. Technical architecture / whitepaper / project roadmap.
- 1.3. Disclosures
- 1.4. Create SNS configuration file
- 1.5. Create NNS proposals
- Technical Prep & Testing
- 2.1. Security review
- 2.2. Open Sourcing
- 2.3. Create reproducible build
- 2.4. Test dapp operations under SNS on mainnet with SNS Testflight
- 2.5. Integrate an SNS frontend into the dapp
- 2.6. Test the SNS launch locally
- Community Consultation
- 3.1. Publish tokenomics / whitepaper / roadmap / architecture
- 3.2. Community discussion (forum) - min. 2 weeks before submitting NNS proposals.
- SNS Launch Workflow
- 4.1. Submit canister creation proposal
- 4.2. Create SNS canisters
- 4.3. Dapp control handover
- 4.4. Submit decentralization proposal
- 4.5. Setup custom SNS functions
1.1.1. Token utility
Define concisely for which use cases the token of the DAO will be used for participation in governance, rewarding active participation in services offered by the dapp that is governed by the DAO and rewarding contributions to the growth of the dapp and the DAO.
1.1.2. Initial token allocation
For the initial token allocation, i.e., defining which groups/accounts should receive how many tokens, developers could consider the following main blocks: DAO treasury, decentralization swap, seed funders and funding development team. See more information about token allocation in the documentation. Include information about vesting periods for developers and the seed team.
1.1.3. Voting power
Provide information about how voting power is distributed at genesis, potential attack vectors and how the voting power might evolve over time.
It is considered to be best practice that sale participants have the majority of voting power at genesis. If the developers and seed investors have the majority together, then it should be clearly articulated why these two parties are independent.
1.1.4. Funding target
The minimum and maximum funding target must be defined for the decentralization sale. Add information about the planned usage of the funds, e.g. plans of ramping up the team.
The analyzer uses the SNS configuration file as a basis that you’ll later use to create the proposal for the SNS DAO.
1.2.1. Technical architecture
The technical architecture should give an overview of the dapp and illustrate how the dapp works. Some dapps rely on off-chain components, either developed and maintained by the team, or 3rd party components. The use of components that will not be controlled by the DAO should also be included to show the dependencies.
The whitepaper should provide information about the dapp, the architecture, the goal with launching the SNS, tokenomics and other information relevant to the community to vote on the decentralization proposal. It should be clear what the dapp will gain from the SNS launch. The whitepaper from OpenChat’s SNS launch can be used for inspiration, see it here.
1.2.3. Project roadmap
The roadmap should show what the plan is with the dapp, also past the SNS launch. The roadmap should show the vision the team/developers behind the dapp have for the dapp, and what they would like to work on, also after the SNS launch. See OpenChat’s roadmap for inspiration.
It may not be possible to fully decentralize the dapp at the time of the SNS launch. The dapp may rely on off-chain services or 3rd party service providers like SMS/Text gateways.
If the dapp does have dependencies of some kind that cannot be managed by the DAO, then those dependencies should be documented so the community is aware of potential risks. When possible, there should also be a plan for how to bring these services on-chain and under control of the DAO.
The SNS is initialized using an NNS proposal that defines the initial parameters, thus the initial configuration is approved by the NNS DAO.
The proposal can be created from a .yaml configuration file and defines things like the token name, token supply, token distribution, transaction fees, dissolve delays and more.
The initial parameters are explained more here.
You can find a template with all parameters that need to be defined here and an example of a filled in file here.
Add comments, explaining the parameters and token allocation, in the configuration file for transparency and ease of reading.
Geo-restriction can be used to exclude users with IPs in specific countries with the “restricted_countries” parameter, which takes an array of country codes like this:
restricted_countries: [ "CH" ].
A confirmation text, defined as a parameter that is approved by the NNS, can be shown before the user can participate in the decentralization swap. This confirmation text can be set like this:
confirmation_text: "Please confirm that..."
Test the configuration extensively locally before submitting the NNS proposal. See section 2 for more information about testing.
As a part of the SNS launch process, an NNS proposal must be created to ask the NNS to create an SNS and start a decentralization swap. You can find the details about how to create such a proposal here.
Include relevant information like tokenomics (token distribution, governance, decentralization swap), details about the dapp (link to the open sourced code), whitepaper, a link to the forum discussion (see Step 3.2), and anything else relevant for the community to make a decisions if an SNS should be launched for the dapp.
For details about the preparation process, see the documentation. The documentation page SNS Predeployment Considerations has a list of topics that should be covered in the whitepaper/proposal. See this forum post for information about DFINITY’s voting.
In general, it is considered best practice to conduct a security review including the fixing of risky findings. Guidance on security best practices is here. It should be explained to which extent security reviews are relevant for the dapp and what kind of security reviews have been conducted for the dapp if applicable.
If the dapp is not already open sourced, it should be open sourced before the SNS launch - actually before the decentralization proposals are created. A dapp is not truly decentralized if the source code is not shared with the community. Open sourcing the code gives the community an opportunity to evaluate the dapp before the SNS launch, and after the launch, where upgrades must be voted on. It’s hard to make a meaningful voting decision without having full visibility into the code, and without the visibility it will also not be possible to verify the code and assess the impact it will have, before voting.
It should be possible to create a reproducible build from the open sourced code, for the same reasons as open sourcing the code. Providing the build and deploy instructions enables the community to evaluate the dapp and the code before voting on the SNS launch proposal, and after the decentralization, where upgrades must be voted on, the upgrades can be verified and tested by the community before voting.
Provide the build and deploy instructions with the source code. Ideally the instructions are a part of the code repository README file, and if that’s not the case, a link to the instructions should be available in the README file. In order to be able to create a reproducible build, the build environment needs to be reproducible. The documentation here provides more information how reproducible builds can be created using Docker.
Before requesting an SNS launch in production, developers are strongly encouraged to test their deployed dapp’s operation (e.g., upgrading the dapp’s canisters) via SNS proposals, as if the live version of the dapp was managed by SNS.
Make sure to test upgrading canisters through SNS proposals, test updating asset canister content through SNS proposals, and other typical upgrade and maintenance operations. Also establish a cycles management strategy, so canisters never run out of cycles. The longer the test runs, the better, ideally several weeks.
The developer can keep direct control over the dapp’s canisters registered with testflight SNS.
The testflight can be done in a local test environment or with the live dapp on the mainnet. When deployed on the mainnet, the testflight SNS is deployed to a regular application subnet instead of a dedicated SNS subnet.
To use the SNS testflight on the mainnet, pass the “–network ic” parameter to the deploy command. The documentation for running the testflight is the same as for deploying it locally - except for the added parameter (which is also covered in the documentation).
See the documentation for more information about the SNS Testflight, including setup instructions.
Developers can choose to integrate a frontend for the SNS functionality in the dapp. A good example of a useful integration is SNS proposal voting. This allows neurons to vote on proposals directly in the dapp frontend. Integrations should be tested thoroughly with the SNS Testflight or the local SNS test before the SNS launch.
In addition to performing comprehensive testing of all dApp operations using the SNS (as explained in section 2.4), it is recommended to conduct a local test of the SNS launch process. By doing so, you can simulate the complete SNS initial token swap process also from the user’s perspective via the NNS frontend dApp. Detailed instructions on how to set up SNS locally for testing are available here.
The documentation prepared in section 1.1 and 1.2 should be made publicly available ahead of the SNS launch. This provides transparency about the dapp, future plans with the dapp, the technical architecture and the tokenomics. This information can be shared on the dapp’s website, GitHub or where it would make sense.
It’s strongly recommended that developers have a discussion in the forum with the community about the decentralization plans. It’s suggested to start a thread at least a couple of weeks before the NNS proposal is created. This will allow the community to learn about your plans, ask questions and build trust in the SNS launch. The SNS initialization and decentralization sale will not start unless enough NNS neurons vote in favor of the proposal.
It is recommended to share:
- The init file and sale file (example: OpenChat)
- Provide whitepaper with a full description of the decentralization and tokenomics.
- Provide a technical decomposition of the dapp architecture in terms of canisters, source code and documentation so that the community can validate that the dapp will actually be a decentralized application after the swap.
- Explain to which extent security reviews were considered relevant for the dapp and what kind of security reviews have been conducted for the dapp.
The idea is to provide the community with information so they can verify what they are supporting from a decentralization standpoint.
First step in the launch is create a proposal to add a principal that can later create the SNS canisters. Use the proposal content created in section 1.4.1 and create the NNS proposal. The proposal can be created with the quill command line tool.
When the NNS neurons have voted in favor of the canister creation proposal, the SNS canisters can be installed, and prepared for the SNS launch. The SNS canisters are installed with the sns cli tool.
Before the decentralization sale, the SNS root canister must be set as the controller of the dapp and other developers are removed from the list of controllers. This entails “registering” the dapp with the SNS so that SNS root is aware that it controls these canisters, and this registration is done by SNS proposal.
Consider what the impact of the handover will have for the entire dapp, since principals will change. Is it necessary to change access rights to e.g. asset canisters? All features of the dapp should be thoroughly tested before the SNS launch. See previous mention of testing with the SNS testflight.
This step is similar to submitting the canister creation proposal. This proposal will initiate the decentralization and the token sale. Use the proposal content created in section 1.4.2 and create the NNS proposal. The proposal can be created with the quill command line tool.
To execute code on SNS managed canisters via SNS proposals, the canisters must expose two public functions, also referred to as generic functions in the documentation. The first function is a validation function to validate and render the proposal payload, and the second function is an execution function to perform an action given the proposal payload.
To use generic functions, you must first submit an SNS proposal to register these functions with SNS governance. Once the proposal is adopted, you can submit proposals to execute them with a given binary payload.
See the documentation for more information about generic functions, how to submit the register proposal, and how to submit proposals to execute the functions.