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
54fn unique_subset(values: &[String], supported: &[&str], field: &str) -> Result<()> {
55 let unique: BTreeSet<_> = values.iter().collect();
56 ensure!(!values.is_empty(), "dataset {field} must not be empty");
57 ensure!(unique.len() == values.len(), "duplicate dataset {field}");
58 ensure!(
59 values
60 .iter()
61 .all(|value| supported.contains(&value.as_str())),
62 "unsupported dataset {field}"
63 );
64 Ok(())
65}
66
67fn valid_date(value: &str) -> bool {
68 let bytes = value.as_bytes();
69 if bytes.len() != 10
70 || bytes[4] != b'-'
71 || bytes[7] != b'-'
72 || !bytes
73 .iter()
74 .enumerate()
75 .all(|(index, byte)| index == 4 || index == 7 || byte.is_ascii_digit())
76 {
77 return false;
78 }
79 let (Ok(year), Ok(month), Ok(day)) = (
80 value[0..4].parse::<u32>(),
81 value[5..7].parse::<u32>(),
82 value[8..10].parse::<u32>(),
83 ) else {
84 return false;
85 };
86 let leap = year.is_multiple_of(4) && (!year.is_multiple_of(100) || year.is_multiple_of(400));
87 let days = match month {
88 1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
89 4 | 6 | 9 | 11 => 30,
90 2 if leap => 29,
91 2 => 28,
92 _ => 0,
93 };
94 year > 0 && day > 0 && day <= days
95}
96
97impl Dataset {
98 pub fn bundled() -> Result<Self> {
99 Self::parse(BUNDLED)
100 }
101
102 pub fn parse(input: &str) -> Result<Self> {
103 let document: Document =
104 serde_json::from_str(input).context("invalid compatibility dataset JSON")?;
105 ensure!(
106 document.schema_version == 1,
107 "unsupported dataset schema_version"
108 );
109 ensure!(
110 document.engine_schema == 1,
111 "dataset requires an unsupported engine schema"
112 );
113 ensure!(
114 !document.revision.trim().is_empty(),
115 "dataset revision is required"
116 );
117 ensure!(
118 document.records.len() == 1,
119 "exactly one SC201 record is required; overlapping records are not supported"
120 );
121 let record = document.records.into_iter().next().expect("length checked");
122 ensure!(
123 record.rule_id == "SC201" && record.id == "rpc-read-version-acceptance",
124 "unsupported compatibility record"
125 );
126 ensure!(
127 record.revision > 0 && !record.rule_name.trim().is_empty(),
128 "record name and positive revision are required"
129 );
130 ensure!(
131 record.evidence_kind == "upstream_documentation",
132 "unsupported evidence kind"
133 );
134 let date = record.verified_on.as_bytes();
135 ensure!(
136 date.len() == 10
137 && date[4] == b'-'
138 && date[7] == b'-'
139 && date
140 .iter()
141 .enumerate()
142 .all(|(i, b)| i == 4 || i == 7 || b.is_ascii_digit()),
143 "verified_on must be YYYY-MM-DD"
144 );
145 let year: u32 = record.verified_on[0..4].parse()?;
146 let month: u32 = record.verified_on[5..7].parse()?;
147 let day: u32 = record.verified_on[8..10].parse()?;
148 let leap =
149 year.is_multiple_of(4) && (!year.is_multiple_of(100) || year.is_multiple_of(400));
150 let days = match month {
151 1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
152 4 | 6 | 9 | 11 => 30,
153 2 if leap => 29,
154 2 => 28,
155 _ => 0,
156 };
157 ensure!(
158 year > 0 && day > 0 && day <= days,
159 "verified_on must be a valid calendar date"
160 );
161 ensure!(
162 !record.sources.is_empty()
163 && record.sources.iter().all(|url| url.starts_with("https://")
164 && url.len() > 8
165 && !url.chars().any(char::is_whitespace)),
166 "record requires HTTPS source references"
167 );
168 ensure!(
169 !record.notes.trim().is_empty(),
170 "record requires scope notes"
171 );
172 unique_subset(
173 &record.reviewed_versions,
174 &["legacy", "v0", "v1"],
175 "reviewed_versions",
176 )?;
177 unique_subset(
178 &record.reviewed_encodings,
179 &["json", "jsonParsed", "base64", "base58"],
180 "reviewed_encodings",
181 )?;
182 unique_subset(&record.methods, &["getBlock", "getTransaction"], "methods")?;
183 unique_subset(
184 &record.body_free_block_details,
185 &["none", "signatures"],
186 "body_free_block_details",
187 )?;
188 let expected: Vec<_> = crate::catalog::RULES
189 .iter()
190 .filter(|rule| rule.metadata == crate::catalog::MetadataOwner::Dataset)
191 .map(|rule| rule.id)
192 .collect();
193 ensure!(
194 document.rules.len() == expected.len(),
195 "dataset requires all eight compatibility rule records"
196 );
197 let mut seen = BTreeSet::new();
198 for rule in &document.rules {
199 ensure!(
200 expected.contains(&rule.rule_id.as_str()),
201 "unsupported rule record {}",
202 rule.rule_id
203 );
204 ensure!(
205 seen.insert(rule.rule_id.clone()),
206 "duplicate rule record {}",
207 rule.rule_id
208 );
209 ensure!(
210 rule.revision > 0 && !rule.rule_name.trim().is_empty(),
211 "rule metadata is incomplete"
212 );
213 ensure!(
214 valid_date(&rule.verified_on),
215 "verified_on must be a valid calendar date"
216 );
217 ensure!(
218 !rule.sources.is_empty()
219 && rule
220 .sources
221 .iter()
222 .all(|url| url.starts_with("https://")
223 && !url.chars().any(char::is_whitespace)),
224 "record requires HTTPS source references"
225 );
226 ensure!(!rule.notes.trim().is_empty(), "record requires scope notes");
227 }
228 Ok(Self {
229 revision: document.revision,
230 digest: crate::digest(input.as_bytes()),
231 record,
232 rules: document.rules,
233 })
234 }
235
236 pub fn rpc_record(&self) -> &RpcRecord {
237 &self.record
238 }
239
240 pub fn rule(&self, id: &str) -> &RuleRecord {
241 self.rules
242 .iter()
243 .find(|rule| rule.rule_id == id)
244 .expect("validated bundled rule")
245 }
246}
247
248#[cfg(test)]
249mod tests {
250 use super::*;
251
252 #[test]
253 fn invalid_data_never_becomes_empty_success() {
254 let original: serde_json::Value = serde_json::from_str(BUNDLED).unwrap();
255 for field in ["schema_version", "engine_schema"] {
256 let mut value = original.clone();
257 value[field] = 99.into();
258 assert!(Dataset::parse(&value.to_string()).is_err());
259 }
260 let mut duplicate = original.clone();
261 let record = duplicate["records"][0].clone();
262 duplicate["records"].as_array_mut().unwrap().push(record);
263 assert!(Dataset::parse(&duplicate.to_string()).is_err());
264 for field in ["sources", "reviewed_versions", "methods"] {
265 let mut value = original.clone();
266 value["records"][0][field] = serde_json::json!([]);
267 assert!(Dataset::parse(&value.to_string()).is_err());
268 }
269 let mut future = original;
270 future["records"][0]["reviewed_versions"] = serde_json::json!(["v2"]);
271 assert!(Dataset::parse(&future.to_string()).is_err());
272 }
273
274 #[test]
275 fn invalid_review_dates_are_rejected() {
276 let mut document: serde_json::Value = serde_json::from_str(BUNDLED).unwrap();
277 for date in [
278 "2026-02-29",
279 "2026-99-01",
280 "2026-01-00",
281 "0000-01-01",
282 "not-a-date",
283 ] {
284 document["records"][0]["verified_on"] = date.into();
285 assert!(Dataset::parse(&document.to_string()).is_err(), "{date}");
286 }
287 document["records"][0]["verified_on"] = "2024-02-29".into();
288 assert!(Dataset::parse(&document.to_string()).is_ok());
289 }
290}