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