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 super::classification::{NnsNeuronState, NnsNeuronType, NnsNeuronVisibility, NnsNeuronVote};
8#[cfg(feature = "host")]
9use serde::Deserialize as SerdeDeserialize;
10use serde::Serialize;
11
12///
13/// NnsKnownNeuronData
14///
15/// Public metadata attached to a registered known neuron.
16///
17
18#[cfg_attr(feature = "host", derive(SerdeDeserialize))]
19#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
20pub struct NnsKnownNeuronData {
21 /// Registered neuron name.
22 pub name: String,
23 /// Optional registered description.
24 pub description: Option<String>,
25 /// Registered related links.
26 pub links: Vec<String>,
27}
28
29///
30/// NnsNeuronBallotRow
31///
32/// One recent public ballot exposed by the Governance neuron index.
33///
34
35#[cfg_attr(feature = "host", derive(SerdeDeserialize))]
36#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
37pub struct NnsNeuronBallotRow {
38 /// Proposal identifier when supplied by Governance.
39 pub proposal_id: Option<u64>,
40 /// Raw Governance vote discriminant.
41 pub vote: i32,
42 /// Typed classification and stable display label for the raw vote.
43 pub vote_text: NnsNeuronVote,
44}
45
46///
47/// NnsNeuronRow
48///
49/// Public limited view of one NNS neuron returned by Governance.
50///
51
52#[cfg_attr(feature = "host", derive(SerdeDeserialize))]
53#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
54pub struct NnsNeuronRow {
55 /// Stable Governance neuron identifier.
56 pub neuron_id: u64,
57 /// Raw Governance state discriminant.
58 pub state: i32,
59 /// Typed classification and stable display label for the raw state.
60 pub state_text: NnsNeuronState,
61 /// Raw optional neuron visibility discriminant.
62 pub visibility: Option<i32>,
63 /// Typed classification and stable display label for the raw visibility.
64 pub visibility_text: NnsNeuronVisibility,
65 /// Raw optional neuron-type discriminant.
66 pub neuron_type: Option<i32>,
67 /// Typed classification and stable display label for the raw neuron type.
68 pub neuron_type_text: NnsNeuronType,
69 /// Public effective stake, including staked maturity, in e8s.
70 pub stake_e8s: u64,
71 /// Staked maturity included in effective stake, in e8s when supplied.
72 pub staked_maturity_e8s_equivalent: Option<u64>,
73 /// Current dissolve delay in seconds.
74 pub dissolve_delay_seconds: u64,
75 /// Current neuron age in seconds.
76 pub age_seconds: u64,
77 /// Neuron creation timestamp in Unix seconds.
78 pub created_timestamp_seconds: u64,
79 /// Governance retrieval timestamp in Unix seconds.
80 pub retrieved_at_timestamp_seconds: u64,
81 /// Deprecated Governance voting-power field retained losslessly.
82 pub voting_power: u64,
83 /// Current deciding voting power when supplied.
84 pub deciding_voting_power: Option<u64>,
85 /// Current potential voting power when supplied.
86 pub potential_voting_power: Option<u64>,
87 /// Last voting-power refresh timestamp in Unix seconds.
88 pub voting_power_refreshed_timestamp_seconds: Option<u64>,
89 /// Neurons' Fund join timestamp in Unix seconds when publicly visible.
90 pub joined_community_fund_timestamp_seconds: Option<u64>,
91 /// Eight-year dissolve-delay bonus base in e8s when supplied.
92 pub eight_year_gang_bonus_base_e8s: Option<u64>,
93 /// Registered public known-neuron metadata when present.
94 pub known_neuron_data: Option<NnsKnownNeuronData>,
95 /// Recent ballots visible to the unauthenticated caller.
96 pub recent_ballots: Vec<NnsNeuronBallotRow>,
97}
98
99///
100/// NnsNeuronListRequest
101///
102/// Request for one page of the public NNS Governance neuron index.
103///
104
105#[derive(Clone, Debug, Eq, PartialEq)]
106pub struct NnsNeuronListRequest {
107 /// Requested network identity.
108 pub network: String,
109 /// Replica endpoint used for the query.
110 pub source_endpoint: String,
111 /// Caller-provided collection time in Unix seconds.
112 pub now_unix_secs: u64,
113 /// Maximum rows to return.
114 pub limit: u32,
115 /// Exclusive lower neuron-id bound.
116 pub exclusive_start_neuron_id: Option<u64>,
117 /// Whether text output should include expanded metadata.
118 pub verbose: bool,
119}
120
121impl NnsNeuronListRequest {
122 /// Construct a first-page public neuron-index request.
123 #[must_use]
124 pub fn new(
125 network: impl Into<String>,
126 source_endpoint: impl Into<String>,
127 now_unix_secs: u64,
128 limit: u32,
129 ) -> Self {
130 Self {
131 network: network.into(),
132 source_endpoint: source_endpoint.into(),
133 now_unix_secs,
134 limit,
135 exclusive_start_neuron_id: None,
136 verbose: false,
137 }
138 }
139
140 /// Start strictly after the given neuron id.
141 #[must_use]
142 pub const fn with_exclusive_start_neuron_id(mut self, neuron_id: u64) -> Self {
143 self.exclusive_start_neuron_id = Some(neuron_id);
144 self
145 }
146
147 /// Select compact or expanded text rendering.
148 #[must_use]
149 pub const fn with_verbose(mut self, verbose: bool) -> Self {
150 self.verbose = verbose;
151 self
152 }
153}
154
155///
156/// NnsNeuronInfoRequest
157///
158/// Request for one public NNS Governance neuron view.
159///
160
161#[derive(Clone, Debug, Eq, PartialEq)]
162pub struct NnsNeuronInfoRequest {
163 /// Requested network identity.
164 pub network: String,
165 /// Replica endpoint used for the query.
166 pub source_endpoint: String,
167 /// Caller-provided collection time in Unix seconds.
168 pub now_unix_secs: u64,
169 /// Governance neuron identifier.
170 pub neuron_id: u64,
171 /// Whether text output should include expanded metadata.
172 pub verbose: bool,
173}
174
175impl NnsNeuronInfoRequest {
176 /// Construct a public neuron-detail request.
177 #[must_use]
178 pub fn new(
179 network: impl Into<String>,
180 source_endpoint: impl Into<String>,
181 now_unix_secs: u64,
182 neuron_id: u64,
183 ) -> Self {
184 Self {
185 network: network.into(),
186 source_endpoint: source_endpoint.into(),
187 now_unix_secs,
188 neuron_id,
189 verbose: false,
190 }
191 }
192
193 /// Select compact or expanded text rendering.
194 #[must_use]
195 pub const fn with_verbose(mut self, verbose: bool) -> Self {
196 self.verbose = verbose;
197 self
198 }
199}
200
201///
202/// NnsNeuronListReport
203///
204/// Serializable page from the public NNS Governance neuron index.
205///
206
207#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
208pub struct NnsNeuronListReport {
209 /// Report schema version.
210 pub schema_version: u32,
211 /// Queried network identity.
212 pub network: String,
213 /// NNS Governance canister principal.
214 pub governance_canister_id: String,
215 /// UTC collection timestamp.
216 pub fetched_at: String,
217 /// Replica endpoint or cached snapshot endpoint provenance.
218 pub source_endpoint: String,
219 /// Collector identity.
220 pub fetched_by: String,
221 /// Cache path when the page came from a complete snapshot.
222 pub cache_path: Option<String>,
223 /// Whether rows came from a complete local snapshot.
224 pub from_cache: bool,
225 /// Requested page limit.
226 pub requested_limit: u32,
227 /// Exclusive lower neuron-id bound.
228 pub exclusive_start_neuron_id: Option<u64>,
229 /// Cursor for a possible next page.
230 pub next_start_neuron_id: Option<u64>,
231 /// Total rows in the complete snapshot when known.
232 pub total_neuron_count: Option<usize>,
233 /// Whether all returned rows are guaranteed to describe one Governance instant.
234 pub point_in_time_guaranteed: bool,
235 /// Number of rows returned in this view.
236 pub returned_neuron_count: usize,
237 /// Whether verbose text rendering was requested.
238 pub verbose: bool,
239 /// Canonically ascending neuron rows.
240 pub neurons: Vec<NnsNeuronRow>,
241}
242
243///
244/// NnsNeuronInfoReport
245///
246/// Serializable public view of one NNS neuron.
247///
248
249#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
250pub struct NnsNeuronInfoReport {
251 /// Report schema version.
252 pub schema_version: u32,
253 /// Queried network identity.
254 pub network: String,
255 /// NNS Governance canister principal.
256 pub governance_canister_id: String,
257 /// UTC collection timestamp.
258 pub fetched_at: String,
259 /// Replica endpoint or cached snapshot endpoint provenance.
260 pub source_endpoint: String,
261 /// Collector identity.
262 pub fetched_by: String,
263 /// Cache path when the row came from a complete snapshot.
264 pub cache_path: Option<String>,
265 /// Whether the row came from a complete local snapshot.
266 pub from_cache: bool,
267 /// Whether verbose text rendering was requested.
268 pub verbose: bool,
269 /// Public Governance neuron view.
270 pub neuron: NnsNeuronRow,
271}