Internet Computer NNS Neurons Can Now Be Merged

Network Nervous System neuron holders can combine multiple neurons owned by the same controller key into a single neuron.

The Internet Computer blockchain is controlled by the Network Nervous System (NNS), an open, permissionless algorithmic governance system. ICP utility token holders can stake their tokens within neurons in the NNS to engage in network governance and vote on whether to adopt or reject network proposals, while earning voting rewards for their participation.

NNS neuron holders who own more than a single neuron have been interested in the option of combining them into one neuron. Accordingly, the DFINITY Foundation R&D team has implemented a feature in the NNS to permit the merging of multiple neurons owned by the same controller key into a single neuron, which can be done via the command line or the NNS front-end dapp (see steps below).

The merging of neurons is implemented by transferring all stake, age, and maturity from a source neuron into a target neuron, provided that the necessary preconditions discussed below are met. The properties of the resulting neuron are derived from those of all of the source neurons by weighting them according to their respective stake.

This blog post reviews everything that might happen when you merge two neurons, such as what happens to your stake, your maturity, your neuron’s aging bonus, etc. (Note: Merging is not currently supported for neurons controlled via hotkey or via hardware wallet, or neurons that have been dedicated to the NNS community fund.)

Why merge neurons?

If you own multiple neurons, it can be cumbersome to repeatedly spawn or merge maturity in each of them as the maturity reaches 1 ICP token in value. In the case where several of your neurons have a similar dissolve delay, merging them into a single neuron makes managing them easier and allows for the more frequent merging of maturity.

The operation proceeds by merging a “source” neuron into a “target” neuron. If you’re using the command-line utility quill, the command is:

quill neuron-manage <TARGET_ID> — merge-from-neuron <SOURCE_ID>

For NNS front-end dapp users, here is an example of how the steps will appear:

1. The Neurons tab lists the user’s neurons.

2. Clicking the “Merge Neurons” button creates a pop-up widget from which the user can select the two neurons they want to merge. The selected neurons are highlighted.

3. The user must re-confirm the action before the neurons are merged, which is irreversible.

4. Wait for the merge process to complete.

5. Upon completion, the user will see that the two neurons have been merged into a single neuron.

Restrictions

There are few restrictions to note:

• The user must own both neurons — that is, they must both be controlled by the same principal id.
• They must be different neurons.
• Neither neuron may be involved in a current proposal, whether as a proposer, or as the subject of a ManageNeuron proposal.
• The ManageNeuron followees of both neurons must match.
• They must agree in their KYC and not-for-profit flags, if either of these are set.
• Neither neuron may be committed to the community fund. This is not yet supported.

Expected outcomes

If your merge operation fulfills these restrictions and succeeds, the following will happen:

1. The entire stake from the source neuron is moved into the target neuron, minus the usual transaction fee.
2. Any stake reserved to potentially pay rejected proposal fees in the source neuron are immediately burned.
3. All maturity in the source neuron is moved to the target neuron. Note: Since maturity is displayed as a percentage of stake in the NNS dapp, it may not be clear that this is what happened.
4. Any age accumulated in the source neuron — due to it being non-dissolving — is “moved” into the target, but only if the target is not dissolving. If the target is dissolving, any age from the source will be lost. The resulting dissolve delay will be the greater of the two neurons, which means that if you merge an 8-year neuron into a 1-year neuron, the target neuron will now have a dissolve delay of 8 years.
5. Whether the source or the target is currently dissolving remains unchanged. So although the dissolve delay of the target is set to the larger of the two, its dissolve state is otherwise unaffected.
6. Followees for voting remain unchanged in both neurons.
7. Hot keys remain unchanged in both neurons.

What will happen to the source neuron?

• The source neuron’s stake will be zero.
• The source neuron’s maturity will be zero, but could increase after the merging operation if there were any open proposals at the time of the merge that the source neuron was able to vote on.
• The source neuron’s age will be zero.
• The source neuron’s proposal fees will be burned, and thus also zero.
• The source neuron’s dissolving state is left untouched.
• The source neuron’s dissolve delay is left untouched.
• The source neuron’s set of followees and hot keys are left untouched.

What will happen to the target neuron?

• The target neuron’s stake will be the sum of the two neuron’s stakes, minus the transaction fee.
• The target neuron’s maturity will be the sum of the two neurons’ maturities.
• The target neuron’s age will include any age that had accumulated in the source. This is not the sum exactly, but rather:
  ((target_stake * target_age) + (source_stake * source_age)) /
  (target_stake + source_stake)
• The target neuron’s proposal fees are left unchanged.
• The target neuron’s dissolving state is left untouched.
• The target neuron’s dissolve delay will be increased to match the source neuron, but only if the source’s delay was longer.
• The target neuron’s set of followees and hot keys are left untouched.

Additional implications

With the exception of fees, the following also hold true:

• Merging immediately after splitting has no effect (other than the temporary creation of another neuron, and the expense of transaction fees).
• Merging a source neuron with no dissolve delay has the same effect as “topping up” (also known as refreshing).
• If the dissolve delay of the target is extended to match the source, then the total APY for both neurons together is increased due to that extension. Otherwise, the total APY is identical.

In the days following merging from a source neuron, it’s possible there will still be proposals open showing voting activity by that neuron. This means you may receive voting rewards in the form of maturity for that neuron over the next several days.

Here’s what is happening in the NNS that causes this:

1. Every time a proposal is created, a “ballot” is made for every neuron you hold that has voting power. This reflects votes you may cast on that proposal, and guards against “buying voting power” after a proposal becomes known.
2. When the proposal is finally closed, you earn a reward for your voting participation (if you voted, of course) based on your ballot.
3. Now, when merging two neurons: we merge the neurons, but not the ballots. We don’t merge ballots because this would require changing proposal data that until now is fixed and read-only until the proposal is executed. We deemed the security risk of making this aspect of proposals “changeable” to be higher than the education problem of dealing with dangling neurons.

Fortunately, the solution is easy: Wait until one week after you merge your neurons, then merge them again if they re-appear in your list of neurons on the NNS Dapp. Any bits of maturity remaining (even if it is too small to appear as a percentage) will be transferred, and thereafter the source neuron will truly be at zero stake and maturity and stay there — because it has no voting power, and cannot produce future ballots.

This issue is likely to affect everyone who merges neurons with voting power, and has been causing confusion on Twitter, Reddit, here, and elsewhere. Nothing can be lost by merging your neurons. So please link people to this post if you see the question being asked!

____

Start building at smartcontracts.org and join the developer community at forum.dfinity.org.