How brunoerg/bitcoinfuzz works
Main Components
• Fuzzing Engine & Core Driver: The entry point (main.cpp) along with driver.cpp/driver.h and code inside the “include/bitcoinfuzz” directory represent the central fuzzing workflow.
• Modules/Subsystems: Under the “modules” directory, you have multiple subdirectories, each encapsulating a different Bitcoin or Lightning module. These include:
• modules/bitcoin (Bitcoin Core functionality, with extensive source files and libraries)
• modules/btcd (btcd-related components)
• modules/rustbitcoin (Rust Bitcoin libraries)
• modules/rustminiscript (Rust Miniscript libraries)
• modules/mako (Mako’s script-related components)
• modules/ldk (Lightning Development Kit integration)
• modules/lnd (Lightning daemon support)
• modules/nlightning (another Lightning implementation)
• Build & Integration Scripts: The top-level Makefile, merge.sh, and separate Makefiles within each module are used to compile these components and integrate them into the bitcoinfuzz executable.
• External Dependencies: The project integrates with external tools and libraries—clang/libfuzzer (for compilation with sanitizers), the Boost filesystem/system libraries (for Bitcoin Core), and Cargo for compiling the Rust components, among others.
Relationships and Interactions
• Integration of external dependencies. For example, show that the “bitcoin” module relies on Boost, while the “rustbitcoin” and “rustminiscript” modules require Cargo (Rust’s build tool) and link their libraries back to the central fuzzer.
• Build and configuration elements are also crucial. Illustrate that both GitHub Actions workflows (in .github/workflows) and top-level build scripts help in integration and continuous testing.
Architectural Patterns and Design Principles
• Modular Architecture: Since each module is self-contained (each with its own Makefile and build steps), the design emphasizes loose coupling—each module can be built and tested independently before integration.
• Plugin or Extension Style: The modules are designed to be “plugged” into the main fuzzing engine through the use of preprocessor flags (e.g., -DBITCOIN), suggesting a design that allows for easy extension and customization.
• Differential Testing: At a high level, bitcoinfuzz treats each module as an independent implementation of similar functionality, comparing outputs to identify discrepancies (as noted in the “Bugs/inconsistences/mismatches” list).