Skip to main content

ic_query/nns/neuron/report/source/
mod.rs

1//! Module: nns::neuron::report::source
2//!
3//! Responsibility: build NNS neuron reports from a portable async source.
4//! Does not own: CLI parsing, cache IO, transport internals, or text rendering.
5//! Boundary: native, canister, and custom sources converge before report assembly.
6
7#[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///
52/// NnsNeuronPage
53///
54/// One canonically ascending page from the public Governance neuron index.
55///
56
57#[derive(Clone, Debug, Eq, PartialEq)]
58pub struct NnsNeuronPage {
59    /// Public neuron rows returned by Governance.
60    pub neurons: Vec<NnsNeuronRow>,
61    /// Exclusive lower bound for a possible next page.
62    pub next_start_neuron_id: Option<u64>,
63}
64
65/// Build one bounded NNS neuron-index page from a caller-owned async source.
66pub 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
95/// Build one exact NNS neuron detail from a caller-owned async source.
96pub 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
121///
122/// NnsNeuronSourceFuture
123///
124/// Boxed caller-runtime future returned by a neuron source.
125///
126
127pub type NnsNeuronSourceFuture<'a, T> =
128    crate::report::SourceFuture<'a, Result<NnsGovernanceSourceData<T>, NnsNeuronError>>;
129
130///
131/// NnsNeuronSource
132///
133/// Portable async capability for bounded neuron list and exact detail calls.
134///
135
136pub trait NnsNeuronSource: Send + Sync {
137    /// Fetch at most one bounded page from the public neuron index.
138    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    /// Fetch one exact public limited neuron view.
146    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;