feat(governance): expose get_maturity_modulation query endpoint (#9879)

## Why

PR #9847 computes Mission 70 maturity modulation locally and stores it
in canister state, but the computed value is not yet consumed by
spawning
or disbursement (those still rely on CMC). This PR exposes the locally
computed value through a new `get_maturity_modulation` query endpoint so
it can be observed and validated against the existing CMC-based
modulation before the switchover happens in a follow-up PR.

External tools and dashboards can also use this endpoint to read the
current maturity modulation value.

https://dfinity.atlassian.net/browse/NNS1-4319

## What

- Add MaturityModulation, GetMaturityModulationRequest, and
  GetMaturityModulationResponse types to the ic-nns-governance-api crate
- Add Governance::get_maturity_modulation() method
- Add #[query] fn get_maturity_modulation endpoint to the governance
  canister
- Add corresponding types and service entry to governance.did
- Add pb::api From conversion for MaturityModulation

### PR Chain
- ⬅️ Previous: #9847

Author: jasonz-dfinity

rs/nns/governance/api/src/types.rs

@@ -4741,3 +4741,23 @@ pub struct CreatedNeuron {
 }
 
 pub type CreateNeuronResponse = Result<CreatedNeuron, GovernanceError>;
+
+#[derive(
+    candid::CandidType, candid::Deserialize, serde::Serialize, Debug, Clone, PartialEq, Default,
+)]
+pub struct MaturityModulation {
+    pub current_value_permyriad: Option<i32>,
+    pub updated_at_timestamp_seconds: Option<u64>,
+}
+
+#[derive(
+    candid::CandidType, candid::Deserialize, serde::Serialize, Debug, Clone, PartialEq, Default,
+)]
+pub struct GetMaturityModulationRequest {}
+
+#[derive(
+    candid::CandidType, candid::Deserialize, serde::Serialize, Debug, Clone, PartialEq, Default,
+)]
+pub struct GetMaturityModulationResponse {
+    pub maturity_modulation: Option<MaturityModulation>,
+}

rs/nns/governance/canister/canister.rs

@@ -29,14 +29,15 @@ use ic_nns_governance::{
 use ic_nns_governance_api::test_api::TimeWarp;
 use ic_nns_governance_api::{
     ClaimOrRefreshNeuronFromAccount, ClaimOrRefreshNeuronFromAccountResponse, CreateNeuronRequest,
-    CreateNeuronResponse, GetNeuronIndexRequest, GetNeuronsFundAuditInfoRequest,
-    GetNeuronsFundAuditInfoResponse, GetPendingProposalsRequest, Governance as ApiGovernanceProto,
-    GovernanceError, ListKnownNeuronsResponse, ListNeuronVotesRequest, ListNeuronVotesResponse,
-    ListNeurons, ListNeuronsResponse, ListNodeProviderRewardsRequest,
-    ListNodeProviderRewardsResponse, ListNodeProvidersResponse, ListProposalInfoRequest,
-    ListProposalInfoResponse, ManageNeuronCommandRequest, ManageNeuronRequest,
-    ManageNeuronResponse, MonthlyNodeProviderRewards, NetworkEconomics, Neuron, NeuronIndexData,
-    NeuronInfo, NodeProvider, Proposal, ProposalInfo, RestoreAgingSummary, RewardEvent,
+    CreateNeuronResponse, GetMaturityModulationRequest, GetMaturityModulationResponse,
+    GetNeuronIndexRequest, GetNeuronsFundAuditInfoRequest, GetNeuronsFundAuditInfoResponse,
+    GetPendingProposalsRequest, Governance as ApiGovernanceProto, GovernanceError,
+    ListKnownNeuronsResponse, ListNeuronVotesRequest, ListNeuronVotesResponse, ListNeurons,
+    ListNeuronsResponse, ListNodeProviderRewardsRequest, ListNodeProviderRewardsResponse,
+    ListNodeProvidersResponse, ListProposalInfoRequest, ListProposalInfoResponse,
+    ManageNeuronCommandRequest, ManageNeuronRequest, ManageNeuronResponse,
+    MonthlyNodeProviderRewards, NetworkEconomics, Neuron, NeuronIndexData, NeuronInfo,
+    NodeProvider, Proposal, ProposalInfo, RestoreAgingSummary, RewardEvent,
     SettleCommunityFundParticipation, SettleNeuronsFundParticipationRequest,
     SettleNeuronsFundParticipationResponse, UpdateNodeProvider, Vote,
     claim_or_refresh_neuron_from_account_response::Result as ClaimOrRefreshNeuronFromAccountResponseResult,
@@ -577,6 +578,15 @@ fn get_restore_aging_summary() -> RestoreAgingSummary {
     RestoreAgingSummary::from(response)
 }
 
+/// Returns the current maturity modulation, as defined by Mission 70.
+#[query]
+fn get_maturity_modulation(
+    _request: GetMaturityModulationRequest,
+) -> GetMaturityModulationResponse {
+    debug_log("get_maturity_modulation");
+    with_governance(|governance| governance.get_maturity_modulation())
+}
+
 #[query]
 fn list_neuron_votes(request: ListNeuronVotesRequest) -> ListNeuronVotesResponse {
     with_governance(|governance| {

rs/nns/governance/canister/governance.did

@@ -334,6 +334,17 @@ type GetNeuronsFundAuditInfoRequest = record {
   nns_proposal_id : opt ProposalId;
 };
 
+type MaturityModulation = record {
+  current_value_permyriad : opt int32;
+  updated_at_timestamp_seconds : opt nat64;
+};
+
+type GetMaturityModulationRequest = record {};
+
+type GetMaturityModulationResponse = record {
+  maturity_modulation : opt MaturityModulation;
+};
+
 type GetNeuronsFundAuditInfoResponse = record {
   result : opt Result_6;
 };
@@ -1599,6 +1610,9 @@ service : (Governance) -> {
       Result_2,
     ) query;
   get_latest_reward_event : () -> (RewardEvent) query;
+  get_maturity_modulation : (GetMaturityModulationRequest) -> (
+      GetMaturityModulationResponse,
+    ) query;
   get_metrics : () -> (Result_3) query;
   get_monthly_node_provider_rewards : () -> (Result_4);
   get_most_recent_monthly_node_provider_rewards : () -> (

rs/nns/governance/src/governance.rs

@@ -108,8 +108,9 @@ use ic_nns_constants::{
 };
 use ic_nns_governance_api::{
     self as api, CreateServiceNervousSystem as ApiCreateServiceNervousSystem,
-    GetNeuronIndexRequest, GetPendingProposalsRequest, ListNeuronVotesRequest, ListNeurons,
-    ListNeuronsResponse, ListProposalInfoRequest, ListProposalInfoResponse, ManageNeuronResponse,
+    GetMaturityModulationResponse, GetNeuronIndexRequest, GetPendingProposalsRequest,
+    ListNeuronVotesRequest, ListNeurons, ListNeuronsResponse, ListProposalInfoRequest,
+    ListProposalInfoResponse, ManageNeuronResponse, MaturityModulation as ApiMaturityModulation,
     NeuronIndexData, NeuronInfo, NeuronVote, NeuronVotes, ProposalInfo,
     manage_neuron_response::{self, StakeMaturityResponse},
     proposal_validation::{
@@ -8030,6 +8031,16 @@ impl Governance {
     pub fn get_restore_aging_summary(&self) -> Option<RestoreAgingSummary> {
         self.heap_data.restore_aging_summary.clone()
     }
+
+    /// Returns the current maturity modulation, as defined by Mission 70.
+    pub fn get_maturity_modulation(&self) -> GetMaturityModulationResponse {
+        GetMaturityModulationResponse {
+            maturity_modulation: self
+                .heap_data
+                .maturity_modulation
+                .map(ApiMaturityModulation::from),
+        }
+    }
 }
 
 impl From<NeuronSubsetMetrics> for NeuronSubsetMetricsPb {

rs/nns/governance/src/governance/tests/get_maturity_modulation.rs

@@ -0,0 +1,77 @@
+use crate::governance::{
+    Governance,
+    tests::{MockEnvironment, StubCMC, StubIcpLedger},
+};
+use crate::pb::v1::MaturityModulation;
+use crate::test_utils::MockRandomness;
+use ic_nervous_system_common::ONE_DAY_SECONDS;
+use ic_nns_governance_api::{
+    GetMaturityModulationResponse, MaturityModulation as ApiMaturityModulation,
+};
+use std::sync::Arc;
+
+fn make_governance() -> Governance {
+    Governance::new(
+        Default::default(),
+        Arc::new(MockEnvironment::new(vec![], 0)),
+        Arc::new(StubIcpLedger {}),
+        Arc::new(StubCMC {}),
+        Box::new(MockRandomness::new()),
+    )
+}
+
+#[test]
+fn returns_none_when_unset() {
+    let governance = make_governance();
+
+    let response = governance.get_maturity_modulation();
+
+    assert_eq!(
+        response,
+        GetMaturityModulationResponse {
+            maturity_modulation: None
+        }
+    );
+}
+
+#[test]
+fn converts_days_since_epoch_to_seconds() {
+    let mut governance = make_governance();
+    governance.heap_data.maturity_modulation = Some(MaturityModulation {
+        current_value_permyriad: Some(123),
+        updated_at_days_since_epoch: Some(20_000),
+    });
+
+    let response = governance.get_maturity_modulation();
+
+    assert_eq!(
+        response,
+        GetMaturityModulationResponse {
+            maturity_modulation: Some(ApiMaturityModulation {
+                current_value_permyriad: Some(123),
+                updated_at_timestamp_seconds: Some(20_000 * ONE_DAY_SECONDS),
+            }),
+        }
+    );
+}
+
+#[test]
+fn updated_at_returns_none_when_days_overflow() {
+    let mut governance = make_governance();
+    governance.heap_data.maturity_modulation = Some(MaturityModulation {
+        current_value_permyriad: Some(123),
+        updated_at_days_since_epoch: Some(u64::MAX),
+    });
+
+    let response = governance.get_maturity_modulation();
+
+    assert_eq!(
+        response,
+        GetMaturityModulationResponse {
+            maturity_modulation: Some(ApiMaturityModulation {
+                current_value_permyriad: Some(123),
+                updated_at_timestamp_seconds: None,
+            }),
+        }
+    );
+}

rs/nns/governance/src/governance/tests/mod.rs

@@ -24,6 +24,7 @@ use lazy_static::lazy_static;
 use maplit::hashmap;
 use std::{convert::TryFrom, time::Duration};
 
+mod get_maturity_modulation;
 mod get_neuron_index;
 mod list_neurons;
 mod list_proposals;

rs/nns/governance/src/pb/conversions/mod.rs

@@ -4,6 +4,7 @@ use crate::pb::{
 };
 
 use ic_crypto_sha2::Sha256;
+use ic_nervous_system_common::ONE_DAY_SECONDS;
 use ic_nns_governance_api as api;
 use ic_nns_governance_conversions::{
     convert_guest_launch_measurements_from_api_to_pb,
@@ -4076,3 +4077,14 @@ impl From<api::TakeCanisterSnapshot> for pb::TakeCanisterSnapshot {
         }
     }
 }
+
+impl From<pb::MaturityModulation> for api::MaturityModulation {
+    fn from(item: pb::MaturityModulation) -> Self {
+        Self {
+            current_value_permyriad: item.current_value_permyriad,
+            updated_at_timestamp_seconds: item
+                .updated_at_days_since_epoch
+                .and_then(|days| days.checked_mul(ONE_DAY_SECONDS)),
+        }
+    }
+}

rs/nns/governance/unreleased_changelog.md

@@ -11,6 +11,8 @@ on the process that this file is part of, see
 
 * Daily timer task that fetches ICP/XDR rates from the Exchange Rate Canister, maintains a 365-day price history in Governance state, and computes Mission 70 maturity modulation locally. The computed value is not yet consumed by spawning or disbursement; that switchover will happen in a follow-up PR.
 
+* `get_maturity_modulation` query endpoint that returns the current Mission 70 maturity modulation value, including `current_value_permyriad` and `updated_at_timestamp_seconds`.
+
 * Expose `staked_maturity_e8s_equivalent` on `NeuronInfo`, so external callers
   can read staked maturity from `get_neuron_info` / `list_neurons` responses.
 

rs/nns/nns.bzl

@@ -22,7 +22,7 @@ CANISTER_NAME_TO_MAX_COMPRESSED_WASM_SIZE_E5_BYTES = {
     "cycles-minting-canister.wasm.gz": 6,
     "genesis-token-canister.wasm.gz": 3,
     "governance-canister.wasm.gz": 22,
-    "governance-canister_test.wasm.gz": 23,
+    "governance-canister_test.wasm.gz": 24,
     "registry-canister.wasm.gz": 16,
     "root-canister.wasm.gz": 5,
 }