ListNeurons API Change - Empty Neurons

Governance NNS Governance
1

We’d like to propose a change to the behavior of the list_neurons canister method in NNS Governance.

Background: Empty Neurons

Neurons can become empty in one of the 2 ways: (1) merging neurons - the source neuron would become empty (2) disbursing neurons after they are dissolved (neurons spawned from maturity also fall into this category). Such neurons can be “revived” by staking more ICPs, and they still contain some records such as recent ballots, but beyond that they are not very useful. In addition, the NNS Dapp never shows such neurons to the users.

Current Behavior

In the ListNeurons request, there is a boolean flag: include_empty_neurons_readable_by_caller, which lets the caller specify whether they’d like the response to include “empty” neurons (stake/maturity are both 0). This flag only takes effect when include_neurons_readable_by_caller is set to true. When the caller does not specify include_empty_neurons_readable_by_caller (i.e. it is set to null), the NNS Governance canister treats it as if the value is opt true, in order to maintain its behavior prior to the introduction of this flag. In other words, for clients who choose not to set this field (or written before the flag was introduced), empty neurons are still included in the response.

type ListNeurons = record {
  include_public_neurons_in_full_neurons : opt bool;
  neuron_ids : vec nat64;
  include_empty_neurons_readable_by_caller : opt bool;
  include_neurons_readable_by_caller : bool;
}

Upcoming API change

In the next release (to be proposed on Jan 24, 2025), we will propose changing the default value of include_empty_neurons_readable_by_caller to false instead (essentially, treating null as opt false). Clients can still opt to retrieve such neurons by setting the flag to opt true explicitly.

Next steps towards a cleaner API

One thing to consider in the future is that the flag can be removed entirely (although there is no such plan yet), while retaining the behavior of opt false. Even after that, clients would still be able to retrieve empty neurons by calling get_neuron_ids and then list_neurons, by supplying neuron_ids in the list_neurons request. Feedback or suggestions on this next step would be much appreciated.

4 Likes
2

Two calls wouldn’t be necessary if this feature was added: NNS Governance canister feature request: list_neurons by subaccount

Clients can compute their own neuron subaccounts, like principal + nonce, nonce can be a simple incrementing number and you can easily query certain neurons if list_neurons supported subaccounts like all the other endpoints do.

There could be a new method list_neurons_by_id_or_subaccount or there could be an optional value in the current list_neurons method like neuron_ids_or_subaccounts.

Maybe the team can look at adding this too since work is being planned here.

2 Likes
3

Thanks! I think it indeed could be helpful in very specific use cases where the caller is the controller of the neurons. Two calls would still be needed when the callers are hotkeys (e.g. for services which manage certain aspects of a user’s neurons).