ic_query/nns/governance/
model.rs

1//! Module: nns::governance::model
2//!
3//! Responsibility: define direct NNS Governance report models.
4//! Does not own: live transport, CLI parsing, caching, or text rendering.
5//! Boundary: preserves native Governance values and explicit query provenance.
6
7#[cfg(feature = "host")]
8use candid::CandidType;
9use serde::{Deserialize as SerdeDeserialize, Serialize};
10
11///
12/// NnsGovernanceReportContext
13///
14/// Shared provenance flattened into every direct NNS Governance report.
15///
16
17#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
18pub struct NnsGovernanceReportContext {
19    /// Report schema version.
20    pub schema_version: u32,
21    /// Queried network identity.
22    pub network: String,
23    /// NNS Governance canister principal.
24    pub governance_canister_id: String,
25    /// UTC collection timestamp.
26    pub fetched_at: String,
27    /// Replica endpoint used for the query.
28    pub source_endpoint: String,
29    /// Collector identity.
30    pub fetched_by: String,
31}
32
33///
34/// NnsGovernanceMetricBucket
35///
36/// One native Governance metric bucket represented as a named key/value row.
37///
38
39#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
40pub struct NnsGovernanceMetricBucket<Value> {
41    /// Raw unlabeled Candid bucket key.
42    pub key: u64,
43    /// Raw unlabeled Candid bucket value.
44    pub value: Value,
45}
46
47///
48/// NnsGovernanceEconomicsReport
49///
50/// Serializable live snapshot of the NNS Governance economics parameters.
51///
52
53#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
54pub struct NnsGovernanceEconomicsReport {
55    /// Shared Governance query provenance.
56    #[serde(flatten)]
57    pub context: NnsGovernanceReportContext,
58    /// Native Governance economics parameters.
59    pub economics: NnsGovernanceEconomics,
60}
61
62///
63/// NnsGovernanceEconomics
64///
65/// Native NNS Governance network economics parameters.
66///
67
68#[cfg_attr(feature = "host", derive(CandidType))]
69#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
70pub struct NnsGovernanceEconomics {
71    /// Minimum neuron stake in e8s.
72    pub neuron_minimum_stake_e8s: u64,
73    /// Maximum retained proposals per Governance topic.
74    pub max_proposals_to_keep_per_topic: u32,
75    /// Neuron-management proposal fee in e8s.
76    pub neuron_management_fee_per_proposal_e8s: u64,
77    /// Proposal rejection cost in e8s.
78    pub reject_cost_e8s: u64,
79    /// Ledger transaction fee in e8s.
80    pub transaction_fee_e8s: u64,
81    /// Spawned-neuron dissolve delay in seconds.
82    pub neuron_spawn_dissolve_delay_seconds: u64,
83    /// Raw minimum ICP/XDR rate.
84    pub minimum_icp_xdr_rate: u64,
85    /// Maximum node-provider rewards in e8s.
86    pub maximum_node_provider_rewards_e8s: u64,
87    /// Optional Neurons' Fund economics.
88    pub neurons_fund_economics: Option<NnsNeuronsFundEconomics>,
89    /// Optional voting-power economics.
90    pub voting_power_economics: Option<NnsVotingPowerEconomics>,
91}
92
93///
94/// NnsNeuronsFundEconomics
95///
96/// Native optional parameters governing Neurons' Fund participation.
97///
98
99#[cfg_attr(feature = "host", derive(CandidType))]
100#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
101pub struct NnsNeuronsFundEconomics {
102    /// Maximum ICP/XDR rate.
103    pub maximum_icp_xdr_rate: Option<NnsGovernancePercentage>,
104    /// Matched-funding curve coefficients.
105    pub neurons_fund_matched_funding_curve_coefficients:
106        Option<NnsNeuronsFundMatchedFundingCurveCoefficients>,
107    /// Maximum theoretical Neurons' Fund participation amount in XDR.
108    pub max_theoretical_neurons_fund_participation_amount_xdr: Option<NnsGovernanceDecimal>,
109    /// Minimum ICP/XDR rate.
110    pub minimum_icp_xdr_rate: Option<NnsGovernancePercentage>,
111}
112
113///
114/// NnsNeuronsFundMatchedFundingCurveCoefficients
115///
116/// Native decimal-string parameters for the Neurons' Fund matching curve.
117///
118
119#[cfg_attr(feature = "host", derive(CandidType))]
120#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
121pub struct NnsNeuronsFundMatchedFundingCurveCoefficients {
122    /// Contribution threshold in XDR.
123    pub contribution_threshold_xdr: Option<NnsGovernanceDecimal>,
124    /// One-third participation milestone in XDR.
125    pub one_third_participation_milestone_xdr: Option<NnsGovernanceDecimal>,
126    /// Full participation milestone in XDR.
127    pub full_participation_milestone_xdr: Option<NnsGovernanceDecimal>,
128}
129
130///
131/// NnsGovernancePercentage
132///
133/// Native optional-basis-points percentage wrapper used by Governance.
134///
135
136#[cfg_attr(feature = "host", derive(CandidType))]
137#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
138pub struct NnsGovernancePercentage {
139    /// Percentage value in basis points when supplied.
140    pub basis_points: Option<u64>,
141}
142
143///
144/// NnsGovernanceDecimal
145///
146/// Native human-readable decimal wrapper used by Governance.
147///
148
149#[cfg_attr(feature = "host", derive(CandidType))]
150#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
151pub struct NnsGovernanceDecimal {
152    /// Decimal representation when supplied.
153    pub human_readable: Option<String>,
154}
155
156///
157/// NnsVotingPowerEconomics
158///
159/// Native optional parameters governing NNS neuron voting power.
160///
161
162#[cfg_attr(feature = "host", derive(CandidType))]
163#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
164pub struct NnsVotingPowerEconomics {
165    /// Inactivity duration before voting power starts decreasing.
166    pub start_reducing_voting_power_after_seconds: Option<u64>,
167    /// Reduction duration after which following is cleared.
168    pub clear_following_after_seconds: Option<u64>,
169    /// Minimum dissolve delay required to vote.
170    pub neuron_minimum_dissolve_delay_to_vote_seconds: Option<u64>,
171}
172
173///
174/// NnsGovernanceMetricsReport
175///
176/// Serializable live snapshot of cached NNS Governance metrics.
177///
178
179#[derive(Clone, Debug, PartialEq, SerdeDeserialize, Serialize)]
180pub struct NnsGovernanceMetricsReport {
181    /// Shared Governance query provenance.
182    #[serde(flatten)]
183    pub context: NnsGovernanceReportContext,
184    /// Native Governance metrics.
185    pub metrics: NnsGovernanceMetrics,
186}
187
188///
189/// NnsGovernanceMetrics
190///
191/// Native cached metrics returned by the NNS Governance canister.
192///
193
194#[derive(Clone, Debug, PartialEq, SerdeDeserialize, Serialize)]
195pub struct NnsGovernanceMetrics {
196    /// Total maturity in e8s-equivalent.
197    pub total_maturity_e8s_equivalent: u64,
198    /// Non-dissolving neuron stake buckets.
199    pub not_dissolving_neurons_e8s_buckets: Vec<NnsGovernanceMetricBucket<f64>>,
200    /// Staked maturity of dissolving neurons in e8s-equivalent.
201    pub dissolving_neurons_staked_maturity_e8s_equivalent_sum: u64,
202    /// Number of garbage-collectable neurons.
203    pub garbage_collectable_neurons_count: u64,
204    /// Staked-maturity buckets for dissolving neurons.
205    pub dissolving_neurons_staked_maturity_e8s_equivalent_buckets:
206        Vec<NnsGovernanceMetricBucket<f64>>,
207    /// Number of neurons with invalid stake.
208    pub neurons_with_invalid_stake_count: u64,
209    /// Count buckets for non-dissolving neurons.
210    pub not_dissolving_neurons_count_buckets: Vec<NnsGovernanceMetricBucket<u64>>,
211    /// Number of early-contributor-token neurons.
212    pub ect_neuron_count: u64,
213    /// Total ICP supply reported by Governance.
214    pub total_supply_icp: u64,
215    /// Number of neurons with less than six months dissolve delay.
216    pub neurons_with_less_than_6_months_dissolve_delay_count: u64,
217    /// Number of dissolved neurons.
218    pub dissolved_neurons_count: u64,
219    /// Community Fund maturity in e8s-equivalent.
220    pub community_fund_total_maturity_e8s_equivalent: u64,
221    /// Total seed-neuron stake in e8s.
222    pub total_staked_e8s_seed: u64,
223    /// Total staked maturity of early-contributor-token neurons.
224    pub total_staked_maturity_e8s_equivalent_ect: u64,
225    /// Total neuron stake in e8s.
226    pub total_staked_e8s: u64,
227    /// Number of non-dissolving neurons.
228    pub not_dissolving_neurons_count: u64,
229    /// Total locked stake in e8s.
230    pub total_locked_e8s: u64,
231    /// Number of active Neurons' Fund neurons.
232    pub neurons_fund_total_active_neurons: u64,
233    /// Voting power controlled by non-self-authenticating principals.
234    pub total_voting_power_non_self_authenticating_controller: Option<u64>,
235    /// Total staked maturity in e8s-equivalent.
236    pub total_staked_maturity_e8s_equivalent: u64,
237    /// Non-dissolving early-contributor-token neuron stake buckets.
238    pub not_dissolving_neurons_e8s_buckets_ect: Vec<NnsGovernanceMetricBucket<f64>>,
239    /// Total stake of early-contributor-token neurons in e8s.
240    pub total_staked_e8s_ect: u64,
241    /// Staked maturity of non-dissolving neurons in e8s-equivalent.
242    pub not_dissolving_neurons_staked_maturity_e8s_equivalent_sum: u64,
243    /// Total dissolved-neuron stake in e8s.
244    pub dissolved_neurons_e8s: u64,
245    /// Stake controlled by non-self-authenticating principals.
246    pub total_staked_e8s_non_self_authenticating_controller: Option<u64>,
247    /// Dissolving seed-neuron stake buckets.
248    pub dissolving_neurons_e8s_buckets_seed: Vec<NnsGovernanceMetricBucket<f64>>,
249    /// Stake of neurons with less than six months dissolve delay.
250    pub neurons_with_less_than_6_months_dissolve_delay_e8s: u64,
251    /// Staked-maturity buckets for non-dissolving neurons.
252    pub not_dissolving_neurons_staked_maturity_e8s_equivalent_buckets:
253        Vec<NnsGovernanceMetricBucket<f64>>,
254    /// Count buckets for dissolving neurons.
255    pub dissolving_neurons_count_buckets: Vec<NnsGovernanceMetricBucket<u64>>,
256    /// Dissolving early-contributor-token neuron stake buckets.
257    pub dissolving_neurons_e8s_buckets_ect: Vec<NnsGovernanceMetricBucket<f64>>,
258    /// Number of dissolving neurons.
259    pub dissolving_neurons_count: u64,
260    /// Dissolving neuron stake buckets.
261    pub dissolving_neurons_e8s_buckets: Vec<NnsGovernanceMetricBucket<f64>>,
262    /// Total staked maturity of seed neurons.
263    pub total_staked_maturity_e8s_equivalent_seed: u64,
264    /// Total Community Fund stake in e8s.
265    pub community_fund_total_staked_e8s: u64,
266    /// Non-dissolving seed-neuron stake buckets.
267    pub not_dissolving_neurons_e8s_buckets_seed: Vec<NnsGovernanceMetricBucket<f64>>,
268    /// Governance metric collection timestamp in Unix seconds.
269    pub timestamp_seconds: u64,
270    /// Number of seed neurons.
271    pub seed_neuron_count: u64,
272    /// Number of spawning neurons.
273    pub spawning_neurons_count: u64,
274    /// Maturity disbursements currently in progress.
275    pub total_maturity_disbursements_in_progress_e8s_equivalent: u64,
276    /// Metrics for neurons controlled by non-self-authenticating principals.
277    pub non_self_authenticating_controller_neuron_subset_metrics:
278        Option<NnsGovernanceNeuronSubsetMetrics>,
279    /// Metrics for publicly visible neurons.
280    pub public_neuron_subset_metrics: Option<NnsGovernanceNeuronSubsetMetrics>,
281    /// Metrics for neurons with declining voting power.
282    pub declining_voting_power_neuron_subset_metrics: Option<NnsGovernanceNeuronSubsetMetrics>,
283    /// Metrics for neurons that have fully lost voting power.
284    pub fully_lost_voting_power_neuron_subset_metrics: Option<NnsGovernanceNeuronSubsetMetrics>,
285}
286
287///
288/// NnsGovernanceNeuronSubsetMetrics
289///
290/// Native cached Governance metrics for one neuron subset.
291///
292
293#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
294pub struct NnsGovernanceNeuronSubsetMetrics {
295    /// Number of neurons in the subset.
296    pub count: Option<u64>,
297    /// Total subset stake in e8s.
298    pub total_staked_e8s: Option<u64>,
299    /// Total subset maturity in e8s-equivalent.
300    pub total_maturity_e8s_equivalent: Option<u64>,
301    /// Total subset staked maturity in e8s-equivalent.
302    pub total_staked_maturity_e8s_equivalent: Option<u64>,
303    /// Deprecated raw total voting power.
304    pub total_voting_power: Option<u64>,
305    /// Total deciding voting power.
306    pub total_deciding_voting_power: Option<u64>,
307    /// Total potential voting power.
308    pub total_potential_voting_power: Option<u64>,
309    /// Neuron-count buckets.
310    pub count_buckets: Vec<NnsGovernanceMetricBucket<u64>>,
311    /// Stake buckets in e8s.
312    pub staked_e8s_buckets: Vec<NnsGovernanceMetricBucket<u64>>,
313    /// Maturity buckets in e8s-equivalent.
314    pub maturity_e8s_equivalent_buckets: Vec<NnsGovernanceMetricBucket<u64>>,
315    /// Staked-maturity buckets in e8s-equivalent.
316    pub staked_maturity_e8s_equivalent_buckets: Vec<NnsGovernanceMetricBucket<u64>>,
317    /// Deprecated voting-power buckets.
318    pub voting_power_buckets: Vec<NnsGovernanceMetricBucket<u64>>,
319    /// Deciding-voting-power buckets.
320    pub deciding_voting_power_buckets: Vec<NnsGovernanceMetricBucket<u64>>,
321    /// Potential-voting-power buckets.
322    pub potential_voting_power_buckets: Vec<NnsGovernanceMetricBucket<u64>>,
323}
324
325///
326/// NnsGovernanceRewardEventReport
327///
328/// Serializable live snapshot of the latest NNS voting reward event.
329///
330
331#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
332pub struct NnsGovernanceRewardEventReport {
333    /// Shared Governance query provenance.
334    #[serde(flatten)]
335    pub context: NnsGovernanceReportContext,
336    /// Latest native Governance reward event.
337    pub reward_event: NnsGovernanceRewardEvent,
338}
339
340///
341/// NnsGovernanceRewardEvent
342///
343/// Latest native NNS Governance voting reward event.
344///
345
346#[cfg_attr(feature = "host", derive(CandidType))]
347#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
348pub struct NnsGovernanceRewardEvent {
349    /// Rounds elapsed since the previous distribution when supplied.
350    pub rounds_since_last_distribution: Option<u64>,
351    /// Reward day after NNS genesis.
352    pub day_after_genesis: u64,
353    /// Actual reward-event timestamp in Unix seconds.
354    pub actual_timestamp_seconds: u64,
355    /// Total rewards available in e8s-equivalent.
356    pub total_available_e8s_equivalent: u64,
357    /// Rewards available in the latest round when supplied.
358    pub latest_round_available_e8s_equivalent: Option<u64>,
359    /// Rewards distributed in e8s-equivalent.
360    pub distributed_e8s_equivalent: u64,
361    /// Proposals settled by the event, in Governance order.
362    pub settled_proposals: Vec<NnsGovernanceProposalId>,
363}
364
365///
366/// NnsGovernanceProposalId
367///
368/// Native NNS Governance proposal identifier wrapper.
369///
370
371#[cfg_attr(feature = "host", derive(CandidType))]
372#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
373pub struct NnsGovernanceProposalId {
374    /// Governance proposal identifier.
375    pub id: u64,
376}
377
378///
379/// NnsGovernanceMaturityModulationReport
380///
381/// Serializable live snapshot of NNS maturity modulation.
382///
383
384#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
385pub struct NnsGovernanceMaturityModulationReport {
386    /// Shared Governance query provenance.
387    #[serde(flatten)]
388    pub context: NnsGovernanceReportContext,
389    /// Current modulation when Governance supplies it.
390    pub maturity_modulation: Option<NnsGovernanceMaturityModulation>,
391}
392
393///
394/// NnsGovernanceMaturityModulation
395///
396/// Current native NNS Governance maturity-modulation value.
397///
398
399#[cfg_attr(feature = "host", derive(CandidType))]
400#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
401pub struct NnsGovernanceMaturityModulation {
402    /// Current signed modulation in permyriad when supplied.
403    pub current_value_permyriad: Option<i32>,
404    /// Last update timestamp in Unix seconds when supplied.
405    pub updated_at_timestamp_seconds: Option<u64>,
406}
ic_query/nns/governance/model.rs

ic_query/nns/governance/
model.rs
