Chapter 1: Architecture & Big Picture | The Blockchain Chief Bitcoin Book

What Is Bitcoin Core?

Bitcoin Core is the reference implementation of the Bitcoin protocol. It is a single C++ binary, bitcoind, that performs four distinct roles simultaneously:

Full Node: downloads, validates, and stores every block ever created.
Mempool: holds unconfirmed transactions waiting to be mined.
P2P Relay: connects to other nodes, shares blocks and transactions.
Wallet (optional) - manages keys, creates and signs transactions.

Understanding the architecture means understanding how these roles interact. The rest of this chapter builds that picture layer by layer.

The Four Layers

Bitcoin Core's code follows a layered design. Lower layers are more fundamental and change less frequently; higher layers build on them.

Layer 4: Applications Wallet, RPC, GUI, CLI

Layer 3: Network & Mempool P2P protocol, message handling, transaction pool

Layer 2: Chain State & Validation Block validation, UTXO database, chain index

Layer 1: Primitives & Consensus Data structures, script, cryptography, consensus rules

Layer 1: Primitives & Consensus

The foundation defines the data types and rules that every Bitcoin node must agree on:

primitives/ - CTransaction, CBlock, CTxIn, CTxOut
consensus/ - consensus parameters, block size limits, script flags
script/, the Bitcoin Script interpreter and signature checking
crypto/ - SHA-256, RIPEMD-160, ECDSA, secp256k1

Layer 2: Chain State & Validation

Manages the current state of the blockchain:

validation.cpp, the heart of block and transaction validation
coins.cpp, the UTXO set (CCoinsView hierarchy)
txdb.cpp, on-disk blockchain database (LevelDB)
chain.h, the in-memory block index tree (CBlockIndex)

Layer 3: Network & Mempool

Handles communication with the outside world:

net.cpp - manages TCP connections to peers
net_processing.cpp - interprets P2P protocol messages
txmempool.cpp, the unconfirmed transaction pool

Layer 4: Applications

User-facing functionality built on top of the core:

wallet/ - key storage, coin selection, transaction creation
rpc/, JSON-RPC API for external tools
qt/, graphical interface (Bitcoin-Qt)
init.cpp, application startup and shutdown

Core Components

At a high level, Bitcoin Core is made up of a handful of interacting components. Here is how they relate:

🌐

P2P Network

Manages connections to ~125 peers. Sends and receives blocks, transactions, and address info.

✅

Validation Engine

The gatekeeper. Every block and transaction must pass through validation.cpp before being accepted.

💾

Mempool

Holds valid unconfirmed transactions. Miners draw from it to build blocks. Tracks fees and dependencies.

🔗

Chainstate (UTXO DB)

The set of all unspent transaction outputs. This is what determines who owns what bitcoin right now.

👛

Wallet

Manages private keys and creates transactions. Optional, a node can run without a wallet.

🔌

RPC Interface

JSON-RPC API used by bitcoin-cli and external applications to query the node and submit transactions.

Data Flow

Understanding how data moves through the system is key to reading the code. There are two primary flows:

Transaction Flow

When a new transaction enters the system, whether from the local wallet or a remote peer:

EntryWallet (RPC) or P2P peer sends a transaction

↓

AcceptToMemoryPool()validation.cpp, verify scripts, check fees, look up UTXOs

↓

CTxMemPool::addUnchecked()txmempool.cpp, add to mempool, track dependencies

↓

Relay to Peersnet_processing.cpp, announce via INV messages

↓

Miner picks upBlock template creation pulls from mempool

↓

ConnectBlock()validation.cpp, apply block to UTXO set, confirm transaction

Block Flow

When a new block arrives from the network:

Network Receivenet.cpp, receive raw block bytes from a peer

↓

ProcessMessage(BLOCK)net_processing.cpp, deserialize and hand to validation

↓

ProcessNewBlock()validation.cpp, verify PoW, check header, store to disk

↓

ActivateBestChain()validation.cpp, determine if this extends the best chain

↓

ConnectBlock()validation.cpp, execute every tx, update UTXO set

↓

Update Chain Indexchain.h, update CBlockIndex tree

Design Principles

Consensus vs. Policy

This distinction is critical to understand:

💡 Key Concept

Consensus rules are rules that every node on the network must enforce identically. If a node breaks a consensus rule, its chain forks. These live in consensus/ and validation.cpp.

Policy rules are local decisions a node makes, for example, the minimum relay fee or whether to accept RBF transactions. Different nodes can have different policies without causing forks. These live in policy/.

Modularity & Interfaces

Components communicate through abstract interfaces (in interfaces/). This means:

The wallet is optional; bitcoind can run wallet-free.
The GUI is optional; the RPC/CLI interface is independent.
Subsystems can be tested in isolation.

Immutability Where It Matters

CTransaction is immutable after construction. To modify a transaction, you work with CMutableTransaction, then convert. This prevents accidental modification of transactions whose hash has already been computed.

Threading Model

Bitcoin Core is multi-threaded. The most important locks to know:

cs_main - protects chain state, block index, and the UTXO set. The "big lock."
cs_wallet - protects wallet data structures.
mempool.cs - protects the transaction pool.
cs_vNodes - protects the list of peer connections.

⚠️ Lock Ordering

Bitcoin Core enforces a strict lock ordering discipline. Acquiring cs_main while holding cs_wallet (or vice versa in the wrong order) will trigger an assertion in debug builds. This prevents deadlocks.

Source Tree Map

A quick reference for navigating the repository:

src/primitives/Transaction & block data structures

src/consensus/Consensus parameters & rules

src/script/Script interpreter & signing

src/crypto/Cryptographic algorithms

src/validation.cppBlock & transaction validation (6,400+ lines)

src/txmempool.cppUnconfirmed transaction pool

src/net.cppP2P connection management

src/net_processing.cppP2P message handling (6,000+ lines)

src/wallet/Wallet, coin selection, signing

src/rpc/JSON-RPC API handlers

src/init.cppApplication startup & shutdown