Skip to content
This repository was archived by the owner on Apr 16, 2026. It is now read-only.

feat(cheatcodes): add ExternalCheatcode trait for extensible cheatcodes - #403

Closed
decofe wants to merge 2 commits into
tempofrom
zerosnacks/external-cheatcodes
Closed

decofe wants to merge 2 commits into
tempofrom
zerosnacks/external-cheatcodes

Conversation

@decofe

@decofe decofe commented Apr 10, 2026

Copy link
Copy Markdown
Member

Summary

Adds an ExternalCheatcode trait that allows Foundry library consumers to register custom cheatcodes without forking.

Motivation

Ecosystem teams (e.g. security tooling like phylax.systems) want to extend Foundry with custom cheatcodes — custom assertions, storage snapshots, invariant checkers — while reusing the fuzzer, test runner, and cheatcode-augmented EVM runtime. Today the only way is to fork Foundry and modify the sealed VmCalls enum. This PR adds a plugin-style extension point.

Inspired by this discussion on the Foundry 2.0 SDK vision.

Changes

  • crates/cheatcodes/src/lib.rs: new public ExternalCheatcode trait with tri-state return (Ok(Some) = handled, Ok(None) = skip, Err = revert). Public accessor methods on CheatsCtxt (state(), ecx(), caller(), gas_limit()) so external handlers can interact with EVM state without exposing raw fields.
  • crates/cheatcodes/src/inspector.rs: external_cheatcodes: Vec<Arc<dyn ExternalCheatcode>> field on Cheatcodes, register_external_cheatcode() method, and fallback dispatch in apply_cheatcode() that tries external handlers on UnknownSelector before erroring.
  • crates/evm/evm/src/inspectors/stack.rs: .external_cheatcode(handler) builder method on InspectorStackBuilder.

Consumer API

use std::sync::Arc;
use foundry_cheatcodes::{CheatsCtxt, ExternalCheatcode};

#[derive(Debug)]
struct MyCheatcodes;

impl ExternalCheatcode for MyCheatcodes {
    fn call(&self, calldata: &[u8], ccx: &mut CheatsCtxt) -> foundry_cheatcodes::Result<Option<Vec<u8>>> {
        if calldata.len() < 4 { return Ok(None) }
        // decode + handle known selectors, return Ok(None) for unknown
        Ok(None)
    }
}

let executor = ExecutorBuilder::new()
    .inspectors(|stack| {
        stack
            .cheatcodes(cheats_config)
            .external_cheatcode(Arc::new(MyCheatcodes))
    })
    .build(env, backend);

Testing

  • cargo clippy -p foundry-cheatcodes -p foundry-evm -p forge -- -D warnings — clean
  • cargo check -p forge — clean

Prompted by: zerosnacks

Adds an ExternalCheatcode trait that allows library consumers to register
custom cheatcodes without forking Foundry. External handlers are tried
in order when a call to the cheatcode address does not match any built-in
selector.

Key changes:
- ExternalCheatcode trait with tri-state return (Ok(Some), Ok(None), Err)
- Registration via Cheatcodes::register_external_cheatcode and builder API
- Public accessor methods on CheatsCtxt for external handler use
- Fallback dispatch in apply_cheatcode on UnknownSelector

Co-authored-by: zerosnacks <95942363+zerosnacks@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019d7860-7f04-73ef-a9f9-aa04f6f76387
- Fix nightly rustfmt doc comment wrapping
- Add tests for registration, clone semantics, and multi-handler coexistence
- Include example handler impls (TestExternalCheatcode, RevertingExternalCheatcode)

Co-authored-by: zerosnacks <95942363+zerosnacks@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019d7860-7f04-73ef-a9f9-aa04f6f76387
@zerosnacks zerosnacks closed this Apr 10, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants