B++ Logo
Feedback

Bitcoin Core Internals

Bitcoin Core is the reference implementation of Bitcoin. Understanding its internal architecture helps developers contribute to Bitcoin Core, build compatible software, and debug issues.

Architecture Overview

Core Components

Bitcoin Core:
├── Consensus Engine
│   ├── Validation
│   ├── Block processing
│   └── Chain state
├── Network Layer
│   ├── P2P protocol
│   ├── Peer management
│   └── Message handling
├── Wallet System
│   ├── Key management
│   ├── Transaction creation
│   └── UTXO tracking
└── RPC Interface
    ├── JSON-RPC API
    ├── REST API
    ├── Command handling
    └── Response formatting

Main Runtime Components

At runtime, the node coordinates several major components (names may differ across versions):

ComponentRole
ChainstateManagerManages one or two chainstates (e.g. normal IBD and optional AssumeUTXO snapshot). Interface for activating and validating the best chain.
BlockManagerKeeps the tree of blocks on disk (via LevelDB index), resolves the most-work tip, and manages blk*.dat and rev*.dat files.
CTxMemPoolValidates and stores unconfirmed transactions that may be included in the next block. Applies fee-based prioritization and eviction.
PeerManagerHandles P2P message processing, block and transaction fetch, and peer behavior (disconnect, misbehaviour).
CConnmanManages network connections: opening sockets, sending/receiving bytes, and coordinating net threads.
AddrManStores and serves peers’ network addresses (from DNS seeds, peers, and config).
Interfaces::ChainAbstraction used by wallet and other clients to read chain state, submit transactions, get fee estimates, and receive notifications. Enables multiprocess (node, wallet, GUI in separate processes).

Key Subsystems

1. Consensus Engine

Validates transactions and blocks:

Responsibilities:
- Verify transaction validity
- Check block validity
- Maintain chain state
- Enforce consensus rules

2. UTXO Set

Tracks unspent transaction outputs:

Structure:
- Database: LevelDB
- Index: Transaction outputs
- Updates: On each block
- Size: ~5-10GB

3. Mempool

Manages unconfirmed transactions:

Features:
- Transaction storage
- Fee-based prioritization
- Eviction policies
- Size limits

4. Block Storage

Stores blockchain data:

Formats:
- blk*.dat: Raw block data
- rev*.dat: Undo data
- Chainstate: UTXO set

Threading Model

Bitcoin Core is multi-threaded. The main bitcoind thread starts and shuts down the process and spawns worker threads. Key groups:

Main and init

  • Main (bitcoind): Startup, shutdown, and spawning other threads.
  • Init/load (b-initload): Block import, reindex, loading mempool, and starting optional indexers (without blocking node startup).

Validation and RPC

  • Script check (b-scriptch.x): Parallel threads that verify Script in block transactions.
  • HTTP (b-http, b-httpworker.x): Listens for and serves JSON-RPC and REST requests.
  • Indexers (b-txindex, etc.): One thread per optional index (txindex, blockfilterindex, coinstatsindex) for background syncing.
  • Scheduler (b-scheduler): Background tasks (e.g. dumping wallet, addrman, validation callbacks).

Network

  • Message handler (b-msghand): Most P2P and validation logic (sending/receiving messages, block/tx handling).
  • Socket handler (b-net): Sends and receives raw bytes on the P2P port (default 8333).
  • Connections (b-opencon, b-addcon): Opens new outbound connections and connections to added nodes.
  • DNS seed (b-dnsseed): Fetches peer addresses from DNS seeds.
  • I2P (b-i2paccept): Accepts incoming I2P connections when I2P is enabled.

Understanding these threads helps when debugging, profiling, or contributing to Bitcoin Core. The developer notes and Bitcoin Core Academy describe them in more detail.

Database Systems

LevelDB

Used for:

  • Chainstate (chainstate/): UTXO set and related metadata.
  • Block index (blocks/index/): Block metadata and header tree (most-work chain, orphans). Not affected by -blocksdir.
  • Wallets (wallets/): Each wallet is a SQLite DB; the chainstate is in LevelDB, wallet logic uses both.
  • Optional indexes (in indexes/, created only if enabled):
    • txindex (-txindex=1): Look up transactions by txid.
    • blockfilterindex=basic: BIP 158 compact block filters for light clients.
    • coinstatsindex (-coinstatsindex=1): Aggregated coin statistics used by gettxoutsetinfo and similar.

Flat Files

Used for:

  • Blocks (blocks/blk*.dat): Raw block data in network format (128 MiB per file).
  • Undo (blocks/rev*.dat): Block undo data for reorganisations.

Data Directory Layout

The data directory (default: ~/.bitcoin on Linux, ~/Library/Application Support/Bitcoin on macOS, %LOCALAPPDATA%\Bitcoin on Windows) is chain-specific. For testnet, signet, or regtest, subdirs testnet3/, signet/, or regtest/ are used.

Besides blocks/, chainstate/, and indexes/, important files include:

  • peers.dat: Peer address database.
  • mempool.dat: Mempool dump (optional, on shutdown).
  • banlist.json: Banned peers.
  • debug.log: Log output (configurable).
  • bitcoin.conf: User configuration (must be created manually).

See the Bitcoin Core files documentation for the full layout, wallet structure, and installed binaries.

Binaries and Libraries

Bitcoin Core builds several executables:

BinaryPurpose
bitcoindHeadless node and built-in wallet.
bitcoin-qtNode and wallet with GUI.
bitcoin-cliRPC client (calls bitcoind or bitcoin-qt).
bitcoin-walletStandalone wallet tool (create, upgrade, migrate descriptors).
bitcoin-txCreate and modify raw transactions.
bitcoin-utilUtilities (e.g. chainstate, hashing).

The consensus and validation logic can be built as libbitcoinkernel (shared library), so other software can link against it without running a full node process. The multiprocess design allows bitcoin-node, bitcoin-wallet, and bitcoin-gui to run in separate processes communicating over IPC, improving isolation and enabling use cases like running the GUI without a local node.

Code Structure

Key Directories

src/
├── consensus/     - Consensus rules and params
├── kernel/        - Libbitcoinkernel (consensus + validation core)
├── node/          - Node logic (chain, mempool, init)
├── net_processing/- P2P message handling and peer logic
├── net/           - Network connections and transport
├── wallet/        - Wallet logic
├── rpc/           - JSON-RPC and REST
├── script/        - Script execution
├── validation/    - Block and transaction validation
└── interfaces/    - Abstract interfaces (Chain, Node, Wallet) for multiprocess and testing

The layout evolves; see the repository and Bitcoin Core Academy – Source organization for up-to-date structure.

Resources