NNS Canisters

The Network Nervous System (NNS) is the decentralized autonomous organization (DAO) that governs the Internet Computer by proposals on which ICP neuron owners can vote. Once such a proposal is accepted, it is autonomously executed.

The NNS of the Internet Computer is realized by a set of canisters. NNS canisters include:

1. Ledger canister: The ledger canister stores the ICP utility token balance of each principal and the history of ICP transactions.
2. 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.
3. 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.
4. 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.
5. Root canister: The root canister is the controller of all other NNS canisters and responsible for upgrading them.
6. Lifeline canister: The lifeline canister is the controller of the root canister and responsible for upgrading it.
7. Archive canisters: The canisters that store the history of the ledger transactions once there are too many transactions to keep in a single canister.
8. Genesis token canister: The canister that initialized 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 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:

1. ICP tokens facilitate participation in governance (more below on how the neurons are connected with the tokens).
2. Those who participate in governance and those who provide compute capacity by operating note machines are rewarded in ICP tokens.
3. 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

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?
  1. 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 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 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 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:

1. Absolute Majority before the voting period ends: At any point, even before the voting period ends, if an absolute majority (more than half of the total voting power stored in the proposal) has voted Yes, then the proposal is adopted and if an absolute majority has voted No, then the proposal is rejected.
2. Simple Majority at the voting period’s end: When the voting period ends, if a simple majority (more than half of the cast votes) has voted Yes and the number of these Yes-votes constitute at least 3% of the total voting power, then the proposal is adopted. Otherwise, the proposal is rejected.

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 the neuron's attribute that is called maturity.

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

1. Spawn maturity: A neuron holder can choose to 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.
2. Stake maturity: A user can stake maturity which locks the maturity until the neuron is dissolved. Once a neuron is dissolved, staked maturity is unlocked and becomes normal maturity. Staked maturity contributes to the voting power of the neuron as determined by Voting Power = (ICP staked + maturity staked) x Dissolve Delay Bonus x Age Bonus. No ICP is (or can be) produced from staked maturity until the neuron is dissolved and the maturity is spawned (as described in the section above), at which point it is subject to maturity modulation.

Cycles Minting Canister and Cycles

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.

See also

• Medium article
• Video