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/// IcIcrcHolderCountReport
144///
145/// One current holder count from the official Dashboard ICRC API.
146///
147
148#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
149pub struct IcIcrcHolderCountReport {
150 /// Shared Dashboard provenance, flattened in serialized report JSON.
151 #[serde(flatten)]
152 pub provenance: IcDashboardReportProvenance,
153 /// Canonical ICRC ledger canister principal requested from the API.
154 pub ledger_canister_id: String,
155 /// Number of holder rows currently represented by the Dashboard index.
156 pub total: u64,
157}
158
159///
160/// IcDailyStatsRow
161///
162/// Selected raw daily network-activity values returned by the Dashboard API.
163///
164
165#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
166pub struct IcDailyStatsRow {
167 /// Raw UTC calendar day returned by the Dashboard.
168 pub day: String,
169 /// Observation timestamp as Unix seconds.
170 pub timestamp_unix_secs: u64,
171 /// Raw average query-transaction rate.
172 pub average_query_transactions_per_second: String,
173 /// Raw average update-transaction rate.
174 pub average_update_transactions_per_second: String,
175 /// Raw average total-transaction rate.
176 pub average_transactions_per_second: String,
177 /// Raw maximum query-transaction rate.
178 pub max_query_transactions_per_second: String,
179 /// Raw maximum update-transaction rate.
180 pub max_update_transactions_per_second: String,
181 /// Raw maximum total-transaction rate.
182 pub max_total_transactions_per_second: String,
183 /// Raw average block-production rate.
184 pub blocks_per_second_average: String,
185}
186
187///
188/// IcDailyStatsReport
189///
190/// One bounded daily network-activity response from the official Dashboard API.
191///
192
193#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
194pub struct IcDailyStatsReport {
195 /// Shared Dashboard provenance, flattened in serialized report JSON.
196 #[serde(flatten)]
197 pub provenance: IcDashboardReportProvenance,
198 /// Exact requested time bounds, flattened in report JSON.
199 #[serde(flatten)]
200 pub query: IcDailyStatsQuery,
201 /// Number of daily rows returned by the API.
202 pub returned_day_count: usize,
203 /// Rows in strictly increasing timestamp order.
204 pub rows: Vec<IcDailyStatsRow>,
205}
206
207///
208/// IcBoundaryNodeDataCenterRow
209///
210/// One raw data-center aggregate returned by the boundary-node API.
211///
212
213#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
214pub struct IcBoundaryNodeDataCenterRow {
215 /// Dashboard data-center identifier.
216 pub dc_id: String,
217 /// Raw data-center display name.
218 pub name: String,
219 /// Raw infrastructure-owner label.
220 pub owner: String,
221 /// Raw Dashboard region label.
222 pub region: String,
223 /// Raw decimal latitude.
224 pub latitude: String,
225 /// Raw decimal longitude.
226 pub longitude: String,
227 /// Raw decimal count of boundary nodes assigned to this data center.
228 pub total_nodes: String,
229}
230
231///
232/// IcBoundaryNodeDataCentersReport
233///
234/// One complete response from the official boundary-node data-center resource.
235///
236
237#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
238pub struct IcBoundaryNodeDataCentersReport {
239 /// Shared Dashboard provenance, flattened in serialized report JSON.
240 #[serde(flatten)]
241 pub provenance: IcDashboardReportProvenance,
242 /// Number of data-center rows returned by the API.
243 pub data_center_count: usize,
244 /// Sum of the raw per-data-center boundary-node counts.
245 pub total_node_count: u64,
246 /// Rows in canonical data-center-id order, including zero-node locations.
247 pub rows: Vec<IcBoundaryNodeDataCenterRow>,
248}
249
250///
251/// IcCanisterReport
252///
253/// One live canister metadata report from the official Dashboard API.
254///
255
256#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
257pub struct IcCanisterReport {
258 /// Shared Dashboard provenance, flattened in serialized report JSON.
259 #[serde(flatten)]
260 pub provenance: IcDashboardReportProvenance,
261 /// Canonical canister principal.
262 pub canister_id: String,
263 /// Dashboard database row identifier.
264 pub dashboard_id: u64,
265 /// Raw optional Dashboard canister classification.
266 pub canister_type: Option<String>,
267 /// Raw Dashboard canister name; an empty string means no name was recorded.
268 pub name: String,
269 /// Canonical Subnet principal recorded by the Dashboard.
270 pub subnet_id: String,
271 /// Canonically ordered controller principals recorded by the Dashboard.
272 pub controllers: Vec<String>,
273 /// Raw Dashboard language label; an empty string means no language was recorded.
274 pub language: String,
275 /// Raw current module hash; an empty string means no hash was recorded.
276 pub module_hash: String,
277 /// Raw Dashboard row update timestamp.
278 pub dashboard_updated_at: String,
279 /// Number of proposal-linked upgrades when history is available.
280 pub upgrade_count: Option<usize>,
281 /// Proposal-linked upgrade history, or `None` when the Dashboard returned `null`.
282 pub upgrades: Option<Vec<IcCanisterUpgrade>>,
283}
284
285///
286/// IcCanisterCountReport
287///
288/// One filtered canister count from the official Dashboard API.
289///
290
291#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
292pub struct IcCanisterCountReport {
293 /// Shared Dashboard provenance, flattened in serialized report JSON.
294 #[serde(flatten)]
295 pub provenance: IcDashboardReportProvenance,
296 /// Filters applied by the Dashboard.
297 pub filters: IcCanisterFilters,
298 /// Number of matching Dashboard canister records.
299 pub total: u64,
300}
301
302///
303/// IcCanisterPageController
304///
305/// One controller entry returned by the Dashboard canister collection API.
306///
307
308#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
309pub struct IcCanisterPageController {
310 /// Canonical controller principal.
311 pub principal_id: String,
312 /// Raw optional Dashboard metadata associated with the controller.
313 pub raw_metadata: Option<String>,
314}
315
316///
317/// IcCanisterPageRow
318///
319/// One discovery row from a bounded Dashboard canister page.
320///
321
322#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
323pub struct IcCanisterPageRow {
324 /// Canonical canister principal.
325 pub canister_id: String,
326 /// Dashboard database row identifier.
327 pub dashboard_id: u64,
328 /// Raw optional Dashboard canister classification.
329 pub canister_type: Option<String>,
330 /// Raw Dashboard canister name.
331 pub name: String,
332 /// Canonical Subnet principal recorded by the Dashboard.
333 pub subnet_id: String,
334 /// Canonically ordered controller entries recorded by the Dashboard.
335 pub controllers: Vec<IcCanisterPageController>,
336 /// Raw Dashboard language label.
337 pub language: String,
338 /// Raw current module hash.
339 pub module_hash: String,
340 /// Raw Dashboard row update timestamp.
341 pub dashboard_updated_at: String,
342}
343
344///
345/// IcCanisterPageReport
346///
347/// One explicitly bounded page from the official Dashboard canister collection.
348///
349
350#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
351pub struct IcCanisterPageReport {
352 /// Shared Dashboard provenance, flattened in serialized report JSON.
353 #[serde(flatten)]
354 pub provenance: IcDashboardReportProvenance,
355 /// Filters applied by the Dashboard.
356 pub filters: IcCanisterFilters,
357 /// Maximum rows requested from the API.
358 pub requested_limit: u16,
359 /// Number of rows returned in this report.
360 pub returned_count: usize,
361 /// Exclusive forward cursor supplied to this request.
362 pub after: Option<String>,
363 /// Exclusive backward cursor supplied to this request.
364 pub before: Option<String>,
365 /// Cursor for an explicit request for the preceding page.
366 pub previous_cursor: Option<String>,
367 /// Cursor for an explicit request for the following page.
368 pub next_cursor: Option<String>,
369 /// Canister discovery rows in Dashboard canister-id order.
370 pub rows: Vec<IcCanisterPageRow>,
371}