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