ic_agent/agent/
subnet.rs

1//! Information about IC subnets.
2//!
3//! Fetch subnet information via [`Agent::fetch_subnet_by_id`](crate::Agent::fetch_subnet_by_id) or
4//! [`Agent::get_subnet_by_canister`](crate::Agent::get_subnet_by_canister).
5
6use std::{collections::HashMap, ops::RangeInclusive};
7
8use candid::Principal;
9use rangemap::RangeInclusiveSet;
10
11/// The type of an IC subnet, as reported in the state tree under `/subnet/<subnet_id>/type`.
12///
13/// This leaf is present for certification version V25 and higher.
14#[derive(Clone, Debug, PartialEq, Eq)]
15pub enum SubnetType {
16    /// The NNS subnet and other system-level subnets.
17    System,
18    /// A standard application subnet.
19    Application,
20    /// A verified application subnet.
21    VerifiedApplication,
22    /// An unrecognized subnet type string, preserved for forward compatibility.
23    Unknown(String),
24}
25
26/// Information about a subnet, including its public key, member nodes, and assigned canister ranges.
27///
28/// Range information may be incomplete depending on how the subnet was fetched. The lack of a canister ID
29/// within assigned ranges should not be treated immediately as an authorization failure without fetching
30/// fresh data with [`Agent::fetch_subnet_by_canister`](crate::Agent::fetch_subnet_by_canister).
31#[derive(Debug, Clone)]
32pub struct Subnet {
33    pub(crate) id: Principal,
34    // This key is just fetched for completeness. Do not actually use this value as it is not authoritative in case of a rogue subnet.
35    // If a future agent needs to know the subnet key then it should fetch /subnet from the *root* subnet.
36    pub(crate) key: Vec<u8>,
37    pub(crate) node_keys: HashMap<Principal, Vec<u8>>,
38    pub(crate) canister_ranges: RangeInclusiveSet<Principal>,
39    /// Present when the certificate's version is V25 or higher; `None` for older certificates.
40    pub(crate) subnet_type: Option<SubnetType>,
41}
42
43impl Subnet {
44    /// Checks whether the given canister ID is contained within the subnet's assigned canister ranges.
45    pub fn contains_canister(&self, canister_id: &Principal) -> bool {
46        self.canister_ranges.contains(canister_id)
47    }
48    /// Returns an iterator over the known canister ID ranges assigned to this subnet.
49    pub fn iter_canister_ranges(&self) -> CanisterRangesIter<'_> {
50        CanisterRangesIter {
51            inner: self.canister_ranges.iter(),
52        }
53    }
54    /// Returns the self-reported public key of the subnet.
55    ///
56    /// Note that this key is not authoritative if the subnet is rogue.
57    pub fn self_reported_key(&self) -> &[u8] {
58        &self.key
59    }
60    /// Checks whether the given node ID is a member of this subnet.
61    pub fn contains_node(&self, node_id: &Principal) -> bool {
62        self.node_keys.contains_key(node_id)
63    }
64    /// Returns the public key of the given node ID, if it is a member of this subnet.
65    pub fn get_node_key(&self, node_id: &Principal) -> Option<&[u8]> {
66        self.node_keys.get(node_id).map(|k| &k[..])
67    }
68    /// Returns an iterator over the nodes in this subnet.
69    pub fn iter_nodes(&self) -> SubnetNodeIter<'_> {
70        SubnetNodeIter {
71            inner: self.node_keys.keys(),
72        }
73    }
74    /// Returns an iterator over the node IDs and their corresponding public keys in this subnet.
75    pub fn iter_node_keys(&self) -> SubnetKeysIter<'_> {
76        SubnetKeysIter {
77            inner: self.node_keys.iter(),
78        }
79    }
80    /// Returns the subnet's ID.
81    pub fn id(&self) -> Principal {
82        self.id
83    }
84    /// Returns the subnet type if it was present in the state tree certificate.
85    ///
86    /// This is populated when the replica uses certification version V25 or higher.
87    /// Returns `None` for older certificates that do not include the `type` leaf.
88    pub fn subnet_type(&self) -> Option<&SubnetType> {
89        self.subnet_type.as_ref()
90    }
91}
92
93/// Iterator over the canister ID ranges assigned to a subnet.
94pub struct CanisterRangesIter<'a> {
95    inner: rangemap::inclusive_set::Iter<'a, Principal>,
96}
97
98impl Iterator for CanisterRangesIter<'_> {
99    type Item = RangeInclusive<Principal>;
100
101    fn next(&mut self) -> Option<Self::Item> {
102        self.inner.next().cloned()
103    }
104}
105
106/// Iterator over the node IDs in a subnet.
107#[derive(Debug)]
108pub struct SubnetNodeIter<'a> {
109    inner: std::collections::hash_map::Keys<'a, Principal, Vec<u8>>,
110}
111
112impl<'a> Iterator for SubnetNodeIter<'a> {
113    type Item = Principal;
114
115    fn next(&mut self) -> Option<Self::Item> {
116        self.inner.next().copied()
117    }
118}
119
120/// Iterator over the node IDs and their corresponding public keys in a subnet.
121#[derive(Debug)]
122pub struct SubnetKeysIter<'a> {
123    inner: std::collections::hash_map::Iter<'a, Principal, Vec<u8>>,
124}
125
126impl<'a> Iterator for SubnetKeysIter<'a> {
127    type Item = (Principal, &'a [u8]);
128
129    fn next(&mut self) -> Option<Self::Item> {
130        self.inner.next().map(|(k, v)| (*k, &v[..]))
131    }
132}
ic_agent/agent/subnet.rs

ic_agent/agent/
subnet.rs
