libbitcoinkernel
The most ambitious ongoing refactor in Bitcoin Core is the extraction of consensus-critical code into a standalone library called libbitcoinkernel. The goal: any project can link against this library and validate blocks identically to Bitcoin Core, without pulling in networking, wallet, or GUI code.
Why It Matters
Bitcoin's consensus rules are scattered across dozens of source files, interwoven with P2P networking, RPC handling, and wallet logic. This coupling creates several problems:
- Alternative implementations risk consensus bugs: reimplementing validation from scratch is dangerous; even subtle differences can cause chain splits.
- Review burden: changes to non-consensus code require careful review to ensure they don't accidentally change consensus behavior.
- Embedding is impossible: projects that want to validate Bitcoin data (sidechains, Layer 2 protocols, research tools) must link all of Bitcoin Core or reimplement validation.
The C API
libbitcoinkernel exposes a pure C API through kernel/bitcoinkernel.h, using opaque pointer types for safety and ABI stability:
What You Can Do
- Validate blocks: process a serialized block through the full consensus pipeline
- Verify scripts: run the script interpreter on individual transaction inputs
- Iterate the block index: walk the header tree, inspect heights, timestamps, and chain work
- Read block data from disk: load raw blocks and undo data by position
- Receive events: register callbacks for validation progress, errors, and fatal conditions
Design Principles
- No C++ in the API: pure C types ensure compatibility across languages and ABIs
- Opaque pointers: all types are forward-declared; internal layout is hidden from consumers
- Create/Destroy pattern: every object returned by
*_create()has a corresponding*_destroy() - No global state: all state flows through the explicit
btck_Context
As of 2025, libbitcoinkernel is functional but not yet included in official releases. The API is unversioned and subject to breaking changes. The long-term vision is a stable, versioned library that alternative node implementations and tools can depend on safely.
Multiprocess Architecture
Bitcoin Core is historically a single monolithic process: node, wallet, and GUI all run in the same address space. The multiprocess project splits these into separate OS processes communicating over IPC (inter-process communication).
The Interfaces Layer
Before multiprocess, an abstraction layer was built: the interfaces/ directory defines clean boundaries between subsystems:
interfaces::Node: the node's public API (start, stop, get block info, submit transactions)interfaces::Chain: wallet's view of the blockchain (check UTXOs, estimate fees, get block heights)interfaces::Wallet: wallet operations (create transactions, sign, list addresses)interfaces::Mining: mining interface (create block templates, submit solutions)
IPC via Cap'n Proto
The multiprocess framework uses Cap'n Proto for serialization and communication between processes. Each interface is described in a .capnp schema file, and the framework generates proxy objects that transparently forward method calls across process boundaries.
Benefits
- Security isolation: a vulnerability in the wallet code can't directly access consensus state
- Independent restarts: the GUI can crash without affecting the node
- Flexible deployment: run the node on one machine and the wallet on another
- Clean API boundaries: forces well-defined interfaces between subsystems
Peer Eviction Logic
Bitcoin Core limits the number of inbound connections (default: 125 total, with a portion reserved for inbound). When a new inbound peer connects and slots are full, the node must decide which existing peer to evict. The eviction algorithm aims to keep a diverse, useful set of peers while resisting eclipse attacks.
Protection Criteria
Before eviction, peers are protected in several rounds:
- 4 peers with lowest ping time: fast peers are valuable for block relay
- 4 peers that most recently sent us transactions: actively relaying peers
- 4 peers that most recently sent us blocks: important for staying in sync
- Up to 8 peers on privacy networks: Tor, I2P, and CJDNS peers are protected by ratio to preserve network diversity
- Half of remaining peers by longest connection time: long-lived connections are harder for an attacker to establish
Eviction Selection
After protection rounds, if any candidates remain, the algorithm groups them by network group (based on IP prefix). The network group with the most candidates loses one peer: the one connected most recently. This prevents an attacker from monopolizing connections from a single network range.
Tor and I2P peers typically have higher latency than IPv4/IPv6. Without special protection, they would be systematically evicted due to high ping times, reducing the network's resilience against surveillance and partitioning attacks. The ProtectEvictionCandidatesByRatio() function reserves slots specifically for these peers.
Privacy Networks
Bitcoin Core supports multiple privacy-preserving network transports, allowing nodes to operate without revealing their IP address.
Tor (The Onion Router)
- Automatic integration: if Tor is running, Bitcoin Core auto-detects the control port and creates a hidden service
- Control protocol:
torcontrol.cppuses Tor's control protocol (port 9051) to create ephemeral v3 onion services - Outbound via SOCKS5: all outbound connections to .onion addresses route through Tor's SOCKS5 proxy
- -onlynet=onion: restrict all connections to Tor for maximum privacy
I2P (Invisible Internet Project)
- SAM protocol: Bitcoin Core uses the SAM (Simple Anonymous Messaging) v3.1 protocol to communicate with a local I2P router
- Session-based: creates a persistent session for accepting inbound connections and a transient session for each outbound connection
- B32 addresses: I2P addresses are base32-encoded 256-bit hashes of the destination's public key
- -i2psam=host:port: specify the I2P SAM proxy address
CJDNS
- An encrypted IPv6 mesh network where addresses are derived from public keys
- Bitcoin Core treats CJDNS as a separate network type for peer management
- CJDNS peers are protected during eviction, similar to Tor and I2P
ZMQ Notifications
Bitcoin Core can push real-time notifications to external applications using ZeroMQ (ZMQ) publish-subscribe sockets. This is faster than polling RPC.
Available Topics
Configuration
Each topic binds to a separate ZMQ endpoint: -zmqpubhashtx=tcp://127.0.0.1:28332. Subscribers connect to these endpoints and receive a continuous stream of notifications. Each message includes a sequence number to detect missed messages.
REST Interface
Bitcoin Core includes a lightweight REST API (enabled with -rest) for retrieving blockchain data without RPC authentication.
Available Endpoints
/rest/block/<hash>.json: full block as JSON/rest/block/notxdetails/<hash>.json: block header + txid list/rest/tx/<txid>.json: transaction details (requires -txindex)/rest/headers/<count>/<hash>.json: consecutive block headers/rest/chaininfo.json: current chain state (height, best block, difficulty)/rest/mempool/info.json: mempool statistics/rest/mempool/contents.json: all mempool transaction details/rest/getutxos/<txid>-<n>.json: check if specific UTXOs exist/rest/blockhashbyheight/<height>.json: block hash at a given height
Responses are available in JSON (.json), binary (.bin), or hex (.hex) formats. The REST interface is read-only; it cannot submit transactions or modify state.