Skip to main content

solcompat_core/
data.rs

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}