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}