Bitcoin Core — Administrator & Engineering Guide

Exhaustive operator and developer reference for Bitcoin Core at commit 1aef4d5. Covers architecture, deployment, configuration, security hardening, operations, internals, and extension points. If you run a node in production, operate mining infrastructure, embed Bitcoin Core into services, or contribute to the codebase — this is your manual.

Table of Contents

• 1. Executive Summary
• 2. Architecture Overview
• 3. Component Inventory
• 4. System Requirements
• 5. Configuration Reference
• 6. Deployment
• 7. Operations
• 8. Security
• 9. Troubleshooting
• 10. Developer Internals
• 11. Quick Reference

1. Executive Summary

Bitcoin Core is the reference implementation of the Bitcoin protocol. It is a full-validating peer-to-peer node, consensus engine, descriptor-based wallet, JSON-RPC/REST API server, ZMQ event publisher, and optional Qt GUI — all in a single C++ codebase of approximately 2,918 source files and 14.8 million characters of code.

Key facts at this commit:

Note

This guide is derived from direct source-code analysis. Written from the code at the stated commit. Where the code is the only authority, we say so explicitly.

2. Architecture Overview

2.1 Process Model

Bitcoin Core supports two process architectures:

Monolithic (default): A single process (bitcoind or bitcoin-qt) runs the node, wallet, and RPC server in one address space.

Multiprocess (experimental): With ENABLE_IPC=ON, separate executables communicate via Cap'n Proto over Unix sockets:

bitcoin-node  ←──IPC──→  bitcoin-wallet
      ↑                        ↑
      └────────IPC─────────────┘
              ↕
         bitcoin-gui

The multiprocess architecture is defined in src/init/:

Each Init class implements interfaces::Init, which provides factory methods:

virtual std::unique_ptr<Node> makeNode();
virtual std::unique_ptr<Chain> makeChain();
virtual std::unique_ptr<Mining> makeMining();
virtual std::unique_ptr<WalletLoader> makeWalletLoader(Chain& chain);
virtual std::unique_ptr<Echo> makeEcho();
virtual std::unique_ptr<Rpc> makeRpc();
virtual Ipc* ipc();

2.2 Layered Architecture

┌─────────────────────────────────────────────────────┐
│                    User Interfaces                   │
│         Qt GUI  │  JSON-RPC  │  REST  │  ZMQ        │
├─────────────────────────────────────────────────────┤
│                  Interface Layer                     │
│   interfaces::Node  │  Chain  │  Mining  │  Wallet   │
├─────────────────────────────────────────────────────┤
│                Application Layer                     │
│  Wallet (src/wallet/)  │  Mempool  │  Fee Estimator  │
├─────────────────────────────────────────────────────┤
│               Validation / Consensus                 │
│  ChainstateManager  │  BlockManager  │  UTXO Cache   │
├─────────────────────────────────────────────────────┤
│                  P2P Network Layer                    │
│        CConnman  │  PeerManager  │  AddrMan          │
├─────────────────────────────────────────────────────┤
│                  Storage Layer                        │
│    LevelDB (block index)  │  Flat files (blocks)     │
├─────────────────────────────────────────────────────┤
│               Cryptographic Primitives               │
│   secp256k1  │  SHA-256  │  ctaes  │  minisketch     │
└─────────────────────────────────────────────────────┘

2.3 Data Flow

1. Block reception: P2P layer receives block → ChainstateManager validates against consensus rules → BlockManager writes to flat file + updates LevelDB index → UTXO set updated → wallet notified via CValidationInterface
2. Transaction submission: RPC/wallet creates tx → mempool validates (policy + consensus) → relayed to peers via P2P inventory messages
3. RPC request: HTTP server accepts connection → CRPCTable dispatches to registered RPCMethod handler → handler accesses node state via locks → JSON response returned

3. Component Inventory

3.1 Core Libraries

3.2 Node Components

3.3 Wallet

Important

Legacy BDB wallets are deprecated. New wallets use SQLite exclusively. Legacy wallets can be migrated via migratewallet RPC. The DEFAULT_WALLET_TX_VERSION follows CTransaction::CURRENT_VERSION.

3.4 GUI

3.5 Utility Binaries

3.6 Contrib Tools

4. System Requirements

4.1 Hardware

4.2 Software

4.3 Build Presets

From CMakePresets.json:

5. Configuration Reference

5.1 Configuration Files

Bitcoin Core reads configuration from these sources (highest priority first):

1. Command-line arguments (-option=value)
2. settings.json (data directory, written by RPC setban, wallet settings)
3. bitcoin.conf (data directory, user-edited)

The config file location defaults to:

Section syntax for network-specific overrides:

# Global
server=1

[test]
rpcport=18332

[signet]
rpcport=38332

[regtest]
rpcport=18443

[testnet4]
rpcport=48332

Valid section names: main, test, signet, regtest, testnet4.

Negation syntax: Any boolean option can be negated with no prefix: -nowalletbroadcast, -nolisten. Double negation (-nofoo=0) is supported but discouraged.

5.2 Network Options

5.3 RPC/REST Options

Warning

Never expose -rpcbind to untrusted networks without proper -rpcallowip restrictions and strong -rpcauth credentials. The RPC interface provides full node control including wallet access.

5.4 Wallet Options

5.5 Block Storage & Pruning

5.6 Mempool Options

5.7 Mining Options

5.8 ZMQ Options

5.9 Debug & Logging

5.10 Consensus/Network Selection

6. Deployment

6.1 Building from Source

# Clone
git clone https://github.com/bitcoin/bitcoin.git
cd bitcoin

# Configure
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Optional features
cmake -B build \
  -DBUILD_GUI=ON \
  -DWITH_ZMQ=ON \
  -DENABLE_IPC=OFF \
  -DWITH_SQLITE=ON

# Build
cmake --build build -j$(nproc)

# Install
cmake --install build

Windows (MSVC):

cmake --preset vs2026
cmake --build build --config Release

vcpkg dependencies (from vcpkg.json):

• boost-multi-index
• libevent
• Optional features: qt, tests, wallet, zeromq, qrencode

6.2 Reproducible Builds

Bitcoin Core uses Guix for deterministic, reproducible builds:

contrib/guix/guix-build
contrib/guix/guix-attest
contrib/guix/guix-verify

6.3 Init System Integration

Example systemd unit (doc/init.md conventions):

[Unit]
Description=Bitcoin Core Daemon
After=network-online.target
Wants=network-online.target

[Service]
Type=forking
ExecStart=/usr/local/bin/bitcoind -daemon -conf=/etc/bitcoin/bitcoin.conf -datadir=/var/lib/bitcoind
ExecStop=/usr/local/bin/bitcoin-cli stop
User=bitcoin
Group=bitcoin
RuntimeDirectory=bitcoind
StateDirectory=bitcoind

# Hardening
PrivateTmp=true
ProtectSystem=full
NoNewPrivileges=true
MemoryDenyWriteExecute=true

[Install]
WantedBy=multi-user.target

6.4 Docker

Note

Bitcoin Core does not ship an official Docker image. When containerizing, ensure the data directory is on a persistent volume and the container runs as a non-root user.

6.5 Tor Hidden Service

# bitcoin.conf
proxy=127.0.0.1:9050
listen=1
bind=127.0.0.1
onlynet=onion
torcontrol=127.0.0.1:9051
torpassword=<your_hashed_password>

Bitcoin Core will automatically create a v3 Tor hidden service when torcontrol is configured.

6.6 I2P

# bitcoin.conf
i2psam=127.0.0.1:7656

Requires a running I2P SAM bridge. Bitcoin Core creates a persistent I2P destination stored in <datadir>/i2p_private_key.

6.7 CJDNS

# bitcoin.conf
cjdnsreachable=1

Requires the host to have a CJDNS interface configured. Peers with fc00::/8 addresses will be treated as CJDNS.

7. Operations

7.1 Initial Block Download (IBD)

IBD downloads and validates the entire blockchain history. Optimization strategies:

Tip

Setting -dbcache to half your available RAM during IBD can reduce sync time from days to hours. Reduce it after sync completes.

7.2 Pruning

Automatic pruning: -prune=<MiB> (minimum 550 MiB). Old block files are deleted when total exceeds the target.

Manual pruning: -prune=1. Use pruneblockchain <height> RPC to prune on demand.

Caution

Pruned nodes cannot serve historical blocks to peers, cannot run -txindex, and cannot rescan the wallet for transactions before the pruned height. Backup wallet files before enabling pruning.

7.3 UTXO Snapshots (AssumeUTXO)

# On a fully-synced node: create snapshot
bitcoin-cli dumptxoutset /path/to/utxo.dat

# On a new node: load snapshot to start immediately
bitcoin-cli loadtxoutset /path/to/utxo.dat

The node begins operating from the snapshot height immediately while validating the full history in the background. Once background validation completes, the snapshot chainstate is promoted.

7.4 Backup & Recovery

Critical files to back up:

Wallet backup:

bitcoin-cli backupwallet /path/to/backup.dat

Warning

Descriptor wallets derive keys from descriptors, so a backup taken at wallet creation time covers all future addresses. However, labels and metadata added later require fresh backups.

7.5 Monitoring

RPC health checks:

# Node status
bitcoin-cli getblockchaininfo
bitcoin-cli getnetworkinfo
bitcoin-cli getpeerinfo

# Mempool
bitcoin-cli getmempoolinfo

# Uptime and RPC info
bitcoin-cli uptime
bitcoin-cli getrpcinfo

ZMQ streaming for real-time monitoring:

# Subscribe to new blocks
zmqsub tcp://127.0.0.1:28332 hashblock

# Subscribe to new transactions
zmqsub tcp://127.0.0.1:28332 hashtx

Log categories for targeted debug output:

net, tor, mempool, http, bench, zmq, walletdb, rpc, estimatefee,
addrman, selectcoins, reindex, cmpctblock, rand, prune, proxy,
mempoolrej, libevent, coindb, qt, leveldb, validation, i2p, ipc,
lock, blockstorage, txreconciliation, scan, txpackages

7.6 Performance Tuning

7.7 RPC Interface

Authentication methods (choose one):

1. Cookie auth (default): Auto-generated .cookie file in data directory
2. rpcauth: Generate with share/rpcauth/rpcauth.py:

python3 share/rpcauth/rpcauth.py myuser
# Output: rpcauth=myuser:salt$hash
# Add to bitcoin.conf

RPC command categories (from src/rpc/):

7.8 REST Interface

When -rest=1:

Formats: .json, .bin, .hex

8. Security

8.1 Threat Model

Bitcoin Core operates in an adversarial environment where peers may be malicious. The security architecture defends against:

• Consensus attacks: Every block and transaction is fully validated against consensus rules
• Eclipse attacks: Diversified peer selection via AddrMan bucketing, AS-map support (-asmap)
• Sybil attacks: Connection limits, peer scoring, eviction logic
• DoS attacks: Resource limits (mempool size, orphan limits, ban scoring), rate limiting
• Timing attacks: Constant-time cryptographic operations (ctaes, secp256k1)

8.2 Cryptographic Security

8.3 Wallet Security

• Encryption: Wallet database encrypted with AES-256-CBC; master key derived from passphrase via key stretching
• Key derivation: BIP 32/44/49/84/86 hierarchical deterministic derivation from descriptors
• Address types: Legacy (P2PKH), P2SH-SegWit (P2SH-P2WPKH), Native SegWit (P2WPKH), Taproot (P2TR)
• Signing: Supports PSBT (BIP 174/370) for offline/multisig signing workflows
• Coin control: CCoinControl allows manual UTXO selection with input weight, sequence, and script overrides

8.4 Network Security

• RPC: Bind to localhost by default; cookie auth or hashed password auth
• P2P: No authentication (public network); peer reputation via misbehavior scoring
• Block storage XOR: Blocks are XOR-obfuscated on disk (-blocksxor=true default) to prevent antivirus false positives; this is NOT encryption
• Ban list: banlist.json persists bans across restarts

Caution

The XOR obfuscation of block files (-blocksxor) is not a security feature. It exists solely to prevent antivirus software from flagging block data that coincidentally matches malware signatures. Do not rely on it for data confidentiality.

8.5 Hardening Checklist

• [ ] Run as dedicated non-root user
• [ ] Use -rpcauth instead of -rpcuser/-rpcpassword
• [ ] Keep -rpcbind=127.0.0.1 unless remote access is required
• [ ] Set -rpcallowip to restrict RPC access by subnet
• [ ] Use Tor/I2P to hide node IP from peers
• [ ] Enable -asmap for eclipse attack resistance
• [ ] Use systemd hardening directives (PrivateTmp, ProtectSystem, NoNewPrivileges, MemoryDenyWriteExecute)
• [ ] Encrypt wallet with encryptwallet RPC
• [ ] Back up wallet before any upgrade or migration
• [ ] Monitor debug.log for WARNING and ERROR entries

9. Troubleshooting

9.1 Startup Issues

9.2 Sync Issues

9.3 Wallet Issues

9.4 Network Issues

9.5 RPC Issues

10. Developer Internals

10.1 Repository Structure

bitcoin/
├── cmake/              CMake modules and scripts
│   ├── module/         Feature detection modules
│   └── script/         Build helper scripts
├── contrib/            Tools, scripts, packaging
│   ├── completions/    Shell completions (bash, fish)
│   ├── devtools/       Developer tools (clang-tidy, coverage)
│   ├── guix/           Deterministic build infrastructure
│   ├── linearize/      Blockchain linearization
│   ├── seeds/          Seed node list generation
│   ├── signet/         Signet tools
│   ├── tracing/        USDT/eBPF tracing scripts
│   └── verify-binaries/ Release verification
├── doc/                Documentation
│   ├── design/         Internal design documents
│   ├── man/            Man pages
│   ├── policy/         Transaction relay policy docs
│   └── release-notes/  Per-version release notes
├── share/              Shared resources
│   ├── examples/       Example bitcoin.conf
│   ├── qt/             Qt resources
│   └── rpcauth/        RPC authentication helper
├── src/                All C++ source code
│   ├── bench/          Benchmarks
│   ├── common/         Shared utilities (args, settings)
│   ├── compat/         Platform compatibility
│   ├── consensus/      Consensus-critical code
│   ├── crypto/         Cryptographic primitives
│   ├── index/          Optional indexes
│   ├── init/           Process initialization (per-binary)
│   ├── interfaces/     Abstract interfaces (IPC boundary)
│   ├── ipc/            IPC infrastructure (Cap'n Proto)
│   ├── kernel/         Consensus kernel library
│   ├── logging/        Logging infrastructure
│   ├── node/           Node-specific logic
│   ├── policy/         Transaction relay policy
│   ├── primitives/     Core data types (block, tx)
│   ├── qt/             Qt GUI
│   ├── rpc/            JSON-RPC handlers
│   ├── script/         Script engine, descriptors
│   ├── secp256k1/      Embedded libsecp256k1
│   ├── support/        Allocators, cleanse
│   ├── test/           Unit tests
│   ├── util/           General utilities
│   ├── wallet/         Wallet implementation
│   └── zmq/            ZMQ notification publisher
└── test/
    ├── functional/     Python functional tests (268 files)
    ├── fuzz/           Fuzz test corpus/seeds
    └── lint/           Linting tools (Rust)

10.2 Module Reference

Consensus (src/consensus/)

The consensus module defines Bitcoin's protocol constants:

static constexpr CAmount COIN = 100'000'000;           // satoshis per BTC
static constexpr CAmount MAX_MONEY = 21'000'000 * COIN; // 2.1 quadrillion sats
static const unsigned int MAX_BLOCK_WEIGHT = 4'000'000;  // 4 MW (BIP 141)
static const unsigned int MAX_BLOCK_SERIALIZED_SIZE = 4'000'000;
static const int64_t MAX_BLOCK_SIGOPS_COST = 80'000;
static const int COINBASE_MATURITY = 100;
static const int WITNESS_SCALE_FACTOR = 4;
static constexpr int64_t MAX_TIMEWARP = 600;            // BIP 94

Important

MAX_MONEY is a sanity check, not the actual supply. The actual circulating supply is less than 21M BTC due to provably lost coins and rounding in subsidy halvings.

Block Storage (src/node/blockstorage.cpp)

Blocks are stored in flat files (blk?????.dat) with undo data in rev?????.dat. The block index lives in LevelDB with these key prefixes:

Block comparison for chain selection uses CBlockIndexWorkComparator: most total work first, then earliest sequence ID.

Mempool Policy (src/policy/)

The policy layer enforces standardness rules stricter than consensus:

• Fee rates: CFeeRate tracks fees per virtual byte (sat/vB), internally stored as FeePerVSize
• Dust: Outputs below the dust threshold (based on -dustrelayfee) are non-standard
• Ephemeral dust (new): Zero-fee transactions may create dust outputs, but a child transaction must spend ALL dust outputs from its parent. Enforced by PreCheckEphemeralTx() and CheckEphemeralSpends()
• RBF: BIP 125 opt-in replace-by-fee with incremental fee requirements
• Package relay: CPFP and package RBF for mempool submissions (submitpackage RPC)

Serialization

Bitcoin Core uses a custom serialization framework (src/serialize.h) with:

• Network-specific magic bytes for message framing
• Hash-verified serialization (HashedSourceWriter/HashVerifier) for data integrity
• Atomic file writes via temp file + rename pattern (SerializeFileDB)
• Version-aware deserialization for backward compatibility

Address Manager (src/addrdb.*, src/addrman.*)

• Peers stored in peers.dat with network-magic-prefixed serialization and checksum verification
• AddrMan uses bucketed storage with configurable consistency checks (-checkaddrman)
• anchors.dat stores block-relay-only peer addresses on shutdown for eclipse attack resistance
• Ban list stored in banlist.json (JSON format, migrated from banlist.dat in v22)

10.3 Code Patterns

Locking

Bitcoin Core uses annotated mutexes with Clang thread-safety analysis:

LOCK(cs_main);                            // Acquire lock
LOCK2(cs_main, cs_wallet);               // Acquire two locks
AssertLockHeld(cs_main);                  // Assert lock is held
AssertLockNotHeld(cs_main);              // Assert lock is NOT held (perf)
EXCLUSIVE_LOCKS_REQUIRED(::cs_main);     // Function annotation
WITH_LOCK(cs_main, return active_chain.Height());  // Inline lock

Error Handling

// Result type for fallible operations
util::Result<std::unique_ptr<AddrMan>> LoadAddrman(...);

// Bilingual strings for user-facing errors
return util::Error{strprintf(_("message %s"), arg)};

// RPC errors
throw JSONRPCError(RPC_INVALID_PARAMETER, "message");

RPC Registration

Commands are registered as RPCMethod objects:

static RPCMethod getblockcount()
{
    return RPCMethod{
        "getblockcount",
        "Returns the height of the most-work fully-validated chain.\n",
        {},                              // Parameters
        RPCResult{...},                  // Result type
        RPCExamples{...},                // CLI/RPC examples
        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue {
            // Handler body
        },
    };
}

Interface Pattern

The interfaces:: namespace defines abstract boundaries between components:

class Init {
    virtual std::unique_ptr<Node> makeNode();
    virtual std::unique_ptr<Chain> makeChain();
    virtual std::unique_ptr<Mining> makeMining();
    virtual std::unique_ptr<WalletLoader> makeWalletLoader(Chain& chain);
    virtual std::unique_ptr<Echo> makeEcho();
    virtual std::unique_ptr<Rpc> makeRpc();
    virtual Ipc* ipc();
};

This enables the multiprocess architecture: each binary implements the interfaces it provides and consumes the rest via IPC.

10.4 Testing Strategy

Running tests:

# Unit tests
cmake --build build --target test_bitcoin && ./build/src/test/test_bitcoin

# Functional tests
python3 test/functional/test_runner.py

# Specific functional test
python3 test/functional/wallet_basic.py

# Fuzz tests (requires libfuzzer preset)
cmake --preset libfuzzer
cmake --build build_fuzz
FUZZ=process_message ./build_fuzz/src/test/fuzz/fuzz

Functional test framework (test/functional/test_framework/):

• BitcoinTestFramework: Base class for all functional tests
• Manages multiple bitcoind nodes in regtest mode
• Provides helpers for mining, wallet operations, P2P message construction
• Supports mock time, custom network topologies, crash recovery testing

10.5 Contributing

Code standards:

• C++20 with -Wall -Wextra equivalent warnings
• Custom clang-tidy checks (contrib/devtools/bitcoin-tidy/): nontrivial thread-local validation
• IWYU (Include What You Use) enforcement
• Python functional tests follow PEP 8
• All changes require review before merge

Deterministic testing tools:

• contrib/devtools/deterministic-unittest-coverage/ (Rust): Ensures deterministic unit test execution for reproducible coverage
• contrib/devtools/deterministic-fuzz-coverage/ (Rust): Same for fuzz corpus

Static analysis annotations:

• CHECK_NONFATAL(): Assertion that throws instead of aborting (for recoverable invariant violations)
• Assume(): Weaker assertion for optimizer hints (debug-only check)
• NONFATAL_UNREACHABLE(): Marks unreachable code paths

11. Quick Reference

11.1 Port Numbers

11.2 Data Directory Layout

<datadir>/
├── bitcoin.conf           Configuration file
├── settings.json          Runtime settings
├── debug.log              Log file
├── .cookie                RPC cookie auth
├── peers.dat              Known peer addresses
├── banlist.json           Banned peers
├── anchors.dat            Block-relay-only anchors
├── fee_estimates.dat      Fee estimator state
├── mempool.dat            Mempool persistence
├── blocks/
│   ├── blk?????.dat       Raw block data
│   ├── rev?????.dat       Undo data
│   └── index/             LevelDB block index
├── chainstate/            LevelDB UTXO set
├── indexes/
│   ├── txindex/           Transaction index (if -txindex)
│   ├── blockfilter/       Block filter index
│   └── coinstatsindex/    Coin stats index
└── wallets/
    └── <wallet_name>/     SQLite wallet files

11.3 Key RPC Quick Reference

# Node info
bitcoin-cli getblockchaininfo
bitcoin-cli getnetworkinfo
bitcoin-cli getpeerinfo

# Block operations
bitcoin-cli getblock $(bitcoin-cli getbestblockhash) 2
bitcoin-cli getblockcount

# Mempool
bitcoin-cli getmempoolinfo
bitcoin-cli getrawmempool true

# Wallet
bitcoin-cli createwallet "mywallet"
bitcoin-cli -rpcwallet=mywallet getnewaddress "" bech32m
bitcoin-cli -rpcwallet=mywallet getbalance
bitcoin-cli -rpcwallet=mywallet sendtoaddress <addr> <amount>

# Transaction
bitcoin-cli getrawtransaction <txid> true
bitcoin-cli testmempoolaccept '["<hex>"]'

# Maintenance
bitcoin-cli stop
bitcoin-cli logging '["net","mempool"]'

11.4 Consensus Constants Quick Reference

Note

Negative knowledge — what does NOT exist in the code at this commit:

• No built-in mining pool or stratum server implementation
• No built-in block explorer or web interface
• No official Docker image or Kubernetes manifests
• No gRPC interface (only JSON-RPC, REST, ZMQ)
• No native TLS/SSL for RPC (use a reverse proxy for remote access)
• No automatic wallet backup scheduling
• No built-in transaction fee prediction API beyond fee estimation RPC
• No Lightning Network or Layer 2 protocol support (separate projects)
• No GUI-only configuration options — all GUI settings map to CLI flags
• No Prometheus/metrics endpoint (monitor via RPC polling or ZMQ)