# brunoerg/bitcoinfuzz architecture

> Architecture diagram of the GitHub repository brunoerg/bitcoinfuzz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brunoerg/bitcoinfuzz
- Repository: https://github.com/brunoerg/bitcoinfuzz

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Fuzzing Engine & Core Driver
    subgraph "Fuzzing Engine & Core Driver"
        FE["Fuzzing Engine\n(main.cpp, driver.cpp, driver.h)"]:::core
        BF["Bitcoin Fuzz Core\n(include/bitcoinfuzz)"]:::core
    end

    %% Modules
    subgraph "Modules"
        modBitcoin["Bitcoin Module"]:::module
        modBtcd["btcd Module"]:::module
        modRustBitcoin["rust-bitcoin Module"]:::module
        modRustMiniscript["rust-miniscript Module"]:::module
        modMako["mako Module"]:::module
        modLDK["LDK Module"]:::module
        modLND["LND Module"]:::module
        modNLightning["NLightning Module"]:::module
    end

    %% Build & Integration and CI
    subgraph "Build & Integration"
        buildScripts["Build Scripts\n(Makefile, merge.sh)"]:::build
        ci["CI & Config\n(.github/workflows)"]:::build
    end

    %% External Dependencies
    subgraph "External Dependencies"
        clang["Clang/LibFuzzer"]:::external
        boost["Boost Libraries"]:::external
        cargo["Cargo (Rust)"]:::external
    end

    %% Connections from Fuzzing Engine to Modules (with preprocessor flag annotations)
    FE -->|" -DBITCOIN"| modBitcoin
    FE -->|" -DBTCD"| modBtcd
    FE -->|" -DRUST_BITCOIN"| modRustBitcoin
    FE -->|" -DRUST_MINISCRIPT"| modRustMiniscript
    FE -->|" -DMAKO"| modMako
    FE -->|" -DLDK"| modLDK
    FE -->|" -DLND"| modLND
    FE -->|" -DNLIGHTNING"| modNLightning

    %% Modules reporting back to Fuzzing Engine
    modBitcoin -->|"reports"| FE
    modBtcd -->|"reports"| FE
    modRustBitcoin -->|"reports"| FE
    modRustMiniscript -->|"reports"| FE
    modMako -->|"reports"| FE
    modLDK -->|"reports"| FE
    modLND -->|"reports"| FE
    modNLightning -->|"reports"| FE

    %% External Dependencies used by Modules
    modBitcoin -->|"uses Boost"| boost
    modRustBitcoin -->|"uses Cargo"| cargo
    modRustMiniscript -->|"uses Cargo"| cargo
    modMako -->|"requires Clang"| clang
    modLDK -->|"requires Clang"| clang
    modLND -->|"requires Clang"| clang
    modNLightning -->|"requires Clang"| clang

    %% Build & Integration impacting components
    buildScripts --> FE
    buildScripts --> modBitcoin
    buildScripts --> modBtcd
    buildScripts --> modRustBitcoin
    buildScripts --> modRustMiniscript
    buildScripts --> modMako
    buildScripts --> modLDK
    buildScripts --> modLND
    buildScripts --> modNLightning
    ci --> buildScripts

    %% Click Events
    click FE "https://github.com/brunoerg/bitcoinfuzz/blob/v2/main.cpp"
    click BF "https://github.com/brunoerg/bitcoinfuzz/tree/v2/include/bitcoinfuzz/"
    click modBitcoin "https://github.com/brunoerg/bitcoinfuzz/tree/v2/modules/bitcoin/"
    click modBtcd "https://github.com/brunoerg/bitcoinfuzz/tree/v2/modules/btcd/"
    click modRustBitcoin "https://github.com/brunoerg/bitcoinfuzz/tree/v2/modules/rustbitcoin/"
    click modRustMiniscript "https://github.com/brunoerg/bitcoinfuzz/tree/v2/modules/rustminiscript/"
    click modMako "https://github.com/brunoerg/bitcoinfuzz/tree/v2/modules/mako/"
    click modLDK "https://github.com/brunoerg/bitcoinfuzz/tree/v2/modules/ldk/"
    click modLND "https://github.com/brunoerg/bitcoinfuzz/tree/v2/modules/lnd/"
    click modNLightning "https://github.com/brunoerg/bitcoinfuzz/tree/v2/modules/nlightning/"
    click buildScripts "https://github.com/brunoerg/bitcoinfuzz/tree/v2/Makefile"
    click ci "https://github.com/brunoerg/bitcoinfuzz/tree/v2/.github/workflows/"

    %% Styles
    classDef core fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef module fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef build fill:#87CEFA,stroke:#4682B4,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
```
