ic_query/icrc/model/contracts/reports/account_history.rs
1//! Module: icrc::model::contracts::reports::account_history
2//!
3//! Responsibility: serialized ICRC account-history page, cache, and row contracts.
4//! Does not own: ledger-wide history, requests, live transport, cache mechanics, or rendering.
5//! Boundary: owns the stable JSON and persisted snapshot shapes for indexed account history.
6
7use crate::cache::{CacheCollectionCompleteness, CacheRefreshAttemptStatus, CacheValidationStatus};
8use serde::{Deserialize as SerdeDeserialize, Serialize};
9use serde_json::Value as JsonValue;
10
11///
12/// IcrcAccountTransactionPageReport
13///
14/// Serializable report for a backward page of ICRC index account transactions.
15///
16
17#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
18pub struct IcrcAccountTransactionPageReport {
19 /// Report schema version.
20 pub schema_version: u32,
21 /// Ledger canister whose transactions were indexed.
22 pub ledger_canister_id: String,
23 /// Index canister that answered the account-history query.
24 pub index_canister_id: String,
25 /// Queried account owner principal.
26 pub account_owner: String,
27 /// Queried subaccount as normalized hex.
28 pub subaccount_hex: Option<String>,
29 /// Exclusive block-index cursor supplied by the caller.
30 pub requested_start: Option<String>,
31 /// Maximum number of transactions requested.
32 pub requested_limit: u32,
33 /// Cursor to pass as `start` to request the next older page.
34 pub next_start: Option<String>,
35 /// Oldest transaction id known for this account.
36 pub oldest_transaction_id: Option<String>,
37 /// Account balance reported by the index at its synchronized tip.
38 pub balance: String,
39 /// Ledger token symbol used for text rendering.
40 pub token_symbol: String,
41 /// Ledger token decimals used for text rendering.
42 pub decimals: u8,
43 /// Collection timestamp in UTC text form.
44 pub fetched_at: String,
45 /// IC API endpoint used for ledger and index calls.
46 pub source_endpoint: String,
47 /// Collector identity.
48 pub fetched_by: String,
49 /// Transactions returned by the index in its native page order.
50 pub transactions: Vec<IcrcAccountTransactionRow>,
51}
52
53///
54/// IcrcAccountTransactionSnapshot
55///
56/// Complete persisted account-history snapshot collected by exhausting the index API.
57///
58
59#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
60pub struct IcrcAccountTransactionSnapshot {
61 /// Cache schema version.
62 pub schema_version: u32,
63 /// IC API endpoint used for ledger and index calls.
64 pub source_endpoint: String,
65 /// Collection start timestamp.
66 pub collection_started_at: String,
67 /// Collection completion timestamp.
68 pub collection_completed_at: String,
69 /// Collector identity.
70 pub fetched_by: String,
71 /// Ledger canister whose transactions were indexed.
72 pub ledger_canister_id: String,
73 /// Verified index canister used for every page.
74 pub index_canister_id: String,
75 /// Queried account owner principal.
76 pub account_owner: String,
77 /// Queried subaccount as normalized hex.
78 pub subaccount_hex: Option<String>,
79 /// Account balance reported by the first index page.
80 pub balance: String,
81 /// Ledger token symbol used for text rendering.
82 pub token_symbol: String,
83 /// Ledger token decimals used for text rendering.
84 pub decimals: u8,
85 /// Highest collected transaction id.
86 pub newest_transaction_id: Option<String>,
87 /// Lowest collected transaction id.
88 pub oldest_transaction_id: Option<String>,
89 /// Complete-collection evidence.
90 pub completeness: CacheCollectionCompleteness,
91 /// Canonical newest-first account transactions.
92 pub transactions: Vec<IcrcAccountTransactionRow>,
93}
94
95///
96/// IcrcAccountTransactionRefreshReport
97///
98/// Serializable forced-refresh outcome for one complete account-history cache.
99///
100
101#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
102pub struct IcrcAccountTransactionRefreshReport {
103 /// Report schema version.
104 pub schema_version: u32,
105 /// Ledger canister whose account history was collected.
106 pub ledger_canister_id: String,
107 /// Verified index canister used for every page.
108 pub index_canister_id: String,
109 /// Queried account owner principal.
110 pub account_owner: String,
111 /// Queried subaccount as normalized hex.
112 pub subaccount_hex: Option<String>,
113 /// Number of unique transactions published.
114 pub transaction_count: usize,
115 /// Highest published transaction id.
116 pub newest_transaction_id: Option<String>,
117 /// Lowest published transaction id.
118 pub oldest_transaction_id: Option<String>,
119 /// Maximum transactions requested per source page.
120 pub page_size: u32,
121 /// Number of source pages collected.
122 pub page_count: u32,
123 /// Whether the source guarantees one point-in-time snapshot.
124 pub point_in_time_guaranteed: bool,
125 /// Whether a prior complete cache existed.
126 pub replaced_existing_cache: bool,
127 /// Non-fatal error encountered finalizing the refresh-attempt sidecar.
128 pub attempt_finalization_error: Option<String>,
129 /// Collection start timestamp.
130 pub collection_started_at: String,
131 /// Collection completion timestamp.
132 pub collection_completed_at: String,
133 /// IC API endpoint used for ledger and index calls.
134 pub source_endpoint: String,
135 /// Collector identity.
136 pub fetched_by: String,
137 /// Published complete-cache path.
138 pub cache_path: String,
139 /// Refresh-attempt sidecar path.
140 pub refresh_attempt_path: String,
141 /// Refresh lock path.
142 pub refresh_lock_path: String,
143}
144
145///
146/// IcrcAccountTransactionListReport
147///
148/// Serializable cache-only view over a complete account-history snapshot.
149///
150
151#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
152pub struct IcrcAccountTransactionListReport {
153 /// Report schema version.
154 pub schema_version: u32,
155 /// Ledger canister whose cached history is shown.
156 pub ledger_canister_id: String,
157 /// Verified index canister used to collect the cache.
158 pub index_canister_id: String,
159 /// Cached account owner principal.
160 pub account_owner: String,
161 /// Cached subaccount as normalized hex.
162 pub subaccount_hex: Option<String>,
163 /// Maximum cached rows requested by this view.
164 pub requested_limit: u32,
165 /// Stable requested ordering name.
166 pub sort: String,
167 /// Total rows in the complete cache.
168 pub total_transaction_count: usize,
169 /// Rows returned by this view.
170 pub returned_transaction_count: usize,
171 /// Highest transaction id in the complete cache.
172 pub newest_transaction_id: Option<String>,
173 /// Lowest transaction id in the complete cache.
174 pub oldest_transaction_id: Option<String>,
175 /// Account balance captured from the first index page.
176 pub balance: String,
177 /// Ledger token symbol used for text rendering.
178 pub token_symbol: String,
179 /// Ledger token decimals used for text rendering.
180 pub decimals: u8,
181 /// Complete collection start timestamp.
182 pub collection_started_at: String,
183 /// Complete collection finish timestamp.
184 pub collection_completed_at: String,
185 /// IC API endpoint represented by the cache.
186 pub source_endpoint: String,
187 /// Collector identity.
188 pub fetched_by: String,
189 /// Whether source exhaustion was proven.
190 pub complete: bool,
191 /// Whether the source guaranteed one point-in-time snapshot.
192 pub point_in_time_guaranteed: bool,
193 /// Maximum transactions requested per source page.
194 pub page_size: u32,
195 /// Number of source pages collected.
196 pub page_count: u32,
197 /// Complete-cache path read by this view.
198 pub cache_path: String,
199 /// Selected cached rows in requested order.
200 pub transactions: Vec<IcrcAccountTransactionRow>,
201}
202
203///
204/// IcrcAccountTransactionCacheStatusReport
205///
206/// Serializable local cache and latest-refresh status.
207///
208
209#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
210pub struct IcrcAccountTransactionCacheStatusReport {
211 /// Report schema version.
212 pub schema_version: u32,
213 /// Ledger canister in the requested cache identity.
214 pub ledger_canister_id: String,
215 /// Account owner in the requested cache identity.
216 pub account_owner: String,
217 /// Subaccount in the requested cache identity.
218 pub subaccount_hex: Option<String>,
219 /// IC API endpoint in the requested cache identity.
220 pub source_endpoint: String,
221 /// Whether a cache file exists at the expected path.
222 pub found: bool,
223 /// Validation summary when a cache file exists.
224 pub cache: Option<IcrcAccountTransactionCacheSummary>,
225 /// Expected complete-cache path.
226 pub expected_cache_path: String,
227 /// Refresh-attempt sidecar path.
228 pub refresh_attempt_path: String,
229 /// Refresh lock path.
230 pub refresh_lock_path: String,
231 /// Latest refresh-attempt state when present.
232 pub latest_attempt: Option<IcrcAccountTransactionRefreshAttemptStatus>,
233}
234
235///
236/// IcrcAccountTransactionCacheSummary
237///
238/// Serializable validation summary for one complete account-history cache.
239///
240
241#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
242pub struct IcrcAccountTransactionCacheSummary {
243 /// Stable cache validation status.
244 pub cache_status: CacheValidationStatus,
245 /// Validation error when the existing cache is invalid.
246 pub cache_error: Option<String>,
247 /// Verified index canister when the cache is valid.
248 pub index_canister_id: Option<String>,
249 /// Number of cached transaction rows.
250 pub transaction_count: usize,
251 /// Highest cached transaction id.
252 pub newest_transaction_id: Option<String>,
253 /// Lowest cached transaction id.
254 pub oldest_transaction_id: Option<String>,
255 /// Maximum transactions requested per source page.
256 pub page_size: u32,
257 /// Number of source pages collected.
258 pub page_count: u32,
259 /// Whether source exhaustion was proven.
260 pub complete: bool,
261 /// Whether the source guaranteed one point-in-time snapshot.
262 pub point_in_time_guaranteed: bool,
263 /// Complete collection start timestamp.
264 pub collection_started_at: String,
265 /// Complete collection finish timestamp.
266 pub collection_completed_at: String,
267 /// Complete-cache path.
268 pub cache_path: String,
269}
270
271///
272/// IcrcAccountTransactionRefreshAttemptStatus
273///
274/// Serializable status of the latest complete-history refresh attempt.
275///
276
277#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
278pub struct IcrcAccountTransactionRefreshAttemptStatus {
279 /// Stable attempt lifecycle status.
280 pub status: CacheRefreshAttemptStatus,
281 /// Attempt start timestamp.
282 pub started_at: String,
283 /// Last attempt update timestamp.
284 pub updated_at: String,
285 /// Explicit or resolved index canister recorded by the attempt.
286 pub index_canister_id: Option<String>,
287 /// Maximum transactions requested per source page.
288 pub page_size: u32,
289 /// Successfully collected pages.
290 pub pages_fetched: u32,
291 /// Rows retained before the latest update.
292 pub rows_fetched: usize,
293 /// Last exclusive cursor when present.
294 pub last_cursor: Option<String>,
295 /// Final failure text when the attempt failed.
296 pub last_error: Option<String>,
297}
298
299///
300/// IcrcAccountRow
301///
302/// Serializable ICRC account identity used in account-transaction rows.
303///
304
305#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
306pub struct IcrcAccountRow {
307 /// ICRC account owner principal when the index uses structured accounts.
308 pub owner: Option<String>,
309 /// Optional 32-byte subaccount as lowercase hex.
310 pub subaccount_hex: Option<String>,
311 /// Legacy ICP account identifier when the index returns identifier text.
312 pub account_identifier: Option<String>,
313}
314
315///
316/// IcrcAccountTransactionRow
317///
318/// Serializable projected and lossless JSON representation of one index transaction.
319///
320
321#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
322pub struct IcrcAccountTransactionRow {
323 /// Ledger block index of the transaction.
324 pub id: String,
325 /// Index-reported transaction kind.
326 pub kind: String,
327 /// Ledger transaction timestamp as Unix nanoseconds when present.
328 pub timestamp_unix_nanos: Option<String>,
329 /// Operation amount in ledger base units when the operation carries one.
330 pub amount_base_units: Option<String>,
331 /// Operation fee in ledger base units when the operation carries one.
332 pub fee_base_units: Option<String>,
333 /// Source account when present.
334 pub from: Option<IcrcAccountRow>,
335 /// Destination account when present.
336 pub to: Option<IcrcAccountRow>,
337 /// Spender account when present.
338 pub spender: Option<IcrcAccountRow>,
339 /// Operation memo as lowercase hex when present.
340 pub memo_hex: Option<String>,
341 /// Caller-supplied creation time as Unix nanoseconds when present.
342 pub created_at_time_unix_nanos: Option<String>,
343 /// Approval expiry as Unix nanoseconds when present.
344 pub expires_at_unix_nanos: Option<String>,
345 /// Expected prior allowance in base units when present.
346 pub expected_allowance_base_units: Option<String>,
347 /// Lossless JSON projection of every typed transaction field returned by the index.
348 pub raw_transaction: JsonValue,
349}