feat(nns): Define API for disburse maturity (#4138)

# Why

Similar to SNS, we'd like to support disbursing maturity instead of
spawning neurons from it, since most of the time the users just want the
minted ICP by converting the maturity.

# What

* Define a new manage neuron command `DisburseMaturity` and
corresponding response, in .proto, .rs and .did
* Add `#[serde(with = "serde_bytes")]` to the subaccount bytes in the
API type

Author: jasonz-dfinity

rs/nns/governance/api/src/ic_nns_governance.pb.v1.rs

@@ -1081,6 +1081,29 @@ pub mod manage_neuron {
     )]
     pub struct RefreshVotingPower {}
 
+    /// Disburse the maturity of a neuron to any ledger account. If an account
+    /// is not specified, the caller's account will be used. The caller can choose
+    /// a percentage of the current maturity to disburse to the ledger account. The
+    /// resulting amount to disburse must be greater than or equal to the
+    /// transaction fee.
+    #[derive(
+        candid::CandidType,
+        candid::Deserialize,
+        serde::Serialize,
+        comparable::Comparable,
+        Clone,
+        PartialEq,
+        ::prost::Message,
+    )]
+    pub struct DisburseMaturity {
+        /// The percentage to disburse, from 1 to 100
+        #[prost(uint32, tag = "1")]
+        pub percentage_to_disburse: u32,
+        /// The (optional) principal to which to transfer the stake.
+        #[prost(message, optional, tag = "2")]
+        pub to_account: ::core::option::Option<super::Account>,
+    }
+
     /// The ID of the neuron to manage. This can either be a subaccount or a neuron ID.
     #[derive(candid::CandidType, candid::Deserialize, serde::Serialize, comparable::Comparable)]
     #[allow(clippy::derive_partial_eq_without_eq)]
@@ -1124,6 +1147,8 @@ pub mod manage_neuron {
         StakeMaturity(StakeMaturity),
         #[prost(message, tag = "16")]
         RefreshVotingPower(RefreshVotingPower),
+        #[prost(message, tag = "17")]
+        DisburseMaturity(DisburseMaturity),
         // KEEP THIS IN SYNC WITH ManageNeuronCommandRequest!
     }
 }
@@ -1254,6 +1279,21 @@ pub mod manage_neuron_response {
     )]
     pub struct RefreshVotingPowerResponse {}
 
+    #[derive(
+        candid::CandidType,
+        candid::Deserialize,
+        serde::Serialize,
+        comparable::Comparable,
+        Clone,
+        Copy,
+        PartialEq,
+        ::prost::Message,
+    )]
+    pub struct DisburseMaturityResponse {
+        #[prost(uint64, optional, tag = "1")]
+        amount_disbursed_e8s: Option<u64>,
+    }
+
     #[derive(candid::CandidType, candid::Deserialize, serde::Serialize, comparable::Comparable)]
     #[allow(clippy::derive_partial_eq_without_eq)]
     #[derive(Clone, PartialEq, ::prost::Oneof)]
@@ -1286,6 +1326,8 @@ pub mod manage_neuron_response {
         StakeMaturity(StakeMaturityResponse),
         #[prost(message, tag = "14")]
         RefreshVotingPower(RefreshVotingPowerResponse),
+        #[prost(message, tag = "15")]
+        DisburseMaturity(DisburseMaturityResponse),
     }
 
     // Below, we should remove `manage_neuron_response::`, but that should be
@@ -1545,6 +1587,8 @@ pub enum ManageNeuronCommandRequest {
     StakeMaturity(manage_neuron::StakeMaturity),
     #[prost(message, tag = "16")]
     RefreshVotingPower(manage_neuron::RefreshVotingPower),
+    #[prost(message, tag = "17")]
+    DisburseMaturity(manage_neuron::DisburseMaturity),
     // KEEP THIS IN SYNC WITH manage_neuron::Command!
 }
 
@@ -4181,6 +4225,30 @@ pub mod restore_aging_summary {
         }
     }
 }
+
+/// A Ledger account identified by the owner of the account `of` and
+/// the `subaccount`. If the `subaccount` is not specified then the default
+/// one is used.
+#[derive(
+    candid::CandidType,
+    candid::Deserialize,
+    serde::Serialize,
+    comparable::Comparable,
+    Clone,
+    PartialEq,
+    ::prost::Message,
+)]
+pub struct Account {
+    /// The owner of the account.
+    #[prost(message, optional, tag = "1")]
+    pub owner: ::core::option::Option<::ic_base_types::PrincipalId>,
+    /// The subaccount of the account. If not set then the default
+    /// subaccount (all bytes set to 0) is used.
+    #[prost(message, optional, tag = "2")]
+    #[serde(deserialize_with = "ic_utils::deserialize::deserialize_option_blob")]
+    pub subaccount: ::core::option::Option<Vec<u8>>,
+}
+
 /// Proposal types are organized into topics. Neurons can automatically
 /// vote based on following other neurons, and these follow
 /// relationships are defined per topic.

rs/nns/governance/api/src/proposal_submission_helpers.rs

@@ -139,6 +139,7 @@ impl From<ManageNeuronCommandRequest> for Command {
             ManageNeuronCommandRequest::Merge(v) => Command::Merge(v),
             ManageNeuronCommandRequest::StakeMaturity(v) => Command::StakeMaturity(v),
             ManageNeuronCommandRequest::RefreshVotingPower(v) => Command::RefreshVotingPower(v),
+            ManageNeuronCommandRequest::DisburseMaturity(v) => Command::DisburseMaturity(v),
         }
     }
 }

rs/nns/governance/canister/governance.did

@@ -123,6 +123,20 @@ type RefreshVotingPowerResponse = record {
   // minimal until we discover there is a "real need". YAGNI.
 };
 
+type DisburseMaturity = record {
+  percentage_to_disburse : nat32;
+  to_account : opt Account;
+};
+
+type Account = record {
+  owner: opt principal;
+  subaccount: opt blob;
+};
+
+type DisburseMaturityResponse = record {
+  amount_disbursed_e8s : opt nat64;
+};
+
 // KEEP THIS IN SYNC WITH ManageNeuronCommandRequest!
 type Command = variant {
   Spawn : Spawn;
@@ -138,6 +152,7 @@ type Command = variant {
   MergeMaturity : MergeMaturity;
   Disburse : Disburse;
   RefreshVotingPower : RefreshVotingPower;
+  DisburseMaturity : DisburseMaturity;
 
   // KEEP THIS IN SYNC WITH ManageNeuronCommandRequest!
 };
@@ -157,6 +172,7 @@ type Command_1 = variant {
   MergeMaturity : MergeMaturityResponse;
   Disburse : DisburseResponse;
   RefreshVotingPower : RefreshVotingPowerResponse;
+  DisburseMaturity : DisburseMaturityResponse;
 };
 
 type Command_2 = variant {
@@ -540,6 +556,7 @@ type ManageNeuronCommandRequest = variant {
   MergeMaturity : MergeMaturity;
   Disburse : Disburse;
   RefreshVotingPower : RefreshVotingPower;
+  DisburseMaturity : DisburseMaturity;
 
   // KEEP THIS IN SYNC WITH COMMAND!
 };

rs/nns/governance/canister/governance_test.did

@@ -123,6 +123,20 @@ type RefreshVotingPowerResponse = record {
   // minimal until we discover there is a "real need". YAGNI.
 };
 
+type DisburseMaturity = record {
+  percentage_to_disburse : nat32;
+  to_account : opt Account;
+};
+
+type Account = record {
+  owner: opt principal;
+  subaccount: opt blob;
+};
+
+type DisburseMaturityResponse = record {
+  amount_disbursed_e8s : opt nat64;
+};
+
 type Command = variant {
   Spawn : Spawn;
   Split : Split;
@@ -137,6 +151,7 @@ type Command = variant {
   MergeMaturity : MergeMaturity;
   Disburse : Disburse;
   RefreshVotingPower : RefreshVotingPower;
+  DisburseMaturity : DisburseMaturity;
 };
 
 type Command_1 = variant {
@@ -154,6 +169,7 @@ type Command_1 = variant {
   MergeMaturity : MergeMaturityResponse;
   Disburse : DisburseResponse;
   RefreshVotingPower : RefreshVotingPowerResponse;
+  DisburseMaturity : DisburseMaturityResponse;
 };
 
 type Command_2 = variant {
@@ -517,6 +533,7 @@ type ManageNeuronCommandRequest = variant {
   MergeMaturity : MergeMaturity;
   Disburse : Disburse;
   RefreshVotingPower : RefreshVotingPower;
+  DisburseMaturity : DisburseMaturity;
 };
 
 type ManageNeuronRequest = record {

rs/nns/governance/proto/ic_nns_governance/pb/v1/governance.proto

@@ -1100,6 +1100,19 @@ message ManageNeuron {
   // fields in Neuron.
   message RefreshVotingPower {}
 
+  // Disburse the maturity of a neuron to any ledger account. If an account
+  // is not specified, the caller's account will be used. The caller can choose
+  // a percentage of the current maturity to disburse to the ledger account. The
+  // resulting amount to disburse must be greater than or equal to the
+  // transaction fee.
+  message DisburseMaturity {
+    // The percentage to disburse, from 1 to 100
+    uint32 percentage_to_disburse = 1;
+
+    // The (optional) principal to which to transfer the stake.
+    Account to_account = 2;
+  }
+
   oneof command {
     Configure configure = 2;
     Disburse disburse = 3;
@@ -1114,6 +1127,7 @@ message ManageNeuron {
     Merge merge = 14;
     StakeMaturity stake_maturity = 15;
     RefreshVotingPower refresh_voting_power = 16;
+    DisburseMaturity disburse_maturity = 17;
   }
 }
 
@@ -2717,3 +2731,20 @@ message ProposalVotingStateMachine {
   repeated ic_nns_common.pb.v1.NeuronId followers_to_check = 4;
   map<uint64, Vote> recent_neuron_ballots_to_record = 5;
 }
+
+// A Ledger subaccount.
+message Subaccount {
+  bytes subaccount = 1;
+}
+
+// A Ledger account identified by the owner of the account `of` and
+// the `subaccount`. If the `subaccount` is not specified then the default
+// one is used.
+message Account {
+  // The owner of the account.
+  ic_base_types.pb.v1.PrincipalId owner = 1;
+
+  // The subaccount of the account. If not set then the default
+  // subaccount (all bytes set to 0) is used.
+  optional Subaccount subaccount = 2;
+}

rs/nns/governance/src/gen/ic_nns_governance.pb.v1.rs

@@ -780,7 +780,7 @@ pub struct ManageNeuron {
     pub neuron_id_or_subaccount: ::core::option::Option<manage_neuron::NeuronIdOrSubaccount>,
     #[prost(
         oneof = "manage_neuron::Command",
-        tags = "2, 3, 4, 5, 6, 7, 8, 9, 10, 13, 14, 15, 16"
+        tags = "2, 3, 4, 5, 6, 7, 8, 9, 10, 13, 14, 15, 16, 17"
     )]
     pub command: ::core::option::Option<manage_neuron::Command>,
 }
@@ -1270,6 +1270,28 @@ pub mod manage_neuron {
         ::prost::Message,
     )]
     pub struct RefreshVotingPower {}
+    /// Disburse the maturity of a neuron to any ledger account. If an account
+    /// is not specified, the caller's account will be used. The caller can choose
+    /// a percentage of the current maturity to disburse to the ledger account. The
+    /// resulting amount to disburse must be greater than or equal to the
+    /// transaction fee.
+    #[derive(
+        candid::CandidType,
+        candid::Deserialize,
+        serde::Serialize,
+        comparable::Comparable,
+        Clone,
+        PartialEq,
+        ::prost::Message,
+    )]
+    pub struct DisburseMaturity {
+        /// The percentage to disburse, from 1 to 100
+        #[prost(uint32, tag = "1")]
+        pub percentage_to_disburse: u32,
+        /// The (optional) principal to which to transfer the stake.
+        #[prost(message, optional, tag = "2")]
+        pub to_account: ::core::option::Option<super::Account>,
+    }
     /// The ID of the neuron to manage. This can either be a subaccount or a neuron ID.
     #[derive(
         candid::CandidType,
@@ -1323,6 +1345,8 @@ pub mod manage_neuron {
         StakeMaturity(StakeMaturity),
         #[prost(message, tag = "16")]
         RefreshVotingPower(RefreshVotingPower),
+        #[prost(message, tag = "17")]
+        DisburseMaturity(DisburseMaturity),
     }
 }
 #[derive(candid::CandidType, candid::Deserialize, serde::Serialize, comparable::Comparable)]
@@ -4214,6 +4238,41 @@ pub struct ProposalVotingStateMachine {
     #[prost(map = "uint64, enumeration(Vote)", tag = "5")]
     pub recent_neuron_ballots_to_record: ::std::collections::HashMap<u64, i32>,
 }
+/// A Ledger subaccount.
+#[derive(
+    candid::CandidType,
+    candid::Deserialize,
+    serde::Serialize,
+    comparable::Comparable,
+    Clone,
+    PartialEq,
+    ::prost::Message,
+)]
+pub struct Subaccount {
+    #[prost(bytes = "vec", tag = "1")]
+    pub subaccount: ::prost::alloc::vec::Vec<u8>,
+}
+/// A Ledger account identified by the owner of the account `of` and
+/// the `subaccount`. If the `subaccount` is not specified then the default
+/// one is used.
+#[derive(
+    candid::CandidType,
+    candid::Deserialize,
+    serde::Serialize,
+    comparable::Comparable,
+    Clone,
+    PartialEq,
+    ::prost::Message,
+)]
+pub struct Account {
+    /// The owner of the account.
+    #[prost(message, optional, tag = "1")]
+    pub owner: ::core::option::Option<::ic_base_types::PrincipalId>,
+    /// The subaccount of the account. If not set then the default
+    /// subaccount (all bytes set to 0) is used.
+    #[prost(message, optional, tag = "2")]
+    pub subaccount: ::core::option::Option<Subaccount>,
+}
 /// Proposal types are organized into topics. Neurons can automatically
 /// vote based on following other neurons, and these follow
 /// relationships are defined per topic.

rs/nns/governance/src/governance.rs

@@ -6332,6 +6332,10 @@ impl Governance {
             Some(Command::RefreshVotingPower(_)) => self
                 .refresh_voting_power(&id, caller)
                 .map(ManageNeuronResponse::refresh_voting_power_response),
+            Some(Command::DisburseMaturity(_)) => Err(GovernanceError::new_with_message(
+                ErrorType::Unavailable,
+                "Disbursing maturity is not implemented yet.",
+            )),
             None => panic!(),
         }
     }