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