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

ic_query/ic/model/requests/
icrc_index.rs
