Multiprocess Architecture

Run Bitcoin Core components in separate processes for improved isolation and flexibility

The multiprocess feature allows Bitcoin Core to run node, wallet, and GUI components in separate processes, communicating via IPC (Inter-Process Communication). This provides better isolation, security, and flexibility.

What is Multiprocess Bitcoin?

Multiprocess Bitcoin splits the traditional monolithic bitcoind and bitcoin-qt binaries into separate executables:

• bitcoin-node - Handles P2P networking and RPC
• bitcoin-wallet - Manages wallet operations
• bitcoin-gui - Provides the graphical interface

These processes communicate via socket pairs using the Cap’n Proto protocol, allowing them to run:

• In separate address spaces for better isolation
• On different machines
• In different environments
• With independent lifecycles (start/stop components separately)

When to Use Multiprocess

Multiprocess architecture is beneficial when you need:

• Enhanced Security: Isolate wallet operations from network code
• Flexibility: Run components on different machines (e.g., wallet on secure offline system)
• Debugging: Easier to debug individual components in isolation
• Development: Test components independently
• Resource Management: Allocate resources differently to each component

Multiprocess is currently experimental. Future versions will expand functionality to support remote components and independent lifecycle management.

Building with Multiprocess Support

Unix/Linux Build

Multiprocess is enabled by default on Unix systems:

cmake -B build -DENABLE_IPC=ON
cmake --build build

Dependencies

Multiprocess requires Cap’n Proto to be installed. Install dependencies according to your platform:

• See build-unix.md for Linux instructions
• See build-osx.md for macOS instructions

Using the Depends System

Alternatively, use the depends system to avoid manual dependency installation:

cd <BITCOIN_SOURCE_DIRECTORY>
make -C depends NO_QT=1

# Check depends/ directory for your platform subdirectory
HOST_PLATFORM="x86_64-pc-linux-gnu"

cmake -B build --toolchain=depends/$HOST_PLATFORM/toolchain.cmake
cmake --build build

The depends system automatically handles IPC settings (controlled by NO_IPC=1 option).

Cross-Compiling

When cross-compiling without depends, specify native code generation tools:

cmake -B build \
  -DMPGEN_EXECUTABLE=/path/to/mpgen \
  -DCAPNP_EXECUTABLE=/path/to/capnp \
  -DCAPNPC_CXX_EXECUTABLE=/path/to/capnpc-c++
cmake --build build

External libmultiprocess

By default, libmultiprocess is built from sources at src/ipc/libmultiprocess/. To use an external installation:

# Install libmultiprocess externally first
# Then build Bitcoin Core
cmake -B build -DWITH_EXTERNAL_LIBMULTIPROCESS=ON
cmake --build build

Set CMAKE_PREFIX_PATH if libmultiprocess is installed in a non-standard location:

export CMAKE_PREFIX_PATH=/path/to/libmultiprocess/install
cmake -B build -DWITH_EXTERNAL_LIBMULTIPROCESS=ON
cmake --build build

Usage

Running Multiprocess Binaries

The recommended way is using the bitcoin CLI with the -m flag:

# Run multiprocess node
bitcoin -m node -regtest -printtoconsole -debug=ipc

# Run multiprocess GUI
bitcoin -m gui -printtoconsole -debug=ipc

When using -m (or --multiprocess):

• bitcoin -m node executes bitcoin-node instead of bitcoind
• bitcoin -m gui executes bitcoin-gui instead of bitcoin-qt

Direct invocation of bitcoin-node, bitcoin-wallet, or bitcoin-gui is not recommended as they may change or be renamed in future releases.

Debugging IPC Communication

Enable IPC debugging to see requests and responses between processes:

bitcoin -m node -debug=ipc -printtoconsole

This shows detailed IPC communication logs, helpful for development and troubleshooting.

Running Tests

Run functional tests with multiprocess:

BITCOIN_CMD="bitcoin -m" build/test/functional/test_runner.py

Current Features

Multiprocess binaries currently:

• Function the same as monolithic binaries
• Support an additional -ipcbind option for IPC configuration
• Provide better process isolation

Future Features

Planned enhancements include:

Independent Process Spawning

After PR #10102:

• bitcoin-gui will spawn bitcoin-node for P2P and RPC
• bitcoin-node will spawn bitcoin-wallet for wallet operations
• Components communicate over socket pairs

Remote Connection Support

PR #19460 adds:

# Connect a new wallet process to existing node
bitcoin-wallet -ipcconnect <address>

PR #19461 adds:

# Connect a new GUI process to existing node
bitcoin-gui -ipcconnect <address>

These features enable:

• Running wallet on a secure, isolated machine
• Running GUI remotely while node runs on a server
• Starting/stopping components independently

Example: Development Setup

# Build with depends
cd bitcoin
make -C depends NO_QT=1
HOST_PLATFORM="x86_64-pc-linux-gnu"
cmake -B build --toolchain=depends/$HOST_PLATFORM/toolchain.cmake
cmake --build build

# Run in regtest mode with IPC debugging
build/bin/bitcoin -m node -regtest -printtoconsole -debug=ipc

# In another terminal, interact via RPC
build/bin/bitcoin-cli -regtest getblockchaininfo

Example: Production Setup

# Install dependencies
sudo apt-get install libcapnp-dev

# Build Bitcoin Core
cmake -B build -DENABLE_IPC=ON
cmake --build build
sudo cmake --install build

# Run multiprocess node
bitcoin -m node -daemon

# Check it's running
bitcoin-cli getnetworkinfo

Security Considerations

• Each process runs in its own address space
• Memory corruption in one component doesn’t affect others
• Wallet operations are isolated from network code
• Future versions will support running components on separate machines for enhanced security

While multiprocess improves isolation, it’s still experimental. Use caution in production environments and keep Bitcoin Core updated.