ic-query 0.40.1

Internet Computer query library for CloudEngine, NNS, SNS, ICRC, system canisters, and public network metadata
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Module: nns::governance::build
//!
//! Responsibility: assemble direct NNS Governance reports with shared provenance.
//! Does not own: live transport, Candid wire types, persistence, or text rendering.
//! Boundary: validates request and returned source evidence around one source invocation.

use super::{
    NNS_GOVERNANCE_REPORT_SCHEMA_VERSION, NnsGovernanceEconomicsReport, NnsGovernanceError,
    NnsGovernanceMaturityModulationReport, NnsGovernanceMetricsReport, NnsGovernanceReportContext,
    NnsGovernanceRequest, NnsGovernanceRewardEventReport, NnsGovernanceSource,
    NnsGovernanceSourceProvenance,
    validation::{
        validate_governance_metrics, validate_governance_request, validate_source_provenance,
    },
};
use crate::nns::MAINNET_GOVERNANCE_CANISTER_ID;
#[cfg(feature = "nns-host")]
use crate::{nns::LiveNnsSource, runtime::block_on_current_thread};

#[cfg(feature = "nns-host")]
use super::NnsGovernanceHostError;

/// Build one live NNS Governance economics report through the native replica adapter.
#[cfg(feature = "nns-host")]
pub fn build_nns_governance_economics_report(
    request: &NnsGovernanceRequest,
) -> Result<NnsGovernanceEconomicsReport, NnsGovernanceHostError> {
    Ok(block_on_current_thread(
        build_nns_governance_economics_report_with_source(request, &LiveNnsSource),
    )??)
}

/// Build one NNS Governance economics report from a caller-owned async source.
pub async fn build_nns_governance_economics_report_with_source(
    request: &NnsGovernanceRequest,
    source: &dyn NnsGovernanceSource,
) -> Result<NnsGovernanceEconomicsReport, NnsGovernanceError> {
    validate_governance_request(request)?;
    let data = source.fetch_economics(request).await?;
    validate_source_provenance(&request.source, &data.provenance)?;
    Ok(NnsGovernanceEconomicsReport {
        context: report_context(request, data.provenance),
        economics: data.value,
    })
}

/// Build one live NNS Governance metrics report through the native replica adapter.
#[cfg(feature = "nns-host")]
pub fn build_nns_governance_metrics_report(
    request: &NnsGovernanceRequest,
) -> Result<NnsGovernanceMetricsReport, NnsGovernanceHostError> {
    Ok(block_on_current_thread(
        build_nns_governance_metrics_report_with_source(request, &LiveNnsSource),
    )??)
}

/// Build one NNS Governance metrics report from a caller-owned async source.
pub async fn build_nns_governance_metrics_report_with_source(
    request: &NnsGovernanceRequest,
    source: &dyn NnsGovernanceSource,
) -> Result<NnsGovernanceMetricsReport, NnsGovernanceError> {
    validate_governance_request(request)?;
    let data = source.fetch_metrics(request).await?;
    validate_source_provenance(&request.source, &data.provenance)?;
    validate_governance_metrics(&data.value)?;
    Ok(NnsGovernanceMetricsReport {
        context: report_context(request, data.provenance),
        metrics: data.value,
    })
}

/// Build one live latest reward-event report through the native replica adapter.
#[cfg(feature = "nns-host")]
pub fn build_nns_governance_reward_event_report(
    request: &NnsGovernanceRequest,
) -> Result<NnsGovernanceRewardEventReport, NnsGovernanceHostError> {
    Ok(block_on_current_thread(
        build_nns_governance_reward_event_report_with_source(request, &LiveNnsSource),
    )??)
}

/// Build one latest reward-event report from a caller-owned async source.
pub async fn build_nns_governance_reward_event_report_with_source(
    request: &NnsGovernanceRequest,
    source: &dyn NnsGovernanceSource,
) -> Result<NnsGovernanceRewardEventReport, NnsGovernanceError> {
    validate_governance_request(request)?;
    let data = source.fetch_reward_event(request).await?;
    validate_source_provenance(&request.source, &data.provenance)?;
    Ok(NnsGovernanceRewardEventReport {
        context: report_context(request, data.provenance),
        reward_event: data.value,
    })
}

/// Build one live maturity-modulation report through the native replica adapter.
#[cfg(feature = "nns-host")]
pub fn build_nns_governance_maturity_modulation_report(
    request: &NnsGovernanceRequest,
) -> Result<NnsGovernanceMaturityModulationReport, NnsGovernanceHostError> {
    Ok(block_on_current_thread(
        build_nns_governance_maturity_modulation_report_with_source(request, &LiveNnsSource),
    )??)
}

/// Build one maturity-modulation report from a caller-owned async source.
pub async fn build_nns_governance_maturity_modulation_report_with_source(
    request: &NnsGovernanceRequest,
    source: &dyn NnsGovernanceSource,
) -> Result<NnsGovernanceMaturityModulationReport, NnsGovernanceError> {
    validate_governance_request(request)?;
    let data = source.fetch_maturity_modulation(request).await?;
    validate_source_provenance(&request.source, &data.provenance)?;
    Ok(NnsGovernanceMaturityModulationReport {
        context: report_context(request, data.provenance),
        maturity_modulation: data.value,
    })
}

fn report_context(
    request: &NnsGovernanceRequest,
    source: NnsGovernanceSourceProvenance,
) -> NnsGovernanceReportContext {
    NnsGovernanceReportContext {
        schema_version: NNS_GOVERNANCE_REPORT_SCHEMA_VERSION,
        network: request.network.clone(),
        governance_canister_id: MAINNET_GOVERNANCE_CANISTER_ID.to_string(),
        fetched_at: request.fetched_at.clone(),
        source,
    }
}