feat(fuzz): enhance corpus mutation with all-call strategy and msg.value support

When using the ABI mutation type in coverage-guided fuzzing:
- 30% chance to mutate ALL calls in the sequence rather than just one
- Mutate sender (15%) using addresses from dictionary
- Mutate msg.value (15%) for payable functions

Also adds automatic msg.value generation for payable functions during
initial call generation, with value shown in sequence output.

Value generation is biased towards smaller values to avoid balance issues:
- 85% no value, 10% small (0-1000 wei), 4% medium (0.001 ETH), 1% large (1 ETH)

Based on #8644

Co-authored-by: QiuhaoLi <qiuhaoli@outlook.com>

Author: grandizzy

crates/evm/evm/src/executors/corpus.rs

@@ -43,7 +43,7 @@ use foundry_config::FuzzCorpusConfig;
 use foundry_evm_fuzz::{
     BasicTxDetails,
     invariant::FuzzRunIdentifiedContracts,
-    strategies::{EvmFuzzState, mutate_param_value},
+    strategies::{EvmFuzzState, generate_msg_value, mutate_param_value},
 };
 use proptest::{
     prelude::{Just, Rng, Strategy},
@@ -560,12 +560,23 @@ impl WorkerCorpus {
 
                     new_seq = corpus.tx_seq.clone();
 
-                    let idx = rng.random_range(0..new_seq.len());
-                    let tx = new_seq.get_mut(idx).unwrap();
-                    if let (_, Some(function)) = targets.fuzzed_artifacts(tx) {
-                        // TODO: add call_value to call details and mutate it as well as sender some
-                        // of the time.
-                        if !function.inputs.is_empty() {
+                    // 30% chance to mutate ALL calls in the sequence.
+                    // This helps break multi-constraint bugs where any call could hit the target.
+                    if rng.random_range(0..10) < 3 {
+                        for tx in &mut new_seq {
+                            if let (_, Some(function)) = targets.fuzzed_artifacts(tx)
+                                && !function.inputs.is_empty()
+                            {
+                                self.abi_mutate(tx, function, test_runner, fuzz_state)?;
+                            }
+                        }
+                    } else {
+                        // Standard: mutate a single random call.
+                        let idx = rng.random_range(0..new_seq.len());
+                        let tx = new_seq.get_mut(idx).unwrap();
+                        if let (_, Some(function)) = targets.fuzzed_artifacts(tx)
+                            && !function.inputs.is_empty()
+                        {
                             self.abi_mutate(tx, function, test_runner, fuzz_state)?;
                         }
                     }
@@ -687,7 +698,26 @@ impl WorkerCorpus {
         test_runner: &mut TestRunner,
         fuzz_state: &EvmFuzzState,
     ) -> Result<()> {
-        // let rng = test_runner.rng();
+        // Mutate sender with 15% probability using addresses from dictionary.
+        if test_runner.rng().random_ratio(15, 100) {
+            let dict = fuzz_state.dictionary_read();
+            let addresses = dict.addresses();
+            if !addresses.is_empty() {
+                let idx = test_runner.rng().random_range(0..addresses.len());
+                if let Some(&addr) = addresses.get_index(idx) {
+                    tx.sender = addr;
+                }
+            }
+        }
+
+        // Mutate value with 15% probability for payable functions.
+        if function.state_mutability == alloy_json_abi::StateMutability::Payable
+            && test_runner.rng().random_ratio(15, 100)
+        {
+            tx.call_details.value = Some(generate_msg_value(test_runner));
+        }
+
+        // Mutate calldata.
         let mut arg_mutation_rounds =
             test_runner.rng().random_range(0..=function.inputs.len()).max(1);
         let round_arg_idx: Vec<usize> = if function.inputs.len() <= 1 {
@@ -1104,6 +1134,7 @@ mod tests {
             call_details: foundry_evm_fuzz::CallDetails {
                 target: Address::ZERO,
                 calldata: Bytes::new(),
+                value: None,
             },
         }
     }

crates/evm/evm/src/executors/fuzz/mod.rs

@@ -251,7 +251,11 @@ impl FuzzedExecutor {
                 warp: None,
                 roll: None,
                 sender: self.sender,
-                call_details: CallDetails { target: address, calldata: calldata.clone() },
+                call_details: CallDetails {
+                    target: address,
+                    calldata: calldata.clone(),
+                    value: None,
+                },
             }],
             new_coverage,
         );
@@ -414,7 +418,7 @@ impl FuzzedExecutor {
             warp: None,
             roll: None,
             sender: Default::default(),
-            call_details: CallDetails { target: Default::default(), calldata },
+            call_details: CallDetails { target: Default::default(), calldata, value: None },
         });
 
         let mut corpus = WorkerCorpus::new(

crates/evm/evm/src/executors/invariant/mod.rs

@@ -1090,8 +1090,12 @@ pub(crate) fn execute_tx(executor: &mut Executor, tx: &BasicTxDetails) -> Result
     }
 
     // Perform the raw call.
+    // Only use value if sender has sufficient balance, otherwise fall back to 0.
+    let requested_value = tx.call_details.value.unwrap_or(U256::ZERO);
+    let sender_balance = executor.get_balance(tx.sender)?;
+    let value = if sender_balance >= requested_value { requested_value } else { U256::ZERO };
     let mut call_result = executor
-        .call_raw(tx.sender, tx.call_details.target, tx.call_details.calldata.clone(), U256::ZERO)
+        .call_raw(tx.sender, tx.call_details.target, tx.call_details.calldata.clone(), value)
         .map_err(|e| eyre!(format!("Could not make raw evm call: {e}")))?;
 
     // Propagate block adjustments to call result which will be committed.

crates/evm/fuzz/src/lib.rs

@@ -56,6 +56,10 @@ pub struct CallDetails {
     pub target: Address,
     /// The data of the transaction.
     pub calldata: Bytes,
+    /// Ether value to send with the transaction.
+    /// Uses `#[serde(default)]` for backwards compatibility with existing corpus files.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub value: Option<U256>,
 }
 
 impl BasicTxDetails {
@@ -86,6 +90,9 @@ pub struct BaseCounterExample {
     pub addr: Option<Address>,
     /// The data to provide.
     pub calldata: Bytes,
+    /// Ether value sent with the call.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub value: Option<U256>,
     /// Contract name if it exists.
     pub contract_name: Option<String>,
     /// Function name if it exists.
@@ -115,6 +122,7 @@ impl BaseCounterExample {
         let sender = tx.sender;
         let target = tx.call_details.target;
         let bytes = &tx.call_details.calldata;
+        let value = tx.call_details.value;
         let warp = tx.warp;
         let roll = tx.roll;
         if let Some((name, abi)) = &contracts.get(&target)
@@ -128,6 +136,7 @@ impl BaseCounterExample {
                     sender: Some(sender),
                     addr: Some(target),
                     calldata: bytes.clone(),
+                    value,
                     contract_name: Some(name.clone()),
                     func_name: Some(func.name.clone()),
                     signature: Some(func.signature()),
@@ -147,6 +156,7 @@ impl BaseCounterExample {
             sender: Some(sender),
             addr: Some(target),
             calldata: bytes.clone(),
+            value,
             contract_name: None,
             func_name: None,
             signature: None,
@@ -169,6 +179,7 @@ impl BaseCounterExample {
             sender: None,
             addr: None,
             calldata: bytes,
+            value: None,
             contract_name: None,
             func_name: None,
             signature: None,
@@ -194,6 +205,20 @@ impl fmt::Display for BaseCounterExample {
                 writeln!(f, "\t\tvm.roll(block.number + {roll});")?;
             }
             writeln!(f, "\t\tvm.prank({sender});")?;
+            // Use value syntax for payable calls.
+            if let Some(value) = &self.value
+                && !value.is_zero()
+            {
+                write!(
+                    f,
+                    "\t\t{}({}).{}{{value: {value}}}({});",
+                    contract.split_once(':').map_or(contract.as_str(), |(_, contract)| contract),
+                    address,
+                    func_name,
+                    args
+                )?;
+                return Ok(());
+            }
             write!(
                 f,
                 "\t\t{}({}).{}({});",
@@ -226,6 +251,13 @@ impl fmt::Display for BaseCounterExample {
             write!(f, "roll={roll} ")?;
         }
 
+        // Display value if non-zero (for payable calls).
+        if let Some(value) = &self.value
+            && !value.is_zero()
+        {
+            write!(f, "value={value} ")?;
+        }
+
         if let Some(sig) = &self.signature {
             write!(f, "calldata={sig}")?
         } else {

crates/evm/fuzz/src/strategies/invariants.rs

@@ -1,4 +1,4 @@
-use super::{fuzz_calldata, fuzz_param_from_state};
+use super::{fuzz_calldata, fuzz_msg_value, fuzz_param_from_state};
 use crate::{
     BasicTxDetails, CallDetails, FuzzFixtures,
     invariant::{FuzzRunIdentifiedContracts, SenderFilters},
@@ -153,15 +153,21 @@ pub fn fuzz_contract_with_calldata(
     target: Address,
     func: Function,
 ) -> impl Strategy<Value = CallDetails> + use<> {
+    let is_payable = func.state_mutability == alloy_json_abi::StateMutability::Payable;
+
     // We need to compose all the strategies generated for each parameter in all possible
     // combinations.
     // `prop_oneof!` / `TupleUnion` `Arc`s for cheap cloning.
-    prop_oneof![
+    let calldata_strategy = prop_oneof![
         60 => fuzz_calldata(func.clone(), fuzz_fixtures),
         40 => fuzz_calldata_from_state(func, fuzz_state),
-    ]
-    .prop_map(move |calldata| {
-        trace!(input=?calldata);
-        CallDetails { target, calldata }
+    ];
+
+    // For payable functions, generate random value using shared strategy.
+    let value_strategy = if is_payable { fuzz_msg_value().boxed() } else { Just(None).boxed() };
+
+    (calldata_strategy, value_strategy).prop_map(move |(calldata, value)| {
+        trace!(input=?calldata, ?value);
+        CallDetails { target, calldata, value }
     })
 }

crates/evm/fuzz/src/strategies/mod.rs

@@ -6,8 +6,8 @@ pub use uint::UintStrategy;
 
 mod param;
 pub use param::{
-    fuzz_param, fuzz_param_from_state, fuzz_param_with_fixtures, mutate_param_value,
-    mutate_param_value_with_senders,
+    fuzz_msg_value, fuzz_param, fuzz_param_from_state, fuzz_param_with_fixtures,
+    generate_msg_value, mutate_param_value, mutate_param_value_with_senders,
 };
 
 mod calldata;

crates/evm/fuzz/src/strategies/param.rs

@@ -512,6 +512,53 @@ fn mutate_random_array_value(
     *elem = new_val;
 }
 
+/// 0.001 ETH in wei.
+const MILLI_ETH: u64 = 1_000_000_000_000_000;
+/// 1 ETH in wei.
+const ONE_ETH: u64 = 1_000_000_000_000_000_000;
+
+/// Returns a proptest strategy for generating random msg.value for payable functions.
+/// Biased towards smaller values to avoid balance issues.
+///
+/// Distribution:
+/// - 85% chance: no value (None)
+/// - 10% chance: small values (0-1000 wei)
+/// - 4% chance: medium values (up to 0.001 ETH)
+/// - 1% chance: larger values (up to 1 ETH)
+pub fn fuzz_msg_value() -> impl Strategy<Value = Option<U256>> {
+    proptest::prop_oneof![
+        // 85% chance: no value
+        85 => proptest::strategy::Just(None),
+        // 10% chance: small values (0-1000 wei)
+        10 => (0u64..=1000).prop_map(|v| Some(U256::from(v))),
+        // 4% chance: medium values (up to 0.001 ETH)
+        4 => (0u64..=MILLI_ETH).prop_map(|v| Some(U256::from(v))),
+        // 1% chance: larger values (up to 1 ETH)
+        1 => (0u64..=ONE_ETH).prop_map(|v| Some(U256::from(v))),
+    ]
+}
+
+/// Generates a random msg.value for payable functions using TestRunner's RNG.
+/// Biased towards smaller values to avoid balance issues.
+///
+/// Distribution:
+/// - 60% chance: small values (0-1000 wei)
+/// - 30% chance: medium values (up to 0.001 ETH)
+/// - 9% chance: larger values (up to 1 ETH)
+/// - 1% chance: max value (edge case)
+pub fn generate_msg_value(test_runner: &mut TestRunner) -> U256 {
+    match test_runner.rng().random_range(0..=10) {
+        // Small values (0-1000 wei) - 60% chance.
+        0..=5 => U256::from(test_runner.rng().random_range(0u64..=1000)),
+        // Medium values (up to 0.001 ETH) - 30% chance.
+        6..=8 => U256::from(test_runner.rng().random_range(0u64..=MILLI_ETH)),
+        // Larger values (up to 1 ETH) - 9% chance.
+        9 => U256::from(test_runner.rng().random_range(0u64..=ONE_ETH)),
+        // Edge case (max) - 1% chance.
+        _ => U256::MAX,
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use crate::{

crates/forge/src/runner.rs

@@ -786,6 +786,7 @@ impl<'a> FunctionRunner<'a> {
                         call_details: CallDetails {
                             target: seq.addr.unwrap_or_default(),
                             calldata: seq.calldata.clone(),
+                            value: None,
                         },
                     }
                 })

crates/forge/tests/cli/test_cmd/invariant/common.rs

@@ -1782,3 +1782,84 @@ Logs:
 ...
 "#]]);
 });
+
+// Test that invariant fuzzer generates random msg.value for payable functions.
+// Based on the example from https://github.com/foundry-rs/foundry/pull/8644
+forgetest_init!(invariant_msg_value, |prj, cmd| {
+    prj.update_config(|config| {
+        config.fuzz.seed = Some(U256::from(42u32));
+        config.invariant.runs = 200;
+        config.invariant.depth = 20;
+    });
+
+    prj.add_test(
+        "InvariantMsgValue.t.sol",
+        r#"
+import "forge-std/Test.sol";
+
+contract ValueTarget {
+    bool public valueReceived;
+
+    // Payable function that tracks if any value was received
+    function deposit() external payable {
+        if (msg.value > 0) {
+            valueReceived = true;
+        }
+    }
+}
+
+contract InvariantMsgValue is Test {
+    ValueTarget target;
+    address sender1;
+    address sender2;
+
+    function setUp() public {
+        target = new ValueTarget();
+        // Create and fund specific senders
+        sender1 = makeAddr("sender1");
+        sender2 = makeAddr("sender2");
+        vm.deal(sender1, 1000 ether);
+        vm.deal(sender2, 1000 ether);
+        // Target only these funded senders
+        targetSender(sender1);
+        targetSender(sender2);
+        // Target only the ValueTarget contract
+        targetContract(address(target));
+    }
+
+    function invariant_value_never_received() public view {
+        require(!target.valueReceived(), "Value was received");
+    }
+}
+"#,
+    );
+
+    // The test should fail because the fuzzer generates msg.value > 0 for payable functions
+    // First check regular output format shows value=X
+    cmd.args(["test", "--mt", "invariant_value_never_received"])
+        .assert_failure()
+        .stdout_eq(str![[r#"
+...
+[FAIL: Value was received]
+	[Sequence] (original: [..], shrunk: 1)
+		sender=[..] addr=[test/InvariantMsgValue.t.sol:ValueTarget][..] value=[..] calldata=deposit() args=[]
+...
+"#]]);
+
+    // Now check solidity output format shows proper {value: X} syntax
+    cmd.forge_fuse().arg("clean").assert_success();
+    prj.update_config(|config| {
+        config.invariant.show_solidity = true;
+    });
+    cmd.forge_fuse()
+        .args(["test", "--mt", "invariant_value_never_received"])
+        .assert_failure()
+        .stdout_eq(str![[r#"
+...
+[FAIL: Value was received]
+	[Sequence] (original: [..], shrunk: 1)
+		vm.prank([..]);
+		ValueTarget([..]).deposit{value: [..]}();
+...
+"#]]);
+});