feat(invariant): gas-envelope fuzzing via invariant.gas_fuzz

crates/config/src/invariant.rs

@@ -147,6 +147,16 @@ pub struct InvariantConfig {
     ///
     /// Example: `check_interval = 10` means assert after calls 10, 20, 30, ... and the last call.
     pub check_interval: u32,
+    /// Enable gas-envelope fuzzing and per-selector gas reporting.
+    /// Default `false` (no behavior change, no new output).
+    ///
+    /// Turns on three things at once:
+    /// 1. Per-call `tx.gas_limit` drawn uniformly from `[2^24, 2^25)` to exercise gas-conditional
+    ///    EVM dispatch (refund accounting, EIP-150 1/64 retention, OOG dispatch at the EIP-7825
+    ///    cap).
+    /// 2. Per-`(target, selector)` `max_gas` tracking (adds the "Max Gas" column).
+    /// 3. Per-selector reproducer block: the call sequence that produced each peak.
+    pub gas_fuzz: bool,
 }
 
 impl Default for InvariantConfig {
@@ -169,6 +179,7 @@ impl Default for InvariantConfig {
             max_time_delay: None,
             max_block_delay: None,
             check_interval: 1,
+            gas_fuzz: false,
         }
     }
 }

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

@@ -282,6 +282,7 @@ impl WorkerCorpusSeed {
         fuzzed_function: Option<&Function>,
         fuzzed_contracts: Option<&FuzzRunIdentifiedContracts>,
         dynamic: Option<DynamicTargetCtx<'_>>,
+        gas_fuzz: bool,
     ) -> Result<Self> {
         let mut seed = Self::empty(config).with_optimization_state(config);
         let Some(corpus_dir) = &config.corpus_dir else {
@@ -321,7 +322,7 @@ impl WorkerCorpusSeed {
                 metrics: Some(&mut seed.metrics),
             };
             let ReplayOutcome { keep_entry, cmp_seq, failed_replays, .. } =
-                replay_corpus_sequence(&tx_seq, executor, target, coverage)?;
+                replay_corpus_sequence(&tx_seq, executor, target, coverage, gas_fuzz)?;
             seed.failed_replays += failed_replays;
             if !keep_entry {
                 continue;
@@ -351,6 +352,7 @@ impl WorkerCorpusSeed {
         entries: impl IntoIterator<Item = CampaignCorpusEntry>,
         executor: &Executor<FEN>,
         target: ReplayTarget<'_>,
+        gas_fuzz: bool,
         optimization_best: Option<(I256, &[BasicTxDetails])>,
     ) -> Result<()> {
         let mut history_map = self.history_map.clone();
@@ -367,7 +369,7 @@ impl WorkerCorpusSeed {
                     metrics: None,
                 };
                 let ReplayOutcome { keep_entry, new_coverage, .. } =
-                    replay_corpus_sequence(&entry.tx_seq, executor, target, coverage)?;
+                    replay_corpus_sequence(&entry.tx_seq, executor, target, coverage, gas_fuzz)?;
                 if !keep_entry || !new_coverage {
                     continue;
                 }
@@ -496,6 +498,18 @@ pub struct WorkerCorpus {
     optimization_best_value: Option<I256>,
     /// Optimization mode: the call sequence that produced the best value.
     optimization_best_sequence: Vec<BasicTxDetails>,
+    /// `invariant.gas_fuzz` for this campaign; gates persisted `gas_limit` overrides on load.
+    gas_fuzz: bool,
+}
+
+/// Context used by the master worker to replay persisted corpus entries.
+#[derive(Clone, Copy, Default)]
+pub struct WorkerCorpusReplayConfig<'a, FEN: FoundryEvmNetwork> {
+    pub executor: Option<&'a Executor<FEN>>,
+    pub fuzzed_function: Option<&'a Function>,
+    pub fuzzed_contracts: Option<&'a FuzzRunIdentifiedContracts>,
+    pub dynamic: Option<DynamicTargetCtx<'a>>,
+    pub gas_fuzz: bool,
 }
 
 /// Refs used during corpus replay to register contracts deployed mid-sequence as fuzz targets,
@@ -573,9 +587,18 @@ fn replay_corpus_sequence<FEN: FoundryEvmNetwork>(
     executor: &Executor<FEN>,
     target: ReplayTarget<'_>,
     coverage: ReplayCoverage<'_>,
+    gas_fuzz: bool,
 ) -> Result<ReplayOutcome> {
     let mut executor = executor.clone();
-    replay_corpus_sequence_with_executor(tx_seq, &mut executor, target, coverage, false, true)
+    replay_corpus_sequence_with_executor(
+        tx_seq,
+        &mut executor,
+        target,
+        coverage,
+        false,
+        true,
+        gas_fuzz,
+    )
 }
 
 fn replay_corpus_sequence_with_executor<FEN: FoundryEvmNetwork>(
@@ -585,13 +608,22 @@ fn replay_corpus_sequence_with_executor<FEN: FoundryEvmNetwork>(
     mut coverage: ReplayCoverage<'_>,
     trace_sync: bool,
     reject_unmatched_function: bool,
+    gas_fuzz: bool,
 ) -> Result<ReplayOutcome> {
     let mut cmp_seq = Vec::with_capacity(tx_seq.len());
     let mut failed_replays = 0;
     let mut new_coverage_for_entry = false;
     let mut created: Vec<Address> = Vec::new();
 
     for tx in tx_seq {
+        let mut replay_tx;
+        let tx = if gas_fuzz {
+            tx
+        } else {
+            replay_tx = tx.clone();
+            replay_tx.call_details.gas_limit = None;
+            &replay_tx
+        };
         if WorkerCorpus::can_replay_tx(tx, target.fuzzed_function, target.fuzzed_contracts) {
             let mut call_result = execute_tx(executor, tx)?;
             cmp_seq.push(call_result.evm_cmp_values.take().unwrap_or_default());
@@ -657,31 +689,36 @@ impl WorkerCorpus {
         id: usize,
         config: FuzzCorpusConfig,
         tx_generator: BoxedStrategy<BasicTxDetails>,
-        // Only required by master worker (id = 0) to replay existing corpus.
-        executor: Option<&Executor<FEN>>,
-        fuzzed_function: Option<&Function>,
-        fuzzed_contracts: Option<&FuzzRunIdentifiedContracts>,
-        dynamic: Option<DynamicTargetCtx<'_>>,
+        replay: WorkerCorpusReplayConfig<'_, FEN>,
     ) -> Result<Self> {
+        let WorkerCorpusReplayConfig {
+            executor,
+            fuzzed_function,
+            fuzzed_contracts,
+            dynamic,
+            gas_fuzz,
+        } = replay;
         let seed = if id == 0 {
             WorkerCorpusSeed::load_from_disk(
                 &config,
                 executor,
                 fuzzed_function,
                 fuzzed_contracts,
                 dynamic,
+                gas_fuzz,
             )?
         } else {
             WorkerCorpusSeed::empty(&config).with_optimization_state(&config)
         };
-        Ok(Self::from_seed(id, config, tx_generator, seed))
+        Ok(Self::from_seed(id, config, tx_generator, seed, gas_fuzz))
     }
 
     pub(crate) fn from_seed(
         id: usize,
         config: FuzzCorpusConfig,
         tx_generator: BoxedStrategy<BasicTxDetails>,
         seed: WorkerCorpusSeed,
+        gas_fuzz: bool,
     ) -> Self {
         let mutation_generator = prop_oneof![
             Just(MutationType::Splice),
@@ -724,6 +761,7 @@ impl WorkerCorpus {
             last_sync_metrics: Default::default(),
             optimization_best_value: seed.optimization_best_value,
             optimization_best_sequence: seed.optimization_best_sequence,
+            gas_fuzz,
         }
     }
 
@@ -1389,6 +1427,7 @@ impl WorkerCorpus {
                     coverage,
                     true,
                     false,
+                    self.gas_fuzz,
                 )?;
 
             let sync_path = &entry.path;
@@ -1700,6 +1739,7 @@ mod tests {
                 target: Address::ZERO,
                 calldata: Bytes::new(),
                 value: None,
+                gas_limit: None,
             },
         }
     }
@@ -1721,7 +1761,13 @@ mod tests {
     }
 
     fn worker_corpus(id: usize, corpus_root: PathBuf, seed: WorkerCorpusSeed) -> WorkerCorpus {
-        WorkerCorpus::from_seed(id, corpus_config(corpus_root), Just(basic_tx()).boxed(), seed)
+        WorkerCorpus::from_seed(
+            id,
+            corpus_config(corpus_root),
+            Just(basic_tx()).boxed(),
+            seed,
+            false,
+        )
     }
 
     fn empty_worker_corpus(id: usize, corpus_root: PathBuf) -> WorkerCorpus {
@@ -1755,6 +1801,7 @@ mod tests {
                 target: Address::ZERO,
                 calldata,
                 value: None,
+                gas_limit: None,
             },
         };
         let cmp = CmpOperands {
@@ -1875,10 +1922,7 @@ mod tests {
             1,
             corpus_config(corpus_root),
             Just(basic_tx()).boxed(),
-            None,
-            None,
-            None,
-            None,
+            WorkerCorpusReplayConfig::default(),
         )
         .unwrap();
 
@@ -1921,8 +1965,13 @@ mod tests {
             optimization_best_sequence: tx_seq,
         };
 
-        let manager =
-            WorkerCorpus::from_seed(1, corpus_config(corpus_root), Just(basic_tx()).boxed(), seed);
+        let manager = WorkerCorpus::from_seed(
+            1,
+            corpus_config(corpus_root),
+            Just(basic_tx()).boxed(),
+            seed,
+            false,
+        );
 
         assert_eq!(manager.in_memory_corpus.len(), 1);
         assert_eq!(manager.history_map, vec![1, 2, 3]);

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

@@ -1,6 +1,6 @@
 use crate::executors::{
     DURATION_BETWEEN_METRICS_REPORT, EarlyExit, Executor, FuzzTestTimer, RawCallResult,
-    corpus::{GlobalCorpusMetrics, WorkerCorpus},
+    corpus::{GlobalCorpusMetrics, WorkerCorpus, WorkerCorpusReplayConfig},
 };
 use alloy_dyn_abi::JsonAbiExt;
 use alloy_json_abi::Function;
@@ -284,6 +284,7 @@ impl<FEN: FoundryEvmNetwork> FuzzedExecutor<FEN> {
                     target: address,
                     calldata: calldata.clone(),
                     value: None,
+                    gas_limit: None,
                 },
             }],
             &[cmp_values],
@@ -459,18 +460,24 @@ impl<FEN: FoundryEvmNetwork> FuzzedExecutor<FEN> {
             warp: None,
             roll: None,
             sender: Default::default(),
-            call_details: CallDetails { target: Default::default(), calldata, value: None },
+            call_details: CallDetails {
+                target: Default::default(),
+                calldata,
+                value: None,
+                gas_limit: None,
+            },
         });
 
         let mut corpus = WorkerCorpus::new(
             worker_id,
             self.config.corpus.clone(),
             strategy.boxed(),
-            // Master worker replays the persisted corpus using the executor
-            (worker_id == 0).then_some(&self.executor_f),
-            Some(func),
-            None, // fuzzed_contracts for invariant tests
-            None, // dynamic target ctx (invariant-only)
+            WorkerCorpusReplayConfig {
+                // Master worker replays the persisted corpus using the executor.
+                executor: (worker_id == 0).then_some(&self.executor_f),
+                fuzzed_function: Some(func),
+                ..Default::default()
+            },
         )?;
         let mut executor = self.executor_f.clone();
 

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

@@ -469,6 +469,7 @@ mod tests {
                 target: Address::repeat_byte(sender.wrapping_add(1)),
                 calldata: Bytes::from(vec![0, 0, 0, sender]),
                 value: None,
+                gas_limit: None,
             },
         }
     }
@@ -679,7 +680,7 @@ mod tests {
                 3,
                 0x30,
                 "transfer(address)",
-                InvariantMetrics { calls: 3, reverts: 1, discards: 0 },
+                InvariantMetrics { calls: 3, reverts: 1, discards: 0, ..Default::default() },
                 3,
                 0,
             ),
@@ -690,7 +691,7 @@ mod tests {
                 1,
                 0x10,
                 "transfer(address)",
-                InvariantMetrics { calls: 1, reverts: 0, discards: 2 },
+                InvariantMetrics { calls: 1, reverts: 0, discards: 2, ..Default::default() },
                 1,
                 4,
             ),
@@ -701,7 +702,7 @@ mod tests {
                 2,
                 0x20,
                 "approve(address)",
-                InvariantMetrics { calls: 2, reverts: 1, discards: 1 },
+                InvariantMetrics { calls: 2, reverts: 1, discards: 1, ..Default::default() },
                 2,
                 0,
             ),
@@ -716,9 +717,15 @@ mod tests {
         assert_eq!(result.last_run_inputs[0].sender, Address::repeat_byte(0x30));
 
         let transfer_metrics = result.metrics.get("transfer(address)").unwrap();
-        assert_eq!(transfer_metrics, &InvariantMetrics { calls: 4, reverts: 1, discards: 2 });
+        assert_eq!(
+            transfer_metrics,
+            &InvariantMetrics { calls: 4, reverts: 1, discards: 2, ..Default::default() }
+        );
         let approve_metrics = result.metrics.get("approve(address)").unwrap();
-        assert_eq!(approve_metrics, &InvariantMetrics { calls: 2, reverts: 1, discards: 1 });
+        assert_eq!(
+            approve_metrics,
+            &InvariantMetrics { calls: 2, reverts: 1, discards: 1, ..Default::default() }
+        );
 
         let coverage = result.line_coverage.unwrap();
         assert_eq!(coverage.get(&B256::ZERO).unwrap().get(7).unwrap().get(), 6);