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/// IcIcrcTokenValueQuery
122///
123/// One explicitly bounded token-value series query for an ICRC ledger.
124///
125
126#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
127pub struct IcIcrcTokenValueQuery {
128    /// Query start as Unix seconds.
129    pub start_unix_secs: u64,
130    /// Query end as Unix seconds.
131    pub end_unix_secs: u64,
132    /// Maximum rows requested from the official API.
133    pub limit: u16,
134}
135
136impl IcIcrcTokenValueQuery {
137    /// Construct one explicit token-value query window.
138    #[must_use]
139    pub const fn new(start_unix_secs: u64, end_unix_secs: u64, limit: u16) -> Self {
140        Self {
141            start_unix_secs,
142            end_unix_secs,
143            limit,
144        }
145    }
146}
147
148///
149/// IcIcrcTokenValueRequest
150///
151/// Request accepted by the bounded official ICRC token-value report builder.
152///
153
154#[derive(Clone, Debug, Eq, PartialEq)]
155pub struct IcIcrcTokenValueRequest {
156    /// Shared analytics endpoint, collection time, and ledger identity.
157    pub analytics: IcIcrcAnalyticsRequest,
158    /// Explicitly bounded token-value query.
159    pub query: IcIcrcTokenValueQuery,
160}
161
162impl IcIcrcTokenValueRequest {
163    /// Construct one bounded live ICRC token-value 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: IcIcrcTokenValueQuery,
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}
181
182///
183/// IcIcrcTotalSupplyQuery
184///
185/// One explicitly bounded total-supply series query for an ICRC ledger.
186///
187
188#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
189pub struct IcIcrcTotalSupplyQuery {
190    /// Inclusive query start as Unix seconds.
191    pub start_unix_secs: u64,
192    /// Inclusive query end as Unix seconds.
193    pub end_unix_secs: u64,
194    /// Requested observation interval in seconds.
195    pub step_secs: u32,
196}
197
198impl IcIcrcTotalSupplyQuery {
199    /// Construct one explicit total-supply query window.
200    #[must_use]
201    pub const fn new(start_unix_secs: u64, end_unix_secs: u64, step_secs: u32) -> Self {
202        Self {
203            start_unix_secs,
204            end_unix_secs,
205            step_secs,
206        }
207    }
208}
209
210///
211/// IcIcrcTotalSupplyRequest
212///
213/// Request accepted by the bounded official ICRC analytics report builder.
214///
215
216#[derive(Clone, Debug, Eq, PartialEq)]
217pub struct IcIcrcTotalSupplyRequest {
218    /// Shared analytics endpoint, collection time, and ledger identity.
219    pub analytics: IcIcrcAnalyticsRequest,
220    /// Explicitly bounded total-supply query.
221    pub query: IcIcrcTotalSupplyQuery,
222}
223
224impl IcIcrcTotalSupplyRequest {
225    /// Construct one bounded live ICRC total-supply analytics request.
226    #[must_use]
227    pub fn new(
228        source_endpoint: impl Into<String>,
229        now_unix_secs: u64,
230        ledger_canister_id: impl Into<String>,
231        query: IcIcrcTotalSupplyQuery,
232    ) -> Self {
233        Self {
234            analytics: IcIcrcAnalyticsRequest::new(
235                source_endpoint,
236                now_unix_secs,
237                ledger_canister_id,
238            ),
239            query,
240        }
241    }
242}
ic_query/ic/model/requests/icrc_analytics.rs

ic_query/ic/model/requests/
icrc_analytics.rs
