Practical overview
When it fits
Use Bitcoinfuzz when you need to compare how multiple compiled Bitcoin implementations or libraries respond to fuzzing inputs, such as comparing Bitcoin Core with rust-bitcoin for a BIP32 key-generation target.
Who it is for
- Developers testing Bitcoin implementations or libraries for differences in behavior.
- Maintainers investigating discrepancies across protocol implementations.
- Teams developing regression tests from differential fuzzing failures.
Documented uses
- Compare responses from selected compiled implementations for a fuzzing target.
- Fuzz Bitcoin-related libraries to investigate implementation inconsistencies.
- Inspect module outputs while debugging a target.
- Use differential failures as the basis for regression tests.
Requirements & limits
The repository is public and licensed under MIT. The project is developed and supported on Linux; its README recommends Docker for macOS and Windows.
- Only compiled modules can be selected; requesting a module that was not compiled causes an error.
- If MODULES is unset or empty, the tool loads all compiled modules.
- The project depends on multiple supported projects and their runtimes, and provides Docker workflows to ease setup.
- Certain modules require LLVM tooling and compiler flags; the stated minimum Clang version for those flags is 10.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Build selected Bitcoinfuzz modules
Use the automatic build script to compile the modules named in CXXFLAGS.
Before you start
- A Linux environment, the platform developed and supported by the project.
- LLVM tooling including Clang; Clang 10 or later is required for certain flags.
- The bitcoinfuzz repository and its project dependencies.
Steps
Set CXXFLAGS to the desired module defines, such as -DLDK -DLND.
Run ./scripts/auto_build.py.
Expected outcome
The script builds the modules selected by CXXFLAGS.
Guide limitations
- The project has dependencies from the implementations and runtimes of the projects it supports.
- For module-specific dependencies and instructions, consult that module's README.
- The project warns that it is a work in progress and may not be stable.
Run AFL++ fuzzing against a selected target
Follow the README’s command-line workflow to start AFL++ fuzzing with bitcoinfuzz.
Before you start
- A built bitcoinfuzz executable.
- AFL++ and its afl-clang-fast compiler wrappers.
Steps
Clone the AFL++ repository and build its source-only components.
Build bitcoinfuzz with CC and CXX set to AFL++’s afl-clang-fast wrappers.
Create input and output directories and add an initial input file.
Run afl-fuzz with a FUZZ target, the input and output directories, and ./bitcoinfuzz as the target.
Expected outcome
AFL++ starts a fuzzing run using the specified target and directories.
Guide limitations
- The README points to RUNNING.md for container-based AFL++ instructions and notes a Linux core_pattern caveat.
- This workflow documents starting a run; it does not guarantee findings or successful results.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 13 October 2026
- Original website title
- bitcoinfuzz/bitcoinfuzz · Official homepage title · retained in its source language