@dfinity/nns-proto 0.0.1

package/dist/proto/governance.proto

@@ -0,0 +1,292 @@
+syntax = "proto3";
+
+package ic_nns_governance.pb.v1;
+
+import "base_types.proto";
+import "ledger.proto";
+
+// All operations that modify the state of an existing neuron are
+// represented by instances of `ManageNeuron`.
+//
+// All commands are available to the `controller` of the neuron. In
+// addition, commands related to voting, i.g., [manage_neuron::Follow]
+// and [manage_neuron::RegisterVote], are also available to the
+// registered hot keys of the neuron.
+message ManageNeuron {
+  option (ic_base_types.pb.v1.tui_signed_message) = true;
+
+  // This is the legacy way to specify neuron IDs that is now discouraged.
+  ic_base_types.pb.v1.NeuronId id = 1 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true];
+
+  // The ID of the neuron to manage. This can either be a subaccount or a neuron ID.
+  oneof neuron_id_or_subaccount {
+    bytes subaccount = 11 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true];
+    ic_base_types.pb.v1.NeuronId neuron_id = 12 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true];
+  }
+
+  message IncreaseDissolveDelay {
+    uint32 additional_dissolve_delay_seconds = 1 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true];
+  }
+
+  message StartDissolving {}
+  message StopDissolving {}
+
+  message AddHotKey {
+    ic_base_types.pb.v1.PrincipalId new_hot_key = 1 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true];
+  }
+
+  message RemoveHotKey {
+    ic_base_types.pb.v1.PrincipalId hot_key_to_remove = 1 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true];
+  }
+
+  // Commands that only configure a given neuron, but do not interact
+  // with the outside world. They all require the caller to be the
+  // controller of the neuron.
+  message Configure {
+    oneof operation {
+      IncreaseDissolveDelay increase_dissolve_delay = 1;
+      StartDissolving start_dissolving = 2;
+      StopDissolving stop_dissolving = 3;
+      AddHotKey add_hot_key = 4;
+      RemoveHotKey remove_hot_key = 5;
+      JoinCommunityFund join_community_fund = 7;
+    }
+  }
+
+  message Spawn {
+    ic_base_types.pb.v1.PrincipalId new_controller = 1 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true];
+    optional uint64 nonce = 2;
+    optional uint32 percentage_to_spawn = 3;
+  }
+
+  message Disburse {
+    option (ic_base_types.pb.v1.tui_signed_message) = true;
+    message Amount {
+      option (ic_base_types.pb.v1.tui_signed_message) = true;
+      uint64 e8s = 1 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true, jstype = JS_STRING];
+    }
+    Amount amount = 1 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true];
+    ic_ledger.pb.v1.AccountIdentifier to_account = 2 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true];
+  }
+
+  message Follow {
+    Topic topic = 1;
+    repeated ic_base_types.pb.v1.NeuronId followees = 2;
+  }
+
+  message RegisterVote {
+    ic_base_types.pb.v1.ProposalId proposal = 1;
+    Vote vote = 2;
+  }
+
+  // Merge another neuron into this neuron.
+  message Merge {
+    // The neuron to merge stake and maturity from.
+    ic_base_types.pb.v1.NeuronId source_neuron_id = 1;
+  }
+
+  message MergeMaturity {
+    uint32 percentage_to_merge = 1;
+  }
+
+  message JoinCommunityFund {}
+
+  oneof command {
+    Configure configure = 2;
+    Disburse disburse = 3;
+    Spawn spawn = 4;
+    Follow follow = 5;
+    RegisterVote register_vote = 7;
+    MergeMaturity merge_maturity = 13;
+    Merge merge = 14;
+  }
+}
+
+
+// The response of the ManageNeuron command
+//
+// There is a dedicated response type for each `ManageNeuron.command` field
+message ManageNeuronResponse {
+  message ConfigureResponse {}
+
+  message DisburseResponse {
+    uint64 transfer_block_height = 1 [jstype = JS_STRING];
+  }
+
+  message SpawnResponse {
+    ic_base_types.pb.v1.NeuronId created_neuron_id = 1;
+  }
+
+  message MergeMaturityResponse {
+    uint64 merged_maturity_e8s = 1 [jstype = JS_STRING];
+    uint64 new_stake_e8s = 2 [jstype = JS_STRING];
+  }
+
+  message FollowResponse {}
+
+  message RegisterVoteResponse {}
+
+  message MergeResponse {}
+
+  oneof command {
+    GovernanceError error = 1;
+    ConfigureResponse configure = 2;
+    DisburseResponse disburse = 3;
+    SpawnResponse spawn = 4;
+    FollowResponse follow = 5;
+    RegisterVoteResponse register_vote = 7;
+    MergeMaturityResponse merge_maturity = 11;
+    MergeResponse merge = 12;
+  }
+}
+
+message GovernanceError {
+  enum ErrorType {
+     ERROR_TYPE_UNSPECIFIED = 0;
+     // The operation was successfully completed.
+     ERROR_TYPE_OK = 1;
+     // This operation is not available, e.g., not implemented.
+     ERROR_TYPE_UNAVAILABLE = 2;
+     // The caller is not authorized to perform this operation.
+     ERROR_TYPE_NOT_AUTHORIZED = 3;
+     // Some entity required for the operation (for example, a neuron) was not found.
+     ERROR_TYPE_NOT_FOUND = 4;
+     // The command was missing or invalid. This is a permanent error.
+     ERROR_TYPE_INVALID_COMMAND = 5;
+     // The neuron is dissolving or dissolved and the operation requires it to
+     // be not dissolving (that is, having a non-zero dissolve delay that is
+     // accumulating age).
+     ERROR_TYPE_REQUIRES_NOT_DISSOLVING = 6;
+     // The neuron is not dissolving or dissolved and the operation requires
+     // it to be dissolving (that is, having a non-zero dissolve delay with
+     // zero age that is not accumulating).
+     ERROR_TYPE_REQUIRES_DISSOLVING = 7;
+     // The neuron is not dissolving and not dissolved and the operation
+     // requires it to be dissolved (that is, having a dissolve delay of zero
+     // and an age of zero).
+     ERROR_TYPE_REQUIRES_DISSOLVED = 8;
+     // When adding or removing a hot key: the key to add was already
+     // present or the key to remove was not present or the key to add
+     // was invalid or adding another hot key would bring the total
+     // number of the maximum number of allowed hot keys per neuron.
+     ERROR_TYPE_HOT_KEY = 9;
+     // Some canister side resource is exhausted, so this operation cannot be
+     // performed.
+     ERROR_TYPE_RESOURCE_EXHAUSTED = 10;
+     // Some precondition for executing this method was not met (e.g. the
+     // neuron's desolve time is too short). There could be a change in the
+     // state of the system such that the operation becomes allowed (e.g. the
+     // owner of the neuron increases its desolve delay).
+     ERROR_TYPE_PRECONDITION_FAILED = 11;
+     // Executing this method failed for some reason external to the
+     // governance canister.
+     ERROR_TYPE_EXTERNAL = 12;
+     // A neuron has an ongoing ledger update and thus can't be
+     // changed.
+     ERROR_TYPE_LEDGER_UPDATE_ONGOING = 13;
+     // There wasn't enough funds to perform the operation.
+     ERROR_TYPE_INSUFFICIENT_FUNDS = 14;
+     // The principal provided was invalid.
+     ERROR_TYPE_INVALID_PRINCIPAL = 15;
+     // The proposal is defective in some way (e.g. title is too long). If the
+     // same proposal is submitted again without modification, it will be
+     // rejected regardless of changes in the system's state (e.g. increasing
+     // the neuron's desolve delay will not make the proposal acceptable).
+     ERROR_TYPE_INVALID_PROPOSAL = 16;
+     // The neuron attempted to join the community fund while already
+     // a member.
+     ERROR_TYPE_ALREADY_JOINED_COMMUNITY_FUND = 17;
+  }
+
+  ErrorType error_type = 1;
+  string error_message = 2;
+}
+
+message ListNeurons {
+  option (ic_base_types.pb.v1.tui_signed_message) = true;
+  repeated fixed64 neuron_ids = 1 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true, jstype = JS_STRING];
+  bool include_neurons_readable_by_caller = 2 [(ic_base_types.pb.v1.tui_signed_display_q2_2021) = true];
+}
+
+message ListNeuronsResponse {
+  message NeuronMapEntry {
+    fixed64 key = 1 [jstype = JS_STRING];
+    NeuronInfo value = 2;
+  }
+
+  // Was originally `map<fixed64, NeuronInfo> neuron_infos = 1`
+  // It had to be modified to this form to annotate the key with js_type.
+  repeated NeuronMapEntry neuron_ids = 1;
+  repeated Neuron full_neurons = 2;
+}
+
+message BallotInfo {
+  ic_base_types.pb.v1.ProposalId proposal_id = 1;
+  Vote vote = 2;
+}
+
+message NeuronInfo {
+  uint64 retrieved_at_timestamp_seconds = 1 [jstype = JS_STRING];;
+  uint64 age_seconds = 3 [jstype = JS_STRING];
+  uint64 dissolve_delay_seconds = 4 [jstype = JS_STRING];
+  repeated BallotInfo recent_ballots = 5;
+  uint64 voting_power = 6 [jstype = JS_STRING];
+  uint64 created_timestamp_seconds = 7 [jstype = JS_STRING];
+}
+
+message Neuron {
+  ic_base_types.pb.v1.NeuronId id = 1;
+  bytes account = 2;
+  ic_base_types.pb.v1.PrincipalId controller = 3;
+  repeated ic_base_types.pb.v1.PrincipalId hot_keys = 4;
+  uint64 cached_neuron_stake_e8s = 5 [jstype = JS_STRING];
+  uint64 neuron_fees_e8s = 6 [jstype = JS_STRING];
+  uint64 created_timestamp_seconds = 7 [jstype = JS_STRING];
+  uint64 aging_since_timestamp_seconds = 8 [jstype = JS_STRING];
+  optional uint64 spawn_at_timestamp_seconds = 19 [jstype = JS_STRING];
+  oneof dissolve_state {
+    uint64 when_dissolved_timestamp_seconds = 9 [jstype = JS_STRING];
+    uint64 dissolve_delay_seconds = 10 [jstype = JS_STRING];
+  }
+  message Followees { repeated ic_base_types.pb.v1.NeuronId followees = 1; }
+  map<int32, Followees> followees = 11;
+  repeated BallotInfo recent_ballots = 12;
+  bool kyc_verified = 13;
+  NeuronStakeTransfer transfer = 14;
+  uint64 maturity_e8s_equivalent = 15 [jstype = JS_STRING];
+  bool not_for_profit = 16;
+}
+
+enum Vote {
+  VOTE_UNSPECIFIED = 0;
+  VOTE_YES = 1;
+  VOTE_NO = 2;
+}
+
+message NeuronStakeTransfer {
+  uint64 transfer_timestamp = 1 [jstype = JS_STRING];
+  ic_base_types.pb.v1.PrincipalId from = 2;
+  bytes from_subaccount = 3;
+  bytes to_subaccount = 4;
+  uint64 neuron_stake_e8s = 5 [jstype = JS_STRING];
+  uint64 block_height = 6 [jstype = JS_STRING];
+  uint64 memo = 7 [jstype = JS_STRING];
+}
+
+enum Topic {
+  TOPIC_UNSPECIFIED = 0;
+  TOPIC_NEURON_MANAGEMENT = 1;
+  TOPIC_EXCHANGE_RATE = 2;
+  TOPIC_NETWORK_ECONOMICS = 3;
+  TOPIC_GOVERNANCE = 4;
+  TOPIC_NODE_ADMIN = 5;
+  TOPIC_PARTICIPANT_MANAGEMENT = 6;
+  TOPIC_SUBNET_MANAGEMENT = 7;
+  TOPIC_NETWORK_CANISTER_MANAGEMENT = 8;
+  TOPIC_KYC = 9;
+  TOPIC_NODE_PROVIDER_REWARDS = 10;
+  TOPIC_SNS_DECENTRALIZATION_SALE = 11;
+  TOPIC_SUBNET_REPLICA_VERSION_MANAGEMENT = 12;
+  TOPIC_REPLICA_VERSION_MANAGEMENT = 13;
+  TOPIC_SNS_AND_COMMUNITY_FUND = 14;
+}