|
1 | | -This branch is not usable in its current state. Please see [version3](https://github.com/libbitcoin/libbitcoin-node/tree/version3) for the latest functional branch. |
| 1 | +[](https://github.com/libbitcoin/libbitcoin-node/actions/workflows/ci.yml?branch=master) |
| 2 | +[](https://coveralls.io/github/libbitcoin/libbitcoin-node?branch=master) |
| 3 | + |
| 4 | +# libbitcoin-node |
| 5 | + |
| 6 | +*The high performance Bitcoin full node based on [libbitcoin-system](https://github.com/libbitcoin/libbitcoin-system), [libbitcoin-database](https://github.com/libbitcoin/libbitcoin-database), and [libbitcoin-network](https://github.com/libbitcoin/libbitcoin-network).* |
| 7 | + |
| 8 | +## tl;dr |
| 9 | + |
| 10 | +This is the **node of libbitcoin v4**. It integrates the basic components and offers a high performance Bitcoin full node that makes heavy use of the available hardware, internet connection and availabe RAM and CPU. |
| 11 | + |
| 12 | +If you follow this README you will be able to build, run and monitor your own libbitcoin node. Libbitcoin is a multi platform software that works on Linux, Windows and OSX (Intel and ARM). |
| 13 | + |
| 14 | +The node currently serves as a full node: it receives and distributes blocks in conformity with the Bitcoin protocol as fast as your hardware allows it. A current work in progress is the connection layer that will let enables to connect the libbitcoin node to other systems like Sparrow Wallet (via `ElectrumX`) or Stratum V1 (via `json-rpc`). |
| 15 | + |
| 16 | +Now, If you want to see how fast your setup can sync the Bitcoin Blockchain, read on and get your libbitcoin node running today. It's pretty easy actually. |
| 17 | + |
| 18 | +**License Overview** |
| 19 | + |
| 20 | +All files in this repository fall under the license specified in [COPYING](COPYING). The project is licensed as [AGPL with a lesser clause](https://wiki.unsystem.net/en/index.php/Libbitcoin/License). 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. |
| 21 | + |
| 22 | +**About libbitcoin** |
| 23 | + |
| 24 | +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](https://github.com/libbitcoin/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](https://github.com/features/actions). |
| 25 | + |
| 26 | +## Contents |
| 27 | +- [Installation](#installation) |
| 28 | + - [Linux](#linux) |
| 29 | + - [macOS](#macos) |
| 30 | + - [Windows](#windows) |
| 31 | +- [Running libbitcoin](#running-libbitcoin) |
| 32 | + - [Startup Process](#startup-process) |
| 33 | + - [Configuration](#configuration) |
| 34 | + - [Logging](#logging) |
| 35 | + - [Using the Console](#using-the-console) |
| 36 | + - [Performance Analysis](#performance-analysis) |
| 37 | + - [Memory Management](#memory-management) |
| 38 | +- [Known Limitiations](#known-limitations) |
| 39 | + |
| 40 | +## Installation |
| 41 | + |
| 42 | +Depending on what operating system you use, the build process will be different. Detailed instructions are provided below. |
| 43 | + |
| 44 | +- [Linux (Ubuntu)](#linux) |
| 45 | +- [macOS](#macos) |
| 46 | +- [Windows](#windows) |
| 47 | + |
| 48 | +### Linux |
| 49 | + |
| 50 | +Linux users 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) from github and builds the stack bottom up to the libbitcoin-node binary - bn. |
| 51 | + |
| 52 | +You can issue the following command to check for further parameterization of the install script: |
| 53 | + |
| 54 | +```bash |
| 55 | +$ install.sh --help |
| 56 | +``` |
| 57 | + |
| 58 | +which brings up the following options: |
| 59 | + |
| 60 | +``` |
| 61 | +Usage: ./install.sh [OPTION]... |
| 62 | +Manage the installation of libbitcoin-node. |
| 63 | +Script options: |
| 64 | + --with-icu Compile with International Components for Unicode. |
| 65 | + Since the addition of BIP-39 and later BIP-38 |
| 66 | + support, libbitcoin conditionally incorporates ICU |
| 67 | + to provide BIP-38 and BIP-39 passphrase |
| 68 | + normalization features. Currently |
| 69 | + libbitcoin-explorer is the only other library that |
| 70 | + accesses this feature, so if you do not intend to |
| 71 | + use passphrase normalization this dependency can |
| 72 | + be avoided. |
| 73 | + --build-icu Build ICU libraries. |
| 74 | + --build-boost Build Boost libraries. |
| 75 | + --build-secp256k1 Build libsecp256k1 libraries. |
| 76 | + --build-dir=<path> Location of downloaded and intermediate files. |
| 77 | + --prefix=<absolute-path> Library install location (defaults to /usr/local). |
| 78 | + --disable-shared Disables shared library builds. |
| 79 | + --disable-static Disables static library builds. |
| 80 | + --help, -h Display usage, overriding script execution. |
| 81 | +
|
| 82 | +All unrecognized options provided shall be passed as configuration options for |
| 83 | +all dependencies. |
| 84 | +``` |
| 85 | + |
| 86 | +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). |
| 87 | + |
| 88 | +#### Requirements |
| 89 | +* Base OS: Ubuntu 24.04.3 LTS (Noble Numbat) |
| 90 | +* C++13 compiler (gcc version 13.3.0 (Ubuntu 13.3.0-6ubuntu2~24.04)) |
| 91 | +* [Autoconf](https://www.gnu.org/software/autoconf/) |
| 92 | +* [Automake](https://www.gnu.org/software/automake/) |
| 93 | +* [libtool](https://www.gnu.org/software/libtool/) |
| 94 | +* [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) |
| 95 | +* [git](https://git-scm.com/) |
| 96 | +* [curl](https://www.gnu.org/software/curl/) |
| 97 | + |
| 98 | +The corresponding packages can be installed with the following command: |
| 99 | + |
| 100 | +```bash |
| 101 | +$ sudo apt install build-essential curl git automake pkg-config libtool |
| 102 | +``` |
| 103 | + |
| 104 | +Create a new directory (e.g. `/home/user/development/libbitcoin`), then use git to fetch the latest repository from github by issuing the following command from within this directory: |
| 105 | + |
| 106 | +```bash |
| 107 | +git clone https://github.com/libbitcoin/libbitcoin-node |
| 108 | +``` |
| 109 | + |
| 110 | +Enter the project directory `cd libbitcoin-node` and start the build with the following command: |
| 111 | + |
| 112 | +```bash |
| 113 | +$ ./install.sh --prefix=/home/user/development/libbitcoin/build/release_static/ --build-secp256k1 --build-boost --disable-shared |
| 114 | +``` |
| 115 | + |
| 116 | +This will build libbitcoin-node as a static release with no [CPU extensions](#cpu-extensions) built in. Use only absolute path names for prefix dir. A successful build will create the following directory/file structure: |
| 117 | + |
| 118 | +``` |
| 119 | +~/development/libbitcoin/ |
| 120 | +~/development/libbitcoin/build/ |
| 121 | +~/development/libbitcoin/build/release_static/ |
| 122 | +~/development/libbitcoin/build/release_static/bin/ |
| 123 | +~/development/libbitcoin/build/release_static/etc/ |
| 124 | +~/development/libbitcoin/build/release_static/include/ |
| 125 | +~/development/libbitcoin/build/release_static/lib/ |
| 126 | +~/development/libbitcoin/build/release_static/share/ |
| 127 | +~/development/libbitcoin/build/release_static/share/doc/ |
| 128 | +~/development/libbitcoin/build/release_static/share/doc/libbitcoin-database/ |
| 129 | +~/development/libbitcoin/build/release_static/share/doc/libbitcoin-network/ |
| 130 | +~/development/libbitcoin/build/release_static/share/doc/libbitcoin-node/ |
| 131 | +~/development/libbitcoin/build/release_static/share/doc/libbitcoin-system/ |
| 132 | +~/development/libbitcoin/libbitcoin-node |
| 133 | +``` |
| 134 | + |
| 135 | +Now enter the bin directory and [fire up](#running-libbitcoin) your node. |
| 136 | + |
| 137 | +### CPU Extensions |
| 138 | + |
| 139 | +CPU Extensions are specific optimizations your CPU might or might not have. libbitcoin can be built with support for the following CPU extensions if your architecture supports them: |
| 140 | + |
| 141 | +* [SHA-NI](https://en.wikipedia.org/wiki/SHA_instruction_set) |
| 142 | +* [SSE4.1](https://en.wikipedia.org/wiki/SSE4) |
| 143 | +* [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) |
| 144 | +* [AVX512](https://en.wikipedia.org/wiki/AVX-512) |
| 145 | + |
| 146 | +To build libbitcoin-node with these extensions use the `--enable-feature` parameters like: |
| 147 | + |
| 148 | +- --enable-shani |
| 149 | +- --enable-avx2 |
| 150 | +- --enable-sse41 |
| 151 | +- --enable-avx512 |
| 152 | + |
| 153 | +This command will create a static release build with all supported CPU extensions (if supported by the system): |
| 154 | + |
| 155 | +```bash |
| 156 | +$ CFLAGS="-O3" CXXFLAGS="-O3" ./install.sh --prefix=/home/eynhaender/development/libbitcoin/build/release_static/ --build-dir=/home/eynhaender/development/libbitcoin/build/temp --build-secp256k1 --build-boost --disable-shared --enable-ndebug --enable-shani --enable-avx2 --enable-sse41 --enable-avx512 |
| 157 | +``` |
| 158 | + |
| 159 | +You can check if the optimizations have been built in your binary with the following command: |
| 160 | + |
| 161 | +```bash |
| 162 | +$ ./bn --hardware |
| 163 | +``` |
| 164 | + |
| 165 | +which will show your CPU architecture as well as the built in status of the supported optimizations: |
| 166 | + |
| 167 | +``` |
| 168 | +Hardware configuration... |
| 169 | +arm..... platform:0. |
| 170 | +intel... platform:1. |
| 171 | +avx512.. platform:1 compiled:1. |
| 172 | +avx2.... platform:1 compiled:1. |
| 173 | +sse41... platform:1 compiled:1. |
| 174 | +shani... platform:1 compiled:1. |
| 175 | +``` |
| 176 | + |
| 177 | +### macOS |
| 178 | +TODO |
| 179 | + |
| 180 | +### Windows |
| 181 | +TODO |
| 182 | + |
| 183 | +## Running libbitcoin |
| 184 | +Let's see what options we have for the node: |
| 185 | + |
| 186 | +```bash |
| 187 | +$ ./bn --help |
| 188 | +``` |
| 189 | + |
| 190 | +The response should look like this: |
| 191 | + |
| 192 | +``` |
| 193 | +Usage: bn [-abdfhiklnrstvw] [--config value] |
| 194 | +
|
| 195 | +Info: Runs a full bitcoin node. |
| 196 | +
|
| 197 | +Options (named): |
| 198 | +
|
| 199 | +-a [--slabs] Scan and display store slab measures. |
| 200 | +-b [--backup] Backup to a snapshot (can also do live). |
| 201 | +-c [--config] Specify path to a configuration settings file. |
| 202 | +-d [--hardware] Display hardware compatibility. |
| 203 | +-f [--flags] Scan and display all flag transitions. |
| 204 | +-h [--help] Display command line options. |
| 205 | +-i [--information] Scan and display store information. |
| 206 | +-k [--buckets] Scan and display all bucket densities. |
| 207 | +-l [--collisions] Scan and display hashmap collision stats (may exceed |
| 208 | + RAM and result in SIGKILL). |
| 209 | +-n [--newstore] Create new store in configured directory. |
| 210 | +-r [--restore] Restore from most recent snapshot. |
| 211 | +-s [--settings] Display all configuration settings. |
| 212 | +-t [--test] Run built-in read test and display. |
| 213 | +-v [--version] Display version information. |
| 214 | +-w [--write] Run built-in write test and display. |
| 215 | +``` |
| 216 | + |
| 217 | +Did you check if all supported [CPU Extensions](#cpu-extensions) are built in (`./bn --hardware`)? |
| 218 | + |
| 219 | +### Startup Process |
| 220 | + |
| 221 | +Starting the node without passing any parameters like: |
| 222 | + |
| 223 | +``` |
| 224 | +$ ./bn |
| 225 | +``` |
| 226 | + |
| 227 | +will do the following: |
| 228 | +- If there is no data store at `./bitcoin/`, the node will create one. The location can be changed in the [config](#config-file) file (`bn.cfg`). |
| 229 | +- Start multiple threads to setup peer connections, to download and to process blocks -> [Theory of operation](#TODO) |
| 230 | +- Expose an interactive console to do basic communication with the node -> [Using the console](#using-the-console) |
| 231 | +- Write various logfiles -> [Logging](#logging) |
| 232 | + |
| 233 | +Furthermore the standard parameters will perform a **milestone sync** with the Bitcoin Blockchain, as opposed to a **full validation sync**. |
| 234 | + |
| 235 | +Although this works in principle, you may want to do at least a few basic settings. You do this by passing a [config file](#config-file) to the node: |
| 236 | + |
| 237 | +```sh |
| 238 | +$ ./bn --config ./bn.cfg |
| 239 | +``` |
| 240 | + |
| 241 | +The node will now expect to find a valid [config file](#config-file) in the current folder. |
| 242 | + |
| 243 | +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: |
| 244 | + |
| 245 | +``` |
| 246 | +[bitcoin] |
| 247 | +checkpoint = 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f:0 |
| 248 | +milestone = 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f:0 |
| 249 | +``` |
| 250 | + |
| 251 | +### Config File |
| 252 | + |
| 253 | +libbitcoin node reads its basic configuration from a config file that can be passed to the function as a parameter `-c`. The config file has the following structure: |
| 254 | + |
| 255 | +``` |
| 256 | +[database] |
| 257 | +path = /mnt/blockchain/bitcoin |
| 258 | +#path = /mnt/blockchain/bitcoin_tn |
| 259 | +#path = /mnt/blockchain/zcash |
| 260 | +
|
| 261 | +[network] |
| 262 | +threads = 16 |
| 263 | +#threads = 8 |
| 264 | +seed = cup.nop.lol:8333 |
| 265 | +#seed = dnsseed.bitcoin.dashjr.org:8333 |
| 266 | +
|
| 267 | +[node] |
| 268 | +#threads = 32 |
| 269 | +
|
| 270 | +[server] |
| 271 | +inbound_connections = 0 |
| 272 | +bind = 0.0.0.0:80 |
| 273 | +
|
| 274 | +``` |
| 275 | +A current config template is generated during build and saved at `/prefix-dir/etc/libbitcoin/bn.cfg`. |
| 276 | + |
| 277 | +### Logging |
| 278 | + |
| 279 | +libbitcoin-node creates the following files at start: |
| 280 | + |
| 281 | +* events.log |
| 282 | +* bn_begin.log |
| 283 | +* bn_end.log |
| 284 | +* hosts.cache |
| 285 | + |
| 286 | +The events.log file displays all information about the sync process, providing the current status and speed of the sync. Read [Performance Analysis](#performance-analysis) to check your sync speed through the logs. |
| 287 | + |
| 288 | +### Using the console |
| 289 | + |
| 290 | +Pressing **`m` + Enter** while running will bring up the interactive console. This interface is mainly user for low level logging and configuration and it looks like this: |
| 291 | + |
| 292 | +``` |
| 293 | +2025-10-17T23:47:58Z.0 Toggle: [v]erbose |
| 294 | +2025-10-17T23:47:58Z.0 Toggle: [o]bjects |
| 295 | +2025-10-17T23:47:58Z.0 Toggle: [q]uitting |
| 296 | +2025-10-17T23:47:58Z.0 Toggle: [f]ault |
| 297 | +2025-10-17T23:47:58Z.0 Toggle: [r]emote |
| 298 | +2025-10-17T23:47:58Z.0 Toggle: [x]proxy |
| 299 | +2025-10-17T23:47:58Z.0 Toggle: [p]rotocol |
| 300 | +2025-10-17T23:47:58Z.0 Toggle: [s]ession |
| 301 | +2025-10-17T23:47:58Z.0 Toggle: [n]ews |
| 302 | +2025-10-17T23:47:58Z.0 Toggle: [a]pplication |
| 303 | +2025-10-17T23:47:58Z.0 Option: [z]eroize disk full error |
| 304 | +2025-10-17T23:47:58Z.0 Option: [w]ork distribution |
| 305 | +2025-10-17T23:47:58Z.0 Option: [t]est built-in case |
| 306 | +2025-10-17T23:47:58Z.0 Option: [m]enu of options and toggles |
| 307 | +2025-10-17T23:47:58Z.0 Option: [i]nfo about store |
| 308 | +2025-10-17T23:47:58Z.0 Option: [h]old network communication |
| 309 | +2025-10-17T23:47:58Z.0 Option: [g]o network communication |
| 310 | +2025-10-17T23:47:58Z.0 Option: [e]rrors in store |
| 311 | +2025-10-17T23:47:58Z.0 Option: [c]lose the node |
| 312 | +2025-10-17T23:47:58Z.0 Option: [b]ackup the store |
| 313 | +``` |
| 314 | + |
| 315 | +### Performance Analysis |
| 316 | + |
| 317 | +To check the net sync performance of your node you will have to let it run until a specific milestone block is reached. The events.log will then tell you how long it took to reach this block height. If you want to check how long it took for the node to reach a specific Block Height, you check the events.log. |
| 318 | + |
| 319 | +Let's check for the **organization** of Block **700,000** |
| 320 | + |
| 321 | +```bash |
| 322 | +$ cat ./events.log | grep 'block_organized..... 700000' |
| 323 | +``` |
| 324 | + |
| 325 | +which will give you something like this, the number on the right representing the seconds from start of the process to 700k: |
| 326 | + |
| 327 | +``` |
| 328 | +block_organized..... 700000 11053 |
| 329 | +``` |
| 330 | + |
| 331 | +In this case it took the node 11053 seconds or 184 minutes to get to Block 700k. |
| 332 | + |
| 333 | +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. |
| 334 | + |
| 335 | +The following table shows what your node should be capable of on a given internet connection. In other words, these are our numbers: |
| 336 | + |
| 337 | +| Network | OS | Milestone | Seconds/Minutes | Setup | |
| 338 | +|--------------------|--------------|------------|-----------------|------------------------------| |
| 339 | +| 260MBit/s VDSL | Linux/Ubuntu | 900k | | Ryzen7/32GB RAM/WD Black SSD | |
| 340 | +| 400MBit/s Starlink | Linux/Ubuntu | 900k | 16,292/271 | Ryzen7/96GB RAM/WD Black SSD | |
| 341 | +| 400 + 300MBit/s LB | Linux/Ubuntu | 900k | 11,188/187 | Ryzen7/96GB RAM/WD Black SSD | |
| 342 | +| 2.3GBit/s | Windows | 900k | 3600/60 | | |
| 343 | + |
| 344 | +### Memory Management |
| 345 | + |
| 346 | +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](https://en.wikipedia.org/wiki/Memory_paging)). |
| 347 | + |
| 348 | +#### Kernel VM Tuning Parameters |
| 349 | + |
| 350 | +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. |
| 351 | + |
| 352 | +| Parameter | Value | Description | |
| 353 | +|--------------------------------|--------|-------------------------------------------------------------------| |
| 354 | +| `vm.dirty_background_ratio` | `10` | Initiates background writeback at 10% dirty RAM (lowers latency). | |
| 355 | +| `vm.dirty_ratio` | `20` | Blocks apps at 20% dirty RAM (prevents OOM). | |
| 356 | +| `vm.dirty_expire_centisecs` | `3000` | Marks pages "old" after 30s (1/100s units; triggers writeback). | |
| 357 | +| `vm.dirty_writeback_centisecs` | `500` | Wakes kworker every 5s to flush old pages. | |
| 358 | + |
| 359 | +Check your actual kernel parameters by issuing the following command: |
| 360 | + |
| 361 | +```sh |
| 362 | +$ sysctl vm.dirty_background_ratio vm.dirty_ratio vm.dirty_expire_centisecs vm.dirty_writeback_centisecs |
| 363 | +``` |
| 364 | + |
| 365 | +The following parameters have been identified to be the most effective for a 'standard' 32GB RAM / SSD computer: |
| 366 | + |
| 367 | +* vm.dirty_background_ratio = 50 |
| 368 | +* vm.dirty_ratio = 80 |
| 369 | +* vm.dirty_expire_centisecs = 6000 |
| 370 | +* vm.dirty_writeback_centisecs = 1000 |
| 371 | + |
| 372 | +**Tune:** Adjust ratios for RAM size; test under load. Set them with the following commands: |
| 373 | + |
| 374 | +```sh |
| 375 | +$ sudo sysctl vm.dirty_background_ratio=50 |
| 376 | +$ sudo sysctl vm.dirty_ratio=80 |
| 377 | +$ sudo sysctl vm.dirty_expire_centisecs=6000 #60 seconds/1 minute |
| 378 | +$ sudo sysctl vm.dirty_writeback_centisecs=1000 #10 seconds |
| 379 | +``` |
| 380 | + |
| 381 | +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. |
| 382 | + |
| 383 | +## Known Limitations |
| 384 | + |
| 385 | +libbitcoin is designed to use the maximum available RAM and, whenever necessary, writes this data to the disk using mmap. The question of whether this is necessary is determined by the operating system (Dirty Paging). During development we noticed that Windows' paging is significantly more performant (because it's dynamic) than either OSX or Linux. To achieve similar performance under Linux as under Windows, the Linux kernel parameters must be adapted to the underlying hardware/the requirements of the node. |
| 386 | + |
| 387 | +Check [Memory Management](#memory-management) and [Performance Analysis](#performance-analysis) to learn how to change your settings. |
0 commit comments