ic_query/ic/model/requests/
icrc_analytics.rs

1//! Module: ic::model::requests::icrc_analytics
2//!
3//! Responsibility: bounded official ICRC analytics request contracts.
4//! Does not own: native ledger queries, transport, source validation, or reports.
5//! Boundary: shares one ledger target while keeping series bounds operation-specific.
6
7use serde::Serialize;
8use std::fmt;
9
10///
11/// IcIcrcAnalyticsRequest
12///
13/// Shared endpoint, collection time, and ledger target for official ICRC analytics.
14///
15
16#[derive(Clone, Debug, Eq, PartialEq)]
17pub struct IcIcrcAnalyticsRequest {
18    /// Official ICRC analytics API base endpoint.
19    pub source_endpoint: String,
20    /// Collection time as Unix seconds.
21    pub now_unix_secs: u64,
22    /// ICRC ledger canister principal requested from the analytics service.
23    pub ledger_canister_id: String,
24}
25
26impl IcIcrcAnalyticsRequest {
27    /// Construct one official ICRC analytics target.
28    #[must_use]
29    pub fn new(
30        source_endpoint: impl Into<String>,
31        now_unix_secs: u64,
32        ledger_canister_id: impl Into<String>,
33    ) -> Self {
34        Self {
35            source_endpoint: source_endpoint.into(),
36            now_unix_secs,
37            ledger_canister_id: ledger_canister_id.into(),
38        }
39    }
40}
41
42///
43/// IcIcrcIndexedCountKind
44///
45/// Scalar ledger resource counted by the official ICRC analytics index.
46///
47
48#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Serialize)]
49#[serde(rename_all = "snake_case")]
50pub enum IcIcrcIndexedCountKind {
51    /// Accounts represented by the index.
52    Account,
53    /// Holders represented by the index.
54    Holder,
55    /// Transactions represented by the index.
56    Transaction,
57}
58
59impl IcIcrcIndexedCountKind {
60    /// Return the stable singular resource label used in reports.
61    #[must_use]
62    pub const fn as_str(self) -> &'static str {
63        match self {
64            Self::Account => "account",
65            Self::Holder => "holder",
66            Self::Transaction => "transaction",
67        }
68    }
69
70    #[cfg(feature = "host")]
71    pub(crate) const fn resource_path_segment(self) -> &'static str {
72        match self {
73            Self::Account => "accounts",
74            Self::Holder => "holders",
75            Self::Transaction => "transactions",
76        }
77    }
78}
79
80impl fmt::Display for IcIcrcIndexedCountKind {
81    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
82        formatter.write_str(self.as_str())
83    }
84}
85
86///
87/// IcIcrcIndexedCountRequest
88///
89/// Request for one scalar count from the official ICRC analytics index.
90///
91
92#[derive(Clone, Debug, Eq, PartialEq)]
93pub struct IcIcrcIndexedCountRequest {
94    /// Shared analytics endpoint, collection time, and ledger identity.
95    pub analytics: IcIcrcAnalyticsRequest,
96    /// Indexed resource to count.
97    pub kind: IcIcrcIndexedCountKind,
98}
99
100impl IcIcrcIndexedCountRequest {
101    /// Construct one live indexed-count request.
102    #[must_use]
103    pub fn new(
104        source_endpoint: impl Into<String>,
105        now_unix_secs: u64,
106        ledger_canister_id: impl Into<String>,
107        kind: IcIcrcIndexedCountKind,
108    ) -> Self {
109        Self {
110            analytics: IcIcrcAnalyticsRequest::new(
111                source_endpoint,
112                now_unix_secs,
113                ledger_canister_id,
114            ),
115            kind,
116        }
117    }
118}
119
120///
121/// IcIcrcTotalSupplyQuery
122///
123/// One explicitly bounded total-supply series query for an ICRC ledger.
124///
125
126#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
127pub struct IcIcrcTotalSupplyQuery {
128    /// Inclusive query start as Unix seconds.
129    pub start_unix_secs: u64,
130    /// Inclusive query end as Unix seconds.
131    pub end_unix_secs: u64,
132    /// Requested observation interval in seconds.
133    pub step_secs: u32,
134}
135
136impl IcIcrcTotalSupplyQuery {
137    /// Construct one explicit total-supply query window.
138    #[must_use]
139    pub const fn new(start_unix_secs: u64, end_unix_secs: u64, step_secs: u32) -> Self {
140        Self {
141            start_unix_secs,
142            end_unix_secs,
143            step_secs,
144        }
145    }
146}
147
148///
149/// IcIcrcTotalSupplyRequest
150///
151/// Request accepted by the bounded official ICRC analytics report builder.
152///
153
154#[derive(Clone, Debug, Eq, PartialEq)]
155pub struct IcIcrcTotalSupplyRequest {
156    /// Shared analytics endpoint, collection time, and ledger identity.
157    pub analytics: IcIcrcAnalyticsRequest,
158    /// Explicitly bounded total-supply query.
159    pub query: IcIcrcTotalSupplyQuery,
160}
161
162impl IcIcrcTotalSupplyRequest {
163    /// Construct one bounded live ICRC total-supply analytics request.
164    #[must_use]
165    pub fn new(
166        source_endpoint: impl Into<String>,
167        now_unix_secs: u64,
168        ledger_canister_id: impl Into<String>,
169        query: IcIcrcTotalSupplyQuery,
170    ) -> Self {
171        Self {
172            analytics: IcIcrcAnalyticsRequest::new(
173                source_endpoint,
174                now_unix_secs,
175                ledger_canister_id,
176            ),
177            query,
178        }
179    }
180}
ic_query/ic/model/requests/icrc_analytics.rs

ic_query/ic/model/requests/
icrc_analytics.rs
