ic_query/nns/registry/report/model.rs
1use serde::{Deserialize, Serialize};
2
3#[cfg(feature = "nns-host")]
4pub(super) const NNS_REGISTRY_VERSION_REPORT_SCHEMA_VERSION: u32 = 2;
5#[cfg(feature = "nns-host")]
6pub(super) const NNS_CERTIFIED_REGISTRY_DELTA_BATCH_SCHEMA_VERSION: u32 = 3;
7
8///
9/// NnsRegistryVersionRequest
10///
11/// Request for the current NNS registry version report.
12///
13
14#[derive(Clone, Debug, Eq, PartialEq)]
15pub struct NnsRegistryVersionRequest {
16 pub network: String,
17 pub source_endpoint: String,
18 pub now_unix_secs: u64,
19}
20
21impl NnsRegistryVersionRequest {
22 #[must_use]
23 pub fn new(
24 network: impl Into<String>,
25 source_endpoint: impl Into<String>,
26 now_unix_secs: u64,
27 ) -> Self {
28 Self {
29 network: network.into(),
30 source_endpoint: source_endpoint.into(),
31 now_unix_secs,
32 }
33 }
34}
35
36///
37/// NnsRegistryVersionReport
38///
39/// Current NNS registry version report with source metadata.
40///
41
42#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
43pub struct NnsRegistryVersionReport {
44 pub schema_version: u32,
45 pub network: String,
46 pub registry_canister_id: String,
47 pub registry_version: u64,
48 pub fetched_at: String,
49 pub source_endpoint: String,
50 pub fetched_by: String,
51 /// Authenticated evidence for the certified latest version.
52 pub certification: NnsRegistryCertification,
53}
54
55///
56/// NnsRegistryCertification
57///
58/// Authenticated certificate and hash-tree evidence for the Registry version.
59///
60
61#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
62pub struct NnsRegistryCertification {
63 /// Whether the certificate and version witness were authenticated.
64 pub certificate_verified: bool,
65 /// Certificate time in raw nanoseconds since the Unix epoch.
66 pub certificate_time_nanos: u64,
67 /// Certificate time formatted at UTC second precision.
68 pub certificate_time: String,
69 /// SHA-256 digest of the trusted DER-encoded root key.
70 pub root_key_digest: String,
71 /// CBOR system certificate encoded as lowercase hexadecimal.
72 pub certificate_hex: String,
73 /// Raw certificate length in bytes.
74 pub certificate_bytes: usize,
75 /// Protobuf mixed hash-tree witness encoded as lowercase hexadecimal.
76 pub hash_tree_hex: String,
77 /// Encoded mixed hash-tree witness length in bytes.
78 pub hash_tree_bytes: usize,
79}
80
81///
82/// NnsCertifiedRegistryDeltaBatchRequest
83///
84/// Request for one authenticated, bounded Registry delta batch.
85///
86
87#[derive(Clone, Debug, Eq, PartialEq)]
88pub struct NnsCertifiedRegistryDeltaBatchRequest {
89 /// Network identity; only mainnet `ic` is supported.
90 pub network: String,
91 /// Replica endpoint used for the certified query.
92 pub source_endpoint: String,
93 /// Last Registry version already held by the caller.
94 pub requested_version: u64,
95 /// Caller observation time used to validate certificate freshness.
96 pub now_unix_secs: u64,
97}
98
99impl NnsCertifiedRegistryDeltaBatchRequest {
100 /// Create a request for the batch immediately after `requested_version`.
101 #[must_use]
102 pub fn new(
103 network: impl Into<String>,
104 source_endpoint: impl Into<String>,
105 requested_version: u64,
106 now_unix_secs: u64,
107 ) -> Self {
108 Self {
109 network: network.into(),
110 source_endpoint: source_endpoint.into(),
111 requested_version,
112 now_unix_secs,
113 }
114 }
115}
116
117///
118/// NnsCertifiedRegistryDeltaBatchReport
119///
120/// Authenticated contiguous Registry mutations returned by one bounded query.
121///
122
123#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
124pub struct NnsCertifiedRegistryDeltaBatchReport {
125 /// Report schema version.
126 pub schema_version: u32,
127 /// Network identity.
128 pub network: String,
129 /// Canonical mainnet Registry canister principal.
130 pub registry_canister_id: String,
131 /// Version after which deltas were requested.
132 pub requested_version: u64,
133 /// Latest Registry version authenticated by the same response.
134 pub certified_latest_version: u64,
135 /// First visible contiguous delta version, when any.
136 pub first_version: Option<u64>,
137 /// Last visible contiguous delta version, when any.
138 pub last_version: Option<u64>,
139 /// Number of visible Registry versions.
140 pub version_count: usize,
141 /// Number of mutations across all visible versions.
142 pub mutation_count: usize,
143 /// Number of preconditions across all visible versions.
144 pub precondition_count: usize,
145 /// Complete inline value bytes across all visible mutations.
146 pub inline_value_bytes: usize,
147 /// Complete reconstructed bytes for chunk-referenced values.
148 pub chunk_value_bytes: usize,
149 /// Complete inline and reconstructed value bytes.
150 pub value_bytes: usize,
151 /// Number of certified chunk references across all visible mutations.
152 pub chunk_reference_count: usize,
153 /// Complete bytes retained once per unique content-addressed chunk.
154 pub chunk_evidence_bytes: usize,
155 /// Whether later certified versions require another explicit request.
156 pub more_available: bool,
157 /// Caller collection time.
158 pub fetched_at: String,
159 /// Exact replica endpoint used by the source.
160 pub source_endpoint: String,
161 /// Collector identity.
162 pub fetched_by: String,
163 /// Number of Registry queries made for this batch.
164 pub query_call_count: u64,
165 /// Number of content-addressed `get_chunk` queries made for this batch.
166 pub chunk_query_call_count: u64,
167 /// Encoded certified delta response size returned by the replica.
168 pub certified_response_bytes: usize,
169 /// Encoded `get_chunk` response bytes returned by the replica.
170 pub chunk_response_bytes: usize,
171 /// Total encoded response bytes returned across every Registry query.
172 pub response_bytes: usize,
173 /// Resource ceilings applied while validating the batch.
174 pub limits: NnsCertifiedRegistryDeltaLimits,
175 /// Ordered contiguous Registry versions.
176 pub versions: Vec<NnsCertifiedRegistryDeltaVersion>,
177 /// Unique hash-verified chunks in canonical digest order.
178 pub chunk_evidence: Vec<NnsCertifiedRegistryChunkEvidence>,
179 /// Certificate and mixed-tree evidence authenticating the batch.
180 pub certification: NnsRegistryCertification,
181}
182
183///
184/// NnsCertifiedRegistryChunkEvidence
185///
186/// One unique Registry chunk retained with its content-addressed digest.
187///
188
189#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
190pub struct NnsCertifiedRegistryChunkEvidence {
191 /// SHA-256 digest as exactly 64 lowercase hexadecimal characters.
192 pub sha256_hex: String,
193 /// Complete decoded chunk content as lowercase hexadecimal.
194 pub content_hex: String,
195}
196
197///
198/// NnsCertifiedRegistryDeltaLimits
199///
200/// Fixed resource ceilings enforced by the certified delta validator.
201///
202
203#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
204pub struct NnsCertifiedRegistryDeltaLimits {
205 /// Maximum visible Registry versions in one response.
206 pub max_versions: usize,
207 /// Maximum total mutations in one response.
208 pub max_mutations: usize,
209 /// Maximum total preconditions in one response.
210 pub max_preconditions: usize,
211 /// Maximum bytes in one Registry key.
212 pub max_key_bytes: usize,
213 /// Maximum combined inline value bytes.
214 pub max_inline_value_bytes: usize,
215 /// Maximum chunk references across the complete batch.
216 pub max_chunk_references: usize,
217 /// Maximum decoded bytes in one retrieved Registry chunk.
218 pub max_chunk_bytes: usize,
219 /// Maximum reconstructed bytes in one Registry value.
220 pub max_reconstructed_value_bytes: usize,
221 /// Maximum combined inline and reconstructed value bytes.
222 pub max_value_bytes: usize,
223 /// Maximum encoded bytes across all `get_chunk` responses.
224 pub max_chunk_response_bytes: usize,
225 /// Maximum encoded bytes accepted for any single agent response body.
226 pub max_response_body_bytes: usize,
227}
228
229///
230/// NnsCertifiedRegistryDeltaVersion
231///
232/// One Registry version and its ordered atomic mutation contents.
233///
234
235#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
236pub struct NnsCertifiedRegistryDeltaVersion {
237 /// Registry version authenticated by the delta-map label.
238 pub version: u64,
239 /// Registry-assigned mutation timestamp in nanoseconds since the Unix epoch.
240 pub timestamp_nanoseconds: u64,
241 /// Ordered mutations applied in this atomic version.
242 pub mutations: Vec<NnsCertifiedRegistryMutation>,
243 /// Preconditions attached to this atomic mutation.
244 pub preconditions: Vec<NnsCertifiedRegistryPrecondition>,
245}
246
247///
248/// NnsCertifiedRegistryMutation
249///
250/// One certified Registry mutation with raw and typed operation evidence.
251///
252
253#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
254pub struct NnsCertifiedRegistryMutation {
255 /// Raw upstream protobuf mutation discriminant.
256 pub mutation_type: i32,
257 /// Supported meaning of the raw discriminant.
258 pub mutation_kind: NnsCertifiedRegistryMutationKind,
259 /// Raw Registry key bytes as lowercase hexadecimal.
260 pub key_hex: String,
261 /// Original certified representation of this mutation's value.
262 pub value_encoding: NnsCertifiedRegistryValueEncoding,
263 /// Ordered certified chunk digests as lowercase hexadecimal.
264 pub chunk_sha256_hexes: Vec<String>,
265 /// Complete value bytes as lowercase hexadecimal.
266 ///
267 /// Usually absent for deletes, but historical committed deletes may retain
268 /// ignored content that replay must preserve as raw evidence.
269 pub value_hex: Option<String>,
270}
271
272///
273/// NnsCertifiedRegistryValueEncoding
274///
275/// Original value representation committed by a certified Registry mutation.
276///
277
278#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
279#[serde(rename_all = "snake_case")]
280pub enum NnsCertifiedRegistryValueEncoding {
281 /// Delete mutation with no retained value content.
282 Absent,
283 /// Value bytes carried directly in the certified delta response, including ignored delete content.
284 Inline,
285 /// Value reconstructed from certified SHA-256 chunk references, including ignored delete content.
286 Chunked,
287}
288
289///
290/// NnsCertifiedRegistryMutationKind
291///
292/// Supported native Registry mutation operations.
293///
294
295#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
296#[serde(rename_all = "snake_case")]
297pub enum NnsCertifiedRegistryMutationKind {
298 /// Insert a key that must not already exist.
299 Insert,
300 /// Update a key that must already exist.
301 Update,
302 /// Delete a key.
303 Delete,
304 /// Insert or update a key.
305 Upsert,
306}
307
308#[cfg(feature = "nns-host")]
309impl NnsCertifiedRegistryMutationKind {
310 pub(super) const fn raw_type(self) -> i32 {
311 match self {
312 Self::Insert => 0,
313 Self::Update => 1,
314 Self::Delete => 2,
315 Self::Upsert => 4,
316 }
317 }
318
319 pub(super) const fn from_raw_type(value: i32) -> Option<Self> {
320 match value {
321 0 => Some(Self::Insert),
322 1 => Some(Self::Update),
323 2 => Some(Self::Delete),
324 4 => Some(Self::Upsert),
325 _ => None,
326 }
327 }
328}
329
330///
331/// NnsCertifiedRegistryPrecondition
332///
333/// One key-version precondition attached to a certified atomic mutation.
334///
335
336#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
337pub struct NnsCertifiedRegistryPrecondition {
338 /// Raw Registry key bytes as lowercase hexadecimal.
339 pub key_hex: String,
340 /// Required version of the Registry key.
341 pub expected_version: u64,
342}