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 = 2;
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 /// Whether later certified versions require another explicit request.
154 pub more_available: bool,
155 /// Caller collection time.
156 pub fetched_at: String,
157 /// Exact replica endpoint used by the source.
158 pub source_endpoint: String,
159 /// Collector identity.
160 pub fetched_by: String,
161 /// Number of Registry queries made for this batch.
162 pub query_call_count: u64,
163 /// Number of content-addressed `get_chunk` queries made for this batch.
164 pub chunk_query_call_count: u64,
165 /// Encoded certified delta response size returned by the replica.
166 pub certified_response_bytes: usize,
167 /// Encoded `get_chunk` response bytes returned by the replica.
168 pub chunk_response_bytes: usize,
169 /// Total encoded response bytes returned across every Registry query.
170 pub response_bytes: usize,
171 /// Resource ceilings applied while validating the batch.
172 pub limits: NnsCertifiedRegistryDeltaLimits,
173 /// Ordered contiguous Registry versions.
174 pub versions: Vec<NnsCertifiedRegistryDeltaVersion>,
175 /// Certificate and mixed-tree evidence authenticating the batch.
176 pub certification: NnsRegistryCertification,
177}
178
179///
180/// NnsCertifiedRegistryDeltaLimits
181///
182/// Fixed resource ceilings enforced by the certified delta validator.
183///
184
185#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
186pub struct NnsCertifiedRegistryDeltaLimits {
187 /// Maximum visible Registry versions in one response.
188 pub max_versions: usize,
189 /// Maximum total mutations in one response.
190 pub max_mutations: usize,
191 /// Maximum total preconditions in one response.
192 pub max_preconditions: usize,
193 /// Maximum bytes in one Registry key.
194 pub max_key_bytes: usize,
195 /// Maximum combined inline value bytes.
196 pub max_inline_value_bytes: usize,
197 /// Maximum chunk references across the complete batch.
198 pub max_chunk_references: usize,
199 /// Maximum decoded bytes in one retrieved Registry chunk.
200 pub max_chunk_bytes: usize,
201 /// Maximum reconstructed bytes in one Registry value.
202 pub max_reconstructed_value_bytes: usize,
203 /// Maximum combined inline and reconstructed value bytes.
204 pub max_value_bytes: usize,
205 /// Maximum encoded bytes across all `get_chunk` responses.
206 pub max_chunk_response_bytes: usize,
207 /// Maximum encoded bytes accepted for any single agent response body.
208 pub max_response_body_bytes: usize,
209}
210
211///
212/// NnsCertifiedRegistryDeltaVersion
213///
214/// One Registry version and its ordered atomic mutation contents.
215///
216
217#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
218pub struct NnsCertifiedRegistryDeltaVersion {
219 /// Registry version authenticated by the delta-map label.
220 pub version: u64,
221 /// Registry-assigned mutation timestamp in nanoseconds since the Unix epoch.
222 pub timestamp_nanoseconds: u64,
223 /// Ordered mutations applied in this atomic version.
224 pub mutations: Vec<NnsCertifiedRegistryMutation>,
225 /// Preconditions attached to this atomic mutation.
226 pub preconditions: Vec<NnsCertifiedRegistryPrecondition>,
227}
228
229///
230/// NnsCertifiedRegistryMutation
231///
232/// One certified Registry mutation with raw and typed operation evidence.
233///
234
235#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
236pub struct NnsCertifiedRegistryMutation {
237 /// Raw upstream protobuf mutation discriminant.
238 pub mutation_type: i32,
239 /// Supported meaning of the raw discriminant.
240 pub mutation_kind: NnsCertifiedRegistryMutationKind,
241 /// Raw Registry key bytes as lowercase hexadecimal.
242 pub key_hex: String,
243 /// Original certified representation of this mutation's value.
244 pub value_encoding: NnsCertifiedRegistryValueEncoding,
245 /// Ordered certified chunk digests as lowercase hexadecimal.
246 pub chunk_sha256_hexes: Vec<String>,
247 /// Complete value bytes as lowercase hexadecimal; absent for deletes.
248 pub value_hex: Option<String>,
249}
250
251///
252/// NnsCertifiedRegistryValueEncoding
253///
254/// Original value representation committed by a certified Registry mutation.
255///
256
257#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
258#[serde(rename_all = "snake_case")]
259pub enum NnsCertifiedRegistryValueEncoding {
260 /// Delete mutation with no value content.
261 Absent,
262 /// Value bytes carried directly in the certified delta response.
263 Inline,
264 /// Value reconstructed from certified SHA-256 chunk references.
265 Chunked,
266}
267
268///
269/// NnsCertifiedRegistryMutationKind
270///
271/// Supported native Registry mutation operations.
272///
273
274#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
275#[serde(rename_all = "snake_case")]
276pub enum NnsCertifiedRegistryMutationKind {
277 /// Insert a key that must not already exist.
278 Insert,
279 /// Update a key that must already exist.
280 Update,
281 /// Delete a key.
282 Delete,
283 /// Insert or update a key.
284 Upsert,
285}
286
287#[cfg(feature = "nns-host")]
288impl NnsCertifiedRegistryMutationKind {
289 pub(super) const fn raw_type(self) -> i32 {
290 match self {
291 Self::Insert => 0,
292 Self::Update => 1,
293 Self::Delete => 2,
294 Self::Upsert => 4,
295 }
296 }
297
298 pub(super) const fn from_raw_type(value: i32) -> Option<Self> {
299 match value {
300 0 => Some(Self::Insert),
301 1 => Some(Self::Update),
302 2 => Some(Self::Delete),
303 4 => Some(Self::Upsert),
304 _ => None,
305 }
306 }
307}
308
309///
310/// NnsCertifiedRegistryPrecondition
311///
312/// One key-version precondition attached to a certified atomic mutation.
313///
314
315#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
316pub struct NnsCertifiedRegistryPrecondition {
317 /// Raw Registry key bytes as lowercase hexadecimal.
318 pub key_hex: String,
319 /// Required version of the Registry key.
320 pub expected_version: u64,
321}