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    /// Restrict the page to one owner principal.
195    #[must_use]
196    pub fn with_owner(mut self, owner: impl Into<String>) -> Self {
197        self.owner = Some(owner.into());
198        self
199    }
200
201    /// Continue after one opaque cursor.
202    #[must_use]
203    pub fn with_after(mut self, after: impl Into<String>) -> Self {
204        self.after = Some(after.into());
205        self
206    }
207
208    /// Continue before one opaque cursor.
209    #[must_use]
210    pub fn with_before(mut self, before: impl Into<String>) -> Self {
211        self.before = Some(before.into());
212        self
213    }
214}
215
216///
217/// IcIcrcHolderListQuery
218///
219/// One explicitly bounded holder-index page query.
220///
221
222#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
223pub struct IcIcrcHolderListQuery {
224    /// Opaque exclusive forward cursor returned by an earlier page.
225    pub after: Option<String>,
226    /// Opaque exclusive backward cursor returned by an earlier page.
227    pub before: Option<String>,
228    /// Maximum rows requested from the official API.
229    pub limit: u16,
230    /// Stable upstream sort order applied to the page.
231    pub sort_by: IcIcrcHolderSort,
232}
233
234impl IcIcrcHolderListQuery {
235    /// Construct one holder-index page query.
236    #[must_use]
237    pub const fn new(limit: u16, sort_by: IcIcrcHolderSort) -> Self {
238        Self {
239            after: None,
240            before: None,
241            limit,
242            sort_by,
243        }
244    }
245
246    /// Continue after one opaque cursor.
247    #[must_use]
248    pub fn with_after(mut self, after: impl Into<String>) -> Self {
249        self.after = Some(after.into());
250        self
251    }
252
253    /// Continue before one opaque cursor.
254    #[must_use]
255    pub fn with_before(mut self, before: impl Into<String>) -> Self {
256        self.before = Some(before.into());
257        self
258    }
259}
260
261///
262/// IcIcrcAccountListRequest
263///
264/// Request accepted by the bounded official ICRC account-list report builder.
265///
266
267#[derive(Clone, Debug, Eq, PartialEq)]
268pub struct IcIcrcAccountListRequest {
269    /// Shared analytics endpoint, collection time, and ledger identity.
270    pub analytics: IcIcrcAnalyticsRequest,
271    /// Explicitly bounded account page query.
272    pub query: IcIcrcAccountListQuery,
273}
274
275impl IcIcrcAccountListRequest {
276    /// Construct one bounded live account-list request.
277    #[must_use]
278    pub fn new(
279        dashboard: IcDashboardRequest,
280        ledger_canister_id: impl Into<String>,
281        query: IcIcrcAccountListQuery,
282    ) -> Self {
283        Self {
284            analytics: IcIcrcAnalyticsRequest::new(dashboard, ledger_canister_id),
285            query,
286        }
287    }
288}
289
290///
291/// IcIcrcAccountInfoRequest
292///
293/// Request accepted by the exact official ICRC account-detail report builder.
294///
295
296#[derive(Clone, Debug, Eq, PartialEq)]
297pub struct IcIcrcAccountInfoRequest {
298    /// Shared analytics endpoint, collection time, and ledger identity.
299    pub analytics: IcIcrcAnalyticsRequest,
300    /// Exact opaque account id requested from the index.
301    pub account_id: String,
302}
303
304impl IcIcrcAccountInfoRequest {
305    /// Construct one exact live account-detail request.
306    #[must_use]
307    pub fn new(
308        dashboard: IcDashboardRequest,
309        ledger_canister_id: impl Into<String>,
310        account_id: impl Into<String>,
311    ) -> Self {
312        Self {
313            analytics: IcIcrcAnalyticsRequest::new(dashboard, ledger_canister_id),
314            account_id: account_id.into(),
315        }
316    }
317}
318
319///
320/// IcIcrcHolderListRequest
321///
322/// Request accepted by the bounded official ICRC holder-list report builder.
323///
324
325#[derive(Clone, Debug, Eq, PartialEq)]
326pub struct IcIcrcHolderListRequest {
327    /// Shared analytics endpoint, collection time, and ledger identity.
328    pub analytics: IcIcrcAnalyticsRequest,
329    /// Explicitly bounded holder page query.
330    pub query: IcIcrcHolderListQuery,
331}
332
333impl IcIcrcHolderListRequest {
334    /// Construct one bounded live holder-list request.
335    #[must_use]
336    pub fn new(
337        dashboard: IcDashboardRequest,
338        ledger_canister_id: impl Into<String>,
339        query: IcIcrcHolderListQuery,
340    ) -> Self {
341        Self {
342            analytics: IcIcrcAnalyticsRequest::new(dashboard, ledger_canister_id),
343            query,
344        }
345    }
346}
ic_query/ic/model/requests/icrc_index.rs

ic_query/ic/model/requests/
icrc_index.rs
