Merge pull request #2295 from LaraAS/master

NNS and SNS how-it-works and go-deeper

docs/developer-docs/integrations/sns/introduction/sns-intro-high-level.md

@@ -7,9 +7,7 @@ sidebar_position: 1
 A Service Nervous Systems (SNS) is an advanced form of a decentralized autonomous organization (DAO).
 It is assumed that if you are reading this page you know what a DAO is and that you want to learn how
 you can hand over your dapp to an SNS DAO.
-If this is not (yet) the case, you can learn more about DAOs and SNSs
-[here](../tokenomics/index.md),
-including what advantages such decentralized governance systems have.
+If this is not (yet) the case, please refer to the [SNS page](/sns/) or the [high level introduction of how SNSs work](/how-it-works/sns/).
 
 Any dapp on the Internet Computer can be handed over to an SNS with the result that the dapp is
 owned and controlled by a community.

how-it-works/3_governance/01_network-nervous-system-nns.card.md

@@ -6,8 +6,8 @@ title: Network Nervous System
 
 # Network Nervous System
 
-The Internet Computer is a *decentralized* system run by many independent nodes. The *Network Nervous System (NNS)* coordinates their effort by determining which subnet a node belongs to (the topology), which protocol version they should run, and when they should upgrade to a new protocol version.
+The Network Nervous System (NNS) is the DAO that controls the Internet Computer blockchain. It is a permissionless, stake-based governance system, where everyone can participate by staking ICP utility tokens. Decisions are made by voting on proposals in a liquid democracy, meaning that voters can either vote directly or delegate their voting power to other voters.
+The NNS governs all aspects of the Internet Computer, including its tokenomics, the rules of the NNS governance itself, the topology of the node machines, and the software that is run on the node machines. All these decisions are executed fully on-chain, which eliminates the need for trusted third parties.
 
-NNS decision making is done via an open tokenized governance system. The NNS is one of the largest decentralized autonomous organizations (DAOs). Anyone can become a participant of the NNS by staking ICP tokens and contribute to decisions.
 
-[Go deeper](/nns/)
+[Go deeper](/how-it-works/network-nervous-system-nns/)

how-it-works/3_governance/01_network-nervous-system-nns.subpage.md

@@ -5,27 +5,92 @@ shareImage: /img/how-it-works/network-nervous-system.webp
 slug: network-nervous-system-nns
 ---
 
-# Network Nervous System: Internet Computer Blockchain Governance
+# The Network Nervous System (NNS)
 
 [![Watch youtube video](https://i.ytimg.com/vi/hWnsluxmRqc/maxresdefault.jpg)](https://www.youtube.com/watch?v=hWnsluxmRqc)
 
-The Network Nervous System (NNS) is the open algorithmic governance of the Internet Computer blockchain. Its most notable innovations include its ability to upgrade the Internet Computer protocol and software running on node machines, onboard new node providers, add node machines into the blockchain network, and create new subnet blockchains to increase capacity. Anyone can participate in the NNS by staking ICP tokens into one or more neurons. Neurons can submit proposals and decide to adopt or reject them. The NNS implements liquid democracy: neurons can follow other neurons a delegate voting power.
 
+The Network Nervous System (NNS) is the DAO that controls the Internet Computer blockchain.
+It is an open, permissionless governance system, where everyone can participate by staking ICP utility tokens in so-called _neurons_.
+Decisions are made by voting on _proposals_, which can be submitted by anyone.
+
+
+
+
+## Governance participation
+Governance participants are called _neurons_.
+Neurons are created by locking ICP utility tokens for a specified period of time.
+The NNS is a stake-based governance system, where a neuron's voting power is depending on three main factors:
+1) the amount of ICP tokens the neuron stakes
+2) the neuron's _dissolve delay_ which is the duration of the staking period
+3) the neuron's _age_, which on a high level is the time since the tokens have been staked.
+
+
+This incentivises neurons to vote in the long-term interest of the ICP as those neurons who are more committed have more voting power.
+
+
+Governance participation is incentivised by _voting rewards_ to neurons.
+They are proportional to a neuron's voting power and how much voting decisions a neuron participated in.
+
+
+## Proposals
+_Proposals_ are suggestions on how to change the ICP protocol.
+Any neuron can submit a proposal, and all other neurons can then vote on it.
+Neurons can vote with the voting power they have at the time of the proposal's submission.
+
+
+## Liquid democracy
+The NNS implements a form of _liquid democracy_, which means that neurons can either vote directly on proposals, or delegate their voting power to other neurons, called _following_.
+Following is done on the basis of proposal _topics_, i.e. groups of proposals that are similar.
+This facilitates following different experts on different topics.
+The voting delegations can be changed at any point in time.
+
+
+## Voting rules
+Voting on NNS proposals follows an algorithm called _wait-for-quiet_.
+The main idea of wait-for-quiet is that proposals where all voters agree can be executed quickly, while strongly contested proposals have a longer voting period. This allows voters to have enough time to react if a proposal result is turned all of a sudden.
+Currently, most proposals start with an initial voting period of 4 days that can be extended up to a total of 8 days.
+A proposal is adopted if either of the two conditions are met:
+1) the voting period has elapsed, there are more votes in favor than against the proposal (simple majority), and at least 3% of the totally available voting power voted in favor of the proposal (enough participation).
+2) more than 50% of the total voting power are in favor of the proposal. At this point, the proposal's result cannot be changed anymore even if all remaining voters vote against the proposal and therefore the proposal is executed without awaiting the end of the voting period.
+
+
+## Proposal execution
+As soon as a proposal is adopted, it is executed by the NNS. With very few exceptions, proposals are executed automatically and fully on-chain.
+
+
+
+
+## What the NNS governs
+The NNS governs the full Internet Computer blockchain.
+For example, the NNS makes decisions on the following topics.
+* *Network topology*: The NNS decides which node machines can join the network and how these nodes are organized into _subnets_.
+* *Software run on the nodes*: The NNS decides which software is run by the nodes that form the blockchain. This allows the NNS to upgrade the protocol without manual intervention of the individual node operators.
+* *Tokenomics*: The NNS decides how many rewards node operators and governance participants get and the costs of computation and storage on the Internet Computer.
+* *Governance*: The NNS decides on the rules of the governance itself, e.g. how many votes are needed for a proposal to be adopted, how long the voting period is, etc.
+* *Motion*: These proposals allow for opinion polls and are the only proposals that do not have a direct effect. 
+
+
+With the exception of motion proposals, all these decisions are executed fully on-chain and at low cost compared to other chains. Therefore, decisions can be made efficiently and frequently allowing the NNS to adapt the ICP platform to the community's needs.
+
+
+## The Architecture of the NNS
+The NNS is implemented as a set of _canister smart contracts_ on a dedicated _NNS system subnet_.
+Facilitated by the low computation and storage costs on the ICP, and since the NNS subnet is cross-subsidized by other subnets, voting on proposals is free of charge and a high volume of votes and proposals can be processed and stored on-chain.
+
+
+Two important canisters are the _governance canister_ that manages neurons, proposals, and the voting process, and the _ICP ledger canister_ that implements the ICP token which is the NNS governance token.
+In addition, there are other canisters for special purposes, for example the _cycles minting canister (CMC)_ that is responsible to mint _cycles_ - the "gas" used for computation and storage on the ICP.
+
+
+To allow for flexible governance evolution, the NNS canisters are _mutable smart contracts_.
+Two canisters, called _root_ and _lifeline_, are responsible for upgrading the NNS canisters. As NNS canisters control each other, it is ensured that they can only be changed by an NNS DAO decision.
 
-[Network Nervous System front-end dapp](https://nns.ic0.app/)
 
-[NNS GitHub Repo](https://github.com/dfinity/ic/tree/master/rs/nns)
 
-[NNS front-end dapp open source](https://github.com/dfinity/nns-dapp)
 
-[The Network Nervous System: Governing the Internet Computer](https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a)
 
-[Understanding the Internet Computer’s Network Nervous System, Neurons, and ICP Utility Tokens](https://medium.com/dfinity/understanding-the-internet-computers-network-nervous-system-neurons-and-icp-utility-tokens-730dab65cae8)
 
-[Getting Started on the Internet Computer’s Network Nervous System dapp & Wallet](https://medium.com/dfinity/getting-started-on-the-internet-computers-network-nervous-system-app-wallet-61ecf111ea11)
 
-[Community Led Governance of the Internet Computer](https://medium.com/dfinity/the-community-led-governance-of-the-internet-computer-b863cd2975ba)
 
-[Earn Substantial Voting Rewards by Staking in the Network Nervous System](https://medium.com/dfinity/earn-substantial-voting-rewards-by-staking-in-the-network-nervous-system-7eb5cf988182)
 
-[NNS Staking Guide [Beta]](https://dfinity.github.io/ic-staking-documentation/)

how-it-works/3_governance/sns.card.md

@@ -8,7 +8,10 @@ coverImage: /img/how-it-works/network-nervous-system.webp
 
 # Service Nervous System (SNS)
 
-Similarly to how the Internet Computer is controlled by the Network Nervous System, a decentralized application on the IC can be controlled by a community. The Internet Computer’s built-in solution for a DAO (decentralized autonomous organization) that *tokenizes* and *decentralizes* a dapp is called the Service Nervous System (SNS). In the process of creating an SNS, new tokens are minted and swapped. The dapp’s control is handed over to the SNS and everyone who holds SNS tokens can contribute to the decisions on how the dapp evolves going forward.
-This allows distributing the power and ownership of the dapp over a number of parties, thereby eliminating single points of failure and gaining censorship resistance. Moreover, the newly created tokens can be used to create incentives to foster user adoption and participation.
+The Service Nervous System (SNS) framework is the Internet Computer's built-in solution for decentralized autonomous organizations (DAOs) to govern dapps.
+An SNS consists of an open, permissionless governance system and of a built-in governance token that is unique to each SNS.
+The SNS framework includes a process on how to launch a new SNS which includes raising initial funds for the DAO and decentralizing the DAO’s voting power.
+Any dapp can be tokenized and decentralized by handing it over to a new SNS DAO.
 
-[Go deeper](/sns/)
+
+[Go deeper](/how-it-works/sns/)

how-it-works/3_governance/sns.subpage.md

@@ -9,7 +9,81 @@ slug: sns
 
 # Service Nervous System (SNS)
 
-An SNS would derive from the [Network Nervous System (NNS)](/how-it-works/network-nervous-system-nns/) , the autonomous tokenized governance system that controls the Internet Computer blockchain in a completely open, permissionless, and decentralized manner.
+The Service Nervous System (SNS) framework is the Internet Computer's built-in solution for creating and maintaining decentralized autonomous organizations (DAOs) to govern dapps.
+An SNS consists of an open, permissionless governance system governing a dapp, and of a built-in governance token that is unique to each SNS.
+
+
+## SNS DAO
+Generally, for each dapp that is under SNS DAO control, there is one SNS DAO.
+The SNS DAO works very similarly to the [NNS DAO that governs the full ICP](/how-it-works/network-nervous-system-nns/), where DAO participants are called _neurons_ and all neurons can suggest and vote on suggestions how to evolve the dapp that are called _proposals_.
+Each SNS community can choose its own unique tokenomics and governance rules by parameters that can be set for each SNS DAO.
+
+
+### What an SNS governs
+On a high level an SNS DAO governs a dapp, that is decides on the code of that dapp and how it is evolved. On the Internet Computer this can also include the dapp's data and frontend.
+Moreover, the SNS DAO makes decisions on the DAO itself, for example on how to change tokenomics.
+More technically, there are _native proposals_ that are common to all SNSs, such as proposals to upgrade the DAO-controlled dapp canisters, change governance rules, or making transfers from the treasury to open a liquidity pool on a DEX.
+In addition, each SNS can define _custom proposals_ that are specific to the dapp's needs. A proposal can be defined to call any method on any canister. This allows, for example to define proposals that orchestrate upgrades of dapps with many canisters.
+
+
+
+
+### Liquid democracy
+The SNS implements a form of _liquid democracy_, which means that neurons can either vote directly on proposals, or delegate their voting power to other neurons, called _following_.
+In the SNS, following is done on the basis of proposal _types_.
+This facilitates following different experts on different proposals kinds.
+The voting delegations can be changed at any point in time.
+
+
+### Voting rules
+Voting on SNS proposals follows an algorithm called _wait-for-quiet_.
+The main idea of wait-for-quiet is that proposals where all voters agree can be executed quickly, while strongly contested proposals have a longer voting period. This allows voters to have enough time to react if a proposal result is turned all of a sudden.
+Each SNS can decide on the initial and maximal voting period of proposals.
+
+
+For proposal adoption, SNSs distinguish between normal and _critical_ proposals, which include for example treasury transfer proposals.
+Most proposals are adopted if
+1) the voting period has elapsed, there are more votes in favor than against the proposal (simple majority), and at least 3% of the totally available voting power voted in favor of the proposal (enough participation).
+2) more than 50% of the total voting power are in favor of the proposal. At this point, the proposal's result cannot be changed anymore even if all remaining voters vote against the proposal and therefore the proposal is executed without awaiting the end of the voting period.
+
+
+For _critical_ proposals, these rules are more strict and passing a proposal requires two thirds of the votes to be in favor of it and at least 20% of the totally available voting power in favor of the proposal (enough participation).
+
+
+### Proposal execution
+As soon as a proposal is adopted, it is executed by the SNS.
+With very few exceptions, proposals are executed automatically and fully on-chain and thus do not require trusting any third party.
+
+## The Architecture of an SNS
+
+
+### SNS canisters
+Each SNS DAO consists of a set of _canisters smart contracts_ that run _Wasm code_.
+The most central canisters closely resemble the [Network Nervous System](/how-it-works/network-nervous-system-nns/) (NNS) which is the DAO that governs the full ICP.
+The _governance canister_ implements the governance system and the _ledger canister_ implements an SNS specific governance token.
+The _swap canister_ implements the initial decentralization swap that is used during the launch process (see below) to raise initial funds in the form of ICP and swap them for newly minted SNS tokens.
+These canisters, together with a few additional ones, form one SNS DAO that governs one dapp.
+
+
+### SNS canister code
+The SNS DAOs are hosted on the _SNS subnet_.
+
+
+The Wasms run on SNS canister are approved by the [NNS](/how-it-works/network-nervous-system-nns/) and published on an NNS canister called the _SNS wasm modules canister (SNS-W)_.
+If an SNS community decides, by DAO decision, to update the SNS, then the DAO will automatically fetch the new version from SNS-W and update the canisters accordingly.
+This means that all the SNS DAOs run code that is pre-approved by the NNS and they all run the same code (some of the SNS might be a few versions behind).
+The fact that this is built into the platform makes it easy for SNS DAO communities to maintain the code. Moreover, it is easy for users to verify different SNS DAOs as they all run the same, pre-approved code.
+
+
+## SNS Launch process
+The SNS framework includes a process how to launch a new SNS.
+To decentralize a dapp, the dapp is handed over to the Internet Computer together with an NNS proposal defining the details of the SNS launch and the initial configuration of the SNS DAO to be created. The proposal details, for example, the initial token distribution.
+If the NNS community approves this proposal, the following steps are executed fully automatically:
+* The NNS creates a new set of SNS canisters and initializes them as defined in the NNS proposal.
+* The NNS hands over the dapp's control to the newly created SNS.
+* The NNS starts an [_initial decentralization swap_](/sns/faq#what-is-a-decentralization-swap) for the SNS. The purpose of this is to raise initial funds for the DAO and to decentralize the voting power. This is done by an open swap where users can contribute ICP tokens as initial funding and get in return (staked) SNS tokens and thereby a share of the DAO's voting power.
+* If the decentralization swap is successful, the SNS launch was successful and turns into a fully functional DAO.
+
+
 
-* [How the Service Nervous System (SNS) Will Bring Tokenized Governance to On-Chain Dapps | Medium](https://medium.com/dfinity/how-the-service-nervous-system-sns-will-bring-tokenized-governance-to-on-chain-dapps-b74fb8364a5c)