feat(fuzz): add bound and gaussian noise mutators (#11342)

* feat(fuzz): add uint/int gaussian noise mutator

* reorg

* Mutators take2

* Add bound mutator

* Comment nit

* Review comments: add instrument, nits

* Fix panic on [min, max] ranges

Author: grandizzy

Cargo.lock

@@ -20,6 +20,7 @@ foundry-common.workspace = true
 foundry-compilers.workspace = true
 foundry-config.workspace = true
 foundry-evm-core.workspace = true
+foundry-evm-fuzz.workspace = true
 foundry-evm-traces.workspace = true
 foundry-wallets.workspace = true
 forge-script-sequence.workspace = true

crates/cheatcodes/Cargo.toml

@@ -2844,6 +2844,10 @@ interface Vm {
     #[cheatcode(group = Utilities)]
     function ensNamehash(string calldata name) external pure returns (bytes32);
 
+    /// Returns an uint256 value bounded in given range and different from the current one.
+    #[cheatcode(group = Utilities)]
+    function bound(uint256 current, uint256 min, uint256 max) external view returns (uint256);
+
     /// Returns a random uint256 value.
     #[cheatcode(group = Utilities)]
     function randomUint() external view returns (uint256);
@@ -2860,6 +2864,10 @@ interface Vm {
     #[cheatcode(group = Utilities)]
     function randomAddress() external view returns (address);
 
+    /// Returns an int256 value bounded in given range and different from the current one.
+    #[cheatcode(group = Utilities)]
+    function bound(int256 current, int256 min, int256 max) external view returns (int256);
+
     /// Returns a random `int256` value.
     #[cheatcode(group = Utilities)]
     function randomInt() external view returns (int256);

crates/cheatcodes/assets/cheatcodes.json

@@ -3,11 +3,12 @@
 use crate::{Cheatcode, Cheatcodes, CheatcodesExecutor, CheatsCtxt, Result, Vm::*};
 use alloy_dyn_abi::{DynSolType, DynSolValue, Resolver, TypedData, eip712_parser::EncodeType};
 use alloy_ens::namehash;
-use alloy_primitives::{B64, Bytes, U256, aliases::B32, keccak256, map::HashMap};
+use alloy_primitives::{B64, Bytes, I256, U256, aliases::B32, keccak256, map::HashMap};
 use alloy_sol_types::SolValue;
 use foundry_common::{TYPE_BINDING_PREFIX, fs};
 use foundry_config::fs_permissions::FsAccessKind;
 use foundry_evm_core::constants::DEFAULT_CREATE2_DEPLOYER;
+use foundry_evm_fuzz::strategies::BoundMutator;
 use proptest::prelude::Strategy;
 use rand::{Rng, RngCore, seq::SliceRandom};
 use revm::context::JournalTr;
@@ -74,6 +75,26 @@ impl Cheatcode for ensNamehashCall {
     }
 }
 
+impl Cheatcode for bound_0Call {
+    fn apply(&self, state: &mut Cheatcodes) -> Result {
+        let Self { current, min, max } = *self;
+        let Some(mutated) = U256::bound(current, min, max, state.test_runner()) else {
+            bail!("cannot bound {current} in [{min}, {max}] range")
+        };
+        Ok(mutated.abi_encode())
+    }
+}
+
+impl Cheatcode for bound_1Call {
+    fn apply(&self, state: &mut Cheatcodes) -> Result {
+        let Self { current, min, max } = *self;
+        let Some(mutated) = I256::bound(current, min, max, state.test_runner()) else {
+            bail!("cannot bound {current} in [{min}, {max}] range")
+        };
+        Ok(mutated.abi_encode())
+    }
+}
+
 impl Cheatcode for randomUint_0Call {
     fn apply(&self, state: &mut Cheatcodes) -> Result {
         random_uint(state, None, None)

crates/cheatcodes/spec/src/vm.rs

@@ -17,3 +17,4 @@ mod invariants;
 pub use invariants::{fuzz_contract_with_calldata, invariant_strat, override_call_strat};
 
 mod mutators;
+pub use mutators::BoundMutator;