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, IcIcrcTokenValueQuery,
9    IcIcrcTotalSupplyQuery, IcMetricQuery, IcReplicaVersionListQuery,
10};
11use serde::Serialize;
12use std::fmt;
13
14///
15/// IcCanisterUpgrade
16///
17/// One proposal-linked canister upgrade recorded by the Dashboard API.
18///
19
20#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
21pub struct IcCanisterUpgrade {
22    /// Proposal execution time as raw Unix seconds.
23    pub executed_timestamp_seconds: u64,
24    /// Wasm module hash as raw lowercase hexadecimal text.
25    pub module_hash: String,
26    /// NNS proposal that installed this module.
27    pub proposal_id: u64,
28}
29
30///
31/// IcDashboardReportProvenance
32///
33/// Shared off-chain provenance and authority guarantees for Dashboard reports.
34///
35
36#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
37pub struct IcDashboardReportProvenance {
38    /// Report schema version.
39    pub schema_version: u32,
40    /// Network represented by the official Dashboard API.
41    pub network: String,
42    /// Authority that supplied the report fields.
43    pub authority: String,
44    /// Dashboard API base endpoint queried by the source.
45    pub source_endpoint: String,
46    /// Time this report was collected.
47    pub fetched_at: String,
48    /// Collector identity.
49    pub fetched_by: String,
50    /// Whether the API response is cryptographically certified IC state.
51    pub certified: bool,
52    /// Whether every returned value is guaranteed to describe one point in time.
53    pub point_in_time_guaranteed: bool,
54}
55
56///
57/// IcMetricObservation
58///
59/// One raw timestamp and value returned by the Dashboard Metrics API.
60///
61
62#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
63pub struct IcMetricObservation {
64    /// Observation timestamp as Unix seconds.
65    pub timestamp_unix_secs: u64,
66    /// Raw value string returned by the Dashboard.
67    pub value: String,
68}
69
70///
71/// IcMetricSeries
72///
73/// One named raw series in a Dashboard metric response.
74///
75
76#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
77pub struct IcMetricSeries {
78    /// Raw Dashboard response field that names this series.
79    pub name: String,
80    /// Observations in strictly increasing timestamp order.
81    pub observations: Vec<IcMetricObservation>,
82}
83
84///
85/// IcMetricReport
86///
87/// One bounded time-series response from the official Dashboard Metrics API.
88///
89
90#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
91pub struct IcMetricReport {
92    /// Shared Dashboard provenance, flattened in serialized report JSON.
93    #[serde(flatten)]
94    pub provenance: IcDashboardReportProvenance,
95    /// Metric and explicit time-series bounds, flattened in report JSON.
96    #[serde(flatten)]
97    pub query: IcMetricQuery,
98    /// Number of named series returned by the API.
99    pub returned_series_count: usize,
100    /// Total number of observations across all returned series.
101    pub returned_observation_count: usize,
102    /// Raw named time series in canonical series-name order.
103    pub series: Vec<IcMetricSeries>,
104}
105
106///
107/// IcIcrcTotalSupplyObservation
108///
109/// One raw ICRC ledger total-supply observation returned by the Dashboard API.
110///
111
112#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
113pub struct IcIcrcTotalSupplyObservation {
114    /// Observation timestamp as Unix seconds.
115    pub timestamp_unix_secs: u64,
116    /// Raw total supply in ledger base units.
117    pub total_supply_base_units: String,
118}
119
120///
121/// IcIcrcTotalSupplyReport
122///
123/// One bounded total-supply series from the official Dashboard ICRC API.
124///
125
126#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
127pub struct IcIcrcTotalSupplyReport {
128    /// Shared Dashboard provenance, flattened in serialized report JSON.
129    #[serde(flatten)]
130    pub provenance: IcDashboardReportProvenance,
131    /// Canonical ICRC ledger canister principal requested from the API.
132    pub ledger_canister_id: String,
133    /// Exact requested time bounds, flattened in report JSON.
134    #[serde(flatten)]
135    pub query: IcIcrcTotalSupplyQuery,
136    /// Maximum observations implied by the requested inclusive window.
137    pub requested_observation_limit: u64,
138    /// Number of observations returned by the API.
139    pub returned_observation_count: usize,
140    /// Raw observations in strictly increasing timestamp order.
141    pub observations: Vec<IcIcrcTotalSupplyObservation>,
142}
143
144///
145/// IcIcrcIndexedCountReport
146///
147/// One current scalar count from the official Dashboard ICRC index.
148///
149
150#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
151pub struct IcIcrcIndexedCountReport {
152    /// Shared Dashboard provenance, flattened in serialized report JSON.
153    #[serde(flatten)]
154    pub provenance: IcDashboardReportProvenance,
155    /// Canonical ICRC ledger canister principal requested from the API.
156    pub ledger_canister_id: String,
157    /// Indexed resource represented by this count.
158    pub kind: IcIcrcIndexedCountKind,
159    /// Number of matching resources currently represented by the Dashboard index.
160    pub total: u64,
161}
162
163///
164/// IcIcrcTokenValueRow
165///
166/// One raw externally sourced token-value record returned by the Dashboard API.
167///
168
169#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
170pub struct IcIcrcTokenValueRow {
171    /// Raw legacy price field in USD, when returned.
172    pub price: Option<String>,
173    /// Raw legacy 24-hour volume field in USD, when returned.
174    pub volume_24h: Option<String>,
175    /// Raw explicit price-in-USD field, when returned.
176    pub price_usd: Option<String>,
177    /// Raw explicit 24-hour volume-in-USD field, when returned.
178    pub volume_24h_usd: Option<String>,
179    /// External value provider named by the Dashboard, when returned.
180    pub source: Option<String>,
181    /// External value-provider URL returned by the Dashboard, when present.
182    pub source_url: Option<String>,
183    /// Observation timestamp as Unix seconds.
184    pub timestamp_unix_secs: u64,
185}
186
187///
188/// IcIcrcTokenValueReport
189///
190/// One bounded token-value series from the official Dashboard ICRC API.
191///
192
193#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
194pub struct IcIcrcTokenValueReport {
195    /// Shared Dashboard provenance, flattened in serialized report JSON.
196    #[serde(flatten)]
197    pub provenance: IcDashboardReportProvenance,
198    /// Canonical ICRC ledger canister principal requested from the API.
199    pub ledger_canister_id: String,
200    /// Exact requested time and row bounds, flattened in report JSON.
201    #[serde(flatten)]
202    pub query: IcIcrcTokenValueQuery,
203    /// Number of rows returned by the API.
204    pub returned_row_count: usize,
205    /// Whether the response reached the requested limit and may be truncated.
206    pub limit_reached: bool,
207    /// Raw token-value rows in nondecreasing timestamp order.
208    pub rows: Vec<IcIcrcTokenValueRow>,
209}
210
211///
212/// IcDailyStatsRow
213///
214/// Selected raw daily network-activity values returned by the Dashboard API.
215///
216
217#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
218pub struct IcDailyStatsRow {
219    /// Raw UTC calendar day returned by the Dashboard.
220    pub day: String,
221    /// Observation timestamp as Unix seconds.
222    pub timestamp_unix_secs: u64,
223    /// Raw average query-transaction rate.
224    pub average_query_transactions_per_second: String,
225    /// Raw average update-transaction rate.
226    pub average_update_transactions_per_second: String,
227    /// Raw average total-transaction rate.
228    pub average_transactions_per_second: String,
229    /// Raw maximum query-transaction rate.
230    pub max_query_transactions_per_second: String,
231    /// Raw maximum update-transaction rate.
232    pub max_update_transactions_per_second: String,
233    /// Raw maximum total-transaction rate.
234    pub max_total_transactions_per_second: String,
235    /// Raw average block-production rate.
236    pub blocks_per_second_average: String,
237}
238
239///
240/// IcDailyStatsReport
241///
242/// One bounded daily network-activity response from the official Dashboard API.
243///
244
245#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
246pub struct IcDailyStatsReport {
247    /// Shared Dashboard provenance, flattened in serialized report JSON.
248    #[serde(flatten)]
249    pub provenance: IcDashboardReportProvenance,
250    /// Exact requested time bounds, flattened in report JSON.
251    #[serde(flatten)]
252    pub query: IcDailyStatsQuery,
253    /// Number of daily rows returned by the API.
254    pub returned_day_count: usize,
255    /// Rows in strictly increasing timestamp order.
256    pub rows: Vec<IcDailyStatsRow>,
257}
258
259///
260/// IcBoundaryNodeDataCenterRow
261///
262/// One raw data-center aggregate returned by the boundary-node API.
263///
264
265#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
266pub struct IcBoundaryNodeDataCenterRow {
267    /// Dashboard data-center identifier.
268    pub dc_id: String,
269    /// Raw data-center display name.
270    pub name: String,
271    /// Raw infrastructure-owner label.
272    pub owner: String,
273    /// Raw Dashboard region label.
274    pub region: String,
275    /// Raw decimal latitude.
276    pub latitude: String,
277    /// Raw decimal longitude.
278    pub longitude: String,
279    /// Raw decimal count of boundary nodes assigned to this data center.
280    pub total_nodes: String,
281}
282
283///
284/// IcBoundaryNodeDataCentersReport
285///
286/// One complete response from the official boundary-node data-center resource.
287///
288
289#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
290pub struct IcBoundaryNodeDataCentersReport {
291    /// Shared Dashboard provenance, flattened in serialized report JSON.
292    #[serde(flatten)]
293    pub provenance: IcDashboardReportProvenance,
294    /// Number of data-center rows returned by the API.
295    pub data_center_count: usize,
296    /// Sum of the raw per-data-center boundary-node counts.
297    pub total_node_count: u64,
298    /// Rows in canonical data-center-id order, including zero-node locations.
299    pub rows: Vec<IcBoundaryNodeDataCenterRow>,
300}
301
302///
303/// IcReplicaVersionStatus
304///
305/// Raw lifecycle status exposed by the official Dashboard release index.
306///
307
308#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Serialize)]
309#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
310pub enum IcReplicaVersionStatus {
311    /// The election proposal has been adopted but not executed.
312    Adopted,
313    /// The election proposal has executed.
314    Executed,
315    /// The election proposal remains open.
316    Open,
317}
318
319impl IcReplicaVersionStatus {
320    /// Return the exact official Dashboard query value.
321    #[must_use]
322    pub const fn as_dashboard_value(self) -> &'static str {
323        match self {
324            Self::Adopted => "ADOPTED",
325            Self::Executed => "EXECUTED",
326            Self::Open => "OPEN",
327        }
328    }
329}
330
331impl fmt::Display for IcReplicaVersionStatus {
332    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
333        formatter.write_str(self.as_dashboard_value())
334    }
335}
336
337///
338/// IcReplicaVersionSubnetRollout
339///
340/// One Dashboard-recorded proposal assigning a Subnet to a replica version.
341///
342
343#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
344pub struct IcReplicaVersionSubnetRollout {
345    /// Canonical Subnet principal.
346    pub subnet_id: String,
347    /// NNS proposal that assigned the Subnet to this version.
348    pub proposal_id: u64,
349    /// Proposal execution time as raw Unix seconds.
350    pub executed_timestamp_seconds: u64,
351}
352
353///
354/// IcReplicaVersionListRow
355///
356/// One release-election row from a bounded official Dashboard page.
357///
358
359#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
360pub struct IcReplicaVersionListRow {
361    /// Lowercase hexadecimal replica-version identifier.
362    pub replica_version_id: String,
363    /// NNS proposal that elected this version.
364    pub proposal_id: u64,
365    /// Election proposal execution time, or zero before execution.
366    pub executed_timestamp_seconds: u64,
367    /// Raw Dashboard proposal lifecycle status.
368    pub status: IcReplicaVersionStatus,
369    /// Raw proposal title.
370    pub title: String,
371    /// Raw proposal discussion URL.
372    pub url: String,
373    /// Number of Dashboard-recorded Subnet assignments.
374    pub subnet_count: usize,
375    /// Dashboard-recorded Subnet assignments in execution order.
376    pub subnets: Vec<IcReplicaVersionSubnetRollout>,
377}
378
379///
380/// IcReplicaVersionListReport
381///
382/// One explicitly bounded replica-version page from the official Dashboard API.
383///
384
385#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
386pub struct IcReplicaVersionListReport {
387    /// Shared Dashboard provenance, flattened in serialized report JSON.
388    #[serde(flatten)]
389    pub provenance: IcDashboardReportProvenance,
390    /// Exact requested page bounds, flattened in report JSON.
391    #[serde(flatten)]
392    pub query: IcReplicaVersionListQuery,
393    /// Proposal-index ceiling selected by the Dashboard for this page series.
394    pub resolved_max_proposal_index: u64,
395    /// Number of release records matching the selected proposal-index ceiling.
396    pub total_proposals: u64,
397    /// Number of rows returned in this page.
398    pub returned_count: usize,
399    /// Offset for an explicit next-page request, when more rows remain.
400    pub next_offset: Option<u64>,
401    /// Release rows in the Dashboard's requested descending execution-time order.
402    pub rows: Vec<IcReplicaVersionListRow>,
403}
404
405///
406/// IcReplicaVersionInfoReport
407///
408/// One exact replica-version release record from the official Dashboard API.
409///
410
411#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
412pub struct IcReplicaVersionInfoReport {
413    /// Shared Dashboard provenance, flattened in serialized report JSON.
414    #[serde(flatten)]
415    pub provenance: IcDashboardReportProvenance,
416    /// Lowercase hexadecimal replica-version identifier.
417    pub replica_version_id: String,
418    /// NNS proposal that elected this version.
419    pub proposal_id: u64,
420    /// Election proposal execution time as raw Unix seconds.
421    pub executed_timestamp_seconds: u64,
422    /// Raw proposal title.
423    pub title: String,
424    /// Raw proposal discussion URL.
425    pub url: String,
426    /// Raw release-note summary.
427    pub summary: String,
428    /// Number of Dashboard-recorded Subnet assignments.
429    pub subnet_count: usize,
430    /// Dashboard-recorded Subnet assignments in execution order.
431    pub subnets: Vec<IcReplicaVersionSubnetRollout>,
432}
433
434///
435/// IcCanisterReport
436///
437/// One live canister metadata report from the official Dashboard API.
438///
439
440#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
441pub struct IcCanisterReport {
442    /// Shared Dashboard provenance, flattened in serialized report JSON.
443    #[serde(flatten)]
444    pub provenance: IcDashboardReportProvenance,
445    /// Canonical canister principal.
446    pub canister_id: String,
447    /// Dashboard database row identifier.
448    pub dashboard_id: u64,
449    /// Raw optional Dashboard canister classification.
450    pub canister_type: Option<String>,
451    /// Raw Dashboard canister name; an empty string means no name was recorded.
452    pub name: String,
453    /// Canonical Subnet principal recorded by the Dashboard.
454    pub subnet_id: String,
455    /// Canonically ordered controller principals recorded by the Dashboard.
456    pub controllers: Vec<String>,
457    /// Raw Dashboard language label; an empty string means no language was recorded.
458    pub language: String,
459    /// Raw current module hash; an empty string means no hash was recorded.
460    pub module_hash: String,
461    /// Raw Dashboard row update timestamp.
462    pub dashboard_updated_at: String,
463    /// Number of proposal-linked upgrades when history is available.
464    pub upgrade_count: Option<usize>,
465    /// Proposal-linked upgrade history, or `None` when the Dashboard returned `null`.
466    pub upgrades: Option<Vec<IcCanisterUpgrade>>,
467}
468
469///
470/// IcCanisterCountReport
471///
472/// One filtered canister count from the official Dashboard API.
473///
474
475#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
476pub struct IcCanisterCountReport {
477    /// Shared Dashboard provenance, flattened in serialized report JSON.
478    #[serde(flatten)]
479    pub provenance: IcDashboardReportProvenance,
480    /// Filters applied by the Dashboard.
481    pub filters: IcCanisterFilters,
482    /// Number of matching Dashboard canister records.
483    pub total: u64,
484}
485
486///
487/// IcCanisterPageController
488///
489/// One controller entry returned by the Dashboard canister collection API.
490///
491
492#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
493pub struct IcCanisterPageController {
494    /// Canonical controller principal.
495    pub principal_id: String,
496    /// Raw optional Dashboard metadata associated with the controller.
497    pub raw_metadata: Option<String>,
498}
499
500///
501/// IcCanisterPageRow
502///
503/// One discovery row from a bounded Dashboard canister page.
504///
505
506#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
507pub struct IcCanisterPageRow {
508    /// Canonical canister principal.
509    pub canister_id: String,
510    /// Dashboard database row identifier.
511    pub dashboard_id: u64,
512    /// Raw optional Dashboard canister classification.
513    pub canister_type: Option<String>,
514    /// Raw Dashboard canister name.
515    pub name: String,
516    /// Canonical Subnet principal recorded by the Dashboard.
517    pub subnet_id: String,
518    /// Canonically ordered controller entries recorded by the Dashboard.
519    pub controllers: Vec<IcCanisterPageController>,
520    /// Raw Dashboard language label.
521    pub language: String,
522    /// Raw current module hash.
523    pub module_hash: String,
524    /// Raw Dashboard row update timestamp.
525    pub dashboard_updated_at: String,
526}
527
528///
529/// IcCanisterPageReport
530///
531/// One explicitly bounded page from the official Dashboard canister collection.
532///
533
534#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
535pub struct IcCanisterPageReport {
536    /// Shared Dashboard provenance, flattened in serialized report JSON.
537    #[serde(flatten)]
538    pub provenance: IcDashboardReportProvenance,
539    /// Filters applied by the Dashboard.
540    pub filters: IcCanisterFilters,
541    /// Maximum rows requested from the API.
542    pub requested_limit: u16,
543    /// Number of rows returned in this report.
544    pub returned_count: usize,
545    /// Exclusive forward cursor supplied to this request.
546    pub after: Option<String>,
547    /// Exclusive backward cursor supplied to this request.
548    pub before: Option<String>,
549    /// Cursor for an explicit request for the preceding page.
550    pub previous_cursor: Option<String>,
551    /// Cursor for an explicit request for the following page.
552    pub next_cursor: Option<String>,
553    /// Canister discovery rows in Dashboard canister-id order.
554    pub rows: Vec<IcCanisterPageRow>,
555}
ic_query/ic/model/reports.rs

ic_query/ic/model/
reports.rs
