From 7e49af4fd563d8f4aa59832f49b4d46c210ec15d Mon Sep 17 00:00:00 2001 From: Lara Schmid Date: Mon, 17 Jul 2023 12:15:05 +0200 Subject: [PATCH] adding launch explanation for new 1proposal solution --- .../sns/launching/launch-steps-1proposal.md | 120 ++++ .../sns/launching/launch-summary-1proposal.md | 514 ++++++++++++++++++ .../sns/launching/launch-summary.md | 16 +- 3 files changed, 643 insertions(+), 7 deletions(-) create mode 100644 docs/developer-docs/integrations/sns/launching/launch-steps-1proposal.md create mode 100644 docs/developer-docs/integrations/sns/launching/launch-summary-1proposal.md diff --git a/docs/developer-docs/integrations/sns/launching/launch-steps-1proposal.md b/docs/developer-docs/integrations/sns/launching/launch-steps-1proposal.md new file mode 100644 index 0000000000..9f83263435 --- /dev/null +++ b/docs/developer-docs/integrations/sns/launching/launch-steps-1proposal.md @@ -0,0 +1,120 @@ +# SNS launch steps + +## Overview +At a high level, the stages for launching an SNS in production are explained [here](../launching/launch-summary.md). + +This article lists the technical commands and steps a developer needs to complete the stages for an SNS launch. + +At a low level, the [SNS local testing repository](../testing/testing-locally.md) guides you through the same, with the difference that the commands target the canisters on the mainnet. + +## Requirements + +### 1. IC SDK + +See: [installing the IC SDK](../../../setup/install). + +### 2. `ic-admin` + +See: [installing the `ic-admin`](../../../setup/ic-admin.md). + +### 3. `sns` CLI + +:::note +The version of the sns CLI that is bundled with your dfx version may not have the latest commands described in the Usage section. If needed, it is recommended to build and use the sns CLI tool yourself. +::: + +```bash +git clone git@github.com:dfinity/ic.git +cd ic +bazel build //rs/sns/cli:sns +ls bazel-bin/rs/sns/cli/sns +``` +## Stages + +### 1. Dapp developers choose the initial parameters of the SNS for a dapp + +Typically, dapp developers typically choose initial parameters that will be used in subsequent proposals. + +### 2. Dapp developers submit NNS proposal so they can deploy to the SNS subnet + +Anyone who owns an NNS neuron with enough stake can submit a proposal +that lists a principal wallet in [SNS-W](../introduction/sns-architecture.md#SNS-W) who can then deploy the SNS canisters. + +To create such a proposal, a common path is to use `ic-admin` and run the following: + +```bash +ic-admin \ + --nns-url "${NETWORK_URL}" propose-to-update-sns-deploy-whitelist \ + --added-principals "${WALLET}" \ + --proposal-title "Let me SNS!" \ + --summary "This proposal whitelists developer's principal to deploy SNS" +``` + +* One can substitute `WALLET` with the principal in question. +* One can substitute `NETWORK_URL` with `https://nns.ic0.app`. + +### 3. Proposal #1 (of 3) is passed or rejected + +### 4. Dapp developers trigger the SNS canisters to be created on SNS subnet + +After the wallet canister is listed in SNS-W, +the SNS canisters are created triggered by a manual call to SNS-W. + +The `sns CLI` command to trigger the creation of SNS canisters on the SNS subnet: + +```bash +sns deploy --network "${NETWORK}" --init-config-file "${CONFIG}" --save-to "sns_canister_ids.json" +``` + +### 5. Dapp developers submit an SNS proposal to handover control of their dapp to the SNS + +After the SNS canisters are deployed and the dapp's control is handed over to +the SNS, an NNS proposal starts the swap. + +Again, anyone who owns an NNS neuron with enough stake can submit this proposal. +Of course it is crucial to set the right parameters in this proposal. +You can also find an example how this command is used in the SNS local testing +[here](https://github.com/dfinity/sns-testing/blob/main/open_sns_sale.sh#L11-L26). +``` +ic-admin \ + --nns-url "${NETWORK_URL}" propose-to-open-sns-token-swap \ + --min-participants 3 \ + --min-icp-e8s 5000000000 \ + --max-icp-e8s 50000000000 \ + --min-participant-icp-e8s 100000000 \ + --max-participant-icp-e8s 20000000000 \ + --swap-due-timestamp-seconds "${DEADLINE}" \ + --sns-token-e8s 500000000000 \ + --target-swap-canister-id "${SNS_SWAP_ID}" \ + --community-fund-investment-e8s 5000000000 \ + --neuron-basket-count 3 \ + --neuron-basket-dissolve-delay-interval-seconds 31536000 \ + --proposal-title "Decentralize this SNS" \ + --summary "Decentralize this SNS" +``` + +### 6. Proposal #2 (of 3) is passed or rejected + +Nothing technical for dapp developers to do. Community votes. + +### 7. Proposal to start the decentralization swap + +### 8. Proposal #3 (of 3) is passed or rejected + +Nothing technical for dapp developers to do. Community votes. + +### 9. SNS participants participate in the decentralization swap + +Nothing technical for dapp developers to do. Community participates in the swap. + +### 10. SNS canisters become SNS DAO + +When the swap ends, either because its deadline is reached or because the maximum +ICP have been collected, its finalization has to be triggered by a manual call +to the SNS swap that can be done by anyone. +You can find this command with more context in the SNS local testing repository +[here](https://github.com/dfinity/sns-testing/blob/main/finalize_sns_sale.sh#L8). + +``` +dfx canister --network "${NETWORK}" call finalize_swap '(record {})' +``` diff --git a/docs/developer-docs/integrations/sns/launching/launch-summary-1proposal.md b/docs/developer-docs/integrations/sns/launching/launch-summary-1proposal.md new file mode 100644 index 0000000000..4cfb89b060 --- /dev/null +++ b/docs/developer-docs/integrations/sns/launching/launch-summary-1proposal.md @@ -0,0 +1,514 @@ +# Stages of an SNS launch + +## Overview + +A crucial purpose of an SNS launch is to decentralize the control of an SNS and thereby of +the dapp that the SNS governs. + +Thereby, new tokens must be distributed to a large community to ensure +proper decentralization of the voting power. There are of course many ways to do so. + +The SNS provides one simple way to achieve this: a developer can hand over their dapp +to the NNS and ask it to create an SNS and start a decentralization swap for it. +The decentralization swap collects ICP from participants and distributes the voting +power of the SNS among participants by swaping the ICP for (staked) SNS tokens. + +We first explain the decentralization swap in more detail and then all the stages of +an SNS launch. + +## Key concepts + +### Decentralization swap + +The launch of each SNS includes a separate **decentralization swap canister** that +is owned and run by the IC. +In more detail, it is controlled by the NNS root canister. + +* The swap canister is set up at the start with a defined amount of SNS tokens to be + distributed publicly. + +* During the decentralization swap, participants can send ICP to the swap canister + to contribute to the dapp’s funding. + +* At the swap's end the collected ICP are “swapped” for the SNS tokens; the + participants get staked SNS tokens in the form of SNS neurons and the SNS gets the + collected ICP. Each swap participant will receive their portion of the pool of SNS + tokens, pro-rated by their share of the overall number of ICP contributed. + For example, if the swap canister initially held 1000 SNS tokens and 500 ICP tokens + were collected during the decentralization swap, then the exchange rate would be 2:1 + and each participant would get 2 SNS tokens for each ICP token they contributed. + +## SNS launch Stages +Handing over a dapp's control to a newly created SNS proceeds in the following high +level stages. +Note that only the first two stages require manual action from the dapp's developer +team and the NNS community. All other stages are exectued fully automatically. +The NNS community's approval is relevant in Stage 2. + +### 1. Dapp developers choose the initial parameters of the SNS for a dapp + These parameters define all the initial parameters of the SNS, including + * the token name, token symbol, ledger transaction fee + * the tokenomics and how the governance will work + * the initial token distribution + * the conditions for the decentralization swap + + Therefore defining these parameters usually requires a lot of preparation and + community engagement already (see [here](../tokenomics/sns-checklist.md) for + more information). + + What we have at this stage: + +#### Table 1 + + + + + + + + + + + + + + + + + + +
SNS ProcessState
Decentralization swap statePending
NNS ProposalNot Created
SNS ProposalNot Created
+ +#### Table 2 + + + + + + + + + + + + +
CanistersStateControlled by
a dappoperationaldapp developer principal
+ +### 2. Dapp developers submit NNS proposal to create SNS + +This proposal defines all the initial parameters for teh the conditions for the decentralization swap +(e.g. how many ICP tokens should at least and at most be collected). + +If successful, at the end of stage, we the following has changed: + + +When all initial parameters are specified and the NNS approved the SNS launch, +the SNS canisters can be created by a manual call to [SNS-W](../introduction/sns-architecture.md#SNS-W). +This will initiate the creation of the SNS canisters and set their initial parameters as +chosen in [Step 1](#SNS-launch-step-preparation). + +**The SNS canisters are created in pre-decentralization-swap mode.** + +After the SNS canister creation, the canisters exist but are not yet fully functional - the SNS is in **pre-decentralization-swap mode**. + +At this point, the SNS ledger has two accounts: + +* The **treasury** that is owned by the SNS governance canister and which can be used in the future according to the SNS community's wishes. +* Some pre-allocated tokens to be used in the initial decentralization swap. + +To ensure that no one can transfer tokens and distribute them, or start token markets prematurely, all remaining initial tokens are locked in neurons. +Moreover, in pre-decentralization-swap mode, the initial neurons cannot modify the SNS or transfer the treasury tokens. + +If successful, at the end of stage, we the following has changed: + +#### Table 3 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Objects in the SNS subnetStateControlled by
a principal that can deploy to SNS subnetrevoked because it is 1-time useNA
SNS root on the SNS subnetpre-decentralization swap modeinitial developer neurons
initial developer neuronspre-decentralization swap modedapp developer principal
treasury account on the SNS Ledgerpre-decentralization swap modeSNS governance
swap account on the SNS Ledgerpre-decentralization swap modeSNS swap
+ + +### 3. Dapp developers add NNS root as co-controller of dapp + +### 4. Proposal is decided +If + * proposal adopted + * sns-w must have cycles +=> next stages are triggered automatically, else failed swap + +### 5. (automatically) SNS-W deploys SNS canisters +### 6. (automatically) SNS-W sets SNS root as single controller of dapp +* removes devs as controllers => proxied call to SNS root over NNS root => transfer of control to SNS +* if all good, have NNS root remove itself as controller + +### 7. (automatically) SNS-W initializes SNS canisters according to settings from Step 1 +* installs init payloads, including start of swap + + +### 8. (automatically) SNS swap starts +swap starts automatically if the time is reached + +### 9. (automatically) SNS swap ends +swap automatically ends if deadline reached (or max participation) + +### 10. (automatically) SNS swap finalizes +swap automatically finalizes + +### Failed launch +if proposal rejected +or SNS-W not enough cycles +or swap unsucessful +=> give back + + +======= +### 4. Dapp developers trigger the SNS canisters to be created on SNS subnet + + + +**The SNS canisters are created in pre-decentralization-swap mode.** + +After the SNS canister creation, the canisters exist but are not yet fully functional - the SNS is in **pre-decentralization-swap mode**. + +At this point, the SNS ledger has two accounts: + +* The **treasury** that is owned by the SNS governance canister and which can be used in the future according to the SNS community's wishes. +* Some pre-allocated tokens to be used in the initial decentralization swap. + +To ensure that no one can transfer tokens and distribute them, or start token markets prematurely, all remaining initial tokens are locked in neurons. +Moreover, in pre-decentralization-swap mode, the initial neurons cannot modify the SNS or transfer the treasury tokens. + +If successful, at the end of stage, we the following has changed: + +#### Table 3 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Objects in the SNS subnetStateControlled by
a principal that can deploy to SNS subnetrevoked because it is 1-time useNA
SNS root on the SNS subnetpre-decentralization swap modeinitial developer neurons
initial developer neuronspre-decentralization swap modedapp developer principal
treasury account on the SNS Ledgerpre-decentralization swap modeSNS governance
swap account on the SNS Ledgerpre-decentralization swap modeSNS swap
+ +### 5. Dapp developers submit an SNS proposal to handover control of their dapp to the SNS + Before the decentralization swap, the developers hand over the control of the dapp to the SNS. + + This includes adding the SNS root canister as the controller of the dapp and removing + yourself (and possibly other developers) from the list of + controllers. Also, this includes "registering" the dapp with the SNS so that SNS + root is aware that it controls these canisters. + + The registration is done by **SNS proposal**. + + As there are already initial neurons, this, + as well as potential upgrades to the dapp, can be realized by SNS proposals and by the + majority of initial neurons voting in favor of them. + The initial neurons cannot do other things, such as changing + the SNS parameters, as the SNS governance canister is still in + pre-decentralization-swap mode. + +If successful, at the end of stage, we the following has changed: + +#### Table 1 + + + + + + + + + + + + + + + + + + + + + + +
SNS ProcessState
Decentralization swap statePending
NNS Proposal #1Approved
SNS Proposal #1Submitted
NNS Proposal #2Not Created
+ +### 6. Proposal #2 (of 3) is passed or rejected + +The initial SNS developer neurons are declared in the initial parameters and available at SNS installation. + +If successful, at the end of stage, we the following has changed: + +#### Table 1 + + + + + + + + + + + + + + + + + + + + + + +
SNS ProcessState
Decentralization swap statePending
NNS Proposal #1Approved
SNS Proposal #1Approved
NNS Proposal #2Not Created
+ +#### Table 2 + + + + + + + + + + + + +
Objects in an app subnetStateControlled by
a dappoperationalSNS root
+ +### 7. Proposal to start the decentralization swap + +This proposal defines the conditions for the decentralization swap (e.g. how many ICP tokens should at least and at most be collected). + +If successful, at the end of stage, we the following has changed: + +#### Table 1 + + + + + + + + + + + + + + + + + + + + + + +
SNS ProcessState
Decentralization swap statePending
NNS Proposal #1Approved
SNS Proposal #1Approved
NNS Proposal #2Submitted
+ +### 8. Proposal #3 (of 3) is passed or rejected + +This is the **last of three** proposals that need to successfully pass for the process to continue. + +When voting on this proposal, the NNS voters can verify the parameters in the already +existing SNS canisters as well as the swap parameters that are set in the proposal. + +* If the NNS proposal is adopted, the swap is started after a specified delay. +* If the NNS proposal is rejected, the SNS launch is aborted and the dapp’s control is handed +back to the original developers of the dapp. + +If successful, at the end of stage, we the following has changed: + + +#### Table 1 + + + + + + + + + + + + + + + + + + + + + + +
SNS ProcessState
Decentralization swap stateOpen
NNS Proposal #1Approved
SNS Proposal #1Approved
NNS Proposal #2Approved
+ +### 9. SNS participants participate in the decentralization swap + + When the swap starts, the swap canister holds the number + of SNS tokens that were specified. End users can + participate in the decentralization swap by transferring ICP tokens to the + swap canister. + + +### 10. SNS canisters become SNS DAO + + When the decentralization swap ends, it is first established whether + it was successful, e.g., enough ICP have been collected. If the swap was successful, + the exchange rate is determined and all SNS tokens are given to the swap participants in + neurons. + + Currently, this process needs to be triggered by a call to the swap canister that anyone + can make. + + Once all neurons are created, the SNS should be under decentralized control + and the pre-decentralization-swap mode is reverted. + Thus, the governance canister is set to be fully functional. + If the swap is not successful, the decentralization attempt failed and everything + is reverted to the state before the SNS launch attempt, including that the dapp’s control + is handed back to the original developers of the dapp, and the + collected ICP are refunded to the swap participants. + + +If successful, at the end of stage, we have: + +#### Table 1 + + + + + + + + + + + + + + + + + + + + + + +
SNS ProcessState
Decentralization swap stateCommitted
NNS Proposal #1Approved
SNS Proposal #1Approved
NNS Proposal #2Approved
+ +#### Table 2 + + + + + + + + + + + + +
Objects in an app subnetStateControlled by
A dappoperationalSNS DAO
+ +#### Table 3 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Objects in the SNS subnetStateControlled by
a principal that can deploy to SNS subnetrevoked because it is 1-time useNA
SNS rootnormal modeSNS DAO
initial developer neuronsnormal modedapp developer principal
treasury account on the SNS Ledgernormal modeSNS DAO
swap account on the SNS LedgeremptySNS DAO
SNS neuronsnormal modeswap participant principals
diff --git a/docs/developer-docs/integrations/sns/launching/launch-summary.md b/docs/developer-docs/integrations/sns/launching/launch-summary.md index 3189d182db..e4d43c4bbf 100644 --- a/docs/developer-docs/integrations/sns/launching/launch-summary.md +++ b/docs/developer-docs/integrations/sns/launching/launch-summary.md @@ -8,8 +8,9 @@ the dapp that the SNS governs. Thereby, new tokens must be distributed to a large community to ensure proper decentralization of the voting power. There are of course many ways to do so. -The current SNS version provides one simple way to achieve this: a developer can hand over their dapp to the NNS and ask it to start a decentralization -swap for the newly created SNS. +The current SNS version provides one simple way to achieve this: a developer can hand +over their dapp to the NNS and ask it to start a decentralization swap for the newly +created SNS. We first explain the decentralization swap and then the stages for an SNS launch. @@ -35,7 +36,7 @@ In more detail, it is controlled by the NNS root canister. were collected during the decentralization swap, then the exchange rate would be 2:1 and each participant would get 2 SNS tokens for each ICP token they contributed. -## Stages +## SNS launch stages Handing over a dapp's control to a newly created SNS proceeds in the following high level stages. Note that the NNS community's approval is relevant in two stages (stages 3, 7, and 9). @@ -140,11 +141,12 @@ What we have at this stage: -### 3. Proposal #1 (of 3) is passed or rejected +### 3. Proposal #1 (of 3) is adopted or rejected This is the **first of three** proposals that need to successfully pass. -If this NNS proposal passes and the developer's principal is added the list of principals that can deploy to the SNS subnet, it does **not** guarantee the rest of the next stages will complete. +If this NNS proposal passes and the developer's principal is added the list of principals that can deploy to the SNS +subnet, it does **not** guarantee the rest of the next stages will complete. If the proposal is adopted successfully, at the end of this step, we have: @@ -304,7 +306,7 @@ If successful, at the end of stage, we the following has changed: -### 6. Proposal #2 (of 3) is passed or rejected +### 6. Proposal #2 (of 3) is adopter or rejected The initial SNS developer neurons are declared in the initial parameters and available at SNS installation. @@ -381,7 +383,7 @@ If successful, at the end of stage, we the following has changed: -### 8. Proposal #3 (of 3) is passed or rejected +### 8. Proposal #3 (of 3) is adopted or rejected This is the **last of three** proposals that need to successfully pass for the process to continue.