ic_query/icrc/model/requests/
account_history.rs

1//! Module: icrc::model::requests::account_history
2//!
3//! Responsibility: ICRC account-history page, cache, refresh, and list requests.
4//! Does not own: ledger-wide history, live transport, cache mechanics, or reports.
5//! Boundary: separates stable collection identity from pagination and local view options.
6
7use super::IcrcLedgerRequest;
8
9use std::path::PathBuf;
10
11///
12/// IcrcAccountTransactionPageRequest
13///
14/// Request accepted by the live ICRC index account-transaction page builder.
15///
16
17#[derive(Clone, Debug, Eq, PartialEq)]
18pub struct IcrcAccountTransactionPageRequest {
19    /// Shared ledger identity, explicit endpoint and caller collection clock.
20    pub ledger: IcrcLedgerRequest,
21    /// Optional explicit index canister; otherwise ICRC-106 discovery is used.
22    pub index_canister_id: Option<String>,
23    /// Account owner principal.
24    pub account_owner: String,
25    /// Optional normalized 32-byte subaccount hex.
26    pub subaccount_hex: Option<String>,
27    /// Optional exclusive block-index cursor for backward pagination.
28    pub start: Option<String>,
29    /// Maximum number of account transactions to request.
30    pub limit: u32,
31}
32
33impl IcrcAccountTransactionPageRequest {
34    /// Constructs an account-history request that discovers the index through the ledger.
35    #[must_use]
36    pub fn new(ledger: IcrcLedgerRequest, account_owner: impl Into<String>, limit: u32) -> Self {
37        Self {
38            ledger,
39            index_canister_id: None,
40            account_owner: account_owner.into(),
41            subaccount_hex: None,
42            start: None,
43            limit,
44        }
45    }
46}
47
48///
49/// IcrcAccountTransactionCacheRequest
50///
51/// Stable account-history cache identity independent of page and view options.
52///
53
54#[derive(Clone, Debug, Eq, PartialEq)]
55pub struct IcrcAccountTransactionCacheRequest {
56    /// Root directory containing the shared cache.
57    pub cache_root: PathBuf,
58    /// IC API endpoint whose indexed history is cached.
59    pub source_endpoint: String,
60    /// Ledger canister whose account history is cached.
61    pub ledger_canister_id: String,
62    /// Account owner principal.
63    pub account_owner: String,
64    /// Optional normalized 32-byte subaccount hex.
65    pub subaccount_hex: Option<String>,
66}
67
68impl IcrcAccountTransactionCacheRequest {
69    /// Constructs a cache identity for the default subaccount.
70    #[must_use]
71    pub fn new(
72        cache_root: impl Into<PathBuf>,
73        source_endpoint: impl Into<String>,
74        ledger_canister_id: impl Into<String>,
75        account_owner: impl Into<String>,
76    ) -> Self {
77        Self {
78            cache_root: cache_root.into(),
79            source_endpoint: source_endpoint.into(),
80            ledger_canister_id: ledger_canister_id.into(),
81            account_owner: account_owner.into(),
82            subaccount_hex: None,
83        }
84    }
85}
86
87///
88/// IcrcAccountTransactionRefreshRequest
89///
90/// Request for a forced complete account-history refresh.
91///
92
93#[derive(Clone, Debug, Eq, PartialEq)]
94pub struct IcrcAccountTransactionRefreshRequest {
95    /// Stable cache identity.
96    pub cache: IcrcAccountTransactionCacheRequest,
97    /// Collection start clock in Unix seconds; completion adds monotonic elapsed time.
98    pub now_unix_secs: u64,
99    /// Optional explicit index canister; otherwise ICRC-106 discovery is used.
100    pub index_canister_id: Option<String>,
101    /// Maximum transactions requested per index page.
102    pub page_size: u32,
103    /// Optional diagnostic bound that fails rather than publishing a partial cache.
104    pub max_pages: Option<u32>,
105}
106
107impl IcrcAccountTransactionRefreshRequest {
108    /// Constructs a complete refresh request.
109    #[must_use]
110    pub const fn new(
111        cache: IcrcAccountTransactionCacheRequest,
112        now_unix_secs: u64,
113        page_size: u32,
114    ) -> Self {
115        Self {
116            cache,
117            now_unix_secs,
118            index_canister_id: None,
119            page_size,
120            max_pages: None,
121        }
122    }
123}
124
125///
126/// IcrcAccountTransactionSort
127///
128/// Supported cached account-history ordering.
129///
130
131#[derive(Clone, Copy, Debug, Eq, PartialEq)]
132pub enum IcrcAccountTransactionSort {
133    /// Highest transaction id first.
134    Newest,
135    /// Lowest transaction id first.
136    Oldest,
137}
138
139impl IcrcAccountTransactionSort {
140    /// All supported choices in their public presentation order.
141    pub const ALL: &'static [Self] = &[Self::Newest, Self::Oldest];
142
143    /// Stable JSON/text name for this ordering.
144    #[must_use]
145    pub const fn as_str(self) -> &'static str {
146        match self {
147            Self::Newest => "newest",
148            Self::Oldest => "oldest",
149        }
150    }
151}
152
153///
154/// IcrcAccountTransactionListRequest
155///
156/// Cache-only account-history list view.
157///
158
159#[derive(Clone, Debug, Eq, PartialEq)]
160pub struct IcrcAccountTransactionListRequest {
161    /// Stable cache identity.
162    pub cache: IcrcAccountTransactionCacheRequest,
163    /// Maximum cached rows returned by this view.
164    pub limit: u32,
165    /// Requested cached-row ordering.
166    pub sort: IcrcAccountTransactionSort,
167}
168
169impl IcrcAccountTransactionListRequest {
170    /// Constructs a newest-first cached list view.
171    #[must_use]
172    pub const fn new(cache: IcrcAccountTransactionCacheRequest, limit: u32) -> Self {
173        Self {
174            cache,
175            limit,
176            sort: IcrcAccountTransactionSort::Newest,
177        }
178    }
179}
ic_query/icrc/model/requests/account_history.rs

ic_query/icrc/model/requests/
account_history.rs
