ic_query/ic/model/requests/
icrc_index.rs

1//! Module: ic::model::requests::icrc_index
2//!
3//! Responsibility: bounded official ICRC account and holder index request contracts.
4//! Does not own: native ledger queries, transport, source validation, or reports.
5//! Boundary: exposes one exact account lookup or one explicitly bounded cursor page.
6
7use super::IcDashboardRequest;
8
9use super::IcIcrcAnalyticsRequest;
10use serde::Serialize;
11use std::fmt;
12
13///
14/// IcIcrcAccountSort
15///
16/// Sort order accepted by the official ICRC account index.
17///
18
19#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Serialize)]
20pub enum IcIcrcAccountSort {
21    /// Account id in ascending order.
22    #[serde(rename = "id")]
23    Id,
24    /// Account id in descending order.
25    #[serde(rename = "-id")]
26    IdDescending,
27    /// Raw balance in ascending order.
28    #[serde(rename = "balance")]
29    Balance,
30    /// Raw balance in descending order.
31    #[serde(rename = "-balance")]
32    BalanceDescending,
33    /// Total transaction count in ascending order.
34    #[serde(rename = "total_transactions")]
35    TotalTransactions,
36    /// Total transaction count in descending order.
37    #[serde(rename = "-total_transactions")]
38    TotalTransactionsDescending,
39    /// Creation timestamp in ascending order.
40    #[serde(rename = "created_timestamp")]
41    CreatedTimestamp,
42    /// Creation timestamp in descending order.
43    #[serde(rename = "-created_timestamp")]
44    CreatedTimestampDescending,
45    /// Owner principal in ascending order.
46    #[serde(rename = "owner")]
47    Owner,
48    /// Owner principal in descending order.
49    #[serde(rename = "-owner")]
50    OwnerDescending,
51}
52
53impl IcIcrcAccountSort {
54    /// All supported choices in their public presentation order.
55    pub const ALL: &'static [Self] = &[
56        Self::Id,
57        Self::IdDescending,
58        Self::Balance,
59        Self::BalanceDescending,
60        Self::TotalTransactions,
61        Self::TotalTransactionsDescending,
62        Self::CreatedTimestamp,
63        Self::CreatedTimestampDescending,
64        Self::Owner,
65        Self::OwnerDescending,
66    ];
67
68    /// Return the exact official API query value.
69    #[must_use]
70    pub const fn as_api_value(self) -> &'static str {
71        match self {
72            Self::Id => "id",
73            Self::IdDescending => "-id",
74            Self::Balance => "balance",
75            Self::BalanceDescending => "-balance",
76            Self::TotalTransactions => "total_transactions",
77            Self::TotalTransactionsDescending => "-total_transactions",
78            Self::CreatedTimestamp => "created_timestamp",
79            Self::CreatedTimestampDescending => "-created_timestamp",
80            Self::Owner => "owner",
81            Self::OwnerDescending => "-owner",
82        }
83    }
84}
85
86impl fmt::Display for IcIcrcAccountSort {
87    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
88        formatter.write_str(self.as_api_value())
89    }
90}
91
92///
93/// IcIcrcHolderSort
94///
95/// Sort order accepted by the official ICRC holder index.
96///
97
98#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Serialize)]
99pub enum IcIcrcHolderSort {
100    /// Raw aggregate balance in ascending order.
101    #[serde(rename = "balance")]
102    Balance,
103    /// Raw aggregate balance in descending order.
104    #[serde(rename = "-balance")]
105    BalanceDescending,
106    /// Total transaction count in ascending order.
107    #[serde(rename = "total_transactions")]
108    TotalTransactions,
109    /// Total transaction count in descending order.
110    #[serde(rename = "-total_transactions")]
111    TotalTransactionsDescending,
112    /// Earliest account creation timestamp in ascending order.
113    #[serde(rename = "created_timestamp")]
114    CreatedTimestamp,
115    /// Earliest account creation timestamp in descending order.
116    #[serde(rename = "-created_timestamp")]
117    CreatedTimestampDescending,
118    /// Holder principal in ascending order.
119    #[serde(rename = "principal")]
120    Principal,
121    /// Holder principal in descending order.
122    #[serde(rename = "-principal")]
123    PrincipalDescending,
124}
125
126impl IcIcrcHolderSort {
127    /// All supported choices in their public presentation order.
128    pub const ALL: &'static [Self] = &[
129        Self::Balance,
130        Self::BalanceDescending,
131        Self::TotalTransactions,
132        Self::TotalTransactionsDescending,
133        Self::CreatedTimestamp,
134        Self::CreatedTimestampDescending,
135        Self::Principal,
136        Self::PrincipalDescending,
137    ];
138
139    /// Return the exact official API query value.
140    #[must_use]
141    pub const fn as_api_value(self) -> &'static str {
142        match self {
143            Self::Balance => "balance",
144            Self::BalanceDescending => "-balance",
145            Self::TotalTransactions => "total_transactions",
146            Self::TotalTransactionsDescending => "-total_transactions",
147            Self::CreatedTimestamp => "created_timestamp",
148            Self::CreatedTimestampDescending => "-created_timestamp",
149            Self::Principal => "principal",
150            Self::PrincipalDescending => "-principal",
151        }
152    }
153}
154
155impl fmt::Display for IcIcrcHolderSort {
156    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
157        formatter.write_str(self.as_api_value())
158    }
159}
160
161///
162/// IcIcrcAccountListQuery
163///
164/// One explicitly bounded account-index page query.
165///
166
167#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
168pub struct IcIcrcAccountListQuery {
169    /// Optional canonical owner principal filter.
170    pub owner: Option<String>,
171    /// Opaque exclusive forward cursor returned by an earlier page.
172    pub after: Option<String>,
173    /// Opaque exclusive backward cursor returned by an earlier page.
174    pub before: Option<String>,
175    /// Maximum rows requested from the official API.
176    pub limit: u16,
177    /// Stable upstream sort order applied to the page.
178    pub sort_by: IcIcrcAccountSort,
179}
180
181impl IcIcrcAccountListQuery {
182    /// Construct one account-index page query.
183    #[must_use]
184    pub const fn new(limit: u16, sort_by: IcIcrcAccountSort) -> Self {
185        Self {
186            owner: None,
187            after: None,
188            before: None,
189            limit,
190            sort_by,
191        }
192    }
193}
194
195///
196/// IcIcrcHolderListQuery
197///
198/// One explicitly bounded holder-index page query.
199///
200
201#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
202pub struct IcIcrcHolderListQuery {
203    /// Opaque exclusive forward cursor returned by an earlier page.
204    pub after: Option<String>,
205    /// Opaque exclusive backward cursor returned by an earlier page.
206    pub before: Option<String>,
207    /// Maximum rows requested from the official API.
208    pub limit: u16,
209    /// Stable upstream sort order applied to the page.
210    pub sort_by: IcIcrcHolderSort,
211}
212
213impl IcIcrcHolderListQuery {
214    /// Construct one holder-index page query.
215    #[must_use]
216    pub const fn new(limit: u16, sort_by: IcIcrcHolderSort) -> Self {
217        Self {
218            after: None,
219            before: None,
220            limit,
221            sort_by,
222        }
223    }
224}
225
226///
227/// IcIcrcAccountListRequest
228///
229/// Request accepted by the bounded official ICRC account-list report builder.
230///
231
232#[derive(Clone, Debug, Eq, PartialEq)]
233pub struct IcIcrcAccountListRequest {
234    /// Shared analytics endpoint, collection time, and ledger identity.
235    pub analytics: IcIcrcAnalyticsRequest,
236    /// Explicitly bounded account page query.
237    pub query: IcIcrcAccountListQuery,
238}
239
240impl IcIcrcAccountListRequest {
241    /// Construct one bounded live account-list request.
242    #[must_use]
243    pub fn new(
244        dashboard: IcDashboardRequest,
245        ledger_canister_id: impl Into<String>,
246        query: IcIcrcAccountListQuery,
247    ) -> Self {
248        Self {
249            analytics: IcIcrcAnalyticsRequest::new(dashboard, ledger_canister_id),
250            query,
251        }
252    }
253}
254
255///
256/// IcIcrcAccountInfoRequest
257///
258/// Request accepted by the exact official ICRC account-detail report builder.
259///
260
261#[derive(Clone, Debug, Eq, PartialEq)]
262pub struct IcIcrcAccountInfoRequest {
263    /// Shared analytics endpoint, collection time, and ledger identity.
264    pub analytics: IcIcrcAnalyticsRequest,
265    /// Exact opaque account id requested from the index.
266    pub account_id: String,
267}
268
269impl IcIcrcAccountInfoRequest {
270    /// Construct one exact live account-detail request.
271    #[must_use]
272    pub fn new(
273        dashboard: IcDashboardRequest,
274        ledger_canister_id: impl Into<String>,
275        account_id: impl Into<String>,
276    ) -> Self {
277        Self {
278            analytics: IcIcrcAnalyticsRequest::new(dashboard, ledger_canister_id),
279            account_id: account_id.into(),
280        }
281    }
282}
283
284///
285/// IcIcrcHolderListRequest
286///
287/// Request accepted by the bounded official ICRC holder-list report builder.
288///
289
290#[derive(Clone, Debug, Eq, PartialEq)]
291pub struct IcIcrcHolderListRequest {
292    /// Shared analytics endpoint, collection time, and ledger identity.
293    pub analytics: IcIcrcAnalyticsRequest,
294    /// Explicitly bounded holder page query.
295    pub query: IcIcrcHolderListQuery,
296}
297
298impl IcIcrcHolderListRequest {
299    /// Construct one bounded live holder-list request.
300    #[must_use]
301    pub fn new(
302        dashboard: IcDashboardRequest,
303        ledger_canister_id: impl Into<String>,
304        query: IcIcrcHolderListQuery,
305    ) -> Self {
306        Self {
307            analytics: IcIcrcAnalyticsRequest::new(dashboard, ledger_canister_id),
308            query,
309        }
310    }
311}
ic_query/ic/model/requests/icrc_index.rs

ic_query/ic/model/requests/
icrc_index.rs
