The high performance Bitcoin full node server based on libbitcoin-node, libbitcoin-system, libbitcoin-database, and libbitcoin-network.
This is the server component of libbitcoin v4. It integrates the basic components and offers a high performance Bitcoin full node with a comprehensive set of client-server interfaces like bitcoind, electrum and stratum as well as an intergrated block explorer. It makes full use of the available hardware, internet connection and availabe RAM and CPU so you can sync the Bitcoin blockchain from genesis, today and in the future.
If you follow this README you will be able to build, run and monitor your own libbitcoin server (bs). Libbitcoin is a multi platform software that works on Linux, Windows and OSX (Intel and ARM).
Now, If you want to see how fast your setup can sync the Bitcoin Blockchain, read on and get your libbitcoin server running today. It's pretty easy actually.
License Overview
All files in this repository fall under the license specified in COPYING. The project is licensed under the GNU Affero General Public License v3.0. It may be used within a proprietary project, but the core library and any changes to it must be published online. Source code for this library must always remain free for everybody to access.
About libbitcoin
The libbitcoin toolkit is a set of cross platform C++ libraries for building Bitcoin applications. The toolkit consists of several libraries, most of which depend on the foundational libbitcoin-system library. Each library's repository can be cloned and built separately. There are no packages yet in distribution, however each library includes an installation script (described below) which is regularly verified via GitHub Actions.
The build process is essentially the same on Linux, macOS, and other Unix-like systems. It differs significantly on Windows due to the use of native Visual Studio projects and solutions. Detailed instructions are provided below.
Linux users can build libbitcoin node with the provided installation script install.sh that uses Autotools and pkg-config to first build the needed dependencies (boost, libpsec256) and then fetches the latest libbitcoin projects (libbitcoin-system, libbitcoin-database, libbitcoin-network, libbitcoin-node and libbitcoin-server) from GitHub and builds the stack bottom up to the libbitcoin-server executable - bs.
You can issue the following command to check for further parameterization of the install script:
$ install.sh --helpwhich brings up the following options:
Usage: ./install.sh [OPTION]...
Manage the installation of libbitcoin-server.
Script options:
--with-icu Compile with International Components for Unicode.
Since the addition of BIP-39 and later BIP-38
support, libbitcoin conditionally incorporates ICU
to provide BIP-38 and BIP-39 passphrase
normalization features. Currently
libbitcoin-explorer is the only other library that
accesses this feature, so if you do not intend to
use passphrase normalization this dependency can
be avoided.
--build-icu Build ICU libraries.
--build-boost Build Boost libraries.
--build-secp256k1 Build libsecp256k1 libraries.
--build-dir=<path> Location of downloaded and intermediate files.
--prefix=<absolute-path> Library install location (defaults to /usr/local).
--disable-shared Disables shared library builds.
--disable-static Disables static library builds.
--help, -h Display usage, overriding script execution.
All unrecognized options provided shall be passed as configuration options for
all dependencies.
In order to successfully execute install.sh a few requirements need to be met. This walkthrough is based on a 'current' installation of the following components. (That doesn't necessarily mean these are the minimum requirements though).
- Base OS: Ubuntu 24.04.3 LTS (Noble Numbat)
- C++13 compiler (gcc version 13.3.0 (Ubuntu 13.3.0-6ubuntu2~24.04))
- Autoconf
- Automake
- libtool
- pkg-config
- git
- curl
The corresponding packages can be installed with the following command:
$ sudo apt install build-essential curl git autoconf automake pkg-config libtoolCreate a new directory (e.g. /home/user/libbitcoin), then use git to fetch the latest repository from GitHub by issuing the following command from within this directory:
git clone https://github.com/libbitcoin/libbitcoin-serverEnter the project directory cd libbitcoin-server and start the build with the following command:
$ ./install.sh --prefix=/home/user/libbitcoin/build/release_static/ --build-secp256k1 --build-boost --disable-sharedThis will build the libbitcoin-server executable as a static release with no CPU extensions built in. Use only absolute path names for prefix dir. A successful build will create the following directory/file structure:
~/bitcoin/libbitcoin/
~/bitcoin/libbitcoin/build/
~/bitcoin/libbitcoin/build/release_static/
~/bitcoin/libbitcoin/build/release_static/bin/
~/bitcoin/libbitcoin/build/release_static/etc/
~/bitcoin/libbitcoin/build/release_static/include/
~/bitcoin/libbitcoin/build/release_static/lib/
~/bitcoin/libbitcoin/build/release_static/share/
~/bitcoin/libbitcoin/build/release_static/share/doc/
~/bitcoin/libbitcoin/build/release_static/share/doc/libbitcoin-database/
~/bitcoin/libbitcoin/build/release_static/share/doc/libbitcoin-network/
~/bitcoin/libbitcoin/build/release_static/share/doc/libbitcoin-node/
~/bitcoin/libbitcoin/build/release_static/share/doc/libbitcoin-server/
~/bitcoin/libbitcoin/build/release_static/share/doc/libbitcoin-system/
~/bitcoin/libbitcoin/libbitcoin-node
Now enter the bin directory and fire up your libbitcoin server.
CPU Extensions are specific optimizations your CPU might or might not have. libbitcoin(-server) can be built with support for the following CPU extensions if your architecture supports them:
To build libbitcoin-server with these extensions use the --enable-feature parameters like:
- --enable-shani
- --enable-sse41
- --enable-avx2
- --enable-avx512
This command will create a static release build with all supported CPU extensions (if supported by the system). Building libbitcoin with unsupported CPU extensions might work but will lead to crashes at runtime.
$ CFLAGS="-O3" CXXFLAGS="-O3" ./install.sh --prefix=/home/user/libbitcoin/build/release_static/ --build-dir=/home/user/libbitcoin/build/temp --build-secp256k1 --build-boost --disable-shared --enable-ndebug --enable-shani --enable-avx2 --enable-sse41 --enable-isystemYou can check if the optimizations have been built in your binary with the following command:
$ ./bs --hardwarewhich will show your CPU architecture as well as the built in status of the supported optimizations:
Hardware configuration...
arm..... platform:0.
intel... platform:1.
avx512.. platform:1 compiled:1.
avx2.... platform:1 compiled:1.
sse41... platform:1 compiled:1.
shani... platform:1 compiled:1.
TBD
TBD
Let's see what options we have for the server:
$ ./bs --helpThe response should look like this:
Usage: bs [-abdfhiklnrstvw] [--config value]
Info: Runs a full bitcoin server.
Options (named):
-a [--slabs] Scan and display store slab measures.
-b [--backup] Backup to a snapshot (can also do live).
-c [--config] Specify path to a configuration settings file.
-d [--hardware] Display hardware compatibility.
-f [--flags] Scan and display all flag transitions.
-h [--help] Display command line options.
-i [--information] Scan and display store information.
-k [--buckets] Scan and display all bucket densities.
-l [--collisions] Scan and display hashmap collision stats (may exceed
RAM and result in SIGKILL).
-n [--newstore] Create new store in configured directory.
-r [--restore] Restore from most recent snapshot.
-s [--settings] Display all configuration settings.
-t [--test] Run built-in read test and display.
-v [--version] Display version information.
-w [--write] Run built-in write test and display.
Did you check if all supported CPU Extensions are built in (./bn --hardware)?
Starting the server without passing any parameters like
$ ./bs
will do the following:
- If there is no data store at
./bitcoin/, the node will create one. The location can be changed in the config file (bs.cfg). - Start multiple threads to setup peer connections, to download and to process blocks in default mode (milestone sync). See Theory of operation for more information about operating modes.
- Expose an interactive console to do basic communication with the node -> Using the console
- Write various logfiles -> Logging
Furthermore the standard parameters will perform a milestone sync with the Bitcoin Blockchain, as opposed to a full validation sync.
Although this works in principle, you may want to do at least a few basic settings. You do this by passing a config file to the node:
$ ./bs --config ./bs.cfgThe node will now expect to find a valid config file in the current folder.
Starting a full validation sync on the node requires to set the latest milestone block back to genesis. This is done by adding the following lines to the config file:
[bitcoin]
checkpoint = 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f:0
milestone = 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f:0
Further information on how to adjust the config file as well as example configurations can be found here.
libbitcoin-server creates the following files at start:
- events.log
- bs_begin.log (rotated to bs_end.log)
- hosts.cache
The events.log file records all information about the sync process, providing the current status and speed of the sync. Read Performance to learn how to check your sync speed through the logs.
Pressing m + Enter in the terminal will bring up the interactive console. This interface is mainly used for low level logging and configuration and it looks like this:
2025-10-17T23:47:58Z.0 Toggle: [v]erbose
2025-10-17T23:47:58Z.0 Toggle: [o]bjects
2025-10-17T23:47:58Z.0 Toggle: [q]uitting
2025-10-17T23:47:58Z.0 Toggle: [f]ault
2025-10-17T23:47:58Z.0 Toggle: [r]emote
2025-10-17T23:47:58Z.0 Toggle: [x]proxy
2025-10-17T23:47:58Z.0 Toggle: [p]rotocol
2025-10-17T23:47:58Z.0 Toggle: [s]ession
2025-10-17T23:47:58Z.0 Toggle: [n]ews
2025-10-17T23:47:58Z.0 Toggle: [a]pplication
2025-10-17T23:47:58Z.0 Option: [z]eroize disk full error
2025-10-17T23:47:58Z.0 Option: [w]ork distribution
2025-10-17T23:47:58Z.0 Option: [t]est built-in case
2025-10-17T23:47:58Z.0 Option: [m]enu of options and toggles
2025-10-17T23:47:58Z.0 Option: [i]nfo about store
2025-10-17T23:47:58Z.0 Option: [h]old network communication
2025-10-17T23:47:58Z.0 Option: [g]o network communication
2025-10-17T23:47:58Z.0 Option: [e]rrors in store
2025-10-17T23:47:58Z.0 Option: [c]lose the node
2025-10-17T23:47:58Z.0 Option: [b]ackup the store
Further information about how to use the interactive console can be found here
You can check your server's performance using the log files. To do this, check the events.log file as follows. Let's check for the organization of Block 700,000. The command
$ cat ./events.log | grep 'block_organized..... 700000'will give you something like this, with the number on the right representing the seconds since the server started until block 700k was organized:
block_organized..... 700000 11053
In this case it took the node 11053 seconds (or 184 minutes) to sync up to Block 700k.
As the node aims to sync the Blockchain as fast as possible, we assume that if the computer is powerful enough, the limiting factor for syncing the chain is your internet connection - you simply can't sync faster than the time needed to download the Blockchain.
The following diagram shows the performance data extracted from various IBDs (bs milestone and full validation, Core 30 Standard and AssumeValid) on a 64 Core, 256MB RAM machine running Ubuntu.
brunella - Dell Precision Tower 7810
- Dual Intel® Xeon® CPU E5-2683 v4 @ 2.10 GHz (32 Kerne / 64 Threads)
- 256 GB DDR4 ECC Registered (RDIMM)
- 4 TB SSD Samsung 990 PRO (PCIe Gen4)
- 2 GBit/s Fiber Internet
Check this to learn more about how performance profiling and optimization works.
In order to improve the performance on your Linux system, you probably have to alter the kernel parameters that determine the memory management of the system (Memory Paging).
These sysctl parameters optimize Linux VM dirty page writeback for high I/O workloads (e.g., databases). Set via /etc/sysctl.conf or sudo sysctl. This table shows the stock values of the current Ubuntu LTS.
| Parameter | Value | Description |
|---|---|---|
vm.dirty_background_ratio |
10 |
Initiates background writeback at 10% dirty RAM (lowers latency). |
vm.dirty_ratio |
20 |
Blocks apps at 20% dirty RAM (prevents OOM). |
vm.dirty_expire_centisecs |
3000 |
Marks pages "old" after 30s (1/100s units; triggers writeback). |
vm.dirty_writeback_centisecs |
500 |
Wakes kworker every 5s to flush old pages. |
Check your actual kernel parameters by issuing the following command:
$ sysctl vm.dirty_background_ratio vm.dirty_ratio vm.dirty_expire_centisecs vm.dirty_writeback_centisecsThe following parameters have been identified to be the most effective for the most computers we use for testing. They basically allow the server process to use as much RAM as possible (90%) and flush the dirty pages after 2 minutes:
- vm.dirty_background_ratio = 90
- vm.dirty_ratio = 90
- vm.dirty_expire_centisecs = 12000
- vm.dirty_writeback_centisecs = 12000
Set them with the following commands:
$ sudo sysctl vm.dirty_background_ratio=90
$ sudo sysctl vm.dirty_ratio=90
$ sudo sysctl vm.dirty_expire_centisecs=12000
$ sudo sysctl vm.dirty_writeback_centisecs=12000Tuning: As these parameters apply globally, you can adjust them under load from a different terminal.
If set this way the settings are only temporary and reset after reboot. Although there are options to set them permanently we suggest to play around with session based parameters until you found the setting that works best for your system. Note that these parameters apply to the OS and therefore to all running applications.
Further information on how to adjust dirty page writeback on other operating systems can be found here.