feat(nns): Added Neuron::voting_power_refreshed_timestamp_seconds fie…

…ld. (#2268)

When creating a new neuron, this field gets set to the same value as
created_timestamp_seconds.

For existing neurons, they will be treated as though the value in this
field is 1 second after midnight 2024-11-05 UTC (until they refresh).

In a later PR, the value in this field will get updated to the current
time whenever the user performs "relevant" operations.

Closes https://dfinity.atlassian.net/browse/NNS1-3404.

[Next PR 👉][next]

[next]: #2320

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

@@ -98,6 +98,21 @@ pub struct NeuronInfo {
     /// See the Visibility enum.
     #[prost(enumeration = "Visibility", optional, tag = "12")]
     pub visibility: Option<i32>,
+    /// The last time that voting power was "refreshed". There are two ways to
+    /// refresh the voting power of a neuron: set following, or vote directly. In
+    /// the future, there will be a dedicated API for refreshing. Note that direct
+    /// voting implies that refresh also occurs when a proposal is created, because
+    /// direct voting is part of proposal creation.
+    ///
+    /// Effect: When this becomes > 6 months ago, the amount of voting power that
+    /// this neuron can exercise decreases linearly down to 0 over the course of 1
+    /// month. After that, following is cleared, except for ManageNeuron proposals.
+    ///
+    /// This will always be populated. If the underlying neuron was never
+    /// refreshed, this will be set to 2024-11-05T00:00:01 UTC (1730764801 seconds
+    /// after the UNIX epoch).
+    #[prost(uint64, optional, tag = "13")]
+    pub voting_power_refreshed_timestamp_seconds: ::core::option::Option<u64>,
 }
 /// A transfer performed from some account to stake a new neuron.
 #[derive(candid::CandidType, candid::Deserialize, serde::Serialize, comparable::Comparable)]
@@ -256,6 +271,21 @@ pub struct Neuron {
     /// See the Visibility enum.
     #[prost(enumeration = "Visibility", optional, tag = "23")]
     pub visibility: Option<i32>,
+    /// The last time that voting power was "refreshed". There are two ways to
+    /// refresh the voting power of a neuron: set following, or vote directly. In
+    /// the future, there will be a dedicated API for refreshing. Note that direct
+    /// voting implies that refresh also occurs when a proposal is created, because
+    /// direct voting is part of proposal creation.
+    ///
+    /// Effect: When this becomes > 6 months ago, the amount of voting power that
+    /// this neuron can exercise decreases linearly down to 0 over the course of 1
+    /// month. After that, following is cleared, except for ManageNeuron proposals.
+    ///
+    /// This will always be populated. If the underlying neuron was never
+    /// refreshed, this will be set to 2024-11-05T00:00:01 UTC (1730764801 seconds
+    /// after the UNIX epoch).
+    #[prost(uint64, optional, tag = "24")]
+    pub voting_power_refreshed_timestamp_seconds: ::core::option::Option<u64>,
     /// At any time, at most one of `when_dissolved` and
     /// `dissolve_delay` are specified.
     ///
@@ -364,6 +394,8 @@ pub struct AbridgedNeuron {
     pub neuron_type: Option<i32>,
     #[prost(enumeration = "Visibility", optional, tag = "23")]
     pub visibility: Option<i32>,
+    #[prost(uint64, optional, tag = "24")]
+    pub voting_power_refreshed_timestamp_seconds: ::core::option::Option<u64>,
     #[prost(oneof = "abridged_neuron::DissolveState", tags = "9, 10")]
     pub dissolve_state: Option<abridged_neuron::DissolveState>,
 }

rs/nns/governance/canister/governance.did

@@ -577,6 +577,7 @@ type Neuron = record {
   transfer : opt NeuronStakeTransfer;
   known_neuron_data : opt KnownNeuronData;
   spawn_at_timestamp_seconds : opt nat64;
+  voting_power_refreshed_timestamp_seconds : opt nat64;
 };
 
 type NeuronBasketConstructionParameters = record {
@@ -628,6 +629,7 @@ type NeuronInfo = record {
   known_neuron_data : opt KnownNeuronData;
   voting_power : nat64;
   age_seconds : nat64;
+  voting_power_refreshed_timestamp_seconds : opt nat64;
 };
 
 type NeuronStakeTransfer = record {

rs/nns/governance/canister/governance_test.did

@@ -579,6 +579,7 @@ type Neuron = record {
   transfer : opt NeuronStakeTransfer;
   known_neuron_data : opt KnownNeuronData;
   spawn_at_timestamp_seconds : opt nat64;
+  voting_power_refreshed_timestamp_seconds : opt nat64;
 };
 
 type NeuronBasketConstructionParameters = record {
@@ -630,6 +631,7 @@ type NeuronInfo = record {
   known_neuron_data : opt KnownNeuronData;
   voting_power : nat64;
   age_seconds : nat64;
+  voting_power_refreshed_timestamp_seconds : opt nat64;
 };
 
 type NeuronStakeTransfer = record {

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

@@ -246,6 +246,20 @@ message NeuronInfo {
   optional NeuronType neuron_type = 11;
   // See the Visibility enum.
   optional Visibility visibility = 12;
+  // The last time that voting power was "refreshed". There are two ways to
+  // refresh the voting power of a neuron: set following, or vote directly. In
+  // the future, there will be a dedicated API for refreshing. Note that direct
+  // voting implies that refresh also occurs when a proposal is created, because
+  // direct voting is part of proposal creation.
+  //
+  // Effect: When this becomes > 6 months ago, the amount of voting power that
+  // this neuron can exercise decreases linearly down to 0 over the course of 1
+  // month. After that, following is cleared, except for ManageNeuron proposals.
+  //
+  // This will always be populated. If the underlying neuron was never
+  // refreshed, this will be set to 2024-11-05T00:00:01 UTC (1730764801 seconds
+  // after the UNIX epoch).
+  optional uint64 voting_power_refreshed_timestamp_seconds = 13;
 }
 
 // A transfer performed from some account to stake a new neuron.
@@ -429,6 +443,21 @@ message Neuron {
 
   // See the Visibility enum.
   optional Visibility visibility = 23;
+
+  // The last time that voting power was "refreshed". There are two ways to
+  // refresh the voting power of a neuron: set following, or vote directly. In
+  // the future, there will be a dedicated API for refreshing. Note that direct
+  // voting implies that refresh also occurs when a proposal is created, because
+  // direct voting is part of proposal creation.
+  //
+  // Effect: When this becomes > 6 months ago, the amount of voting power that
+  // this neuron can exercise decreases linearly down to 0 over the course of 1
+  // month. After that, following is cleared, except for ManageNeuron proposals.
+  //
+  // This will always be populated. If the underlying neuron was never
+  // refreshed, this will be set to 2024-11-05T00:00:01 UTC (1730764801 seconds
+  // after the UNIX epoch).
+  optional uint64 voting_power_refreshed_timestamp_seconds = 24;
 }
 
 // Subset of Neuron that has no collections or big fields that might not exist in most neurons, and
@@ -454,6 +483,7 @@ message AbridgedNeuron {
   optional uint64 joined_community_fund_timestamp_seconds = 17;
   optional NeuronType neuron_type = 22;
   optional Visibility visibility = 23;
+  optional uint64 voting_power_refreshed_timestamp_seconds = 24;
 
   reserved 1;
   reserved "id";

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

@@ -113,6 +113,21 @@ pub struct NeuronInfo {
     /// See the Visibility enum.
     #[prost(enumeration = "Visibility", optional, tag = "12")]
     pub visibility: ::core::option::Option<i32>,
+    /// The last time that voting power was "refreshed". There are two ways to
+    /// refresh the voting power of a neuron: set following, or vote directly. In
+    /// the future, there will be a dedicated API for refreshing. Note that direct
+    /// voting implies that refresh also occurs when a proposal is created, because
+    /// direct voting is part of proposal creation.
+    ///
+    /// Effect: When this becomes > 6 months ago, the amount of voting power that
+    /// this neuron can exercise decreases linearly down to 0 over the course of 1
+    /// month. After that, following is cleared, except for ManageNeuron proposals.
+    ///
+    /// This will always be populated. If the underlying neuron was never
+    /// refreshed, this will be set to 2024-11-05T00:00:01 UTC (1730764801 seconds
+    /// after the UNIX epoch).
+    #[prost(uint64, optional, tag = "13")]
+    pub voting_power_refreshed_timestamp_seconds: ::core::option::Option<u64>,
 }
 /// A transfer performed from some account to stake a new neuron.
 #[derive(
@@ -276,6 +291,21 @@ pub struct Neuron {
     /// See the Visibility enum.
     #[prost(enumeration = "Visibility", optional, tag = "23")]
     pub visibility: ::core::option::Option<i32>,
+    /// The last time that voting power was "refreshed". There are two ways to
+    /// refresh the voting power of a neuron: set following, or vote directly. In
+    /// the future, there will be a dedicated API for refreshing. Note that direct
+    /// voting implies that refresh also occurs when a proposal is created, because
+    /// direct voting is part of proposal creation.
+    ///
+    /// Effect: When this becomes > 6 months ago, the amount of voting power that
+    /// this neuron can exercise decreases linearly down to 0 over the course of 1
+    /// month. After that, following is cleared, except for ManageNeuron proposals.
+    ///
+    /// This will always be populated. If the underlying neuron was never
+    /// refreshed, this will be set to 2024-11-05T00:00:01 UTC (1730764801 seconds
+    /// after the UNIX epoch).
+    #[prost(uint64, optional, tag = "24")]
+    pub voting_power_refreshed_timestamp_seconds: ::core::option::Option<u64>,
     /// At any time, at most one of `when_dissolved` and
     /// `dissolve_delay` are specified.
     ///
@@ -401,6 +431,8 @@ pub struct AbridgedNeuron {
     pub neuron_type: ::core::option::Option<i32>,
     #[prost(enumeration = "Visibility", optional, tag = "23")]
     pub visibility: ::core::option::Option<i32>,
+    #[prost(uint64, optional, tag = "24")]
+    pub voting_power_refreshed_timestamp_seconds: ::core::option::Option<u64>,
     #[prost(oneof = "abridged_neuron::DissolveState", tags = "9, 10")]
     pub dissolve_state: ::core::option::Option<abridged_neuron::DissolveState>,
 }