Skip to main content

foundry_config/
symbolic.rs

1//! Configuration for symbolic testing.
2
3use serde::{Deserialize, Serialize};
4use std::collections::BTreeMap;
5
6/// Storage modelling mode for symbolic tests.
7#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
8#[serde(rename_all = "snake_case")]
9pub enum SymbolicStorageLayout {
10    /// Model Solidity storage layout precisely where the symbolic executor knows the layout shape.
11    #[default]
12    Solidity,
13    /// Treat every storage read as potentially arbitrary symbolic storage.
14    Generic,
15    /// Treat unwritten symbolic storage reads as zero.
16    ZeroInit,
17}
18
19/// Pending symbolic path exploration order.
20#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
21#[serde(rename_all = "snake_case")]
22pub enum SymbolicExplorationOrder {
23    /// Explore pending paths in first-in, first-out order.
24    #[default]
25    Bfs,
26    /// Explore pending paths in last-in, first-out order.
27    Dfs,
28}
29
30/// Configuration for symbolic testing.
31#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
32pub struct SymbolicConfig {
33    /// Whether symbolic tests are enabled.
34    pub enabled: bool,
35    /// Whether fuzz tests should be symbolically concretized into fuzz corpus seeds.
36    pub seed_corpus: bool,
37    /// Whether fuzz corpus seeds should guide symbolic fuzz-test exploration.
38    pub use_fuzz_corpus: bool,
39    /// Maximum number of fuzz corpus seeds to import for one symbolic run.
40    pub corpus_seed_limit: usize,
41    /// Whether fuzz branch frontiers should guide targeted symbolic fuzz-test seeding.
42    pub use_fuzz_frontiers: bool,
43    /// Whether invariant frontier seeding should first search for a property-breaking call.
44    #[serde(default)]
45    pub check_invariant_frontiers: bool,
46    /// Whether one bounded symbolic worker assists a running invariant campaign.
47    ///
48    /// Off by default. Uses `timeout`, `max_solver_queries`, and `frontier_limit` as
49    /// campaign-wide budgets. Candidates must pass normal concrete campaign execution.
50    #[serde(default)]
51    pub live: bool,
52    /// Maximum imported frontiers per symbolic run or submitted live frontiers per campaign.
53    pub frontier_limit: usize,
54    /// Fuzz branch frontier artifact IDs to import. Empty imports by artifact order.
55    #[serde(default, skip_serializing_if = "Vec::is_empty")]
56    pub frontier_ids: Vec<u64>,
57    /// Fuzz branch frontier comparison program counters to import. Empty imports any PC.
58    #[serde(default, skip_serializing_if = "Vec::is_empty")]
59    pub frontier_pcs: Vec<usize>,
60    /// Fuzz branch frontier calldata selectors to import. Empty imports any selector.
61    #[serde(default, skip_serializing_if = "Vec::is_empty")]
62    pub frontier_selectors: Vec<String>,
63    /// Solver executable to invoke.
64    pub solver: String,
65    /// Exact solver command to invoke. When set, this overrides `solver`.
66    #[serde(default, skip_serializing_if = "Option::is_none")]
67    pub solver_command: Option<String>,
68    /// Solver names or exact commands to race in parallel. Ignored when `solver_command` is set.
69    #[serde(default, skip_serializing_if = "Vec::is_empty")]
70    pub solver_portfolio: Vec<String>,
71    /// Optional SMT solver timeout in seconds. Also bounds the stateless deferred hard-arithmetic
72    /// solver phase and wall-clock symbolic invariant exploration before falling back to fuzzing.
73    pub timeout: Option<u32>,
74    /// Halmos-compatible loop bound accepted by config and annotations.
75    #[serde(default, rename = "loop", skip_serializing_if = "Option::is_none")]
76    pub loop_bound: Option<u32>,
77    /// Halmos-compatible execution depth alias. When set, this overrides `max_depth`.
78    #[serde(default, skip_serializing_if = "Option::is_none")]
79    pub depth: Option<u32>,
80    /// Halmos-compatible path width alias. When set, this overrides `max_paths`.
81    #[serde(default, skip_serializing_if = "Option::is_none")]
82    pub width: Option<u32>,
83    /// Maximum number of opcodes to execute along a path.
84    pub max_depth: u32,
85    /// Maximum number of symbolic paths to explore.
86    pub max_paths: u32,
87    /// Maximum number of calls in a bounded symbolic invariant sequence.
88    pub invariant_depth: u32,
89    /// Order used to select the next pending symbolic path.
90    #[serde(default)]
91    pub exploration_order: SymbolicExplorationOrder,
92    /// Maximum number of solver queries.
93    pub max_solver_queries: u32,
94    /// Default bounded length for dynamic ABI inputs.
95    pub default_dynamic_length: u32,
96    /// Maximum permitted bounded length for a dynamic ABI input.
97    pub max_dynamic_length: u32,
98    /// Per-dynamic-leaf bounded lengths, applied in ABI traversal order.
99    pub array_lengths: Vec<u32>,
100    /// Per-symbolic-input bounded lengths keyed by ABI argument name or generated symbolic name.
101    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
102    pub dynamic_lengths: BTreeMap<String, Vec<u32>>,
103    /// Default bounded lengths for dynamic ABI arrays without an explicit length.
104    #[serde(default, skip_serializing_if = "Vec::is_empty")]
105    pub default_array_lengths: Vec<u32>,
106    /// Default bounded lengths for ABI `bytes` and `string` values without an explicit length.
107    #[serde(default, skip_serializing_if = "Vec::is_empty")]
108    pub default_bytes_lengths: Vec<u32>,
109    /// Maximum symbolic calldata size in bytes.
110    pub max_calldata_bytes: u32,
111    /// Whether symbolic call targets may be expanded over known deployed contracts.
112    pub symbolic_call_targets: bool,
113    /// Whether to dump SMT-LIB queries before invoking the configured solver.
114    pub dump_smt: bool,
115    /// Storage modelling mode used for symbolic storage reads.
116    pub storage_layout: SymbolicStorageLayout,
117}
118
119impl Default for SymbolicConfig {
120    fn default() -> Self {
121        Self {
122            enabled: false,
123            seed_corpus: false,
124            use_fuzz_corpus: false,
125            corpus_seed_limit: 32,
126            use_fuzz_frontiers: false,
127            check_invariant_frontiers: false,
128            live: false,
129            frontier_limit: 256,
130            frontier_ids: Vec::new(),
131            frontier_pcs: Vec::new(),
132            frontier_selectors: Vec::new(),
133            solver: "z3".to_string(),
134            solver_command: None,
135            solver_portfolio: Vec::new(),
136            timeout: Some(30),
137            loop_bound: None,
138            depth: None,
139            width: None,
140            max_depth: 10_000,
141            max_paths: 1_024,
142            invariant_depth: 10,
143            exploration_order: SymbolicExplorationOrder::default(),
144            max_solver_queries: 10_000,
145            default_dynamic_length: 2,
146            max_dynamic_length: 256,
147            array_lengths: Vec::new(),
148            dynamic_lengths: BTreeMap::new(),
149            default_array_lengths: Vec::new(),
150            default_bytes_lengths: Vec::new(),
151            max_calldata_bytes: 4_096,
152            symbolic_call_targets: false,
153            dump_smt: false,
154            storage_layout: SymbolicStorageLayout::Solidity,
155        }
156    }
157}
158
159impl SymbolicConfig {
160    /// Returns the effective per-path opcode depth limit used by the symbolic executor.
161    ///
162    /// The Halmos-compatible `depth` alias takes precedence over `max_depth` so inline
163    /// compatibility annotations and native Foundry config resolve to one internal limit.
164    pub fn execution_depth(&self) -> u32 {
165        self.depth.unwrap_or(self.max_depth)
166    }
167
168    /// Returns the effective symbolic path width limit used by the symbolic executor.
169    ///
170    /// The Halmos-compatible `width` alias takes precedence over `max_paths` so both
171    /// configuration spellings feed the same path exploration budget.
172    pub fn path_width(&self) -> u32 {
173        self.width.unwrap_or(self.max_paths)
174    }
175}
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180
181    #[test]
182    fn missing_exploration_order_defaults_to_bfs() {
183        let value = serde_json::json!({
184            "enabled": false,
185            "seed_corpus": false,
186            "use_fuzz_corpus": false,
187            "corpus_seed_limit": 32,
188            "use_fuzz_frontiers": false,
189            "frontier_limit": 256,
190            "frontier_ids": [],
191            "frontier_pcs": [],
192            "frontier_selectors": [],
193            "solver": "z3",
194            "timeout": 30,
195            "max_depth": 10000,
196            "max_paths": 1024,
197            "invariant_depth": 10,
198            "max_solver_queries": 10000,
199            "default_dynamic_length": 2,
200            "max_dynamic_length": 256,
201            "array_lengths": [],
202            "max_calldata_bytes": 4096,
203            "symbolic_call_targets": false,
204            "dump_smt": false,
205            "storage_layout": "solidity"
206        });
207
208        let config: SymbolicConfig = serde_json::from_value(value).unwrap();
209
210        assert_eq!(config.exploration_order, SymbolicExplorationOrder::Bfs);
211        assert!(!config.live);
212    }
213}