ic_query/nns/neuron/report/source/

mod.rs

//! Module: nns::neuron::report::source
//!
//! Responsibility: build NNS neuron reports from a portable async source.
//! Does not own: CLI parsing, cache IO, transport internals, or text rendering.
//! Boundary: native, canister, and custom sources converge before report assembly.

#[cfg(any(
    feature = "nns-host",
    all(feature = "canister", target_arch = "wasm32")
))]
use crate::nns::governance::{GovernanceError, NnsGovernanceNeuronId};
#[cfg(all(feature = "canister", target_arch = "wasm32"))]
mod canister;
#[cfg(feature = "nns-host")]
mod host;

use super::{
    NNS_NEURON_INFO_REPORT_SCHEMA_VERSION, NNS_NEURON_LIST_REPORT_SCHEMA_VERSION,
    NNS_NEURON_MAX_PAGE_SIZE, NnsNeuronError,
    model::{
        NnsNeuronInfoReport, NnsNeuronInfoRequest, NnsNeuronListReport, NnsNeuronListRequest,
        NnsNeuronRow,
    },
};
#[cfg(any(
    feature = "nns-host",
    all(feature = "canister", target_arch = "wasm32")
))]
use super::{
    model::{NnsKnownNeuronData, NnsNeuronBallotRow},
    wire::{
        GetNeuronIndexRequestWire, GetNeuronIndexResultWire, GetNeuronInfoResultWire,
        NeuronInfoWire,
    },
};
#[cfg(feature = "nns-host")]
use crate::nns::LiveNnsSource;
use crate::nns::governance::{
    NnsGovernanceReportContext, NnsGovernanceRequest, NnsGovernanceSourceData,
    validate_governance_request, validate_source_provenance,
};

#[cfg(any(
    feature = "nns-host",
    all(feature = "canister", target_arch = "wasm32"),
    test
))]
const GOVERNANCE_ERROR_TYPE_NOT_FOUND: i32 = 4;

///
/// NnsNeuronPage
///
/// One canonically ascending page from the public Governance neuron index.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub struct NnsNeuronPage {
    /// Public neuron rows returned by Governance.
    pub neurons: Vec<NnsNeuronRow>,
    /// Exclusive lower bound for a possible next page.
    pub next_start_neuron_id: Option<u64>,
}

/// Build one bounded neuron-index page through the native replica adapter.
#[cfg(feature = "nns-host")]
pub async fn build_nns_neuron_list_report(
    request: &NnsNeuronListRequest,
) -> Result<NnsNeuronListReport, super::NnsNeuronHostError> {
    Ok(build_nns_neuron_list_report_with_source(request, &LiveNnsSource::default()).await?)
}

/// Build one exact neuron detail through the native replica adapter.
#[cfg(feature = "nns-host")]
pub async fn build_nns_neuron_info_report(
    request: &NnsNeuronInfoRequest,
) -> Result<NnsNeuronInfoReport, super::NnsNeuronHostError> {
    Ok(build_nns_neuron_info_report_with_source(request, &LiveNnsSource::default()).await?)
}

/// Build one bounded NNS neuron-index page from a caller-owned async source.
pub async fn build_nns_neuron_list_report_with_source(
    request: &NnsNeuronListRequest,
    source: &dyn NnsNeuronSource,
) -> Result<NnsNeuronListReport, NnsNeuronError> {
    validate_governance_request(&request.governance)?;
    validate_page_size(request.limit)?;
    let data = source
        .fetch_neuron_page(
            &request.governance,
            request.exclusive_start_neuron_id,
            request.limit,
        )
        .await?;
    validate_source_provenance(&request.governance.source, &data.provenance)?;
    validate_neuron_page(
        &data.value,
        request.exclusive_start_neuron_id,
        request.limit,
    )?;
    Ok(list_report_from_rows(
        request,
        NnsNeuronReportProvenance::live(NnsGovernanceReportContext::from_source(
            &request.governance,
            data.provenance,
        )),
        data.value.neurons,
        data.value.next_start_neuron_id,
        None,
    ))
}

/// Build one exact NNS neuron detail from a caller-owned async source.
pub async fn build_nns_neuron_info_report_with_source(
    request: &NnsNeuronInfoRequest,
    source: &dyn NnsNeuronSource,
) -> Result<NnsNeuronInfoReport, NnsNeuronError> {
    validate_governance_request(&request.governance)?;
    let data = source
        .fetch_neuron(&request.governance, request.neuron_id)
        .await?;
    validate_source_provenance(&request.governance.source, &data.provenance)?;
    if data.value.neuron_id != request.neuron_id {
        return Err(NnsNeuronError::InvalidResponse {
            reason: format!(
                "source returned neuron {}, expected {}",
                data.value.neuron_id, request.neuron_id
            ),
        });
    }
    validate_neuron_rows(std::slice::from_ref(&data.value))?;
    Ok(info_report_from_row(
        NnsNeuronReportProvenance::live(NnsGovernanceReportContext::from_source(
            &request.governance,
            data.provenance,
        )),
        data.value,
    ))
}

///
/// NnsNeuronSourceFuture
///
/// Boxed caller-runtime future returned by a neuron source.
///

pub type NnsNeuronSourceFuture<'a, T> =
    crate::report::SourceFuture<'a, Result<NnsGovernanceSourceData<T>, NnsNeuronError>>;

///
/// NnsNeuronSource
///
/// Portable async capability for bounded neuron list and exact detail calls.
///

pub trait NnsNeuronSource: Send + Sync {
    /// Fetch at most one bounded page from the public neuron index.
    fn fetch_neuron_page<'a>(
        &'a self,
        request: &'a NnsGovernanceRequest,
        exclusive_start_neuron_id: Option<u64>,
        page_size: u32,
    ) -> NnsNeuronSourceFuture<'a, NnsNeuronPage>;

    /// Fetch one exact public limited neuron view.
    fn fetch_neuron<'a>(
        &'a self,
        request: &'a NnsGovernanceRequest,
        neuron_id: u64,
    ) -> NnsNeuronSourceFuture<'a, NnsNeuronRow>;
}

///
/// NnsNeuronReportProvenance
///
/// Shared live or cached provenance used while assembling neuron reports.
///

#[derive(Clone)]
pub(super) struct NnsNeuronReportProvenance {
    pub(super) context: NnsGovernanceReportContext,
    pub(super) cache_path: Option<String>,
}

impl NnsNeuronReportProvenance {
    const fn live(context: NnsGovernanceReportContext) -> Self {
        Self {
            context,
            cache_path: None,
        }
    }
}

pub(super) fn list_report_from_rows(
    request: &NnsNeuronListRequest,
    provenance: NnsNeuronReportProvenance,
    neurons: Vec<NnsNeuronRow>,
    next_start_neuron_id: Option<u64>,
    total_neuron_count: Option<usize>,
) -> NnsNeuronListReport {
    NnsNeuronListReport {
        context: NnsGovernanceReportContext {
            schema_version: NNS_NEURON_LIST_REPORT_SCHEMA_VERSION,
            ..provenance.context
        },
        provenance: provenance
            .cache_path
            .map_or(crate::report::ReportProvenance::Live, |cache_path| {
                crate::report::ReportProvenance::Cache { cache_path }
            }),
        requested_limit: request.limit,
        exclusive_start_neuron_id: request.exclusive_start_neuron_id,
        next_start_neuron_id,
        total_neuron_count,
        point_in_time_guaranteed: false,
        returned_neuron_count: neurons.len(),
        neurons,
    }
}

pub(super) fn info_report_from_row(
    provenance: NnsNeuronReportProvenance,
    neuron: NnsNeuronRow,
) -> NnsNeuronInfoReport {
    NnsNeuronInfoReport {
        context: NnsGovernanceReportContext {
            schema_version: NNS_NEURON_INFO_REPORT_SCHEMA_VERSION,
            ..provenance.context
        },
        provenance: provenance
            .cache_path
            .map_or(crate::report::ReportProvenance::Live, |cache_path| {
                crate::report::ReportProvenance::Cache { cache_path }
            }),
        neuron,
    }
}

pub(super) fn validate_page_size(page_size: u32) -> Result<(), NnsNeuronError> {
    if (1..=NNS_NEURON_MAX_PAGE_SIZE).contains(&page_size) {
        Ok(())
    } else {
        Err(NnsNeuronError::InvalidPageSize {
            page_size,
            max_page_size: NNS_NEURON_MAX_PAGE_SIZE,
        })
    }
}

pub(super) fn validate_neuron_rows(rows: &[NnsNeuronRow]) -> Result<(), NnsNeuronError> {
    if rows
        .windows(2)
        .any(|pair| pair[0].neuron_id >= pair[1].neuron_id)
    {
        return Err(NnsNeuronError::InvalidResponse {
            reason: "neuron ids are not strictly ascending and unique".to_string(),
        });
    }
    Ok(())
}

pub(super) fn validate_neuron_page(
    page: &NnsNeuronPage,
    exclusive_start_neuron_id: Option<u64>,
    page_size: u32,
) -> Result<(), NnsNeuronError> {
    if page.neurons.len() > page_size as usize {
        return Err(NnsNeuronError::InvalidResponse {
            reason: format!(
                "source returned {} rows for page size {page_size}",
                page.neurons.len()
            ),
        });
    }
    validate_neuron_rows(&page.neurons)?;
    if let (Some(start), Some(first)) = (
        exclusive_start_neuron_id,
        page.neurons.first().map(|row| row.neuron_id),
    ) && first <= start
    {
        return Err(NnsNeuronError::InvalidResponse {
            reason: format!("first neuron id {first} is not greater than cursor {start}"),
        });
    }
    let expected_next = (page.neurons.len() == page_size as usize)
        .then(|| page.neurons.last().map(|row| row.neuron_id))
        .flatten();
    if page.next_start_neuron_id != expected_next {
        return Err(NnsNeuronError::InvalidResponse {
            reason: format!(
                "next cursor {:?} does not match expected {:?}",
                page.next_start_neuron_id, expected_next
            ),
        });
    }
    Ok(())
}

#[cfg(any(
    feature = "nns-host",
    all(feature = "canister", target_arch = "wasm32")
))]
pub(in crate::nns::neuron::report) fn governance_result<Response>(
    result: Result<Response, GovernanceError>,
) -> Result<Response, NnsNeuronError> {
    result.map_err(|error| NnsNeuronError::GovernanceResponse {
        error_type: error.error_type,
        message: error.error_message,
    })
}

#[cfg(any(
    feature = "nns-host",
    all(feature = "canister", target_arch = "wasm32"),
    test
))]
pub(in crate::nns::neuron::report) fn map_neuron_info_error(
    error: NnsNeuronError,
    neuron_id: u64,
) -> NnsNeuronError {
    match error {
        NnsNeuronError::GovernanceResponse { error_type, .. }
            if error_type == GOVERNANCE_ERROR_TYPE_NOT_FOUND =>
        {
            NnsNeuronError::NeuronNotFound { neuron_id }
        }
        error => error,
    }
}

#[cfg(any(
    feature = "nns-host",
    all(feature = "canister", target_arch = "wasm32")
))]
pub(in crate::nns::neuron::report) fn neuron_row_from_wire(
    wire: NeuronInfoWire,
) -> Result<NnsNeuronRow, NnsNeuronError> {
    let neuron_id = wire.id.ok_or(NnsNeuronError::MissingNeuronId)?.id;
    Ok(NnsNeuronRow {
        neuron_id,
        state: wire.state,
        visibility: wire.visibility,

        neuron_type: wire.neuron_type,
        stake_e8s: wire.stake_e8s,
        staked_maturity_e8s_equivalent: wire.staked_maturity_e8s_equivalent,
        dissolve_delay_seconds: wire.dissolve_delay_seconds,
        age_seconds: wire.age_seconds,
        created_timestamp_seconds: wire.created_timestamp_seconds,
        retrieved_at_timestamp_seconds: wire.retrieved_at_timestamp_seconds,
        voting_power: wire.voting_power,
        deciding_voting_power: wire.deciding_voting_power,
        potential_voting_power: wire.potential_voting_power,
        voting_power_refreshed_timestamp_seconds: wire.voting_power_refreshed_timestamp_seconds,
        joined_community_fund_timestamp_seconds: wire.joined_community_fund_timestamp_seconds,
        eight_year_gang_bonus_base_e8s: wire.eight_year_gang_bonus_base_e8s,
        known_neuron_data: wire.known_neuron_data.map(|known| NnsKnownNeuronData {
            name: known.name,
            description: known.description,
            links: known.links.unwrap_or_default(),
        }),
        recent_ballots: wire
            .recent_ballots
            .into_iter()
            .map(|ballot| NnsNeuronBallotRow {
                proposal_id: ballot.proposal_id.map(|proposal| proposal.id),
                vote: ballot.vote,
            })
            .collect(),
    })
}

#[cfg(any(
    feature = "nns-host",
    all(feature = "canister", target_arch = "wasm32")
))]
fn neuron_page_request(
    exclusive_start_neuron_id: Option<u64>,
    page_size: u32,
) -> GetNeuronIndexRequestWire {
    GetNeuronIndexRequestWire {
        exclusive_start_neuron_id: exclusive_start_neuron_id.map(|id| NnsGovernanceNeuronId { id }),
        page_size: Some(page_size),
    }
}

#[cfg(any(
    feature = "nns-host",
    all(feature = "canister", target_arch = "wasm32")
))]
fn neuron_page_from_wire(
    result: GetNeuronIndexResultWire,
    page_size: u32,
) -> Result<NnsNeuronPage, NnsNeuronError> {
    let neurons = governance_result(result)?
        .neurons
        .into_iter()
        .map(neuron_row_from_wire)
        .collect::<Result<Vec<_>, _>>()?;
    let next_start_neuron_id = (neurons.len() == page_size as usize)
        .then(|| neurons.last().map(|row| row.neuron_id))
        .flatten();
    Ok(NnsNeuronPage {
        neurons,
        next_start_neuron_id,
    })
}

#[cfg(any(
    feature = "nns-host",
    all(feature = "canister", target_arch = "wasm32")
))]
fn neuron_row_from_response(
    result: GetNeuronInfoResultWire,
    neuron_id: u64,
) -> Result<NnsNeuronRow, NnsNeuronError> {
    let wire =
        governance_result(result).map_err(|error| map_neuron_info_error(error, neuron_id))?;
    neuron_row_from_wire(*wire)
}

#[cfg(test)]
mod tests {
    use super::{NnsNeuronError, map_neuron_info_error};

    #[test]
    fn neuron_info_maps_only_the_native_not_found_error() {
        let not_found = map_neuron_info_error(
            NnsNeuronError::GovernanceResponse {
                error_type: 4,
                message: "wording is not part of the contract".to_string(),
            },
            42,
        );
        assert!(matches!(
            not_found,
            NnsNeuronError::NeuronNotFound { neuron_id: 42 }
        ));

        let unrelated = map_neuron_info_error(
            NnsNeuronError::GovernanceResponse {
                error_type: 12,
                message: "not found text must not override the code".to_string(),
            },
            42,
        );
        assert!(matches!(
            unrelated,
            NnsNeuronError::GovernanceResponse { error_type: 12, .. }
        ));
    }
}