Periodic confirmation - API changes & Release plan

Governance NNS Governance
,
1

TL;DR

  • We share the API changes and the release plan for the feature periodic confirmation
  • Neurons will have a new field voting_power_refreshed_timestamp_seconds indicating when the neuron last voted directly, set following, or confirm following (called “refreshed their voting power” in the API).
  • Neuron holders: By the end of November, users can reset their neuron’s timer by performing any of these actions. Neurons who are not performing any of them will have adjusted voting power in March 2025 and their followees reset in April 2025.
  • Integrators: All API changes shared today will be released by the end of November. The adjusted voting power will be developed behind a feature flag and be turned on at the beginning of the new year.

Intro

Hi all,

As we are making some progress on the periodic confirmation feature, we would like to share the detailed API changes and the release plan. This is particularly important for frontends and products that integrate with governance, so that they can implement the required changes on their end.

In the following, we will assume that readers are familiar with the high-level design that has been approved by the NNS. If you would like to read up more on it, we recommend reading the approved motion proposal and the forum post where the design was discussed.

Governance API

You can find the detailed API changes in this draft PR for the governance.did changes.

Here is a summary of the main changes.

Neuron attributes

  • Each neuron has a new field voting_power_refreshed_timestamp_seconds that records when the neuron last took any of the actions of voting, set following, or confirm following.
    • If a neuron performs any of these actions, the timestamp is set to the current time now.
    • The field is initialized with the timestamp representing midnight Sep 1st 2024 UTC.
    • New neurons have this field set to the same value as created_timestamp_seconds.
  • For each neuron, there are two new fields indicating the neuron’s voting power.
    deciding_voting_power indicates the voting power that a neuron exercises on proposals. This voting power is adjusted in the case where the neuron hasn’t voted directly, set following, or confirmed following for more than 6 months.
    potential_voting_power indicates the voting power that the neuron had if it regularly confirmed following (or voted directly or set following).
    • Unlike the current field voting_power, both deciding_voting_power and potential_voting_power will be shown as zero for neurons that are not eligible for voting (have less than 6 months dissolve delay).
    • The existing field voting_power is deprecated. For backwards compatibility it will for now remain existent and will newly also show zero for neurons that are not eligible.

Neuron actions

  • There is a new manage neuron command RefreshVotingPower to confirm the following on a neuron. It is called “refresh voting power” because calling this refreshes the new neuron field voting_power_refreshed_timestamp_seconds to now.
    • Remark: Note that even without this new action (and before it is implemented) the same can be achieved by reading a neuron’s followees and setting the neuron’s followers to the same selection or by voting directly.

Proposal attributes

  • Each proposal has a new field total_potential_voting_power that denotes the sum of the potential voting powers for all eligible neurons. This is used as a basis for distributing rewards as laid out in the design.

Nervous system parameters

  • There are two new nervous system parameters: start_reducing_voting_power_after_seconds defines the time period after a neuron’s timer has been refreshed when the neurons’ voting power is adjusted and clear_following_after_seconds determines the time period from when the voting power adjustment kicked in to when the neuron’s voting power will reach zero and the neuron’s followees are reset.
    • start_reducing_voting_power_after_seconds will be initialized with 0.5 years and clear_following_after_seconds with 1/12 year (which is how one month is defined in the governance code).

Release plan

This is the release plan we aim at.

Next week (until Nov 18 2024)

  • Each neuron has a new timestamp voting_power_refreshed_timestamp_seconds that is set to Sep 1st 2024
  • New nervous system parameters

Second half of November 2024

  • Refreshing of the neuron’s voting_power_refreshed_timestamp_seconds when the neuron votes directly, sets following, or confirms following
    => Users: at this time, users can already take any of these actions to refresh the timer of their neurons. When they do, they have again 6 months until the neuron would have adjusted voting power.
  • New APIs (as above)
    => Integrators: those who want to integrate with this feature or build a frontend for it have all APIs needed to do so.

December 2024

  • Behind a feature flag, implement the effect of the feature on voting power in the neurons and the proposals. Note that this has no effect yet. This is to give all integrators time to implement the feature on their end.

January 2025

  • Turn on the feature flag so that the feature takes effect.

March 2025

  • => The neurons who haven’t taken any action until now, start having adjusted voting power

April 2025

  • => The neurons who haven’t taken any action until now, will have their followees reset

Next steps / updates

We are actively working on the above changes and will post important updates in this thread.

9 Likes
2

Wow @lara! DFINITY is making amazing progress on implementation of this feature. I can’t believe this change is finally upon us. All the details sound consistent with what I recall from prior discussions about periodic confirmation.

1 Like