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, PartialEq, Eq, 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, PartialEq, Eq, 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.
348    pub success: bool,
349    /// Whether the test case was skipped. `reason` will contain the skip reason, if any.
350    pub skipped: bool,
351
352    /// If there was a revert, this field will be populated.
353    pub reason: Option<String>,
354
355    /// Minimal reproduction test case for failing fuzz tests
356    pub counterexample: Option<CounterExample>,
357
358    /// Any captured & parsed as strings logs along the test's execution which should
359    /// be printed to the user.
360    pub logs: Vec<Log>,
361
362    /// Labeled addresses
363    pub labels: AddressHashMap<String>,
364
365    /// Exemplary traces for a fuzz run of the test function
366    ///
367    /// **Note** We only store a single trace of a successful fuzz call, otherwise we would get
368    /// `num(fuzz_cases)` traces, one for each run, which is neither helpful nor performant.
369    pub traces: Option<SparsedTraceArena>,
370
371    /// Additional traces used for gas report construction.
372    /// Those traces should not be displayed.
373    pub gas_report_traces: Vec<CallTraceArena>,
374
375    /// Raw line coverage info
376    pub line_coverage: Option<HitMaps>,
377
378    /// Breakpoints for debugger. Correspond to the same fuzz case as `traces`.
379    pub breakpoints: Option<Breakpoints>,
380
381    /// Runtime bytecodes for contracts seen in the debug trace.
382    pub debug_bytecodes: AddressHashMap<Bytes>,
383
384    // Deprecated cheatcodes mapped to their replacements.
385    pub deprecated_cheatcodes: HashMap<&'static str, Option<&'static str>>,
386
387    /// Number of failed replays from persisted corpus.
388    pub failed_corpus_replays: usize,
389
390    /// The active fork's block number for the failing case, if any.
391    pub fork_block_number: Option<u64>,
392}
393
394impl FuzzTestResult {
395    /// Returns the median gas of all test cases
396    pub fn median_gas(&self, with_stipend: bool) -> u64 {
397        let mut values = self.gas_values(with_stipend);
398        values.sort_unstable();
399        calc::median_sorted(&values)
400    }
401
402    /// Returns the average gas use of all test cases
403    pub fn mean_gas(&self, with_stipend: bool) -> u64 {
404        let mut values = self.gas_values(with_stipend);
405        values.sort_unstable();
406        calc::mean(&values)
407    }
408
409    fn gas_values(&self, with_stipend: bool) -> Vec<u64> {
410        self.gas_by_case
411            .iter()
412            .map(|gas| if with_stipend { gas.0 } else { gas.0.saturating_sub(gas.1) })
413            .collect()
414    }
415}
416
417/// Data of a single fuzz test case
418#[derive(Clone, Debug, Default, Serialize, Deserialize)]
419pub struct FuzzCase {
420    /// Consumed gas
421    pub gas: u64,
422    /// The initial gas stipend for the transaction
423    pub stipend: u64,
424}
425
426/// Container type for all successful test cases
427#[derive(Clone, Debug, Serialize, Deserialize)]
428#[serde(transparent)]
429pub struct FuzzedCases {
430    cases: Vec<FuzzCase>,
431}
432
433impl FuzzedCases {
434    pub fn new(mut cases: Vec<FuzzCase>) -> Self {
435        cases.sort_by_key(|c| c.gas);
436        Self { cases }
437    }
438
439    pub fn cases(&self) -> &[FuzzCase] {
440        &self.cases
441    }
442
443    pub fn into_cases(self) -> Vec<FuzzCase> {
444        self.cases
445    }
446
447    /// Get the last [FuzzCase]
448    pub fn last(&self) -> Option<&FuzzCase> {
449        self.cases.last()
450    }
451
452    /// Returns the median gas of all test cases
453    pub fn median_gas(&self, with_stipend: bool) -> u64 {
454        let mut values = self.gas_values(with_stipend);
455        values.sort_unstable();
456        calc::median_sorted(&values)
457    }
458
459    /// Returns the average gas use of all test cases
460    pub fn mean_gas(&self, with_stipend: bool) -> u64 {
461        let mut values = self.gas_values(with_stipend);
462        values.sort_unstable();
463        calc::mean(&values)
464    }
465
466    fn gas_values(&self, with_stipend: bool) -> Vec<u64> {
467        self.cases
468            .iter()
469            .map(|c| if with_stipend { c.gas } else { c.gas.saturating_sub(c.stipend) })
470            .collect()
471    }
472
473    /// Returns the case with the highest gas usage
474    pub fn highest(&self) -> Option<&FuzzCase> {
475        self.cases.last()
476    }
477
478    /// Returns the case with the lowest gas usage
479    pub fn lowest(&self) -> Option<&FuzzCase> {
480        self.cases.first()
481    }
482
483    /// Returns the highest amount of gas spent on a fuzz case
484    pub fn highest_gas(&self, with_stipend: bool) -> u64 {
485        self.highest()
486            .map(|c| if with_stipend { c.gas } else { c.gas - c.stipend })
487            .unwrap_or_default()
488    }
489
490    /// Returns the lowest amount of gas spent on a fuzz case
491    pub fn lowest_gas(&self) -> u64 {
492        self.lowest().map(|c| c.gas).unwrap_or_default()
493    }
494}
495
496/// Fixtures to be used for fuzz tests.
497///
498/// The key represents name of the fuzzed parameter, value holds possible fuzzed values.
499/// For example, for a fixture function declared as
500/// `function fixture_sender() external returns (address[] memory senders)`
501/// the fuzz fixtures will contain `sender` key with `senders` array as value
502#[derive(Clone, Default, Debug)]
503pub struct FuzzFixtures {
504    inner: Arc<HashMap<String, DynSolValue>>,
505    /// Variant counts for project enums, used to constrain fuzzed enum inputs.
506    enum_bounds: strategies::EnumBounds,
507}
508
509impl FuzzFixtures {
510    pub fn new(fixtures: HashMap<String, DynSolValue>) -> Self {
511        Self { inner: Arc::new(fixtures), enum_bounds: strategies::EnumBounds::default() }
512    }
513
514    /// Attaches collected enum variant counts.
515    pub fn with_enum_bounds(mut self, enum_bounds: strategies::EnumBounds) -> Self {
516        self.enum_bounds = enum_bounds;
517        self
518    }
519
520    /// Returns configured fixtures for `param_name` fuzzed parameter.
521    pub fn param_fixtures(&self, param_name: &str) -> Option<&[DynSolValue]> {
522        if let Some(param_fixtures) = self.inner.get(&normalize_fixture(param_name)) {
523            param_fixtures.as_fixed_array().or_else(|| param_fixtures.as_array())
524        } else {
525            None
526        }
527    }
528
529    /// Returns the variant count for an enum identified by an optional contract qualifier and name
530    /// (as found in an ABI `internalType`), or `None` if unknown.
531    pub fn enum_variant_count(&self, contract: Option<&str>, name: &str) -> Option<usize> {
532        self.enum_bounds.variant_count(contract, name)
533    }
534}
535
536/// Extracts fixture name from a function name.
537/// For example: fixtures defined in `fixture_Owner` function will be applied for `owner` parameter.
538pub fn fixture_name(function_name: String) -> String {
539    normalize_fixture(function_name.strip_prefix("fixture").unwrap())
540}
541
542/// Normalize fixture parameter name, for example `_Owner` to `owner`.
543fn normalize_fixture(param_name: &str) -> String {
544    param_name.trim_matches('_').to_ascii_lowercase()
545}
foundry_evm_fuzz/lib.rs

foundry_evm_fuzz/
lib.rs
