ic_query/ic/model/reports.rs
1//! Module: ic::model::reports
2//!
3//! Responsibility: public serialized Dashboard report, row, and provenance contracts.
4//! Does not own: requests, host source data, errors, transport, or projection.
5//! Boundary: preserves raw Dashboard values and explicit off-chain provenance.
6
7use super::requests::{
8 IcCanisterFilters, IcDailyStatsQuery, IcIcrcTotalSupplyQuery, IcMetricQuery,
9};
10use serde::Serialize;
11
12///
13/// IcCanisterUpgrade
14///
15/// One proposal-linked canister upgrade recorded by the Dashboard API.
16///
17
18#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
19pub struct IcCanisterUpgrade {
20 /// Proposal execution time as raw Unix seconds.
21 pub executed_timestamp_seconds: u64,
22 /// Wasm module hash as raw lowercase hexadecimal text.
23 pub module_hash: String,
24 /// NNS proposal that installed this module.
25 pub proposal_id: u64,
26}
27
28///
29/// IcDashboardReportProvenance
30///
31/// Shared off-chain provenance and authority guarantees for Dashboard reports.
32///
33
34#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
35pub struct IcDashboardReportProvenance {
36 /// Report schema version.
37 pub schema_version: u32,
38 /// Network represented by the official Dashboard API.
39 pub network: String,
40 /// Authority that supplied the report fields.
41 pub authority: String,
42 /// Dashboard API base endpoint queried by the source.
43 pub source_endpoint: String,
44 /// Time this report was collected.
45 pub fetched_at: String,
46 /// Collector identity.
47 pub fetched_by: String,
48 /// Whether the API response is cryptographically certified IC state.
49 pub certified: bool,
50 /// Whether every returned value is guaranteed to describe one point in time.
51 pub point_in_time_guaranteed: bool,
52}
53
54///
55/// IcMetricObservation
56///
57/// One raw timestamp and value returned by the Dashboard Metrics API.
58///
59
60#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
61pub struct IcMetricObservation {
62 /// Observation timestamp as Unix seconds.
63 pub timestamp_unix_secs: u64,
64 /// Raw value string returned by the Dashboard.
65 pub value: String,
66}
67
68///
69/// IcMetricSeries
70///
71/// One named raw series in a Dashboard metric response.
72///
73
74#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
75pub struct IcMetricSeries {
76 /// Raw Dashboard response field that names this series.
77 pub name: String,
78 /// Observations in strictly increasing timestamp order.
79 pub observations: Vec<IcMetricObservation>,
80}
81
82///
83/// IcMetricReport
84///
85/// One bounded time-series response from the official Dashboard Metrics API.
86///
87
88#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
89pub struct IcMetricReport {
90 /// Shared Dashboard provenance, flattened in serialized report JSON.
91 #[serde(flatten)]
92 pub provenance: IcDashboardReportProvenance,
93 /// Metric and explicit time-series bounds, flattened in report JSON.
94 #[serde(flatten)]
95 pub query: IcMetricQuery,
96 /// Number of named series returned by the API.
97 pub returned_series_count: usize,
98 /// Total number of observations across all returned series.
99 pub returned_observation_count: usize,
100 /// Raw named time series in canonical series-name order.
101 pub series: Vec<IcMetricSeries>,
102}
103
104///
105/// IcIcrcTotalSupplyObservation
106///
107/// One raw ICRC ledger total-supply observation returned by the Dashboard API.
108///
109
110#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
111pub struct IcIcrcTotalSupplyObservation {
112 /// Observation timestamp as Unix seconds.
113 pub timestamp_unix_secs: u64,
114 /// Raw total supply in ledger base units.
115 pub total_supply_base_units: String,
116}
117
118///
119/// IcIcrcTotalSupplyReport
120///
121/// One bounded total-supply series from the official Dashboard ICRC API.
122///
123
124#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
125pub struct IcIcrcTotalSupplyReport {
126 /// Shared Dashboard provenance, flattened in serialized report JSON.
127 #[serde(flatten)]
128 pub provenance: IcDashboardReportProvenance,
129 /// Canonical ICRC ledger canister principal requested from the API.
130 pub ledger_canister_id: String,
131 /// Exact requested time bounds, flattened in report JSON.
132 #[serde(flatten)]
133 pub query: IcIcrcTotalSupplyQuery,
134 /// Maximum observations implied by the requested inclusive window.
135 pub requested_observation_limit: u64,
136 /// Number of observations returned by the API.
137 pub returned_observation_count: usize,
138 /// Raw observations in strictly increasing timestamp order.
139 pub observations: Vec<IcIcrcTotalSupplyObservation>,
140}
141
142///
143/// IcDailyStatsRow
144///
145/// Selected raw daily network-activity values returned by the Dashboard API.
146///
147
148#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
149pub struct IcDailyStatsRow {
150 /// Raw UTC calendar day returned by the Dashboard.
151 pub day: String,
152 /// Observation timestamp as Unix seconds.
153 pub timestamp_unix_secs: u64,
154 /// Raw average query-transaction rate.
155 pub average_query_transactions_per_second: String,
156 /// Raw average update-transaction rate.
157 pub average_update_transactions_per_second: String,
158 /// Raw average total-transaction rate.
159 pub average_transactions_per_second: String,
160 /// Raw maximum query-transaction rate.
161 pub max_query_transactions_per_second: String,
162 /// Raw maximum update-transaction rate.
163 pub max_update_transactions_per_second: String,
164 /// Raw maximum total-transaction rate.
165 pub max_total_transactions_per_second: String,
166 /// Raw average block-production rate.
167 pub blocks_per_second_average: String,
168}
169
170///
171/// IcDailyStatsReport
172///
173/// One bounded daily network-activity response from the official Dashboard API.
174///
175
176#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
177pub struct IcDailyStatsReport {
178 /// Shared Dashboard provenance, flattened in serialized report JSON.
179 #[serde(flatten)]
180 pub provenance: IcDashboardReportProvenance,
181 /// Exact requested time bounds, flattened in report JSON.
182 #[serde(flatten)]
183 pub query: IcDailyStatsQuery,
184 /// Number of daily rows returned by the API.
185 pub returned_day_count: usize,
186 /// Rows in strictly increasing timestamp order.
187 pub rows: Vec<IcDailyStatsRow>,
188}
189
190///
191/// IcBoundaryNodeDataCenterRow
192///
193/// One raw data-center aggregate returned by the boundary-node API.
194///
195
196#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
197pub struct IcBoundaryNodeDataCenterRow {
198 /// Dashboard data-center identifier.
199 pub dc_id: String,
200 /// Raw data-center display name.
201 pub name: String,
202 /// Raw infrastructure-owner label.
203 pub owner: String,
204 /// Raw Dashboard region label.
205 pub region: String,
206 /// Raw decimal latitude.
207 pub latitude: String,
208 /// Raw decimal longitude.
209 pub longitude: String,
210 /// Raw decimal count of boundary nodes assigned to this data center.
211 pub total_nodes: String,
212}
213
214///
215/// IcBoundaryNodeDataCentersReport
216///
217/// One complete response from the official boundary-node data-center resource.
218///
219
220#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
221pub struct IcBoundaryNodeDataCentersReport {
222 /// Shared Dashboard provenance, flattened in serialized report JSON.
223 #[serde(flatten)]
224 pub provenance: IcDashboardReportProvenance,
225 /// Number of data-center rows returned by the API.
226 pub data_center_count: usize,
227 /// Sum of the raw per-data-center boundary-node counts.
228 pub total_node_count: u64,
229 /// Rows in canonical data-center-id order, including zero-node locations.
230 pub rows: Vec<IcBoundaryNodeDataCenterRow>,
231}
232
233///
234/// IcCanisterReport
235///
236/// One live canister metadata report from the official Dashboard API.
237///
238
239#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
240pub struct IcCanisterReport {
241 /// Shared Dashboard provenance, flattened in serialized report JSON.
242 #[serde(flatten)]
243 pub provenance: IcDashboardReportProvenance,
244 /// Canonical canister principal.
245 pub canister_id: String,
246 /// Dashboard database row identifier.
247 pub dashboard_id: u64,
248 /// Raw optional Dashboard canister classification.
249 pub canister_type: Option<String>,
250 /// Raw Dashboard canister name; an empty string means no name was recorded.
251 pub name: String,
252 /// Canonical Subnet principal recorded by the Dashboard.
253 pub subnet_id: String,
254 /// Canonically ordered controller principals recorded by the Dashboard.
255 pub controllers: Vec<String>,
256 /// Raw Dashboard language label; an empty string means no language was recorded.
257 pub language: String,
258 /// Raw current module hash; an empty string means no hash was recorded.
259 pub module_hash: String,
260 /// Raw Dashboard row update timestamp.
261 pub dashboard_updated_at: String,
262 /// Number of proposal-linked upgrades when history is available.
263 pub upgrade_count: Option<usize>,
264 /// Proposal-linked upgrade history, or `None` when the Dashboard returned `null`.
265 pub upgrades: Option<Vec<IcCanisterUpgrade>>,
266}
267
268///
269/// IcCanisterCountReport
270///
271/// One filtered canister count from the official Dashboard API.
272///
273
274#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
275pub struct IcCanisterCountReport {
276 /// Shared Dashboard provenance, flattened in serialized report JSON.
277 #[serde(flatten)]
278 pub provenance: IcDashboardReportProvenance,
279 /// Filters applied by the Dashboard.
280 pub filters: IcCanisterFilters,
281 /// Number of matching Dashboard canister records.
282 pub total: u64,
283}
284
285///
286/// IcCanisterPageController
287///
288/// One controller entry returned by the Dashboard canister collection API.
289///
290
291#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
292pub struct IcCanisterPageController {
293 /// Canonical controller principal.
294 pub principal_id: String,
295 /// Raw optional Dashboard metadata associated with the controller.
296 pub raw_metadata: Option<String>,
297}
298
299///
300/// IcCanisterPageRow
301///
302/// One discovery row from a bounded Dashboard canister page.
303///
304
305#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
306pub struct IcCanisterPageRow {
307 /// Canonical canister principal.
308 pub canister_id: String,
309 /// Dashboard database row identifier.
310 pub dashboard_id: u64,
311 /// Raw optional Dashboard canister classification.
312 pub canister_type: Option<String>,
313 /// Raw Dashboard canister name.
314 pub name: String,
315 /// Canonical Subnet principal recorded by the Dashboard.
316 pub subnet_id: String,
317 /// Canonically ordered controller entries recorded by the Dashboard.
318 pub controllers: Vec<IcCanisterPageController>,
319 /// Raw Dashboard language label.
320 pub language: String,
321 /// Raw current module hash.
322 pub module_hash: String,
323 /// Raw Dashboard row update timestamp.
324 pub dashboard_updated_at: String,
325}
326
327///
328/// IcCanisterPageReport
329///
330/// One explicitly bounded page from the official Dashboard canister collection.
331///
332
333#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
334pub struct IcCanisterPageReport {
335 /// Shared Dashboard provenance, flattened in serialized report JSON.
336 #[serde(flatten)]
337 pub provenance: IcDashboardReportProvenance,
338 /// Filters applied by the Dashboard.
339 pub filters: IcCanisterFilters,
340 /// Maximum rows requested from the API.
341 pub requested_limit: u16,
342 /// Number of rows returned in this report.
343 pub returned_count: usize,
344 /// Exclusive forward cursor supplied to this request.
345 pub after: Option<String>,
346 /// Exclusive backward cursor supplied to this request.
347 pub before: Option<String>,
348 /// Cursor for an explicit request for the preceding page.
349 pub previous_cursor: Option<String>,
350 /// Cursor for an explicit request for the following page.
351 pub next_cursor: Option<String>,
352 /// Canister discovery rows in Dashboard canister-id order.
353 pub rows: Vec<IcCanisterPageRow>,
354}