# dropnation/contract-fuzzer architecture

> Architecture diagram of the GitHub repository dropnation/contract-fuzzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dropnation/contract-fuzzer
- Repository: https://github.com/dropnation/contract-fuzzer

## Overview

Solfuzz fuzzes Solidity contracts against Echidna-style boolean properties. The main workflow starts at the CLI, compiles selected sources, extracts ABI properties and mutable call targets, then repeatedly generates arguments, sends transactions to an in-process EVM, and checks properties. On violations it writes a failure artifact and summary; replay is a separate best-effort CLI path. The graph reflects shown calls and README capabilities; diagnostics and replay are included, while details of configuration and artifact behavior are based only on the available excerpts.

Main entry points: [`src/solfuzz/cli.py`](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/cli.py) (CLI commands), [`src/solfuzz/fuzzer.py`](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/fuzzer.py) (Fuzz orchestration), [`src/solfuzz/utils.py`](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/utils.py) (Run artifacts), [`src/solfuzz/runtime.py`](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/runtime.py) (EVM runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and diagnostics"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_diagnostics["Environment diagnostics<br/>[system_info.py]"]
end

subgraph group_analysis["Contract preparation"]
  node_compiler["Solidity compiler<br/>[compiler.py]"]
  node_abi["ABI discovery<br/>[abi.py]"]
end

subgraph group_execution["Fuzz execution"]
  node_fuzzer["Fuzz orchestration<br/>[fuzzer.py]"]
  node_generator["Argument generation<br/>[generator.py]"]
  node_runtime["EVM runtime<br/>[runtime.py]"]
end

subgraph group_outputs["Artifacts and replay"]
  node_artifacts["Run artifacts<br/>[utils.py]"]
  node_summary["Run summary<br/>[report.py]"]
  node_failure["Failure replay<br/>[cli.py]"]
end

node_user(("Engineer"))
node_evm[("In-process EVM")]
node_solidity["Solidity sources"]

node_user -->|"invokes"| node_cli
node_cli -->|"gathers info"| node_diagnostics
node_cli -->|"compiles"| node_compiler
node_solidity -.->|"provides sources"| node_compiler
node_cli -->|"extracts contracts"| node_abi
node_cli -->|"starts run"| node_fuzzer
node_fuzzer -->|"discovers functions"| node_abi
node_fuzzer -->|"requests arguments"| node_generator
node_fuzzer -->|"deploys and transacts"| node_runtime
node_runtime -->|"executes transactions"| node_evm
node_fuzzer -->|"writes failures"| node_artifacts
node_fuzzer -->|"writes summary"| node_summary
node_summary -->|"writes JSON"| node_artifacts
node_cli -->|"creates run files"| node_artifacts
node_user -->|"requests replay"| node_failure
node_failure -->|"recompiles sources"| node_compiler
node_failure -->|"extracts contract"| node_abi
node_failure -->|"replays transaction"| node_runtime
node_failure -.->|"reads failure"| node_artifacts

click node_cli "https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/cli.py"
click node_diagnostics "https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/system_info.py"
click node_compiler "https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/compiler.py"
click node_abi "https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/abi.py"
click node_fuzzer "https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/fuzzer.py"
click node_generator "https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/generator.py"
click node_runtime "https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/runtime.py"
click node_artifacts "https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/utils.py"
click node_summary "https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/report.py"
click node_failure "https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/cli.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_diagnostics toneBlue
class node_compiler,node_abi,node_evm toneAmber
class node_fuzzer,node_generator,node_runtime toneMint
class node_artifacts,node_summary,node_failure toneRose
class node_user,node_solidity toneIndigo
```

## Components

### CLI and diagnostics

- [CLI commands](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/cli.py): `src/solfuzz/cli.py`
- [Environment diagnostics](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/system_info.py): `src/solfuzz/system_info.py`

### Contract preparation

- [Solidity compiler](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/compiler.py): `src/solfuzz/compiler.py`
- [ABI discovery](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/abi.py): `src/solfuzz/abi.py`

### Fuzz execution

- [Fuzz orchestration](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/fuzzer.py): `src/solfuzz/fuzzer.py`
- [Argument generation](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/generator.py): `src/solfuzz/generator.py`
- [EVM runtime](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/runtime.py): `src/solfuzz/runtime.py`

### Artifacts and replay

- [Run artifacts](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/utils.py): `src/solfuzz/utils.py`
- [Run summary](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/report.py): `src/solfuzz/report.py`
- [Failure replay](https://github.com/dropnation/contract-fuzzer/blob/main/src/solfuzz/cli.py): `src/solfuzz/cli.py`

### Other components

- **Engineer**
- **In-process EVM**
- **Solidity sources**

## Connections

- Engineer → CLI commands: invokes (evidence: `src/solfuzz/cli.py`)
- CLI commands → Environment diagnostics: gathers info (evidence: `src/solfuzz/cli.py`)
- CLI commands → Solidity compiler: compiles (evidence: `src/solfuzz/cli.py`)
- Solidity sources → Solidity compiler: provides sources (evidence: `README.md`)
- CLI commands → ABI discovery: extracts contracts (evidence: `src/solfuzz/cli.py`)
- CLI commands → Fuzz orchestration: starts run (evidence: `src/solfuzz/cli.py`)
- Fuzz orchestration → ABI discovery: discovers functions (evidence: `src/solfuzz/fuzzer.py`)
- Fuzz orchestration → Argument generation: requests arguments (evidence: `src/solfuzz/fuzzer.py`)
- Fuzz orchestration → EVM runtime: deploys and transacts (evidence: `src/solfuzz/fuzzer.py`)
- EVM runtime → In-process EVM: executes transactions (evidence: `src/solfuzz/runtime.py`)
- Fuzz orchestration → Run artifacts: writes failures (evidence: `src/solfuzz/fuzzer.py`)
- Fuzz orchestration → Run summary: writes summary (evidence: `src/solfuzz/fuzzer.py`)
- Run summary → Run artifacts: writes JSON (evidence: `src/solfuzz/report.py`)
- CLI commands → Run artifacts: creates run files (evidence: `src/solfuzz/cli.py`)
- Engineer → Failure replay: requests replay (evidence: `README.md`)
- Failure replay → Solidity compiler: recompiles sources (evidence: `src/solfuzz/cli.py`)
- Failure replay → ABI discovery: extracts contract (evidence: `src/solfuzz/cli.py`)
- Failure replay → EVM runtime: replays transaction (evidence: `src/solfuzz/cli.py`)
- Failure replay → Run artifacts: reads failure (evidence: `src/solfuzz/cli.py`)