Skip to main content

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, IcIcrcAccountListQuery, IcIcrcHolderListQuery,
9    IcIcrcIndexedCountKind, IcIcrcTokenValueQuery, IcIcrcTotalSupplyQuery, IcMetricQuery,
10    IcNodeProviderRewardHistoryQuery, IcNodeProviderRewardListQuery, IcReplicaVersionListQuery,
11};
12use serde::Serialize;
13use std::{collections::BTreeMap, fmt};
14
15///
16/// IcCanisterUpgrade
17///
18/// One proposal-linked canister upgrade recorded by the Dashboard API.
19///
20
21#[derive(Clone, Debug, Eq, PartialEq, Serialize, serde::Deserialize)]
22pub struct IcCanisterUpgrade {
23    /// Proposal execution time as raw Unix seconds.
24    pub executed_timestamp_seconds: u64,
25    /// Wasm module hash as raw lowercase hexadecimal text.
26    pub module_hash: String,
27    /// NNS proposal that installed this module.
28    pub proposal_id: u64,
29}
30
31///
32/// IcDashboardReportProvenance
33///
34/// Shared off-chain provenance and authority guarantees for Dashboard reports.
35///
36
37#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
38pub struct IcDashboardReportProvenance {
39    /// Report schema version.
40    pub schema_version: u32,
41    /// Network represented by the official Dashboard API.
42    pub network: String,
43    /// Authority that supplied the report fields.
44    pub authority: String,
45    /// Dashboard API base endpoint queried by the source.
46    pub source_endpoint: String,
47    /// Time this report was collected.
48    pub fetched_at: String,
49    /// Collector identity.
50    pub fetched_by: String,
51    /// Whether the API response is cryptographically certified IC state.
52    pub certified: bool,
53    /// Whether every returned value is guaranteed to describe one point in time.
54    pub point_in_time_guaranteed: bool,
55}
56
57///
58/// IcMetricObservation
59///
60/// One raw timestamp and value returned by the Dashboard Metrics API.
61///
62
63#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
64pub struct IcMetricObservation {
65    /// Observation timestamp as Unix seconds.
66    pub timestamp_unix_secs: u64,
67    /// Raw value string returned by the Dashboard.
68    pub value: String,
69}
70
71///
72/// IcMetricSeries
73///
74/// One named raw series in a Dashboard metric response.
75///
76
77#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
78pub struct IcMetricSeries {
79    /// Raw Dashboard response field that names this series.
80    pub name: String,
81    /// Observations in strictly increasing timestamp order.
82    pub observations: Vec<IcMetricObservation>,
83}
84
85///
86/// IcMetricReport
87///
88/// One bounded time-series response from the official Dashboard Metrics API.
89///
90
91#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
92pub struct IcMetricReport {
93    /// Shared Dashboard provenance, flattened in serialized report JSON.
94    #[serde(flatten)]
95    pub provenance: IcDashboardReportProvenance,
96    /// Metric and explicit time-series bounds, flattened in report JSON.
97    #[serde(flatten)]
98    pub query: IcMetricQuery,
99    /// Raw named time series in canonical series-name order.
100    pub series: Vec<IcMetricSeries>,
101}
102
103///
104/// IcIcrcTotalSupplyObservation
105///
106/// One raw ICRC ledger total-supply observation returned by the Dashboard API.
107///
108
109#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
110pub struct IcIcrcTotalSupplyObservation {
111    /// Observation timestamp as Unix seconds.
112    pub timestamp_unix_secs: u64,
113    /// Raw total supply in ledger base units.
114    pub total_supply_base_units: String,
115}
116
117///
118/// IcIcrcTotalSupplyReport
119///
120/// One bounded total-supply series from the official Dashboard ICRC API.
121///
122
123#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
124pub struct IcIcrcTotalSupplyReport {
125    /// Shared Dashboard provenance, flattened in serialized report JSON.
126    #[serde(flatten)]
127    pub provenance: IcDashboardReportProvenance,
128    /// Canonical ICRC ledger canister principal requested from the API.
129    pub ledger_canister_id: String,
130    /// Exact requested time bounds, flattened in report JSON.
131    #[serde(flatten)]
132    pub query: IcIcrcTotalSupplyQuery,
133    /// Maximum observations implied by the requested inclusive window.
134    pub requested_observation_limit: u64,
135    /// Raw observations in strictly increasing timestamp order.
136    pub observations: Vec<IcIcrcTotalSupplyObservation>,
137}
138
139///
140/// IcIcrcIndexedCountReport
141///
142/// One current scalar count from the official Dashboard ICRC index.
143///
144
145#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
146pub struct IcIcrcIndexedCountReport {
147    /// Shared Dashboard provenance, flattened in serialized report JSON.
148    #[serde(flatten)]
149    pub provenance: IcDashboardReportProvenance,
150    /// Canonical ICRC ledger canister principal requested from the API.
151    pub ledger_canister_id: String,
152    /// Indexed resource represented by this count.
153    pub kind: IcIcrcIndexedCountKind,
154    /// Number of matching resources currently represented by the Dashboard index.
155    pub total: u64,
156}
157
158///
159/// IcIcrcAccountRow
160///
161/// One account record maintained by the official ICRC index.
162///
163
164#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
165pub struct IcIcrcAccountRow {
166    /// Opaque stable account id used for exact API follow-up.
167    pub account_id: String,
168    /// Canonical account owner principal.
169    pub owner: String,
170    /// Raw subaccount text returned by the API; empty denotes the default subaccount.
171    pub subaccount: String,
172    /// Raw current indexed balance in ledger base units.
173    pub balance_base_units: String,
174    /// Number of indexed transactions involving this account.
175    pub total_transactions: u64,
176    /// Account creation timestamp normalized to Unix seconds.
177    pub created_at_unix_secs: u64,
178    /// Nanoseconds below the normalized creation second, preserving upstream precision.
179    pub created_at_subsec_nanos: u32,
180    /// Canonical ledger canister principal carried by the row.
181    pub ledger_canister_id: String,
182    /// Latest indexed transaction involving this account.
183    pub latest_transaction_index: u64,
184    /// Raw Dashboard database update timestamp.
185    pub dashboard_updated_at: String,
186    /// Whether the account is currently classified as an active fee collector.
187    pub active_fee_collector: bool,
188    /// Raw fee-collector block-range arrays returned by the Dashboard.
189    pub fee_collector_block_ranges: Vec<Vec<serde_json::Value>>,
190}
191
192///
193/// IcIcrcAccountListReport
194///
195/// One explicitly bounded account-index page from the official ICRC API.
196///
197
198#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
199pub struct IcIcrcAccountListReport {
200    /// Shared Dashboard provenance, flattened in serialized report JSON.
201    #[serde(flatten)]
202    pub provenance: IcDashboardReportProvenance,
203    /// Canonical ICRC ledger canister principal requested from the API.
204    pub ledger_canister_id: String,
205    /// Exact page query, flattened in report JSON.
206    #[serde(flatten)]
207    pub query: IcIcrcAccountListQuery,
208    /// Opaque cursor for an explicit preceding-page request.
209    pub previous_cursor: Option<String>,
210    /// Opaque cursor for an explicit following-page request.
211    pub next_cursor: Option<String>,
212    /// Account rows in the exact order returned by the API.
213    pub rows: Vec<IcIcrcAccountRow>,
214}
215
216///
217/// IcIcrcAccountInfoReport
218///
219/// One exact account record from the official ICRC API.
220///
221
222#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
223pub struct IcIcrcAccountInfoReport {
224    /// Shared Dashboard provenance, flattened in serialized report JSON.
225    #[serde(flatten)]
226    pub provenance: IcDashboardReportProvenance,
227    /// Exact account record, flattened in serialized report JSON.
228    #[serde(flatten)]
229    pub account: IcIcrcAccountRow,
230}
231
232///
233/// IcIcrcHolderRow
234///
235/// One principal-level holder aggregate maintained by the official ICRC index.
236///
237
238#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
239pub struct IcIcrcHolderRow {
240    /// Canonical holder principal.
241    pub principal: String,
242    /// Raw aggregate balance in ledger base units.
243    pub balance_base_units: String,
244    /// Number of indexed transactions across the holder's accounts.
245    pub total_transactions: u64,
246    /// Earliest indexed account creation timestamp normalized to Unix seconds.
247    pub created_at_unix_secs: u64,
248    /// Nanoseconds below the normalized creation second, preserving upstream precision.
249    pub created_at_subsec_nanos: u32,
250    /// Canonical ledger canister principal carried by the row.
251    pub ledger_canister_id: String,
252    /// Latest indexed transaction across the holder's accounts.
253    pub latest_transaction_index: u64,
254    /// Raw numeric supply percentage returned by the Dashboard.
255    pub percentage: serde_json::Value,
256    /// Raw nullable USD value returned by the Dashboard.
257    pub value_usd: serde_json::Value,
258    /// Raw Dashboard database update timestamp.
259    pub dashboard_updated_at: String,
260}
261
262///
263/// IcIcrcHolderListReport
264///
265/// One explicitly bounded holder-index page from the official ICRC API.
266///
267
268#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
269pub struct IcIcrcHolderListReport {
270    /// Shared Dashboard provenance, flattened in serialized report JSON.
271    #[serde(flatten)]
272    pub provenance: IcDashboardReportProvenance,
273    /// Canonical ICRC ledger canister principal requested from the API.
274    pub ledger_canister_id: String,
275    /// Exact page query, flattened in report JSON.
276    #[serde(flatten)]
277    pub query: IcIcrcHolderListQuery,
278    /// Opaque cursor for an explicit preceding-page request.
279    pub previous_cursor: Option<String>,
280    /// Opaque cursor for an explicit following-page request.
281    pub next_cursor: Option<String>,
282    /// Holder rows in the exact order returned by the API.
283    pub rows: Vec<IcIcrcHolderRow>,
284}
285
286///
287/// IcIcrcTokenValueRow
288///
289/// One raw externally sourced token-value record returned by the Dashboard API.
290///
291
292#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
293pub struct IcIcrcTokenValueRow {
294    /// Raw legacy price field in USD, when returned.
295    pub price: Option<String>,
296    /// Raw legacy 24-hour volume field in USD, when returned.
297    pub volume_24h: Option<String>,
298    /// Raw explicit price-in-USD field, when returned.
299    pub price_usd: Option<String>,
300    /// Raw explicit 24-hour volume-in-USD field, when returned.
301    pub volume_24h_usd: Option<String>,
302    /// External value provider named by the Dashboard, when returned.
303    pub source: Option<String>,
304    /// External value-provider URL returned by the Dashboard, when present.
305    pub source_url: Option<String>,
306    /// Observation timestamp as Unix seconds.
307    pub timestamp_unix_secs: u64,
308}
309
310///
311/// IcIcrcTokenValueReport
312///
313/// One bounded token-value series from the official Dashboard ICRC API.
314///
315
316#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
317pub struct IcIcrcTokenValueReport {
318    /// Shared Dashboard provenance, flattened in serialized report JSON.
319    #[serde(flatten)]
320    pub provenance: IcDashboardReportProvenance,
321    /// Canonical ICRC ledger canister principal requested from the API.
322    pub ledger_canister_id: String,
323    /// Exact requested time and row bounds, flattened in report JSON.
324    #[serde(flatten)]
325    pub query: IcIcrcTokenValueQuery,
326    /// Whether the response reached the requested limit and may be truncated.
327    pub limit_reached: bool,
328    /// Raw token-value rows in nondecreasing timestamp order.
329    pub rows: Vec<IcIcrcTokenValueRow>,
330}
331
332///
333/// IcDailyStatsRow
334///
335/// Selected raw daily network-activity values returned by the Dashboard API.
336///
337
338#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, Serialize)]
339pub struct IcDailyStatsRow {
340    /// Raw UTC calendar day returned by the Dashboard.
341    pub day: String,
342    /// Observation timestamp as Unix seconds.
343    #[serde(rename(deserialize = "timestamp"))]
344    pub timestamp_unix_secs: u64,
345    /// Raw average query-transaction rate.
346    pub average_query_transactions_per_second: String,
347    /// Raw average update-transaction rate.
348    pub average_update_transactions_per_second: String,
349    /// Raw average total-transaction rate.
350    pub average_transactions_per_second: String,
351    /// Raw maximum query-transaction rate.
352    pub max_query_transactions_per_second: String,
353    /// Raw maximum update-transaction rate.
354    pub max_update_transactions_per_second: String,
355    /// Raw maximum total-transaction rate.
356    pub max_total_transactions_per_second: String,
357    /// Raw average block-production rate.
358    pub blocks_per_second_average: String,
359}
360
361///
362/// IcDailyStatsReport
363///
364/// One bounded daily network-activity response from the official Dashboard API.
365///
366
367#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
368pub struct IcDailyStatsReport {
369    /// Shared Dashboard provenance, flattened in serialized report JSON.
370    #[serde(flatten)]
371    pub provenance: IcDashboardReportProvenance,
372    /// Exact requested time bounds, flattened in report JSON.
373    #[serde(flatten)]
374    pub query: IcDailyStatsQuery,
375    /// Rows in strictly increasing timestamp order.
376    pub rows: Vec<IcDailyStatsRow>,
377}
378
379///
380/// IcBoundaryNodeDataCenterRow
381///
382/// One raw data-center aggregate returned by the boundary-node API.
383///
384
385#[derive(Clone, Debug, Eq, PartialEq, Serialize, serde::Deserialize)]
386pub struct IcBoundaryNodeDataCenterRow {
387    /// Dashboard data-center identifier.
388    pub dc_id: String,
389    /// Raw data-center display name.
390    pub name: String,
391    /// Raw infrastructure-owner label.
392    pub owner: String,
393    /// Raw Dashboard region label.
394    pub region: String,
395    /// Raw decimal latitude.
396    pub latitude: String,
397    /// Raw decimal longitude.
398    pub longitude: String,
399    /// Raw decimal count of boundary nodes assigned to this data center.
400    pub total_nodes: String,
401}
402
403///
404/// IcBoundaryNodeDataCentersReport
405///
406/// One complete response from the official boundary-node data-center resource.
407///
408
409#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
410pub struct IcBoundaryNodeDataCentersReport {
411    /// Shared Dashboard provenance, flattened in serialized report JSON.
412    #[serde(flatten)]
413    pub provenance: IcDashboardReportProvenance,
414    /// Sum of the raw per-data-center boundary-node counts.
415    pub total_node_count: u64,
416    /// Rows in canonical data-center-id order, including zero-node locations.
417    pub rows: Vec<IcBoundaryNodeDataCenterRow>,
418}
419
420///
421/// IcNodeProviderRewardXdrConversionRate
422///
423/// XDR conversion-rate evidence recorded with one node-provider reward.
424///
425
426#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, serde::Deserialize)]
427pub struct IcNodeProviderRewardXdrConversionRate {
428    /// Conversion-rate timestamp as Unix seconds, when present in the record.
429    #[serde(skip_serializing_if = "Option::is_none")]
430    #[serde(rename(deserialize = "timestamp_seconds"))]
431    #[serde(default, deserialize_with = "super::decoding::optional_integer")]
432    pub timestamp_unix_secs: Option<u64>,
433    /// XDR per ICP multiplied by 10,000, when present in the record.
434    #[serde(skip_serializing_if = "Option::is_none")]
435    #[serde(default, deserialize_with = "super::decoding::optional_integer")]
436    pub xdr_permyriad_per_icp: Option<u64>,
437}
438
439///
440/// IcNodeProviderRewardRow
441///
442/// One raw node-provider reward record returned by the official Dashboard API.
443///
444
445#[derive(Clone, Debug, Eq, PartialEq, Serialize, serde::Deserialize)]
446pub struct IcNodeProviderRewardRow {
447    /// Dashboard reward record id.
448    #[serde(rename(deserialize = "id"))]
449    pub reward_id: u64,
450    /// Reward amount in raw ICP e8s.
451    pub amount_e8s: u64,
452    /// Mode-specific raw reward details preserved as a JSON object.
453    #[serde(default)]
454    pub details: BTreeMap<String, serde_json::Value>,
455    /// Maximum node-provider reward in e8s used for this record, when available.
456    pub maximum_node_provider_rewards_e8s: Option<u64>,
457    /// Minimum XDR-permyriad-per-ICP floor used for this record, when available.
458    pub minimum_xdr_permyriad_per_icp: Option<u64>,
459    /// Canonical node-provider principal.
460    #[serde(rename(deserialize = "node_provider"))]
461    pub node_provider_id: String,
462    /// NNS proposal associated with this reward, when recorded by the Dashboard.
463    #[serde(default, deserialize_with = "super::decoding::optional_integer")]
464    pub proposal_id: Option<u64>,
465    /// Registry version associated with this reward, when recorded by the Dashboard.
466    #[serde(default, deserialize_with = "super::decoding::optional_integer")]
467    pub registry_version: Option<u64>,
468    /// Raw mode name so additive Dashboard reward modes remain visible.
469    pub reward_mode: String,
470    /// Reward timestamp as Unix seconds.
471    #[serde(rename(deserialize = "timestamp_seconds"))]
472    pub reward_timestamp_unix_secs: u64,
473    /// Raw Dashboard database update timestamp.
474    #[serde(rename(deserialize = "updated_at"))]
475    pub dashboard_updated_at: String,
476    /// XDR conversion-rate evidence, empty for historical records that predate it.
477    #[serde(default)]
478    pub xdr_conversion_rate: IcNodeProviderRewardXdrConversionRate,
479}
480
481///
482/// IcNodeProviderRewardListReport
483///
484/// One explicitly bounded node-provider reward page from the official Dashboard API.
485///
486
487#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
488pub struct IcNodeProviderRewardListReport {
489    /// Shared Dashboard provenance, flattened in serialized report JSON.
490    #[serde(flatten)]
491    pub provenance: IcDashboardReportProvenance,
492    /// Exact requested page bounds, flattened in report JSON.
493    #[serde(flatten)]
494    pub query: IcNodeProviderRewardListQuery,
495    /// Reward-index ceiling selected by the Dashboard for this page series.
496    pub resolved_max_reward_index: u64,
497    /// Number of reward records matching the selected reward-index ceiling.
498    pub total_reward_records: u64,
499    /// Arithmetic offset hint for an explicit later request, when more records remain.
500    pub next_offset_hint: Option<u64>,
501    /// Whether adjacent upstream offset pages can contain overlapping record ids.
502    pub pages_may_overlap: bool,
503    /// Reward rows in the exact order returned by the Dashboard.
504    pub rows: Vec<IcNodeProviderRewardRow>,
505}
506
507///
508/// IcNodeProviderRewardInfoReport
509///
510/// One exact node-provider reward record from the official Dashboard API.
511///
512
513#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
514pub struct IcNodeProviderRewardInfoReport {
515    /// Shared Dashboard provenance, flattened in serialized report JSON.
516    #[serde(flatten)]
517    pub provenance: IcDashboardReportProvenance,
518    /// Exact reward record, flattened in serialized report JSON.
519    #[serde(flatten)]
520    pub reward: IcNodeProviderRewardRow,
521}
522
523///
524/// IcNodeProviderRewardHistoryObservation
525///
526/// One aggregate reward amount returned by the Dashboard history endpoint.
527///
528
529#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
530pub struct IcNodeProviderRewardHistoryObservation {
531    /// Observation timestamp as Unix seconds.
532    pub timestamp_unix_secs: u64,
533    /// Aggregate node-provider reward amount in raw ICP e8s.
534    pub amount_e8s: u64,
535}
536
537///
538/// IcNodeProviderRewardHistoryReport
539///
540/// One bounded aggregate node-provider reward history response.
541///
542
543#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
544pub struct IcNodeProviderRewardHistoryReport {
545    /// Shared Dashboard provenance, flattened in serialized report JSON.
546    #[serde(flatten)]
547    pub provenance: IcDashboardReportProvenance,
548    /// Exact requested history bounds, flattened in report JSON.
549    #[serde(flatten)]
550    pub query: IcNodeProviderRewardHistoryQuery,
551    /// Maximum observations implied by the requested inclusive window.
552    pub requested_observation_limit: u64,
553    /// Aggregate observations in strictly increasing timestamp order.
554    pub observations: Vec<IcNodeProviderRewardHistoryObservation>,
555}
556
557///
558/// IcReplicaVersionStatus
559///
560/// Raw lifecycle status exposed by the official Dashboard release index.
561///
562
563#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Serialize, serde::Deserialize)]
564#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
565pub enum IcReplicaVersionStatus {
566    /// The election proposal has been adopted but not executed.
567    Adopted,
568    /// The election proposal has executed.
569    Executed,
570    /// The election proposal remains open.
571    Open,
572}
573
574impl IcReplicaVersionStatus {
575    /// Return the exact official Dashboard query value.
576    #[must_use]
577    pub const fn as_dashboard_value(self) -> &'static str {
578        match self {
579            Self::Adopted => "ADOPTED",
580            Self::Executed => "EXECUTED",
581            Self::Open => "OPEN",
582        }
583    }
584}
585
586impl fmt::Display for IcReplicaVersionStatus {
587    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
588        formatter.write_str(self.as_dashboard_value())
589    }
590}
591
592///
593/// IcReplicaVersionSubnetRollout
594///
595/// One Dashboard-recorded proposal assigning a Subnet to a replica version.
596///
597
598#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, Serialize)]
599pub struct IcReplicaVersionSubnetRollout {
600    /// Canonical Subnet principal.
601    pub subnet_id: String,
602    /// NNS proposal that assigned the Subnet to this version.
603    pub proposal_id: u64,
604    /// Proposal execution time as raw Unix seconds.
605    pub executed_timestamp_seconds: u64,
606}
607
608///
609/// IcReplicaVersionListRow
610///
611/// One release-election row from a bounded official Dashboard page.
612///
613
614#[derive(Clone, Debug, Eq, PartialEq, Serialize, serde::Deserialize)]
615pub struct IcReplicaVersionListRow {
616    /// Lowercase hexadecimal replica-version identifier.
617    pub replica_version_id: String,
618    /// NNS proposal that elected this version.
619    pub proposal_id: u64,
620    /// Election proposal execution time, or zero before execution.
621    pub executed_timestamp_seconds: u64,
622    /// Raw Dashboard proposal lifecycle status.
623    pub status: IcReplicaVersionStatus,
624    /// Raw proposal title.
625    pub title: String,
626    /// Raw proposal discussion URL.
627    pub url: String,
628    /// Dashboard-recorded Subnet assignments in execution order.
629    pub subnets: Vec<IcReplicaVersionSubnetRollout>,
630}
631
632///
633/// IcReplicaVersionListReport
634///
635/// One explicitly bounded replica-version page from the official Dashboard API.
636///
637
638#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
639pub struct IcReplicaVersionListReport {
640    /// Shared Dashboard provenance, flattened in serialized report JSON.
641    #[serde(flatten)]
642    pub provenance: IcDashboardReportProvenance,
643    /// Exact requested page bounds, flattened in report JSON.
644    #[serde(flatten)]
645    pub query: IcReplicaVersionListQuery,
646    /// Proposal-index ceiling selected by the Dashboard for this page series.
647    pub resolved_max_proposal_index: u64,
648    /// Number of release records matching the selected proposal-index ceiling.
649    pub total_proposals: u64,
650    /// Offset for an explicit next-page request, when more rows remain.
651    pub next_offset: Option<u64>,
652    /// Release rows in the Dashboard's requested descending execution-time order.
653    pub rows: Vec<IcReplicaVersionListRow>,
654}
655
656///
657/// IcReplicaVersionDetails
658///
659/// Exact Dashboard release-election payload shared by sources and reports.
660///
661
662#[derive(Clone, Debug, Eq, PartialEq, Serialize, serde::Deserialize)]
663pub struct IcReplicaVersionDetails {
664    /// Lowercase hexadecimal replica-version identifier.
665    pub replica_version_id: String,
666    /// NNS proposal that elected this version.
667    pub proposal_id: u64,
668    /// Election proposal execution time as raw Unix seconds.
669    pub executed_timestamp_seconds: u64,
670    /// Raw proposal title.
671    pub title: String,
672    /// Raw proposal discussion URL.
673    pub url: String,
674    /// Raw release-note summary.
675    pub summary: String,
676    /// Dashboard-recorded Subnet assignments in execution order.
677    pub subnets: Vec<IcReplicaVersionSubnetRollout>,
678}
679
680///
681/// IcReplicaVersionInfoReport
682///
683/// One exact replica-version release record from the official Dashboard API.
684///
685
686#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
687pub struct IcReplicaVersionInfoReport {
688    /// Shared Dashboard provenance, flattened in serialized report JSON.
689    #[serde(flatten)]
690    pub provenance: IcDashboardReportProvenance,
691    /// Shared record, flattened in serialized output.
692    #[serde(flatten)]
693    pub release: IcReplicaVersionDetails,
694}
695
696///
697/// IcCanisterData
698///
699/// Dashboard canister payload shared by source data and validated reports.
700/// Source values are validated and canonically ordered before publication.
701/// Deserialization reads Dashboard field names; serialization emits report field names.
702///
703
704#[derive(Clone, Debug, Eq, PartialEq, Serialize, serde::Deserialize)]
705pub struct IcCanisterData {
706    /// Canonical canister principal.
707    pub canister_id: String,
708    /// Dashboard database row identifier.
709    #[serde(rename(deserialize = "id"))]
710    pub dashboard_id: u64,
711    /// Raw optional Dashboard canister classification.
712    pub canister_type: Option<String>,
713    /// Raw Dashboard canister name; an empty string means no name was recorded.
714    pub name: String,
715    /// Canonical Subnet principal recorded by the Dashboard.
716    pub subnet_id: String,
717    /// Canonically ordered controller principals recorded by the Dashboard.
718    pub controllers: Vec<String>,
719    /// Raw Dashboard language label; an empty string means no language was recorded.
720    pub language: String,
721    /// Raw current module hash; an empty string means no hash was recorded.
722    pub module_hash: String,
723    /// Raw Dashboard row update timestamp.
724    #[serde(rename(deserialize = "updated_at"))]
725    pub dashboard_updated_at: String,
726    /// Proposal-linked upgrade history, or `None` when the Dashboard returned `null`.
727    pub upgrades: Option<Vec<IcCanisterUpgrade>>,
728}
729
730///
731/// IcCanisterReport
732///
733/// One live canister metadata report from the official Dashboard API.
734///
735
736#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
737pub struct IcCanisterReport {
738    /// Shared Dashboard provenance, flattened in serialized report JSON.
739    #[serde(flatten)]
740    pub provenance: IcDashboardReportProvenance,
741    /// Canister payload, flattened in serialized report JSON.
742    #[serde(flatten)]
743    pub data: IcCanisterData,
744}
745
746///
747/// IcCanisterCountReport
748///
749/// One filtered canister count from the official Dashboard API.
750///
751
752#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
753pub struct IcCanisterCountReport {
754    /// Shared Dashboard provenance, flattened in serialized report JSON.
755    #[serde(flatten)]
756    pub provenance: IcDashboardReportProvenance,
757    /// Filters applied by the Dashboard.
758    pub filters: IcCanisterFilters,
759    /// Number of matching Dashboard canister records.
760    pub total: u64,
761}
762
763///
764/// IcCanisterPageController
765///
766/// One controller entry returned by the Dashboard canister collection API.
767/// Deserialization reads the wire tuple; serialization emits named report fields.
768///
769
770#[derive(Clone, Debug, Eq, PartialEq, Serialize, serde::Deserialize)]
771#[serde(from = "(String, Option<String>)")]
772pub struct IcCanisterPageController {
773    /// Canonical controller principal.
774    pub principal_id: String,
775    /// Raw optional Dashboard metadata associated with the controller.
776    pub raw_metadata: Option<String>,
777}
778
779///
780/// IcCanisterPageRow
781///
782/// One discovery row from a bounded Dashboard canister page.
783/// Deserialization reads Dashboard field names; serialization emits report field names.
784///
785
786#[derive(Clone, Debug, Eq, PartialEq, Serialize, serde::Deserialize)]
787pub struct IcCanisterPageRow {
788    /// Canonical canister principal.
789    pub canister_id: String,
790    /// Dashboard database row identifier.
791    #[serde(rename(deserialize = "id"))]
792    pub dashboard_id: u64,
793    /// Raw optional Dashboard canister classification.
794    pub canister_type: Option<String>,
795    /// Raw Dashboard canister name.
796    pub name: String,
797    /// Canonical Subnet principal recorded by the Dashboard.
798    pub subnet_id: String,
799    /// Canonically ordered controller entries recorded by the Dashboard.
800    pub controllers: Vec<IcCanisterPageController>,
801    /// Raw Dashboard language label.
802    pub language: String,
803    /// Raw current module hash.
804    pub module_hash: String,
805    /// Raw Dashboard row update timestamp.
806    #[serde(rename(deserialize = "updated_at"))]
807    pub dashboard_updated_at: String,
808}
809
810///
811/// IcCanisterPageReport
812///
813/// One explicitly bounded page from the official Dashboard canister collection.
814///
815
816#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
817pub struct IcCanisterPageReport {
818    /// Shared Dashboard provenance, flattened in serialized report JSON.
819    #[serde(flatten)]
820    pub provenance: IcDashboardReportProvenance,
821    /// Admitted page payload, flattened in JSON.
822    #[serde(flatten)]
823    pub data: IcCanisterPageData,
824}
825
826///
827/// IcCanisterPageData
828///
829/// Shared canister page payload; source admission validates rows and request identity.
830///
831
832#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
833pub struct IcCanisterPageData {
834    /// Filters applied by the Dashboard.
835    pub filters: IcCanisterFilters,
836    /// Maximum rows requested from the API.
837    pub requested_limit: u16,
838    /// Exclusive forward cursor supplied to this request.
839    pub after: Option<String>,
840    /// Exclusive backward cursor supplied to this request.
841    pub before: Option<String>,
842    /// Cursor for an explicit request for the preceding page.
843    pub previous_cursor: Option<String>,
844    /// Cursor for an explicit request for the following page.
845    pub next_cursor: Option<String>,
846    /// Canister discovery rows in Dashboard canister-id order.
847    pub rows: Vec<IcCanisterPageRow>,
848}
849
850impl From<(String, Option<String>)> for IcCanisterPageController {
851    fn from((principal_id, raw_metadata): (String, Option<String>)) -> Self {
852        Self {
853            principal_id,
854            raw_metadata,
855        }
856    }
857}