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 super::IcDashboardRequest;
8
9use serde::Serialize;
10use std::fmt;
11
12///
13/// IcIcrcAnalyticsRequest
14///
15/// Shared endpoint, collection time, and ledger target for official ICRC analytics.
16///
17
18#[derive(Clone, Debug, Eq, PartialEq)]
19pub struct IcIcrcAnalyticsRequest {
20    /// Explicit Dashboard endpoint and caller collection clock.
21    pub dashboard: IcDashboardRequest,
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(dashboard: IcDashboardRequest, ledger_canister_id: impl Into<String>) -> Self {
30        Self {
31            dashboard,
32            ledger_canister_id: ledger_canister_id.into(),
33        }
34    }
35}
36
37///
38/// IcIcrcIndexedCountKind
39///
40/// Scalar ledger resource counted by the official ICRC analytics index.
41///
42
43#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Serialize)]
44#[serde(rename_all = "snake_case")]
45pub enum IcIcrcIndexedCountKind {
46    /// Accounts represented by the index.
47    Account,
48    /// Holders represented by the index.
49    Holder,
50    /// Transactions represented by the index.
51    Transaction,
52}
53
54impl IcIcrcIndexedCountKind {
55    /// Return the stable singular resource label used in reports.
56    #[must_use]
57    pub const fn as_str(self) -> &'static str {
58        match self {
59            Self::Account => "account",
60            Self::Holder => "holder",
61            Self::Transaction => "transaction",
62        }
63    }
64
65    #[cfg(feature = "dashboard-host")]
66    pub(crate) const fn resource_path_segment(self) -> &'static str {
67        match self {
68            Self::Account => "accounts",
69            Self::Holder => "holders",
70            Self::Transaction => "transactions",
71        }
72    }
73}
74
75impl fmt::Display for IcIcrcIndexedCountKind {
76    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
77        formatter.write_str(self.as_str())
78    }
79}
80
81///
82/// IcIcrcIndexedCountRequest
83///
84/// Request for one scalar count from the official ICRC analytics index.
85///
86
87#[derive(Clone, Debug, Eq, PartialEq)]
88pub struct IcIcrcIndexedCountRequest {
89    /// Shared analytics endpoint, collection time, and ledger identity.
90    pub analytics: IcIcrcAnalyticsRequest,
91    /// Indexed resource to count.
92    pub kind: IcIcrcIndexedCountKind,
93}
94
95impl IcIcrcIndexedCountRequest {
96    /// Construct one live indexed-count request.
97    #[must_use]
98    pub fn new(
99        dashboard: IcDashboardRequest,
100        ledger_canister_id: impl Into<String>,
101        kind: IcIcrcIndexedCountKind,
102    ) -> Self {
103        Self {
104            analytics: IcIcrcAnalyticsRequest::new(dashboard, ledger_canister_id),
105            kind,
106        }
107    }
108}
109
110///
111/// IcIcrcTokenValueQuery
112///
113/// One explicitly bounded token-value series query for an ICRC ledger.
114///
115
116#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
117pub struct IcIcrcTokenValueQuery {
118    /// Query start as Unix seconds.
119    pub start_unix_secs: u64,
120    /// Query end as Unix seconds.
121    pub end_unix_secs: u64,
122    /// Maximum rows requested from the official API.
123    pub limit: u16,
124}
125
126impl IcIcrcTokenValueQuery {
127    /// Construct one explicit token-value query window.
128    #[must_use]
129    pub const fn new(start_unix_secs: u64, end_unix_secs: u64, limit: u16) -> Self {
130        Self {
131            start_unix_secs,
132            end_unix_secs,
133            limit,
134        }
135    }
136}
137
138///
139/// IcIcrcTokenValueRequest
140///
141/// Request accepted by the bounded official ICRC token-value report builder.
142///
143
144#[derive(Clone, Debug, Eq, PartialEq)]
145pub struct IcIcrcTokenValueRequest {
146    /// Shared analytics endpoint, collection time, and ledger identity.
147    pub analytics: IcIcrcAnalyticsRequest,
148    /// Explicitly bounded token-value query.
149    pub query: IcIcrcTokenValueQuery,
150}
151
152impl IcIcrcTokenValueRequest {
153    /// Construct one bounded live ICRC token-value request.
154    #[must_use]
155    pub fn new(
156        dashboard: IcDashboardRequest,
157        ledger_canister_id: impl Into<String>,
158        query: IcIcrcTokenValueQuery,
159    ) -> Self {
160        Self {
161            analytics: IcIcrcAnalyticsRequest::new(dashboard, ledger_canister_id),
162            query,
163        }
164    }
165}
166
167///
168/// IcIcrcTotalSupplyQuery
169///
170/// One explicitly bounded total-supply series query for an ICRC ledger.
171///
172
173#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
174pub struct IcIcrcTotalSupplyQuery {
175    /// Inclusive query start as Unix seconds.
176    pub start_unix_secs: u64,
177    /// Inclusive query end as Unix seconds.
178    pub end_unix_secs: u64,
179    /// Requested observation interval in seconds.
180    pub step_secs: u32,
181}
182
183impl IcIcrcTotalSupplyQuery {
184    /// Construct one explicit total-supply query window.
185    #[must_use]
186    pub const fn new(start_unix_secs: u64, end_unix_secs: u64, step_secs: u32) -> Self {
187        Self {
188            start_unix_secs,
189            end_unix_secs,
190            step_secs,
191        }
192    }
193}
194
195///
196/// IcIcrcTotalSupplyRequest
197///
198/// Request accepted by the bounded official ICRC analytics report builder.
199///
200
201#[derive(Clone, Debug, Eq, PartialEq)]
202pub struct IcIcrcTotalSupplyRequest {
203    /// Shared analytics endpoint, collection time, and ledger identity.
204    pub analytics: IcIcrcAnalyticsRequest,
205    /// Explicitly bounded total-supply query.
206    pub query: IcIcrcTotalSupplyQuery,
207}
208
209impl IcIcrcTotalSupplyRequest {
210    /// Construct one bounded live ICRC total-supply analytics request.
211    #[must_use]
212    pub fn new(
213        dashboard: IcDashboardRequest,
214        ledger_canister_id: impl Into<String>,
215        query: IcIcrcTotalSupplyQuery,
216    ) -> Self {
217        Self {
218            analytics: IcIcrcAnalyticsRequest::new(dashboard, ledger_canister_id),
219            query,
220        }
221    }
222}
ic_query/ic/model/requests/icrc_analytics.rs

ic_query/ic/model/requests/
icrc_analytics.rs
