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}
103
104impl NnsNeuronListRequest {
105    /// Construct a first-page public neuron-index request.
106    #[must_use]
107    pub const fn new(governance: NnsGovernanceRequest, limit: u32) -> Self {
108        Self {
109            governance,
110            limit,
111            exclusive_start_neuron_id: None,
112        }
113    }
114
115    /// Start strictly after the given neuron id.
116    #[must_use]
117    pub const fn with_exclusive_start_neuron_id(mut self, neuron_id: u64) -> Self {
118        self.exclusive_start_neuron_id = Some(neuron_id);
119        self
120    }
121}
122
123///
124/// NnsNeuronInfoRequest
125///
126/// Request for one public NNS Governance neuron view.
127///
128
129#[derive(Clone, Debug, Eq, PartialEq)]
130pub struct NnsNeuronInfoRequest {
131    /// Shared network, collection time, and source transport request.
132    pub governance: NnsGovernanceRequest,
133    /// Governance neuron identifier.
134    pub neuron_id: u64,
135}
136
137impl NnsNeuronInfoRequest {
138    /// Construct a public neuron-detail request.
139    #[must_use]
140    pub const fn new(governance: NnsGovernanceRequest, neuron_id: u64) -> Self {
141        Self {
142            governance,
143            neuron_id,
144        }
145    }
146}
147
148///
149/// NnsNeuronListReport
150///
151/// Serializable page from the public NNS Governance neuron index.
152///
153
154#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
155pub struct NnsNeuronListReport {
156    /// Shared Governance authority and transport provenance.
157    #[serde(flatten)]
158    pub context: NnsGovernanceReportContext,
159    /// Live acquisition or complete-cache origin.
160    #[serde(flatten)]
161    pub provenance: crate::report::ReportProvenance,
162    /// Requested page limit.
163    pub requested_limit: u32,
164    /// Exclusive lower neuron-id bound.
165    pub exclusive_start_neuron_id: Option<u64>,
166    /// Cursor for a possible next page.
167    pub next_start_neuron_id: Option<u64>,
168    /// Total rows in the complete snapshot when known.
169    pub total_neuron_count: Option<usize>,
170    /// Whether all returned rows are guaranteed to describe one Governance instant.
171    pub point_in_time_guaranteed: bool,
172    /// Number of rows returned in this view.
173    pub returned_neuron_count: usize,
174    /// Canonically ascending neuron rows.
175    pub neurons: Vec<NnsNeuronRow>,
176}
177
178///
179/// NnsNeuronInfoReport
180///
181/// Serializable public view of one NNS neuron.
182///
183
184#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
185pub struct NnsNeuronInfoReport {
186    /// Shared Governance authority and transport provenance.
187    #[serde(flatten)]
188    pub context: NnsGovernanceReportContext,
189    /// Live acquisition or complete-cache origin.
190    #[serde(flatten)]
191    pub provenance: crate::report::ReportProvenance,
192    /// Public Governance neuron view.
193    pub neuron: NnsNeuronRow,
194}
ic_query/nns/neuron/report/model.rs

ic_query/nns/neuron/report/
model.rs
