Difference between revisions of "Network Nervous System"

From Internet Computer Wiki
Jump to: navigation, search
Line 4: Line 4:
 
'''While other blockchains take weeks or months to upgrade (sometimes called hard fork) and typically require substantial manual work and coordination to do so, the IC upgrades itself on a weekly basis (https://dashboard.internetcomputer.org/releases). Its ability to upgrade and iterate is a comparative "superpower."'''
 
'''While other blockchains take weeks or months to upgrade (sometimes called hard fork) and typically require substantial manual work and coordination to do so, the IC upgrades itself on a weekly basis (https://dashboard.internetcomputer.org/releases). Its ability to upgrade and iterate is a comparative "superpower."'''
  
−
The NNS is realized by a set of ''[[canisters|canisters]]''.  
+
The NNS works by allowing users to stake ICP governance tokens to create voting neurons. Anyone can create a neuron, which together exert the will of the community, mediated through algorithms. Neurons are like accounts where notice of withdrawals must be given, where the length of the notice period is a configuration known as the “dissolve delay.” The voting power of neurons, and their relative claim to voting rewards, is proportional to the quantity of staked ICP, the length of the configured dissolve delay, and their “age.” Neurons can be made to vote manually, or automatically, by following other neurons in a form of liquid democracy.
  
−
==NNS canisters==
+
Neuron holders are placed in a cryptoeconomic game, where they are incentivized to vote to adopt and reject proposals, or to configure neuron follows that cause them to vote automatically in a desirable way, according to what is most likely to drive the value of the Internet Computer network over the long term.
−
# '''Ledger canister:''' The ledger canister stores the ICP utility ''token balance'' of each principal and the history of ICP ''transactions''.
 
−
# '''Governance canister:''' The governance canister receives and stores ''Proposals'', which are suggestions for how the Internet Computer should be changed. These proposals can then be voted on. The governance canister also tracks ''Neurons'', which determine who is allowed to participate in governance.
 
−
# '''Registry canister:''' The registry canister stores the configuration of the whole Internet Computer, e.g., which nodes belong to a certain subnet and the software each node should run.
 
−
# '''Cycles minting canister''': This canister is responsible for minting ''cycles'', the fuel for canisters for computation, communication and storage. New cycles can be minted when a new canister is newly created or when an existing canister is topped up with additional cycles.
 
−
# '''Root canister''': The root canister is the controller of all other NNS canisters and responsible for upgrading them.
 
−
# '''Lifeline canister''': The lifeline canister is the controller of the root canister and responsible for upgrading it.
 
−
# '''Archive canisters''': The canisters that store the history of the ledger transactions once there are too many transactions to keep in a single canister.
 
−
#'''Genesis token canister:''' This is the canister that was used to initialize the neurons that already existed during genesis.
 
  
−
The canisters that users of the Internet Computer are interacting with the most are the first two: the ledger canister for making transactions, and the governance canister for staking tokens and submitting and voting on proposals.
+
This is the first time in history when a decentralized infrastructure will self-direct with the aim of competing with proprietary centralized infrastructures run by commercial organizations with leaders and boards.
  
−
==Ledger canister & ICP utility tokens in the NNS==
+
=== Overview ===
−
[[ICP token|ICP utility tokens]] are managed by the ledger canister, which stores two things: accounts and transactions. An account record keeps track of how many tokens are in the possession of a given [[principal]] (i.e., an identity by which a user is authenticated on the Internet Computer). Tokens can then be sent from one account to another, and this is recorded in the transactions of the ledger canister.
+
The purpose of the NNS is to allow the Internet Computer network to be governed in an open, decentralized, and secure manner. It has complete control over all aspects of the network. For example, it can upgrade the protocol and software used by the node machines that host the network; it can create new subnet blockchains to increase network capacity; it can split subnets to divide their load; it can configure economic parameters that control how much must be paid by users for compute capacity; and, in extreme situations, it can freeze malicious canister smart contract software in order to protect the network; and many other things. The NNS works by accepting proposals, and deciding to adopt or reject them based on voting activity by “neurons” that network participants have created.
  
−
In the NNS, ICP utility tokens are used for three different things:
+
Neurons are also used by participants to submit new proposals. After submission, proposals are either adopted or rejected, which can happen almost immediately, or after some delay, depending upon how the totality of neurons vote. Each proposal is an instance of a specific “proposal type,” which determines what information it contains. For each type of proposal, the NNS maintains a corresponding system function, which it invokes whenever a proposal of that type is adopted. When a proposal is adopted by the NNS, it invokes the corresponding system function by drawing information from the proposal’s content to fill the parameters. Each type of proposal belongs to a specific “proposal topic,” such as “#NodeAdmin” or “#NetworkEconomics,” which determines details about how it will be processed.To prevent users (neurons) from spamming the NNS with proposals, a fee is levied on the neuron that submitted a proposal if it is rejected.
  
−
# ICP tokens facilitate '''participation in governance''' (more below on how the neurons are connected with the tokens).
+
The NNS decides whether to adopt or reject proposals by watching how neurons emit votes. Anyone can create a neuron by locking balances of the Internet Computer’s native utility token (ICP) that is hosted on a ledger inside the NNS. When a user creates a neuron, the locked balance of ICP can only be unlocked by disbursing (“destroying”) the neuron. Users are incentivized to create neurons because they earn rewards when they vote on proposals. Rewards take the form of newly minted ICP that are created by the NNS. The quantity of ICP rewards disbursed to a neuron derive from such factors as the size of the locked balance, the minimum lockup period remaining (the “dissolve delay”), the neuron’s “age,” the proportion of possible votes it has participated in, and the sum of voting activity across all neurons, since the overall total rewards disbursed is capped and must be divided between voters.
−
# Those who participate in governance and those who provide compute capacity by operating note machines are '''rewarded''' in ICP tokens.
 
−
# ICP tokens are used for '''conversion into cycles''', which are fuel for canisters for computation, communication and storage.
 
  
−
==Governance Canister==
+
At any moment, each neuron has a currently configured “dissolve delay.” This determines how long it will take to dissolve if it is placed into “dissolve mode.” Once a neuron has been placed into “dissolve mode,” its dissolve delay falls over the passage of time, rather like a kitchen timer, until it reaches zero, whereupon its owner can perform a final disburse action to unlock the balance of ICP. The dissolve delay creates an economic incentive for neuron owners to vote with a view toward maximizing the value of their locked ICP balances at a future date. ICP is a proxy for the success of the network over the long term, sans short-term volatility, this creates an economic incentive to vote in the best interests of the network. Neuron owners can freely configure higher dissolve delays, up to a maximum delay of eight years, but cannot decrease the dissolve delay other than by the natural passage of time. The NNS pays higher voting rewards the higher the dissolve delay, encouraging users to enter a game in which an economic incentive is created to vote according to a very long-term vision.
−
The governance canister is responsible for holding ''neurons'', determining who is allowed to participate in governance. Moreover, it stores proposals, which are suggestions for changes to the Internet Computer, and the information associated with proposals that decides if these suggestions should be implemented. If a proposal is adopted, the governance canister automatically executes the decision. Finally, the governance canister distributes rewards to those neurons who participated in voting and contributed to the decision making.
 
  
−
==Neurons==
+
Neuron owners may find it hard to manually vote directly on every proposal submitted to the NNS. Firstly, large volumes of proposals may be submitted to the NNS, often at awkward times, and owners may not be available or have the necessary time to evaluate each one. Secondly, neuron owners may lack the necessary expertise to evaluate proposals themselves. The NNS uses a form of liquid democracy to address these challenges. For any proposal topic, a neuron can be configured to vote automatically by following the votes of a group of neurons, voting to adopt proposals whenever more than half of the followees vote to adopt, and voting to reject whenever at least half of the followees vote to reject. A catch-all follow rule may also be defined to make a neuron vote automatically on proposals with topics for which no follow rule has been defined. It is assumed that neuron owners will manage how their neurons follow other neurons in the best interests of the network, which is also in their own economic interests, owing to their locked ICP balances.
−
Neurons contain ''locked'' ICP utility tokens. These staked tokens are not liquid and cannot be transferred freely to others.
 
  
−
===Neuron Attributes===
+
It is expected that a large proportion of the overall supply of ICP will be locked in order to earn rewards. This secures the Internet Computer’s network governance, by making it both difficult and exorbitantly expensive for an attacker to acquire a sufficiently large stake to gain significant influence. Since neuron owners may wish to maximize their rewards by voting on all proposals, most neurons will either be actively managed or configured to follow other neurons so that they can vote automatically. In practice, once trusted neurons have voted on proposals, a majority of the other neurons will also vote as the result of cascading follow relationships. This means that the NNS can usually quickly determine whether a majority of the overall voting power represented by all neurons wishes to adopt or reject a proposal, and decide on the proposal accordingly. However, the NNS cannot depend on obtaining such a majority since, in principle, neuron owners may not define follow rules, or they may simply choose not to vote.
−
Each neuron stores a number of neuron attributes. Some of the most important ones are the following:
 
  
−
* How many ICP tokens are ''locked'' in the neuron. This information is accessible both by a neuron referencing an account on the ledger canister that stores the neuron's balance and by a cached stake on the governance canister.
+
== Proposals ==
−
* A ''controller'' principal, which identifies who manages the neuron's actions.
+
=== Format ===
−
* A unique ''neuron ID''
+
Each proposal submitted to the NNS has the following fields:
−
*The neuron's ''dissolve delay.'' Intuitively, the dissolve delay defines the earliest time when the locked ICP tokens can be unlocked. This time can be increased to up to 8 years but it can only be decreased by waiting for time to pass. A neuron can either be ''non-dissolving'', ''dissolving'', or ''dissolved.'' If a neuron is non-dissolving, its set dissolve delay is kept stable and the timer is not running down. The neuron can then be set to dissolving, which means that the dissolve delay is decreasing with the time. Finally, if a the dissolve delay reaches 0, the neuron is dissolved and the locked tokens can be transferred out of the neuron.
 
−
*The ''age'', which is between 0 and 4 years. A neuron's age determines the time since when then neuron has last entered the non-dissolving state.
 
−
A neuron's dissolve delay determines a neuron's ''eligibility'' to participate in voting. Namely, only those neurons with tokens locked for at least six months are eligible to participate in governance. This incentivizes neuron holders to vote such that the value of their tokens is maximized for a future date. Assuming the value of the tokens is a rough proxy for the network’s success, this incentivizes neuron holders to vote in the long-term interest of the Internet Computer.
 
  
−
A neuron's ''voting power'' depends on how many tokens a neuron has locked, as well as the neuron's dissolve delay and age. Intuitively, those who are more committed to the Internet Computer, as they have locked their tokens for longer or have already staked them for a long time, have more voting power. The voting power increases with the dissolve delay and the age.
+
* '''Summary:''' Text providing a short description of the proposal, composed using a maximum of 280 bytes.
 +
* '''URL:''' The web address of additional content required to evaluate the proposal, specified using HTTPS. For example, the address might describe content 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. So the balance needs to be big enough to pay the charge on (all) rejection(s). We require a neuron to have a dissolve delay ≥ 6 months to vote, and this applies to submitting proposals too.
 +
* '''Proposal Type:''' The type of the proposal. This infers what topic it belongs to (e.g., #NodeAdmin), the system function that will process the proposal if it is adopted, and the type and structure of the parameters that will be passed to that function.
 +
* '''Parameters:''' The parameters that will be passed to the system function that will be invoked if the proposal is adopted, as determined by its type. When a proposal is submitted, the NNS checks the parameters.
 +
The NNS assigns a unique identity to each proposal that it receives.
  
−
Finally, the number of rewards that each neuron receives depends on the number of votes that the neuron participated in as well as the neuron's voting power.
+
The NNS assigns a unique identity to each proposal that it receives.
  
−
===How to lock tokens in a neuron<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref>===
+
=== Topics ===
 +
The topic of a proposal, which is inferred from its type, determines how it will be processed. For example, the NNS may require voters to have a greater degree of agreement, or to try to process proposals faster, for some topics. Also, neurons follow other neurons on a per-topic basis. Initial topics include:
  
−
As a user, there are different [[ICP staking options]] to stake ICP utility tokens in a neuron. The effect of such an operation is that these ICP tokens are transferred to a ledger account that is associated with a newly created neuron. The tokens are thus locked and cannot be used freely by the neuron holder.
+
* '''#NeuronManagement:''' A special topic by means of which a neuron can be managed by the followees for this topic (in this case, there is no fallback to default). Votes on this topic are not included in the voting history of the neuron. For proposals on this topic, only the neuron’s followees on the topic that the proposals pertain to are allowed to vote. Because the set of eligible voters of proposals on this topic is restricted, proposals on this topic have a shorter than normal voting period.
 +
* '''ExchangeRate:''' All proposals provide information in “real time” about the market value of ICP, as measured by an International Monetary Fund (IMF) Special Drawing Right (SDR) , which allows the NNS to convert ICP to cycles (which power computation) at a rate that keeps their real-world cost constant. Because proposals on this topic are very frequent, they have a shorter voting period, and votes on this topic are not included in the voting history of the neuron.
 +
* '''#NetworkEconomics:''' Proposals that administer network economics — for example, determining what rewards should be paid to node operators.
 +
* '''#Governance:''' All proposals that administer governance — for example, motions and the configuration of certain parameters.
 +
* '''#NodeAdmin:''' All proposals that administer node machines somehow, including but not limited to upgrading or configuring the OS, upgrading or configuring the virtual machine framework, and upgrading or configuring the node replica software.
 +
* '''#ParticipantManagement:''' All proposals that administer network participants — for example, granting and revoking DCIDs (data center identities) or NPIDs (node provider identities).
 +
* '''#SubnetManagement:''' All proposals that administer network subnets — for example, creating new subnets, adding and removing subnet nodes, and splitting subnets.
 +
* '''#NetworkCanisterManagement:''' Installing and upgrading “system” canisters that belong to the network — for example, upgrading the NNS.
 +
* '''#KYC:''' Proposals that update KYC information for regulatory purposes — for example, during the initial Genesis distribution of ICP in the form of neurons.
 +
* '''#NodeProviderRewards:''' Topic for proposals to reward node providers.
  
−
'''Example.''' ''Let’s assume that User B, who has an account (A1) on the ledger canister, would like to lock a hundred tokens in a neuron. To do so, User B sends a command to the NNS specifying the number of tokens and User B’s corresponding principal ID.''
+
=== Types ===
 +
Initial proposal types include:
  
−
''A transaction is then recorded on the ledger, which specifies that some tokens are sent from the original account (A1) of the user to a new account (A2), which also creates the new account (A2) that holds the locked tokens. A new neuron is created in the governance canister that specifies that User B is the one controlling this neuron and that specifies that the amount of locked tokens is defined by the new ledger account A2.''
+
* '''ManageNeuron (#NeuronManagement, Restricted Voting)''' This type of proposal calls a major function on a specified target neuron. Only the followees of the target neuron may vote on these proposals, which effectively provides the followees with control over the target neuron. This can provide a convenient and highly secure means for a team of individuals to manage an important neuron. For example, a neuron might hold a large balance, or belong to an organization of high repute, and be publicized so that many other neurons can follow its vote. In both cases, managing the private key of the principal securely could be problematic. (Either a single copy is held, which is very insecure and provides for a single party to take control, or a group of individuals must divide responsibility — for example, using threshold cryptography, which is complex and time consuming). To address this using this proposal type, the important neuron can be configured to follow the neurons controlled by individual members of a team. Now they can submit proposals to make the important neuron perform actions, which are adopted if and only if a majority of them vote to adopt. (Submitting such a proposal costs a small fee, to prevent denial-of-service attacks.) Nearly any command on the target neuron can be executed, including commands that change the follow rules, allowing the set of team members to be dynamic. Only the final step of dissolving the neuron once its dissolve delay reaches zero cannot be performed using this type of proposal, since this would allow control/“ownership” over the locked balances to be transferred. (The only exception to this rule applies to not-for-profit organizations, which may be allowed to dissolve their neurons without using the initial private key.) To prevent a neuron falling under the malign control of the principal’s private key by accident, the private key can be destroyed so that the neuron can only be controlled by its followees, although this makes it impossible to subsequently unlock the balance.
  
−
''Externally, it’s not visible that the new account (A2) holds locked tokens or is in any way related to the original account (A1). Nevertheless, this account is in fact controlled by the neuron, which means that the tokens are not liquid and that User B cannot transfer the tokens or convert the tokens into cycles.''
+
* '''ManageNetworkEconomics (#NetworkEconomics)''' This is a single proposal type which can update one or several economic parameters:
 +
**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 creation of a neuron. The same limit must also be respected when increasing 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/SDR rate: To prevent mistakes, there is a lower bound for the ICP/SDR 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.
  
−
The main reason for a user to lock tokens in a neuron is to be able to participate in voting and get voting rewards. Both are described in more detail below.
+
* '''Motion (#Governance)''' A motion is a text that can be adopted or rejected. No code is executed when a motion is adopted. An adopted motion should guide the future strategy of the Internet Computer ecosystem.
  
−
==Proposals==
+
* '''ApproveGenesisKYC (#KYC)''' When new neurons are created at Genesis, they have 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.
−
A proposal is a suggestion for a change to the Internet Computer. More technically, a proposal describes a ''method'' in a canister that is called if the proposal is accepted. Moreover, it describes the ''parameters'' with which the method will be called.
+
(Special note: 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.)
  
−
The Internet Computer supports a variety of different proposal ''topics''. Here are some examples of topics that are supported in the NNS governance canister:
+
* '''AddOrRemoveNodeProvider (#Participant Management)''' Assign (or revoke) an identity to a node provider, associating key information regarding the legal person associated that should provide a way to uniquely identify it.
−
* #SubnetManagement Proposals: This considers topology changes. The example proposal above about whether a node should be added to a subnet falls into this category.
 
−
* #NodeAdmin Proposals: This concerns the administration of node machines. An example of a proposal could specify that all of the nodes in a subnet should be updated.
 
−
* #NetworkEconomics Proposals: This concerns the administration of network economics. For example: what rewards should be paid to the node machine providers?
 
−
*#Motion Proposals: These proposals do not have a direct execution of a method as a consequence but are merely there to record the opinion of the community on a specified matter.
 
  
−
==Voting and proposal lifecycle==
+
* '''RewardNodeProvider (#NodeProviderRewards)''' Propose to reward a Gen-1 node provider an amount of ICP as compensation for providing Gen-1 nodes to the IC.
  
−
=== Submitting a proposal ===
+
* '''SetDefaultFollowees (#Governance)''' Specify the list of followees that a freshly created neuron should have.
−
Any eligible neuron can make and [https://wiki.internetcomputer.org/index.php?title=Neuron_Attributes_and_Commands#Make_Proposal submit a proposal]. To avoid being inundated by useless proposals, a user submitting a proposal has to pay a fee of 1 ICP when submitting a proposal, that they will receive back if the proposal is adopted (but that they will not receive back if the proposal is rejected).
 
  
−
'''Example.''' ''Let’s consider a User C who would like to suggest that a new subnet is created that initially consists of two nodes: Node 1 and Node 2. Once User C controls a neuron, they can submit a proposal by specifying their neuron ID, the type of proposal that they would like to submit, and the proposal’s parameters. In our example, the proposal specifies that a new subnet should be created and the proposal's parameters consist of the initial nodes Node 1 and Node 2. Upon the receipt of this proposal, the governance canister first checks that this user is indeed the one controlling the neuron with the given ID and that this neuron is eligible to vote. If the requirements are met, the proposal is added to the governance canister.''
+
The following is a list of proposal types that call other NNS canisters:
  
−
After a proposal is submitted by an eligible neuron, the proposal is created and stored in the governance canister. Moreover, the governance canister computes and stores additional information with each proposal. First, the [[voting power]] of each neuron is computed and stored together with the proposal. The sum of all of these voting powers also determines the ''total voting power'' associated with a given proposal.
+
* '''CreateSubnet (#SubnetManagement)''' 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 decentralized subnet. The execution of this external update 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 initial configuration information for the subnet, from where the nodes comprising the subnet pick it up.
  
−
When a new proposal is created, the number of “yes” votes associated with the proposal is already increased by the proposer’s voting power. This reflects that the proposal already has the support of the user submitting it.
+
* '''AddNodeToSubnet (#SubnetManagement)''' 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.
  
−
Moreover, each proposal has an associated ''voting period,'' which determines the period of time over which votes for this proposal are accepted.
+
* '''InstallNetworkCanister (#NetworkCanisterManagement)''' A proposal to add a new canister to be installed and executed in the NNS subnetwork. The root canister, which controls all canisters on the NNS except for itself, handles this proposal type. The call also expects the Wasm module that shall be installed.
  
−
===Viewing NNS Proposals===
+
* '''UpgradeNetworkCanister (#NetworkCanisterManagement)''' A proposal to upgrade an existing canister in the NNS subnetwork. This proposal type is executed by the root canister. Beyond upgrading the Wasm module of the target canister, the proposal can also set the authorization information and the allocations.
−
You can see all the NNS proposals on the Internet Computer dashboard: https://dashboard.internetcomputer.org/governance
 
  
−
===Discussing NNS Proposals===
+
* '''BlessReplicaVersion (#NodeAdmin)''' A proposal to bless a new version to which the replicas can be upgraded. The proposal registers a replica version (identified by the hash of the installation image) in the registry. Besides creating a record for that version, the proposal also appends that version to the list of “blessed versions” that can be installed on a subnet. By itself, this proposal does not effect any upgrade. (In the future, there will only be one blessed version of the replica software at any given time.)
−
Voters can freely discuss proposal anywhere they like. A lot of NNS proposals are discussed on the developer forum: https://forum.dfinity.org/c/roadmap/29.
 
  
−
===Voting on a proposal===
+
* '''RecoverSubnet (#SubnetManagement)''' 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.
−
After a proposal is submitted and added to the governance canister, other users who control neurons can [[ICP voting options|vote on the proposal]]. Currently, the most user-friendly way to vote on NNS proposals is via the NNS Frontend dapp: https://nns.ic0.app/. For voting, users would first learn which are the open proposals on the governance canister that they can actually vote on. This information is available, for example on Internet Computer dashboard: https://dashboard.internetcomputer.org/governance or in the [[NNS frontend dapp]].  
+
UpdateSubnetConfig (#SubnetManagement)
 +
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).
  
−
If a neuron votes in favor of a proposal, the governance canister adds this neuron’s voting power, as stored with the proposal, to the “Yes”-votes associated with the proposal. Likewise, if a neuron votes against a proposal, the governance canister adds the neuron’s voting power to the “No”-votes of the proposal.
+
* '''AssignNPID (#ParticipantManagement)''' Assign an identity to a node operator 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 IC. When an additional node is added by the node operator, the remaining allowance is decreased.
  
−
'''Example.''' ''Assume that a given User D would like to reject the proposal that was just added by User C. To do so, User D would send their neuron ID and a “no” vote to the governance canister. The governance canister would check that the vote is coming from the correct user who controls the neuron and confirm that the neuron is eligible to vote. If the conditions are met, the governance canister would then add the voting power of User D to the “no” votes.''
+
* '''RootUpgrade (#NetworkCanisterManagement)''' A proposal to upgrade the root canister in the NNS subnetwork. The proposal is processed by the Lifeline canister, which controls the root canister. The proposal updates the Wasm module as well as the authorization settings.
  
−
====Neuron following and liquid democracy====
+
* '''SetICPSDR (#ExchangeRate)''' Instruct the NNS about the market value of 1 ICP as measured by an IMF SDR. This setting affects cycles pricing (as the value of cycles shall be constant with respect to IMF SDRs).
−
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 of delegating the right to vote to other voters who then effectively vote with more voting power is called ''liquid democracy.''
 
  
−
Concretely, for each proposal topic a neuron can [[How to follow neurons|specify a set of other neurons that it would like to ''follow'']] ''(so-called followees)''. In addition, a neuron can specify a set of followees for "all other topics" that are not covered by specific rules. The governance canister keeps track of this relation of follower and followee neurons. It then automatically casts a vote for a follower neuron based on the decision of the followees. In particular, if more than 50% of the followees vote "yes", then a "yes" vote is cast for the follower and if at least 50% of the followees vote "no", then a "no" vote is cast for the follower.  
+
* '''UpgradeSubnetToReplicaVersion (#SubnetManagement)''' Update the replica version running on a given subnet. The proposal changes the replica version that is used on the specified subnet. The version must be contained in the list of blessed replica versions. The upgrade is performed when the subnet creates the next regular CUP.
  
−
'''Example'''. ''Consider neuron N1 that follows the set of neurons {N2, N3, N4, N5} on all proposal topics. Consider now that a proposal is submitted by another neuron N6. Assume in a first scenario that first N2 votes "No" and then N3 votes "No" on the proposal. In that case, the governance canister will also send a "No" vote for N1 two out of four followees voted "No" (which also means that it is not possible anymore to get more than 50% "Yes" votes). Assume a second scenario where N2 votes "Yes" and then N3 votes "Yes" on the proposal. In that case, no vote is sent yet for N1. However, if either N4 and N5 also send a "Yes" vote, a "Yes" vote is also cast for N1.''
+
* '''ClearProvisionalWhitelist (#NetworkEconomics)''' Clears the provisional whitelist, which allows the listed principals to create canisters with cycles. The mechanism is only needed for bootstrap and testing and must be deactivated afterward.
  
−
This liquid democracy has great advantages. First, it allows even neurons that do not have enough knowledge of a certain topic to nevertheless participate in governance by choosing the neurons that they trust with certain decisions and by delegating their vote to them. In particular, a neuron can choose a different set of followees for different topics. Moreover, this mechanism allows neuron holders to get voting rewards from voting participation even if they do not have time to actively participate in all voting decision.
+
* '''RemoveNodeFromSubnet (#SubnetManagement)''' 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.
  
−
=== Proposal decision and wait-for-quiet ===
+
* '''SetAuthorizedSubnetworks (#Governance)''' 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.
−
A proposal can be ''decided'' in two ways:
 
−
# '''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.
 
−
# '''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.
 
  
−
What also plays into this is the fact that the governance voting algorithm also applies ''wait-for-quiet''. 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.
+
* '''SetFirewallConfig (#SubnetManagement)''' Change the Firewall configuration in the registry (configures which boundary nodes subnet blockchain replicas will communicate with).
  
−
=== Proposal execution ===
+
* '''UpdateNodeOperatorConfig (#NodeAdmin)''' Change a node operator’s allowance in the registry.
−
Recall that a proposal defines a method, a canister, and some parameters. As soon as a proposal is adopted, the defined method on the specified canister is called with the given parameters. This is done fully automatically by the governance canister.  
 
  
−
== Voting Rewards ==
+
* '''StopOrStartNNSCanister (#NetworkCanisterManagement)''' Stop or start an NNS canister.
−
Contributing to decision-making is one incentive for voters to lock their neurons, but they are also ''rewarded'' for participating in network governance.
 
  
−
Specifically, each day the governance canister considers which proposal can be settled. It is then considered for each neuron in how many proposals they participated and with which voting power. Depending on this, the neurons get rewarded. Concretely, rewards are added to the neuron's attribute that is called ''maturity.'' Maturity represents ICP utility token that are not yet minted.
+
== ICP tokens ==
 +
ICP are native utility tokens that play three key roles in the network:
  
−
A neuron holder can then profit from the maturity in two ways:
+
# '''Facilitating Network Governance''' ICP tokens can be locked to create neurons that participate in network governance by voting, through which they can earn economic rewards.
  
−
# '''Spawn maturity:''' A neuron holder can choose to [[How to spawn a neuron|spawn a new neuron]] to get liquid ICP utility tokens worth the voting rewards. Spawning a new neuron has the effect that a new neuron with a new associated account on the ledger will be created, which contains the amount of staked ICP utility token equivalent to the maturity of the original neuron. In fact, the new tokens are minted and transferred to the new account, which is also recorded in the ledger canister. The new neuron has a small dissolve delay of 7 days. This means that users only need to wait a short amount of time to be able to unlock the tokens and use them freely, no matter what dissolve delay the original neuron has.
+
# '''Production of Cycles for Compute''' ICP provides a source store of value that can be converted into “cycles,” which power computation in the role of fuel that is burned when it is used. The NNS converts ICP to cycles at a variable rate, so chosen to ensure users of the network can always create new cycles at approximately constant cost in real terms, such that the cost of acquiring fuel is predictable.
−
# '''Merge maturity''': A neuron holder can choose to [[merge maturity]] to reinvest the voting rewards in the existing neuron. This neuron operation adds the ICP utility token equivalent of the maturity to the neuron's stake and adjusts the neuron's age accordingly. Effectively this means that the maturity is reinvested in the neuron and contributes to the neuron's voting power.
 
  
 +
# '''Rewarding Participants''' The network mints new ICP to reward and incentivize those playing important roles that enable the network to function, including: a) the provision of “voting rewards” to those participating in governance, and b) the provision of “node provider rewards” to those operating the node machines that are hosting the network.
  
−
==Cycles Minting Canister and Cycles<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref>==
+
== Ledger ==
−
Besides governance participation and voting rewards, tokens can also be converted into cycles, which fuel computation and storage on the Internet Computer. Each canister on the Internet Computer, except for those on the NNS, uses cycles for computations and has some cycles stored within it. While the token price may vary over time, the goal of the cycles is to keep the price of computation roughly consistent over time.
+
The ICP ledger is hosted within the NNS, and records all balances of ICP in the manner of a spreadsheet. Each row is called an “account,” which has two fields (i.e., there are two “columns”):
  
−
The canister responsible for converting ICP utility tokens into cycles is the ''Cycles Minting Canister.'' To convert cycles for creating or topping-up a canister, a user needs to send ICP utility tokens to the Cycles Minting Canister. This canister then burns the tokens and mints the cycles.  
+
# '''Account identifier (bytes)''' A unique value that is derived from the identity of the “principal” that “controls” the account. Currently, the principal must either be: (i) the owner of a public key pair, or (ii) a canister smart contract that is part of the NNS. Account identifiers are derived by hashing the concatenation of a domain separator, the principal ID, and the subaccount (or zeros if no subaccount is given).
  
−
The Cycles Minting Canister only facilitates the conversion of ICP utility tokens to cycles but not the other way around. Cycles are burned in canisters when they use computation and storage over time.  
+
# '''Balance''' (positive integer, representing one hundredth of a millionth of an ICP) The quantity of ICP assigned to the principal of the account.
  
−
'''Example.''' ''Consider User E who runs a canister on the Internet Computer and would like to top up the cycles of this canister so that it can perform even more computations. Also assume that this canister currently has 700 trillion cycles and User E would like to increase this number by 200 trillion. To do so, the user would send a command to the NNS that specifies the action of topping up their canister. Upon receiving this command, a transaction is made from the user’s account to the Cycles Minting Canister. As a result of this transaction, the Cycles Minting Canister would burn the tokens, mint new cycles, and send these freshly minted cycles to the user’s canister, meaning the canister balance is now 900 trillion cycles.''
+
When the principal is a public key or Canister, they can apply the following operation to an account:
  
−
==See also==
+
# '''Send''' Send a portion of the ICP balance to another account. If all the ICP is sent to another account, then the sending account ceases to exist (i.e., is deleted from the ledger).
 +
# '''Notify''' When the destination of the funds sent is the account of an NNS canister (e.g., an account of the governance canister), the sender can ask the ledger to notify the recipient canister of the incoming transfer. The recipient canister can then act on this notification. Two examples where this ability is used are creating a neuron and refreshing the stake of a neuron. These are detailed below.
  
−
* [https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a Medium article]
+
Operations that require interaction between the ledger and the governance system (Neurons):
−
* [https://dfinity.org/howitworks/network-nervous-system-nns Video]
 
  
−
=References=
+
# '''Create neuron''' When the principal is a public key holder, they may lock a portion of their balance inside a new neuron. Technically, creating the neuron is done in two stages. First transfer the ICP to be staked to an account of the governance canister (which corresponds to a new neuron — the details of the association are omitted here). Then notify the governance canister of the incoming transfer which updates its internal neuron bookkeeping. If the entire balance is locked inside a new neuron, the account ceases to exist (i.e., is deleted from the ledger). To move these ICP to a different account, such as back to the original account, where they can once again be controlled like a normal balance, the associated neuron must be fully dissolved and disbursed (destroyed). The new neuron that has been created is controlled by the private key of the principal that created it.
 +
# '''Refresh stake''' The stake of a neuron may be increased by transferring to its address/account in the ledger and notifying the governance canister of the incoming transfer. Refreshing the stake will change the maturity and age of the neuron prorated. For example, if the stake is doubled, the maturity and age will be halved, so spawning will yield the same amount and the age bonus will be the same as before (in absolute terms).
 +
 
 +
== Neurons ==
 +
 
 +
A neuron locks a balance of ICP and enables its owner to participate in network governance, through which they can earn rewards.
 +
 
 +
=== Attributes ===
 +
Neurons have the following attributes:
 +
 
 +
* '''Identity (uint64)''' The general identity of the neuron object. When a neuron is configured to follow another neuron, this is the value that is used. This is a random 64-bit value selected at neuron creation.
 +
 
 +
* '''Account (bytes, private)''' The ledger account where the locked ICP balance resides.
 +
 
 +
* '''Controller (principal ID, private)''' The principal that actually controls the neuron. The principal must identify a public key pair, which acts as a “master key,” such that the corresponding secret key should be kept very secure. The principal might control many neurons.
 +
 
 +
* '''Hot Keys (list of principal ID, private)''' Keys that can be used to perform actions with limited privileges, such as voting, without exposing the secret key corresponding to the principal (e.g., could be a WebAuthn key).
 +
 
 +
* '''CreatedAt (timestamp)''' When the Neuron was created.
 +
 
 +
* '''AgingSince (timestamp)''' The timestamp corresponding to the time this neuron has started aging. This is either the creation time or the last time at which the neuron has stopped dissolving. This value is meaningless when the neuron is dissolving, since a dissolving neuron always has an age of zero.
 +
 
 +
* '''DissolveState''' At any time, at most one of WhenDissolved and DissolveDelay are specified.
 +
** WhenDissolved (timestamp)
 +
When the dissolve timer is running, this stores the timestamp in seconds from the Unix epoch, at which point the neuron becomes dissolved. At any time while the neuron is dissolving, the neuron owner may pause dissolving, in which case DissolveDelay will get assigned to: WhenDissolved minus the timestamp when the action is taken.
 +
**DissolveDelay (duration)
 +
When the dissolve timer is stopped, this stores how much time the dissolve timer will be started with. It can be eight years at most. At any time while in this state, the neuron owner may (re)start dissolving, in which case WhenDissolved will get assigned to the timestamp when the action is taken plus DissolveDelay.
 +
 
 +
* '''Maturity (positive number – percent)''' The maturity of a neuron, which determines its ability to spawn a new neuron and corresponding locked balance of newly minted ICP in expectation equal to this value in percent of the stake of the spawning neuron. When new neurons are created, their maturity is zero. When neurons vote, over time the NNS increases their maturity to reward them.
 +
 
 +
* '''Follow Relationships (mapping from topic to list of followees, private)''' A neuron can be configured to vote automatically by following other neurons on a topic-by-topic basis. For any valid topic, a list of followees can be specified, and the neuron will follow the vote of a majority of the followees on a proposal with a type belonging to that topic. If a null topic is specified, this acts as a catch-all that enables the neuron to follow the vote of followees where a rule has not been specified.
 +
 
 +
* '''Recent Votes (public)''' A record of recent votes is maintained. This can provide a guide for those wishing to evaluate whether to follow a neuron, or how their followees are voting.
 +
 
 +
* '''NotForProfit (boolean)''' Whether this neuron is “not for profit,” making it dissolvable by voting.
 +
 
 +
The following attributes can be computed:
 +
 
 +
* ''' Age (seconds)''' (computed from AgingSince and current time) The period of time that has elapsed since the neuron was created or last stopped dissolving. Conceptually, whenever a neuron starts dissolving, then its age is reset to zero and remains zero while it is dissolving. If a dissolving neuron has dissolving turned off, the current time becomes the effective neuron creation date for the purposes of calculating the age.
 +
* '''State (LOCKED or DISSOLVING or DISSOLVED)''' (computed from DissolveState and the current time)
 +
**LOCKED: In this state, the neuron is locked with a specific DissolveDelay. It accrues age by the passage of time and it can vote if DissolveDelay is at least six months. The method start_dissolving can be called to transfer the neuron to the DISSOLVING state. The method increase_dissolve_delay can be used to increase the dissolve delay without affecting the state or the age of the neuron.
 +
**DISSOLVING: In this state, the neuron’s effective dissolve delay decreases with the passage of time. While dissolving, the neuron’s age is considered zero. Eventually it will reach the DISSOLVED state. The method stop_dissolving can be called to transfer the neuron to the LOCKED state, and the neuron will start aging again. The method increase_dissolve_delay can be used to increase the dissolve delay, but this will not stop the timer or affect the age of the neuron.
 +
**DISSOLVED: In the dissolved state, the neuron’s stake can be disbursed using the disburse method. It cannot vote as its dissolve delay is considered to be zero. If the method increase_dissolve_delay is called in this state, the neuron will become locked with the specified dissolve delay and start aging again. Neuron holders have an incentive not to keep neurons in the dissolved state for a long time: if the holders want to make their tokens liquid, they disburse the neuron’s stake, and if they want to earn voting rewards, they increase the dissolve delay. If these incentives turn out to be insufficient, the NNS may decide to impose further restrictions on dissolved neurons.
 +
 
 +
* '''ControlByProposals (boolean)''' (true if the neuron has a non-empty list of followees on the #NeuronManagement topic) If a neuron specifies followees on the ManageNeuron topic, it can be managed by proposals of type ManageNeuron (#NeuronManagement), which may only be voted upon by the neuron’s own followees. This provides a foundation for the management of highly security sensitive neurons, since it allows them to be maintained without hot keys or the secret key of the principal, which can be kept in cold storage or even destroyed (so long as the associated balance of ICP need never be unlocked). For example, the DFINITY Foundation or the Internet Computer Association might publicize the address of special neurons that will be made to vote according to their wishes, so that others can configure their neurons to follow them and leverage their expertise and efforts in governance. One problem with such practices is that they introduce the risk that secret keys used in the management of the publicized neurons might be compromised, allowing hackers to take control and “trick” large numbers of following neurons into voting according to their wishes. If the publicized neurons have admin proposals enabled, however, then they can be administered by the neurons they follow (their followees), which are typically controlled by a large number of team members who cannot be simultaneously extorted, without any need for the usage of secret keys whatsoever.
 +
 
 +
=== Commands ===
 +
The principal that controls a neuron may instruct it to perform the following actions:
 +
 
 +
* '''Start Dissolving''' The dissolve delay is like a kitchen timer that can only be turned in one direction. It can be arbitrarily increased, but only reduced by turning on dissolve mode and counting down. The neuron can be instructed to start “dissolving.” When the neuron is dissolving, its dissolve delay falls over the passage of time until either it is stopped or it reaches zero. A neuron cannot vote (or earn rewards for voting) when its dissolve delay falls below six months. Once the dissolve delay reaches zero, it stops falling and the controlling principal can instruct the neuron to disburse.
 +
 
 +
* '''Stop Dissolving''' A neuron that is dissolving can be instructed to stop, whereupon its dissolve delay stops falling with time.
 +
 
 +
* '''Disburse''' When the dissolve delay of the neuron is 0, its controlling principal can instruct it to disburse the neuron’s stake. Its locked ICP balance is transferred to a specified new ledger account, and the neuron and its own ledger account disappear.
 +
 
 +
* '''Increase Dissolve Delay''' The dissolve delay of a neuron can be increased up to a maximum of eight years.
 +
 
 +
* '''Spawn''' When the maturity of a neuron has risen above a threshold, it can be instructed to spawn a new neuron. This creates a new neuron that locks a new balance of ICP on the ledger. The new neuron can remain controlled by the same principal as its parent, or be assigned to a new principal. When a neuron spawns a new neuron, its maturity falls to zero.
 +
 
 +
* '''Add Hot Key''' Add a new hot key that can be used to manage the neuron. This provides an alternative to using the principal’s cold key to manage the neuron, which might be onerous and difficult to keep secure, especially if it is used regularly. A hot key might be a WebAuthn key that is maintained inside a user device, such as a smartphone.
 +
 
 +
* '''Remove Hot Key''' Remove a hot key that has been previously assigned to the neuron.
 +
 
 +
The following actions can be initiated using the principal or a hot key that has been configured:
 +
 
 +
* '''Vote''' Have the neuron vote to either adopt or reject a proposal with a specified ID.
 +
* '''Follow''' Add a rule that enables the neuron to vote automatically on proposals that belong to a specific topic, by specifying a group of followee neurons whose majority vote is followed. The configuration of such follow rules can be used to: a) distribute control over voting power amongst multiple entities, b) have a neuron vote automatically when its owner lacks time to evaluate newly submitted proposals, c) have a neuron vote automatically when its own lacks the expertise to evaluate newly submitted proposals, and d) for other purposes. A follow rule specifies a set of followees. Once a majority of the followees votes to adopt or reject a proposal belonging to the specified topic, the neuron votes the same way. If it becomes impossible for a majority of the followees to adopt (for example, because they are split 50–50 between adopt and reject), then the neuron votes to reject. If a rule is specified where the proposal topic is null, then it becomes a catch-all follow rule, which will be used to vote automatically on proposals belonging to topics for which no specific rule has been specified. If the list of followees is empty, this effectively removes a follow rule.

Revision as of 16:46, 6 September 2022

The NNS is the decentralized autonomous organization (DAO) that governs the Internet Computer (IC). It is a fully on-chain, decentralized system and is, for instance, responsible for making protocol level upgrades to continuously improve the Internet Computer. It does this via an implementation of liquid democracy in which ICP neuron holders vote on proposals that shape the development of the Internet Computer. Once such a proposal is accepted, it is autonomously executed.

While other blockchains take weeks or months to upgrade (sometimes called hard fork) and typically require substantial manual work and coordination to do so, the IC upgrades itself on a weekly basis (https://dashboard.internetcomputer.org/releases). Its ability to upgrade and iterate is a comparative "superpower."

The NNS works by allowing users to stake ICP governance tokens to create voting neurons. Anyone can create a neuron, which together exert the will of the community, mediated through algorithms. Neurons are like accounts where notice of withdrawals must be given, where the length of the notice period is a configuration known as the “dissolve delay.” The voting power of neurons, and their relative claim to voting rewards, is proportional to the quantity of staked ICP, the length of the configured dissolve delay, and their “age.” Neurons can be made to vote manually, or automatically, by following other neurons in a form of liquid democracy.

Neuron holders are placed in a cryptoeconomic game, where they are incentivized to vote to adopt and reject proposals, or to configure neuron follows that cause them to vote automatically in a desirable way, according to what is most likely to drive the value of the Internet Computer network over the long term.

This is the first time in history when a decentralized infrastructure will self-direct with the aim of competing with proprietary centralized infrastructures run by commercial organizations with leaders and boards.

Overview

The purpose of the NNS is to allow the Internet Computer network to be governed in an open, decentralized, and secure manner. It has complete control over all aspects of the network. For example, it can upgrade the protocol and software used by the node machines that host the network; it can create new subnet blockchains to increase network capacity; it can split subnets to divide their load; it can configure economic parameters that control how much must be paid by users for compute capacity; and, in extreme situations, it can freeze malicious canister smart contract software in order to protect the network; and many other things. The NNS works by accepting proposals, and deciding to adopt or reject them based on voting activity by “neurons” that network participants have created.

Neurons are also used by participants to submit new proposals. After submission, proposals are either adopted or rejected, which can happen almost immediately, or after some delay, depending upon how the totality of neurons vote. Each proposal is an instance of a specific “proposal type,” which determines what information it contains. For each type of proposal, the NNS maintains a corresponding system function, which it invokes whenever a proposal of that type is adopted. When a proposal is adopted by the NNS, it invokes the corresponding system function by drawing information from the proposal’s content to fill the parameters. Each type of proposal belongs to a specific “proposal topic,” such as “#NodeAdmin” or “#NetworkEconomics,” which determines details about how it will be processed.To prevent users (neurons) from spamming the NNS with proposals, a fee is levied on the neuron that submitted a proposal if it is rejected.

The NNS decides whether to adopt or reject proposals by watching how neurons emit votes. Anyone can create a neuron by locking balances of the Internet Computer’s native utility token (ICP) that is hosted on a ledger inside the NNS. When a user creates a neuron, the locked balance of ICP can only be unlocked by disbursing (“destroying”) the neuron. Users are incentivized to create neurons because they earn rewards when they vote on proposals. Rewards take the form of newly minted ICP that are created by the NNS. The quantity of ICP rewards disbursed to a neuron derive from such factors as the size of the locked balance, the minimum lockup period remaining (the “dissolve delay”), the neuron’s “age,” the proportion of possible votes it has participated in, and the sum of voting activity across all neurons, since the overall total rewards disbursed is capped and must be divided between voters.

At any moment, each neuron has a currently configured “dissolve delay.” This determines how long it will take to dissolve if it is placed into “dissolve mode.” Once a neuron has been placed into “dissolve mode,” its dissolve delay falls over the passage of time, rather like a kitchen timer, until it reaches zero, whereupon its owner can perform a final disburse action to unlock the balance of ICP. The dissolve delay creates an economic incentive for neuron owners to vote with a view toward maximizing the value of their locked ICP balances at a future date. ICP is a proxy for the success of the network over the long term, sans short-term volatility, this creates an economic incentive to vote in the best interests of the network. Neuron owners can freely configure higher dissolve delays, up to a maximum delay of eight years, but cannot decrease the dissolve delay other than by the natural passage of time. The NNS pays higher voting rewards the higher the dissolve delay, encouraging users to enter a game in which an economic incentive is created to vote according to a very long-term vision.

Neuron owners may find it hard to manually vote directly on every proposal submitted to the NNS. Firstly, large volumes of proposals may be submitted to the NNS, often at awkward times, and owners may not be available or have the necessary time to evaluate each one. Secondly, neuron owners may lack the necessary expertise to evaluate proposals themselves. The NNS uses a form of liquid democracy to address these challenges. For any proposal topic, a neuron can be configured to vote automatically by following the votes of a group of neurons, voting to adopt proposals whenever more than half of the followees vote to adopt, and voting to reject whenever at least half of the followees vote to reject. A catch-all follow rule may also be defined to make a neuron vote automatically on proposals with topics for which no follow rule has been defined. It is assumed that neuron owners will manage how their neurons follow other neurons in the best interests of the network, which is also in their own economic interests, owing to their locked ICP balances.

It is expected that a large proportion of the overall supply of ICP will be locked in order to earn rewards. This secures the Internet Computer’s network governance, by making it both difficult and exorbitantly expensive for an attacker to acquire a sufficiently large stake to gain significant influence. Since neuron owners may wish to maximize their rewards by voting on all proposals, most neurons will either be actively managed or configured to follow other neurons so that they can vote automatically. In practice, once trusted neurons have voted on proposals, a majority of the other neurons will also vote as the result of cascading follow relationships. This means that the NNS can usually quickly determine whether a majority of the overall voting power represented by all neurons wishes to adopt or reject a proposal, and decide on the proposal accordingly. However, the NNS cannot depend on obtaining such a majority since, in principle, neuron owners may not define follow rules, or they may simply choose not to vote.

Proposals

Format

Each proposal submitted to the NNS has the following fields:

  • Summary: Text providing a short description of the proposal, composed using a maximum of 280 bytes.
  • URL: The web address of additional content required to evaluate the proposal, specified using HTTPS. For example, the address might describe content 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. So the balance needs to be big enough to pay the charge on (all) rejection(s). We require a neuron to have a dissolve delay ≥ 6 months to vote, and this applies to submitting proposals too.
  • Proposal Type: The type of the proposal. This infers what topic it belongs to (e.g., #NodeAdmin), the system function that will process the proposal if it is adopted, and the type and structure of the parameters that will be passed to that function.
  • Parameters: The parameters that will be passed to the system function that will be invoked if the proposal is adopted, as determined by its type. When a proposal is submitted, the NNS checks the parameters.

The NNS assigns a unique identity to each proposal that it receives.

The NNS assigns a unique identity to each proposal that it receives.

Topics

The topic of a proposal, which is inferred from its type, determines how it will be processed. For example, the NNS may require voters to have a greater degree of agreement, or to try to process proposals faster, for some topics. Also, neurons follow other neurons on a per-topic basis. Initial topics include:

  • #NeuronManagement: A special topic by means of which a neuron can be managed by the followees for this topic (in this case, there is no fallback to default). Votes on this topic are not included in the voting history of the neuron. For proposals on this topic, only the neuron’s followees on the topic that the proposals pertain to are allowed to vote. Because the set of eligible voters of proposals on this topic is restricted, proposals on this topic have a shorter than normal voting period.
  • ExchangeRate: All proposals provide information in “real time” about the market value of ICP, as measured by an International Monetary Fund (IMF) Special Drawing Right (SDR) , which allows the NNS to convert ICP to cycles (which power computation) at a rate that keeps their real-world cost constant. Because proposals on this topic are very frequent, they have a shorter voting period, and votes on this topic are not included in the voting history of the neuron.
  • #NetworkEconomics: Proposals that administer network economics — for example, determining what rewards should be paid to node operators.
  • #Governance: All proposals that administer governance — for example, motions and the configuration of certain parameters.
  • #NodeAdmin: All proposals that administer node machines somehow, including but not limited to upgrading or configuring the OS, upgrading or configuring the virtual machine framework, and upgrading or configuring the node replica software.
  • #ParticipantManagement: All proposals that administer network participants — for example, granting and revoking DCIDs (data center identities) or NPIDs (node provider identities).
  • #SubnetManagement: All proposals that administer network subnets — for example, creating new subnets, adding and removing subnet nodes, and splitting subnets.
  • #NetworkCanisterManagement: Installing and upgrading “system” canisters that belong to the network — for example, upgrading the NNS.
  • #KYC: Proposals that update KYC information for regulatory purposes — for example, during the initial Genesis distribution of ICP in the form of neurons.
  • #NodeProviderRewards: Topic for proposals to reward node providers.

Types

Initial proposal types include:

  • ManageNeuron (#NeuronManagement, Restricted Voting) This type of proposal calls a major function on a specified target neuron. Only the followees of the target neuron may vote on these proposals, which effectively provides the followees with control over the target neuron. This can provide a convenient and highly secure means for a team of individuals to manage an important neuron. For example, a neuron might hold a large balance, or belong to an organization of high repute, and be publicized so that many other neurons can follow its vote. In both cases, managing the private key of the principal securely could be problematic. (Either a single copy is held, which is very insecure and provides for a single party to take control, or a group of individuals must divide responsibility — for example, using threshold cryptography, which is complex and time consuming). To address this using this proposal type, the important neuron can be configured to follow the neurons controlled by individual members of a team. Now they can submit proposals to make the important neuron perform actions, which are adopted if and only if a majority of them vote to adopt. (Submitting such a proposal costs a small fee, to prevent denial-of-service attacks.) Nearly any command on the target neuron can be executed, including commands that change the follow rules, allowing the set of team members to be dynamic. Only the final step of dissolving the neuron once its dissolve delay reaches zero cannot be performed using this type of proposal, since this would allow control/“ownership” over the locked balances to be transferred. (The only exception to this rule applies to not-for-profit organizations, which may be allowed to dissolve their neurons without using the initial private key.) To prevent a neuron falling under the malign control of the principal’s private key by accident, the private key can be destroyed so that the neuron can only be controlled by its followees, although this makes it impossible to subsequently unlock the balance.
  • ManageNetworkEconomics (#NetworkEconomics) This is a single proposal type which can update one or several economic parameters:
    • 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 creation of a neuron. The same limit must also be respected when increasing 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/SDR rate: To prevent mistakes, there is a lower bound for the ICP/SDR 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.
  • Motion (#Governance) A motion is a text that can be adopted or rejected. No code is executed when a motion is adopted. An adopted motion should guide the future strategy of the Internet Computer ecosystem.
  • ApproveGenesisKYC (#KYC) When new neurons are created at Genesis, they have 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.

(Special note: 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.)

  • AddOrRemoveNodeProvider (#Participant Management) Assign (or revoke) an identity to a node provider, associating key information regarding the legal person associated that should provide a way to uniquely identify it.
  • RewardNodeProvider (#NodeProviderRewards) Propose to reward a Gen-1 node provider an amount of ICP as compensation for providing Gen-1 nodes to the IC.
  • SetDefaultFollowees (#Governance) Specify the list of followees that a freshly created neuron should have.

The following is a list of proposal types that call other NNS canisters:

  • CreateSubnet (#SubnetManagement) 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 decentralized subnet. The execution of this external update 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 initial configuration information for the subnet, from where the nodes comprising the subnet pick it up.
  • AddNodeToSubnet (#SubnetManagement) 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.
  • InstallNetworkCanister (#NetworkCanisterManagement) A proposal to add a new canister to be installed and executed in the NNS subnetwork. The root canister, which controls all canisters on the NNS except for itself, handles this proposal type. The call also expects the Wasm module that shall be installed.
  • UpgradeNetworkCanister (#NetworkCanisterManagement) A proposal to upgrade an existing canister in the NNS subnetwork. This proposal type is executed by the root canister. Beyond upgrading the Wasm module of the target canister, the proposal can also set the authorization information and the allocations.
  • BlessReplicaVersion (#NodeAdmin) A proposal to bless a new version to which the replicas can be upgraded. The proposal registers a replica version (identified by the hash of the installation image) in the registry. Besides creating a record for that version, the proposal also appends that version to the list of “blessed versions” that can be installed on a subnet. By itself, this proposal does not effect any upgrade. (In the future, there will only be one blessed version of the replica software at any given time.)
  • RecoverSubnet (#SubnetManagement) 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.

UpdateSubnetConfig (#SubnetManagement) 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).

  • AssignNPID (#ParticipantManagement) Assign an identity to a node operator 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 IC. When an additional node is added by the node operator, the remaining allowance is decreased.
  • RootUpgrade (#NetworkCanisterManagement) A proposal to upgrade the root canister in the NNS subnetwork. The proposal is processed by the Lifeline canister, which controls the root canister. The proposal updates the Wasm module as well as the authorization settings.
  • SetICPSDR (#ExchangeRate) Instruct the NNS about the market value of 1 ICP as measured by an IMF SDR. This setting affects cycles pricing (as the value of cycles shall be constant with respect to IMF SDRs).
  • UpgradeSubnetToReplicaVersion (#SubnetManagement) Update the replica version running on a given subnet. The proposal changes the replica version that is used on the specified subnet. The version must be contained in the list of blessed replica versions. The upgrade is performed when the subnet creates the next regular CUP.
  • ClearProvisionalWhitelist (#NetworkEconomics) Clears the provisional whitelist, which allows the listed principals to create canisters with cycles. The mechanism is only needed for bootstrap and testing and must be deactivated afterward.
  • RemoveNodeFromSubnet (#SubnetManagement) 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.
  • SetAuthorizedSubnetworks (#Governance) 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.
  • SetFirewallConfig (#SubnetManagement) Change the Firewall configuration in the registry (configures which boundary nodes subnet blockchain replicas will communicate with).
  • UpdateNodeOperatorConfig (#NodeAdmin) Change a node operator’s allowance in the registry.
  • StopOrStartNNSCanister (#NetworkCanisterManagement) Stop or start an NNS canister.

ICP tokens

ICP are native utility tokens that play three key roles in the network:

  1. Facilitating Network Governance ICP tokens can be locked to create neurons that participate in network governance by voting, through which they can earn economic rewards.
  1. Production of Cycles for Compute ICP provides a source store of value that can be converted into “cycles,” which power computation in the role of fuel that is burned when it is used. The NNS converts ICP to cycles at a variable rate, so chosen to ensure users of the network can always create new cycles at approximately constant cost in real terms, such that the cost of acquiring fuel is predictable.
  1. Rewarding Participants The network mints new ICP to reward and incentivize those playing important roles that enable the network to function, including: a) the provision of “voting rewards” to those participating in governance, and b) the provision of “node provider rewards” to those operating the node machines that are hosting the network.

Ledger

The ICP ledger is hosted within the NNS, and records all balances of ICP in the manner of a spreadsheet. Each row is called an “account,” which has two fields (i.e., there are two “columns”):

  1. Account identifier (bytes) A unique value that is derived from the identity of the “principal” that “controls” the account. Currently, the principal must either be: (i) the owner of a public key pair, or (ii) a canister smart contract that is part of the NNS. Account identifiers are derived by hashing the concatenation of a domain separator, the principal ID, and the subaccount (or zeros if no subaccount is given).
  1. Balance (positive integer, representing one hundredth of a millionth of an ICP) The quantity of ICP assigned to the principal of the account.

When the principal is a public key or Canister, they can apply the following operation to an account:

  1. Send Send a portion of the ICP balance to another account. If all the ICP is sent to another account, then the sending account ceases to exist (i.e., is deleted from the ledger).
  2. Notify When the destination of the funds sent is the account of an NNS canister (e.g., an account of the governance canister), the sender can ask the ledger to notify the recipient canister of the incoming transfer. The recipient canister can then act on this notification. Two examples where this ability is used are creating a neuron and refreshing the stake of a neuron. These are detailed below.

Operations that require interaction between the ledger and the governance system (Neurons):

  1. Create neuron When the principal is a public key holder, they may lock a portion of their balance inside a new neuron. Technically, creating the neuron is done in two stages. First transfer the ICP to be staked to an account of the governance canister (which corresponds to a new neuron — the details of the association are omitted here). Then notify the governance canister of the incoming transfer which updates its internal neuron bookkeeping. If the entire balance is locked inside a new neuron, the account ceases to exist (i.e., is deleted from the ledger). To move these ICP to a different account, such as back to the original account, where they can once again be controlled like a normal balance, the associated neuron must be fully dissolved and disbursed (destroyed). The new neuron that has been created is controlled by the private key of the principal that created it.
  2. Refresh stake The stake of a neuron may be increased by transferring to its address/account in the ledger and notifying the governance canister of the incoming transfer. Refreshing the stake will change the maturity and age of the neuron prorated. For example, if the stake is doubled, the maturity and age will be halved, so spawning will yield the same amount and the age bonus will be the same as before (in absolute terms).

Neurons

A neuron locks a balance of ICP and enables its owner to participate in network governance, through which they can earn rewards.

Attributes

Neurons have the following attributes:

  • Identity (uint64) The general identity of the neuron object. When a neuron is configured to follow another neuron, this is the value that is used. This is a random 64-bit value selected at neuron creation.
  • Account (bytes, private) The ledger account where the locked ICP balance resides.
  • Controller (principal ID, private) The principal that actually controls the neuron. The principal must identify a public key pair, which acts as a “master key,” such that the corresponding secret key should be kept very secure. The principal might control many neurons.
  • Hot Keys (list of principal ID, private) Keys that can be used to perform actions with limited privileges, such as voting, without exposing the secret key corresponding to the principal (e.g., could be a WebAuthn key).
  • CreatedAt (timestamp) When the Neuron was created.
  • AgingSince (timestamp) The timestamp corresponding to the time this neuron has started aging. This is either the creation time or the last time at which the neuron has stopped dissolving. This value is meaningless when the neuron is dissolving, since a dissolving neuron always has an age of zero.
  • DissolveState At any time, at most one of WhenDissolved and DissolveDelay are specified.
    • WhenDissolved (timestamp)

When the dissolve timer is running, this stores the timestamp in seconds from the Unix epoch, at which point the neuron becomes dissolved. At any time while the neuron is dissolving, the neuron owner may pause dissolving, in which case DissolveDelay will get assigned to: WhenDissolved minus the timestamp when the action is taken.

    • DissolveDelay (duration)

When the dissolve timer is stopped, this stores how much time the dissolve timer will be started with. It can be eight years at most. At any time while in this state, the neuron owner may (re)start dissolving, in which case WhenDissolved will get assigned to the timestamp when the action is taken plus DissolveDelay.

  • Maturity (positive number – percent) The maturity of a neuron, which determines its ability to spawn a new neuron and corresponding locked balance of newly minted ICP in expectation equal to this value in percent of the stake of the spawning neuron. When new neurons are created, their maturity is zero. When neurons vote, over time the NNS increases their maturity to reward them.
  • Follow Relationships (mapping from topic to list of followees, private) A neuron can be configured to vote automatically by following other neurons on a topic-by-topic basis. For any valid topic, a list of followees can be specified, and the neuron will follow the vote of a majority of the followees on a proposal with a type belonging to that topic. If a null topic is specified, this acts as a catch-all that enables the neuron to follow the vote of followees where a rule has not been specified.
  • Recent Votes (public) A record of recent votes is maintained. This can provide a guide for those wishing to evaluate whether to follow a neuron, or how their followees are voting.
  • NotForProfit (boolean) Whether this neuron is “not for profit,” making it dissolvable by voting.

The following attributes can be computed:

  • Age (seconds) (computed from AgingSince and current time) The period of time that has elapsed since the neuron was created or last stopped dissolving. Conceptually, whenever a neuron starts dissolving, then its age is reset to zero and remains zero while it is dissolving. If a dissolving neuron has dissolving turned off, the current time becomes the effective neuron creation date for the purposes of calculating the age.
  • State (LOCKED or DISSOLVING or DISSOLVED) (computed from DissolveState and the current time)
    • LOCKED: In this state, the neuron is locked with a specific DissolveDelay. It accrues age by the passage of time and it can vote if DissolveDelay is at least six months. The method start_dissolving can be called to transfer the neuron to the DISSOLVING state. The method increase_dissolve_delay can be used to increase the dissolve delay without affecting the state or the age of the neuron.
    • DISSOLVING: In this state, the neuron’s effective dissolve delay decreases with the passage of time. While dissolving, the neuron’s age is considered zero. Eventually it will reach the DISSOLVED state. The method stop_dissolving can be called to transfer the neuron to the LOCKED state, and the neuron will start aging again. The method increase_dissolve_delay can be used to increase the dissolve delay, but this will not stop the timer or affect the age of the neuron.
    • DISSOLVED: In the dissolved state, the neuron’s stake can be disbursed using the disburse method. It cannot vote as its dissolve delay is considered to be zero. If the method increase_dissolve_delay is called in this state, the neuron will become locked with the specified dissolve delay and start aging again. Neuron holders have an incentive not to keep neurons in the dissolved state for a long time: if the holders want to make their tokens liquid, they disburse the neuron’s stake, and if they want to earn voting rewards, they increase the dissolve delay. If these incentives turn out to be insufficient, the NNS may decide to impose further restrictions on dissolved neurons.
  • ControlByProposals (boolean) (true if the neuron has a non-empty list of followees on the #NeuronManagement topic) If a neuron specifies followees on the ManageNeuron topic, it can be managed by proposals of type ManageNeuron (#NeuronManagement), which may only be voted upon by the neuron’s own followees. This provides a foundation for the management of highly security sensitive neurons, since it allows them to be maintained without hot keys or the secret key of the principal, which can be kept in cold storage or even destroyed (so long as the associated balance of ICP need never be unlocked). For example, the DFINITY Foundation or the Internet Computer Association might publicize the address of special neurons that will be made to vote according to their wishes, so that others can configure their neurons to follow them and leverage their expertise and efforts in governance. One problem with such practices is that they introduce the risk that secret keys used in the management of the publicized neurons might be compromised, allowing hackers to take control and “trick” large numbers of following neurons into voting according to their wishes. If the publicized neurons have admin proposals enabled, however, then they can be administered by the neurons they follow (their followees), which are typically controlled by a large number of team members who cannot be simultaneously extorted, without any need for the usage of secret keys whatsoever.

Commands

The principal that controls a neuron may instruct it to perform the following actions:

  • Start Dissolving The dissolve delay is like a kitchen timer that can only be turned in one direction. It can be arbitrarily increased, but only reduced by turning on dissolve mode and counting down. The neuron can be instructed to start “dissolving.” When the neuron is dissolving, its dissolve delay falls over the passage of time until either it is stopped or it reaches zero. A neuron cannot vote (or earn rewards for voting) when its dissolve delay falls below six months. Once the dissolve delay reaches zero, it stops falling and the controlling principal can instruct the neuron to disburse.
  • Stop Dissolving A neuron that is dissolving can be instructed to stop, whereupon its dissolve delay stops falling with time.
  • Disburse When the dissolve delay of the neuron is 0, its controlling principal can instruct it to disburse the neuron’s stake. Its locked ICP balance is transferred to a specified new ledger account, and the neuron and its own ledger account disappear.
  • Increase Dissolve Delay The dissolve delay of a neuron can be increased up to a maximum of eight years.
  • Spawn When the maturity of a neuron has risen above a threshold, it can be instructed to spawn a new neuron. This creates a new neuron that locks a new balance of ICP on the ledger. The new neuron can remain controlled by the same principal as its parent, or be assigned to a new principal. When a neuron spawns a new neuron, its maturity falls to zero.
  • Add Hot Key Add a new hot key that can be used to manage the neuron. This provides an alternative to using the principal’s cold key to manage the neuron, which might be onerous and difficult to keep secure, especially if it is used regularly. A hot key might be a WebAuthn key that is maintained inside a user device, such as a smartphone.
  • Remove Hot Key Remove a hot key that has been previously assigned to the neuron.

The following actions can be initiated using the principal or a hot key that has been configured:

  • Vote Have the neuron vote to either adopt or reject a proposal with a specified ID.
  • Follow Add a rule that enables the neuron to vote automatically on proposals that belong to a specific topic, by specifying a group of followee neurons whose majority vote is followed. The configuration of such follow rules can be used to: a) distribute control over voting power amongst multiple entities, b) have a neuron vote automatically when its owner lacks time to evaluate newly submitted proposals, c) have a neuron vote automatically when its own lacks the expertise to evaluate newly submitted proposals, and d) for other purposes. A follow rule specifies a set of followees. Once a majority of the followees votes to adopt or reject a proposal belonging to the specified topic, the neuron votes the same way. If it becomes impossible for a majority of the followees to adopt (for example, because they are split 50–50 between adopt and reject), then the neuron votes to reject. If a rule is specified where the proposal topic is null, then it becomes a catch-all follow rule, which will be used to vote automatically on proposals belonging to topics for which no specific rule has been specified. If the list of followees is empty, this effectively removes a follow rule.
Retrieved from "https://wiki.internetcomputer.org/w/index.php?title=Network_Nervous_System&oldid=3032"