1use anyhow::{ensure, Context, Result};
2use serde::{Deserialize, Serialize};
3use std::collections::BTreeSet;
4
5const BUNDLED: &str = include_str!("../compatibility/records/rpc-read-contracts.json");
6
7#[derive(Clone, Debug, Deserialize, Serialize)]
8#[serde(deny_unknown_fields)]
9pub struct RpcRecord {
10 pub id: String,
11 pub revision: u32,
12 pub rule_id: String,
13 pub rule_name: String,
14 pub verified_on: String,
15 pub evidence_kind: String,
16 pub sources: Vec<String>,
17 pub reviewed_versions: Vec<String>,
18 pub reviewed_encodings: Vec<String>,
19 pub methods: Vec<String>,
20 pub body_free_block_details: Vec<String>,
21 pub notes: String,
22}
23
24#[derive(Debug, Deserialize)]
25#[serde(deny_unknown_fields)]
26struct Document {
27 schema_version: u32,
28 revision: String,
29 engine_schema: u32,
30 records: Vec<RpcRecord>,
31 #[serde(default)]
32 rules: Vec<RuleRecord>,
33}
34
35#[derive(Clone, Debug, Deserialize, Serialize)]
36#[serde(deny_unknown_fields)]
37pub struct RuleRecord {
38 pub rule_id: String,
39 pub rule_name: String,
40 pub revision: u32,
41 pub verified_on: String,
42 pub sources: Vec<String>,
43 pub notes: String,
44}
45
46#[derive(Clone, Debug)]
47pub struct Dataset {
48 pub revision: String,
49 pub digest: String,
50 record: RpcRecord,
51 rules: Vec<RuleRecord>,
52}
53
54#[derive(Debug, Deserialize)]
55#[serde(deny_unknown_fields)]
56struct TargetDocument {
57 schema_version: u32,
58 id: String,
59 #[serde(default)]
60 conditional: bool,
61 #[serde(default)]
62 artifact_policies: Vec<crate::ArtifactPolicy>,
63}
64
65impl crate::AnalysisTarget {
66 pub fn named(id: &str) -> Result<Self> {
67 ensure!(
68 matches!(
69 id,
70 "local" | "mainnet-beta-2026-09-26" | "future-sbpfv3-deployment"
71 ),
72 "unsupported target: {id}"
73 );
74 let artifact_policies = if id == "future-sbpfv3-deployment" {
75 vec![crate::ArtifactPolicy {
76 loader: "loader-v3".into(),
77 operations: vec!["deploy".into(), "finalize".into(), "upgrade".into()],
78 allowed_sbpf_versions: vec!["v3".into()],
79 }]
80 } else {
81 vec![]
82 };
83 Ok(Self {
84 id: id.into(),
85 conditional: id == "future-sbpfv3-deployment",
86 artifact_policies,
87 digest: None,
88 })
89 }
90
91 pub fn parse(input: &str) -> Result<Self> {
92 let document: TargetDocument =
93 serde_json::from_str(input).context("invalid target JSON")?;
94 ensure!(
95 document.schema_version == 1,
96 "unsupported target schema_version"
97 );
98 ensure!(!document.id.trim().is_empty(), "target id is required");
99 let mut pairs = BTreeSet::new();
100 for policy in &document.artifact_policies {
101 ensure!(
102 !policy.loader.trim().is_empty(),
103 "target loader is required"
104 );
105 ensure!(
106 !policy.operations.is_empty()
107 && policy.operations.iter().all(|operation| matches!(
108 operation.as_str(),
109 "deploy" | "upgrade" | "finalize" | "execute"
110 )),
111 "target has unsupported artifact operation"
112 );
113 ensure!(
114 !policy.allowed_sbpf_versions.is_empty()
115 && policy
116 .allowed_sbpf_versions
117 .iter()
118 .all(|version| matches!(version.as_str(), "v0" | "v1" | "v2" | "v3")),
119 "target has unsupported sBPF version"
120 );
121 for operation in &policy.operations {
122 ensure!(
123 pairs.insert((policy.loader.clone(), operation.clone())),
124 "overlapping target artifact policy"
125 );
126 }
127 }
128 Ok(Self {
129 id: document.id,
130 conditional: document.conditional,
131 artifact_policies: document.artifact_policies,
132 digest: Some(crate::digest(input.as_bytes())),
133 })
134 }
135}
136
137fn unique_subset(values: &[String], supported: &[&str], field: &str) -> Result<()> {
138 let unique: BTreeSet<_> = values.iter().collect();
139 ensure!(!values.is_empty(), "dataset {field} must not be empty");
140 ensure!(unique.len() == values.len(), "duplicate dataset {field}");
141 ensure!(
142 values
143 .iter()
144 .all(|value| supported.contains(&value.as_str())),
145 "unsupported dataset {field}"
146 );
147 Ok(())
148}
149
150fn valid_date(value: &str) -> bool {
151 let bytes = value.as_bytes();
152 if bytes.len() != 10
153 || bytes[4] != b'-'
154 || bytes[7] != b'-'
155 || !bytes
156 .iter()
157 .enumerate()
158 .all(|(index, byte)| index == 4 || index == 7 || byte.is_ascii_digit())
159 {
160 return false;
161 }
162 let (Ok(year), Ok(month), Ok(day)) = (
163 value[0..4].parse::<u32>(),
164 value[5..7].parse::<u32>(),
165 value[8..10].parse::<u32>(),
166 ) else {
167 return false;
168 };
169 let leap = year.is_multiple_of(4) && (!year.is_multiple_of(100) || year.is_multiple_of(400));
170 let days = match month {
171 1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
172 4 | 6 | 9 | 11 => 30,
173 2 if leap => 29,
174 2 => 28,
175 _ => 0,
176 };
177 year > 0 && day > 0 && day <= days
178}
179
180impl Dataset {
181 pub fn bundled() -> Result<Self> {
182 Self::parse(BUNDLED)
183 }
184
185 pub fn parse(input: &str) -> Result<Self> {
186 let document: Document =
187 serde_json::from_str(input).context("invalid compatibility dataset JSON")?;
188 ensure!(
189 document.schema_version == 1,
190 "unsupported dataset schema_version"
191 );
192 ensure!(
193 document.engine_schema == 1,
194 "dataset requires an unsupported engine schema"
195 );
196 ensure!(
197 !document.revision.trim().is_empty(),
198 "dataset revision is required"
199 );
200 ensure!(
201 document.records.len() == 1,
202 "exactly one SC201 record is required; overlapping records are not supported"
203 );
204 let record = document.records.into_iter().next().expect("length checked");
205 ensure!(
206 record.rule_id == "SC201" && record.id == "rpc-read-version-acceptance",
207 "unsupported compatibility record"
208 );
209 ensure!(
210 record.revision > 0 && !record.rule_name.trim().is_empty(),
211 "record name and positive revision are required"
212 );
213 ensure!(
214 record.evidence_kind == "upstream_documentation",
215 "unsupported evidence kind"
216 );
217 let date = record.verified_on.as_bytes();
218 ensure!(
219 date.len() == 10
220 && date[4] == b'-'
221 && date[7] == b'-'
222 && date
223 .iter()
224 .enumerate()
225 .all(|(i, b)| i == 4 || i == 7 || b.is_ascii_digit()),
226 "verified_on must be YYYY-MM-DD"
227 );
228 let year: u32 = record.verified_on[0..4].parse()?;
229 let month: u32 = record.verified_on[5..7].parse()?;
230 let day: u32 = record.verified_on[8..10].parse()?;
231 let leap =
232 year.is_multiple_of(4) && (!year.is_multiple_of(100) || year.is_multiple_of(400));
233 let days = match month {
234 1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
235 4 | 6 | 9 | 11 => 30,
236 2 if leap => 29,
237 2 => 28,
238 _ => 0,
239 };
240 ensure!(
241 year > 0 && day > 0 && day <= days,
242 "verified_on must be a valid calendar date"
243 );
244 ensure!(
245 !record.sources.is_empty()
246 && record.sources.iter().all(|url| url.starts_with("https://")
247 && url.len() > 8
248 && !url.chars().any(char::is_whitespace)),
249 "record requires HTTPS source references"
250 );
251 ensure!(
252 !record.notes.trim().is_empty(),
253 "record requires scope notes"
254 );
255 unique_subset(
256 &record.reviewed_versions,
257 &["legacy", "v0", "v1"],
258 "reviewed_versions",
259 )?;
260 unique_subset(
261 &record.reviewed_encodings,
262 &["json", "jsonParsed", "base64", "base58"],
263 "reviewed_encodings",
264 )?;
265 unique_subset(&record.methods, &["getBlock", "getTransaction"], "methods")?;
266 unique_subset(
267 &record.body_free_block_details,
268 &["none", "signatures"],
269 "body_free_block_details",
270 )?;
271 let expected = [
272 "SC001", "SC003", "SC102", "SC103", "SC104", "SC200", "SC302", "SC400",
273 ];
274 ensure!(
275 document.rules.len() == expected.len(),
276 "dataset requires all eight compatibility rule records"
277 );
278 let mut seen = BTreeSet::new();
279 for rule in &document.rules {
280 ensure!(
281 expected.contains(&rule.rule_id.as_str()),
282 "unsupported rule record {}",
283 rule.rule_id
284 );
285 ensure!(
286 seen.insert(rule.rule_id.clone()),
287 "duplicate rule record {}",
288 rule.rule_id
289 );
290 ensure!(
291 rule.revision > 0 && !rule.rule_name.trim().is_empty(),
292 "rule metadata is incomplete"
293 );
294 ensure!(
295 valid_date(&rule.verified_on),
296 "verified_on must be a valid calendar date"
297 );
298 ensure!(
299 !rule.sources.is_empty()
300 && rule
301 .sources
302 .iter()
303 .all(|url| url.starts_with("https://")
304 && !url.chars().any(char::is_whitespace)),
305 "record requires HTTPS source references"
306 );
307 ensure!(!rule.notes.trim().is_empty(), "record requires scope notes");
308 }
309 Ok(Self {
310 revision: document.revision,
311 digest: crate::digest(input.as_bytes()),
312 record,
313 rules: document.rules,
314 })
315 }
316
317 pub fn rpc_record(&self) -> &RpcRecord {
318 &self.record
319 }
320
321 pub fn rule(&self, id: &str) -> &RuleRecord {
322 self.rules
323 .iter()
324 .find(|rule| rule.rule_id == id)
325 .expect("validated bundled rule")
326 }
327}
328
329#[cfg(test)]
330mod tests {
331 use super::*;
332
333 #[test]
334 fn invalid_data_never_becomes_empty_success() {
335 let original: serde_json::Value = serde_json::from_str(BUNDLED).unwrap();
336 for field in ["schema_version", "engine_schema"] {
337 let mut value = original.clone();
338 value[field] = 99.into();
339 assert!(Dataset::parse(&value.to_string()).is_err());
340 }
341 let mut duplicate = original.clone();
342 let record = duplicate["records"][0].clone();
343 duplicate["records"].as_array_mut().unwrap().push(record);
344 assert!(Dataset::parse(&duplicate.to_string()).is_err());
345 for field in ["sources", "reviewed_versions", "methods"] {
346 let mut value = original.clone();
347 value["records"][0][field] = serde_json::json!([]);
348 assert!(Dataset::parse(&value.to_string()).is_err());
349 }
350 let mut future = original;
351 future["records"][0]["reviewed_versions"] = serde_json::json!(["v2"]);
352 assert!(Dataset::parse(&future.to_string()).is_err());
353 }
354
355 #[test]
356 fn invalid_review_dates_are_rejected() {
357 let mut document: serde_json::Value = serde_json::from_str(BUNDLED).unwrap();
358 for date in [
359 "2026-02-29",
360 "2026-99-01",
361 "2026-01-00",
362 "0000-01-01",
363 "not-a-date",
364 ] {
365 document["records"][0]["verified_on"] = date.into();
366 assert!(Dataset::parse(&document.to_string()).is_err(), "{date}");
367 }
368 document["records"][0]["verified_on"] = "2024-02-29".into();
369 assert!(Dataset::parse(&document.to_string()).is_ok());
370 }
371}