feat: add read_state_subnet_canister_ranges (#661)

* Add 'read_state_subnet_canister_ranges' which can query the canister id ranges for a given subnet.

* Updated changelog.

* Fixed lint.

Author: vincent-dfinity

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+* Added `read_state_subnet_canister_ranges` which can query the canister id ranges for a given subnet.
+
 ## [0.44.0] - 2025-08-25
 
 * BREAKING: Bump `ic-management-canister-types` to v0.4.0.

ic-agent/src/agent/mod.rs

@@ -45,7 +45,8 @@ mod agent_test;
 use crate::{
     agent::response_authentication::{
         extract_der, lookup_canister_info, lookup_canister_metadata, lookup_request_status,
-        lookup_subnet, lookup_subnet_metrics, lookup_time, lookup_value,
+        lookup_subnet, lookup_subnet_canister_ranges, lookup_subnet_metrics, lookup_time,
+        lookup_value,
     },
     agent_error::TransportError,
     export::Principal,
@@ -1093,6 +1094,20 @@ impl Agent {
         lookup_subnet_metrics(cert, subnet_id)
     }
 
+    /// Request a list of metrics about the subnet.
+    pub async fn read_state_subnet_canister_ranges(
+        &self,
+        subnet_id: Principal,
+    ) -> Result<Vec<(Principal, Principal)>, AgentError> {
+        let paths = vec![vec![
+            "subnet".into(),
+            Label::from_bytes(subnet_id.as_slice()),
+            "canister_ranges".into(),
+        ]];
+        let cert = self.read_subnet_state_raw(paths, subnet_id).await?;
+        lookup_subnet_canister_ranges(cert, subnet_id)
+    }
+
     /// Fetches the status of a particular request by its ID.
     pub async fn request_status_raw(
         &self,

ic-agent/src/agent/response_authentication.rs

@@ -77,6 +77,15 @@ pub(crate) fn lookup_subnet_metrics<Storage: AsRef<[u8]>>(
     Ok(serde_cbor::from_slice(metrics)?)
 }
 
+pub(crate) fn lookup_subnet_canister_ranges<Storage: AsRef<[u8]>>(
+    certificate: Certificate<Storage>,
+    subnet_id: Principal,
+) -> Result<Vec<(Principal, Principal)>, AgentError> {
+    let path_ranges = [b"subnet", subnet_id.as_slice(), b"canister_ranges"];
+    let ranges = lookup_value(&certificate.tree, path_ranges)?;
+    Ok(serde_cbor::from_slice(ranges)?)
+}
+
 pub(crate) fn lookup_request_status<Storage: AsRef<[u8]>>(
     certificate: &Certificate<Storage>,
     request_id: &RequestId,

ref-tests/tests/ic-ref.rs

@@ -938,6 +938,24 @@ mod management_canister {
             Ok(())
         })
     }
+
+    #[ignore]
+    #[test]
+    fn subnet_canister_ranges() {
+        with_agent(|agent| async move {
+            // fetch root subnet canister ranges
+            let ranges = agent
+                .read_state_subnet_canister_ranges(Principal::self_authenticating(
+                    agent.read_root_key(),
+                ))
+                .await?;
+            assert!(
+                !ranges.is_empty(),
+                "expected at least one canister range on the root subnet"
+            );
+            Ok(())
+        })
+    }
 }
 
 mod simple_calls {