ic_query/icrc/model/contracts/
reports.rs

1//! Module: icrc::model::contracts::reports
2//!
3//! Responsibility: public serializable ICRC report and row contracts.
4//! Does not own: requests, source data, errors, live transport, caching, or rendering.
5//! Boundary: preserves raw JSON fields and cache/report schemas independently of request construction.
6
7use serde::{Deserialize as SerdeDeserialize, Serialize};
8use serde_json::Value as JsonValue;
9
10///
11/// IcrcTokenReport
12///
13/// Serializable report for generic ICRC ledger token metadata.
14///
15
16#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
17pub struct IcrcTokenReport {
18    pub schema_version: u32,
19    pub ledger_canister_id: String,
20    pub fetched_at: String,
21    pub source_endpoint: String,
22    pub fetched_by: String,
23    pub token_name: String,
24    pub token_symbol: String,
25    pub decimals: u8,
26    pub transfer_fee: String,
27    pub total_supply: String,
28    pub minting_account_owner: Option<String>,
29    pub minting_account_subaccount_hex: Option<String>,
30    pub supported_standards: Vec<IcrcTokenStandardRow>,
31    pub metadata: Vec<IcrcTokenMetadataRow>,
32}
33
34///
35/// IcrcBalanceReport
36///
37/// Serializable report for one generic ICRC account balance lookup.
38///
39
40#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
41pub struct IcrcBalanceReport {
42    pub schema_version: u32,
43    pub ledger_canister_id: String,
44    pub account_owner: String,
45    pub subaccount_hex: Option<String>,
46    pub fetched_at: String,
47    pub source_endpoint: String,
48    pub fetched_by: String,
49    pub token_symbol: String,
50    pub decimals: u8,
51    pub balance: String,
52}
53
54///
55/// IcrcAllowanceReport
56///
57/// Serializable report for one generic ICRC allowance lookup.
58///
59
60#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
61pub struct IcrcAllowanceReport {
62    pub schema_version: u32,
63    pub ledger_canister_id: String,
64    pub account_owner: String,
65    pub account_subaccount_hex: Option<String>,
66    pub spender_owner: String,
67    pub spender_subaccount_hex: Option<String>,
68    pub fetched_at: String,
69    pub source_endpoint: String,
70    pub fetched_by: String,
71    pub token_symbol: String,
72    pub decimals: u8,
73    pub allowance: String,
74    pub expires_at_unix_nanos: Option<String>,
75}
76
77///
78/// IcrcAccountTransactionPageReport
79///
80/// Serializable report for a backward page of ICRC index account transactions.
81///
82
83#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
84pub struct IcrcAccountTransactionPageReport {
85    /// Report schema version.
86    pub schema_version: u32,
87    /// Ledger canister whose transactions were indexed.
88    pub ledger_canister_id: String,
89    /// Index canister that answered the account-history query.
90    pub index_canister_id: String,
91    /// Queried account owner principal.
92    pub account_owner: String,
93    /// Queried subaccount as normalized hex.
94    pub subaccount_hex: Option<String>,
95    /// Exclusive block-index cursor supplied by the caller.
96    pub requested_start: Option<String>,
97    /// Maximum number of transactions requested.
98    pub requested_limit: u32,
99    /// Cursor to pass as `start` to request the next older page.
100    pub next_start: Option<String>,
101    /// Oldest transaction id known for this account.
102    pub oldest_transaction_id: Option<String>,
103    /// Account balance reported by the index at its synchronized tip.
104    pub balance: String,
105    /// Ledger token symbol used for text rendering.
106    pub token_symbol: String,
107    /// Ledger token decimals used for text rendering.
108    pub decimals: u8,
109    /// Collection timestamp in UTC text form.
110    pub fetched_at: String,
111    /// IC API endpoint used for ledger and index calls.
112    pub source_endpoint: String,
113    /// Collector identity.
114    pub fetched_by: String,
115    /// Transactions returned by the index in its native page order.
116    pub transactions: Vec<IcrcAccountTransactionRow>,
117}
118
119///
120/// IcrcAccountTransactionCompleteness
121///
122/// Evidence that a persisted account-history snapshot exhausted the index API.
123///
124
125#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
126pub struct IcrcAccountTransactionCompleteness {
127    /// Stable completeness classification; complete snapshots use `api_exhausted`.
128    pub status: String,
129    /// Maximum transactions requested per source page.
130    pub page_size: u32,
131    /// Number of source pages collected.
132    pub page_count: u32,
133    /// Number of unique persisted transaction rows.
134    pub row_count: usize,
135    /// Whether the source guarantees every page belongs to one point in time.
136    pub point_in_time_guaranteed: bool,
137}
138
139///
140/// IcrcAccountTransactionSnapshot
141///
142/// Complete persisted account-history snapshot collected by exhausting the index API.
143///
144
145#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
146pub struct IcrcAccountTransactionSnapshot {
147    /// Cache schema version.
148    pub schema_version: u32,
149    /// IC API endpoint used for ledger and index calls.
150    pub source_endpoint: String,
151    /// Collection start timestamp.
152    pub collection_started_at: String,
153    /// Collection completion timestamp.
154    pub collection_completed_at: String,
155    /// Collector identity.
156    pub fetched_by: String,
157    /// Ledger canister whose transactions were indexed.
158    pub ledger_canister_id: String,
159    /// Verified index canister used for every page.
160    pub index_canister_id: String,
161    /// Queried account owner principal.
162    pub account_owner: String,
163    /// Queried subaccount as normalized hex.
164    pub subaccount_hex: Option<String>,
165    /// Account balance reported by the first index page.
166    pub balance: String,
167    /// Ledger token symbol used for text rendering.
168    pub token_symbol: String,
169    /// Ledger token decimals used for text rendering.
170    pub decimals: u8,
171    /// Highest collected transaction id.
172    pub newest_transaction_id: Option<String>,
173    /// Lowest collected transaction id.
174    pub oldest_transaction_id: Option<String>,
175    /// Complete-collection evidence.
176    pub completeness: IcrcAccountTransactionCompleteness,
177    /// Canonical newest-first account transactions.
178    pub transactions: Vec<IcrcAccountTransactionRow>,
179}
180
181///
182/// IcrcAccountTransactionRefreshReport
183///
184/// Serializable forced-refresh outcome for one complete account-history cache.
185///
186
187#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
188pub struct IcrcAccountTransactionRefreshReport {
189    /// Report schema version.
190    pub schema_version: u32,
191    /// Ledger canister whose account history was collected.
192    pub ledger_canister_id: String,
193    /// Verified index canister used for every page.
194    pub index_canister_id: String,
195    /// Queried account owner principal.
196    pub account_owner: String,
197    /// Queried subaccount as normalized hex.
198    pub subaccount_hex: Option<String>,
199    /// Number of unique transactions published.
200    pub transaction_count: usize,
201    /// Highest published transaction id.
202    pub newest_transaction_id: Option<String>,
203    /// Lowest published transaction id.
204    pub oldest_transaction_id: Option<String>,
205    /// Maximum transactions requested per source page.
206    pub page_size: u32,
207    /// Number of source pages collected.
208    pub page_count: u32,
209    /// Whether the source guarantees one point-in-time snapshot.
210    pub point_in_time_guaranteed: bool,
211    /// Whether a prior complete cache existed.
212    pub replaced_existing_cache: bool,
213    /// Non-fatal error encountered finalizing the refresh-attempt sidecar.
214    pub attempt_finalization_error: Option<String>,
215    /// Collection start timestamp.
216    pub collection_started_at: String,
217    /// Collection completion timestamp.
218    pub collection_completed_at: String,
219    /// IC API endpoint used for ledger and index calls.
220    pub source_endpoint: String,
221    /// Collector identity.
222    pub fetched_by: String,
223    /// Published complete-cache path.
224    pub cache_path: String,
225    /// Refresh-attempt sidecar path.
226    pub refresh_attempt_path: String,
227    /// Refresh lock path.
228    pub refresh_lock_path: String,
229}
230
231///
232/// IcrcAccountTransactionListReport
233///
234/// Serializable cache-only view over a complete account-history snapshot.
235///
236
237#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
238pub struct IcrcAccountTransactionListReport {
239    /// Report schema version.
240    pub schema_version: u32,
241    /// Ledger canister whose cached history is shown.
242    pub ledger_canister_id: String,
243    /// Verified index canister used to collect the cache.
244    pub index_canister_id: String,
245    /// Cached account owner principal.
246    pub account_owner: String,
247    /// Cached subaccount as normalized hex.
248    pub subaccount_hex: Option<String>,
249    /// Maximum cached rows requested by this view.
250    pub requested_limit: u32,
251    /// Stable requested ordering name.
252    pub sort: String,
253    /// Total rows in the complete cache.
254    pub total_transaction_count: usize,
255    /// Rows returned by this view.
256    pub returned_transaction_count: usize,
257    /// Highest transaction id in the complete cache.
258    pub newest_transaction_id: Option<String>,
259    /// Lowest transaction id in the complete cache.
260    pub oldest_transaction_id: Option<String>,
261    /// Account balance captured from the first index page.
262    pub balance: String,
263    /// Ledger token symbol used for text rendering.
264    pub token_symbol: String,
265    /// Ledger token decimals used for text rendering.
266    pub decimals: u8,
267    /// Complete collection start timestamp.
268    pub collection_started_at: String,
269    /// Complete collection finish timestamp.
270    pub collection_completed_at: String,
271    /// IC API endpoint represented by the cache.
272    pub source_endpoint: String,
273    /// Collector identity.
274    pub fetched_by: String,
275    /// Whether source exhaustion was proven.
276    pub complete: bool,
277    /// Whether the source guaranteed one point-in-time snapshot.
278    pub point_in_time_guaranteed: bool,
279    /// Maximum transactions requested per source page.
280    pub page_size: u32,
281    /// Number of source pages collected.
282    pub page_count: u32,
283    /// Complete-cache path read by this view.
284    pub cache_path: String,
285    /// Selected cached rows in requested order.
286    pub transactions: Vec<IcrcAccountTransactionRow>,
287}
288
289///
290/// IcrcAccountTransactionCacheStatusReport
291///
292/// Serializable local cache and latest-refresh status.
293///
294
295#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
296pub struct IcrcAccountTransactionCacheStatusReport {
297    /// Report schema version.
298    pub schema_version: u32,
299    /// Ledger canister in the requested cache identity.
300    pub ledger_canister_id: String,
301    /// Account owner in the requested cache identity.
302    pub account_owner: String,
303    /// Subaccount in the requested cache identity.
304    pub subaccount_hex: Option<String>,
305    /// IC API endpoint in the requested cache identity.
306    pub source_endpoint: String,
307    /// Whether a cache file exists at the expected path.
308    pub found: bool,
309    /// Validation summary when a cache file exists.
310    pub cache: Option<IcrcAccountTransactionCacheSummary>,
311    /// Expected complete-cache path.
312    pub expected_cache_path: String,
313    /// Refresh-attempt sidecar path.
314    pub refresh_attempt_path: String,
315    /// Refresh lock path.
316    pub refresh_lock_path: String,
317    /// Latest refresh-attempt state when present.
318    pub latest_attempt: Option<IcrcAccountTransactionRefreshAttemptStatus>,
319}
320
321///
322/// IcrcAccountTransactionCacheSummary
323///
324/// Serializable validation summary for one complete account-history cache.
325///
326
327#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
328pub struct IcrcAccountTransactionCacheSummary {
329    /// Stable cache validation status.
330    pub cache_status: String,
331    /// Validation error when the existing cache is invalid.
332    pub cache_error: Option<String>,
333    /// Verified index canister when the cache is valid.
334    pub index_canister_id: Option<String>,
335    /// Number of cached transaction rows.
336    pub transaction_count: usize,
337    /// Highest cached transaction id.
338    pub newest_transaction_id: Option<String>,
339    /// Lowest cached transaction id.
340    pub oldest_transaction_id: Option<String>,
341    /// Maximum transactions requested per source page.
342    pub page_size: u32,
343    /// Number of source pages collected.
344    pub page_count: u32,
345    /// Whether source exhaustion was proven.
346    pub complete: bool,
347    /// Whether the source guaranteed one point-in-time snapshot.
348    pub point_in_time_guaranteed: bool,
349    /// Complete collection start timestamp.
350    pub collection_started_at: String,
351    /// Complete collection finish timestamp.
352    pub collection_completed_at: String,
353    /// Complete-cache path.
354    pub cache_path: String,
355}
356
357///
358/// IcrcAccountTransactionRefreshAttemptStatus
359///
360/// Serializable status of the latest complete-history refresh attempt.
361///
362
363#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
364pub struct IcrcAccountTransactionRefreshAttemptStatus {
365    /// Stable attempt lifecycle status.
366    pub status: String,
367    /// Attempt start timestamp.
368    pub started_at: String,
369    /// Last attempt update timestamp.
370    pub updated_at: String,
371    /// Explicit or resolved index canister recorded by the attempt.
372    pub index_canister_id: Option<String>,
373    /// Maximum transactions requested per source page.
374    pub page_size: u32,
375    /// Successfully collected pages.
376    pub pages_fetched: u32,
377    /// Rows retained before the latest update.
378    pub rows_fetched: usize,
379    /// Last exclusive cursor when present.
380    pub last_cursor: Option<String>,
381    /// Final failure text when the attempt failed.
382    pub last_error: Option<String>,
383}
384
385///
386/// IcrcIndexReport
387///
388/// Serializable report for one generic ICRC-106 index discovery lookup.
389///
390
391#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
392pub struct IcrcIndexReport {
393    pub schema_version: u32,
394    pub ledger_canister_id: String,
395    pub fetched_at: String,
396    pub source_endpoint: String,
397    pub fetched_by: String,
398    pub index_canister_id: Option<String>,
399    pub index_error: Option<String>,
400}
401
402///
403/// IcrcTransactionsReport
404///
405/// Serializable report for a generic ICRC ledger transaction/block history page.
406///
407
408#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
409pub struct IcrcTransactionsReport {
410    pub schema_version: u32,
411    pub ledger_canister_id: String,
412    pub fetched_at: String,
413    pub source_endpoint: String,
414    pub fetched_by: String,
415    pub requested_start: String,
416    pub requested_limit: u32,
417    pub follow_archives: bool,
418    pub log_length: Option<String>,
419    pub blocks: Vec<IcrcTransactionBlockRow>,
420    pub archived_blocks: Vec<IcrcArchivedBlocksRow>,
421    pub followed_archive_blocks: Vec<IcrcFollowedArchiveBlockRow>,
422    pub archive_follow_errors: Vec<IcrcArchiveFollowErrorRow>,
423}
424
425///
426/// IcrcBlockTypesReport
427///
428/// Serializable report for generic ICRC-3 supported block type discovery.
429///
430
431#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
432pub struct IcrcBlockTypesReport {
433    pub schema_version: u32,
434    pub ledger_canister_id: String,
435    pub fetched_at: String,
436    pub source_endpoint: String,
437    pub fetched_by: String,
438    pub block_types: Vec<IcrcBlockTypeRow>,
439}
440
441///
442/// IcrcArchivesReport
443///
444/// Serializable report for generic ICRC-3 archive range discovery.
445///
446
447#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
448pub struct IcrcArchivesReport {
449    pub schema_version: u32,
450    pub ledger_canister_id: String,
451    pub from_canister_id: Option<String>,
452    pub fetched_at: String,
453    pub source_endpoint: String,
454    pub fetched_by: String,
455    pub archives: Vec<IcrcArchiveRow>,
456}
457
458///
459/// IcrcTipCertificateReport
460///
461/// Serializable report for a generic ICRC-3 ledger tip certificate.
462///
463
464#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
465pub struct IcrcTipCertificateReport {
466    pub schema_version: u32,
467    pub ledger_canister_id: String,
468    pub fetched_at: String,
469    pub source_endpoint: String,
470    pub fetched_by: String,
471    pub certificate_present: bool,
472    pub certificate_hex: Option<String>,
473    pub certificate_bytes: Option<usize>,
474    pub hash_tree_hex: Option<String>,
475    pub hash_tree_bytes: Option<usize>,
476}
477
478///
479/// IcrcCapabilitiesReport
480///
481/// Serializable report for generic ICRC ledger endpoint capabilities.
482///
483
484#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
485pub struct IcrcCapabilitiesReport {
486    pub schema_version: u32,
487    pub ledger_canister_id: String,
488    pub fetched_at: String,
489    pub source_endpoint: String,
490    pub fetched_by: String,
491    pub supported_standards: Vec<IcrcTokenStandardRow>,
492    pub capabilities: Vec<IcrcCapabilityRow>,
493}
494
495///
496/// IcrcCapabilityRow
497///
498/// Serializable row for one probed generic ICRC ledger capability.
499///
500
501#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
502pub struct IcrcCapabilityRow {
503    pub capability: String,
504    pub method: String,
505    pub status: String,
506    pub details: Option<String>,
507    pub error: Option<String>,
508}
509
510///
511/// IcrcTokenStandardRow
512///
513/// Serializable row for one ICRC standard supported by a ledger.
514///
515
516#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
517pub struct IcrcTokenStandardRow {
518    pub name: String,
519    pub url: String,
520}
521
522///
523/// IcrcTokenMetadataRow
524///
525/// Serializable row for one raw ICRC ledger metadata entry.
526///
527
528#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
529pub struct IcrcTokenMetadataRow {
530    pub key: String,
531    pub value_type: String,
532    pub value: JsonValue,
533}
534
535///
536/// IcrcAccountRow
537///
538/// Serializable ICRC account identity used in account-transaction rows.
539///
540
541#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
542pub struct IcrcAccountRow {
543    /// ICRC account owner principal when the index uses structured accounts.
544    pub owner: Option<String>,
545    /// Optional 32-byte subaccount as lowercase hex.
546    pub subaccount_hex: Option<String>,
547    /// Legacy ICP account identifier when the index returns identifier text.
548    pub account_identifier: Option<String>,
549}
550
551///
552/// IcrcAccountTransactionRow
553///
554/// Serializable projected and lossless JSON representation of one index transaction.
555///
556
557#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
558pub struct IcrcAccountTransactionRow {
559    /// Ledger block index of the transaction.
560    pub id: String,
561    /// Index-reported transaction kind.
562    pub kind: String,
563    /// Ledger transaction timestamp as Unix nanoseconds when present.
564    pub timestamp_unix_nanos: Option<String>,
565    /// Operation amount in ledger base units when the operation carries one.
566    pub amount_base_units: Option<String>,
567    /// Operation fee in ledger base units when the operation carries one.
568    pub fee_base_units: Option<String>,
569    /// Source account when present.
570    pub from: Option<IcrcAccountRow>,
571    /// Destination account when present.
572    pub to: Option<IcrcAccountRow>,
573    /// Spender account when present.
574    pub spender: Option<IcrcAccountRow>,
575    /// Operation memo as lowercase hex when present.
576    pub memo_hex: Option<String>,
577    /// Caller-supplied creation time as Unix nanoseconds when present.
578    pub created_at_time_unix_nanos: Option<String>,
579    /// Approval expiry as Unix nanoseconds when present.
580    pub expires_at_unix_nanos: Option<String>,
581    /// Expected prior allowance in base units when present.
582    pub expected_allowance_base_units: Option<String>,
583    /// Lossless JSON projection of every typed transaction field returned by the index.
584    pub raw_transaction: JsonValue,
585}
586
587///
588/// IcrcTransactionBlockRow
589///
590/// Serializable row for one ICRC-3 block returned by a ledger canister.
591///
592
593#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
594pub struct IcrcTransactionBlockRow {
595    pub index: String,
596    pub block_type: Option<String>,
597    pub transaction_kind: Option<String>,
598    pub timestamp_unix_nanos: Option<String>,
599    pub amount_base_units: Option<String>,
600    pub raw_block: JsonValue,
601}
602
603///
604/// IcrcArchivedBlocksRow
605///
606/// Serializable row for one ICRC-3 archive callback returned by a ledger canister.
607///
608
609#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
610pub struct IcrcArchivedBlocksRow {
611    pub callback_canister_id: String,
612    pub callback_method: String,
613    pub ranges: Vec<IcrcArchivedRangeRow>,
614}
615
616///
617/// IcrcArchivedRangeRow
618///
619/// Serializable row for one ICRC-3 archived block range.
620///
621
622#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
623pub struct IcrcArchivedRangeRow {
624    pub start: String,
625    pub length: String,
626}
627
628///
629/// IcrcFollowedArchiveBlockRow
630///
631/// Serializable row for one ICRC-3 block fetched from an archive callback.
632///
633
634#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
635pub struct IcrcFollowedArchiveBlockRow {
636    pub archive_canister_id: String,
637    pub callback_method: String,
638    pub index: String,
639    pub block_type: Option<String>,
640    pub transaction_kind: Option<String>,
641    pub timestamp_unix_nanos: Option<String>,
642    pub amount_base_units: Option<String>,
643    pub raw_block: JsonValue,
644}
645
646///
647/// IcrcArchiveFollowErrorRow
648///
649/// Serializable row for one archive callback that could not be followed.
650///
651
652#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
653pub struct IcrcArchiveFollowErrorRow {
654    pub callback_canister_id: String,
655    pub callback_method: String,
656    pub ranges: Vec<IcrcArchivedRangeRow>,
657    pub error: String,
658}
659
660///
661/// IcrcBlockTypeRow
662///
663/// Serializable row for one supported ICRC-3 block type.
664///
665
666#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
667pub struct IcrcBlockTypeRow {
668    pub block_type: String,
669    pub url: String,
670}
671
672///
673/// IcrcArchiveRow
674///
675/// Serializable row for one ICRC-3 archive range.
676///
677
678#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
679pub struct IcrcArchiveRow {
680    pub canister_id: String,
681    pub start: String,
682    pub end: String,
683}
ic_query/icrc/model/contracts/reports.rs

ic_query/icrc/model/contracts/
reports.rs
