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