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 /// Whether text output should include expanded metadata.
103 pub verbose: bool,
104}
105
106impl NnsNeuronListRequest {
107 /// Construct a first-page public neuron-index request.
108 #[must_use]
109 pub const fn new(governance: NnsGovernanceRequest, limit: u32) -> Self {
110 Self {
111 governance,
112 limit,
113 exclusive_start_neuron_id: None,
114 verbose: false,
115 }
116 }
117
118 /// Start strictly after the given neuron id.
119 #[must_use]
120 pub const fn with_exclusive_start_neuron_id(mut self, neuron_id: u64) -> Self {
121 self.exclusive_start_neuron_id = Some(neuron_id);
122 self
123 }
124
125 /// Select compact or expanded text rendering.
126 #[must_use]
127 pub const fn with_verbose(mut self, verbose: bool) -> Self {
128 self.verbose = verbose;
129 self
130 }
131}
132
133///
134/// NnsNeuronInfoRequest
135///
136/// Request for one public NNS Governance neuron view.
137///
138
139#[derive(Clone, Debug, Eq, PartialEq)]
140pub struct NnsNeuronInfoRequest {
141 /// Shared network, collection time, and source transport request.
142 pub governance: NnsGovernanceRequest,
143 /// Governance neuron identifier.
144 pub neuron_id: u64,
145 /// Whether text output should include expanded metadata.
146 pub verbose: bool,
147}
148
149impl NnsNeuronInfoRequest {
150 /// Construct a public neuron-detail request.
151 #[must_use]
152 pub const fn new(governance: NnsGovernanceRequest, neuron_id: u64) -> Self {
153 Self {
154 governance,
155 neuron_id,
156 verbose: false,
157 }
158 }
159
160 /// Select compact or expanded text rendering.
161 #[must_use]
162 pub const fn with_verbose(mut self, verbose: bool) -> Self {
163 self.verbose = verbose;
164 self
165 }
166}
167
168///
169/// NnsNeuronListReport
170///
171/// Serializable page from the public NNS Governance neuron index.
172///
173
174#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
175pub struct NnsNeuronListReport {
176 /// Shared Governance authority and transport provenance.
177 #[serde(flatten)]
178 pub context: NnsGovernanceReportContext,
179 /// Cache path when the page came from a complete snapshot.
180 pub cache_path: Option<String>,
181 /// Whether rows came from a complete local snapshot.
182 pub from_cache: bool,
183 /// Requested page limit.
184 pub requested_limit: u32,
185 /// Exclusive lower neuron-id bound.
186 pub exclusive_start_neuron_id: Option<u64>,
187 /// Cursor for a possible next page.
188 pub next_start_neuron_id: Option<u64>,
189 /// Total rows in the complete snapshot when known.
190 pub total_neuron_count: Option<usize>,
191 /// Whether all returned rows are guaranteed to describe one Governance instant.
192 pub point_in_time_guaranteed: bool,
193 /// Number of rows returned in this view.
194 pub returned_neuron_count: usize,
195 /// Whether verbose text rendering was requested.
196 pub verbose: bool,
197 /// Canonically ascending neuron rows.
198 pub neurons: Vec<NnsNeuronRow>,
199}
200
201///
202/// NnsNeuronInfoReport
203///
204/// Serializable public view of one NNS neuron.
205///
206
207#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
208pub struct NnsNeuronInfoReport {
209 /// Shared Governance authority and transport provenance.
210 #[serde(flatten)]
211 pub context: NnsGovernanceReportContext,
212 /// Cache path when the row came from a complete snapshot.
213 pub cache_path: Option<String>,
214 /// Whether the row came from a complete local snapshot.
215 pub from_cache: bool,
216 /// Whether verbose text rendering was requested.
217 pub verbose: bool,
218 /// Public Governance neuron view.
219 pub neuron: NnsNeuronRow,
220}