# starkware-bitcoin/bitcoin architecture

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

- Interactive diagram: https://gitdiagram.com/starkware-bitcoin/bitcoin
- Repository: https://github.com/starkware-bitcoin/bitcoin

## Overview

##### Project Type and Purpose
- Bitcoin Knots is a full-node cryptocurrency client (fork of Bitcoin Core) with P2P networking, on-disk blockchain storage, consensus/validation logic, wallet, RPC/CLI interfaces, and optional Qt GUI.

##### Top-Level Components to Sketch
a. Networking Layer (P2P)
- src/net.cpp, src/net_processing.cpp, src/peerman, src/ipc: handles peer discovery, gossip, message serialization, connection management.
- External service: Internet (other Bitcoin nodes).
b. Consensus & Validation
- src/consensus, src/validation, src/chainstate: enforces consensus rules, block & transaction validation, UTXO set maintenance.
c. Storage Layer
- src/txdb, src/dbwrapper, src/flatfile: on-disk block files (.blk/.idx), leveldb for UTXO, BerkeleyDB for wallet.
d. Node Kernel & Interfaces
- src/kernel, src/node: orchestrates interactions between networking, consensus, storage, and higher-level interfaces.
e. RPC & CLI Interfaces
- src/rpc, bitcoin-cli: JSON-RPC server listens on HTTP (or zmq), services client requests.
f. Wallet Subsystem
- src/wallet: BDB or SQLite backend, coin selection, key management, transaction creation, external signer hooks.
g. GUI (Optional)
- src/qt: Qt-based GUI front-end rendering wallet and node status, communicates with core via interfaces (onside or via RPC).
h. Libraries & Dependencies
- secp256k1 (elliptic-curve crypto), univalue (JSON), libevent (async I/O), ZeroMQ (notifications), LevelDB, BerkeleyDB.

##### Relationships & Data Flows
- P2P networking → Node Kernel → Consensus → Storage
- Consensus notifications → Wallet / GUI via interfaces or RPC callbacks
- RPC/CLI → Node Kernel (query chainstate, send transactions)
- Wallet → Consensus & Mempool (broadcasting TX) → P2P
- GUI → Wallet & Node Kernel (through interfaces layer or RPC)
- External libraries (crypto, DB) support core components

##### Architectural Patterns & Principles
- Layered architecture:
- Transport (P2P, IPC)
- Core logic (kernel, consensus, validation)
- Persistence (blockstore, UTXO, wallet DB)
- Interface/API (RPC, CLI, GUI)
- Modular C++ libraries (crypto/, primitives/, script/, consensus/)
- Interface segregation: src/interfaces defines abstract handlers for UI, wallet, mining, etc.
- Plugin-style external signer, ZeroMQ notifications.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External World
    Internet((Internet Peers)):::external
    Signer((External Signer)):::external

    %% Networking Layer
    subgraph "Networking Layer" 
        direction TB
        NetCore["net.cpp"]:::network
        NetProc["net_processing.cpp"]:::network
        AddrMan["addrman.cpp/.h"]:::network
        BanMan["banman.cpp/.h"]:::network
        NetBase["netbase.cpp/.h"]:::network
    end

    %% Core Node Kernel
    subgraph "Node Core" 
        direction TB
        KernelDir["src/kernel/"]:::core
        NodeDir["src/node/"]:::core
        InterfacesDir["src/interfaces/"]:::core
    end

    %% Consensus & Validation
    subgraph "Consensus & Validation" 
        direction TB
        ConsensDir["src/consensus/"]:::consensus
        Validation["validation.cpp/.h"]:::consensus
        ValInt["validationinterface.cpp/.h"]:::consensus
        CsMain["cs_main.cpp/.h"]:::consensus
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        TxDB["txdb.cpp/.h"]:::storage
        DBWrap["dbwrapper.cpp/.h"]:::storage
        FlatFile["flatfile.cpp/.h"]:::storage
    end

    %% Wallet Subsystem
    subgraph "Wallet Subsystem"
        direction TB
        WalletDir["src/wallet/"]:::wallet
        WDB["wallet/db.cpp/.h"]:::wallet
        SQLite["wallet/sqlite.cpp/.h"]:::wallet
    end

    %% Interfaces Layer
    subgraph "Interface Layer"
        direction TB
        subgraph "RPC & CLI"
            direction TB
            RPCDir["src/rpc/"]:::interface
            Bitcoind["bitcoind.cpp"]:::interface
            CLI["bitcoin-cli.cpp"]:::interface
        end
        subgraph "Qt GUI (Optional)"
            direction TB
            QtDir["src/qt/"]:::interface
            QtMain["main.cpp"]:::interface
            QtGUI["bitcoingui.cpp/.h"]:::interface
        end
    end

    %% Third-Party Libraries
    subgraph "Third-Party Libs"
        direction TB
        SecpDir["src/secp256k1/"]:::lib
        CryptoDir["src/crypto/"]:::lib
        UniDir["src/univalue/"]:::lib
        LevelDir["src/leveldb/"]:::lib
        ZmqDir["src/zmq/"]:::lib
    end

    %% Data Flows
    Internet -->|P2P Messages| NetCore
    Signer -->|Sign TX| WalletDir

    NetCore -->|Handshake & Messages| KernelDir
    KernelDir -->|Invoke Validation| ConsensDir
    ConsensDir -->|Validate Blocks| TxDB
    ConsensDir -->|Update UTXO| DBWrap
    TxDB -->|Store Blocks| FlatFile

    KernelDir -->|Serve Requests| RPCDir
    RPCDir -->|RPC Calls| KernelDir
    CLI -->|CLI Commands| RPCDir

    QtDir -->|UI Calls| KernelDir
    QtDir -->|Wallet UI| WalletDir

    WalletDir -->|Create TX| ConsensDir
    WalletDir -->|Broadcast TX| NetCore

    %% Library Dependencies
    SecpDir -->|Crypto| ConsensDir
    CryptoDir -->|Crypto| WalletDir
    UniDir -->|JSON| RPCDir
    LevelDir -->|UTXO Store| ConsensDir
    ZmqDir -->|Notifications| RPCDir

    %% Click Events
    click NetCore "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/net.cpp"
    click NetProc "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/net_processing.cpp"
    click AddrMan "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/addrman.cpp"
    click BanMan "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/banman.cpp"
    click NetBase "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/netbase.cpp"
    click ConsensDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/consensus/"
    click Validation "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/validation.cpp"
    click ValInt "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/validationinterface.cpp"
    click CsMain "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/kernel/cs_main.cpp"
    click TxDB "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/txdb.cpp"
    click DBWrap "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/dbwrapper.cpp"
    click FlatFile "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/flatfile.cpp"
    click KernelDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/kernel/"
    click NodeDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/node/"
    click InterfacesDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/interfaces/"
    click RPCDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/rpc/"
    click Bitcoind "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/bitcoind.cpp"
    click CLI "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/bitcoin-cli.cpp"
    click WalletDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/wallet/"
    click WDB "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/wallet/db.cpp"
    click SQLite "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/wallet/sqlite.cpp"
    click QtDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/qt/"
    click QtMain "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/qt/main.cpp"
    click QtGUI "https://github.com/starkware-bitcoin/bitcoin/blob/28.x-knots/src/qt/bitcoingui.cpp"
    click SecpDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/secp256k1/"
    click CryptoDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/crypto/"
    click UniDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/univalue/"
    click LevelDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/leveldb/"
    click ZmqDir "https://github.com/starkware-bitcoin/bitcoin/tree/28.x-knots/src/zmq/"

    %% Styles
    classDef external fill:#f2f2f2,stroke:#999,stroke-width:1px;
    classDef network fill:#cfe2f3,stroke:#0366d6,stroke-width:1px;
    classDef core fill:#d9ead3,stroke:#38761d,stroke-width:1px;
    classDef consensus fill:#d9ead3,stroke:#6aa84f,stroke-width:1px;
    classDef storage fill:#d9ead3,stroke:#6aa84f,stroke-width:1px;
    classDef wallet fill:#fce5cd,stroke:#e69138,stroke-width:1px;
    classDef interface fill:#ead1dc,stroke:#92278f,stroke-width:1px;
    classDef lib fill:#eeeeee,stroke:#666,stroke-width:1px;
```
