ic_query/icrc/model/reports/ledger/
mod.rs

1//! Module: icrc::model::reports::ledger
2//!
3//! Responsibility: serialized ICRC ledger metadata, capability, and history contracts.
4//! Does not own: account-index history, requests, live transport, archive following, or rendering.
5//! Boundary: preserves raw ledger, block, archive, certificate, and capability fields.
6
7use crate::icrc::{IcrcIndexData, IcrcTokenData, IcrcTokenStandardRow};
8use serde::Serialize;
9use serde_json::Value as JsonValue;
10
11///
12/// IcrcTokenReport
13///
14/// Serializable report for generic ICRC ledger token metadata.
15///
16
17#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
18pub struct IcrcTokenReport {
19    /// Shared record, flattened in serialized output.
20    #[serde(flatten)]
21    pub provenance: super::IcrcReportProvenance,
22    /// Raw ledger metadata shared with token source capabilities.
23    #[serde(flatten)]
24    pub token: IcrcTokenData,
25}
26
27///
28/// IcrcIndexReport
29///
30/// Serializable report for one generic ICRC-106 index discovery lookup.
31///
32
33#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
34pub struct IcrcIndexReport {
35    /// Shared record, flattened in serialized output.
36    #[serde(flatten)]
37    pub provenance: super::IcrcReportProvenance,
38    /// Discovered index principal or the source's unavailability reason.
39    pub index: IcrcIndexData,
40}
41
42///
43/// IcrcTransactionsData
44///
45/// Source-layer ICRC-3 block history result from a ledger canister.
46///
47
48#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
49pub struct IcrcTransactionsData {
50    /// Total number of blocks as a decimal natural, or unknown for custom sources.
51    /// Returned blocks and archive ranges must stay below this length when known.
52    pub log_length: Option<String>,
53    /// Blocks returned directly by the ledger.
54    pub blocks: Vec<IcrcTransactionBlockRow>,
55    /// Archive referrals returned for the requested page.
56    pub archived_blocks: Vec<IcrcArchivedBlocksRow>,
57    /// Blocks retained from successful archive callbacks.
58    pub followed_archive_blocks: Vec<IcrcFollowedArchiveBlockRow>,
59    /// Bounded failures retained while following archive callbacks.
60    pub archive_follow_errors: Vec<IcrcArchiveFollowErrorRow>,
61}
62
63///
64/// IcrcTransactionsReport
65///
66/// Serializable report for a generic ICRC ledger transaction/block history page.
67///
68
69#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
70pub struct IcrcTransactionsReport {
71    /// Shared record, flattened in serialized output.
72    #[serde(flatten)]
73    pub provenance: super::IcrcReportProvenance,
74    pub requested_start: String,
75    pub requested_limit: u32,
76    pub follow_archives: bool,
77    /// Canonical history payload.
78    #[serde(flatten)]
79    pub transactions: IcrcTransactionsData,
80}
81
82///
83/// IcrcBlockTypesReport
84///
85/// Serializable report for generic ICRC-3 supported block type discovery.
86///
87
88#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
89pub struct IcrcBlockTypesReport {
90    /// Shared record, flattened in serialized output.
91    #[serde(flatten)]
92    pub provenance: super::IcrcReportProvenance,
93    pub block_types: Vec<IcrcBlockTypeRow>,
94}
95
96///
97/// IcrcArchivesReport
98///
99/// Serializable report for generic ICRC-3 archive range discovery.
100///
101
102#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
103pub struct IcrcArchivesReport {
104    /// Shared record, flattened in serialized output.
105    #[serde(flatten)]
106    pub provenance: super::IcrcReportProvenance,
107    pub from_canister_id: Option<String>,
108    pub archives: Vec<IcrcArchiveRow>,
109}
110
111///
112/// IcrcTipCertificateReport
113///
114/// Serializable report for a generic ICRC-3 ledger tip certificate.
115///
116
117#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
118pub struct IcrcTipCertificateReport {
119    /// Shared record, flattened in serialized output.
120    #[serde(flatten)]
121    pub provenance: super::IcrcReportProvenance,
122    /// Complete certificate/witness evidence, absent when the ledger returns none.
123    pub certificate: Option<IcrcTipCertificateEvidence>,
124}
125
126///
127/// IcrcTipCertificateEvidence
128///
129/// Original certificate and hash-tree reply evidence with their byte lengths.
130///
131
132#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
133pub struct IcrcTipCertificateEvidence {
134    /// Original certificate bytes as lowercase hexadecimal text.
135    pub certificate_hex: String,
136    /// Number of bytes in the original certificate.
137    pub certificate_bytes: usize,
138    /// Original hash-tree bytes as lowercase hexadecimal text.
139    pub hash_tree_hex: String,
140    /// Number of bytes in the original hash tree.
141    pub hash_tree_bytes: usize,
142}
143
144///
145/// IcrcCapabilitiesReport
146///
147/// Serializable report for generic ICRC ledger endpoint capabilities.
148///
149
150#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
151pub struct IcrcCapabilitiesReport {
152    /// Shared record, flattened in serialized output.
153    #[serde(flatten)]
154    pub provenance: super::IcrcReportProvenance,
155    pub supported_standards: Vec<IcrcTokenStandardRow>,
156    pub capabilities: Vec<IcrcCapabilityRow>,
157}
158
159///
160/// IcrcCapabilityRow
161///
162/// Serializable row for one probed generic ICRC ledger capability.
163///
164
165#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
166pub struct IcrcCapabilityRow {
167    pub capability: String,
168    pub method: String,
169    pub status: IcrcCapabilityStatus,
170    pub details: Option<String>,
171    pub error: Option<String>,
172}
173
174///
175/// IcrcCapabilityStatus
176///
177/// Result of probing one optional ICRC ledger capability.
178///
179
180#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
181#[serde(rename_all = "snake_case")]
182pub enum IcrcCapabilityStatus {
183    /// The target answered the capability query successfully.
184    Available,
185    /// The target does not export the probed query method.
186    Unsupported,
187    /// The target exports the method but the query failed.
188    Error,
189}
190
191impl IcrcCapabilityStatus {
192    /// Return the stable JSON and text label.
193    #[must_use]
194    pub const fn as_str(self) -> &'static str {
195        match self {
196            Self::Available => "available",
197            Self::Unsupported => "unsupported",
198            Self::Error => "error",
199        }
200    }
201}
202
203///
204/// IcrcTransactionBlockRow
205///
206/// Serializable row for one ICRC-3 block returned by a ledger canister.
207///
208
209#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
210pub struct IcrcTransactionBlockRow {
211    pub index: String,
212    pub block_type: Option<String>,
213    pub transaction_kind: Option<String>,
214    pub timestamp_unix_nanos: Option<String>,
215    pub amount_base_units: Option<String>,
216    pub raw_block: JsonValue,
217}
218
219///
220/// IcrcArchivedBlocksRow
221///
222/// Serializable row for one ICRC-3 archive callback returned by a ledger canister.
223///
224
225#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
226pub struct IcrcArchivedBlocksRow {
227    pub callback_canister_id: String,
228    pub callback_method: String,
229    pub ranges: Vec<IcrcArchivedRangeRow>,
230}
231
232///
233/// IcrcArchivedRangeRow
234///
235/// Serializable row for one ICRC-3 archived block range.
236///
237
238#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
239pub struct IcrcArchivedRangeRow {
240    pub start: String,
241    pub length: String,
242}
243
244///
245/// IcrcFollowedArchiveBlockRow
246///
247/// Serializable row for one ICRC-3 block fetched from an archive callback.
248///
249
250#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
251pub struct IcrcFollowedArchiveBlockRow {
252    pub archive_canister_id: String,
253    pub callback_method: String,
254    /// Canonical block summary and raw evidence.
255    #[serde(flatten)]
256    pub block: IcrcTransactionBlockRow,
257}
258
259#[cfg(test)]
260mod tests;
261
262///
263/// IcrcArchiveFollowErrorRow
264///
265/// Serializable row for one archive callback that could not be followed.
266///
267
268#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
269pub struct IcrcArchiveFollowErrorRow {
270    pub callback_canister_id: String,
271    pub callback_method: String,
272    pub ranges: Vec<IcrcArchivedRangeRow>,
273    pub error: String,
274}
275
276///
277/// IcrcBlockTypeRow
278///
279/// Serializable row for one supported ICRC-3 block type.
280///
281
282#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
283pub struct IcrcBlockTypeRow {
284    pub block_type: String,
285    pub url: String,
286}
287
288///
289/// IcrcArchiveRow
290///
291/// Serializable row for one ICRC-3 archive range.
292///
293
294#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
295pub struct IcrcArchiveRow {
296    pub canister_id: String,
297    pub start: String,
298    pub end: String,
299}
ic_query/icrc/model/reports/ledger/mod.rs

ic_query/icrc/model/reports/ledger/
mod.rs
