This repository was archived by the owner on Apr 16, 2026. It is now read-only.
Repository navigation
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an
ExternalCheatcodetrait 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
VmCallsenum. 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 publicExternalCheatcodetrait with tri-state return (Ok(Some)= handled,Ok(None)= skip,Err= revert). Public accessor methods onCheatsCtxt(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 onCheatcodes,register_external_cheatcode()method, and fallback dispatch inapply_cheatcode()that tries external handlers onUnknownSelectorbefore erroring.crates/evm/evm/src/inspectors/stack.rs:.external_cheatcode(handler)builder method onInspectorStackBuilder.Consumer API
Testing
cargo clippy -p foundry-cheatcodes -p foundry-evm -p forge -- -D warnings— cleancargo check -p forge— cleanPrompted by: zerosnacks