feat: Add subnet_metrics management canister endpoint

[Dfinity-Bjoern]

Implements the EXPERIMENTAL subnet_metrics management canister endpoint specified in dfinity/developer-docs#333.

type subnet_metrics_args = record { subnet_id : principal };

type subnet_metrics_result = record {
    block_height : nat;
    num_canisters : nat;
    canister_state_bytes : nat;
    consumed_cycles_total : nat;
    update_transactions_total : nat;
};

Canister-callable only; not reachable via ingress. subnet_id may name any subnet — routing delivers the call to the named subnet, so the args.subnet_id == own_subnet_id check mirrors node_metrics_history and does not block cross-subnet calls. It guards the NNS direct-subnet-addressing path, where a call can reach subnet A while naming subnet B and would otherwise be answered with subnet A's metrics.

Four of the five values were previously readable only by external users via the certified state tree at /subnet/<subnet_id>/metrics, which canisters cannot read. block_height is genuinely new: it is current_round, already deterministic at execution time — the same value vetkd_derive_key commits to replicated state today.

No replicated-state, protobuf, or certification-version change. No Cargo.toml or Bazel change.

Design points worth reviewer attention

The instruction charge is keyed on hot_len(), not num_canisters(). total_consumed_cycles() folds over hot canisters only, and hot_len() << len() is the steady state, so keying on the total over-charges ~41× at 100k canisters. That does not protect the subnet — it lets ~61 calls/round pin the entire shared 250M subnet-message budget and defer install_code / upload_chunk / snapshot traffic, for roughly $3.5/day, from a canister with no foothold on the target subnet. Priced against the already-enabled fetch_canister_logs (2.4 cycles per round-instruction of budget consumed), the hot-keyed endpoint costs an attacker 3.6. subnet_metrics_charge_ignores_cold_canisters fails if this regresses.

hot_len() is the first partition-cardinality input to execution. That makes the unconditional repartition_canister_states() call in commit_and_certify a correctness requirement rather than an optimisation — moving it inside the CertificationScope::Metadata branch would diverge the charge across replicas. Determinism rests on four legs: is_cold() is time-independent; the partition is never serialized (every load path derives it via CanisterStates::new); repartitioning is unconditional at commit, so committed equals derived at every height; and all four state-acquisition paths therefore agree. hot_cold_partition_is_canonical_after_every_commit guards the coupling.

consumed_cycles_total uses the corrected V29 computation. CURRENT_CERTIFICATION_VERSION is V27, so the certified state tree still reports the legacy double-counting value and the two will disagree until V29 becomes current. This was a deliberate choice: report the correct number from day one rather than bake a known bug into a new interface.

canister_state_bytes is read from the stored field, never recomputed. The stored value refreshes only every 10 rounds by design, so a live recomputation would disagree with the state tree on 9 rounds out of 10.

validate_cold_stats() alerts; it does not enforce. validate_eq_checkpoint discards the error and the checkpoint still finalizes, with detection lagging a checkpoint interval. It is a strict improvement — ColdStats is already consensus-critical today via cold_stats.memory_usage → canister_state_bytes, with no check at all — but it should be described as detection, not prevention.

Verification

cargo check --all-targets clean; cargo fmt -- --check exit 0; targeted clippy with --deny warnings clean apart from three pre-existing unused_imports. Roughly 80 of the 464 depth-2 Bazel targets run, including both candid_equality targets and all subnet_metrics unit tests. Candid fixtures verified byte-identical to the spec in both crates.

Not verified locally, and needing CI:

• The five system tests in rs/tests/execution/general_execution_tests/api_tests.rs are Linux-only and have never been compiled. This includes the cross-subnet test — the spec's headline capability — and the composite-query rejection test. Symbols were hand-checked; CI is their first real check.
• ./ci/scripts/rust-lint.sh could not complete: its clippy step is --all-features --workspace, which hits a pre-existing break at rs/types/management_canister_types/src/lib.rs:2431 unrelated to this change.
• //rs/state_manager:state_manager_integration / lsmt_merge_overhead fails, reproduced identically on a clean tree.
• The end_to_end benchmark group was not measured, so the 100K base constant is estimated from the handler's fixed work rather than measured. It errs generous. A suggested pass line for a future run is ≤ 50 µs/call.

Follow-ups, out of scope here

ic-cdk and Motoko bindings; optionally adding block_height to the state tree so external users get it in certified form; consensus sign-off on introducing a block-height concept to the interface spec.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Implements the experimental subnet_metrics management canister endpoint across the IC execution stack (routing, permissions, metering, and state access), plus adds unit/system tests and benchmarks to pin determinism and cost-model behavior.

Changes:

• Adds SubnetMetrics as a new management canister method with canister-callable-only enforcement and composite-query rejection.
• Implements execution logic returning subnet metrics (including block_height) with round-instruction charging keyed to hot_len().
• Adds broad regression coverage (execution env, state manager/checkpoint validation, routing tests, candid fixtures, and criterion benches).

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
rs/types/types/src/messages/inter_canister.rs	Treats SubnetMetrics as having no effective canister id for canister calls.
rs/types/types/src/messages/ingress_messages.rs	Ensures SubnetMetrics is treated as a subnet method (not allowed for ingress).
rs/types/management_canister_types/tests/ic.did	Adds Candid fixture types + service method for subnet_metrics.
rs/types/management_canister_types/tests/candid_equality.rs	Extends candid-equality coverage with subnet_metrics stub.
rs/types/management_canister_types/src/lib.rs	Adds Method::SubnetMetrics and public arg/response Rust types.
rs/tests/execution/general_execution_tests/api_tests.rs	Adds end-to-end system tests for own-subnet, cross-subnet, and query/composite-query failure modes.
rs/tests/execution/general_execution_test.rs	Registers the new subnet_metrics system tests in the execution test group.
rs/test_utilities/execution_environment/src/lib.rs	Exposes and plumbs current_round in the test harness; updates round-instruction special-casing.
rs/state_manager/tests/state_manager.rs	Adds a regression test pinning unconditional repartitioning for deterministic hot_len()-keyed charging.
rs/state_manager/src/lib.rs	Documents why repartition_canister_states() must remain unconditional.
rs/state_manager/src/checkpoint.rs	Adds advisory cold_stats aggregate validation during checkpoint validation and preserves per-canister diagnostics.
rs/replicated_state/src/replicated_state.rs	Strengthens documentation for repartitioning as a correctness requirement (not just an optimization).
rs/replicated_state/src/canister_states/tests.rs	Adds tests for total_consumed_cycles correctness and validate_cold_stats behavior.
rs/replicated_state/src/canister_states.rs	Adds validate_cold_stats() API and documents its advisory validation role.
rs/execution_environment/tests/execution_test.rs	Adds instruction-accounting tests for subnet_metrics (budget respect + hot-vs-total scaling + block height progression).
rs/execution_environment/src/scheduler.rs	Special-cases SubnetMetrics like ListCanisters for round-limit gating and adds instruction-limit selection entry.
rs/execution_environment/src/ic00_permissions.rs	Documents/records that SubnetMetrics bypasses effective-canister-id permission path.
rs/execution_environment/src/execution_environment.rs	Implements SubnetMetrics handler, response construction, and hot-keyed round-instruction charge function.
rs/execution_environment/src/execution_environment_metrics.rs	Extends metrics labeling to include SubnetMetrics.
rs/execution_environment/src/canister_manager/tests.rs	Adds focused unit tests for canister-only access, block height, foreign-subnet rejection, payload decoding, etc.
rs/execution_environment/src/canister_manager.rs	Adds SubnetMetrics to ingress-filter rejection arm for defense in depth.
rs/execution_environment/benches/management_canister/test_canister/src/main.rs	Adds a test-canister helper method to call subnet_metrics for benchmarks.
rs/execution_environment/benches/management_canister/test_canister/candid.did	Updates the benchmark test canister Candid interface with subnet_metrics.
rs/execution_environment/benches/management_canister/subnet_metrics.rs	New benchmarks measuring end-to-end and hot-fold costs for subnet_metrics.
rs/execution_environment/benches/management_canister/main.rs	Registers the new subnet_metrics benchmark module.
rs/embedders/src/wasmtime_embedder/system_api/sandbox_safe_system_state.rs	Allows SubnetMetrics through the system-state-modifications method allowlist.
rs/embedders/src/wasmtime_embedder/system_api/routing.rs	Adds routing for SubnetMetrics (payload subnet) and explicit composite-query rejection + tests.
rs/canonical_state/src/encoding/tests/subnet_metrics.rs	New cross-check ensuring consumed_cycles_total matches canonical encoding at V29.
rs/canonical_state/src/encoding.rs	Registers the new canonical-state subnet-metrics test module.
packages/ic-management-canister-types/tests/ic.did	Updates public-package Candid fixture with subnet_metrics types + service method.
packages/ic-management-canister-types/tests/candid_equality.rs	Adds candid-equality stub method for subnet_metrics.
packages/ic-management-canister-types/src/lib.rs	Adds exported SubnetMetricsArgs / SubnetMetricsResult types (public bindings).
packages/ic-management-canister-types/CHANGELOG.md	Notes addition of subnet_metrics types in the package changelog.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 0e795b7.

Security Overview

• 🔎 Scanned files: 29 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/f5e9d2bb-29a4-4b64-902a-391d65fd8b2d?scanId=e42b5ea2-9d7b-43ab-816a-b246fbe14f56&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type

Relevant files

Enhancement

► packages/ic-management-canister-types/src/lib.rs     + Added SubnetMetricsArgs and SubnetMetricsResult structs and related fields/methods ► packages/ic-management-canister-types/tests/candid_equality.rs     + Added subnet_metrics candid method stubs for testing ► packages/ic-management-canister-types/tests/ic.did     + Extended DID with subnet_metrics types and endpoint ► rs/canonical_state/src/encoding/types.rs     + Updated metrics handling to use consumed_cycles_total_including_canisters for V29+ ► rs/embedders/src/wasmtime_embedder/system_api/routing.rs     + Routing support for SubnetMetrics payloads (SubnetMetricsArgs) and related tests ► rs/embedders/src/wasmtime_embedder/system_api/sandbox_safe_system_state.rs     + Treat SubnetMetrics as a selectable system API in routing guard ► rs/execution_environment/benches/management_canister/main.rs     + Benchmark inclusion for subnet_metrics ► rs/execution_environment/benches/management_canister/subnet_metrics.rs     + New benchmark file for subnet_metrics consumed cycles fold ► rs/execution_environment/src/canister_manager.rs     + Exhaustiveness: treat SubnetMetrics as a possible Ic00Method in match arms ► rs/execution_environment/src/canister_manager/tests.rs     + Tests and helpers for subnet_metrics inter-canister call flow ► rs/execution_environment/src/execution_environment.rs     + SubnetMetrics handling: ingress/execute path and response construction ► rs/execution_environment/src/execution_environment_metrics.rs     + Include SubnetMetrics in allowed ic00 methods for metrics path ► rs/execution_environment/src/ic00_permissions.rs     + Permit SubnetMetrics in Ic00MethodPermissions with special handling ► rs/execution_environment/src/scheduler.rs     + Defer ListCanisters and SubnetMetrics when round limit reached ► rs/execution_environment/tests/execution_test.rs     + Include SubnetMetrics in test scaffolding for Ic00 arguments

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated no new comments.