feat(fuzz): add max_deal config to fund senders for payable functions

Adds max_deal invariant config option that generates random deal amounts
(0 to max_deal) to increase sender balance before each tx for payable functions.

Behavior:
- If max_deal is NOT configured: value is generated for payable functions but
  falls back to 0 if sender has insufficient balance
- If max_deal IS configured: random deal amount is applied before the call,
  enabling payable calls with msg.value > 0 to succeed

The deal is only applied when the function is payable (has value > 0).
If balance is still insufficient after deal, value falls back to 0.

Counterexamples display deal as:
- Regular: deal=X
- Solidity: vm.deal(sender, sender.balance + X);

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019bf992-367c-721c-a497-58a1a11ee2be

Author: grandizzy

crates/config/src/invariant.rs

@@ -41,6 +41,8 @@ pub struct InvariantConfig {
     pub max_time_delay: Option<u32>,
     /// Maximum number of blocks elapsed between generated txs.
     pub max_block_delay: Option<u32>,
+    /// Maximum amount (in wei) to deal to sender before each tx for payable functions.
+    pub max_deal: Option<u64>,
     /// Number of calls to execute between invariant assertions.
     ///
     /// - `0`: Only assert on the last call of each run (fastest, but may miss exact breaking call)
@@ -69,6 +71,7 @@ impl Default for InvariantConfig {
             show_solidity: false,
             max_time_delay: None,
             max_block_delay: None,
+            max_deal: None,
             check_interval: 1,
         }
     }

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

@@ -1145,6 +1145,7 @@ mod tests {
         BasicTxDetails {
             warp: None,
             roll: None,
+            deal: None,
             sender: Address::ZERO,
             call_details: foundry_evm_fuzz::CallDetails {
                 target: Address::ZERO,

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

@@ -250,6 +250,7 @@ impl FuzzedExecutor {
             &[BasicTxDetails {
                 warp: None,
                 roll: None,
+                deal: None,
                 sender: self.sender,
                 call_details: CallDetails {
                     target: address,
@@ -417,6 +418,7 @@ impl FuzzedExecutor {
         .prop_map(move |calldata| BasicTxDetails {
             warp: None,
             roll: None,
+            deal: None,
             sender: Default::default(),
             call_details: CallDetails { target: Default::default(), calldata, value: None },
         });

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

@@ -1105,7 +1105,8 @@ pub(crate) fn call_invariant_function(
 }
 
 /// Executes a fuzz call and returns the result.
-/// Applies any block timestamp (warp) and block number (roll) adjustments before the call.
+/// Applies any block timestamp (warp), block number (roll), and balance (deal) adjustments before
+/// the call.
 pub(crate) fn execute_tx(executor: &mut Executor, tx: &BasicTxDetails) -> Result<RawCallResult> {
     let warp = tx.warp.unwrap_or_default();
     let roll = tx.roll.unwrap_or_default();
@@ -1129,9 +1130,19 @@ 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);
+
+    // Apply deal (increase sender balance) if specified and function is payable (has value).
+    // Value is only generated for payable functions, so we check if requested_value > 0.
+    if let Some(deal) = tx.deal
+        && requested_value > U256::ZERO
+    {
+        let current_balance = executor.get_balance(tx.sender)?;
+        executor.set_balance(tx.sender, current_balance + deal)?;
+    }
+
+    // Perform the raw call.
+    // Only use value if sender has sufficient balance (after deal), otherwise fall back to 0.
     let sender_balance = executor.get_balance(tx.sender)?;
     let value = if sender_balance >= requested_value { requested_value } else { U256::ZERO };
     executor

crates/evm/fuzz/src/invariant/call_override.rs

@@ -91,7 +91,13 @@ impl RandomCallGenerator {
 
             // `original_caller` has a 80% chance of being the `new_target`.
             let choice = self.strategy.new_tree(&mut self.runner.lock()).unwrap().current().map(
-                |call_details| BasicTxDetails { warp: None, roll: None, sender, call_details },
+                |call_details| BasicTxDetails {
+                    warp: None,
+                    roll: None,
+                    deal: None,
+                    sender,
+                    call_details,
+                },
             );
 
             self.last_sequence.write().push(choice.clone());

crates/evm/fuzz/src/lib.rs

@@ -42,6 +42,9 @@ pub struct BasicTxDetails {
     /// Number to increase block number before executing the tx.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub roll: Option<U256>,
+    /// Amount to deal (add) to sender's balance before executing the tx.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub deal: Option<U256>,
     /// Transaction sender address.
     pub sender: Address,
     /// Transaction call details.
@@ -84,6 +87,8 @@ pub struct BaseCounterExample {
     pub warp: Option<U256>,
     // Amount to increase block number.
     pub roll: Option<U256>,
+    // Amount to deal (add) to sender's balance.
+    pub deal: Option<U256>,
     /// Address which makes the call.
     pub sender: Option<Address>,
     /// Address to which to call to.
@@ -125,6 +130,7 @@ impl BaseCounterExample {
         let value = tx.call_details.value;
         let warp = tx.warp;
         let roll = tx.roll;
+        let deal = tx.deal;
         if let Some((name, abi)) = &contracts.get(&target)
             && let Some(func) = abi.functions().find(|f| f.selector() == bytes[..4])
         {
@@ -133,6 +139,7 @@ impl BaseCounterExample {
                 return Self {
                     warp,
                     roll,
+                    deal,
                     sender: Some(sender),
                     addr: Some(target),
                     calldata: bytes.clone(),
@@ -153,6 +160,7 @@ impl BaseCounterExample {
         Self {
             warp,
             roll,
+            deal,
             sender: Some(sender),
             addr: Some(target),
             calldata: bytes.clone(),
@@ -176,6 +184,7 @@ impl BaseCounterExample {
         Self {
             warp: None,
             roll: None,
+            deal: None,
             sender: None,
             addr: None,
             calldata: bytes,
@@ -204,6 +213,9 @@ impl fmt::Display for BaseCounterExample {
             if let Some(roll) = &self.roll {
                 writeln!(f, "\t\tvm.roll(block.number + {roll});")?;
             }
+            if let Some(deal) = &self.deal {
+                writeln!(f, "\t\tvm.deal({sender}, {sender}.balance + {deal});")?;
+            }
             writeln!(f, "\t\tvm.prank({sender});")?;
             // Use value syntax for payable calls.
             if let Some(value) = &self.value
@@ -250,6 +262,9 @@ impl fmt::Display for BaseCounterExample {
         if let Some(roll) = &self.roll {
             write!(f, "roll={roll} ")?;
         }
+        if let Some(deal) = &self.deal {
+            write!(f, "deal={deal} ")?;
+        }
 
         // Display value if non-zero (for payable calls).
         if let Some(value) = &self.value

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

@@ -77,8 +77,8 @@ pub fn invariant_strat(
     let senders = Rc::new(senders);
     let dictionary_weight = config.dictionary.dictionary_weight;
 
-    // Strategy to generate values for tx warp and roll.
-    let warp_roll_strat = |cond: bool| {
+    // Strategy to generate optional U256 values for tx warp, roll, and deal.
+    let optional_u256_strat = |cond: bool| {
         if cond { any::<U256>().prop_map(Some).boxed() } else { Just(None).boxed() }
     };
 
@@ -97,17 +97,19 @@ pub fn invariant_strat(
                 target_function.clone(),
             );
 
-            let warp = warp_roll_strat(config.max_time_delay.is_some());
-            let roll = warp_roll_strat(config.max_block_delay.is_some());
+            let warp = optional_u256_strat(config.max_time_delay.is_some());
+            let roll = optional_u256_strat(config.max_block_delay.is_some());
+            let deal = optional_u256_strat(config.max_deal.is_some());
 
-            (warp, roll, sender, call_details)
+            (warp, roll, deal, sender, call_details)
         })
-        .prop_map(move |(warp, roll, sender, call_details)| {
+        .prop_map(move |(warp, roll, deal, sender, call_details)| {
             let warp =
                 warp.map(|time| time % U256::from(config.max_time_delay.unwrap_or_default()));
             let roll =
                 roll.map(|block| block % U256::from(config.max_block_delay.unwrap_or_default()));
-            BasicTxDetails { warp, roll, sender, call_details }
+            let deal = deal.map(|amount| amount % U256::from(config.max_deal.unwrap_or_default()));
+            BasicTxDetails { warp, roll, deal, sender, call_details }
         })
 }
 

crates/forge/src/runner.rs

@@ -778,6 +778,7 @@ impl<'a> FunctionRunner<'a> {
                     BasicTxDetails {
                         warp: seq.warp,
                         roll: seq.roll,
+                        deal: seq.deal,
                         sender: seq.sender.unwrap_or_default(),
                         call_details: CallDetails {
                             target: seq.addr.unwrap_or_default(),

crates/forge/tests/cli/config.rs

@@ -1288,6 +1288,7 @@ forgetest_init!(test_default_config, |prj, cmd| {
     "show_solidity": false,
     "max_time_delay": null,
     "max_block_delay": null,
+    "max_deal": null,
     "check_interval": 1
   },
   "ffi": false,

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

@@ -2055,3 +2055,138 @@ contract InvariantOptimizeWarpTest is Test {
 ...
 "#]]);
 });
+
+// Test that without max_deal, payable calls with value fail when sender has no balance.
+// The fuzzer should fall back to value=0, so the invariant should pass.
+forgetest_init!(invariant_no_max_deal_fallback, |prj, cmd| {
+    prj.update_config(|config| {
+        config.fuzz.seed = Some(U256::from(42u32));
+        config.invariant.runs = 50;
+        config.invariant.depth = 10;
+        // No max_deal configured - sender has no balance so value falls back to 0
+    });
+
+    prj.add_test(
+        "InvariantNoMaxDeal.t.sol",
+        r#"
+import "forge-std/Test.sol";
+
+contract ValueTarget {
+    bool public valueReceived;
+
+    function deposit() external payable {
+        if (msg.value > 0) {
+            valueReceived = true;
+        }
+    }
+}
+
+contract InvariantNoMaxDeal is Test {
+    ValueTarget target;
+
+    function setUp() public {
+        target = new ValueTarget();
+        // Target only the ValueTarget contract
+        targetContract(address(target));
+        // Use a custom sender with no initial balance
+        targetSender(makeAddr("sender1"));
+        // NOTE: No vm.deal() for sender1 - it has 0 balance
+        // Without max_deal config, value should fall back to 0
+    }
+
+    // This invariant should PASS because without max_deal, value falls back to 0
+    function invariant_value_never_received() public view {
+        require(!target.valueReceived(), "Value was received");
+    }
+}
+"#,
+    );
+
+    // The test should pass because without max_deal and no sender balance,
+    // value falls back to 0
+    cmd.args(["test", "--mt", "invariant_value_never_received"]).assert_success().stdout_eq(str![
+        [r#"
+...
+[PASS] invariant_value_never_received() (runs: 50, calls: 500, reverts: 0)
+...
+"#]
+    ]);
+});
+
+// Test that with max_deal configured, the fuzzer deals balance to sender before tx,
+// enabling payable calls with msg.value > 0 to succeed.
+forgetest_init!(invariant_with_max_deal, |prj, cmd| {
+    prj.update_config(|config| {
+        config.fuzz.seed = Some(U256::from(42u32));
+        config.invariant.runs = 100;
+        config.invariant.depth = 20;
+        // Configure max_deal to fund senders before each tx
+        config.invariant.max_deal = Some(1_000_000_000_000_000_000); // 1 ETH in wei
+    });
+
+    prj.add_test(
+        "InvariantWithMaxDeal.t.sol",
+        r#"
+import "forge-std/Test.sol";
+
+contract ValueTarget {
+    bool public valueReceived;
+
+    function deposit() external payable {
+        if (msg.value > 0) {
+            valueReceived = true;
+        }
+    }
+}
+
+contract InvariantWithMaxDeal is Test {
+    ValueTarget target;
+
+    function setUp() public {
+        target = new ValueTarget();
+        // Target only the ValueTarget contract
+        targetContract(address(target));
+        // Use a custom sender with no initial balance
+        targetSender(makeAddr("sender1"));
+        // NOTE: No vm.deal() in setUp - max_deal config will fund sender1
+    }
+
+    // This invariant should FAIL because max_deal funds senders,
+    // allowing payable calls with msg.value > 0
+    function invariant_value_never_received() public view {
+        require(!target.valueReceived(), "Value was received");
+    }
+}
+"#,
+    );
+
+    // The test should fail because max_deal funds senders before each tx,
+    // enabling value > 0 to be sent
+    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/InvariantWithMaxDeal.t.sol:ValueTarget][..] deal=[..] value=[..] calldata=deposit() args=[]
+...
+"#]]);
+
+    // Check solidity output format shows vm.deal()
+    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.deal([..], [..].balance + [..]);
+		vm.prank([..]);
+		ValueTarget([..]).deposit{value: [..]}();
+...
+"#]]);
+});