Internet Computer Wiki - User contributions [en]

Governance of the Internet Computer

2022-01-03T19:03:14Z

LaraAS: /* Submitting a proposal */ update link

The Internet Computer blockchain is governed by the Network Nervous System<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref>. The NNS is an algorithmic governance system that oversees the network and the token economics that make it possible to build DeFi dapps, open internet services and enterprise systems.

Holders of the Internet Computer’s ICP utility tokens can lock their tokens in ''neurons'' to participate in governance and contribute to decision-making, such as voting to determine whether or not a new collection of nodes (also called a subnet) should be added to the network.

=== Why the Internet Computer needs a Network Nervous System<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref> ===
The Internet Computer is a distributed protocol run by a network of node machines, which are hosted in different data centers. The nodes communicate with one another over the internet to achieve a consensus on what the Internet Computer’s state should be. A collection of nodes engaging in consensus is called a subnet. On top of this underlying communication and consensus protocol, the Internet Computer hosts ''canisters'', which are stateful programs that can also communicate with each other. The state of all of the canisters has to be replicated across all of the nodes. Therefore, to allow the Internet Computer to scale indefinitely, the network is made up of not just one subnet, but multiple subnets.

Different subnets can communicate with one another, enabling canisters that are hosted on different subnets to also communicate with each other. For the Internet Computer to scale on-demand, the network must be able to add new subnets over time to increase compute capacity. Moreover, the robustness of the subnets can be improved by adding new nodes to them over time. Eventually, the Internet Computer will run millions of nodes at scale. This means that there needs to be a mechanism by which the nodes and subnets are organized, tracked, and managed. For example, decisions must be made about when subnets and nodes should be added or removed. In addition, the Internet Computer was launched with an initial feature set, which evolves over time. Therefore, the Internet Computer needs to be able to make decisions on how to evolve the protocol in a distributed manner.

=Network Nervous System overview=

The NNS is a tokenized open governance system that is responsible for managing the Internet Computer. For example, the NNS stores information about what nodes belong to which subnet and the code each replica runs. The NNS also makes decisions about how to update this information and evolve the IC.

The NNS is realized by a set of ''[[canisters|canister smart contracts]]''.

=== '''NNS canister smart contracts''' ===

# '''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.

= Ledger canister & ICP utility tokens in the NNS =
[[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.

In the NNS, ICP utility tokens are used for three different things:

# ICP tokens facilitate '''participation in governance''' (more below on how the neurons are connected with the tokens).
# 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=

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 ==
Neurons contain ''locked'' ICP utility tokens. These staked tokens are not liquid and cannot be transferred freely to others.

=== '''Neuron Attributes''' ===
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.
* A ''controller'' principal, which identifies who manages the neuron's actions.
* A unique ''neuron ID''
*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.

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.

===How to lock tokens in a neuron<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref>===

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.

'''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.''

''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.''

''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.''

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.
== Proposals ==
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.

The Internet Computer supports a variety of different proposal ''topics''. Here are some examples of topics that are supported in the NNS governance canister:
* #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 ==

=== Submitting a proposal ===
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.''

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.

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.

Moreover, each proposal has an associated ''voting period,'' which determines the period of time over which votes for this proposal are accepted.

=== Viewing NNS Proposals ===
You can see all the NNS proposals on the Internet Computer dashboard: https://dashboard.internetcomputer.org/governance

===Discussing NNS Proposals===

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===
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]].

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.

'''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.''

====Neuron following and liquid democracy====

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.

'''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.''

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.

=== Proposal decision and wait-for-quiet ===
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.

=== Proposal execution ===
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 ==
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 a neuron's attributed that is called ''maturity.'' Maturity represents ICP utility token that are not yet minted.

A neuron holder can then profit from the maturity in two ways:

# '''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.
# '''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.

= Cycles Minting Canister and Cycles<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref> =
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 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.

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.

'''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.''

=References=

Neuron attributes and commands

2022-01-03T19:02:16Z

LaraAS: new page

This page provides more details about the [https://wiki.internetcomputer.org/index.php?title=Governance_of_the_Internet_Computer&veaction=edit&section=6#Neurons neurons] in the Network Nervous System (NNS), focusing on their attributes and the commands by which they can be changed.

== Neuron Attributes ==
Each neuron in the NNS has the following attributes.

* id: the id of the neuron.
* account: The principal of the ICP ledger account where the locked ICP balance resides. That is, each neuron's ICP utility token balance is stored on an account on the ledger canister. In contrast to non-neuron accounts the controller can however not just transfer the funds out of this account.

* controller: The principal that 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 secure. The principal may control many neurons.

* hot_keys: Keys that can be used to perform actions with limited privileges, for example voting for a neuron. The idea is that while the controller key should be kept very secure, the loss or compromise of such keys that are used more often (and thus very secure storage might not be feasible) has less security impact.
* cached_neuron_stake_e8s: The amount of staked ICP tokens, measured in fractions of 10E-8 of an ICP. This does not include the fees or some of the collected rewards (see below) and might not correspond exactly to the amount of ICP tokens of the neuron's account at all times. For example, to top up a neuron, one first transfers some ICP tokens to the neuron's account and then refreshes the neuron, which means that in between these actions the neuron's account actually holds more tokens than indicated by the corresponding cached stake.
* neuron_fees_e8s: The amount that this neuron owes, measured in fractions of 10E-8 of an ICP. This amount is increased when a neuron makes a proposal of [[Topic ManageNeuron|topic ''ManageNeuron'']] or when a neuron makes a proposal of any other topic (in the latter case the fee is reimbursed if the proposal is accepted). When a neuron is disbursed, these tokens are burned.
* created_timestamp_seconds: The time when the neuron was created.
* aging_since_timestamp_seconds: The time, in seconds from the Unix epoch, this neuron has last entered the non-dissolving state.
* dissolve_state: The state specifying whether a neuron is dissolving, i.e., the timer when the staked tokens can be retrieved is decreasing, or non-dissolving, i.e., the time how much into the future the staked tokens can be retrieved is stopped.
** When a neuron is dissolving, i.e., the dissolve timer is running, the state is when_dissolved_timestamp_seconds and stores the timestamp, in seconds from the Unix epoch, at which the neuron becomes dissolved.
** When a neuron is non-dissolving, i.e., the dissolve timer is stopped, the state is dissolve_delay_seconds and stores how much time, in seconds, the dissolve timer will be started with.
* followees: A neuron's followees stored as a map of topics (represented by an integer) to set of followee neurons.
* recent_ballots: Information about how this neuron voted in the recent past. It only contains proposals that the neuron voted yes or no on.
* kyc_verified: `true` if this neuron has passed KYC, `false` otherwise
* transfer: The record of the transfer that was made to create this neuron. This is not used anymore and always set to "None".
* maturity_e8s_equivalent: A neuron's maturity in "e8s equivalent". The maturity keeps track of the rewards that the neurons has collected. While this quantity is on the same scale as ICP tokens, it is not directly convertible to ICPs and conversion requires a minting event (e.g., spawn or merge the maturity).
* not_for_profit: Whether this neuron is "Not for profit", making it dissolvable by voting (see below)
* joined_community_fund_timestamp_seconds: The time point when this neuron joined the community fund.

== Manage Neuron Commands ==
In general, any changes to or in the name of a neuron (e.g., changes to the neuron's attributes or casting a vote in the name of the neuron) can be made in two ways:

# by using the manage_neuron interface of the governance canister or
# by making a special proposal of [[topic ManageNeuron]], where the basic idea is that a set of neurons can control a ''managed neuron'' by submitting and voting on special proposals. This only works if the managed neuron follows these controlling neurons for the proposal topic ManageNeuron. If this is given, the set of controlling neurons can send commands to the governance canister as if they were issued by the managed neuron's controller (that is with the same privileges that the managed neuron's controller has to manipulate the neuron). Thus, if it is stated that some neuron commands can only be done by a neuron's controller, this also includes the possibility that these commands are done per manageNeuron proposal.

We next list all commands that can be done by manage_neuron.

=== Claiming a neuron ===
This can be used to stake ICP utility tokens into a neuron. To do so, first a transfer must be made to the neuron's associated ledger account. Each transfer on the ledger account can be provided with a ''memo.'' After this transfer, the neuron can be claimed on the governance canister by providing the memo and the controller of the neuron. This allows the governance canister to find the corresponding account on the ledger canister and learn how many tokens should be staked in the corresponding neuron. A neuron is then created.

'''Access control (who can issue this command)'':''''' ''Anyone can call this method.''

'''Preconditions (other conditions that must hold):'''

'''The effect on the neuron's attributes:'''

=== Refreshing a neuron ===
Similarly to how a neuron is first created, a neuron can be topped up by making a transfer to the neuron's Ledger canister account and then calling the Governance canister, which will adjust the neuron's stake to the new balance on the neuron's account. For this to work, the caller must either provide the governance canister with the memo and controller (as with claiming a neuron) or with the neuron's ID or account.

'''''Access control (who can issue this command):''' Anyone can call this method.''

'''Preconditions (other conditions that must hold):'''

'''The effect on the neuron's attributes:'''

=== Configuring a neuron ===
Once a neuron is claimed, a neuron's controller might want to configure it. The following are commands that only configure a given neuron, but do not interact with the outside world.

'''Access control (who can issue this command):''' All neuron configurations can only be invoked by a neuron's controller.

* IncreaseDissolveDelay: Increases a neuron's dissolve delay by the given additional dissolve delay but at most to a given maximum dissolve delay (which is currently set to 8 years). If this method is called on a non-dissolving neuron, it remains non-dissolving. If it is called on dissolving neuron, it remains dissolving. If this configuration is called on a dissolved neuron, it becomes non-dissolving. Moreover, the neuron's aging_since_timestamp_seconds is reset to start counting from when it last entered the dissolved state in the case where the ''dissolved'' state was reached through explicit dissolution or to `now` when this is not applicable, e.g., when the neuron is newly created with zero dissolve delay.

* SetDissolveTimestamp: This is just another way of increasing the dissolve delay, by stating the target dissolve timestamp rather than the relative increase in the dissolve delay. It is internally translated to do the same as increasing the dissolve delay.
* StartDissolving: If this neuron is not dissolving, start dissolving it. If the neuron is dissolving or dissolved, an error is returned. Starting to dissolve a neuron intuitively means that the neuron's countdown to when the staked tokens can be liquidated is started. In terms of neuron attributes, the neuron's dissolve state is set to when_dissolved_timestamp_seconds which specifies the time now plus the neuron's dissolve delay (i.e., the defined countdown's duration). Moreover, the neuron's aging_since_timestamp_seconds is set to the maximum possible value, which represents that the neuron has no age as this will be in the future.

* StopDissolving: If this neuron is dissolving, set it to not dissolving. If the neuron is not dissolving, an error is returned. Intuitively, this means that the neuron's countdown towards when the staked tokens can be liquidated is stopped. In terms of neuron attributes, the neuron's state is set to dissolve_delay_seconds, which now tracks the remaining time on the countdown. Also, the neuron's aging_since_timestamp_seconds is set to now.

* AddHotKey: A new hot key is added to the neuron if the following preconditions hold: - key to add is not already present in 'hot_keys' - the key to add is well-formed - there are not already too many hot keys for this neuron (currently 10 hot keys are allowed).
* RemoveHotKey: The specified hot key is removed if it is in the list of hot keys.
* JoinCommunityFund: If the neuron has not yet joined the community fund, this configuration sets the neuron's joined_community_fund_timestamp_seconds to the current time. If the neuron is already a member of the community fund, an error is returned.

=== Make Proposal ===
This command can be used to submit a proposal in the name of a neuron. If successful, the command creates an initial electoral roll that includes a ballot for all neurons that are eligible to vote on the proposal at the time when the proposal is created and where the ballots state the neurons' voting power at the time of the proposal creation. The neuron that makes the proposal is charged the rejection fee upfront which will be reimbursed if the proposal is accepted (except for proposals of topic ManageNeuron) and the voting power of the proposer neuron is already counted towards the yes votes of the proposal.

'''Access control (who can issue this command):''' The neuron's controller or a registered hot key.

'''Preconditions (other conditions that must hold):'''

* The proposal is valid.
* The neuron is eligible to vote on the proposal (i.e., still has a minimum dissolve delay currently set to 6 months)
* The neuron has more stake than the cost of a rejected proposal.
* There are not already too many proposals.

'''The effect on the neuron's attributes:'''

* The neuron_fees_e8s are increased by the rejection fee (or, in case of a ManageNeuron proposal the corresponding fee)
* The recent_ballots are updated with the yes ballot that is cast for the proposer.

=== Register Vote ===
This is used to directly register a neuron's vote for a given proposal. Also, it triggers registering of a vote for all neurons that follow this neuron.

'''Access control (who can issue this command):''' The neuron's controller or a registered hot key.

'''Preconditions (other conditions that must hold):'''

* A proposal is specified and exists.
* The neuron is eligible to vote on this proposal, i.e., an empty ballot has been entered to the electoral roll (if this is not the case, then the neuron was not eligible at the time when the proposal was created and thus the neuron is not allowed to vote on it)
* The neuron has not already voted on this proposal

'''The effect on the neuron's attributes:'''

* The recent_ballots are updated.

=== Follow ===
Add or remove followees for this neuron for a specified topic. If the list of followees is empty, remove the followees for this topic. If the list has at least one element, replace the current list of followees for the given topic with the provided list. Note that the list is replaced, not addded to.

'''Access control (who can issue this command):''' The neuron's controller.

'''Preconditions (other conditions that must hold):'''

* The list of followees is not too long (currently we allow 15 followees per topic)

'''The effect on the neuron's attributes:'''

* The followees for the given topic are updated.

=== Spawn ===
This command allows to convert the neuron's collected rewards that are stored as the neuron's maturity to (staked) ICP utility tokens by minting the corresponding tokens (on the Ledger canister) and "spawning" them into a new neuron. The new ''child neuron'', containing the spawned staked tokens has a small dissolve delay, which means that the tokens can be liquidated after only a short period of time while the original ''parent neuron's'' tokens may still be locked for much longer.

'''Access control (who can issue this command):''' The neuron's controller.

'''Preconditions (other conditions that must hold):'''

* The parent neuron exists.
* The parent neuron is not involved in any neuron commands that have ledger interactions (to avoid inconsistencies).
* The parent neuron has accumulated maturity that would generate more than the minimum stake needed to create a new neuron.
* A controller for the new child neuron is provided that is valid.

'''The effect on the neuron's attributes:'''

* The maturity is decreased by the maturity at the time when the command started (a new reward event might have set it to non-zero already again)

'''The the new "child" neuron's attributes:'''

* id: random ID
* account: random account (that does not yet exist)

* controller: set to the provided controller

* hot_keys: same as parent neuron
* cached_neuron_stake_e8s: set to the parent's maturity at the time when the command started.
* neuron_fees_e8s: 0
* created_timestamp_seconds: current time
* aging_since_timestamp_seconds: current time
* dissolve_state: (non-dissolving) dissolve_delay_seconds set to neuron_spawn_dissolve_delay_seconds as defined in the governance economics (currently set to 7 days)
* followees: same as parent neuron
* recent_ballots: empty
* kyc_verified: same as parent neuron
* transfer: not set
* maturity_e8s_equivalent:0
* not_for_profit: false
* joined_community_fund_timestamp_seconds: None

=== Merge Maturity ===
This command allows to convert the neuron's collected rewards that are stored as the neuron's maturity to (staked) ICP utility tokens by adding them to the neuron's stake. The caller can choose a percentage of maturity to merge. The effect is that the corresponding tokens will be minted on the Ledger canister and added to the neuron's account.

'''Access control (who can issue this command):''' The neuron's controller.

'''Preconditions (other conditions that must hold):'''

* The neuron has some maturity to merge.
* The e8s equivalent of the amount of maturity to merge must be more than the transaction fee on the Ledger canister.

'''The effect on the neuron's attributes:'''

* The specified portion of the maturity is subtracted from the neuron's maturity_e8s_equivalent
* The specified portion of the maturity is added to the neuron's cached_neuron_stake_e8s
* The neuron's age (specified in aging_since_timestamp_seconds) is adjusted to reflect that the newly added tokens have no age

=== Disburse ===
Once a dissolving neuron's countdown has reached zero, the neuron is dissolved and can thus be disbursed, which means that (some or only a specified number of) the staked tokens can be transferred to a given account. If no target account is provided, the transfer is made to the caller's account (i.e., the neuron's controller's account).

In more detail, when a neuron is disbursed multiple steps happen:

# the neuron's accumulated fees are burned
# the neuron's accumulated maturity is converted to ICP utility tokens by minting the corresponding tokens and also transferring them to the target account
# the given staked amount (or the full stake if none is provided) is transferred to the target account

'''Access control (who can issue this command):''' The neuron's controller.

'''Preconditions (other conditions that must hold):'''

* The neuron exists.
* The neuron's state is `Dissolved` at the current timestamp, i.e., the dissolve countdown has reached zero.
* The neuron's kyc_verified is not false. That is, a neuron that was created with kyc_verified false cannot be disbursed until it went through kyc.

'''The effect on the neuron's attributes:'''

* The specified amount is subtracted from the neuron's cached_neuron_stake_e8s, as are the original neuron fees
* The neuron_fees_e8s is set to zero
* The maturity_e8s_equivalent is set to zero

=== Split ===
This command splits a ''parent neuron'' into two neurons, the original parent neuron and a new child neuron. This command may be useful, if a neuron holder would like for example to set the neuron configurations differently for a portion of the locked tokens.

The parent neuron's stake is decreased by the amount specified, while the child neuron is created with a stake equal to that amount, minus the Ledger canister transfer fee. The child neuron inherits all the properties of its parent.

'''Access control (who can issue this command):''' The neuron's controller.

'''Preconditions (other conditions that must hold):'''

* The parent neuron exists
* The parent neuron is not involved in any neuron commands that have ledger interactions (to avoid inconsistencies).
* The staked amount minus amount to split is more than the minimum stake (ensuring that the parent neuron has at least the minimum stake).
* The amount to split minus the transfer fee is more than the minimum stake (ensuring that the child neuron has at least the minimum stake).

'''The effect on the (parent) neuron's attributes:'''

* cached_neuron_stake_e8s: deduced by specified amount that is split

'''The the new "child" neuron's attributes:'''

* id: random ID
* account: random account (that does not yet exist)

* controller: same as parent neuron

* hot_keys: same as parent neuron
* cached_neuron_stake_e8s: set to specified amount that is split from parent minus the transaction fee
* neuron_fees_e8s: 0
* created_timestamp_seconds: current time
* aging_since_timestamp_seconds: same as parent neuron
* dissolve_state: same as parent neuron
* followees: same as parent neuron
* recent_ballots: empty
* kyc_verified: same as parent neuron
* transfer: not set
* maturity_e8s_equivalent: 0
* not_for_profit: same as parent neuron
* joined_community_fund_timestamp_seconds: same as parent neuron

=== Disburse to Neuron ===
(Intro)

'''Access control (who can issue this command):''' The neuron's controller.

'''Preconditions (other conditions that must hold):'''

'''The effect on the neuron's attributes:'''

Internet Computer wiki

2022-01-03T15:46:49Z

LaraAS:

Welcome to the Internet Computer Wiki! Feel free to join in. All are welcome!
== Topics Central ==

* [[Internet computer]]
* [[Internet Computer vision]]
* [[Index of dapps on the Internet Computer]]
* [[ICP token]]
* [[Internet Identity]]
* [https://dashboard.internetcomputer.org/ Internet Computer dashboard]
* [[Internet Computer Performance]]
* [[DFINITY]]
* [[Custody, Staking, and Voting]]
*[[Network Nervous System]]
*ICP is expected to outgrow every crypto in the known universe. ICP coins will be used to power the future of the world.
== For blockchain & crypto enthusiasts ==
* [[Myths and facts]]
* [https://www.reddit.com/r/dfinity/ r/dfinity]
* [[How to stake on the Internet computer]]
* [[Staking and Voting]]
* [[Tokenomics of the Internet Computer]]
* [[Governance of the Internet Computer]]
*[[Neuron Attributes and Commands]]

== For dapp developers ==
* [[Internet Computer for dapp developers]]
* [[Canister smart contracts]]
* [https://forum.dfinity.org/ IC community developer forum]
* [[Best practices for a high traffic dapp launch]]
* [[Best practices for NFT drops]]
* [[Current limitations of the IC]]

== For computer scientists ==
* [[The Internet Computer for Computer Scientists]]

== For node owners ==
* [[Internet Computer for node owners]]

== FAQs ==

* [[FAQ]]
== How-To section ==
How-Tos are step-by-step instructions for specific, narrow goals.
* [[How-To: Claim neurons for seed participants]]

== Tutorial section ==
Tutorials are guided introductions to user stories, intended for first-time users and characterized by a shallow learning curve.
* [[Tutorial: Neuron control]]

== Contributors ==

=== Housekeeping Rules ===

* Please refrain from redundancy, such as referring to the Internet Computer in article titles. This is, after all, the Internet Computer Wiki.
* Please carefully consider your use of capitalisation. Most words in titles should be capitalised. DFINITY is always stylised in all-caps.

=== How to Contribute ===
Consult the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents User's Guide] for information on using the wiki software.
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/postorius/lists/mediawiki-announce.lists.wikimedia.org/ MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Use this page to test editing
* [[Test editing the Internet Computer Wiki]]

Number of articles: {{NUMBEROFARTICLES}}

Neuron attributes and commands

2022-01-03T15:45:03Z

LaraAS: This page explains the neurons in the Network Nervous System (NNS), focusing on their attributes and the commands by which they can be changed.

This page explains the neurons in the Network Nervous System (NNS), focusing on their attributes and the commands by which they can be changed.

Governance of the Internet Computer

2021-12-13T18:17:49Z

LaraAS: adding archive canister to list of canisters

A key feature of the Internet Computer blockchain is the Network Nervous System (NNS)<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref>, an open algorithmic governance system that oversees the network and the token economics that make it possible to build DeFi and dapps, open internet services, and enterprise systems that are capable of operating at hyperscale.

Holders of the Internet Computer’s ICP utility tokens can lock their tokens in ''neurons'' to participate in governance and contribute to decision-making, such as voting to determine whether or not a new collection of nodes (also called a subnet) should be added to the network. By participating in governance, voters earn ''rewards''. They can use these rewards, or otherwise procured ICP utility tokens, to fuel the computations of their canisters.

=== Why the Internet Computer needs a Network Nervous System<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref> ===
The Internet Computer is a distributed protocol run by a network of node machines, which are hosted in different data centers. The nodes communicate with one another over the internet to achieve a consensus on what the Internet Computer’s state should be. A collection of nodes engaging in consensus is called a subnet. On top of this underlying communication and consensus protocol, the Internet Computer hosts ''canisters'', which are stateful programs that can also communicate with each other. The state of all of the canisters has to be replicated across all of the nodes. Therefore, to allow the Internet Computer to scale indefinitely, the network is made up of not just one subnet, but multiple subnets.

Different subnets can communicate with one another, enabling canisters that are hosted on different subnets to also communicate with each other. For the Internet Computer to scale on-demand, the network must be able to add new subnets over time to increase compute capacity. Moreover, the robustness of the subnets can be improved by adding new nodes to them over time. Eventually, the Internet Computer will run millions of nodes at scale. This means that there needs to be a mechanism by which the nodes and subnets are organised, tracked, and managed. For example, decisions must be made about when subnets and nodes should be added or removed. In addition, the Internet Computer was launched with an initial feature set, which evolves over time. Therefore, the Internet Computer needs to be able to make decisions on how to evolve the protocol in a distributed manner.

=Network Nervous System overview=

The Network Nervous System, or “NNS”, is a tokenised open governance system that is responsible for managing the Internet Computer. For example, it stores information about what nodes belong to which subnet. It also makes decisions about how to update this information.

The NNS is realised by a set of ''[[canisters]]''.

=== '''List of the NNS canisters''' ===

# '''Ledger canister:''' The ledger canister stores a. the ICP utility ''token balance'' of each principal and b. the history of ICP ''transactions''.
# '''Governance canister:''' The two most important concepts that the governance canister stores are a. ''Proposals'', which are suggestions for how the Internet Computer should be changed. These proposals can then be voted on. b. ''Neurons'', which determine who is allowed to participate in governance.
# '''Registry canister:''' This canister stores the configuration of the whole Internet Computer that can then be looked up by others. As an example, it stores which nodes belong to a certain subnet.
# '''Cycles minting canister''': This canister is responsible for minting ''cycles'', the fuel for canisters for computations and data storage. It is therefore involved in the initialisation of canisters as well as when canisters are 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 to keep in a single canister.
#'''Genesis token canister:''' This is the canister that was used to initialise the neurons that already existed during genesis.

The canisters that users of the Internet Computer are interacting with most are the first two: the ledger canister for making transactions, and the governance canister for staking tokens and submitting and voting on proposals.

= Ledger canister & ICP utility tokens in the NNS =
[[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.

In the NNS, ICP utility tokens are used for three different things:

# ICP tokens facilitate '''participation in governance''' (more below on how the neurons are connected with the tokens).
# 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 computations and data storage.

=Governance Canister=

The governance canister is responsible for holding ''neurons'', determining who is allowed to participate in governance. Moreover, it stores proposals, which are suggestions how how the Internet Computer should be changed, 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 ==
Neurons contain ''locked'' ICP utility tokens. This means that these tokens are not liquid and cannot be transferred freely to others.

=== '''Neuron Attributes''' ===
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.
* a ''controller'' as a principal ID, which identifies a public key
* a unique ''neuron ID''
*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 should incentivise neuron holders to vote such that the value of their tokens is maximised for a future date. If the value of the tokens is a rough proxy for the network’s success, this incentivises 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. In particular, the voting power is computed as the number of staked ICP utility tokens that is multiplied by a factor of up to 2 depending on the dissolve delay (which is between 0 and 8 years) and by a factor of up to 0.25 due to the age (between 0 and 4 years).

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.

===How to lock tokens in a neuron<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref>===

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.

'''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.''

''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.''

''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.''

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.

== Proposals ==
Intuitively, a proposal is a suggestion how the Internet Computer should be changed. 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.

The Internet Computer supports a variety of different proposal ''topics''. Here are some non-exhaustive examples of topics that are supported in the NNS governance canister:
* #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 ==

=== Submitting a proposal ===
Any eligible neuron can [[submit a proposal]]. To avoid being inundated by useless proposals, a user submitting a proposal has to pay a small fee 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.''

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.

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.

Moreover, each proposal has an associated ''voting period,'' which determines the period of time over which votes for this proposal are accepted.

=== Viewing NNS Proposals ===
You can see all the NNS proposals on the Internet Computer dashboard: https://dashboard.internetcomputer.org/governance

===Discussing NNS Proposals===

A lot of NNS proposals are discussed on the developer forum: https://forum.dfinity.org/c/roadmap/29

Notable examples:
* Direct integration with Bitcoin: https://forum.dfinity.org/t/direct-integration-with-bitcoin/6147
* Increasing smart contract memory: https://forum.dfinity.org/t/increased-canister-smart-contract-memory/6148

===Voting on a proposal===
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]].

If a neuron votes in favour 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.

'''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.''

====Neuron following and liquid democracy====

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 proposals 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.

'''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.''

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.

=== Proposal decision and wait-for-quiet ===
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.

=== Proposal execution ===
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 ==
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 a neuron's attributed that is called ''maturity.'' Maturity represents ICP utility token that are not yet minted.

A neuron holder can then profit from the maturity in two ways:

# '''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.
# '''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.

= Cycles Minting Canister and Cycles<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref> =
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 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 Cansiter. This canister then burns the tokens and mints the cycles.

The Cycles Minting Cansiter 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.

'''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.''

=References=

{{reflist}}

Governance of the Internet Computer

2021-12-13T15:04:41Z

LaraAS: Reorganised this page so that the logic follows the different canisters. Added information regarding different things, in particular: list of all relevant canisters, added information regarding neuron attributed, proposal lifecycle, liquid democracy,updated info on what can be done with maturity (was outdated), added links where I think new "how to" pages should be added

A key feature of the Internet Computer blockchain is the Network Nervous System (NNS)<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref>, an open algorithmic governance system that oversees the network and the token economics that make it possible to build DeFi and dapps, open internet services, and enterprise systems that are capable of operating at hyperscale.

Holders of the Internet Computer’s ICP utility tokens can lock their tokens in ''neurons'' to participate in governance and contribute to decision-making, such as voting to determine whether or not a new collection of nodes (also called a subnet) should be added to the network. By participating in governance, voters earn ''rewards''. They can use these rewards, or otherwise procured ICP utility tokens, to fuel the computations of their canisters.

=== Why the Internet Computer needs a Network Nervous System<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref> ===
The Internet Computer is a distributed protocol run by a network of node machines, which are hosted in different data centers. The nodes communicate with one another over the internet to achieve a consensus on what the Internet Computer’s state should be. A collection of nodes engaging in consensus is called a subnet. On top of this underlying communication and consensus protocol, the Internet Computer hosts ''canisters'', which are stateful programs that can also communicate with each other. The state of all of the canisters has to be replicated across all of the nodes. Therefore, to allow the Internet Computer to scale indefinitely, the network is made up of not just one subnet, but multiple subnets.

Different subnets can communicate with one another, enabling canisters that are hosted on different subnets to also communicate with each other. For the Internet Computer to scale on-demand, the network must be able to add new subnets over time to increase compute capacity. Moreover, the robustness of the subnets can be improved by adding new nodes to them over time. Eventually, the Internet Computer will run millions of nodes at scale. This means that there needs to be a mechanism by which the nodes and subnets are organised, tracked, and managed. For example, decisions must be made about when subnets and nodes should be added or removed. In addition, the Internet Computer was launched with an initial feature set, which evolves over time. Therefore, the Internet Computer needs to be able to make decisions on how to evolve the protocol in a distributed manner.

=Network Nervous System overview=

The Network Nervous System, or “NNS”, is a tokenised open governance system that is responsible for managing the Internet Computer. For example, it stores information about what nodes belong to which subnet. It also makes decisions about how to update this information.

The NNS is realised by a set of ''[[canisters]]''.

=== '''List of the NNS canisters''' ===

# '''Ledger canister:''' The ledger canister stores a. the ICP utility ''token balance'' of each principal and b. the history of ICP ''transactions''.
# '''Governance canister:''' The two most important concepts that the governance canister stores are a. ''Proposals'', which are suggestions for how the Internet Computer should be changed. These proposals can then be voted on. b. ''Neurons'', which determine who is allowed to participate in governance.
# '''Registry canister:''' This canister stores the configuration of the whole Internet Computer that can then be looked up by others. As an example, it stores which nodes belong to a certain subnet.
# '''Cycles minting canister''': This canister is responsible for minting ''cycles'', the fuel for canisters for computations and data storage. It is therefore involved in the initialisation of canisters as well as when canisters are 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.
# '''Genesis token canister:''' This is the canister that was used to initialise the neurons that already existed during genesis.

The canisters that users of the Internet Computer are interacting with most are the first two: the ledger canister for making transactions, and the governance canister for staking tokens and submitting and voting on proposals.

= Ledger canister & ICP utility tokens in the NNS =
[[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.

In the NNS, ICP utility tokens are used for three different things:

# ICP tokens facilitate '''participation in governance''' (more below on how the neurons are connected with the tokens).
# 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 computations and data storage.

=Governance Canister=

The governance canister is responsible for holding ''neurons'', determining who is allowed to participate in governance. Moreover, it stores proposals, which are suggestions how how the Internet Computer should be changed, 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 ==
Neurons contain ''locked'' ICP utility tokens. This means that these tokens are not liquid and cannot be transferred freely to others.

=== '''Neuron Attributes''' ===
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.
* a ''controller'' as a principal ID, which identifies a public key
* a unique ''neuron ID''
*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 should incentivise neuron holders to vote such that the value of their tokens is maximised for a future date. If the value of the tokens is a rough proxy for the network’s success, this incentivises 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. In particular, the voting power is computed as the number of staked ICP utility tokens that is multiplied by a factor of up to 2 depending on the dissolve delay (which is between 0 and 8 years) and by a factor of up to 0.25 due to the age (between 0 and 4 years).

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.

===How to lock tokens in a neuron<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref>===

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.

'''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.''

''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.''

''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.''

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.

== Proposals ==
Intuitively, a proposal is a suggestion how the Internet Computer should be changed. 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.

The Internet Computer supports a variety of different proposal ''topics''. Here are some non-exhaustive examples of topics that are supported in the NNS governance canister:
* #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 ==

=== Submitting a proposal ===
Any eligible neuron can [[submit a proposal]]. To avoid being inundated by useless proposals, a user submitting a proposal has to pay a small fee 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.''

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.

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.

Moreover, each proposal has an associated ''voting period,'' which determines the period of time over which votes for this proposal are accepted.

=== Viewing NNS Proposals ===
You can see all the NNS proposals on the Internet Computer dashboard: https://dashboard.internetcomputer.org/governance

===Discussing NNS Proposals===

A lot of NNS proposals are discussed on the developer forum: https://forum.dfinity.org/c/roadmap/29

Notable examples:
* Direct integration with Bitcoin: https://forum.dfinity.org/t/direct-integration-with-bitcoin/6147
* Increasing smart contract memory: https://forum.dfinity.org/t/increased-canister-smart-contract-memory/6148

===Voting on a proposal===
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]].

If a neuron votes in favour 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.

'''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.''

====Neuron following and liquid democracy====

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 proposals 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.

'''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.''

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.

=== Proposal decision and wait-for-quiet ===
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.

=== Proposal execution ===
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 ==
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 a neuron's attributed that is called ''maturity.'' Maturity represents ICP utility token that are not yet minted.

A neuron holder can then profit from the maturity in two ways:

# '''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.
# '''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.

= Cycles Minting Canister and Cycles<ref>https://medium.com/dfinity/the-network-nervous-system-governing-the-internet-computer-1d176605d66a</ref> =
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 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 Cansiter. This canister then burns the tokens and mints the cycles.

The Cycles Minting Cansiter 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.

'''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.''

=References=

{{reflist}}