@dfinity/nns 10.2.0 → 10.3.1-next-2025-10-15

package/dist/candid/governance.idl.js

@@ -262,8 +262,29 @@ export const idlFactory = ({ IDL }) => {
     'total' : IDL.Nat64,
     'timestamp_seconds' : IDL.Nat64,
   });
+  const TopicToFollow = IDL.Variant({
+    'Kyc' : IDL.Null,
+    'ServiceNervousSystemManagement' : IDL.Null,
+    'ApiBoundaryNodeManagement' : IDL.Null,
+    'ApplicationCanisterManagement' : IDL.Null,
+    'SubnetRental' : IDL.Null,
+    'NeuronManagement' : IDL.Null,
+    'NodeProviderRewards' : IDL.Null,
+    'SubnetManagement' : IDL.Null,
+    'ExchangeRate' : IDL.Null,
+    'CatchAll' : IDL.Null,
+    'NodeAdmin' : IDL.Null,
+    'IcOsVersionElection' : IDL.Null,
+    'ProtocolCanisterManagement' : IDL.Null,
+    'NetworkEconomics' : IDL.Null,
+    'IcOsVersionDeployment' : IDL.Null,
+    'ParticipantManagement' : IDL.Null,
+    'Governance' : IDL.Null,
+    'SnsAndCommunityFund' : IDL.Null,
+  });
   const KnownNeuronData = IDL.Record({
     'name' : IDL.Text,
+    'committed_topics' : IDL.Opt(IDL.Vec(IDL.Opt(TopicToFollow))),
     'description' : IDL.Opt(IDL.Text),
     'links' : IDL.Opt(IDL.Vec(IDL.Text)),
   });
@@ -706,6 +727,10 @@ export const idlFactory = ({ IDL }) => {
     'Ok' : MonthlyNodeProviderRewards,
     'Err' : GovernanceError,
   });
+  const GetNeuronIndexRequest = IDL.Record({
+    'page_size' : IDL.Opt(IDL.Nat32),
+    'exclusive_start_neuron_id' : IDL.Opt(NeuronId),
+  });
   const NeuronInfo = IDL.Record({
     'dissolve_delay_seconds' : IDL.Nat64,
     'recent_ballots' : IDL.Vec(BallotInfo),
@@ -723,6 +748,11 @@ export const idlFactory = ({ IDL }) => {
     'voting_power' : IDL.Nat64,
     'age_seconds' : IDL.Nat64,
   });
+  const NeuronIndexData = IDL.Record({ 'neurons' : IDL.Vec(NeuronInfo) });
+  const GetNeuronIndexResult = IDL.Variant({
+    'Ok' : NeuronIndexData,
+    'Err' : GovernanceError,
+  });
   const Result_5 = IDL.Variant({ 'Ok' : NeuronInfo, 'Err' : GovernanceError });
   const GetNeuronsFundAuditInfoRequest = IDL.Record({
     'nns_proposal_id' : IDL.Opt(ProposalId),
@@ -982,6 +1012,11 @@ export const idlFactory = ({ IDL }) => {
         ['query'],
       ),
     'get_neuron_ids' : IDL.Func([], [IDL.Vec(IDL.Nat64)], ['query']),
+    'get_neuron_index' : IDL.Func(
+        [GetNeuronIndexRequest],
+        [GetNeuronIndexResult],
+        ['query'],
+      ),
     'get_neuron_info' : IDL.Func([IDL.Nat64], [Result_5], ['query']),
     'get_neuron_info_by_id_or_subaccount' : IDL.Func(
         [NeuronIdOrSubaccount],
@@ -1308,8 +1343,29 @@ export const init = ({ IDL }) => {
     'total' : IDL.Nat64,
     'timestamp_seconds' : IDL.Nat64,
   });
+  const TopicToFollow = IDL.Variant({
+    'Kyc' : IDL.Null,
+    'ServiceNervousSystemManagement' : IDL.Null,
+    'ApiBoundaryNodeManagement' : IDL.Null,
+    'ApplicationCanisterManagement' : IDL.Null,
+    'SubnetRental' : IDL.Null,
+    'NeuronManagement' : IDL.Null,
+    'NodeProviderRewards' : IDL.Null,
+    'SubnetManagement' : IDL.Null,
+    'ExchangeRate' : IDL.Null,
+    'CatchAll' : IDL.Null,
+    'NodeAdmin' : IDL.Null,
+    'IcOsVersionElection' : IDL.Null,
+    'ProtocolCanisterManagement' : IDL.Null,
+    'NetworkEconomics' : IDL.Null,
+    'IcOsVersionDeployment' : IDL.Null,
+    'ParticipantManagement' : IDL.Null,
+    'Governance' : IDL.Null,
+    'SnsAndCommunityFund' : IDL.Null,
+  });
   const KnownNeuronData = IDL.Record({
     'name' : IDL.Text,
+    'committed_topics' : IDL.Opt(IDL.Vec(IDL.Opt(TopicToFollow))),
     'description' : IDL.Opt(IDL.Text),
     'links' : IDL.Opt(IDL.Vec(IDL.Text)),
   });

package/dist/candid/governance_test.certified.idl.js

@@ -262,8 +262,29 @@ export const idlFactory = ({ IDL }) => {
     'total' : IDL.Nat64,
     'timestamp_seconds' : IDL.Nat64,
   });
+  const TopicToFollow = IDL.Variant({
+    'Kyc' : IDL.Null,
+    'ServiceNervousSystemManagement' : IDL.Null,
+    'ApiBoundaryNodeManagement' : IDL.Null,
+    'ApplicationCanisterManagement' : IDL.Null,
+    'SubnetRental' : IDL.Null,
+    'NeuronManagement' : IDL.Null,
+    'NodeProviderRewards' : IDL.Null,
+    'SubnetManagement' : IDL.Null,
+    'ExchangeRate' : IDL.Null,
+    'CatchAll' : IDL.Null,
+    'NodeAdmin' : IDL.Null,
+    'IcOsVersionElection' : IDL.Null,
+    'ProtocolCanisterManagement' : IDL.Null,
+    'NetworkEconomics' : IDL.Null,
+    'IcOsVersionDeployment' : IDL.Null,
+    'ParticipantManagement' : IDL.Null,
+    'Governance' : IDL.Null,
+    'SnsAndCommunityFund' : IDL.Null,
+  });
   const KnownNeuronData = IDL.Record({
     'name' : IDL.Text,
+    'committed_topics' : IDL.Opt(IDL.Vec(IDL.Opt(TopicToFollow))),
     'description' : IDL.Opt(IDL.Text),
     'links' : IDL.Opt(IDL.Vec(IDL.Text)),
   });
@@ -706,6 +727,10 @@ export const idlFactory = ({ IDL }) => {
     'Ok' : MonthlyNodeProviderRewards,
     'Err' : GovernanceError,
   });
+  const GetNeuronIndexRequest = IDL.Record({
+    'page_size' : IDL.Opt(IDL.Nat32),
+    'exclusive_start_neuron_id' : IDL.Opt(NeuronId),
+  });
   const NeuronInfo = IDL.Record({
     'dissolve_delay_seconds' : IDL.Nat64,
     'recent_ballots' : IDL.Vec(BallotInfo),
@@ -723,6 +748,11 @@ export const idlFactory = ({ IDL }) => {
     'voting_power' : IDL.Nat64,
     'age_seconds' : IDL.Nat64,
   });
+  const NeuronIndexData = IDL.Record({ 'neurons' : IDL.Vec(NeuronInfo) });
+  const GetNeuronIndexResult = IDL.Variant({
+    'Ok' : NeuronIndexData,
+    'Err' : GovernanceError,
+  });
   const Result_5 = IDL.Variant({ 'Ok' : NeuronInfo, 'Err' : GovernanceError });
   const GetNeuronsFundAuditInfoRequest = IDL.Record({
     'nns_proposal_id' : IDL.Opt(ProposalId),
@@ -978,6 +1008,11 @@ export const idlFactory = ({ IDL }) => {
       ),
     'get_network_economics_parameters' : IDL.Func([], [NetworkEconomics], []),
     'get_neuron_ids' : IDL.Func([], [IDL.Vec(IDL.Nat64)], []),
+    'get_neuron_index' : IDL.Func(
+        [GetNeuronIndexRequest],
+        [GetNeuronIndexResult],
+        [],
+      ),
     'get_neuron_info' : IDL.Func([IDL.Nat64], [Result_5], []),
     'get_neuron_info_by_id_or_subaccount' : IDL.Func(
         [NeuronIdOrSubaccount],
@@ -1293,8 +1328,29 @@ export const init = ({ IDL }) => {
     'total' : IDL.Nat64,
     'timestamp_seconds' : IDL.Nat64,
   });
+  const TopicToFollow = IDL.Variant({
+    'Kyc' : IDL.Null,
+    'ServiceNervousSystemManagement' : IDL.Null,
+    'ApiBoundaryNodeManagement' : IDL.Null,
+    'ApplicationCanisterManagement' : IDL.Null,
+    'SubnetRental' : IDL.Null,
+    'NeuronManagement' : IDL.Null,
+    'NodeProviderRewards' : IDL.Null,
+    'SubnetManagement' : IDL.Null,
+    'ExchangeRate' : IDL.Null,
+    'CatchAll' : IDL.Null,
+    'NodeAdmin' : IDL.Null,
+    'IcOsVersionElection' : IDL.Null,
+    'ProtocolCanisterManagement' : IDL.Null,
+    'NetworkEconomics' : IDL.Null,
+    'IcOsVersionDeployment' : IDL.Null,
+    'ParticipantManagement' : IDL.Null,
+    'Governance' : IDL.Null,
+    'SnsAndCommunityFund' : IDL.Null,
+  });
   const KnownNeuronData = IDL.Record({
     'name' : IDL.Text,
+    'committed_topics' : IDL.Opt(IDL.Vec(IDL.Opt(TopicToFollow))),
     'description' : IDL.Opt(IDL.Text),
     'links' : IDL.Opt(IDL.Vec(IDL.Text)),
   });

package/dist/candid/governance_test.d.ts

@@ -94,6 +94,9 @@ export interface ClaimOrRefreshNeuronFromAccountResponse {
 export interface ClaimOrRefreshResponse {
   refreshed_neuron_id: [] | [NeuronId];
 }
+/**
+ * KEEP THIS IN SYNC WITH ManageNeuronCommandRequest!
+ */
 export type Command =
   | { Spawn: Spawn }
   | { Split: Split }
@@ -264,6 +267,13 @@ export interface FulfillSubnetRentalRequest {
    */
   node_ids: [] | [Array<Principal>];
 }
+export interface GetNeuronIndexRequest {
+  page_size: [] | [number];
+  exclusive_start_neuron_id: [] | [NeuronId];
+}
+export type GetNeuronIndexResult =
+  | { Ok: NeuronIndexData }
+  | { Err: GovernanceError };
 export interface GetNeuronsFundAuditInfoRequest {
   nns_proposal_id: [] | [ProposalId];
 }
@@ -394,6 +404,12 @@ export interface KnownNeuron {
 }
 export interface KnownNeuronData {
   name: string;
+  /**
+   * The first `opt` makes it so that the field can be renamed/deprecated in the future, and
+   * the second `opt` makes it so that an older client not recognizing a new variant can still
+   * get the rest of the `vec`.
+   */
+  committed_topics: [] | [Array<[] | [TopicToFollow]>];
   description: [] | [string];
   links: [] | [Array<string>];
 }
@@ -406,17 +422,45 @@ export interface LedgerParameters {
 export interface ListKnownNeuronsResponse {
   known_neurons: Array<KnownNeuron>;
 }
+/**
+ * Parameters of the list_neurons method.
+ */
 export interface ListNeurons {
   page_size: [] | [bigint];
+  /**
+   * When a public neuron is a member of the result set, include it in the
+   * full_neurons field (of ListNeuronsResponse). This does not affect which
+   * neurons are part of the result set.
+   */
   include_public_neurons_in_full_neurons: [] | [boolean];
+  /**
+   * These fields select neurons to be in the result set.
+   */
   neuron_ids: BigUint64Array | bigint[];
   page_number: [] | [bigint];
+  /**
+   * Only has an effect when include_neurons_readable_by_caller.
+   */
   include_empty_neurons_readable_by_caller: [] | [boolean];
   neuron_subaccounts: [] | [Array<NeuronSubaccount>];
   include_neurons_readable_by_caller: boolean;
 }
+/**
+ * Output of the list_neurons method.
+ */
 export interface ListNeuronsResponse {
+  /**
+   * Per the NeuronInfo type, this is a redacted view of the neurons in the
+   * result set consisting of information that require no special privileges to
+   * view.
+   */
   neuron_infos: Array<[bigint, NeuronInfo]>;
+  /**
+   * If the caller has the necessary special privileges (or the neuron is
+   * public, and the request sets include_public_neurons_in_full_neurons to
+   * true), then all the information about the neurons in the result set is made
+   * available here.
+   */
   full_neurons: Array<Neuron>;
   total_pages_available: [] | [bigint];
 }
@@ -451,11 +495,18 @@ export interface MakeProposalResponse {
   message: [] | [string];
   proposal_id: [] | [ProposalId];
 }
+/**
+ * Not to be confused with ManageNeuronRequest. (Yes, this is very structurally
+ * similar to that, but not actually exactly equivalent.)
+ */
 export interface ManageNeuron {
   id: [] | [NeuronId];
   command: [] | [Command];
   neuron_id_or_subaccount: [] | [NeuronIdOrSubaccount];
 }
+/**
+ * KEEP THIS IN SYNC WITH COMMAND!
+ */
 export type ManageNeuronCommandRequest =
   | { Spawn: Spawn }
   | { Split: Split }
@@ -472,12 +523,31 @@ export type ManageNeuronCommandRequest =
   | { StakeMaturity: StakeMaturity }
   | { MergeMaturity: MergeMaturity }
   | { Disburse: Disburse };
+/**
+ * Parameters of the manage_neuron method.
+ */
 export interface ManageNeuronRequest {
+  /**
+   * Deprecated. Use neuron_id_or_subaccount instead.
+   */
   id: [] | [NeuronId];
+  /**
+   * What operation to perform on the neuron.
+   */
   command: [] | [ManageNeuronCommandRequest];
+  /**
+   * Which neuron to operate on.
+   */
   neuron_id_or_subaccount: [] | [NeuronIdOrSubaccount];
 }
+/**
+ * Output of the manage_neuron method.
+ */
 export interface ManageNeuronResponse {
+  /**
+   * Corresponds to the command field in ManageNeuronRequest, which determines
+   * what operation was performed.
+   */
   command: [] | [Command_1];
 }
 export interface MaturityDisbursement {
@@ -537,10 +607,67 @@ export interface Neuron {
   recent_ballots: Array<BallotInfo>;
   voting_power_refreshed_timestamp_seconds: [] | [bigint];
   kyc_verified: boolean;
+  /**
+   * The amount of "sway" this neuron can have if it refreshes its voting power
+   * frequently enough.
+   *
+   * Unlike deciding_voting_power, this does NOT take refreshing into account.
+   * Rather, this only takes three factors into account:
+   *
+   * 1. (Net) staked amount - This is the "base" of a neuron's voting power.
+   * This primarily consists of the neuron's ICP balance.
+   *
+   * 2. Age - Neurons with more age have more voting power (all else being
+   * equal).
+   *
+   * 3. Dissolve delay - Neurons with longer dissolve delay have more voting
+   * power (all else being equal). Neurons with a dissolve delay of less
+   * than six months are not eligible to vote. Therefore, such neurons
+   * are considered to have 0 voting power.
+   *
+   * Per NNS policy, this is opt. Nevertheless, it will never be null.
+   */
   potential_voting_power: [] | [bigint];
   neuron_type: [] | [number];
   not_for_profit: boolean;
   maturity_e8s_equivalent: bigint;
+  /**
+   * The amount of "sway" this neuron has when voting on proposals.
+   *
+   * When a proposal is created, each eligible neuron gets a "blank" ballot. The
+   * amount of voting power in that ballot is set to the neuron's deciding
+   * voting power at the time of proposal creation. There are two ways that a
+   * proposal can become decided:
+   *
+   * 1. Early: Either more than half of the total voting power in the ballots
+   * votes in favor (then the proposal is approved), or at least half of the
+   * votal voting power in the ballots votes against (then, the proposal is
+   * rejected).
+   *
+   * 2. The proposal's voting deadline is reached. At that point, if there is
+   * more voting power in favor than against, and at least 3% of the total
+   * voting power voted in favor, then the proposal is approved. Otherwise, it
+   * is rejected.
+   *
+   * If a neuron regularly refreshes its voting power, this has the same value
+   * as potential_voting_power. Actions that cause a refresh are as follows:
+   *
+   * 1. voting directly (not via following)
+   * 2. set following
+   * 3. refresh voting power
+   *
+   * (All of these actions are performed via the manage_neuron method.)
+   *
+   * However, if a neuron has not refreshed in a "long" time, this will be less
+   * than potential voting power. See VotingPowerEconomics. As a further result
+   * of less deciding voting power, not only does it have less influence on the
+   * outcome of proposals, the neuron receives less voting rewards (when it
+   * votes indirectly via following).
+   *
+   * For details, see https://dashboard.internetcomputer.org/proposal/132411.
+   *
+   * Per NNS policy, this is opt. Nevertheless, it will never be null.
+   */
   deciding_voting_power: [] | [bigint];
   cached_neuron_stake_e8s: bigint;
   created_timestamp_seconds: bigint;
@@ -549,6 +676,10 @@ export interface Neuron {
   hot_keys: Array<Principal>;
   account: Uint8Array | number[];
   joined_community_fund_timestamp_seconds: [] | [bigint];
+  /**
+   * The maturity disbursements in progress, i.e. the disbursements that are initiated but not
+   * finalized. The finalization happens 7 days after the disbursement is initiated.
+   */
   maturity_disbursements_in_progress: [] | [Array<MaturityDisbursement>];
   dissolve_state: [] | [DissolveState];
   followees: Array<[number, Followees]>;
@@ -583,6 +714,17 @@ export interface NeuronInFlightCommand {
   command: [] | [Command_2];
   timestamp: bigint;
 }
+export interface NeuronIndexData {
+  neurons: Array<NeuronInfo>;
+}
+/**
+ * A limit view of Neuron that allows some aspects of all neurons to be read by
+ * anyone (i.e. without having to be the neuron's controller nor one of its
+ * hotkeys).
+ *
+ * As such, the meaning of each field in this type is generally the same as the
+ * one of the same (or at least similar) name in Neuron.
+ */
 export interface NeuronInfo {
   dissolve_delay_seconds: bigint;
   recent_ballots: Array<BallotInfo>;
@@ -592,11 +734,27 @@ export interface NeuronInfo {
   deciding_voting_power: [] | [bigint];
   created_timestamp_seconds: bigint;
   state: number;
+  /**
+   * The amount of ICP (and staked maturity) locked in this neuron.
+   *
+   * This is the foundation of the neuron's voting power.
+   *
+   * cached_neuron_stake_e8s - neuron_fees_e8s + staked_maturity_e8s_equivalent
+   */
   stake_e8s: bigint;
   joined_community_fund_timestamp_seconds: [] | [bigint];
   retrieved_at_timestamp_seconds: bigint;
   visibility: [] | [number];
   known_neuron_data: [] | [KnownNeuronData];
+  /**
+   * Deprecated. Use either deciding_voting_power or potential_voting_power
+   * instead. Has the same value as deciding_voting_power.
+   *
+   * Previously, if a neuron had < 6 months dissolve delay (making it ineligible
+   * to vote), this would not get set to 0 (zero). That was pretty confusing.
+   * Now that this is set to deciding_voting_power, this actually does get
+   * zeroed out.
+   */
   voting_power: bigint;
   age_seconds: bigint;
 }
@@ -964,6 +1122,31 @@ export interface TimeWindow {
 export interface Tokens {
   e8s: [] | [bigint];
 }
+/**
+ * A topic that can be followed. It is almost the same as the topic on the
+ * proposal, except that the `CatchAll` is a special value and following on this
+ * `topic` will let the neuron follow the votes on all topics except for
+ * Governance and SnsAndCommunityFund.
+ */
+export type TopicToFollow =
+  | { Kyc: null }
+  | { ServiceNervousSystemManagement: null }
+  | { ApiBoundaryNodeManagement: null }
+  | { ApplicationCanisterManagement: null }
+  | { SubnetRental: null }
+  | { NeuronManagement: null }
+  | { NodeProviderRewards: null }
+  | { SubnetManagement: null }
+  | { ExchangeRate: null }
+  | { CatchAll: null }
+  | { NodeAdmin: null }
+  | { IcOsVersionElection: null }
+  | { ProtocolCanisterManagement: null }
+  | { NetworkEconomics: null }
+  | { IcOsVersionDeployment: null }
+  | { ParticipantManagement: null }
+  | { Governance: null }
+  | { SnsAndCommunityFund: null };
 export interface UpdateCanisterSettings {
   canister_id: [] | [Principal];
   settings: [] | [CanisterSettings];
@@ -1041,6 +1224,7 @@ export interface _SERVICE {
   >;
   get_network_economics_parameters: ActorMethod<[], NetworkEconomics>;
   get_neuron_ids: ActorMethod<[], BigUint64Array | bigint[]>;
+  get_neuron_index: ActorMethod<[GetNeuronIndexRequest], GetNeuronIndexResult>;
   get_neuron_info: ActorMethod<[bigint], Result_5>;
   get_neuron_info_by_id_or_subaccount: ActorMethod<
     [NeuronIdOrSubaccount],
@@ -1076,6 +1260,9 @@ export interface _SERVICE {
     ManageNeuronResponse
   >;
   transfer_gtc_neuron: ActorMethod<[NeuronId, NeuronId], Result>;
+  /**
+   * The following are methods for feature = "test"
+   */
   update_neuron: ActorMethod<[Neuron], [] | [GovernanceError]>;
   update_node_provider: ActorMethod<[UpdateNodeProvider], Result>;
 }