ic_query/nns/neuron/report/model.rs
1//! Module: nns::neuron::report::model
2//!
3//! Responsibility: define public NNS neuron request and report models.
4//! Does not own: live transport, cache IO, or text rendering.
5//! Boundary: preserves the unauthenticated Governance `NeuronInfo` fields without private state.
6
7use crate::nns::governance::{NnsGovernanceReportContext, NnsGovernanceRequest};
8use serde::{Deserialize as SerdeDeserialize, Serialize};
9
10///
11/// NnsKnownNeuronData
12///
13/// Public metadata attached to a registered known neuron.
14///
15
16#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
17pub struct NnsKnownNeuronData {
18 /// Registered neuron name.
19 pub name: String,
20 /// Optional registered description.
21 pub description: Option<String>,
22 /// Registered related links.
23 pub links: Vec<String>,
24}
25
26///
27/// NnsNeuronBallotRow
28///
29/// One recent public ballot exposed by the Governance neuron index.
30///
31
32#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
33#[serde(deny_unknown_fields)]
34pub struct NnsNeuronBallotRow {
35 /// Proposal identifier when supplied by Governance.
36 pub proposal_id: Option<u64>,
37 /// Raw Governance vote discriminant.
38 pub vote: i32,
39}
40
41///
42/// NnsNeuronRow
43///
44/// Public limited view of one NNS neuron returned by Governance.
45///
46
47#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
48#[serde(deny_unknown_fields)]
49pub struct NnsNeuronRow {
50 /// Stable Governance neuron identifier.
51 pub neuron_id: u64,
52 /// Raw Governance state discriminant.
53 pub state: i32,
54 /// Raw optional neuron visibility discriminant.
55 pub visibility: Option<i32>,
56 /// Raw optional neuron-type discriminant.
57 pub neuron_type: Option<i32>,
58 /// Public effective stake, including staked maturity, in e8s.
59 pub stake_e8s: u64,
60 /// Staked maturity included in effective stake, in e8s when supplied.
61 pub staked_maturity_e8s_equivalent: Option<u64>,
62 /// Current dissolve delay in seconds.
63 pub dissolve_delay_seconds: u64,
64 /// Current neuron age in seconds.
65 pub age_seconds: u64,
66 /// Neuron creation timestamp in Unix seconds.
67 pub created_timestamp_seconds: u64,
68 /// Governance retrieval timestamp in Unix seconds.
69 pub retrieved_at_timestamp_seconds: u64,
70 /// Deprecated Governance voting-power field retained losslessly.
71 pub voting_power: u64,
72 /// Current deciding voting power when supplied.
73 pub deciding_voting_power: Option<u64>,
74 /// Current potential voting power when supplied.
75 pub potential_voting_power: Option<u64>,
76 /// Last voting-power refresh timestamp in Unix seconds.
77 pub voting_power_refreshed_timestamp_seconds: Option<u64>,
78 /// Neurons' Fund join timestamp in Unix seconds when publicly visible.
79 pub joined_community_fund_timestamp_seconds: Option<u64>,
80 /// Eight-year dissolve-delay bonus base in e8s when supplied.
81 pub eight_year_gang_bonus_base_e8s: Option<u64>,
82 /// Registered public known-neuron metadata when present.
83 pub known_neuron_data: Option<NnsKnownNeuronData>,
84 /// Recent ballots visible to the unauthenticated caller.
85 pub recent_ballots: Vec<NnsNeuronBallotRow>,
86}
87
88///
89/// NnsNeuronListRequest
90///
91/// Request for one page of the public NNS Governance neuron index.
92///
93
94#[derive(Clone, Debug, Eq, PartialEq)]
95pub struct NnsNeuronListRequest {
96 /// Shared network, collection time, and source transport request.
97 pub governance: NnsGovernanceRequest,
98 /// Maximum rows to return.
99 pub limit: u32,
100 /// Exclusive lower neuron-id bound.
101 pub exclusive_start_neuron_id: Option<u64>,
102}
103
104impl NnsNeuronListRequest {
105 /// Construct a first-page public neuron-index request.
106 #[must_use]
107 pub const fn new(governance: NnsGovernanceRequest, limit: u32) -> Self {
108 Self {
109 governance,
110 limit,
111 exclusive_start_neuron_id: None,
112 }
113 }
114}
115
116///
117/// NnsNeuronInfoRequest
118///
119/// Request for one public NNS Governance neuron view.
120///
121
122#[derive(Clone, Debug, Eq, PartialEq)]
123pub struct NnsNeuronInfoRequest {
124 /// Shared network, collection time, and source transport request.
125 pub governance: NnsGovernanceRequest,
126 /// Governance neuron identifier.
127 pub neuron_id: u64,
128}
129
130impl NnsNeuronInfoRequest {
131 /// Construct a public neuron-detail request.
132 #[must_use]
133 pub const fn new(governance: NnsGovernanceRequest, neuron_id: u64) -> Self {
134 Self {
135 governance,
136 neuron_id,
137 }
138 }
139}
140
141///
142/// NnsNeuronListReport
143///
144/// Serializable page from the public NNS Governance neuron index.
145///
146
147#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
148pub struct NnsNeuronListReport {
149 /// Shared Governance authority and transport provenance.
150 #[serde(flatten)]
151 pub context: NnsGovernanceReportContext,
152 /// Live acquisition or complete-cache origin.
153 #[serde(flatten)]
154 pub provenance: crate::report::ReportProvenance,
155 /// Requested page limit.
156 pub requested_limit: u32,
157 /// Exclusive lower neuron-id bound.
158 pub exclusive_start_neuron_id: Option<u64>,
159 /// Cursor for a possible next page.
160 pub next_start_neuron_id: Option<u64>,
161 /// Total rows in the complete snapshot when known.
162 pub total_neuron_count: Option<usize>,
163 /// Whether all returned rows are guaranteed to describe one Governance instant.
164 pub point_in_time_guaranteed: bool,
165 /// Canonically ascending neuron rows.
166 pub neurons: Vec<NnsNeuronRow>,
167}
168
169///
170/// NnsNeuronInfoReport
171///
172/// Serializable public view of one NNS neuron.
173///
174
175#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
176pub struct NnsNeuronInfoReport {
177 /// Shared Governance authority and transport provenance.
178 #[serde(flatten)]
179 pub context: NnsGovernanceReportContext,
180 /// Live acquisition or complete-cache origin.
181 #[serde(flatten)]
182 pub provenance: crate::report::ReportProvenance,
183 /// Public Governance neuron view.
184 pub neuron: NnsNeuronRow,
185}