1#[cfg(any(
8 feature = "nns-host",
9 all(feature = "canister", target_arch = "wasm32")
10))]
11use crate::nns::governance::{GovernanceError, NnsGovernanceNeuronId};
12#[cfg(any(
13 feature = "nns-host",
14 all(feature = "canister", target_arch = "wasm32")
15))]
16mod query;
17
18use crate::report::ReportProvenance;
19
20use super::{
21 NNS_NEURON_INFO_REPORT_SCHEMA_VERSION, NNS_NEURON_LIST_REPORT_SCHEMA_VERSION,
22 NNS_NEURON_MAX_PAGE_SIZE, NnsNeuronError,
23 model::{
24 NnsNeuronInfoReport, NnsNeuronInfoRequest, NnsNeuronListReport, NnsNeuronListRequest,
25 NnsNeuronRow,
26 },
27};
28#[cfg(any(
29 feature = "nns-host",
30 all(feature = "canister", target_arch = "wasm32")
31))]
32use super::{
33 model::{NnsKnownNeuronData, NnsNeuronBallotRow},
34 wire::{
35 GetNeuronIndexRequestWire, GetNeuronIndexResultWire, GetNeuronInfoResultWire,
36 NeuronInfoWire,
37 },
38};
39use crate::nns::governance::{
40 NnsGovernanceReportContext, NnsGovernanceRequest, NnsGovernanceSourceData,
41 validate_governance_request, validate_source_provenance,
42};
43
44#[cfg(any(
45 feature = "nns-host",
46 all(feature = "canister", target_arch = "wasm32"),
47 test
48))]
49const GOVERNANCE_ERROR_TYPE_NOT_FOUND: i32 = 4;
50
51#[derive(Clone, Debug, Eq, PartialEq)]
58pub struct NnsNeuronPage {
59 pub neurons: Vec<NnsNeuronRow>,
61 pub next_start_neuron_id: Option<u64>,
63}
64
65pub async fn build_nns_neuron_list_report_with_source(
67 request: &NnsNeuronListRequest,
68 source: &dyn NnsNeuronSource,
69) -> Result<NnsNeuronListReport, NnsNeuronError> {
70 validate_governance_request(&request.governance)?;
71 validate_page_size(request.limit)?;
72 let data = source
73 .fetch_neuron_page(
74 &request.governance,
75 request.exclusive_start_neuron_id,
76 request.limit,
77 )
78 .await?;
79 validate_source_provenance(&request.governance.source, &data.provenance)?;
80 validate_neuron_page(
81 &data.value,
82 request.exclusive_start_neuron_id,
83 request.limit,
84 )?;
85 Ok(list_report_from_rows(
86 request,
87 NnsGovernanceReportContext::from_source(&request.governance, data.provenance),
88 ReportProvenance::live(),
89 data.value.neurons,
90 data.value.next_start_neuron_id,
91 None,
92 ))
93}
94
95pub async fn build_nns_neuron_info_report_with_source(
97 request: &NnsNeuronInfoRequest,
98 source: &dyn NnsNeuronSource,
99) -> Result<NnsNeuronInfoReport, NnsNeuronError> {
100 validate_governance_request(&request.governance)?;
101 let data = source
102 .fetch_neuron(&request.governance, request.neuron_id)
103 .await?;
104 validate_source_provenance(&request.governance.source, &data.provenance)?;
105 if data.value.neuron_id != request.neuron_id {
106 return Err(NnsNeuronError::InvalidResponse {
107 reason: format!(
108 "source returned neuron {}, expected {}",
109 data.value.neuron_id, request.neuron_id
110 ),
111 });
112 }
113 validate_neuron_rows(std::slice::from_ref(&data.value))?;
114 Ok(info_report_from_row(
115 NnsGovernanceReportContext::from_source(&request.governance, data.provenance),
116 ReportProvenance::live(),
117 data.value,
118 ))
119}
120
121pub type NnsNeuronSourceFuture<'a, T> =
128 crate::report::SourceFuture<'a, Result<NnsGovernanceSourceData<T>, NnsNeuronError>>;
129
130pub trait NnsNeuronSource: Send + Sync {
137 fn fetch_neuron_page<'a>(
139 &'a self,
140 request: &'a NnsGovernanceRequest,
141 exclusive_start_neuron_id: Option<u64>,
142 page_size: u32,
143 ) -> NnsNeuronSourceFuture<'a, NnsNeuronPage>;
144
145 fn fetch_neuron<'a>(
147 &'a self,
148 request: &'a NnsGovernanceRequest,
149 neuron_id: u64,
150 ) -> NnsNeuronSourceFuture<'a, NnsNeuronRow>;
151}
152
153pub(super) fn list_report_from_rows(
154 request: &NnsNeuronListRequest,
155 context: NnsGovernanceReportContext,
156 provenance: ReportProvenance,
157 neurons: Vec<NnsNeuronRow>,
158 next_start_neuron_id: Option<u64>,
159 total_neuron_count: Option<usize>,
160) -> NnsNeuronListReport {
161 NnsNeuronListReport {
162 context: NnsGovernanceReportContext {
163 schema_version: NNS_NEURON_LIST_REPORT_SCHEMA_VERSION,
164 ..context
165 },
166 provenance,
167 requested_limit: request.limit,
168 exclusive_start_neuron_id: request.exclusive_start_neuron_id,
169 next_start_neuron_id,
170 total_neuron_count,
171 point_in_time_guaranteed: false,
172
173 neurons,
174 }
175}
176
177pub(super) fn info_report_from_row(
178 context: NnsGovernanceReportContext,
179 provenance: ReportProvenance,
180 neuron: NnsNeuronRow,
181) -> NnsNeuronInfoReport {
182 NnsNeuronInfoReport {
183 context: NnsGovernanceReportContext {
184 schema_version: NNS_NEURON_INFO_REPORT_SCHEMA_VERSION,
185 ..context
186 },
187 provenance,
188 neuron,
189 }
190}
191
192pub(super) fn validate_page_size(page_size: u32) -> Result<(), NnsNeuronError> {
193 if (1..=NNS_NEURON_MAX_PAGE_SIZE).contains(&page_size) {
194 Ok(())
195 } else {
196 Err(NnsNeuronError::InvalidPageSize {
197 page_size,
198 max_page_size: NNS_NEURON_MAX_PAGE_SIZE,
199 })
200 }
201}
202
203pub(super) fn validate_neuron_rows(rows: &[NnsNeuronRow]) -> Result<(), NnsNeuronError> {
204 if rows
205 .windows(2)
206 .any(|pair| pair[0].neuron_id >= pair[1].neuron_id)
207 {
208 return Err(NnsNeuronError::InvalidResponse {
209 reason: "neuron ids are not strictly ascending and unique".to_string(),
210 });
211 }
212 Ok(())
213}
214
215pub(super) fn validate_neuron_page(
216 page: &NnsNeuronPage,
217 exclusive_start_neuron_id: Option<u64>,
218 page_size: u32,
219) -> Result<(), NnsNeuronError> {
220 if page.neurons.len() > page_size as usize {
221 return Err(NnsNeuronError::InvalidResponse {
222 reason: format!(
223 "source returned {} rows for page size {page_size}",
224 page.neurons.len()
225 ),
226 });
227 }
228 validate_neuron_rows(&page.neurons)?;
229 if let (Some(start), Some(first)) = (
230 exclusive_start_neuron_id,
231 page.neurons.first().map(|row| row.neuron_id),
232 ) && first <= start
233 {
234 return Err(NnsNeuronError::InvalidResponse {
235 reason: format!("first neuron id {first} is not greater than cursor {start}"),
236 });
237 }
238 let expected_next = (page.neurons.len() == page_size as usize)
239 .then(|| page.neurons.last().map(|row| row.neuron_id))
240 .flatten();
241 if page.next_start_neuron_id != expected_next {
242 return Err(NnsNeuronError::InvalidResponse {
243 reason: format!(
244 "next cursor {:?} does not match expected {:?}",
245 page.next_start_neuron_id, expected_next
246 ),
247 });
248 }
249 Ok(())
250}
251
252#[cfg(any(
253 feature = "nns-host",
254 all(feature = "canister", target_arch = "wasm32")
255))]
256pub(in crate::nns::neuron::report) fn governance_result<Response>(
257 result: Result<Response, GovernanceError>,
258) -> Result<Response, NnsNeuronError> {
259 result.map_err(|error| NnsNeuronError::GovernanceResponse {
260 error_type: error.error_type,
261 message: error.error_message,
262 })
263}
264
265#[cfg(any(
266 feature = "nns-host",
267 all(feature = "canister", target_arch = "wasm32"),
268 test
269))]
270pub(in crate::nns::neuron::report) fn map_neuron_info_error(
271 error: NnsNeuronError,
272 neuron_id: u64,
273) -> NnsNeuronError {
274 match error {
275 NnsNeuronError::GovernanceResponse { error_type, .. }
276 if error_type == GOVERNANCE_ERROR_TYPE_NOT_FOUND =>
277 {
278 NnsNeuronError::NeuronNotFound { neuron_id }
279 }
280 error => error,
281 }
282}
283
284#[cfg(any(
285 feature = "nns-host",
286 all(feature = "canister", target_arch = "wasm32")
287))]
288pub(in crate::nns::neuron::report) fn neuron_row_from_wire(
289 wire: NeuronInfoWire,
290) -> Result<NnsNeuronRow, NnsNeuronError> {
291 let neuron_id = wire.id.ok_or(NnsNeuronError::MissingNeuronId)?.id;
292 Ok(NnsNeuronRow {
293 neuron_id,
294 state: wire.state,
295 visibility: wire.visibility,
296
297 neuron_type: wire.neuron_type,
298 stake_e8s: wire.stake_e8s,
299 staked_maturity_e8s_equivalent: wire.staked_maturity_e8s_equivalent,
300 dissolve_delay_seconds: wire.dissolve_delay_seconds,
301 age_seconds: wire.age_seconds,
302 created_timestamp_seconds: wire.created_timestamp_seconds,
303 retrieved_at_timestamp_seconds: wire.retrieved_at_timestamp_seconds,
304 voting_power: wire.voting_power,
305 deciding_voting_power: wire.deciding_voting_power,
306 potential_voting_power: wire.potential_voting_power,
307 voting_power_refreshed_timestamp_seconds: wire.voting_power_refreshed_timestamp_seconds,
308 joined_community_fund_timestamp_seconds: wire.joined_community_fund_timestamp_seconds,
309 eight_year_gang_bonus_base_e8s: wire.eight_year_gang_bonus_base_e8s,
310 known_neuron_data: wire.known_neuron_data.map(|known| NnsKnownNeuronData {
311 name: known.name,
312 description: known.description,
313 links: known.links.unwrap_or_default(),
314 }),
315 recent_ballots: wire
316 .recent_ballots
317 .into_iter()
318 .map(|ballot| NnsNeuronBallotRow {
319 proposal_id: ballot.proposal_id.map(|proposal| proposal.id),
320 vote: ballot.vote,
321 })
322 .collect(),
323 })
324}
325
326#[cfg(any(
327 feature = "nns-host",
328 all(feature = "canister", target_arch = "wasm32")
329))]
330fn neuron_page_request(
331 exclusive_start_neuron_id: Option<u64>,
332 page_size: u32,
333) -> GetNeuronIndexRequestWire {
334 GetNeuronIndexRequestWire {
335 exclusive_start_neuron_id: exclusive_start_neuron_id.map(|id| NnsGovernanceNeuronId { id }),
336 page_size: Some(page_size),
337 }
338}
339
340#[cfg(any(
341 feature = "nns-host",
342 all(feature = "canister", target_arch = "wasm32")
343))]
344fn neuron_page_from_wire(
345 result: GetNeuronIndexResultWire,
346 page_size: u32,
347) -> Result<NnsNeuronPage, NnsNeuronError> {
348 let neurons = governance_result(result)?
349 .neurons
350 .into_iter()
351 .map(neuron_row_from_wire)
352 .collect::<Result<Vec<_>, _>>()?;
353 let next_start_neuron_id = (neurons.len() == page_size as usize)
354 .then(|| neurons.last().map(|row| row.neuron_id))
355 .flatten();
356 Ok(NnsNeuronPage {
357 neurons,
358 next_start_neuron_id,
359 })
360}
361
362#[cfg(any(
363 feature = "nns-host",
364 all(feature = "canister", target_arch = "wasm32")
365))]
366fn neuron_row_from_response(
367 result: GetNeuronInfoResultWire,
368 neuron_id: u64,
369) -> Result<NnsNeuronRow, NnsNeuronError> {
370 let wire =
371 governance_result(result).map_err(|error| map_neuron_info_error(error, neuron_id))?;
372 neuron_row_from_wire(wire)
373}
374
375#[cfg(test)]
376mod tests;