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