diff --git a/.migration/learn-hub/how-does-icp-work/nns/neuron-attributes.md b/.migration/learn-hub/how-does-icp-work/nns/neuron-attributes.md deleted file mode 100644 index b8e55d6..0000000 --- a/.migration/learn-hub/how-does-icp-work/nns/neuron-attributes.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -learn_hub_id: 34140499557908 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34140499557908-Neuron-Attributes" -learn_hub_title: "Neuron Attributes" -learn_hub_section: "NNS - Network Nervous System " -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Neuron Attributes - -In the Network Nervous System (NNS), a [neuron](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692) is an entity that participates in governance and holds voting power. Let's next look here at the detailed attributes of a neuron by looking at the [`Neuron` record](https://github.com/dfinity/ic/blob/173d06185f77265d97bc363d266ce79410f6b914/rs/nns/governance/canister/governance.did#L363C1-L386C3) in the interface of the [governance canister](https://dashboard.internetcomputer.org/canister/rrkah-fqaaa-aaaaa-aaaaq-cai). - - * `id : opt NeuronId`: A unique ID identifying the neuron. This is a number that is randomly chosen by the governance canister when a neuron is created. - * `account : blob`: The neuron's account on the ICP token ledger, holding the tokens locked in the neuron. This corresponds to a subaccount of the NNS governance canister so that the tokens can only be transferred by dissolving the neuron. - * `controller : opt principal`: The [principal](https://learn.internetcomputer.org/hc/en-us/articles/34250491785108) controlling the neuron. The controller has the permissions to read the neuron and perform any operations on the neuron. - * `hot_keys : vec principal`: A list of principals that have limited permissions on the neuron. This can be used for example to use more accessible but less secure keys for everyday operations. Hotkey principals can read the neuron as well as vote with it, which includes both direct voting and changing following. - * `cached_neuron_stake_e8s : nat64`: The amount of staked ICP tokens, measured in fractions of 10E-8 of an ICP token. - * `neuron_fees_e8s : nat64`: The amount of ICP that this neuron has forfeited due to making proposals that were rejected or from using the functionality to manage other neurons through proposals. This value must be smaller than `neuron_stake_e8s`. When a neuron is disbursed, this amount of ICP is burned. - * `created_timestamp_seconds : nat64`: The timestamp, in seconds from the Unix epoch, when the neuron was created. - * `dissolve_state : opt DissolveState; type DissolveState = variant { DissolveDelaySeconds : nat64; WhenDissolvedTimestampSeconds : nat64; }`: The timer that defines how long the tokens in this neuron are locked for. When the neuron is dissolving, i.e., the timer is running down, this this stores the timestamp at which the neuron becomes dissolved `WhenDissolvedTimestampSeconds`. When the neuron is non-dissolving, `DissolveDelaySeconds` stores how much time, in seconds, is left until the neuron is dissolved when the dissolve timer is turned on again. A neuron is dissolved if `WhenDissolvedTimestampSeconds` is in the past or if `DissolveDelaySeconds` is zero. - * `aging_since_timestamp_seconds : nat64`: The timestamp, in seconds from the Unix epoch, when this neuron last entered the non-dissolving state and has started aging. This value is meaningless when the neuron is dissolving and has age zero. The canonical value of this field for a dissolving neuron is `u64::MAX`. - * `followees : vec record { int32; Followees }; type Followees = record { followees : vec NeuronId }`: The followees of a neuron, that is the group of neurons that this neuron follows. They are expressed as maps from proposal topics (expressed by integers) to a list of followees for this particular topic. - * `recent_ballots : vec BallotInfo`: Information about how this neuron voted in the recent past. - * `maturity_e8s_equivalent : nat64`: The accumulated unstaked maturity of the neuron, in e8s equivalent. - * `staked_maturity_e8s_equivalent : opt nat64`: The accumulated staked maturity of the neuron, in e8s equivalent. Staked maturity becomes unstaked maturity once the neuron is dissolved. - * `auto_stake_maturity : opt bool`: If set and true, the maturity rewarded to this neuron for voting will be automatically staked and will contribute to the neuron's voting power. - * `spawn_at_timestamp_seconds : opt nat64`: This is used for neurons that were created when spawning maturity into a neuron. The value denotes the timestamp, in seconds from the Unix epoch, at which this neuron's maturity is replaced by newly minted ICP. - * `visibility : opt int32`: The visibility defines how much information about this neuron is publicly accessible, i.e., visible to those who are neither the controller nor have hot-key privileges to this neuron. Visibility can be public, private, or undefined. For public neurons, the full neuron is accessible to everyone, for private neurons only subset of the fields is visible, which is encoded in the [`NeuronInfo` record](https://github.com/dfinity/ic/blob/173d06185f77265d97bc363d266ce79410f6b914/rs/nns/governance/canister/governance.did#L408) type, further excluding the fields `recent_ballots` and `joined_community_fund_timestamp_seconds`. - * `voting_power_refreshed_timestamp_seconds` the time when the neuron last performed any of the following actions: direct voting, set following, or confirm following. This field is relevant for the neuron's voting power adjustment. If a neuron does not take any of these actions in more than 6 months (hence the timestamp is more than 6 months in the past from the current time), then the neuron has adjusted voting power. The adjustment has the effect that the neuron will have 0 voting power when this timestamp is 7 month in the past. At this time, the neuron's following choices will also be reset. - * `known_neuron_data : opt KnownNeuronData; message KnownNeuronData { string name = 1; optional string description = 2; `: A neuron can be registered as a **known neuron** via proposal so that it can be followed by others. Known neurons have extra information, a name and optionally a description. - * `joined_community_fund_timestamp_seconds : opt nat64`: Timestamp when this neuron joined the [neurons fund](https://learn.internetcomputer.org/hc/en-us/articles/34084179554196). - * `transfer : opt NeuronStakeTransfer`: The record of the transfer that was made to create this neuron. - * `kyc_verified : bool`: This is a field indicating whether genesis neurons have been KYC verified. `false` if this is a genesis neuron that has not been KYC verified. - * `not_for_profit : bool`: Whether this neuron is "Not for profit", making it dissolvable by voting on a manage neuron proposal. - * `neuron_type : opt int32`: The type of a neuron, identifying seed neurons and Early Contributor Token (ECT) neurons. - - - diff --git a/.migration/learn-hub/how-does-icp-work/nns/neurons-fund-nf.md b/.migration/learn-hub/how-does-icp-work/nns/neurons-fund-nf.md deleted file mode 100644 index 04433d0..0000000 --- a/.migration/learn-hub/how-does-icp-work/nns/neurons-fund-nf.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -learn_hub_id: 34084179554196 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34084179554196-Neurons-Fund-NF" -learn_hub_title: "Neurons' Fund (NF)" -learn_hub_section: "NNS - Network Nervous System " -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Neurons' Fund (NF) - -The Neurons' Fund has been disabled temporarily with the acceptance of [this proposal](https://dashboard.internetcomputer.org/proposal/135970). When it is re-enabled, the design described below might be changed. - -## Background and motivation - -The neurons' fund (NF) is designed to support the development of the [Service Nervous System (SNS) DAO](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564) ecosystem. Any holder of an NNS neuron can decide to participate in the NF, contributing the maturity of their neuron to the fund. Decisions on the allocation of NF resources to decentralization swaps of SNS DAOs are made by the NNS. - -## Neurons' fund components - -The NF comprises four main components that will be discussed in more detail below. - - 1. Joining the NF - 2. NF's participation in decentralization swap - 3. Participation in SNS governance - 4. Maturity increase of NF neurons - - - -### Joining and leaving the NF - -Neurons can join or leave the NF. Users of the [NNS dapp](https://nns.ic0.app/) can do so by using a checkbox. This action can be taken at any time, even during ongoing voting on SNS proposals. Joining the NF means neurons expose their maturity to the risks associated with participating in SNSs. - -### NF participation in decentralization swaps - -SNS DAOs are created through an NNS proposal (refer to [SNS launch](https://learn.internetcomputer.org/hc/en-us/articles/34141180048404) for more background). If a proposal to create an SNS is adopted, the decentralization swap, where initial tokens of the SNS are distributed, starts. - -The extent of the NF's involvement in a specific SNS swap is decided by the Matched Funding scheme. Under this scheme, the NF’s contribution increases in proportion to the direct participation in the swap. This design ensures that the fund's involvement accurately reflects market interest and participation levels. - -At the beginning of the swap, the NF neurons' maturity is reduced proportionally to the maximum possible NF participation (`M`). If the decentralization swap is successful, the NNS mints an amount of `X` ICP as determined by the Matched Funding scheme. - - * The SNS treasury receives `X` ICP. - * The NNS NF treasury receives SNS neurons corresponding to `X` ICP. This is provided as a basket of neurons with various dissolve delays for each participating NF neuron. - * If the participation amount `X` is less than `M`, NF neurons' maturity is increased again to compensate. - - - -If the decentralization swap is not successful, the maturity of NF neurons is increased again by the amount it was decreased by earlier. - -Please note: In the Matched Funding framework, the minimum and maximum funding targets of an SNS swap are refer only to the direct participation. This means that the success of a swap only depends on the level of direct participation, not the contributions from the Neurons’ Fund. - -### Participation in SNS governance - -The SNS neurons created for NF participants are controlled by the NNS. Participation in voting on the SNS proposals is, however, passed through to the NF neurons via hotkeys on the SNS neurons owned by the NNS. This means that NF neurons are owned by NNS but permission is given to the principals that exposed maturity to NF neurons to vote on SNS proposals. - -When the swap is finalized, the hotkeys associated with neurons of NF participants are copied to the SNS neuron that is created for them. This is convenient for NF participants who want to keep their neurons' controller key in cold storage, and want to vote on SNS proposals. These users can add a hotkey to their NNS neuron, and it will automatically be copied to their SNS neuron for new SNSs. - -At most 3 hotkeys are copied. If an NNS neuron has more hotkeys, 3 of them will be chosen, prioritizing self-authenticating principals (i.e. non-canister principals) and favoring principals added earlier. This means that users can influence which hotkeys are selected by removing and then re-adding the hotkeys they don't want to be copied. If the user has hotkeys = [A, B, C, D] (all self-authenticating), and they want [A, B, D] to be copied to the SNS, then they should do something like: - -1\. hotkeys.remove(C) // hotkeys = [A, B, D] -2\. hotkeys.add(C) // hotkeys = [A, B, D, C] - -Now [A, B, D] would be copied. - -The voting power of the SNS neurons is proportional to the amount of maturity exposed. - -### Increasing maturity of NF neurons - -The NNS NF treasury holds SNS neurons & tokens in its treasury, to be dissolved and disbursed at its discretion. When a set of neurons from a decentralization swap of an SNS dissolves, the NNS will determine the value of the dissolved SNS neurons. In the first stage, this will be done by a proposal. In a later stage, this could be done by pulling data from a DEX. - -The maturity of NF neurons whose maturity was reduced when a participation in a SNS-controlled dapp was made is increased by the amount determined by the NNS in the previous step. In the worst case, this amount could also be zero. - -The NNS can liquidate the disbursed SNS tokens at a later point in time. In case the NNS decides to swap the SNS tokens for ICP, the received ICP will be burned. - -## Matched funding - -The _Matched Funding_ scheme, in which the contribution of the Neurons’ Fund to SNS decentralization swaps scales in line with direct participation, allows for a reflection of market signals. - -In a SNS swap, there is a separation of contributions from direct participants and the Neurons’ Fund. In the Matched Funding framework, the minimum and maximum funding targets of an SNS swap refer only to the direct participation. This means that the success of a swap only depends on the level of direct participation, not the contributions from the Neurons’ Fund. - -### The Matching function, _f_ - -The scheme is implemented through a matching function _f_ , where the input represents the amount of direct participation, and the output _f(x)_ denotes the corresponding contribution from the Neurons' Fund (NF). - -The function f is designed to have three distinct phases and will be a continuous function to ensure a smooth transition between these phases. Importantly, the rules for these phases will be globally consistent, applicable to all SNS launches. - - * Initial Lag Phase (I): The function starts at 0, and grows slowly until it reaches a set threshold. This design encourages projects to accumulate enough direct participation before receiving substantial contributions from the NF. - * Growth Phase (II): After crossing the threshold, the NF's contribution increases at a faster rate, signifying more significant support for projects that have demonstrated viability through direct participation. - * Saturation Phase (III): Beyond a certain point, f(x) will level off and will not surpass 10% of the NF's total maturity, which ensures that no single SNS will excessively deplete the NF's resources. - * Bounding Condition: The matching function f(x) is bounded by g(x)=x, meaning that it will never exceed a 1:1 ratio with x. In practical terms, the NF's contribution will always be less than or equal to the amount of direct participation. - - - -These design principles aim to create a fair and sustainable system for allocating NF contributions to various SNS initiatives. - -### Benefits of matched funding - -#### Reflection of market signals - -The matched funding system is designed to closely align with market sentiment. Specifically, a project that successfully raises more direct contributions will correspondingly receive a greater contribution from the Neurons' Fund (NF), up to a predetermined limit. - -#### Simpler decision-making for NF NNS neurons - -The automated adjustment feature in the NF's contributions lessens the decision-making burden on NF NNS neurons. As a result, these neurons have fewer instances where they need to opt out, making the process more efficient. - -#### Improved incentives for projects - -The matching system provides a more compelling incentive structure for projects. Knowing that increased direct funding will be matched (up to a point) by the NF, encourages projects to be more proactive in their fundraising efforts. - -### Detailed specification of the matching function - -#### Cap - -The contribution should be capped by 10% of the NF maturity at proposal execution time and also by a global NF contribution cap being equivalent to 0.75M XDR. In other words we have cap = min (10% of NF maturity, global NF contribution cap). - -The global NF contribution cap is a configurable parameter of the NNS. - -#### Thresholds - -For specifying the shape of the matching function _f_ , we define the following thresholds - - * t_1: Up to this point, a project receives no contribution from the NF. - * t_2: Projects get a 2:1 contribution from the NF. - * t_3: Projects receive a 1:1 contribution from the NF. - * t_4 = 2 * cap: Projects get a 2:1 contribution from the NF. (and afterwards the contribution of the NF remains flat). - - - -The thresholds should be configurable parameters of the NNS. For example, they could become part of the NetworkEconomics record. - -These thresholds are specified in XDR and then converted to ICP thresholds at the execution of the SNS swap proposal using the 30-day average ICP/XDR conversion rate. - - * t_1: 75k XDR - * t_2: 225k XDR - * t_3: 375k XDR - - - -For an interactive tool allowing to explore the functionality of matched funding, please see the SNS [tokenomics analyzer](https://dashboard.internetcomputer.org/sns/tokenomics). - -#### Matching function polynomials - - * f_1: for function values between t_1 and t_2 - * f_2: for function values between t_2 and t_3 - * f_3: for function values between t_3 and t_4. - - - -Formulas for the polynomials can be derived from constraints listed above on the functions f and f’. - -### Clearer separation of contributions - -Feedback from both SNS projects and users on earlier designs has highlighted the need for a clearer separation between contributions from direct participants and those from the NF. This is now realized in two areas: - - 1. Proposal structure: Instead of specifying the overall minimum and maximum funding target, projects have the ability to set distinct minimum and maximum funding targets specifically for direct participation, which is the only factor determining whether the swap succeeds. The contribution from the NF is then added to this base amount, determined by a well-defined model (as per the matching function discussed above). - 2. User transparency in the SNS launchpad: During the swap, contributions from direct participants and the NF are displayed separately for transparency, within the NNS dapp’s SNS launchpad. - - - -### Benefits of the clearer separation - - * Transparency in success metrics: The success of the swap is directly and transparently linked to the amount raised through direct participation. - * More freedom to define funding target range: Projects can set a more flexible range for minimum and maximum funding targets without having to factor in the NF contribution, offering more leeway than in the current system where the NF contribution affects these limit (e.g. because the fixed NF contribution should exceed more than 66% of the minimum funding target). - * User clarity: Users will be able to easily see the amount of direct participation already collected during the swap, as well as the anticipated NF contribution. - - - diff --git a/.migration/learn-hub/how-does-icp-work/nns/neurons.md b/.migration/learn-hub/how-does-icp-work/nns/neurons.md deleted file mode 100644 index f50f7c4..0000000 --- a/.migration/learn-hub/how-does-icp-work/nns/neurons.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -learn_hub_id: 34084120668692 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34084120668692-Neurons" -learn_hub_title: "Neurons" -learn_hub_section: "NNS - Network Nervous System " -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Neurons - -## What is a neuron? - -In order to participate in the network's governance and to receive voting rewards, ICP tokens must first be staked in a _neuron_. Neurons represent governance participants. Each neuron has its own identifier and several attributes. - -Once a neuron is locked for more than six months, it gains the ability both to submit proposals and to vote on them. Voting in turn generates voting rewards, based on how active a neuron is. If a neuron votes on every open proposal, it gains the maximum rewards. - -A neuron can also _follow_ other neurons, which causes it to automatically vote the same way as the majority of the neurons that it follows. In order to keep its voting power and thus keep getting voting rewards, a neuron has to regularly vote directly, set following, or confirm the chosen following settings. - -## Why staking matters - -Staking is a way of allowing those who support the Internet Computer to decide what happens next to the network. - -It is possible for proposals to pass with only a majority among 3% of the total voting power, meaning that proposals stand a chance even if large entities abstain and the majority of the network does not vote. - -## Key concepts - -It is important to understand a few key concepts of a neuron. Every user can stake ICP utility tokens into a neuron and participate in the NNS DAO. - -Each neuron has a _neuron ID_ , which is an identity selected by the NNS when the neuron is created. -In addition, each neuron has an associated _account_ on the ICP ledger where the locked ICP balance resides. This account is owned by the NNS governance canister, and therefore a user cannot move staked tokens. - -### Neuron permissions - -The neuron's _controller_ is a [principal](https://learn.internetcomputer.org/hc/en-us/articles/34250491785108) that controls the neuron and which cannot be changed. A principal corresponds to the public key of a public-private key pair, and anyone with possession of the corresponding private key will have full control of the neuron. Therefore, the private key of the controller principal should be kept very secure. One principal can control multiple neurons. - -### Hotkeys - -In addition to the controller, a neuron can have _hotkeys_. Hotkeys are principals that can perform actions with limited privileges, namely: - - * Voting. - * Set and confirm _following_ (see below). - * Reading the full information about the neuron, including non-public fields. - * Submit a proposal. - - - -Hotkeys cannot perform other neuron operations, such as increase dissolve delay, start dissolving, or disburse a neuron's stake. - -A neuron can have up to 15 hotkeys. One common workflow using hotkeys is to set a hardware wallet as the controller of the neuron, then vote or view neuron information through a software wallet set as a hotkey. - -Hotkeys can be added or removed from a neuron using the [NNS dapp](https://nns.ic0.app/) or the [`quill neuron-manage`](https://internetcomputer.org/docs/current/developer-docs/developer-tools/cli-tools/quill-cli-reference/quill-neuron-manage) command. If your principal is added as a hotkey to a neuron, the neuron and its information will be visible in the NNS dapp when you login. - -### Voting power - -The NNS is a stake-based governance system, so the main factor for how much _voting power_ a neuron has is its stake. In addition, the voting power depends on the following factors. - - * _Dissolve delay_ : The tokens in a neuron are locked for a specified duration called the dissolve delay. This can be thought of as a kitchen timer that can only be turned in one direction. It can be arbitrarily increased, but only reduced by turning on the countdown and waiting for the time to pass. A neuron must have a dissolve delay of at least 6 months to be _eligible_ to vote. - * _Dissolve state:_ A neuron can be in one of three states. - * A neuron can be _non-dissolving_ which means that the timer is stopped and the neuron's dissolve delay remains the same. - * A neuron can be _dissolving_ which means that the timer is decreasing the neuron's dissolve delay as time passes. - * Once the timer has counted down, a neuron is _dissolved_ and the ICP tokens can be unstaked again. This is called _disbursing_ a neuron. - * _Age_ : Every non-dissolving neuron has an age, which denotes how long it has been in the non-dissolving state. - * _Voting Power adjustment due to inactivity_ : In order to keep the voting power, a neuron has to regularly perform any of the following actions: vote directly, set following, or confirm its current following settings. If a neuron fails to do this, its voting power decreases slowly with time until it reaches 0. The voting power adjustment can be lifted at any point by the neuron performing one of the above actions. - - - -The first two factors ensure that a neuron who has tokens locked for longer or has been around for longer has more voting power as it is more committed to the long-term interest of the Internet Computer. The last factor ensures that "sleeper" neurons who do not actively participate in the voting process do not automatically get rewards. - -Based on these factors, a neuron's voting power can be determined: - - * Principally, by its stake. 1 ICP = the power of 1 vote. - * By its dissolve delay. 6 months grants a 1.06x voting power bonus, and 8 years grants 2x. All other durations scale linearly between. - * By its age. 4 years grants a 1.25x bonus, multiplicative with any other bonuses. All other durations between 0 seconds and 4 years scale linearly between. - * By voting power adjustments. A neuron who votes directly, sets following, or confirms following once every 6 months gets normal voting power. After 6 months of no action, a neuron’s voting power is linearly decreased for one month until it reaches zero at the end of 7 months without any action. After these 7 months, the neuron’s following settings are fully reset to zero. - - - -This means that the maximum voting power of 2.5 votes per ICP staked is only achievable by locking up your neuron for 8 years, leaving it in that locked-up state for 4 years, and regularly participating in governance by voting, set following, or confirm following. At that time, you will have the most voting power for the stake committed. - -To better understand how these factors influence a neuron's voting power and rewards over time, you can simulate some behaviors with the [NNS neuron sandbox](https://klgza-cqaaa-aaaak-qcz5a-cai.icp0.io/). Note that this tool assumes that neurons are active and therefore are not subject to voting power adjustments. - -### Maturity - -When neurons vote, directly or through following, the _maturity_ of a neuron increases as it collects voting rewards. -Each day the network rewards participants by allocating to every voting neuron a portion of the total reward, based both on its voting power at the time proposals were made and the number of proposals it voted on. See section Voting rewards & maturity for more details. - -### Neuron visibility - -A neuron can be _public_ or _private_. - -If a neuron is private, only its controller and the hotkeys can read the full neuron. Other parties cannot access all the information about the neuron. In particular, they cannot access the neuron's ballot. As a consequence, other neurons can only delegate their voting power to a private neuron if their controller is the same or if their controller is a hotkey of the delegate. - -If a neuron is public, anyone can read the full neuron. All known neurons are public. There are no restrictions who can delegate voting power to a public neuron. - -Refer to the tutorial [Making neurons public](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-making-neurons-public) to learn how you can change the visibility of your neurons on the NNS dapp. - -## Governance participation - -The main purpose of a neuron is to participate in governance. A neuron with a minimal stake can do so by submitting and voting on a [proposals,](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500) or by participating in governance via the liquid democracy _following_ mechanism. - -### Voting - -A neuron is eligible to vote if it has at least 6 months dissolve delay. An eligible neuron can _vote_ on a proposal by choosing to adopt or reject it. This is called _direct voting_ as a neuron can also delegate voting (see next paragraph). - -As stated above a neuron's eligibility and voting power is dependent on its state and computed at proposal submission time. For more details on how these votes are processed in terms of ballots, refer to[ NNS proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500). - -To learn how you can vote directly, refer to [Voting on proposals](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-voting-on-proposals). - -### Vote delegation / Following - -Users may not have the time or knowledge to participate in all voting decisions. Therefore, instead of directly voting on proposals, neuron holders may choose to _delegate_ their vote to other neurons that they trust with certain decisions. This concept, where a neuron follows the decisions of some other neurons, is called _following_ in the NNS DAO. Collective decision making which combines the direct execution with dynamic delegation mechanisms for voting rights is called _[liquid democracy](https://en.wikipedia.org/wiki/Liquid_democracy)._ - -_For an explanation video regarding how following works and more information how following can be set on the NNS dapp, refer to[configuring neuron following](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons)._ - -#### Periodic confirmation - -A neuron that never votes directly needs to either set or confirm its following decisions regularly (once every 6 months) in order to keep it voting power and keep getting rewards. This _periodic confirmation_ encourages governance participants to regularly review their following choices. - -For additional information on how to confirm following on the NNS dapp, refer to [Periodic neuron following confirmation](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-confirm-following). - -#### Following rules - -A neuron can be configured to vote automatically by following the voting decision made by a group of other neurons, called _followees_. Proposals are grouped into different [proposal topics ](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068)and following is done on a per-topic basis. - -A neuron can follow any public neuron. A neuron can only follow a private neuron if it has the same controller or if its controller is a hotkey of the neuron to follow. - -Each neuron can follow at most 15 other neurons for each proposal topic. A neuron will only cast a "Yes"-vote if _more than half_ of the neurons within the followee-group voted Yes. A neuron will only cast a "No"-vote if _at least half_ of the neurons within the followee-group voted No. - -Your neuron will cast a vote when there are enough followee votes to make a decision whether it is a ADOPT or REJECT. For example, if you follow 10 neurons on a topic: -\- Your neuron only votes to adopt if at least 6 out of the 10 neurons vote to adopt. -\- Your neuron only votes to reject a proposal if at least 5 out of the 10 reject the proposal. -\- If less than 5 neurons (out of your 10 followed) vote at all, your neuron will not cast any vote. - - -This should be considered when choosing to follow multiple neurons on a topic. It might be better to follow fewer neurons, and it can be more beneficial to follow an odd number of neurons than an even number. - -#### Following "catch-all" - -In addition to setting following for individual topics, neurons may also define a catch-all follow rule which is triggered for proposals with topics for which no other explicit follow rule has been defined. -However, the catch-all follow rule does not include the proposal topics _SNS & neurons' fund_ and _Governance_. - -The catch-all follow rule is only applied for proposal topics with no other explicit choice. For example, let us assume neuron A follows neuron B for the catch-all and neuron C on the topic subnet management. If B votes on a subnet management proposal but C does not, no vote will be cast for A. -The catch-all follow rule does not apply for SNS & neurons' fund or governance proposals. For example, if neuron A follows neuron B for the catch-all and B votes on a governance proposal, no vote will be cast for A. If neuron A intends to also follow B on such decisions, the user has to explicitly choose to also follow B on the governance topic. - -It is in each neuron's interest to follow other neurons that support the best interests of the network and their own economic interests. - -## Known neurons - -In order for neurons to find which other neurons they could delegate their vote to, the NNS has a notion of _known neurons._ This is a list of neurons that can be used as a basis for finding candidates. - -Using a [proposal](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068#h_01JJ2H93WHRBTDDFYPBVKTBHN2), any neuron can apply to register as a known neuron. If the NNS community approves the proposal, the neuron is added with a name in the list of known neurons. Optionally, the known neuron can also have the following self-declared information: - - * A description, for example what person or group is controlling the neuron, what their background is, and how they intend to vote. - * A list of links, for example to socials where voters can find more information. - * A list of proposal topics that the neuron commits to voting on. - - - -In addition to this self-declared information, the governance stores the past ballots of known neurons so that voters can consider their past behavior when they decide who to delegate their voting power to. - -_One place to find a list of all known neurons is on the[ICP Dashboard](https://dashboard.internetcomputer.org/neurons?s=100&type=known)._ - -_Interested parties who want to register a know neuron, update an existing known neuron, or propose to de-register a known neurons can find more information on the[developer documentation about Known Neurons](https://internetcomputer.org/docs/building-apps/governing-apps/nns/concepts/neurons/becoming-a-known-neuron)._ - -## Voting rewards & maturity - -In addition to influencing the future of the Internet Computer, the main incentive for stakeholders to stake their ICP tokens in a neuron and participate in voting is that they get _voting rewards_ by doing so. Voting rewards are collected by neurons in the form of _maturity_. - -Maturity is an attribute of a neuron; it is not a tradable asset. The decentralized governance of the Internet Computer can change the treatment of maturity at any time. To generate income from maturity, a user needs to trigger a non-deterministic process, which is burning maturity to create new ICP via disbursing the maturity (or spawning a neuron). The maturity modulation function introduces uncertainty in the creation of tokens from maturity. - -### What you can do with maturity - -Maturity can either be _disbursed_ (replacing the old functionality of _spawning)_ or it can be staked, meaning compounded to increase the neuron's total voting power. A user can also choose to _auto-stake_ the maturity. - -#### Disbursing maturity via the maturity modulation function - -Maturity can be liquidated by _disbursing maturity_. This is a process that can be started at any time and will then take seven days. In the end, a maturity modulation is applied, and new ICP tokens are minted that can be freely used. Maturity can be disbursed to any ledger account. If no account is specified, the caller's account will be used. -For more information on how to disburse maturity, refer to [How to disburse maturity](https://learn.internetcomputer.org/hc/en-us/articles/39755298701204). - -#### Spawning maturity via the maturity modulation function - -It is recommended to use disburse maturity instead of spawn maturity. While spawning is currently still supported by the NNS governance, it was replaced with disburse maturity and might be deprecated going forward. - -When a user chooses to spawn maturity, a new neuron will be immediately spawned. However, this newly spawned neuron will have no ICP at start, only maturity. Spawned neurons will have a dissolve delay of 7 days and will be set to dissolving at the time of spawning. After 7 days when the neuron is dissolved, the amount of ICP, modulated by the function introduced below, will be minted from the neuron's maturity and be available to the user. - -For more information on how to spawn maturity, refer to [How to disburse maturity](https://learn.internetcomputer.org/hc/en-us/articles/39755298701204). - -#### Staking maturity - -Maturity can be staked into _staked maturity_ of the neuron. Staked maturity is viewed as part of the neuron's stake and contributes to the neuron's voting power. But, similarly to the neuron's stake, it is also locked until the neuron is dissolved. When a neuron dissolves, its staked maturity is converted back to normal un-staked maturity (which is then subject to the maturity modulation). - -For more information on how to stake maturity, refer to [How to stake and auto-stake maturity](https://learn.internetcomputer.org/hc/en-us/articles/39755363912724). - -#### Auto-staking maturity - -Maturity can be _auto-staked_. In order to not have to regularly perform the previous action, a neuron can also choose to auto-stake its maturity. This means that all new maturity will automatically be added to the staked maturity. - -For more information on how to stake maturity, refer to [How to stake and auto-stake maturity](https://learn.internetcomputer.org/hc/en-us/articles/39755363912724). - -### Maturity modulation - -As mentioned above, to generate income from maturity, a user needs to trigger a non-deterministic process, which is burning maturity to create new ICP via disbursing the maturity. The _maturity modulation function_ introduces uncertainty in the creation of ICP from maturity. - -At the day of modulation, for each of the last 29 days, a 30-day moving average ICP/cycles conversion rate is determined, which is displayed on the Internet Computer dashboard. These are labeled `a1` through `a29`, where `a1` denotes the average rate on the previous day, `a2` denotes the rate 2 days ago and so on. The 30-day moving average conversion rates are used because they exhibit less variance than day-to-day conversion rates. - -Then, compute the relative 7-day return for each of the last 4 weeks. Thus: - - * ` w1 = (a1 - a8) / a8`, - * ` w2 = (a8 - a15) / a15`, - * ` w3 = (a15 - a22) / a22`, - * ` w4 = (a22 - a29) / a29`. - * The values w1, w2, w3, and w4 are bounded from -0.05 to 0.05 by clipping values to the limits of this range, i.e., capping by 0.05 and flooring by -0.05. - * Take the average `w = (w1 + w2 + w3 + w4) / 4`. - * The resulting value w is a number between -5% and 5% that determines modulation. - * The maturity amount x is converted to x * (1+w) units of ICP. - - - -The maturity modulation function is updated once a day. - -#### Example - -On Feb 1, 2022, the modulation function is 0.73% which is the average of the relative weekly returns w1 = -4.59%, w2 =-0.63%, w3=5.00%, w4 = 3.13%. If a user disburses on that day (day of transfer) 100 maturity, then this will result in 100.73 ICP. - -#### Motivation and analysis - -Evidently, this process introduces a certain amount of uncertainty for the conversion from maturity to ICP. However this uncertainty is limited in two ways: - - * The modulation value w is between -5% and +5%: This implies that, e.g., 100 maturity will be converted into an ICP amount in the range of 95 and 105. This kind of volatility is well in the range of daily conversion rate fluctuations of ICP. - * The modulation value w is calculated at the day of modulation as `w = (w1+ w2+ w3 + w4) / 4`. At the day of initiation (7 days prior), the user can already determine `(w2+ w3 + w4)/4`. The missing value w1 can affect the modulation value at most by 1.25% (5%/4) up or down. - - - -The modulation value can change by at most 2.5% from one week to the next, as one week drops out of the window and one week enters the calculation window. - -The modulation function gives an incentive for users to disburse maturity when the ICP/Cycles conversion rate has been increasing over time and to hold back when the ICP has been decreasing recently. For example if the ICP/Cycles conversion rate was monotonically increasing, then w1, w2, w3, w4 are positive and thus also w, incentivizing users to convert a maturity amount x to x * (1+w) units of ICP. - diff --git a/.migration/learn-hub/how-does-icp-work/nns/overview.md b/.migration/learn-hub/how-does-icp-work/nns/overview.md deleted file mode 100644 index d7c2245..0000000 --- a/.migration/learn-hub/how-does-icp-work/nns/overview.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -learn_hub_id: 33692645961236 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33692645961236-Overview" -learn_hub_title: "Overview" -learn_hub_section: "NNS - Network Nervous System " -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Overview - -The Network Nervous System (NNS) is the fully onchain decentralized autonomous organization (DAO) that governs the Internet Computer Protocol. It is a stake-based, open governance system where everyone can participate by staking ICP utility tokens. The NNS is implemented by a set of [canister](https://learn.internetcomputer.org/hc/en-us/articles/34210839162004) smart contracts. - -## The need for the NNS - -The Internet Computer is powered by independent nodes that run the Internet Computer protocol. For efficiency, these nodes are organized into different sub-groups, called subnets. To ensure that the Internet Computer can evolve in terms of security, performance, and scale, decisions such as the following need to be made: - - * Upgrading the protocol and guest operating system software used by the nodes, to extend functionality, improve security or performance. - * Adding new nodes by new node providers to the network for more robustness. - * Creating new subnets to scale the Internet Computer's capacity. - * Splitting subnets to balance network load. - - - -The NNS ensures that all these decisions can be made in a decentralized and autonomous way. - -## Neurons - -On the Internet Computer, governance participants are called _neurons_. Neurons correspond to staked ICP tokens. In other words, anyone can become a part of the NNS governance by locking ICP tokens in a neuron. This is incentivized by voting rewards for neurons who participate in decision making. - -Learn how to stake tokens in a neuron by following this [staking tutorial](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-staking-a-neuron). For more background information on neurons and voting rewards, read the article on [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692). - -## Proposals - -Proposals are suggestion on how to evolve the Internet Computer. This includes decisions updating the protocol, organizing node machines into subnets, and updating the rules of the NNS DAO itself. Any neuron that has tokens staked for at least 6 months can submit and vote on proposals. - -On a high level, a proposal goes through the following lifecycle (ignoring some special cases): - - 1. **Proposal submission** : A neuron submits a proposal with a new suggestion to make a change to the network. - 2. **Establish ballot roll** : The governance canister takes a snapshot and creates (empty) ballots for all eligible neurons. - 3. **Voting** : All eligible neurons can cast their vote. This can either be done by a manual vote or by _following_ , which is a mechanism for delegating the voting power to another neuron. - 4. **Proposal decision** : The proposal is decided based on either: - * **Absolute Majority** \- At any point, even before the voting period ends, if an absolute majority (more than half of the total voting power) has voted "yes," then the proposal is adopted. If an absolute majority has voted "no," then the proposal is rejected. - * **Simple Majority** \- When the voting period ends, if a simple majority (more than half of the cast votes) has voted "yes" and the number of these yes votes constitutes at least 3% of the total voting power, then the proposal is adopted. Otherwise, the proposal is rejected. - 5. **Proposal execution** : If a proposal is adopted, the NNS DAO automatically and autonomously executes the proposals. For example, if the proposal decided to update the voting rules, an upgrade of the canister which implements these rules would be initiated automatically. Compared to other DAOs, this has the advantage that no human action is needed for proposal execution, removing a source of failure and inefficiency. - - - -For a tutorial on how to vote on a proposal, read [Voting on proposals.](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-voting-on-proposals) For a tutorial on how to set or change following, refer to [Following](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons). For more detailed information about proposals, including details of the lifecycle, how to submit proposals, and the precise type of proposals, refer to [Proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500). For more information about voting, the rules of following, and how to verify proposals, refer to [Voting](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-voting-on-proposals). - diff --git a/.migration/learn-hub/how-does-icp-work/nns/proposal-topics-and-types.md b/.migration/learn-hub/how-does-icp-work/nns/proposal-topics-and-types.md deleted file mode 100644 index 62a66d6..0000000 --- a/.migration/learn-hub/how-does-icp-work/nns/proposal-topics-and-types.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -learn_hub_id: 34140518658068 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34140518658068-Proposal-Topics-and-Types" -learn_hub_title: "Proposal Topics and Types" -learn_hub_section: "NNS - Network Nervous System " -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Proposal Topics and Types - -In the Network Nervous System (NNS), governance is performed by means of [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500) that are voted on and execute automatically upon being adopted. Each proposal has a _proposal type_ , which determines the action taken when the proposal is adopted or rejected. Each type of proposal belongs to a specific _proposal topic_. The following list contains all present proposals types grouped by their topics. For more information on what to consider when verifying the different kinds of proposals, please refer to the [tutorial on verifying proposals](https://internetcomputer.org/docs/current/developer-docs/daos/nns/concepts/proposals/verify-proposals). - -## Topic `ProtocolCanisterManagement` - -This topic covers proposals for managing the canisters which are essential to the Internet Computer Protocol's operation. This includes the canisters comprising the NNS DAO, such as [NNS governance](https://dashboard.internetcomputer.org/canister/rrkah-fqaaa-aaaaa-aaaaq-cai), [NNS root](https://dashboard.internetcomputer.org/canister/r7inp-6aaaa-aaaaa-aaabq-cai), the [registry canister](https://dashboard.internetcomputer.org/canister/rwlgt-iiaaa-aaaaa-aaaaa-cai), and the [ICP ledger](https://dashboard.internetcomputer.org/canister/ryjl3-tyaaa-aaaaa-aaaba-cai) canister. - - * `InstallCode`: Install, reinstall, or upgrade the code of a canister that is controlled by the NNS. - * `UpdateCanisterSettings`: Update the settings of a canister that is controlled by the NNS. - * `StopOrStartCanister`: Stop or start a canister that is controlled by the NNS. - * `HardResetNnsRootToVersion`: Uninstall and install the root canister with the Wasm provided in the function. If `InitArgs` are provided, they will be passed to the `canister_init` function of the Wasm provided. This function is meant as a 'break glass' mechanism for when an open call context in the root canister is preventing root or another canister from upgrading. - - - -## Topic `ServiceNervousSystemManagement` - -This topic covers proposals to manage the canisters of [service nervous systems (SNS)](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564), including upgrading relevant canisters and managing SNS framework canister Web Assembly code modules through SNS-W. - - * `InstallCode`, `UpdateCanisterSettings`, and `StopOrStartCanister` are the same as in topic `ProtocolCanisterManagement`, only targeting different canisters. - * `AddSnsWasm`: Add a new SNS canister Wasm to SNS-W. All SNS DAOs can then upgrade to new versions along the upgrade path. - * `InsertSnsWasmUpgradePathEntries`: Insert custom upgrade path entries into SNS-W for all SNSes, or for an SNS specified by its governance canister ID. - - - -## Topic `ApplicationCanisterManagement` - -This topic covers proposals to manage NNS-controlled canisters not covered by the above topics. - - * `InstallCode`, `UpdateCanisterSettings`, and `StopOrStartCanister` are the same as in topics `ProtocolCanisterManagement` and `ServiceNervousSystemManagement` only targeting different canisters. - * `BitcoinSetConfig`: A proposal to set the configuration of the Bitcoin canister that underlies the Bitcoin API. The configuration includes the amount of fees to charge, whether or not the Bitcoin canister should sync new blocks from the network, whether the API is enabled, etc. - - - -## Topic `IcOsVersionElection` - -To upgrade the ICP protocol, the NNS DAO first elects new IC OS versions (the software that is run by ICP nodes). In a second step, selected nodes can be upgraded to the previously elected IC OS versions. This proposal type is for the first part, i.e., to elect new versions. - -HostOS is the hypervisor OS running on the IC node machine. Its main responsibilities include initializing and configuring the node machine hardware and passing functionality through to the GuestOS. The GuestOS, a VM running on the HostOS, contains the critical parts of the IC Protocol code, including the IC Replica, which runs the IC Canisters smart contracts. - -This topic contains the following proposal types: - - * `ReviseElectedGuestosVersions`: A proposal to change the set of elected GuestOS versions. The version to elect is added to the registry, identified by the Git revision of the installation image, along with the URLs of the upgrade image and the SHA-256 checksum of the image. Besides creating a record for that version to the registry, the proposal also appends that version to the list of elected versions that can be installed on nodes of a subnet. Only elected GuestOS versions can be deployed. - * `ReviseElectedHostosVersions`: A proposal to change the set of currently elected HostOS versions by electing a new version, and/or un-electing some previously elected versions. HostOS versions are identified by the hash of the installation image. The version to elect is added to the registry, and the versions to un-elect are removed from the registry, ensuring that HostOS cannot upgrade to these versions anymore. - - - -## Topic `IcOsVersionDeployment` - -This proposal is used to upgrade selected nodes to IC OS versions that have previously been approved ("elected") by the NNS DAO under the `IcOsVersionElection` topic. - -This topic includes the following proposal types: - - * `DeployHostosToSomeNodes`: Deploy a HostOS version to a specified set of nodes, changing the HostOS version used on those nodes. - * `DeployGuestosToAllSubnetNodes`: Deploy a GuestOS version to a specified subnet, changing the GuestOS version used on that subnet. The version must be in the list of elected GuestOS versions. The upgrade is complete when the subnet nodes create the next regular CUP, and then all subnet nodes restart and load the CUP with the new code. - * `DeployGuestosToSomeApiBoundaryNodes`: Update the GuestOS version on a set of API Boundary Nodes. - * `DeployGuestosToAllUnassignedNodes`: Update the GuestOS version on all unassigned nodes. - - - -## Topic `Governance` - -This topic covers proposals for governing the Internet Computer. In contrast to most other topics, which have reward weight 1, governance proposals have reward weight 20. This means that participation in this topic is rewarded more. - -This topic includes the following proposal types: - - * `Motion`: Motion proposals are the only proposals that don't have a direct onchain effect. Rather they can be used as polls that should guide the future strategy of the ICP ecosystem. - * `UninstallCode`: Uninstall code of a canister. - * `SetDefaultFollowees`: Sets default following. Newly created NNS neurons will be created with this default choice of followers for the topics. - * `KnownNeuron`: This proposal registers a [known neuron](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JN0SR92VPHVFPYXWAHKF3BYP) or, if a known neuron with this ID and name is already registered, it updates the known neuron. A known neuron has the following attributes. - * `string name`: a name that identifies the know neuron. - * `optional string description`: a description, for example what person or group is controlling the neuron, what their background is, and how they intend to vote. - * `repeated string links`: a list of links, for example to socials where voters can find more information. - * `repeated Topic committed_topics`: a list of proposal topics that the neuron commits to voting on. - * `DeregisterKnownNeuron`: This proposal de-registers a known neuron. That is it removes the neuron with the given neuron ID from the list of [known neurons.](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JN0SR92VPHVFPYXWAHKF3BYP) - - - -## Topic `SnsAndCommunityFund` - -This topic includes proposals that concern SNS decentralization swaps and the Neurons' Fund (formerly called Community Fund). In contrast to most other topics, this topic has reward weight 20. This means that participation in this topic is rewarded more. - -This topic currently only includes one proposal type: - - * `CreateServiceNervousSystem`: This proposal installs a set of canisters for a new SNS DAO and specifies all settings, including the initial token distribution, the conditions for the initial decentralization swap, the initial SNS DAO parameters, as well as the Neurons' Fund contribution. - - - -## Topic `NetworkEconomics` - -This topic includes proposals concerning network economics. This topic contains the following proposal types: - - * `UpdateNodeRewardsTable`: Update the node rewards table. This table is the basis for distributing rewards to node providers according to some rules, depending on where they are. You can find more information and the current reward table on [this Wiki page](https://wiki.internetcomputer.org/wiki/Node_Provider_Remuneration). - * `NetworkEconomics`: Network economics contains the parameters for several operations related to the economy of the network and settings of the NNS DAO that can be changed by a proposal of this type. -A single proposal can update one or several economic parameters. The default values (0) are considered unchanged. Thus, a valid proposal only needs to set the parameters that it wishes to change. Note that this also means that it is not possible to set any of the values to 0. -The following parameters can be changed: - * **Reject cost** : The amount of ICP the proposer of a rejected proposal will be charged to prevent the spamming of frivolous proposals. - * **Minimum neuron stake** : Set the minimum number of ICP required for the creation of a neuron. The same limit must also be respected when increasing the dissolve delay or changing the neuron state from dissolving to aging. - * **Neuron management fee** : The cost in ICP per neuron management proposal. Here the NNS is doing work on behalf of a specific neuron, and a small fee will be applied to prevent overuse of this feature (i.e., spam). - * **Minimum ICP/XDR rate** : To prevent mistakes, there is a lower bound for the ICP/XDR rate, managed by network economic proposals. - * **Dissolve delay of spawned neurons** : The dissolve delay of a neuron spawned from the maturity of an existing neuron. - * **Maximum node provider rewards** : The maximum rewards to be distributed to node providers in a single distribution event (proposal). - * **Transaction fee** : The transaction fee that must be paid for each ledger transaction. - * **Maximum number of proposals to keep per topic** : The maximum number of proposals to keep, per topic. When the total number of proposals for a given topic is greater than this number, the oldest proposals that have reached a “final” state may be deleted to save space - * **Neurons' Fund economics** : This includes all parameters related to the [Neurons' Fund](https://learn.internetcomputer.org/hc/en-us/articles/34084179554196): - * `max_theoretical_neurons_fund_participation_amount_xdr`: A theoretical limit which should be smaller than any realistic amount of maturity that practically needs to be reserved from the Neurons' Fund for a given SNS swap. - * `neurons_fund_matched_funding_curve_coefficients`: Defines a threshold specifying the shape of the matching function used by the Neurons' Fund to determine how much to contribute for a given direct participation amount. - * `minimum_icp_xdr_rate` and `maximum_icp_xdr_rate` are respectively the minimum and maximum value of the ICP/XDR conversion rate used by the Neurons' Fund for converting XDR values into ICP. - * **Voting Power economics** : This includes all parameters that affect the voting power of neurons. - * `start_reducing_voting_power_after_seconds`: A neuron has to regularly take any of the three actions: vote directly, set vote delegations, [confirm the vote delegations.](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JJ2G9K5P709E5TQDRKTT3ZTP) If the neurons hasn't done so for a period of time, its deciding voting power starts decreasing linearly. This number decides after which period of time this is the case. - * `clear_following_after_seconds`: A neuron has to regularly take any of the three actions: vote directly, set vote delegations, [confirm the vote delegations.](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JJ2G9K5P709E5TQDRKTT3ZTP) If the neurons hasn't done so for a period of time, its deciding voting power starts decreasing linearly (see last parameter) until it reaches zero. At this time, all voting delegations ("following") are removed. This parameter defines after which period of not taking the necessary actions this point is reached where following is removed. - * `neuron_minimum_dissolve_delay_to_vote_seconds`: The minimum dissolve delay a neuron must have in order to be eligible to vote. Neurons with a dissolve delay lower than this threshold are not eligible to vote on proposals, even if they are otherwise active. - * `ClearProvisionalWhitelist`: Clears the provisional whitelist, which allows the listed principals to create canisters with cycles. The mechanism is only needed for bootstrapping and testing and must be deactivated afterward. - - - -## Topic `SubnetManagement` - -All proposals that change the network's subnet topology and configuration. - -The following proposal types relate to the creation and composition of subnets: - - * `CreateSubnet`: Combine a specified set of nodes, typically drawn from data centers and operators in such a way as to guarantee their independence, into a new subnet. The execution of this proposal first initiates a new instance of the distributed key generation protocol. -The transcript of that protocol is written to a new subnet record in the registry, together with the initial configuration information for the subnet, from where the nodes comprising the subnet pick it up. - * `UpdateConfigOfSubnet`: Update a subnet's configuration. This proposal updates the subnet record in the registry, with the changes being picked up by the nodes on the subnet when they reference the respective registry version. Subnet configuration comprises protocol parameters that must be consistent across the subnet (e.g. message sizes). - * `AddNodeToSubnet`: Add a new node to a subnet. The node cannot be currently assigned to a subnet. The execution of this proposal changes an existing subnet record to add a node. From the perspective of the NNS, this update is a simple update of the subnet record in the registry. - * `RemoveNodesFromSubnet`: Remove a node from a subnet. It then becomes available for reassignment. The execution of this proposal changes an existing subnet record to remove a node. From the perspective of the NNS, this update is a simple update of the subnet record in the registry. - * `ChangeSubnetMembership`: Change the subnet node membership. This function combines the functions for adding and removing nodes from the subnet record into one, adding the property of atomic node replacement (node swap) on top. The nodes that are being added to the subnet must be currently unassigned. The nodes that are being removed from the subnet must be currently assigned to the subnet. - * `RecoverSubnet`: Update a subnet’s recovery CUP used to recover subnets that have stalled. Nodes that find a recovery CUP for their subnet will load that CUP from the registry and restart the replica from that CUP. - - - -The following proposal types relate to firewall rules: - - * `SetFirewallConfig:` Change the firewall configuration in the registry and define which boundary nodes the subnet replicas will communicate with. - * `AddFirewallRules`: Add firewall rules in the registry. - * `RemoveFirewallRules`: Remove firewall rules in the registry. - * `UpdateFirewallRules`: Update firewall rules in the registry. - - - -The following proposal types define which principals can create canisters on which subnets, managed by the cycles minting canister: - - * `SetAuthorizedSubnetworks`: Informs the cycles minting canister that a certain principal is authorized to use certain subnetworks (from a list). Can also be used to set the “default” list of subnetworks that principals without special authorization are allowed to use. - * `UpdateSubnetType`: Updates the available subnet types in the cycles minting canister. - * `ChangeSubnetTypeAssignment`: Changes the assignment of subnets to subnet types in the cycles minting canister. - * `UpdateSnsWasmSnsSubnetIds`: Update the list of SNS subnet IDs that SNS Wasm will deploy SNS instances to. - - - -The following proposal types are used for canister migration, e.g., if it is ever needed to split a subnet: - - * `RerouteCanisterRanges`: Update the routing table in the registry which defines the range of canister IDs that are on which subnet. - * `PrepareCanisterMigration`: Insert or update `canister_migrations` entries. This is used during a subnet migration of canisters (e.g., when a subnet needs to be split). - * `CompleteCanisterMigration`: Remove `canister_migrations` entries. This is used during a subnet migration of canisters (e.g., when a subnet needs to be split). - - - -## -Topic `ParticipantManagement` - -All proposals that administer network participants, notably data center and node provider identities. This topic contains the following proposal types: - - * `AddOrRemoveDataCenters`: Add or remove data center records in the registry. - * `AddOrRemoveNodeProvider`: Assign or revoke an identity to a node provider and any associated key information regarding the legal person that should provide a way to uniquely identify it. - - - -## Topic `NodeAdmin` - -Proposals that administer node machines. This topic contains the following proposal types: - - * `AssignNoid`: Assign an identity to a node operator, such as a funding partner, associating key information regarding its ownership, the jurisdiction in which it is located, and other information. The node operator is stored as a record in the registry. It contains the remaining node allowance for that node operator, that is the number of nodes the node operator can still add to the ICP. When an additional node is added by the node operator, the remaining allowance is decreased. - * `UpdateNodeOperatorConfig`: Change a node operator’s allowance in the registry. - * `RemoveNodeOperators`: Remove a Node Operator from the registry. - * `RemoveNodes`: Remove unassigned nodes from the registry. - * `UpdateSshReadonlyAccessForAllUnassignedNodes`: A proposal to update SSH readonly access for all unassigned nodes. - - - -## Topic `KYC` - -This topic only includes the following type concerned with KYCing Genesis neurons: - - * `ApproveGenesisKYC`: When new neurons were created at Genesis, their KYC value was set to `GenesisKYC=false`. This restricts what actions they can perform. Specifically, they cannot spawn new neurons, and once their dissolve delays are zero, they cannot be disbursed and their balances unlocked to new accounts. This proposal sets `GenesisKYC=true` for batches of principals. - - - -The Genesis event disburses all ICP in the form of neurons, whose principals must be KYCed. Consequently, all neurons created after Genesis have `GenesisKYC=true` set automatically since they must have been derived from balances that have already been KYCed. - - - -## Topic `NeuronManagement` (restricted voting) - -A special topic that can be used for multiple users to collectively manage a neuron. Specifically, a neuron can be managed by the followees for this topic. - -In a few aspects, `NeuronManagement` proposals behave differently than other proposals: - - * Only the neuron’s followers on this topic are allowed to vote (and thus have a ballot). - * The [restrictions which private neurons can be followed](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#01JY3Q496PCW6VVT0R6XXST12S) do not apply to this topic. - * Because the set of eligible voters for proposals on this topic is restricted, proposals on this topic have a shorter than normal voting period. - - - -This topic only includes one proposal type: - - * `ManageNeuron`: The proposal calls a command on a specified target neuron. Only the followers of the target neuron may vote on these proposals. - - - diff --git a/.migration/learn-hub/how-does-icp-work/nns/proposals.md b/.migration/learn-hub/how-does-icp-work/nns/proposals.md deleted file mode 100644 index dbb715f..0000000 --- a/.migration/learn-hub/how-does-icp-work/nns/proposals.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -learn_hub_id: 34084113508500 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34084113508500-Proposals" -learn_hub_title: "Proposals" -learn_hub_section: "NNS - Network Nervous System " -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Proposals - -## What is a proposal? - -A proposal is a suggestion to evolve and update the Internet Computer protocol. NNS DAO participants can submit proposals, make suggestions on how the ICP should evolve, and vote on proposals that others have submitted. - -Based on the majority decision, a proposal is either adopted or rejected. If a proposal is adopted, it is automatically executed fully onchain, without the need for manual intervention. - -While other blockchains take weeks or months to upgrade and typically require substantial manual work and coordination to do so, ICP upgrades itself every week (as can be seen on [the dashboard](https://dashboard.internetcomputer.org/releases)). Its ability to upgrade and iterate is a comparative "superpower". - -## Proposal lifecycle - -A proposal lifecycle starts when it is submitted by a [neuron](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692), which is a governance participant. Then, other governance participants form a decision and vote on the proposal. Based on these votes, the governance derives a proposal decision, i.e., the proposal is either adopted or rejected. - -If the proposal is rejected, usually nothing happens. If the proposal is adopted, the agreed upon decision is automatically executed by the governance canister. - -### Proposal submission - -Any eligible neuron can make and submit a proposal. To avoid being inundated by useless proposals, a user submitting a proposal has to pay a fee of 25 ICP when submitting a proposal that they will receive back if the proposal is adopted, but not if the proposal is rejected. - -After a proposal is submitted, the proposal is created and stored in governance. The governance computes and stores additional information with each proposal. - -Then, the governance looks at all neurons, i.e. governance participants, and creates an empty ballot for each eligible neuron that has a dissolve delay of at least 6 months, storing the neuron's voting power in this moment. This means that at the time of the proposal's submission, a neuron snapshot is taken and all neurons can vote on the proposal with the voting power that they have at that moment. - -This results in the following, potentially unintuitive cases: -\- If a neuron is created after a proposal was submitted, it is not eligible to vote on this proposal. -\- If a neuron had a dissolve delay of less than 6 months when a proposal was submitted, it cannot vote on the proposal, even if the neuron's dissolve delay is increased again. -\- If a neuron had a dissolve delay of 6 months when a proposal was submitted, it can vote on the proposal during the full voting period, even if by the time of voting the neuron's dissolve delay decreased slightly below 6 months. - -The sum of all of the neurons' voting powers determines the total voting power associated with a given proposal. In addition to creating all ballots, when a new proposal is created, the proposer's ballot is set to a “Yes” vote. This reflects that the proposal already has the support of the user submitting it. - -Moreover, each proposal has an associated _voting period_ , which determines the period of time over which votes for this proposal are accepted. - -For more information on how to submit a proposal, refer to [How to submit a proposal](https://internetcomputer.org/docs/current/developer-docs/daos/nns/concepts/proposals/proposal-submit). - -### Proposal voting - -After a proposal is submitted and added to the governance canister, other users who control neurons can vote on the proposal. The NNS DAO is an open governance system where anyone can become a participant by [staking some ICP in a neuron](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-app-quickstart#stake-icp-utility-tokens-in-a-neuron). At least 1 ICP is required to create a neuron. Locking tokens for a period of time is known as the [neuron's dissolve delay](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692). If a neuron has more than 6 months dissolve delay, it is eligible to participate in voting. - -#### Finding proposals and discussions - -You can see all the NNS proposals on the [Internet Computer dashboard](https://dashboard.internetcomputer.org/governance) or on the [NNS dapp](https://nns.ic0.app/). Voters can freely discuss proposals anywhere they like. Many NNS proposals are discussed on the [developer forum](https://forum.dfinity.org/c/roadmap/29). - -#### Verifying proposals - -As proposals are executed fully autonomously (see below), they often include code that will be executed on proposal adoption. Before voting on a proposal, it is therefore crucial that voters not only provide their opinion whether a suggestion is a good idea, but also verify that the proposal does, i.e., implements, what it claims. For more details on the different kinds of proposals, refer to [Proposal types and topics](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068) and for some inputs on how to go about verify proposals, refer to [Verify proposals](https://internetcomputer.org/docs/current/developer-docs/daos/nns/concepts/proposals/verify-proposals). - -#### Voting - -As a neuron represents a governance participant, voting happens via a [neuron](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692). When a user has an eligible neuron and would like to vote on an open proposal, one option is to directly vote to adopt or reject the proposal. For more information how to vote, refer to [Voting on Proposals](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-voting-on-proposals). - -For more information how a user can set up their neuron to delegate its voting power using liquid democracy, refer to[ following](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons). - -### Proposal decision - -The governance canister stores a neuron's choice in the empty ballot where the neuron's voting power has been recorded. In this way, the proposal always contains the information of the total voting power of "Yes" and "No" votes. - -A proposal can be decided in two ways: - - 1. _Absolute majority before the voting period ends_ : At any point, even before the voting period ends, if an absolute majority (more than half of the total voting power stored in the proposal) has voted "Yes", then the proposal is adopted, and if an absolute majority has voted "No", then the proposal is rejected. - 2. _Simple majority at the voting period’s end_ : When the voting period ends, if a simple majority (more than half of the cast votes) has voted "Yes" and the number of these "Yes"-votes constitute at least 3% of the total voting power, then the proposal is adopted. Otherwise, the proposal is rejected. - - - -#### Wait-for-quiet - -What also plays into this is an algorithm called _wait-for-quiet_ that dynamically adjusts the deadline. The idea of wait-for-quiet is to decide proposals quickly when all voters agree, but increase the time that neurons can vote for proposals that are controversial. That means that the voting period can be dynamically increased, depending on the neurons’ votes. In particular, each time a proposal’s outcome is turned (either a "Yes"-majority is turned to a "No"-majority or vice versa), the proposal’s deadline is increased. Currently, a proposal's initial voting period is 4 days and can be increased by at most another 4 days. That is, the voting period that is taken into account for the above rules can be between 4 and 8 days, depending on the voting activity. - -A proposal is adopted or rejected as soon as a decision can be made, which may be before the end of the voting period. However, even if an early decision was made, neurons can cast their vote up to the end of the voting period's end in order to get voting rewards. - -### Proposal execution - -Technically, a proposal defines a method on a canister that will be called if the proposal is adopted with some parameters. - -When a proposal is adopted, the defined method on the specified canister is automatically called with the given parameters. This is done automatically by the governance canister and does not require any manual intervention. A proposal's execution may be successful, in which case the proposal is labeled as `executed`, or it may fail, in which case the proposal is labeled as `failed`. - -When a proposal is rejected, most of the time nothing happens. In very few cases, some cleanup work is initiated. Therefore, `rejected` is also a possible final proposal state. - -### Reward distribution - -[Neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692) receive rewards for governance participation. After a proposal reached the voting period's deadline, the governance canister will take it into account for the next reward round. Even if a proposal was decided early, the proposal remains open for voting until the deadline so voters can get voting rewards even if a decision is made very quickly. For the details about NNS voting rewards, refer to [NNS voting rewards](https://learn.internetcomputer.org/hc/en-us/articles/34142993417108). - -After the rewards are distributed, a proposal has been through the full lifecycle. The proposal's details may be emptied by the governance canister to save space. - -## Proposal structure - -Each proposal submitted to the NNS has the following fields: - - * _Summary_ : Text providing a short description of the proposal using a maximum of 280 bytes. - * _URL_ : The web address of additional content required to evaluate the proposal, specified using HTTPS. For example, the URL's content might describe supporting the assignment of a DCID (data center ID) to a new data center. - * _Proposer_ : The ID of the neuron that submitted the proposal. When a proposal is submitted, a “charge” is placed on its balance in case it is rejected. The balance needs to be enough to pay the charge on all rejection(s). The NNS requires a neuron to have a dissolve delay of ≥ 6 months to vote, which also applies to submitting proposals. - * _Proposal type and topic_ : Each proposal has a _proposal type_ , which determines what happens if the proposal is adopted or rejected. This defines which canister method is invoked with which arguments. Each type of proposal belongs to a specific _proposal topic_. Topics are used for neuron following and also determine some other details about how the proposal is processed. For example, the voting period and the voting reward weight are defined per topic. - * _Parameters_ : The parameters that will be passed to the system function and invoked if the proposal is adopted, as determined by its type. When a proposal is submitted, the NNS checks these parameters. - - - -The NNS assigns a unique identity to each proposal that it receives. - -For more details about what kind proposals exist, refer to [proposal topics and types](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068). - diff --git a/.migration/learn-hub/how-does-icp-work/nns/voting-rewards.md b/.migration/learn-hub/how-does-icp-work/nns/voting-rewards.md deleted file mode 100644 index 810c86c..0000000 --- a/.migration/learn-hub/how-does-icp-work/nns/voting-rewards.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -learn_hub_id: 34142993417108 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34142993417108-Voting-Rewards" -learn_hub_title: "Voting Rewards" -learn_hub_section: "NNS - Network Nervous System " -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Voting Rewards - -Within the NNS, voting rewards are paid out to [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692) who participate in governance by voting on [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500). - -Rewards are paid out on a regular basis (currently daily), based on an overall reward pool for that time period. Each neuron receives a pro-rata amount of that pool according to the voting power with which the neuron voted and in how many proposals the neuron participated. - -We begin by outlining the long-term composition of the reward pool and then the daily calculation of voting rewards on a high-level. Finally, we describe detailed formulas for the pool and the rewards. - -## Long-term: voting rewards over years - -The voting reward function is depicted on the [ICP dashboard.](https://dashboard.internetcomputer.org/circulation) - -In the first year after genesis, the NNS allocates 10% of the total supply to generate voting rewards. Note the term "allocates" rather than "mints", because rewards are not minted until they are spawned and the according reward neuron is disbursed. This allocation rate drops quadratically until it reaches 5% by year 8 after genesis. The formula for the annualized rewards as a percentage of total supply for the first 8 years is ` R(t) = 5% + 5% [(G + 8y – t)/8y]²`. - -Like all parameters in the NNS, the reward rate and its schedule could be changed via NNS proposals. - -Because the total supply of ICP is a dynamic system with deflation and inflation, it is impossible to predict what voting rewards will be on any given day or year in the future. It is relatively easy to predict what the percentage allocation rate will be months from now, but it is much harder to predict what the total supply will be both because of potential changes to the rate, and how often stakeholders will spawn their maturity. - -## Short-term: voting rewards each day - -Every day, rewards are granted by the network to each voting neuron. The percentage of those rewards received by each neuron depend on the following factors of a neuron: - - * Amount of ICP and maturity staked. - * The neuron's voting power, which in turn depends on - * Length of dissolve delay. - * Age of the neuron (time spent in a non-dissolving state). - * Activity of the neuron (if a neuron neither votes directly nor sets or confirms following for too long it has an adjusted voting power). - * Number of eligible proposals the neuron has voted on. - - - -## Voting rewards details - - * Determination of the total reward pool: - - * For a time t between G (genesis time) and G + 8y the annualized reward as a percentage of total supply is R(t) = 5% + 5% [(G + 8y – t)/8y]² - * For a time t after G+8y, you have R(t) = 5%. - * The total pool of voting rewards for a given day is calculated as ICP supply (total supply of ICP tokens on that day) * R(t) / 365.25. - - - * Voting power of neurons: - * Only neurons with a dissolve delay of more than `neuron_minimum_dissolve_delay_to_vote_seconds`, defined in the [governance's parameters](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068#h_01JJ2HA6H0DBRWPN13VA5P4F55), are eligible for voting. Currently this value is set to 6 months. The maximum dissolve delay is 8 years. - * The voting power of a neuron is computed as `neuron_stake * dissolve_delay_bonus * age_bonus * voting_power_adjustment` - * The neuron stake is the sum of staked ICP and staked maturity. - * In particular the dissolve delay bonus and the age bonus are cumulative. - * The dissolve delay bonus is a value between 1 and 2 and a linear function of the dissolve delay (capped at eight years). - * The age bonus is a value between 1 and 1.25 and a linear function of the age of the neuron (capped at four years). A neuron starts aging when it enters a non-dissolving state. Aging is reset to 0 when a neuron enters a dissolving state. - * Voting power adjustment is applied when a neuron hasn't voted, set following, or confirmed following in more than 6 months. The adjustment then applies a linear decrease of the voting power until it reaches 0 after 7 months of none of the above activities. - * The voting power is calculated when the proposal is made, not when the ballot is cast. - - - * Allocation of reward pool to neurons: - * The reward pool is allocated in proportion to the voting power of proposals that are settled on this day multiplied by the reward weight of the according proposal category. - * Determine the set of proposals that are included in this reward period (typically a day): these are the proposals that are not yet settled with respect to voting rewards, and no longer open for voting. - * The total voting power by neurons who were eligible for voting is added up. - * Each neuron is rewarded in proportion to the voting power it contributed to these proposals multiplied by the reward weight of the according proposal category. - * When a neuron is rewarded for voting, these rewards are recorded in an attribute of the neuron that is called maturity, which is not a tradable asset. If a user wants to generate income from maturity, they need to burn maturity to create new ICP via spawning a neuron which is a non-deterministic process. Find more information about this in [Spawning maturity & modulation](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692). - * **Reward Roll-Over Mechanism:** There may be days when no proposals within the NNS are settled. Since the distribution of rewards is tied to the ballots of settled proposals, no rewards are distributed on such days. Instead, the rewards that would have been distributed are carried over to the next day. In more detail the process works as follows: - * For each day, the NNS determines the total amount of rewards available for distribution, based on the total token supply and the reward function, as mentioned above. - * If no proposal is settled on a given day, the rewards allocated for that day remain undistributed and are rolled over to the following day. This means that on the next day, the available rewards consist of both the newly accrued rewards and the undistributed rewards from the previous day. - * Whenever at least one proposal settles, the accumulated rewards are distributed accordingly. If no proposal settles again, the rewards continue to roll over. - - - -### Example - -#### Neuron's voting power - -If a neuron has a stake of 60 ICP and 40 staked maturity, it has a combined stake of 100. -Then, let's assume a dissolve delay of 8 years, which gives it a dissolve delay bonus of 2. -Also, assume a neuron age of 2 years, which gives it an age bonus of 1.125. Finally, assume the neuron regularly votes directly and has no voting power adjustment (so the adjustment is 1). -All together, this neuron then has a voting power of `100 * 2 * 1.125 * 1 = 225`. - -#### Rewards distribution - -If on a single day the NNS has generated 1000 maturity in total rewards (see below for more on how this is computed), and there were 10 proposals submitted for which only two neurons were eligible to vote on, and: - - * Neuron A has a voting power of 20, and voted on all 10 proposals. - * Neuron B has a voting power of 80, and voted on all 10 proposals. - - - -Then the 1000 maturity would be divided between these two neurons by their proportional voting power: - - * Neuron A with voting power of 20, gets 20% of the total = 200 maturity. - * Neuron B with voting power of 80, gets 80% of the total = 800 maturity. - - - -If either neuron had only voted for X% of those 10 proposals (weighted by the reward weight of the according proposal category), it's reward would be decreased to X% of its maximum eligibility. - -If on a single day there were 10 proposals, but a neuron only voted for five of them, -that neuron would only receive 50% of its rewards for which it is eligible that day. If the five proposals the neuron voted on had a reward weight of two, it would have a `weight_of_proposal_votes = 5 * 2`, while the `weight_of_all_proposals = 5 * 2 + 5 * 1`, therefore it would receive `(5 * 2) / (5 * 1 + 5 * 2) = 66%` of the rewards for which it is eligible that day. - diff --git a/.migration/learn-hub/how-does-icp-work/sns/dao-settings.md b/.migration/learn-hub/how-does-icp-work/sns/dao-settings.md deleted file mode 100644 index dc51ab5..0000000 --- a/.migration/learn-hub/how-does-icp-work/sns/dao-settings.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -learn_hub_id: 34142964565396 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34142964565396-DAO-Settings" -learn_hub_title: "DAO Settings" -learn_hub_section: "SNS - Service Nervous System" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# DAO Settings - -While all SNSs run the same code that is approved by the NNS, the _nervous system parameters_ define the settings of a particular SNS. Since all SNSs are [upgraded along the same upgrade path](https://learn.internetcomputer.org/hc/en-us/articles/34140764336788), this allows SNSs to customize the rules of their governance, the tokenomics, etc to meet their needs. - -## The parameters - -### `default_followees` - -The set of default followees that every newly created neuron will follow per function. This is specified as a mapping of proposal functions to followees. If unset, neurons will have no followees by default. The number of followees for each function can be at most `max_followees_per_function`. - -### `max_dissolve_delay_seconds` - -The maximum dissolve delay that a neuron can have, given in seconds. That is, the maximum that a neuron's dissolve delay can be increased to. The maximum is also enforced when saturating the dissolve delay bonus in the voting power computation. - -### `max_dissolve_delay_bonus_percentage` - -E.g. if a large dissolve delay can double the voting power of a neuron, then this field would have a value of 100, indicating a maximum of 100% additional voting power. - -For no bonus, this should be set to 0. To achieve functionality equivalent to the NNS, this should be set to 100. - -### `max_followees_per_function` - -The maximum number of followees each neuron can have for each nervous system function. - -This number can be at most as large as the defined ceiling `MAX_FOLLOWEES_PER_FUNCTION_CEILING` (15 at time of writing). - -### `neuron_claimer_permissions` - -The default set of neuron permissions granted to the principal claiming a neuron. - -### `neuron_minimum_stake_e8s` - -The minimum number of e8s (10E-8 of a token) that can be staked in a neuron. - -To ensure that staking and disbursing of the neuron work, the chosen value must be larger than the `transaction_fee_e8s` set in the SNS ledger canister. - -### `max_neuron_age_for_age_bonus` - -The maximum age of a neuron (defined in seconds) that saturates the age bonus for the voting power computation. - -### `initial_voting_period_seconds` - -The initial voting period of a proposal, given in seconds. Changing this parameter will not affect existing proposals. - -### `neuron_minimum_dissolve_delay_to_vote_seconds` - -The minimum dissolve delay, defined in seconds, that a neuron must have to be eligible to vote. The chosen value must be smaller than `max_dissolve_delay_seconds`. - -### `reject_cost_e8s` - -The number of e8s (10E-8 of a token) that a rejected proposal costs the proposer. - -### `max_proposals_to_keep_per_action` - -The maximum number of proposals to keep, per action (i.e., proposal type). When the total number of proposals for a given action is greater than this number, the oldest proposals that have reached final decision state (rejected, executed, or failed) and final rewards status state (settled) may be deleted. - -The number must be larger than zero and at most as large as the defined ceiling `MAX_PROPOSALS_TO_KEEP_PER_ACTION_CEILING` (700 at time of writing). - -### `wait_for_quiet_deadline_increase_seconds` - -A parameter of the wait-for-quiet algorithm that increases the voting period of a proposal if it is controversial and changes the voting outcome. A proposal's voting period starts with `initial_voting_period_seconds` seconds and will be incresed at most by two twice the seconds defined in `wait_for_quiet_deadline_increase_seconds`. -Changing this parameter does not affect existing proposals. - -### `max_number_of_neurons` - -The maximum number of allowed neurons. When this maximum is reached, no new neurons will be created until some are removed. - -This number must be larger than zero and at most as large as the defined ceiling `MAX_NUMBER_OF_NEURONS_CEILINGM` (200_000 at time of writing). - -### `transaction_fee_e8s` - -The transaction fee, in 10E-8 of an SNS token, that must be paid for ledger transactions (except minting and burning governance tokens). - -### `max_number_of_proposals_with_ballots` - -The max number of proposals for which ballots are still stored, i.e., unsettled proposals. If this number of proposals is reached, new proposals can only be added in exceptional cases (for few proposals it is defined that they are allowed even if resources are low to guarantee that the relevant canisters can be upgraded). - -This number must be larger than zero and at most as large as the defined ceiling `MAX_NUMBER_OF_PROPOSALS_WITH_BALLOTS_CEILING` (700 at time of writing). - -### `max_age_bonus_percentage` - -Analogous to `max_dissolve_delay_bonus_percentage`, but this one relates to neuron age instead of dissolve delay. - -To achieve functionality equivalent to the NNS, this should be set to 25. - -### `neuron_grantable_permissions` - -The superset of neuron permissions a principal with permission `NeuronPermissionType::ManagePrincipals` for a given neuron can grant to another principal for this same neuron. If this set changes via a `ManageNervousSystemParameters` proposal, previous neurons' permissions will be unchanged and only newly granted permissions will be affected. - -### `voting_rewards_parameters` - -When this field is not populated, voting rewards are "disabled". Changing this should be evaluated carefully as it might be hard to understand rewards if they change. - -The reward parameters are: - - - final_reward_rate_basis_points : opt nat64; - initial_reward_rate_basis_points : opt nat64; - reward_rate_transition_duration_seconds : opt nat64; - round_duration_seconds : opt nat64; - -### `maturity_modulation_disabled` - -By default, maturity modulation (which is the same as in the NNS - see [here](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692)) is enabled; however, an SNS can use this field to disable it. When disabled, this canister will still poll the Cycles Minting Canister (CMC), and store the value received from there. -However, the fetched value is not used when this setting is set to true. - -The reason this is called "disabled" instead of (positive) "enabled" is so that the protobuf default (bool fields are false) and our application default (enabled) agree. - -### `max_number_of_principals_per_neuron` - -The maximum number of principals that can have permissions for a neuron. - -### `automatically_advance_target_version` - -A boolean defining whether to automatically advance the SNS target version after a new upgrade is approved an published by the NNS. If set to true, this has the effect that the SNS is always automatically upgraded to the latest available version that was approved by the NNS. See also [Framework and Architecture](https://learn.internetcomputer.org/hc/en-us/articles/34140764336788) for details how SNS framework canisters are upgraded. - -If not specified, the value defaults to false for backward compatibility. For newly launched SNSs, the value defaults to true. - diff --git a/.migration/learn-hub/how-does-icp-work/sns/framework-and-architecture.md b/.migration/learn-hub/how-does-icp-work/sns/framework-and-architecture.md deleted file mode 100644 index ebda6da..0000000 --- a/.migration/learn-hub/how-does-icp-work/sns/framework-and-architecture.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -learn_hub_id: 34140764336788 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34140764336788-Framework-and-Architecture" -learn_hub_title: "Framework and Architecture" -learn_hub_section: "SNS - Service Nervous System" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Framework and Architecture - -## SNS framework - -The [SNS](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564) operates as a framework within the Internet Computer Protocol (ICP). This means the ICP is responsible for the SNS functionality and maintains the code for the SNS canisters. More concretely, this means that the [NNS](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236) community maintains the code that is run by all SNSs - it approved the original SNS canisters' code and continuously approves new improved SNS versions. - -### Advantages of the framework - -The fact that SNSs are built into the platform makes it easy for SNS DAO communities to maintain the code and increases trust, as NNS voters verify the code. It is also easy for users to verify different SNS DAOs as they all run the same, pre-approved code. Because all SNSs share a common framework, users familiar with one SNS DAO will find it easy to use another DAO. - -### SNS Wasm modules canister (SNS-W) - -The Wasms run by SNS canister are approved by the NNS and published on an NNS canister called the [SNS wasm modules canister (SNS-W)](https://dashboard.internetcomputer.org/canister/qaa6y-5yaaa-aaaaa-aaafa-cai). 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 SNS framework canisters are published in a unique order on SNS-W, defining different SNS versions. - -### Upgrading SNS framework canisters - -Historically, there are different options how an SNS DAO can be updated to a new version that was pre-approved by the NNS and published on the SNS-W. - - * An SNS community can decide to update the SNS framework by submitting a proposal that will update the SNS to the next version. In this case, the DAO will automatically fetch the new version from SNS-W and update one canister (versions always only differ by one canister). - * An SNS community can choose to update to a particular target version. If an SNS is several versions behind, this is particularly useful as it has the effect that with the adoption of just one proposal, the DAO applies all required updates in sequence until the target version is reached. Compared to the first option, this requires less proposals and thus less time and effort for SNSs to catch up to the latest version. - * Finally, an SNS community can choose to always automatically upgrade to the latest available versions approved by the NNS. This can be done by an appropriate choice in the [DAO settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396). All newly created SNSs have this enabled by default. - - - -For more details about the proposals that can be used to trigger these upgrades or change these settings, refer to the [developer documentation](https://internetcomputer.org/docs/building-apps/governing-apps/managing/making-proposals). - -### SNS subnet - -The SNS DAOs are hosted on the [SNS subnet](https://dashboard.internetcomputer.org/subnet/x33ed-h457x-bsgyx-oqxqf-6pzwv-wkhzr-rm2j3-npodi-purzm-n66cg-gae). Since this subnet exclusively hosts SNSs, this simplifies the verification for end users: users can simply verify that an SNS is running on the SNS subnet and infer that the underlying code has been approved by the NNS community as explained in the previous paragraph. - -## SNS canisters - -Each SNS DAO consists of a set of canisters smart contracts that run Wasm code. The most central canisters closely resemble the NNS (NNS) which is the DAO that governs the full ICP. - -The SNS consists of the following canisters: - - * The governance canister. - * The ledger canister and archive canisters. - * The index canister. - * The root canister. - * The decentralization swap canister. - - - -### SNS governance canisters - -The _governance canister_ defines who can participate in governance decisions and automatically triggers the execution of these decisions. It stores [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204) that are suggestions on how to evolve the dapp that the SNS governs and [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084687583252) that define who the governance participants are. Neurons facilitate stake-based voting as they contain staked SNS tokens. When a proposal is adopted, the governance system automatically and autonomously triggers the execution of the proposal in the form calling a defined method. In most cases, these decisions are therefore executed fully onchain. - -### SNS ledger canister with archive and index - -The _ledger canister_ implements the [ICRC-1 standard ](https://github.com/dfinity/ICRC-1)and contains a unique token that is different for each SNS. These tokens are called _SNS tokens ._ "SNS token" may refer to one specific token of one SNS or to all these kinds of tokens, depending on the context. In each SNS, this SNS's ledger stores which accounts own how many SNS tokens and the history of transactions between them. - -To keep the full ledger history even though a canister has limited memory, the ledger canister spawns _archive canisters_ that store the ledger block history. - -Moreover, wallets and other frontends will need to show all transactions that are relevant for a given account. To facilitate this and ensure that not every frontend has to implement this themselves, the _index canister_ provides a map of which transactions are relevant for a given account. - -### SNS root canister - -The _root canister_ is responsible for upgrading the other SNS canisters and the dapp canisters that the SNS governs. - -### SNS (decentralization) swap canister - -The _decentralization swap canister_ , or swap canister for short, is the main canister involved in the [SNS launch](https://learn.internetcomputer.org/hc/en-us/articles/34141180048404). Users can provide ICP tokens to the swap and, if the swap is successful, they get staked SNS tokens (in SNS neurons) in return. Hence, the ICP and the SNS tokens are "swapped". -This facilitates that 1) the SNS can collect initial funding and 2) the distribution of neurons and thus of voting power to many different participants, which makes the governance decentralized. - -## Nervous system parameters for individual settings - -Individual SNSs can nevertheless be customized by choosing settings, called nervous system parameters, that can be configured to realize different forms of voting and tokenomics. Refer to [SNS DAO settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396) for more information. - diff --git a/.migration/learn-hub/how-does-icp-work/sns/launch.md b/.migration/learn-hub/how-does-icp-work/sns/launch.md deleted file mode 100644 index 60be3e4..0000000 --- a/.migration/learn-hub/how-does-icp-work/sns/launch.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -learn_hub_id: 34141180048404 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34141180048404-Launch" -learn_hub_title: "Launch" -learn_hub_section: "SNS - Service Nervous System" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Launch - -## What is the purpose of the launch? - -The SNS launch not only creates the SNS, but one of its main purposes is to decentralize the control of an SNS and thereby of the dapp that the SNS governs. To achieve this, new tokens must be distributed to a large community to ensure proper decentralization of the voting power. - -During an SNS launch, a developer hands over their dapp to the NNS, proposing to the NNS 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 swapping the ICP for (staked) SNS tokens. - -## What are the steps of an SNS launch? - -If a developer team wants to hand over their dapp on ICP to an SNS, in a first step they propose this in an NNS proposal defining the details of the SNS launch and the initial configuration of the SNS DAO to be created. - -Note that such a proposal often requires some technical as well as non-technical preparation, such as thorough testing, getting the community on board, etc. For more information how to prepare and propose an SNS launch, refer to the [SNS developer documentation](https://internetcomputer.org/docs/current/developer-docs/daos/sns/). - -If the NNS community approves this proposal, the steps below to launch an SNS are then executed fully automatically. - - * The NNS creates a new set of SNS canisters and initializes them as defined in the NNS proposal. - * The initial parameters define the initial settings of the SNS and the token distribution. Some initial neurons can be assigned to some predefined entities, such as the original developer team that built the dapp. It is also defined how many tokens are initially in the treasury and how many tokens are distributed to the community for decentralizing the dapp. - * The NNS hands over the dapp's control to the newly created SNS. - * The NNS starts 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. See the next Section for more details. - * The NNS proposal can optionally define that the SNS would like contributions from the [Neurons' Fund (NF)](https://learn.internetcomputer.org/hc/en-us/articles/34084179554196). - * If the decentralization swap is successful, the SNS turns into a fully functional DAO. Otherwise, all assets such as the canisters comprising the dapp and the tokens collected from participants are returned to the original holder. - - - -### Initial decentralization swap - -A decentralization swap is run entirely onchain. Every aspect of the swap, from its initiation to execution, is completely decentralized and not controlled by any centralized entity. - -An initialization swap proceeds as follows. - - * The swap is set up at the start with a defined amount of SNS tokens to be distributed publicly. For each SNS that is launched, this is a new, unique token associated with this SNS. - * During the decentralization swap, participants can send ICP to the swap canister. - * At the end of the swap, the collected ICP are exchanged for the SNS tokens. The participants receive staked SNS tokens. The ICP tokens collected in the swap will become the treasury of the new SNS DAO. - * 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. Note that the final price of SNS tokens isn't known at the time of the decentralization swap, as it is dependent on the total amount of ICP swapped. However, one can calculate the minimum and maximum price based on the minimum and maximum ICP that the swap accepts, which is defined in the initial parameters. Refer to the next paragraph for some examples. - * Participants receive a basket of [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084687583252). These neurons hold SNS tokens and therefore a share of the DAO's voting power. - - - - -After a successful decentralization swap, SNS tokens are owned and the SNS is governed by a community. - -#### Some examples - -Let's consider some examples how many SNS tokens one would get in neurons when participating in a swap. - - * The decentralization swap distributed 1000 SNS tokens and 500 ICP tokens were collected during the decentralization swap. The exchange rate is 2:1 and each participant would get 2 SNS tokens for each ICP token they contributed. - * The decentralization swap distributed 5000 tokens for 1000 ICP. You participated with 10 ICP. This means you will have 50 SNS tokens, each worth 0.2 ICP. - * The decentralization swap distributed 1 million tokens for 500,000 ICP. You participated with 200 ICP. This means you will have 400 SNS tokens, each worth 0.5 ICP. - * The decentralization swap distributed 100 tokens for 10,000 ICP. You participated with 5 ICP. This means you will have 0.05 SNS tokens, where a full token would be worth 100 ICP. - - - diff --git a/.migration/learn-hub/how-does-icp-work/sns/neurons.md b/.migration/learn-hub/how-does-icp-work/sns/neurons.md deleted file mode 100644 index 9239fe3..0000000 --- a/.migration/learn-hub/how-does-icp-work/sns/neurons.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -learn_hub_id: 34084687583252 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34084687583252-Neurons" -learn_hub_title: "Neurons" -learn_hub_section: "SNS - Service Nervous System" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Neurons - -## What is a neuron? - -Neurons represent SNS governance participants that can vote on proposals. In order to participate in governance, SNS governance tokens (that are unique in each SNS) must be _staked in a neuron_. - -Once tokens are locked in a neuron for a specified time, it gains the ability both to submit proposals and to vote on them. A neuron can also _follow_ other neurons, which causes it to automatically vote the same way as the majority of the neurons that it follows. - -### Relationship to neurons in other DAOs - -The concept of neurons closely resembles [neurons in the NNS.](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692) If you understand and are used to NNS neurons, you most likely understand a lot about SNS neurons already. There are however a few differences, including that NNS neurons can be public or private while all SNS neuron are public. - -Detailed neurons' settings can be chosen by each SNS communities as part of the [governance settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396). For example, each SNS community can choose the rules about how long tokens must be staked in a neuron for the neuron to be eligible to vote, which neuron attributes influence its voting power, whether the governance rewards participation with voting rewards and if so how much. - -### -Key concepts - -Each neuron has a _neuron ID._ In the SNSs, and unlike the NNS, the neuron ID is the neuron _account_ on this SNS's ledger where the locked token balance resides. This account is owned by the governance canister, and therefore a user cannot move staked tokens. - -#### Neuron permissions - -While the NNS has a controller, that cannot be changed, and hotkeys with limited permissions, permissions are more flexible and fine-grained in the SNS framework. - -An SNS distinguishes many different permissions, for example for voting, or for changing certain settings of the neuron. With this, an SNS can for example define that certain operations are reserved for the original "controller" of the neuron (like in the NNS) or that all permissions can be handed over to a new principal. - -Within these rules, a user can then assign any set of permissions to a given principal and has thus a lot of flexibility. Some frontends, such as the[ NNS dapp](https://nns.ic0.app/), only allow users to add and remove "hotkeys" - even though this concept does not exist in the SNS governance it is easier for users to understand. The hotkey setting represents the set of permissions of a [hotkey in the NNS](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692) and is just translated to the SNS's permission system in the background. - -#### Voting power - -An SNS is a stake-based governance system, so the main factor for how much _voting power_ a neuron has is its stake. Each SNS community can decide how the following factors influence a neuron's voting power by [choosing according settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396). - - * _Dissolve delay_ : The tokens in a neuron are locked for a specified duration called the _dissolve delay_. This can be thought of as a kitchen timer that can only be turned in one direction. It can be arbitrarily increased, but only reduced by turning on the countdown and waiting for the time to pass. Each SNS defines the _minimum dissolve delay_ a neuron must have to be _eligible_ to vote. - * _Dissolve state:_ A neuron can be in one of three states. - * A neuron can be _non-dissolving_ which means that the timer is stopped and the neuron's dissolve delay remains the same. - * A neuron can be _dissolving_ which means that the timer is decreasing the neuron's dissolve delay as time passes. - * Once the timer has counted down, a neuron is _dissolved_ and the ICP tokens can be unstaked again. This is called _disbursing_ a neuron. - * _Age_ : Every non-dissolving neuron has an age, which denotes how long it has been in the non-dissolving state. - - - -These factors ensure that a neuron who has tokens locked for longer or has been around for longer has more voting power as it is more committed to the project. - -#### Maturity - -Each [SNS can choose](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396) whether participation in voting is rewarded with [voting rewards](https://learn.internetcomputer.org/hc/en-us/articles/34143058069396). If activated, when neurons vote, directly or through following, the _maturity_ of a neuron increases as it collects voting rewards. See [SNS Rewards](https://learn.internetcomputer.org/hc/en-us/articles/34143058069396) for more details. -There are different things that a neuron holder can do with maturity: - - * Maturity can be liquidated by _disbursing maturity_. This is a process that can be started at any time and will then take seven days. In the end, a _maturity modulation_ is applied, and new SNS tokens are minted that can be freely used. - * Maturity can be disbursed to any ledger account. If no account is specified, the caller's account will be used. - * Maturity can be staked into _staked maturity_ into the neuron. Staked maturity is viewed as part of the neuron's stake and contributes to the neuron's voting power. But, similarly to the neuron's stake, it is also locked until the neuron is dissolved. When a neuron dissolves, its staked maturity is converted back to normal un-staked maturity. - * Maturity can be _auto-staked._ In order to not have to regularly perform the previous action, a neuron can also choose to auto-stake its maturity. This means that all new maturity will automatically be added to the staked maturity. - - - -The (same)[_maturity modulation_](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#01JY1DDWXPKKD5JHH927Z683D0) applies both to NNS neurons and SNS neurons. In both scenarios, the function of maturity modulation will be influenced by the ICP/cycles conversion rate. For more details, refer to [maturity modulation](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#01JY1DDWXPKKD5JHH927Z683D0). - -#### Neuron visibility - -All SNS neurons are _public._ - -## Governance participation - -The main purpose of a neuron is to participate in governance. A neuron with a minimal stake can do so by submit and vote on a [proposals,](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204) or by participating in governance via the liquid democracy. - -### Voting - -A neuron is eligible to vote if it has a minimum staked ([defined in the SNS's settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396)). An eligible neuron can _vote_ on a proposal by choosing to adopt or reject it. As a neuron can also delegate voting (see next paragraph), this is sometimes also called _direct voting._ - -As stated above a neuron's eligibility and voting power is dependent on its state and computed at proposal submission time. For more details how these votes are processed in terms of ballots, refer to[ SNS proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204). - -### Following / vote delegation - -Users may not have the time or knowledge to participate in all voting decisions. Therefore, instead of directly voting on proposals, neuron holders may choose to _delegate_ their vote to other neurons that they trust with certain decisions. This concept, where a neuron follows the decisions of some other neurons, is called _following_. Collective decision making which combines the direct execution with dynamic delegation mechanisms for voting rights is called liquid democracy. - -Following works as in the NNS and you can refer to an explanation video how it can be set on the NNS dapp [here](https://learn.internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons). - -#### Following rules - -A neuron can be configured to vote automatically by following the voting decision made by a group of other neurons, called _followees_. In the SNS, following is currently based on [proposal types](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204). - -A neuron will only cast a "Yes"-vote if _more than half_ of the neurons within the followee-group voted Yes. A neuron will only cast a "No"-vote if _at least half_ of the neurons within the followee-group voted No. - -Your neuron will follow when there are enough votes to make a decision whether it is a ADOPT or REJECT. For example, if you follow 10 neurons on a topic: -\- Your neuron only votes to adopt if at least 6 out of the 10 neurons vote to adopt. -\- Your neuron only votes to reject a proposal if at least 5 out of the 10 reject the proposal. -\- If less than 5 neurons (out of your 10 followed) vote at all, your neuron will not cast any vote. - -This should be considered when choosing to follow multiple neurons on a topic. It might be better to follow fewer neurons, and it can be more beneficial to follow an odd number of neurons than an even number. - -#### Following "catch-all" - -In addition to setting following for individual topics, neurons may also define a catch-all follow rule which is triggered for proposals with topics for which no other explicit follow rule has been defined. -However, the _catch-all follow rule does not include critical proposal types_. - -The catch-all follow rule is only applied for proposal topics with no other explicit choice. For example, let's assume neuron A follows neuron B for the catch-all and neuron C on the topic dapp upgrade. If B votes on a dapp upgrade proposal but C does not, no vote will be cast for A. -The catch-all follow rule does not apply for critical proposals. For example, if neuron A follows neuron B for the catch-all and B votes on a treasury transfer proposal (which is critical, see [SNS Proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204)), no vote will be cast for A. If neuron A intends to also follow B on such decisions, the user has to explicitly choose to also follow B on the treasury type. - - - -It is in each neuron's interest to follow other neurons that support the best interests of the project and their own economic interests. - diff --git a/.migration/learn-hub/how-does-icp-work/sns/proposals.md b/.migration/learn-hub/how-does-icp-work/sns/proposals.md deleted file mode 100644 index 94614d1..0000000 --- a/.migration/learn-hub/how-does-icp-work/sns/proposals.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -learn_hub_id: 34146571133204 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34146571133204-Proposals" -learn_hub_title: "Proposals" -learn_hub_section: "SNS - Service Nervous System" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Proposals - -Proposals are suggestions of how to evolve the dapp that an SNS governs and the SNS DAO itself. They are thus the integral part of managing a dapp as a decentralized community. - -The proposal lifecycle in SNSs closely resembles the one for [NNS proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500). In contrast to the NNS, there are two main distinguishing factors for SNS proposals. First, SNSs have a notion of _proposal criticality -_ some proposal topics are defined to be critical and follow stricter voting rules. Second, to ensure that SNSs are flexible for the needs of different dapps that they govern, SNSs distinguish between has _Built-in proposals_ that are the same in each SNS and _custom proposals_ that can be defined by each SNS community for their specific needs. - -## Proposal lifecycle - -The lifecycle of SNS proposals closely resembles the one from NNS and goes through the following high level flow: - - 1. An eligible neurons submits a proposal. - 2. All other eligible neurons can vote on the proposal. - * Voting can be done by direct voting or by delegating voting power to other neurons - 3. A proposal is decided early when it has sufficient support for adopting or rejection. Otherwise the proposal is decided when the defined voting period is reached, which follows the [wait-for-quiet](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500/h_01JJ2GW8QMPCY5PCV3X96Q1Y79) approach. - 4. Even if a proposal is decided early, voters can cast their vote until the end of the voting period to for getting voting rewards. - 5. An adopted proposal is automatically executed on-chain. - - - -The criteria for proposal decision as well as the voting period in Step 3 depend on the proposal's topic as explained next. - -### Proposal criticality - -In contrast to the NNS, the SNSs distinguish different rules for the proposals' decision, based on whether the proposal is _critical_. - -Criticality is defined based on proposal topics. That is, each proposal has a topic and each topic is either critical or non-critical. Proposals with a critical topic are also called "critical". They follow more strict rules to ensure they are only passed with broad community consensus. - -#### Voting thresholds - -Non-critical proposals can be passed if 3% of the total voting power votes yes and 50% of the exercised voting power votes yes. - -Critical proposals can only be passed if 20% of the total voting power votes yes and 67% of the exercised voting power votes yes. - -#### - -#### Voting period - -The voting period for critical proposal types is 5-10 days and cannot be changed by the SNS. In contrast, for non-critical proposals the default is 4-8 days and this can be adjusted by each SNS DAO. - -Critical proposal have a longer voting period as they require a larger voting participation and it is therefore beneficial to give voters a bit more time to participate. - -As in the NNS, for all proposals the [wait-for-quiet algorithm](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500) ensures that controversial proposals will have a longer voting period (up to 10 days for critical proposals) while proposals where everyone agrees on have a shorter voting period (5 days for critical proposals). - -#### Catch-all following - -Vote delegation is based on proposal topics and, in contrast to the NNS, there is no longer any notion of a "catch-all" following that covers multiple proposal topics. -However, SNS vote delegation used to be based on proposal types, which may still be used by some neurons. This old legacy way of vote delegation supported a "catch-all following" that covered all types, except for the critical proposals. - -## Built-in and custom proposals - -An SNS comes built-in proposals called built-in proposals and SNS-specific custom proposals. - -### - -### Built-in SNS proposals - -These proposals are provided as part of the SNS framework and thus all SNS DAOs have them. - -Built-in proposals also have pre-defined proposal topics, also deciding on the proposal's criticality (see above). This ensures that the same built-in proposal has the same topic in all SNS DAOs, which makes it easier for users of one SNS to quickly navigate another SNS. - -Built-in proposals include: - - * Motion proposals for opinion polls - * Proposals to change the SNS's settings and metadata - * Proposals to upgrade the SNS framework canisters - * Proposals to register and deregister dapp canisters under SNS control, as well as to change the dapps' settings - * Proposals to move treasury funds or mint new tokens - - - -You can find more details on all built-in SNS proposals, including their types and how to submit them in the [developer documentation.](https://internetcomputer.org/docs/building-apps/governing-apps/managing/making-proposals) All the proposals used to manage an SNS are executed on the SNS governance canister, so for the most up-to-date definition of SNS proposals, it helps to have as a reference the [interface for the governance canister](https://github.com/dfinity/ic/blob/master/rs/sns/governance/canister/governance.did), where you can find all proposals defined in the type `Action`. - -### Custom SNS proposals - -Each SNS community might have functions that they would like to only execute if the SNS DAO agrees on it, but that might be very dapp-specific. _Custom proposals_ , also called _generic proposals_ , _generic functions_ , or _generic nervous system functions_ , allow a flexible way for SNS communities to define such functions. - -Some examples: - - * A dapp may have lots of canisters to maintain. For example, there may be one canister for each user, in which case they may want to apply upgrades through an orchestrator canister. For this workflow, they would have to tell this orchestrator what the user-canisters should be upgraded to and when to trigger this upgrade. In a DAO-governed dapp, this should happen via proposal. - * Developers might want the DAO to be the only entity that can elect moderators, call certain methods, make certain payments, etc. - - - -For all these cases, SNS DAOs can use generic proposals. Fundamentally, a custom proposal is just a call to a method on a canister with a certain argument. This means that one can do anything with a generic proposal as long as one can tell the SNS governance canister which method to call. - -In addition, since the governance canister is not aware of what a generic proposal does or in which context it will be applied, a custom proposal also has to define a validation method and canister. This method is called whenever such a generic proposal is submitted and if the validator method fails, the proposal will not be put to vote in the SNS. - -#### Lifecycle of custom proposals - -To use a custom proposal, it first needs to be added to the SNS governance system. This means that the SNS DAO needs to approve that this is a proposal that should be supported going forward. This is also due to the fact that there are a few important, security-critical considerations to make when adding a generic proposal. You can find some of these considerations in the [developer documentation](https://internetcomputer.org/docs/building-apps/governing-apps/managing/making-proposals#security-considerations-when-designing-generic-proposals). - -All SNS proposals have assigned topics that are used for filtering and for vote delegation. Since generic proposals are SNS-specific, each SNS community must define which topic fits a new generic proposal best. This is done when the generic proposal is added. Later the community can re-assign a proposal to a new topic by proposal. - -To use a generic proposal, i.e., submit such a proposal, one uses the “execute generic nervous system function” proposal type and specifies which of the registered generic proposals should be used. - -Finally, custom proposals can then also be removed again from SNS governance if they are not needed anymore. - -All of this handling of custom proposals is done by built-in proposals that are explained in more detail in the [developer documentation](https://internetcomputer.org/docs/building-apps/governing-apps/managing/making-proposals#generic-proposals). - -## Proposal topics - -Each SNS proposal is assigned to a _proposal topics_. There are seven proposal topics that are defined as part of the SNS framework and thus the same for all SNSs. - -A proposal's topics also decides whether the proposal is [critical](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204/h_01K0RK6HWZ0N9HN0EH19P48K44). - -Learn more details on how SNS topics were introduced and how they facilitate vote delegation in this tutorial - -#### Critical proposal topics - -Each SNS has the following **critical proposal topics**. - - * **Critical Dapp Operations** : Proposals to execute critical operations on dapps, such as adding or removing dapps from the SNS, or executing custom logic on dapps. - * **DAO Community Settings** : Proposals to set the direction of the DAO by tokenomics & branding, such as the name and description, token name, etc. - * **Treasury and Asset Management** : Proposals to move and manage assets that are DAO-owned, including tokens in the treasury, tokens in liquidity pools, or DAO-owned neurons. - - - -#### Non-critical proposal topics - -In addition, each SNS has the following **non-critical topics**. - - * **Application Business Logic** : Proposals that are custom to what the governed dapp requires. - * **Dapp Canister Management** : Proposals to upgrade the registered dapp canisters and dapp upgrades via built-in or custom logic and updates to frontend assets. - * **Governance** : Proposals that represent community polls or other forms of community opinion but don’t have any immediate effect in terms of code changes. - * **SNS Framework Management** : Proposals to upgrade and manage the SNS DAO framework. - - - -#### Assignment of proposal types to topics - -Built-in proposals have a fixed assigned topic. This means that in each SNS the same built-in proposal has the same topic. - -For custom proposals, the SNS community needs to assign a topic when the custom proposal is added to governance. This means in particular that two SNSs could have a very similar or even the same custom proposal but have it assigned to different topics. - -For a given SNS where you have a neuron controlled on the NNS dapp, you can find which proposals are assigned to which topic by navigating to `Voting Delegation` in the neuron detail page and clicking on `View topic definitions`. - diff --git a/.migration/learn-hub/how-does-icp-work/sns/rewards.md b/.migration/learn-hub/how-does-icp-work/sns/rewards.md deleted file mode 100644 index 25de3b7..0000000 --- a/.migration/learn-hub/how-does-icp-work/sns/rewards.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -learn_hub_id: 34143058069396 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34143058069396-Rewards" -learn_hub_title: "Rewards" -learn_hub_section: "SNS - Service Nervous System" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Rewards - -The full potential of tokenization can be unlocked by a tokenized open governance system, where tokens can be staked to participate in voting. Anyone with staked tokens can submit and vote on governance [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204) for the dapp governed by the SNS DAO. - -SNS governance empowers developers, users, and investors to collectively shape the dapp's future by voting on proposed features. Staked token holders are incentivized to vote strategically, considering the long-term value of both the tokens and the dapp. - -There are two categories of rewards: - - * **Voting rewards** to incentivize users to take part in SNS governance. - * **User rewards** to incentivize dapp users to become early adopters and active users of the dapp that is governed by the SNS. - - - -The reward scheme is based on the principles for [voting rewards used in the NNS](https://learn.internetcomputer.org/hc/en-us/articles/34142993417108), flexibly configurable for each SNS. - -## Voting rewards - -The SNSs leverage the [NNS voting reward scheme ](https://learn.internetcomputer.org/hc/en-us/articles/34142993417108)with the flexibility to configure the scheme to the DAO's needs. Hence, in the following this guide goes through the features of the NNS and describes how it is adapted and made configurable for the SNS. Unless otherwise stated, the approach and formulae are the same as for the NNS. As for the NNS, it is possible to change the SNS configuration by an SNS governance proposal. - -### Determination of the total reward pool - -The impact of changing the parameters of the reward function can be simulated in this [tool](https://docs.google.com/spreadsheets/d/1cTqgjGcG5rEQ5kRGprpdLvBL7ZdTqUDCuCi0QjClbgk/edit#gid=0). - -![graph_rewards_total_supply.png](https://learn.internetcomputer.org/hc/article_attachments/34143317612948) - - * Reward minimum r_min: rational value greater than or equal to 0. Default value: 0.00. - * Reward maximum r_max: rational value greater than or equal to r_min. Default value: 0.00. - * Start time for paying out rewards t_start: timestamp greater than or equal to genesis time of the SNS. The start time is set to the current time once the reward calculation is switched on. - * Time length t_delta which is greater than or equal to 0 and which determines the time transition length between r_max and r_min. Default value: 0 years. - * For a time t between t_start and t_start+t_delta the annualized reward as a percentage of total supply is R(t) = r_min + (r_max - r_min) [ (t_start + t_delta – t) / t_delta ]² - * For a time t after t_start + t_delta , you have R(t) = r_min - * For the special case r_max = r_min the reward function is constant, namely R(t)=r_min - * The total pool of voting rewards for a given day is calculated as SNS supply (total supply of SNS tokens) * R(t) / 365.25. - * Voting rewards are minted, i.e. generating new supply once the according maturity is converted to the SNS token. In case that the SNS would like to stop a token supply increase after t_start + t_delta the SNS should set r_min = 0. - - - -### Voting power of neurons - - * Required minimum dissolve delay for voting dd_min: integer value greater than or equal to zero. Default value: 6 months. - * Maximum dissolve delay dd_max: integer value greater than or equal to dd_min. Default value: 8 years. - * Maximum dissolve delay bonus: - * ddb_max rational value greater than or equal to 1. Default value: 2. - * The special case ddb_max = 1 results in no dissolve delay bonus. - * Maximum age a_max: integer value greater than or equal to 0. Default value: 4 years. - * Maximum age bonus ab_max rational value greater than or equal to 1. Default value: 1.25. - * The special case ab_max = 1 results in no age bonus. - - - -### Allocation of reward pool - - * The reward pool is allocated in proportion to the voting power of proposals that are settled on this day (same as for the NNS). - * If on a particular day no proposal was submitted then rewards will be carried over to the next day. - * NNS has reward weights for different proposal types. In the current version of the SNS reward scheme this functionality is not available. - - - -There is a flag which activates the calculation and distribution of voting rewards, as an SNS might choose to go through a ramp-up period without voting rewards, or with no voting rewards at all. - -## Setting voting reward parameters - -Voting reward parameters are defined as part of the nervous system parameters that define the[ individual settings for a given SNS instance](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396). - -The following table provides an overview of all relevant parameters which are collectively called _VotingRewardsParameters_ , linking the notation of this article to full names used in the implementation. - -**Parameter** | **Full name in _VotingRewardsParameters_** ----|--- -r_min | _initial_reward_rate_basis_points_ -r_max | _final_reward_rate_basis_points_ -t_start | _start_timestamp_seconds_ -t_delta | _reward_rate_transition_duration_seconds_ - -When _VotingRewardsParameters_ is not populated, voting rewards are disabled. - -The following provides an overview of the relevant parameters for the determination of voting power. - -**Parameter** | **Full name in _VotingRewardsParameters_** ----|--- -dd_min | neuron_minimum_dissolve_delay_to_vote_seconds -dd_max | max_dissolve_delay_seconds -ddb_max | To be added, once implemented. -a_max | max_neuron_age_for_age_bonus -ab_max | To be added, once implemented. - -## User rewards - - * The purpose of user rewards is to foster early adoption and active usage of the SNS. Given that the meaning of usage and the according user rewards can vary greatly across individual SNSs, there is a very simple set-up. - * Some tokens (reserved for user rewards) can be held in an account that is owned by an SNS-controlled canister. This canister can then codify when the rewards are paid out and to whom. - * This solution allows paying out existing (not newly minted) tokens. Triggering minting for user rewards is currently not supported, this functionality may be added in a future version. - - - diff --git a/.migration/learn-hub/how-does-icp-work/sns/sns-service-nervous-system.md b/.migration/learn-hub/how-does-icp-work/sns/sns-service-nervous-system.md deleted file mode 100644 index cd40b8c..0000000 --- a/.migration/learn-hub/how-does-icp-work/sns/sns-service-nervous-system.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -learn_hub_id: 34084394684564 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34084394684564-SNS-Service-Nervous-System" -learn_hub_title: "SNS - Service Nervous System" -learn_hub_section: "SNS - Service Nervous System" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# SNS - Service Nervous System - -The Service Nervous System (SNS) framework enables creating and maintaining decentralized autonomous organizations (DAOs) to govern dapps. An SNS consists of an open, permissionless governance system that can control a dapp, and of a built-in governance token that is unique to each 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. - -## What is a Decentralized Autonomous Organization (DAO)? - -A DAO is an organization whose members – typically holders of the governance token – collectively decide how the organization or the product evolves. Example scenarios: - - * 10'000 token holders each deposit crypto into a smart contract and vote on what to purchase with the total. - * 1 million token holders control a decentralized version of Twitter where token holders propose and vote on feature updates. - - - -A DAO can take the role of carrying out community-driven decisions on when and how to update the code that shapes the organization or product. - -## What is a Service Nervous System (SNS)? - -An SNS is a powerful software framework that enables a DAO community to govern smart contracts and decentralized apps (dapps) running on the Internet Computer completely onchain. - - * A dapp controlled by an SNS DAO is governed by SNS token holders submitting and voting on onchain proposals. No one developer or group of people controls the dapp, rather the dapp is controlled by voting via tokens. - * There can be many SNSs on ICP. Any developer can hand over the control of their dapp to an SNS DAO. Doing so gives control to DAO token holders. - - - -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 ICP. ](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236)DAO participants are called [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084687583252) and all neurons can suggest and vote on suggestions how to evolve the dapp that are called [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084705977876). - -### What can be controlled by an SNS DAO? - -The core purpose of an SNS DAO is to govern a dapp, i.e., decide on the code of that dapp, including configuration, data, and frontend. Moreover, the SNS DAO makes decisions on the DAO itself, for example on how to change the DAO [tokenomics](https://learn.internetcomputer.org/hc/en-us/articles/34088279488660). More technically, there are [native proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204) 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](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204) 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. - -### SNS framework - -The[ SNS framework](https://learn.internetcomputer.org/hc/en-us/articles/34140764336788) is built into ICP and allows anyone to hand over their dapp to an SNS DAO. It comes with a pre-defined path of how an SNS is launched and results in a SNS DAO instance. Each SNS includes a stake-based governance system, that orchestrates decision making and changes, and a ledger that defines a unique token for each SNS. - -The framework ensures that all SNSs run code that is trustworthy and that all SNSs run the same code. This not only simplifies verification that the code is correct and does what it should but also has the advantage that DAOs are more user-friendly - a user that used one SNS will likely have a good intuition how to participate in a second SNS. Despite all SNSs using the same code, each SNS community can choose their own unique tokenomics and governance rules by parameters that can be set for each SNS DAO. Refer to [SNS framework and architecture](https://learn.internetcomputer.org/hc/en-us/articles/34140764336788) for more details. - -### SNS launch - -As mentioned above, the SNS framework includes a process that defines how to launch an 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. On a high level, the following things happen during a successful SNS launch: - - * the canisters for a new SNS DAO are created and installed - * the governance control is distributed to users in a decentralization swap that - * collects initial treasury funds in the form of ICP - * gives participants a share of the governance control in the form of SNS neurons - * the dapp's control is handed over to the new SNS - - - -Refer to the article on [SNS launch](https://learn.internetcomputer.org/hc/en-us/articles/34141180048404) for more details about these events and to [SNS decentralization swap](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-additional-features#sns-decentralization-swaps) for a tutorial on how you can participate in an SNS launch. - -### SNS governance - -After an SNS launch, the control of both the dapp it governs and the SNS canisters shifts from a single entity (like the developer) to the decentralized SNS community. This community then determines the future of the dapp's functionality, the behavior of the SNS canisters, and any modifications to either. Any changes to the dapp and the SNS can only be made by [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084705977876) and are decided on by the SNS's [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084687583252). - -The initial neuron holders include holders of initial neurons (e.g., used for the original developer team of the dapp) as well as the participants of the swap. Over time, more users may stake SNS tokens and participate in governance. - -### Resources - -There are different places where you can learn more about existing and upcoming SNS launches. For example, you can find all launched SNSs on the [Internet Computer dashboard](https://dashboard.internetcomputer.org/sns) and you can find and participate in ongoing launches on the [NNS dapp launchpad](https://nns.ic0.app/launchpad/). - diff --git a/docs/concepts/governance.md b/docs/concepts/governance.md index ad36b19..161d9ed 100644 --- a/docs/concepts/governance.md +++ b/docs/concepts/governance.md @@ -2,7 +2,7 @@ title: "Governance" description: "How ICP is governed: the NNS, SNS for app governance, neurons, proposals, and tokenomics fundamentals" sidebar: - order: 13 + order: 14 --- The Internet Computer Protocol uses two governance systems: the **Network Nervous System (NNS)** governs the protocol itself, and the **Service Nervous System (SNS)** provides a framework for app developers to hand control of their applications to a community-owned DAO. @@ -39,16 +39,16 @@ A neuron is a governance participant created by locking ICP tokens in the NNS go **Key neuron attributes:** -- **Stake**: The amount of ICP locked. Minimum stake to submit proposals is 10 ICP with at least 6 months of dissolve delay. +- **Stake**: The amount of ICP locked. The minimum to create a neuron is 1 ICP. To submit or vote on proposals, a neuron needs at least 6 months of dissolve delay. - **Dissolve delay**: A waiting period (up to 8 years) that must expire before locked ICP can be retrieved. Longer dissolve delay grants more voting power. - **Age**: How long the neuron has been non-dissolving. Older neurons earn an age bonus on voting power. - **State**: A neuron is either locked (non-dissolving), dissolving, or dissolved (ready to disburse). -**Voting power formula:** A neuron's voting power scales with its stake, dissolve delay bonus (up to 2x at 8 years), and age bonus (up to 1.25x at 4 years). This design incentivizes long-term alignment with the network. +**Voting power formula:** A neuron's voting power scales with its stake, dissolve delay bonus (up to 2x at 8 years), and age bonus (up to 1.25x at 4 years). This design incentivizes long-term alignment with the network. **Liquid democracy (following):** Neurons can delegate their votes to other neurons on specific proposal topics. A neuron that doesn't vote directly inherits the vote of its followed neurons. This allows passive participation while still counting toward quorum. -**Known neurons** are named neurons registered in the NNS governance canister through a proposal. They act as trusted delegates that other neurons follow. Any neuron that meets the general proposal prerequisite (at least 10 ICP staked with 6 months dissolve delay) and has at least 25 ICP staked can submit a `RegisterKnownNeuron` proposal. +**Known neurons** are named neurons registered in the NNS governance canister through a proposal. They act as trusted delegates that other neurons follow. Any neuron with at least 6 months of dissolve delay and at least 25 ICP staked can submit a `RegisterKnownNeuron` proposal. ## Proposals @@ -88,7 +88,7 @@ Unlike the NNS, which is a singleton governing the entire protocol, each SNS is ### SNS canisters -An SNS consists of six canisters deployed by SNS-W (the SNS Wasm modules canister, `qaa6y-5yaaa-aaaaa-aaafa-cai`): +An SNS consists of five core canisters plus a variable number of archive canisters, all deployed by SNS-W (the SNS Wasm modules canister, `qaa6y-5yaaa-aaaaa-aaafa-cai`): | Canister | Purpose | |----------|---------| @@ -97,7 +97,7 @@ An SNS consists of six canisters deployed by SNS-W (the SNS Wasm modules caniste | **Root** | Sole controller of all app canisters post-launch | | **Swap** | Runs the decentralization swap (ICP for SNS tokens) | | **Index** | Transaction indexing for the SNS ledger | -| **Archive** | Historical transaction storage | +| **Archive** (one or more, spawned as needed) | Historical ledger block storage; new archive canisters are created automatically as the ledger grows | Once an SNS is live, the SNS Root canister is the sole controller of the app's canisters. Upgrades happen through governance proposals voted on by SNS token holders. @@ -143,10 +143,72 @@ When an app is governed by an SNS, the original developers no longer have direct Developers preparing for an SNS launch should ensure their codebase is stable, open-sourced, and reproducibly buildable before the decentralization swap. The NNS community votes on the creation proposal and expects evidence of product-market fit, sound tokenomics, and a realistic roadmap. +## Neuron hotkeys + +A neuron's **controller** is the principal with full authority over the neuron. A controller can perform any operation: increase dissolve delay, start or stop dissolving, disburse the stake, and more. Because the private key of the controller principal must be kept highly secure (typically in cold storage), neurons can also have **hotkeys**: additional principals with a limited permission set. + +Hotkeys can: +- Vote on proposals (directly or by confirming following). +- Set or change following rules. +- Submit proposals. +- Read all neuron fields, including non-public information. + +Hotkeys cannot modify the stake, change the dissolve delay, or disburse the neuron. Up to 15 hotkeys are allowed per neuron. A common pattern is to set a hardware wallet as the controller and use a software wallet as a hotkey for day-to-day voting. + +## Following rules in detail + +When a neuron follows a group of other neurons on a topic, it casts its vote once a threshold in the followee group is reached: + +- It votes **adopt** if more than half of the followees vote yes. +- It votes **reject** if at least half of the followees vote no. +- It casts no vote if neither threshold is met. + +A neuron can follow at most 15 neurons per topic. A **catch-all** following rule covers topics with no explicit setting, but does not apply to the *SNS & Community Fund* and *Governance* topics, which must be explicitly configured. + +**Periodic confirmation:** A neuron that never votes directly must confirm its following settings at least once every 6 months. If it fails to do so, voting power is linearly reduced over the following month until it reaches zero, and all following settings are reset. This prevents inactive neurons from accumulating rewards without genuine participation. + +## Voting thresholds and proposal decision + +NNS proposals can be decided two ways: + +- **Absolute majority (at any time):** If more than half of the total voting power recorded at proposal creation votes yes, the proposal is immediately adopted. Likewise, a no absolute majority immediately rejects it. +- **Simple majority at deadline:** When the voting period ends (4 to 8 days, depending on wait-for-quiet), the proposal passes if the yes vote constitutes both a simple majority of cast votes and at least 3% of the total voting power. If the 3% quorum is not met, the proposal is rejected even if a majority of participants voted yes. + +The 3% quorum prevents low-turnout proposals from passing on a handful of votes. + +## Maturity operations + +Maturity accumulated from voting rewards is not transferable and is not immediately liquid. Neuron holders have three options: + +- **Disburse (previously: spawn):** Start a 7-day process that burns the maturity and mints new ICP. The exact amount is subject to maturity modulation: the mint multiplier is computed from 30-day moving averages of the ICP/XDR conversion rate over the preceding 4 weeks, bounded to ±5%. This introduces a small amount of uncertainty (the maturity modulation can move ±1.25% from one week to the next) that discourages timing the market. +- **Stake maturity:** Add maturity to the neuron's staked balance, increasing its voting power immediately. Staked maturity is locked alongside the ICP stake and converts back to unstaked maturity when the neuron dissolves. +- **Auto-stake maturity:** Automatically stake all new maturity as it accrues, compounding voting power without manual intervention. + +## Voting rewards formula + +The NNS distributes rewards daily from a reward pool. The annualized pool size as a percentage of total ICP supply follows this schedule: + +- For years 0–8 after genesis: `R(t) = 5% + 5% × [(G + 8y − t) / 8y]²` +- After year 8: `R(t) = 5%` + +where G is the genesis timestamp and t is the current time. This quadratic decline starts at approximately 10% in year 1 and converges to 5%. The daily pool is `total_supply × R(t) / 365.25`. + +Each neuron receives a share of the pool proportional to its voting power multiplied by the fraction of eligible proposals it voted on (weighted by the reward weight of each proposal topic). If no proposals settle on a given day, rewards roll over to the next distribution. + +## The Neurons' Fund + +The Neurons' Fund (NF) is a mechanism that allows NNS neurons to allocate maturity toward the decentralization swaps of new SNS DAOs. Participation is opt-in: a neuron holder can join or leave the NF at any time. + +When an SNS swap runs, NF contributions scale with direct participation through a matching function. NF neurons receive SNS neurons in return, with the same hotkeys copied so that holders can vote in the new SNS governance without exposing their cold-storage keys. + +**Note:** The Neurons' Fund was temporarily disabled by [NNS proposal 135970](https://dashboard.internetcomputer.org/proposal/135970). The design described above reflects the intended behavior when it is re-enabled; details may change. + ## Next steps - [Launch an SNS](../guides/governance/launching.md): step-by-step guide to decentralizing your app - [Manage a live SNS](../guides/governance/managing.md): proposals, upgrades, and treasury management after launch +- [SNS framework](sns-framework.md): detailed architecture, neurons, proposals, and reward scheme +- [NNS proposal types reference](../references/nns-proposal-types.md): all proposal topics and types - [System canisters reference](../references/system-canisters.md): NNS canister IDs and interfaces - + diff --git a/docs/concepts/sns-framework.md b/docs/concepts/sns-framework.md new file mode 100644 index 0000000..a1d49bc --- /dev/null +++ b/docs/concepts/sns-framework.md @@ -0,0 +1,132 @@ +--- +title: "SNS Framework" +description: "How the Service Nervous System works: framework architecture, launch process, neurons, proposals, and configurable rewards" +--- + +The Service Nervous System (SNS) is a governance framework built into ICP that lets any developer hand control of their application to a community-owned DAO. When an app is governed by an SNS, all upgrades, treasury decisions, and parameter changes require on-chain proposals voted on by SNS token holders. + +For a high-level introduction comparing the NNS and SNS, see [Governance](governance.md#the-service-nervous-system). + +## Framework architecture + +All SNS DAOs run code that the NNS community has reviewed and approved. The NNS maintains a canister called the **SNS Wasm modules canister (SNS-W)**, `qaa6y-5yaaa-aaaaa-aaafa-cai`, which stores the approved Wasm binaries for each SNS canister. When a new SNS is created, SNS-W deploys the approved code. When NNS voters approve an improved SNS version, it is published to SNS-W and all existing SNS DAOs can upgrade to it. + +This shared codebase has two benefits. First, NNS voters review the code once and all SNS DAOs benefit. Second, users who have interacted with one SNS have a reliable intuition for how any other SNS works. + +**Upgrade paths:** An SNS community can upgrade its framework canisters in three ways: +- Submit a proposal to upgrade one step at a time along the NNS-approved upgrade path. +- Submit a proposal targeting a specific version, which automatically applies all intermediate steps in sequence. +- Enable `automatically_advance_target_version` in the DAO settings, causing the SNS to always follow the latest NNS-approved version without a proposal. This is enabled by default for newly launched SNSs. + +**SNS subnet:** All SNS DAOs live on a dedicated SNS subnet (`x33ed-h457x-bsgyx-oqxqf-6pzwv-wkhzr-rm2j3-npodi-purzm-n66cg-gae`). Because every canister on that subnet runs NNS-approved SNS code, users can verify an SNS is legitimate simply by confirming it runs on the SNS subnet. + +## The launch process + +Launching an SNS is a one-time process that transfers control of an application from its original developers to a DAO community. + +**Step 1: NNS proposal:** The developer submits a `CreateServiceNervousSystem` proposal to the NNS, specifying the initial token distribution, decentralization swap parameters, initial governance settings, and the canisters to be governed. If the NNS community approves the proposal, the launch proceeds automatically. + +**Step 2: SNS canisters deployed:** The NNS uses SNS-W to deploy a fresh set of SNS canisters. The app's canisters are transferred to SNS Root as their controller. + +**Step 3: Decentralization swap:** A swap window opens where users can send ICP to the SNS Swap canister. At the end of the window (or earlier if the maximum is reached), each contributor receives a proportional share of a fixed SNS token allocation as staked neurons. The ICP collected becomes the DAO treasury. All swap participants receive a basket of neurons with configurable dissolve delays. + +The swap has a minimum and maximum ICP threshold: +- If the minimum is not met when the window closes, the swap fails: all ICP is refunded and control of the app reverts to the original fallback controllers. +- If the maximum is reached before the window closes, the swap ends early. + +**Optional Neurons' Fund participation:** The launch proposal can request matched funding from the Neurons' Fund, which contributes ICP proportional to direct participation up to a cap. + +After a successful swap, the SNS DAO is fully functional: the community governs the app through the governance canister and no single entity retains privileged control. + +## SNS canisters + +Each SNS consists of five core canisters and a variable number of archive canisters: + +| Canister | Purpose | +|---|---| +| **Governance** | Stores proposals and neurons; executes adopted proposals; calculates voting power and rewards. | +| **Ledger** | ICRC-1 token ledger for the SNS's governance token. | +| **Root** | Sole controller of the governed app canisters; orchestrates canister upgrades. | +| **Swap** | Runs the decentralization swap during launch. | +| **Index** | Organizes ledger transactions by account for wallet and explorer queries. | +| **Archive** (one or more) | Stores historical ledger blocks as the ledger grows. | + +## SNS neurons + +SNS neurons work similarly to NNS neurons, with a few differences: + +**All neurons are public.** Unlike NNS neurons, which can be private, all SNS neurons are fully readable by anyone. This makes vote delegation simpler: any neuron can follow any other. + +**Flexible permissions.** Instead of the NNS's controller/hotkey dichotomy, SNS neurons have a fine-grained permission system. Individual permissions (voting, changing following, managing principals, and others) can be granted to any principal independently. Frontends typically surface this as a simpler "add hotkey" interface, which maps to a specific set of permissions. + +**Configurable voting power.** Each SNS community configures the voting power calculation through its governance settings: +- Minimum dissolve delay to vote (default: 6 months). +- Maximum dissolve delay and the bonus it grants at that maximum (default: 8 years, 2x). +- Maximum age and the bonus it grants at that maximum (default: 4 years, 1.25x). + +**Maturity.** If an SNS activates voting rewards, neurons accumulate maturity that can be disbursed (minted as tokens), staked into the neuron for compounding, or auto-staked. The same maturity modulation mechanism as the NNS applies (±5% based on recent ICP/XDR rate movements). + +## SNS proposals + +SNS proposals follow the same lifecycle as NNS proposals (submission, voting, decision, automatic execution), with two notable differences: **proposal criticality** and **custom proposals**. + +### Critical and non-critical proposals + +SNS proposals are assigned to one of seven built-in topics. Each topic is classified as either critical or non-critical, and the classification determines the voting thresholds and period. + +**Critical topics** (require broader consensus): +| Topic | Description | +|---|---| +| Critical Dapp Operations | Adding or removing governed app canisters, executing critical app logic. | +| DAO Community Settings | Tokenomics and branding changes: token name, symbol, description. | +| Treasury and Asset Management | Moving treasury funds, managing liquidity pools, disbursing DAO-owned neurons. | + +Critical proposals pass only if at least 20% of total voting power votes yes and at least 67% of cast votes are yes. The voting period is 5–10 days (extended by wait-for-quiet for contested votes) and cannot be changed by the DAO. + +**Non-critical topics** (standard thresholds): +| Topic | Description | +|---|---| +| Application Business Logic | Custom proposals specific to the governed app. | +| Dapp Canister Management | Upgrading registered app canisters and frontend assets. | +| Governance | Community polls with no immediate code effect. | +| SNS Framework Management | Upgrading and managing the SNS framework canisters. | + +Non-critical proposals pass if at least 3% of total voting power votes yes and a simple majority of cast votes is yes. The default voting period is 4–8 days and is configurable per SNS. + +### Built-in proposals + +All SNS DAOs include a standard set of built-in proposal types: +- Motion proposals for community polls. +- Proposals to change governance settings and SNS metadata. +- Proposals to upgrade the SNS framework canisters. +- Proposals to register or deregister governed app canisters. +- Proposals to transfer treasury funds or mint new tokens. + +### Custom proposals + +Each SNS can register **custom proposals** (also called generic proposals) that call a specific method on a canister with specified arguments. This enables app-specific governance: an orchestrator canister upgrade, moderator election, or any other operation the DAO should control. + +Custom proposals require a validation method: when a custom proposal is submitted, the governance canister calls the validator first, and only proceeds if it succeeds. Custom proposals must be registered through a governance proposal before they can be used, giving the community a chance to audit the function being added. Each custom proposal must be assigned a topic when registered. + +## SNS voting rewards + +Each SNS independently decides whether to enable voting rewards, and if so, what rate to use. The configurable parameters are: + +- **`initial_reward_rate_basis_points` (r\_max):** The starting annualized reward rate as a fraction of total supply. +- **`final_reward_rate_basis_points` (r\_min):** The floor rate after the transition period ends. Set to 0 to stop new issuance after `t_delta`. +- **`reward_rate_transition_duration_seconds` (t\_delta):** How long the transition from r\_max to r\_min takes. + +The formula between `t_start` and `t_start + t_delta` is: `R(t) = r_min + (r_max − r_min) × [(t_start + t_delta − t) / t_delta]²`. After `t_start + t_delta`, the rate is constant at `r_min`. + +If `VotingRewardsParameters` is not set at all, voting rewards are disabled. + +User rewards (distributing existing treasury tokens to active app users) are a separate mechanism: an SNS-controlled canister holds a token reserve and pays out rewards according to its own logic. + +## Next steps + +- [Governance](governance.md): NNS and SNS overview, including neurons, proposals, and voting rewards +- [SNS DAO settings reference](../references/sns-dao-settings.md): all configurable nervous system parameters +- [Launch an SNS](../guides/governance/launching.md): step-by-step guide to the decentralization process +- [Manage a live SNS](../guides/governance/managing.md): proposals, upgrades, and treasury management after launch + + diff --git a/docs/guides/governance/managing.md b/docs/guides/governance/managing.md index 9a527df..ca931aa 100644 --- a/docs/guides/governance/managing.md +++ b/docs/guides/governance/managing.md @@ -121,7 +121,7 @@ type NervousSystemParameters = record { }; ``` -For a description of each parameter and its effect, see the Learn Hub [DAO Settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396) article. +For a description of each parameter and its effect, see the [SNS DAO settings reference](../../references/sns-dao-settings.md). ### ManageSnsMetadata @@ -617,7 +617,7 @@ Neurons are the staking units that give token holders voting power and a share o The SNS neuron staking flow is a two-step process: first transfer SNS tokens to the governance canister using the derived subaccount, then call `claim_or_refresh_neuron_from_account` on the SNS governance canister to claim the neuron. Note that this is distinct from NNS neuron staking, which uses NNS governance and the ICP ledger. -For information on neurons, dissolve delays, voting power bonuses, and reward mechanics, see the Learn Hub articles on [SNS Neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084687583252) and [SNS Rewards](https://learn.internetcomputer.org/hc/en-us/articles/34143058069396). +For information on neurons, dissolve delays, voting power bonuses, and reward mechanics, see [SNS framework](../../concepts/sns-framework.md#sns-neurons). ### Querying neuron state diff --git a/docs/references/nns-proposal-types.md b/docs/references/nns-proposal-types.md new file mode 100644 index 0000000..85842ab --- /dev/null +++ b/docs/references/nns-proposal-types.md @@ -0,0 +1,165 @@ +--- +title: "NNS Proposal Types" +description: "All NNS proposal topics and their proposal types, with descriptions" +--- + +NNS proposals are grouped into topics that determine their reward weight, voting period, and how neurons can delegate their votes. Each proposal type specifies which canister method is called on adoption. For background on how proposals work, see [Governance](../concepts/governance.md#proposals). + +## Topic: ProtocolCanisterManagement + +Manages canisters essential to the Internet Computer Protocol, including the NNS governance canister (`rrkah-fqaaa-aaaaa-aaaaq-cai`), NNS root (`r7inp-6aaaa-aaaaa-aaabq-cai`), the registry canister (`rwlgt-iiaaa-aaaaa-aaaaa-cai`), and the ICP ledger (`ryjl3-tyaaa-aaaaa-aaaba-cai`). + +| Proposal type | Description | +|---|---| +| `InstallCode` | Install, reinstall, or upgrade the code of an NNS-controlled canister. | +| `UpdateCanisterSettings` | Update the settings of an NNS-controlled canister. | +| `StopOrStartCanister` | Stop or start an NNS-controlled canister. | +| `HardResetNnsRootToVersion` | Emergency reset of the root canister to a specified Wasm. Intended as a break-glass mechanism when an open call context prevents normal upgrades. | + +## Topic: ServiceNervousSystemManagement + +Manages SNS canister code and the SNS Wasm modules canister (SNS-W, `qaa6y-5yaaa-aaaaa-aaafa-cai`). + +| Proposal type | Description | +|---|---| +| `InstallCode` | Same as in ProtocolCanisterManagement, targeting SNS canisters. | +| `UpdateCanisterSettings` | Same as in ProtocolCanisterManagement, targeting SNS canisters. | +| `StopOrStartCanister` | Same as in ProtocolCanisterManagement, targeting SNS canisters. | +| `AddSnsWasm` | Add a new SNS canister Wasm to SNS-W, making it available for SNS DAOs to upgrade to. | +| `InsertSnsWasmUpgradePathEntries` | Insert custom upgrade path entries into SNS-W for all SNSes or for a specific SNS. | + +## Topic: ApplicationCanisterManagement + +Manages NNS-controlled canisters not covered by the above topics. + +| Proposal type | Description | +|---|---| +| `InstallCode` | Same as ProtocolCanisterManagement, targeting application canisters. | +| `UpdateCanisterSettings` | Same as ProtocolCanisterManagement, targeting application canisters. | +| `StopOrStartCanister` | Same as ProtocolCanisterManagement, targeting application canisters. | +| `BitcoinSetConfig` | Set the configuration of the Bitcoin integration canister: fees, block syncing, API enablement. | + +## Topic: IcOsVersionElection + +Elects new IC OS versions before deployment. The IC OS has two layers: HostOS (the hypervisor running on physical hardware) and GuestOS (the VM containing the replica). + +| Proposal type | Description | +|---|---| +| `ReviseElectedGuestosVersions` | Add or remove GuestOS versions from the elected set. Identified by Git revision and installation image SHA-256. Only elected versions can be deployed to subnets. | +| `ReviseElectedHostosVersions` | Add or remove HostOS versions from the elected set. | + +## Topic: IcOsVersionDeployment + +Deploys previously elected IC OS versions to specific nodes or subnets. + +| Proposal type | Description | +|---|---| +| `DeployHostosToSomeNodes` | Deploy a HostOS version to a specified set of nodes. | +| `DeployGuestosToAllSubnetNodes` | Deploy a GuestOS version to all nodes in a subnet. | +| `DeployGuestosToSomeApiBoundaryNodes` | Update the GuestOS version on a set of API Boundary Nodes. | +| `DeployGuestosToAllUnassignedNodes` | Update the GuestOS version on all unassigned nodes. | + +## Topic: Governance + +Reward weight: 20 (higher than most topics, incentivizing participation). Covers governance of the Internet Computer itself. + +| Proposal type | Description | +|---|---| +| `Motion` | Opinion poll with no direct onchain effect. Used to signal community consensus on strategy. | +| `UninstallCode` | Uninstall code from a canister. | +| `SetDefaultFollowees` | Set the default following for newly created neurons. | +| `KnownNeuron` | Register or update a known neuron with a name, optional description, links, and committed proposal topics. | +| `DeregisterKnownNeuron` | Remove a neuron from the known neurons list. | + +## Topic: SnsAndCommunityFund + +Reward weight: 20. Covers SNS decentralization swaps and the Neurons' Fund. + +| Proposal type | Description | +|---|---| +| `CreateServiceNervousSystem` | Install a new SNS DAO and specify all settings: initial token distribution, decentralization swap conditions, initial governance parameters, and Neurons' Fund contribution. | + +## Topic: NetworkEconomics + +Economic parameters for the network and NNS DAO settings. + +| Proposal type | Description | +|---|---| +| `UpdateNodeRewardsTable` | Update the table used to calculate node provider rewards by region. | +| `NetworkEconomics` | Update one or more economic parameters: reject cost, minimum neuron stake, neuron management fee, minimum ICP/XDR rate, spawned neuron dissolve delay, maximum node provider rewards, transaction fee, maximum proposals per topic, Neurons' Fund economics, and voting power parameters. | +| `ClearProvisionalWhitelist` | Remove principals from the bootstrapping whitelist that allows canister creation without cycles. Intended for use after mainnet initialization only. | + +## Topic: SubnetManagement + +Subnet topology, configuration, and canister routing. + +**Subnet creation and composition:** + +| Proposal type | Description | +|---|---| +| `CreateSubnet` | Create a new subnet from a set of nodes, triggering distributed key generation. | +| `UpdateConfigOfSubnet` | Update a subnet's protocol configuration (message sizes and similar consensus-level parameters). | +| `AddNodeToSubnet` | Add an unassigned node to a subnet. | +| `RemoveNodesFromSubnet` | Remove nodes from a subnet, making them available for reassignment. | +| `ChangeSubnetMembership` | Atomically add and remove nodes (node swap) in a single operation. | +| `RecoverSubnet` | Update a subnet's recovery catch-up package to recover a stalled subnet. | + +**Firewall rules:** + +| Proposal type | Description | +|---|---| +| `SetFirewallConfig` | Set firewall configuration in the registry. | +| `AddFirewallRules` | Add firewall rules. | +| `RemoveFirewallRules` | Remove firewall rules. | +| `UpdateFirewallRules` | Update firewall rules. | + +**Subnet type and canister routing:** + +| Proposal type | Description | +|---|---| +| `SetAuthorizedSubnetworks` | Authorize a principal to use specific subnets for canister creation via the Cycles Minting Canister. | +| `UpdateSubnetType` | Update the available subnet types in the Cycles Minting Canister. | +| `ChangeSubnetTypeAssignment` | Change which subnets are assigned to which subnet type. | +| `UpdateSnsWasmSnsSubnetIds` | Update the list of subnet IDs where SNS-W deploys new SNS instances. | +| `RerouteCanisterRanges` | Update the registry routing table (which canister ID ranges are on which subnet). | +| `PrepareCanisterMigration` | Insert canister migration entries for a subnet split. | +| `CompleteCanisterMigration` | Remove canister migration entries after a split completes. | + +## Topic: ParticipantManagement + +Node provider and data center identities. + +| Proposal type | Description | +|---|---| +| `AddOrRemoveDataCenters` | Add or remove data center records in the registry. | +| `AddOrRemoveNodeProvider` | Assign or revoke an identity to a node provider, including legal entity information and jurisdiction. | + +## Topic: NodeAdmin + +Node machine administration. + +| Proposal type | Description | +|---|---| +| `AssignNoid` | Assign an identity to a node operator and set their remaining node allowance. | +| `UpdateNodeOperatorConfig` | Update a node operator's allowance or configuration in the registry. | +| `RemoveNodeOperators` | Remove a node operator from the registry. | +| `RemoveNodes` | Remove unassigned nodes from the registry. | +| `UpdateSshReadonlyAccessForAllUnassignedNodes` | Update SSH read-only access for all unassigned nodes. | + +## Topic: KYC + +Genesis neuron KYC verification. All neurons created after genesis have `kyc_verified = true` automatically, since they derive from already-KYC-verified balances. + +| Proposal type | Description | +|---|---| +| `ApproveGenesisKYC` | Set `kyc_verified = true` for a batch of genesis principals, enabling them to spawn neurons and disburse stakes. | + +## Topic: NeuronManagement (restricted voting) + +A special topic for collective management of a specific neuron. Only the target neuron's followers on this topic can vote, so proposals have a shorter-than-normal voting period. The standard restriction on following private neurons does not apply to this topic. + +| Proposal type | Description | +|---|---| +| `ManageNeuron` | Call a command on a specified target neuron. Only the target neuron's followers may vote. | + + diff --git a/docs/references/sns-dao-settings.md b/docs/references/sns-dao-settings.md new file mode 100644 index 0000000..48084aa --- /dev/null +++ b/docs/references/sns-dao-settings.md @@ -0,0 +1,72 @@ +--- +title: "SNS DAO Settings" +description: "Reference for all SNS nervous system parameters (NervousSystemParameters)" +--- + +Each SNS DAO is customized through its **nervous system parameters**, also called DAO settings. These parameters govern voting power calculation, governance rules, token economics, and reward behavior. Parameters are set at launch and can be changed by governance proposal at any time. + +For background, see [SNS framework](../concepts/sns-framework.md). + +## Neuron settings + +| Parameter | Type | Description | +|---|---|---| +| `neuron_minimum_stake_e8s` | `nat64` | Minimum number of e8s (10⁻⁸ of a token) that can be staked in a neuron. Must be larger than `transaction_fee_e8s`. | +| `max_number_of_neurons` | `nat64` | Maximum number of neurons allowed. New neurons are blocked once this ceiling is reached. Ceiling: 200,000. | +| `max_number_of_principals_per_neuron` | `nat64` | Maximum number of principals that can hold permissions for a single neuron. | +| `neuron_claimer_permissions` | permission set | The set of permissions automatically granted to the principal that claims a new neuron. | +| `neuron_grantable_permissions` | permission set | The superset of permissions that a principal with `ManagePrincipals` permission can grant to others on the same neuron. | +| `default_followees` | map | Default following rules applied to every newly created neuron, as a mapping of proposal function IDs to followee neuron IDs. | +| `max_followees_per_function` | `nat64` | Maximum number of followees a neuron can configure per proposal function. Ceiling: 15. | + +## Voting power settings + +| Parameter | Type | Description | +|---|---|---| +| `neuron_minimum_dissolve_delay_to_vote_seconds` | `nat64` | Minimum dissolve delay a neuron must have to be eligible to vote. Must be less than `max_dissolve_delay_seconds`. | +| `max_dissolve_delay_seconds` | `nat64` | Maximum dissolve delay achievable by a neuron. The dissolve delay bonus is saturated at this value. | +| `max_dissolve_delay_bonus_percentage` | `nat64` | Additional voting power percentage granted at maximum dissolve delay. Set to 100 for a 2x bonus (matching NNS behavior). Set to 0 for no bonus. | +| `max_neuron_age_for_age_bonus` | `nat64` | Maximum neuron age (seconds) at which the age bonus is saturated. | +| `max_age_bonus_percentage` | `nat64` | Additional voting power percentage granted at maximum age. Set to 25 for a 1.25x bonus (matching NNS behavior). Set to 0 for no bonus. | + +## Proposal and governance settings + +| Parameter | Type | Description | +|---|---|---| +| `reject_cost_e8s` | `nat64` | Fee (in e8s) charged to the proposer when a proposal is rejected, to discourage spam. | +| `initial_voting_period_seconds` | `nat64` | Initial voting period for non-critical proposals. The actual period may be extended by wait-for-quiet. Does not affect existing proposals. | +| `wait_for_quiet_deadline_increase_seconds` | `nat64` | Maximum total extension added by wait-for-quiet when a proposal outcome flips. The voting period can increase by at most twice this value. Does not affect existing proposals. | +| `max_proposals_to_keep_per_action` | `nat64` | Maximum number of proposals retained per proposal type. When exceeded, the oldest finalized proposals are eligible for deletion. Ceiling: 700. | +| `max_number_of_proposals_with_ballots` | `nat64` | Maximum number of open (unsettled) proposals with stored ballots. When reached, only a few critical proposal types can still be submitted. Ceiling: 700. | + +## Token and fee settings + +| Parameter | Type | Description | +|---|---|---| +| `transaction_fee_e8s` | `nat64` | Per-transfer fee on the SNS ledger, in e8s. Does not apply to minting or burning. | + +## Voting reward settings + +All reward settings live inside a single nested field: **`voting_rewards_parameters`**. If this field is absent, voting rewards are disabled. + +| Parameter | Full field name | Description | +|---|---|---| +| round duration | `round_duration_seconds` | Length of a single reward distribution round, in seconds. Rewards are distributed to voting neurons at the end of each round. Default: 86,400 (1 day). | +| r\_max | `initial_reward_rate_basis_points` | Starting annualized reward rate as a fraction of total supply, in basis points (100 = 1%). | +| r\_min | `final_reward_rate_basis_points` | Floor reward rate after the transition period, in basis points. Set to 0 to end issuance after `t_delta`. | +| t\_delta | `reward_rate_transition_duration_seconds` | Duration of the quadratic decline from r\_max to r\_min, in seconds. | +| t\_start | `start_timestamp_seconds` | Timestamp (Unix seconds) when reward accrual begins. Set automatically to the current time when rewards are first enabled. | + +## Maturity modulation + +| Parameter | Type | Description | +|---|---|---| +| `maturity_modulation_disabled` | `opt bool` | If true, maturity modulation is disabled for this SNS: the ±5% conversion randomness is not applied when neuron holders disburse maturity. The CMC is still polled but the fetched value is ignored. Default: false (modulation enabled). | + +## SNS framework upgrade + +| Parameter | Type | Description | +|---|---|---| +| `automatically_advance_target_version` | `opt bool` | If true, the SNS automatically upgrades to the latest NNS-approved SNS version without a governance proposal. Defaults to true for newly created SNSs, false for older ones. | + +