# bitcoin-core/gui architecture

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

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

## Overview

##### Project Type & Purpose
- Full-stack, peer-to-peer cryptocurrency node with multiple interfaces (daemon, CLI, GUI, RPC, REST, ZMQ) plus wallet and test harnesses.
- Core responsibilities: connect to P2P network, validate/relay blocks & transactions, maintain chainstate & mempool, provide mining support, wallet management, and expose APIs.

##### Main Architectural Layers & Components
A. Persisted Storage
– Block & undo files on disk (flatfile.cpp)
– Chainstate DB (LevelDB under src/leveldb)
– Wallet DB (BerkeleyDB or SQLite under src/wallet)
B. Core Kernel & Consensus
– Consensus rules & validation (src/consensus/, src/validation.cpp)
– Chainstate manager (src/kernel/)
– Mempool & policy (src/mempool*, src/policy/)
– Script engine & interpreter (src/script/)
– Cryptography & hashing (src/crypto/, secp256k1/, minisketch/)
C. Networking & IPC
– P2P networking stack (src/net*, src/connman.cpp)
– I2P integration (src/i2p/)
– Tor control (src/torcontrol.cpp)
– IPC (libmultiprocess under src/ipc/)
– ZMQ publish/subscribe (src/zmq/)
D. Service Interfaces
– RPC server (HTTP+JSON-RPC in src/rpc/)
– REST interface (src/httpserver.cpp + src/rest.cpp)
– CLI tools: bitcoin-cli, bitcoin-tx, bitcoin-wallet (src/*.cpp)
– GUI front-end (Qt) (src/qt/)
E. Wallet & External Signers
– Wallet logic & coin selection (src/wallet/)
– PSBT & external signer support (src/external_signer.cpp)

##### Interactions & Data Flows
1. P2P messages arrive → Net message parser (src/net.cpp) → Peer manager (connman)
2. New blocks/tx dispatched to validation module → consensus rules → chainstate & mempool update
3. Persistence layer writes block files & LevelDB chainstate
4. On chain updates, notification interfaces fire (internal pub/sub via libmultiprocess or ZMQ)
5. RPC/REST endpoints call into the same node interfaces → return JSON results
6. GUI (bitcoin-qt) embeds node or connects via IPC/RPC to daemon
7. CLI tools invoke RPC over HTTP or via IPC socket

##### Architectural Patterns & Principles
- Layered architecture: storage → core logic → networking/IPC → service interfaces → client UIs
- Modular libraries: crypto, consensus, script, network, kernel, wallet, util
- Separation of concerns:
– Chainstate and validation insulated from networking
– Interface adapters (RPC/REST/ZMQ) sit atop node logic
– GUI isolated in Qt module, communicates via well-defined IPC or in-process calls
- Use of message-passing (libmultiprocess) for multiprocess isolation of GUI/node

##### Final Checklist
– Clear, unique labels on all major components
– Arrowed lines showing direction of message or data flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Entities"
        P2PPeers["P2P Peers"]:::external
        TorNet["Tor Network"]:::external
        I2PNet["I2P Network"]:::external
        Miners["Miners"]:::external
        ExtSign["External Signers"]:::external
    end

    subgraph "Networking & IPC"
        P2PStack["P2P Networking Stack"]:::network
        I2P["I2P Integration"]:::network
        TorC["Tor Control"]:::network
        IPC["IPC (libmultiprocess)"]:::network
        ZMQ["ZMQ Pub/Sub"]:::network
    end

    subgraph "Core Kernel & Consensus"
        Consensus["Consensus & Validation"]:::core
        ChainMgr["Chainstate Manager"]:::core
        Mempool["Mempool & Policy"]:::core
        Script["Script Engine & Interpreter"]:::core
        Crypto["Cryptography & Hashing"]:::core
    end

    subgraph "Persisted Storage"
        BlockFiles["Block & Undo Files"]:::storage
        ChainDB["Chainstate DB\n(LevelDB)"]:::storage
        WalletDB["Wallet DB\n(BerkeleyDB/SQLite)"]:::storage
    end

    subgraph "Wallet & External Signers"
        WalletLogic["Wallet Logic & Coin Selection"]:::core
        PSBT["External Signer & PSBT Support"]:::core
    end

    subgraph "Service Interfaces"
        RPC["RPC Server"]:::interface
        REST["REST Interface"]:::interface
        CLIInt["CLI Tools"]:::interface
        GUIiface["GUI Front-end API"]:::interface
    end

    subgraph "Clients"
        QT["bitcoin-qt"]:::client
        CLItool["bitcoin-cli/tx/wallet"]:::client
    end

    %% Flows
    P2PPeers --> P2PStack
    TorNet --> TorC
    I2PNet --> I2P
    ExtSign --> PSBT

    P2PStack --> Consensus
    Consensus --> ChainMgr
    Consensus --> Mempool
    Mempool --> ChainMgr
    Consensus --> Script
    Consensus --> Crypto

    ChainMgr --> BlockFiles
    ChainMgr --> ChainDB
    WalletLogic --> WalletDB

    ChainMgr --> ZMQ
    Mempool --> ZMQ
    ChainMgr --> IPC
    Consensus --> IPC

    RPC --> Consensus
    REST --> Consensus
    RPC --> ChainMgr
    REST --> ChainMgr

    RPC --> WalletLogic
    CLIInt --> RPC
    GUIiface --> RPC

    QT --> GUIiface
    CLItool --> CLIInt

    %% Click Events
    click P2PStack "https://github.com/bitcoin-core/gui/blob/master/src/net.cpp"
    click I2P "https://github.com/bitcoin-core/gui/blob/master/src/i2p.cpp"
    click TorC "https://github.com/bitcoin-core/gui/blob/master/src/torcontrol.cpp"
    click IPC "https://github.com/bitcoin-core/gui/tree/master/src/ipc/libmultiprocess/"
    click ZMQ "https://github.com/bitcoin-core/gui/tree/master/src/zmq/"
    click Consensus "https://github.com/bitcoin-core/gui/blob/master/src/validation.cpp"
    click ChainMgr "https://github.com/bitcoin-core/gui/blob/master/src/kernel/cs_main.cpp"
    click Mempool "https://github.com/bitcoin-core/gui/blob/master/src/kernel/mempool_entry.h"
    click Script "https://github.com/bitcoin-core/gui/tree/master/src/script/"
    click Crypto "https://github.com/bitcoin-core/gui/tree/master/src/crypto/"
    click BlockFiles "https://github.com/bitcoin-core/gui/blob/master/src/flatfile.cpp"
    click ChainDB "https://github.com/bitcoin-core/gui/tree/master/src/leveldb/"
    click WalletDB "https://github.com/bitcoin-core/gui/blob/master/src/wallet/db.cpp"
    click RPC "https://github.com/bitcoin-core/gui/tree/master/src/rpc/"
    click REST "https://github.com/bitcoin-core/gui/blob/master/src/httpserver.cpp"
    click CLItool "https://github.com/bitcoin-core/gui/blob/master/src/bitcoin-cli.cpp"
    click QT "https://github.com/bitcoin-core/gui/tree/master/src/qt/"
    click WalletLogic "https://github.com/bitcoin-core/gui/blob/master/src/wallet/coinselection.cpp"
    click PSBT "https://github.com/bitcoin-core/gui/blob/master/src/external_signer.cpp"

    %% Styles
    classDef storage fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef network fill:#90EE90,stroke:#333,stroke-width:1px
    classDef interface fill:#FFA500,stroke:#333,stroke-width:1px
    classDef client fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef external fill:#F08080,stroke:#333,stroke-width:1px
```
