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