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

ic_query/ic/model/requests/
icrc_index.rs
