Deep Fuzzing (Foundry)
Relevant source files
The following files were used as context for generating this wiki page:
Deep Fuzzing in the Canon Guard project refers to an intensified testing strategy using the Foundry framework to identify edge cases and security vulnerabilities within the multisig solution. This approach extends standard property-based testing by significantly increasing the number of fuzzing runs and utilizing advanced configurations to explore a broader state space of the smart contracts.
The primary objective is to validate critical invariants related to the SafeEntrypoint, ActionHub, and various Action Builders. By simulating thousands of random transaction sequences, the system ensures that security constraints—such as time-delayed execution, cap limits, and approval mechanisms—remain robust under all conditions.
Sources: README.md, CLAUDE.md, test/invariants/PROPERTIES.md
Testing Architecture
The fuzzing architecture is built on Foundry's forge test runner, supplemented by specialized tools like Medusa for invariant testing. The system categorizes tests into unit, integration, and invariant levels, with "Deep Fuzzing" specifically targeting the unit test suite with high-iteration parameters.
Execution Flow
The following diagram illustrates the flow from a developer command to the execution of deep fuzzing runs:
The workflow ensures that unit tests, which are isolated from externalities, are subjected to exhaustive state exploration.
Sources: package.json:28, foundry.toml:22-24, README.md:37-39
Configuration and Profiles
Foundry is configured with specific profiles to optimize for testing performance and depth. Deep fuzzing utilizes the test profile, which enables Intermediate Representation (IR) compilation to handle complex contract structures.
Fuzzing Parameters
| Parameter | Default Value | Deep Fuzzing Value | Description |
|---|---|---|---|
runs | 1000 | 5000 | Number of iterations per fuzz test function |
via_ir | false | true | Enables the IR-based code generator for better optimization |
solc_version | 0.8.30 | 0.8.30 | Specific Solidity compiler version used |
evm_version | prague | prague | Targeted EVM version for execution |
Sources: foundry.toml:13-24, package.json:28
Invariant Testing Configuration
For long-running security assertions, the project uses a separate invariant testing configuration:
- Timeout: 1000 seconds
- Fail on Revert: Enabled
- Corpus Directory:
test/invariants/fuzz/corpus - Show Metrics: Enabled
Sources: foundry.toml:27-32
Invariant Scope and Logic
Deep fuzzing and invariant testing target the core security properties of the Canon Guard ecosystem. These tests ensure that the system cannot enter a "frozen" or inconsistent state.
Targeted Components
CanonGuardandCanonGuardFactoryActionHuband its implementations (e.g.,SimpleActions,CappedTokenTransfers)SafeEntrypointfor transaction lifecycle management
Security Invariants
| Category | Invariant Name | Description |
|---|---|---|
| Cap/Accounting | invariant_capNeverExceeded | Hub-defined limits are never bypassed across epoch boundaries. |
| State Consistency | invariant_sanity_ghostStateConsistency | Ensures ghost state hashes map to valid action builder addresses. |
| Timing | invariant_transactionTimingIsCorrect | Validates that expiresAt > executableAt and executableAt >= queuedAt. |
| Queue Management | invariant_queueHasNoDuplicates | Prevents the same action builder from appearing multiple times in the queue. |
Sources: test/invariants/PROPERTIES.md:3-35
Integration with Medusa
While Foundry handles deep unit fuzzing, Medusa is utilized for continuous invariant testing (fuzzing campaigns). Medusa operates on a specific configuration that complements Foundry's capabilities.
Medusa is configured to use 10 workers and a call sequence length of 100 to find deep state vulnerabilities.
Sources: medusa.json:2-10, package.json:24, README.md:45-47
Development Commands
Developers can trigger different depths of fuzzing using the following scripts defined in the project:
- Standard Unit Tests:
yarn test:unit(1000 runs) - Deep Fuzzing:
yarn test:unit:deep(5000 runs) - Invariant Campaign:
yarn test:fuzz(Medusa-based) - Symbolic Execution:
yarn test:symbolic(Using Halmos for formal verification)
Sources: package.json:21-28, README.md:31-52
Deep Fuzzing via Foundry serves as a critical layer in the Canon Guard security stack, bridging the gap between standard unit testing and formal verification by providing high-confidence state exploration.