feat: coverage-guided fuzzing for Tempo precompiles

Add SanitizerCoverage instrumentation support to collect edge coverage
from native Rust precompile execution during Foundry invariant/fuzz
tests. This makes the fuzzer coverage-guided for Tempo precompile code
paths, which were previously invisible to the EVM-level EdgeCovInspector.

Changes:
- New crate: foundry-tempo-coverage (crates/evm/tempo-coverage/)
  Provides thread-local coverage map, SanitizerCoverage callbacks
  (__sanitizer_cov_trace_pc_guard, __sanitizer_cov_trace_pc_guard_init),
  and RAII guard for map lifecycle management.

- New config field: tempo_precompile_coverage (bool, default false)
  Added to FuzzCorpusConfig, controls whether Tempo precompile coverage
  collection is active. When enabled, implicitly enables edge coverage.

- Executor wiring (TempoCoverageGuard in tempo_cov.rs)
  Wraps EVM transact calls with a coverage map guard that collects
  sancov hits into a scratch buffer, then merges them into the
  RawCallResult edge_coverage for the CorpusManager to consume.

- New build profile: fuzz (inherits release, no LTO/strip)
  Preserves sancov instrumentation through linking.

- Build script: scripts/build-fuzz.sh
  Convenience script to build forge with sancov RUSTFLAGS.

No changes to the tempo repository are required. SanitizerCoverage is a
compiler pass applied via RUSTFLAGS at build time; the callback symbols
are resolved by the linker from foundry-tempo-coverage.

Amp-Thread-ID: https://ampcode.com/threads/T-019c2f47-ec1b-76d3-ac35-429e06bf2460
Co-authored-by: Amp <amp@ampcode.com>

Author: grandizzy

Cargo.lock

@@ -18,6 +18,7 @@ members = [
   "crates/evm/coverage/",
   "crates/evm/evm/",
   "crates/evm/fuzz/",
+  "crates/evm/tempo-coverage/",
   "crates/evm/traces/",
   "crates/fmt/",
   "crates/forge/",
@@ -98,6 +99,17 @@ inherits = "release"
 lto = "fat"
 codegen-units = 1
 
+# Coverage-guided fuzzing of Tempo precompiles.
+# Inherits release performance but disables LTO and stripping so that
+# SanitizerCoverage instrumentation is preserved in the final binary.
+# Build with: cargo build --profile fuzz
+# The sancov RUSTFLAGS are set automatically via .cargo/config.toml [profile.fuzz].
+[profile.fuzz]
+inherits = "release"
+lto = false
+strip = "none"
+debug = "line-tables-only"
+
 # Speed up tests and dev build.
 [profile.dev.package]
 # Solc and artifacts.

Cargo.toml

@@ -113,6 +113,12 @@ pub struct FuzzCorpusConfig {
     pub corpus_min_size: usize,
     /// Whether to collect and display edge coverage metrics.
     pub show_edge_coverage: bool,
+    /// Whether to collect Tempo Rust precompile coverage via SanitizerCoverage.
+    /// When enabled, coverage from Tempo precompile execution is fed into the
+    /// same hitcount map used by the EVM edge coverage, making the fuzzer
+    /// coverage-guided for precompile code paths.
+    /// Requires building with sancov RUSTFLAGS (see docs/tempo-coverage.md).
+    pub tempo_precompile_coverage: bool,
 }
 
 impl FuzzCorpusConfig {
@@ -124,7 +130,12 @@ impl FuzzCorpusConfig {
 
     /// Whether edge coverage should be collected and displayed.
     pub fn collect_edge_coverage(&self) -> bool {
-        self.corpus_dir.is_some() || self.show_edge_coverage
+        self.corpus_dir.is_some() || self.show_edge_coverage || self.tempo_precompile_coverage
+    }
+
+    /// Whether Tempo precompile coverage collection is enabled.
+    pub fn collect_tempo_precompile_coverage(&self) -> bool {
+        self.tempo_precompile_coverage && self.collect_edge_coverage()
     }
 
     /// Whether coverage guided fuzzing is enabled.
@@ -141,6 +152,7 @@ impl Default for FuzzCorpusConfig {
             corpus_min_mutations: 5,
             corpus_min_size: 0,
             show_edge_coverage: false,
+            tempo_precompile_coverage: false,
         }
     }
 }

crates/config/src/fuzz.rs

@@ -20,6 +20,7 @@ foundry-compilers.workspace = true
 foundry-config.workspace = true
 foundry-evm-core.workspace = true
 foundry-evm-coverage.workspace = true
+foundry-tempo-coverage = { path = "../tempo-coverage" }
 foundry-evm-fuzz.workspace = true
 foundry-evm-hardforks.workspace = true
 foundry-evm-networks.workspace = true

crates/evm/evm/Cargo.toml

@@ -67,6 +67,9 @@ mod trace;
 
 pub use trace::TracingExecutor;
 
+mod tempo_cov;
+use tempo_cov::TempoCoverageGuard;
+
 const DURATION_BETWEEN_METRICS_REPORT: Duration = Duration::from_secs(5);
 
 sol! {
@@ -556,19 +559,35 @@ impl Executor {
     #[instrument(name = "call", level = "debug", skip_all)]
     pub fn call_with_env(&self, mut env: Env) -> eyre::Result<RawCallResult> {
         let mut stack = self.inspector().clone();
+        let tempo_cov = stack.inner.tempo_precompile_coverage;
         let mut backend = CowBackend::new_borrowed(self.backend());
-        let result = backend.inspect(&mut env, stack.as_inspector())?;
-        convert_executed_result(env, stack, result, backend.has_state_snapshot_failure())
+        let result = {
+            let _guard = tempo_cov.then(TempoCoverageGuard::new);
+            backend.inspect(&mut env, stack.as_inspector())?
+        };
+        let mut result =
+            convert_executed_result(env, stack, result, backend.has_state_snapshot_failure())?;
+        if tempo_cov {
+            TempoCoverageGuard::merge_into(&mut result);
+        }
+        Ok(result)
     }
 
     /// Execute the transaction configured in `env.tx`.
     #[instrument(name = "transact", level = "debug", skip_all)]
     pub fn transact_with_env(&mut self, mut env: Env) -> eyre::Result<RawCallResult> {
         let mut stack = self.inspector().clone();
+        let tempo_cov = stack.inner.tempo_precompile_coverage;
         let backend = self.backend_mut();
-        let result = backend.inspect(&mut env, stack.as_inspector())?;
+        let result = {
+            let _guard = tempo_cov.then(TempoCoverageGuard::new);
+            backend.inspect(&mut env, stack.as_inspector())?
+        };
         let mut result =
             convert_executed_result(env, stack, result, backend.has_state_snapshot_failure())?;
+        if tempo_cov {
+            TempoCoverageGuard::merge_into(&mut result);
+        }
         self.commit(&mut result);
         Ok(result)
     }

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

@@ -0,0 +1,59 @@
+use foundry_tempo_coverage::COVERAGE_MAP_SIZE;
+
+use super::RawCallResult;
+
+/// RAII guard that activates Tempo precompile coverage collection for the duration of an EVM call.
+///
+/// Allocates a thread-local scratch buffer, sets it as the active coverage map via
+/// `foundry_tempo_coverage`, and on drop clears it. The collected hits can then be merged
+/// into the `RawCallResult`'s `edge_coverage` via [`Self::merge_into`].
+pub(super) struct TempoCoverageGuard;
+
+thread_local! {
+    static TEMPO_COV_BUFFER: std::cell::RefCell<Vec<u8>> =
+        std::cell::RefCell::new(vec![0u8; COVERAGE_MAP_SIZE]);
+}
+
+impl TempoCoverageGuard {
+    pub(super) fn new() -> Self {
+        TEMPO_COV_BUFFER.with(|buf| {
+            let mut buf = buf.borrow_mut();
+            buf.fill(0);
+            let ptr = buf.as_mut_ptr();
+            let len = buf.len();
+            foundry_tempo_coverage::set_coverage_map(ptr, len);
+        });
+        Self
+    }
+
+    /// Merge Tempo precompile coverage hits into the `RawCallResult`'s edge coverage.
+    ///
+    /// If the result already has an `edge_coverage` map (from `EdgeCovInspector`), Tempo precompile hits
+    /// are added into it. If not, the Tempo precompile coverage buffer becomes the edge coverage.
+    pub(super) fn merge_into(result: &mut RawCallResult) {
+        TEMPO_COV_BUFFER.with(|buf| {
+            let buf = buf.borrow();
+            let has_any_hit = buf.iter().any(|&b| b > 0);
+            if !has_any_hit {
+                return;
+            }
+
+            match &mut result.edge_coverage {
+                Some(existing) => {
+                    for (existing_slot, &native_hit) in existing.iter_mut().zip(buf.iter()) {
+                        *existing_slot = existing_slot.saturating_add(native_hit);
+                    }
+                }
+                None => {
+                    result.edge_coverage = Some(buf.clone());
+                }
+            }
+        });
+    }
+}
+
+impl Drop for TempoCoverageGuard {
+    fn drop(&mut self) {
+        foundry_tempo_coverage::clear_coverage_map();
+    }
+}

crates/evm/evm/src/executors/tempo_cov.rs

@@ -339,6 +339,7 @@ pub struct InspectorStackInner {
     pub tracer: Option<Box<TracingInspector>>,
 
     // InspectorExt and other internal data.
+    pub tempo_precompile_coverage: bool,
     pub enable_isolation: bool,
     pub networks: NetworkConfigs,
     pub create2_deployer: Address,
@@ -462,6 +463,12 @@ impl InspectorStack {
         self.edge_coverage = yes.then(EdgeCovInspector::new).map(Into::into);
     }
 
+    /// Set whether to enable Tempo precompile coverage collection.
+    #[inline]
+    pub fn collect_tempo_precompile_coverage(&mut self, yes: bool) {
+        self.tempo_precompile_coverage = yes;
+    }
+
     /// Set whether to enable call isolation.
     #[inline]
     pub fn enable_isolation(&mut self, yes: bool) {

crates/evm/evm/src/inspectors/stack.rs

@@ -0,0 +1,14 @@
+[package]
+name = "foundry-tempo-coverage"
+description = "Tempo precompile coverage feedback for coverage-guided fuzzing"
+
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true

crates/evm/tempo-coverage/Cargo.toml

@@ -0,0 +1,83 @@
+//! Tempo precompile coverage feedback for coverage-guided fuzzing.
+//!
+//! Provides SanitizerCoverage callbacks and a thread-local coverage map pointer
+//! that can be set by the fuzzing executor to collect edge coverage from Tempo precompile code.
+
+use std::cell::Cell;
+use std::sync::atomic::{AtomicU32, Ordering};
+
+pub const COVERAGE_MAP_SIZE: usize = 65536;
+
+thread_local! {
+    static COVERAGE_MAP_PTR: Cell<*mut u8> = const { Cell::new(std::ptr::null_mut()) };
+    static COVERAGE_MAP_LEN: Cell<usize> = const { Cell::new(0) };
+}
+
+pub fn set_coverage_map(ptr: *mut u8, len: usize) {
+    COVERAGE_MAP_PTR.with(|c| c.set(ptr));
+    COVERAGE_MAP_LEN.with(|c| c.set(len));
+}
+
+pub fn clear_coverage_map() {
+    COVERAGE_MAP_PTR.with(|c| c.set(std::ptr::null_mut()));
+    COVERAGE_MAP_LEN.with(|c| c.set(0));
+}
+
+pub fn is_active() -> bool {
+    COVERAGE_MAP_PTR.with(|c| !c.get().is_null())
+}
+
+pub struct CoverageMapGuard;
+
+impl CoverageMapGuard {
+    pub fn new(ptr: *mut u8, len: usize) -> Self {
+        set_coverage_map(ptr, len);
+        Self
+    }
+}
+
+impl Drop for CoverageMapGuard {
+    fn drop(&mut self) {
+        clear_coverage_map();
+    }
+}
+
+#[inline(always)]
+pub fn record_hit(guard_id: u32) {
+    COVERAGE_MAP_PTR.with(|ptr_cell| {
+        let ptr = ptr_cell.get();
+        if ptr.is_null() {
+            return;
+        }
+        COVERAGE_MAP_LEN.with(|len_cell| {
+            let len = len_cell.get();
+            let idx = guard_id as usize % len;
+            unsafe {
+                let slot = ptr.add(idx);
+                *slot = (*slot).wrapping_add(1);
+            }
+        });
+    });
+}
+
+static GUARD_COUNTER: AtomicU32 = AtomicU32::new(1);
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn __sanitizer_cov_trace_pc_guard_init(mut start: *mut u32, stop: *mut u32) {
+    while start < stop {
+        let id = GUARD_COUNTER.fetch_add(1, Ordering::Relaxed);
+        unsafe {
+            *start = id;
+            start = start.add(1);
+        }
+    }
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn __sanitizer_cov_trace_pc_guard(guard: *mut u32) {
+    let id = unsafe { *guard };
+    if id == 0 {
+        return;
+    }
+    record_hit(id);
+}

crates/evm/tempo-coverage/src/lib.rs

@@ -746,6 +746,11 @@ impl<'a> FunctionRunner<'a> {
         executor
             .inspector_mut()
             .collect_edge_coverage(invariant_config.corpus.collect_edge_coverage());
+        executor
+            .inspector_mut()
+            .collect_tempo_precompile_coverage(
+                invariant_config.corpus.collect_tempo_precompile_coverage(),
+            );
         let mut config = invariant_config.clone();
         let (failure_dir, failure_file) = test_paths(
             &mut config.corpus,
@@ -1041,6 +1046,11 @@ impl<'a> FunctionRunner<'a> {
         // Enable edge coverage if running with coverage guided fuzzing or with edge coverage
         // metrics (useful for benchmarking the fuzzer).
         executor.inspector_mut().collect_edge_coverage(fuzz_config.corpus.collect_edge_coverage());
+        executor
+            .inspector_mut()
+            .collect_tempo_precompile_coverage(
+                fuzz_config.corpus.collect_tempo_precompile_coverage(),
+            );
         // Load persisted counterexample, if any.
         let persisted_failure =
             foundry_common::fs::read_json_file::<BaseCounterExample>(failure_file.as_path()).ok();