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
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}