foundry_evm_fuzz/
lib.rs

1//! # foundry-evm-fuzz
2//!
3//! EVM fuzzing implementation using [`proptest`].
4
5#![cfg_attr(not(test), warn(unused_crate_dependencies))]
6#![cfg_attr(docsrs, feature(doc_cfg))]
7
8#[macro_use]
9extern crate tracing;
10
11use alloy_dyn_abi::{DynSolValue, JsonAbiExt};
12use alloy_primitives::{
13    Address, Bytes, Log, U256,
14    map::{AddressHashMap, HashMap},
15};
16use foundry_common::{calc, contracts::ContractsByAddress};
17use foundry_evm_core::Breakpoints;
18use foundry_evm_coverage::HitMaps;
19use foundry_evm_traces::{CallTraceArena, SparsedTraceArena};
20use itertools::Itertools;
21use serde::{Deserialize, Serialize};
22use std::{fmt, sync::Arc};
23
24pub use proptest::test_runner::{Config as FuzzConfig, Reason};
25
26mod error;
27pub use error::FuzzError;
28
29pub mod invariant;
30pub mod sequence;
31pub mod strategies;
32pub use strategies::LiteralMaps;
33
34mod inspector;
35pub use inspector::{Fuzzer, ObservedCall};
36
37/// Metadata needed to reproduce a fuzz run.
38#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize)]
39pub struct FuzzRunMetadata {
40    /// Seed used for the worker's input stream.
41    #[serde(default, rename = "fuzz_seed", skip_serializing_if = "Option::is_none")]
42    pub seed: Option<U256>,
43    /// 1-based run inside the worker's input stream.
44    #[serde(default, rename = "fuzz_run", skip_serializing_if = "Option::is_none")]
45    pub run: Option<u32>,
46    /// Worker that generated the input stream.
47    #[serde(default, rename = "fuzz_worker", skip_serializing_if = "Option::is_none")]
48    pub worker: Option<u32>,
49}
50
51impl FuzzRunMetadata {
52    /// Creates metadata for reproducing a fuzz run.
53    pub const fn new(seed: Option<U256>, run: Option<u32>, worker: Option<u32>) -> Self {
54        Self { seed, run, worker }
55    }
56}
57
58/// Details of a transaction generated by fuzz strategy for fuzzing a target.
59#[derive(Clone, Debug, Serialize, Deserialize)]
60pub struct BasicTxDetails {
61    /// Time (in seconds) to increase block timestamp before executing the tx.
62    #[serde(default, skip_serializing_if = "Option::is_none")]
63    pub warp: Option<U256>,
64    /// Number to increase block number before executing the tx.
65    #[serde(default, skip_serializing_if = "Option::is_none")]
66    pub roll: Option<U256>,
67    /// Transaction sender address.
68    pub sender: Address,
69    /// Transaction call details.
70    #[serde(flatten)]
71    pub call_details: CallDetails,
72}
73
74/// Call details of a transaction generated to fuzz.
75#[derive(Clone, Debug, Serialize, Deserialize)]
76pub struct CallDetails {
77    /// Address of target contract.
78    pub target: Address,
79    /// The data of the transaction.
80    pub calldata: Bytes,
81    /// Ether value to send with the transaction.
82    /// Uses `#[serde(default)]` for backwards compatibility with existing corpus files.
83    #[serde(default, skip_serializing_if = "Option::is_none")]
84    pub value: Option<U256>,
85}
86
87impl BasicTxDetails {
88    /// Returns an estimate of the serialized (JSON) size in bytes.
89    pub fn estimate_serialized_size(&self) -> usize {
90        size_of::<Self>() + self.call_details.calldata.len() * 2
91    }
92}
93
94#[derive(Clone, Debug, Serialize, Deserialize)]
95#[expect(clippy::large_enum_variant)]
96pub enum CounterExample {
97    /// Call used as a counter example for fuzz tests.
98    Single(BaseCounterExample),
99    /// Original sequence size and sequence of calls used as a counter example for invariant tests.
100    Sequence(usize, Vec<BaseCounterExample>),
101}
102
103#[derive(Clone, Debug, Serialize, Deserialize)]
104pub struct BaseCounterExample {
105    // Amount to increase block timestamp.
106    pub warp: Option<U256>,
107    // Amount to increase block number.
108    pub roll: Option<U256>,
109    /// Address which makes the call.
110    pub sender: Option<Address>,
111    /// Address to which to call to.
112    pub addr: Option<Address>,
113    /// The data to provide.
114    pub calldata: Bytes,
115    /// Ether value sent with the call.
116    #[serde(default, skip_serializing_if = "Option::is_none")]
117    pub value: Option<U256>,
118    /// Contract name if it exists.
119    pub contract_name: Option<String>,
120    /// Function name if it exists.
121    pub func_name: Option<String>,
122    /// Function signature if it exists.
123    pub signature: Option<String>,
124    /// Pretty formatted args used to call the function.
125    pub args: Option<String>,
126    /// Unformatted args used to call the function.
127    pub raw_args: Option<String>,
128    /// Counter example traces.
129    #[serde(skip)]
130    pub traces: Option<SparsedTraceArena>,
131    /// Whether to display sequence as solidity.
132    #[serde(skip)]
133    pub show_solidity: bool,
134    /// Fuzz metadata needed to reproduce this counterexample.
135    #[serde(flatten)]
136    pub fuzz: FuzzRunMetadata,
137}
138
139impl BaseCounterExample {
140    /// Creates counter example representing a step from invariant call sequence.
141    pub fn from_invariant_call(
142        tx: &BasicTxDetails,
143        contracts: &ContractsByAddress,
144        traces: Option<SparsedTraceArena>,
145        show_solidity: bool,
146    ) -> Self {
147        let sender = tx.sender;
148        let target = tx.call_details.target;
149        let bytes = &tx.call_details.calldata;
150        let value = tx.call_details.value;
151        let warp = tx.warp;
152        let roll = tx.roll;
153        if let Some((name, abi)) = &contracts.get(&target)
154            && let Some(func) = abi.functions().find(|f| f.selector() == bytes[..4])
155        {
156            // skip the function selector when decoding
157            if let Ok(args) = func.abi_decode_input(&bytes[4..]) {
158                return Self {
159                    warp,
160                    roll,
161                    sender: Some(sender),
162                    addr: Some(target),
163                    calldata: bytes.clone(),
164                    value,
165                    contract_name: Some(name.clone()),
166                    func_name: Some(func.name.clone()),
167                    signature: Some(func.signature()),
168                    args: Some(foundry_common::fmt::format_tokens(&args).format(", ").to_string()),
169                    raw_args: Some(
170                        foundry_common::fmt::format_tokens_raw(&args).format(", ").to_string(),
171                    ),
172                    traces,
173                    show_solidity,
174                    fuzz: FuzzRunMetadata::default(),
175                };
176            }
177        }
178
179        Self {
180            warp,
181            roll,
182            sender: Some(sender),
183            addr: Some(target),
184            calldata: bytes.clone(),
185            value,
186            contract_name: None,
187            func_name: None,
188            signature: None,
189            args: None,
190            raw_args: None,
191            traces,
192            show_solidity: false,
193            fuzz: FuzzRunMetadata::default(),
194        }
195    }
196
197    /// Creates counter example for a fuzz test failure.
198    pub fn from_fuzz_call(
199        bytes: Bytes,
200        args: Vec<DynSolValue>,
201        traces: Option<SparsedTraceArena>,
202    ) -> Self {
203        Self {
204            warp: None,
205            roll: None,
206            sender: None,
207            addr: None,
208            calldata: bytes,
209            value: None,
210            contract_name: None,
211            func_name: None,
212            signature: None,
213            args: Some(foundry_common::fmt::format_tokens(&args).format(", ").to_string()),
214            raw_args: Some(foundry_common::fmt::format_tokens_raw(&args).format(", ").to_string()),
215            traces,
216            show_solidity: false,
217            fuzz: FuzzRunMetadata::default(),
218        }
219    }
220
221    /// Creates counter example for a fuzz test failure from the concrete executed transaction.
222    pub fn from_fuzz_tx(
223        tx: &BasicTxDetails,
224        args: Vec<DynSolValue>,
225        traces: Option<SparsedTraceArena>,
226    ) -> Self {
227        Self {
228            warp: tx.warp,
229            roll: tx.roll,
230            sender: Some(tx.sender),
231            addr: Some(tx.call_details.target),
232            calldata: tx.call_details.calldata.clone(),
233            value: tx.call_details.value,
234            contract_name: None,
235            func_name: None,
236            signature: None,
237            args: Some(foundry_common::fmt::format_tokens(&args).format(", ").to_string()),
238            raw_args: Some(foundry_common::fmt::format_tokens_raw(&args).format(", ").to_string()),
239            traces,
240            show_solidity: false,
241            fuzz: FuzzRunMetadata::default(),
242        }
243    }
244
245    /// Sets fuzz metadata for reproducing this counterexample.
246    pub const fn with_fuzz_metadata(mut self, fuzz: FuzzRunMetadata) -> Self {
247        self.fuzz = fuzz;
248        self
249    }
250}
251
252impl fmt::Display for BaseCounterExample {
253    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
254        // Display counterexample as solidity.
255        if self.show_solidity
256            && let (Some(sender), Some(contract), Some(address), Some(func_name), Some(args)) =
257                (&self.sender, &self.contract_name, &self.addr, &self.func_name, &self.raw_args)
258        {
259            if let Some(warp) = &self.warp {
260                writeln!(f, "\t\tvm.warp(block.timestamp + {warp});")?;
261            }
262            if let Some(roll) = &self.roll {
263                writeln!(f, "\t\tvm.roll(block.number + {roll});")?;
264            }
265            writeln!(f, "\t\tvm.prank({sender});")?;
266            // Use value syntax for payable calls.
267            if let Some(value) = &self.value
268                && !value.is_zero()
269            {
270                write!(
271                    f,
272                    "\t\t{}({}).{}{{value: {value}}}({});",
273                    contract.split_once(':').map_or(contract.as_str(), |(_, contract)| contract),
274                    address,
275                    func_name,
276                    args
277                )?;
278                return Ok(());
279            }
280            write!(
281                f,
282                "\t\t{}({}).{}({});",
283                contract.split_once(':').map_or(contract.as_str(), |(_, contract)| contract),
284                address,
285                func_name,
286                args
287            )?;
288
289            return Ok(());
290        }
291
292        // Regular counterexample display.
293        // Stateless fuzz targets and senders are fixed by the test configuration, so preserve the
294        // compact historical display unless value makes the transaction context relevant.
295        let show_tx_context =
296            self.fuzz.worker.is_none() || self.value.as_ref().is_some_and(|value| !value.is_zero());
297        if show_tx_context {
298            if let Some(sender) = self.sender {
299                write!(f, "\t\tsender={sender} addr=")?
300            }
301
302            if let Some(name) = &self.contract_name {
303                write!(f, "[{name}]")?
304            }
305
306            if let Some(addr) = &self.addr {
307                write!(f, "{addr} ")?
308            }
309        }
310
311        if let Some(warp) = &self.warp {
312            write!(f, "warp={warp} ")?;
313        }
314        if let Some(roll) = &self.roll {
315            write!(f, "roll={roll} ")?;
316        }
317
318        // Display value if non-zero (for payable calls).
319        if let Some(value) = &self.value
320            && !value.is_zero()
321        {
322            write!(f, "value={value} ")?;
323        }
324
325        if let Some(sig) = &self.signature {
326            write!(f, "calldata={sig}")?
327        } else {
328            write!(f, "calldata={}", self.calldata)?
329        }
330
331        if let Some(args) = &self.args {
332            write!(f, " args=[{args}]")
333        } else {
334            write!(f, " args=[]")
335        }
336    }
337}
338
339/// The outcome of a fuzz test
340#[derive(Debug, Default)]
341pub struct FuzzTestResult {
342    /// we keep this for the debugger
343    pub first_case: FuzzCase,
344    /// Gas usage (gas_used, call_stipend) per cases
345    pub gas_by_case: Vec<(u64, u64)>,
346    /// Whether the test case was successful. This means that the transaction executed
347    /// properly, or that there was a revert and that the test was expected to fail
348    /// (prefixed with `testFail`)
349    pub success: bool,
350    /// Whether the test case was skipped. `reason` will contain the skip reason, if any.
351    pub skipped: bool,
352
353    /// If there was a revert, this field will be populated. Note that the test can
354    /// still be successful (i.e self.success == true) when it's expected to fail.
355    pub reason: Option<String>,
356
357    /// Minimal reproduction test case for failing fuzz tests
358    pub counterexample: Option<CounterExample>,
359
360    /// Any captured & parsed as strings logs along the test's execution which should
361    /// be printed to the user.
362    pub logs: Vec<Log>,
363
364    /// Labeled addresses
365    pub labels: AddressHashMap<String>,
366
367    /// Exemplary traces for a fuzz run of the test function
368    ///
369    /// **Note** We only store a single trace of a successful fuzz call, otherwise we would get
370    /// `num(fuzz_cases)` traces, one for each run, which is neither helpful nor performant.
371    pub traces: Option<SparsedTraceArena>,
372
373    /// Additional traces used for gas report construction.
374    /// Those traces should not be displayed.
375    pub gas_report_traces: Vec<CallTraceArena>,
376
377    /// Raw line coverage info
378    pub line_coverage: Option<HitMaps>,
379
380    /// Breakpoints for debugger. Correspond to the same fuzz case as `traces`.
381    pub breakpoints: Option<Breakpoints>,
382
383    /// Runtime bytecodes for contracts seen in the debug trace.
384    pub debug_bytecodes: AddressHashMap<Bytes>,
385
386    // Deprecated cheatcodes mapped to their replacements.
387    pub deprecated_cheatcodes: HashMap<&'static str, Option<&'static str>>,
388
389    /// Number of failed replays from persisted corpus.
390    pub failed_corpus_replays: usize,
391
392    /// The active fork's block number for the failing case, if any.
393    pub fork_block_number: Option<u64>,
394}
395
396impl FuzzTestResult {
397    /// Returns the median gas of all test cases
398    pub fn median_gas(&self, with_stipend: bool) -> u64 {
399        let mut values = self.gas_values(with_stipend);
400        values.sort_unstable();
401        calc::median_sorted(&values)
402    }
403
404    /// Returns the average gas use of all test cases
405    pub fn mean_gas(&self, with_stipend: bool) -> u64 {
406        let mut values = self.gas_values(with_stipend);
407        values.sort_unstable();
408        calc::mean(&values)
409    }
410
411    fn gas_values(&self, with_stipend: bool) -> Vec<u64> {
412        self.gas_by_case
413            .iter()
414            .map(|gas| if with_stipend { gas.0 } else { gas.0.saturating_sub(gas.1) })
415            .collect()
416    }
417}
418
419/// Data of a single fuzz test case
420#[derive(Clone, Debug, Default, Serialize, Deserialize)]
421pub struct FuzzCase {
422    /// Consumed gas
423    pub gas: u64,
424    /// The initial gas stipend for the transaction
425    pub stipend: u64,
426}
427
428/// Container type for all successful test cases
429#[derive(Clone, Debug, Serialize, Deserialize)]
430#[serde(transparent)]
431pub struct FuzzedCases {
432    cases: Vec<FuzzCase>,
433}
434
435impl FuzzedCases {
436    pub fn new(mut cases: Vec<FuzzCase>) -> Self {
437        cases.sort_by_key(|c| c.gas);
438        Self { cases }
439    }
440
441    pub fn cases(&self) -> &[FuzzCase] {
442        &self.cases
443    }
444
445    pub fn into_cases(self) -> Vec<FuzzCase> {
446        self.cases
447    }
448
449    /// Get the last [FuzzCase]
450    pub fn last(&self) -> Option<&FuzzCase> {
451        self.cases.last()
452    }
453
454    /// Returns the median gas of all test cases
455    pub fn median_gas(&self, with_stipend: bool) -> u64 {
456        let mut values = self.gas_values(with_stipend);
457        values.sort_unstable();
458        calc::median_sorted(&values)
459    }
460
461    /// Returns the average gas use of all test cases
462    pub fn mean_gas(&self, with_stipend: bool) -> u64 {
463        let mut values = self.gas_values(with_stipend);
464        values.sort_unstable();
465        calc::mean(&values)
466    }
467
468    fn gas_values(&self, with_stipend: bool) -> Vec<u64> {
469        self.cases
470            .iter()
471            .map(|c| if with_stipend { c.gas } else { c.gas.saturating_sub(c.stipend) })
472            .collect()
473    }
474
475    /// Returns the case with the highest gas usage
476    pub fn highest(&self) -> Option<&FuzzCase> {
477        self.cases.last()
478    }
479
480    /// Returns the case with the lowest gas usage
481    pub fn lowest(&self) -> Option<&FuzzCase> {
482        self.cases.first()
483    }
484
485    /// Returns the highest amount of gas spent on a fuzz case
486    pub fn highest_gas(&self, with_stipend: bool) -> u64 {
487        self.highest()
488            .map(|c| if with_stipend { c.gas } else { c.gas - c.stipend })
489            .unwrap_or_default()
490    }
491
492    /// Returns the lowest amount of gas spent on a fuzz case
493    pub fn lowest_gas(&self) -> u64 {
494        self.lowest().map(|c| c.gas).unwrap_or_default()
495    }
496}
497
498/// Fixtures to be used for fuzz tests.
499///
500/// The key represents name of the fuzzed parameter, value holds possible fuzzed values.
501/// For example, for a fixture function declared as
502/// `function fixture_sender() external returns (address[] memory senders)`
503/// the fuzz fixtures will contain `sender` key with `senders` array as value
504#[derive(Clone, Default, Debug)]
505pub struct FuzzFixtures {
506    inner: Arc<HashMap<String, DynSolValue>>,
507    /// Variant counts for project enums, used to constrain fuzzed enum inputs.
508    enum_bounds: strategies::EnumBounds,
509}
510
511impl FuzzFixtures {
512    pub fn new(fixtures: HashMap<String, DynSolValue>) -> Self {
513        Self { inner: Arc::new(fixtures), enum_bounds: strategies::EnumBounds::default() }
514    }
515
516    /// Attaches collected enum variant counts.
517    pub fn with_enum_bounds(mut self, enum_bounds: strategies::EnumBounds) -> Self {
518        self.enum_bounds = enum_bounds;
519        self
520    }
521
522    /// Returns configured fixtures for `param_name` fuzzed parameter.
523    pub fn param_fixtures(&self, param_name: &str) -> Option<&[DynSolValue]> {
524        if let Some(param_fixtures) = self.inner.get(&normalize_fixture(param_name)) {
525            param_fixtures.as_fixed_array().or_else(|| param_fixtures.as_array())
526        } else {
527            None
528        }
529    }
530
531    /// Returns the variant count for an enum identified by an optional contract qualifier and name
532    /// (as found in an ABI `internalType`), or `None` if unknown.
533    pub fn enum_variant_count(&self, contract: Option<&str>, name: &str) -> Option<usize> {
534        self.enum_bounds.variant_count(contract, name)
535    }
536}
537
538/// Extracts fixture name from a function name.
539/// For example: fixtures defined in `fixture_Owner` function will be applied for `owner` parameter.
540pub fn fixture_name(function_name: String) -> String {
541    normalize_fixture(function_name.strip_prefix("fixture").unwrap())
542}
543
544/// Normalize fixture parameter name, for example `_Owner` to `owner`.
545fn normalize_fixture(param_name: &str) -> String {
546    param_name.trim_matches('_').to_ascii_lowercase()
547}
foundry_evm_fuzz/lib.rs

foundry_evm_fuzz/
lib.rs
