ic-query 0.90.0

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

//! Module: sns::report::model::reports::upgrade
//!
//! Responsibility: bounded native SNS upgrade report DTOs.
//! Does not own: Governance or SNS-W calls, target admission, lookup, or rendering.
//! Boundary: preserves native versions and validates their shared hash representation.

use super::invocation::SnsCanisterMethod;
#[cfg(any(test, feature = "sns-host"))]
use crate::hex::is_canonical_lowercase_hex;
use crate::sns::report::SnsReportContext;
use serde::{Deserialize as SerdeDeserialize, Serialize};

///
/// SnsVersion
///
/// Native six-role SNS Wasm version represented as lowercase hexadecimal hashes.
///

#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct SnsVersion {
    /// Archive Wasm hash.
    pub archive_wasm_hash_hex: String,
    /// Root Wasm hash.
    pub root_wasm_hash_hex: String,
    /// Swap Wasm hash.
    pub swap_wasm_hash_hex: String,
    /// Ledger Wasm hash.
    pub ledger_wasm_hash_hex: String,
    /// Governance Wasm hash.
    pub governance_wasm_hash_hex: String,
    /// Ledger index Wasm hash.
    pub index_wasm_hash_hex: String,
}

#[cfg(any(test, feature = "sns-host"))]
impl SnsVersion {
    pub(in crate::sns::report) fn validate_hashes(&self, field: &str) -> Result<(), String> {
        for (role, hash) in [
            ("archive", self.archive_wasm_hash_hex.as_str()),
            ("root", self.root_wasm_hash_hex.as_str()),
            ("swap", self.swap_wasm_hash_hex.as_str()),
            ("ledger", self.ledger_wasm_hash_hex.as_str()),
            ("governance", self.governance_wasm_hash_hex.as_str()),
            ("index", self.index_wasm_hash_hex.as_str()),
        ] {
            if !is_canonical_lowercase_hex(hash) {
                return Err(format!(
                    "{field}.{role}_wasm_hash_hex is not lowercase even-length hexadecimal text"
                ));
            }
        }
        Ok(())
    }
}

///
/// SnsPendingUpgrade
///
/// Native pending-upgrade state reported by SNS Governance.
///

#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct SnsPendingUpgrade {
    /// Native deadline after which Governance may mark the upgrade failed.
    pub mark_failed_at_seconds: u64,
    /// Native Governance upgrade-lock checking value.
    pub checking_upgrade_lock: u64,
    /// NNS proposal that initiated the pending upgrade.
    pub proposal_id: u64,
    /// Pending target version, when Governance returned it.
    pub target_version: Option<SnsVersion>,
}

///
/// SnsUpgradeQueryGap
///
/// Failed next-version query retained after deployed-version collection succeeded.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct SnsUpgradeQueryGap {
    /// Native SNS-W method that failed.
    pub method: SnsCanisterMethod,
    /// Transport, encoding, or decoding failure retained for diagnostics.
    pub reason: String,
}

///
/// SnsUpgradeReport
///
/// Bounded live report of one SNS deployed, pending, and next blessed version.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct SnsUpgradeReport {
    /// Report schema version.
    pub schema_version: u32,
    /// SNS identity and provenance, serialized as flat report fields.
    #[serde(flatten)]
    pub context: SnsReportContext,
    /// Native Governance running-version method.
    pub running_version_method: SnsCanisterMethod,
    /// Native SNS-W next-version method.
    pub next_version_method: SnsCanisterMethod,
    /// Whether both component responses represent one authoritative point in time.
    pub point_in_time_guaranteed: bool,
    /// Fixed number of bounded upgrade component queries attempted.
    pub component_query_count: usize,
    /// Number of component queries that returned successfully.
    pub successful_component_query_count: usize,
    /// Number of retained next-version query gaps.
    pub component_gap_count: usize,
    /// Governance-reported deployed SNS version.
    pub deployed_version: SnsVersion,
    /// Governance-reported pending upgrade, when present.
    pub pending_upgrade: Option<SnsPendingUpgrade>,
    /// Next blessed SNS-W version, or `None` when no successor exists.
    pub next_version: Option<SnsVersion>,
    /// Failed next-version query, distinct from a successful response with no successor.
    pub next_version_gap: Option<SnsUpgradeQueryGap>,
}

#[cfg(test)]
mod tests;