Bitcoin Core the most popular software implementation of Bitcoin, openly developed on GitHub (https://github.com/bitcoin/bitcoin) and publishing releases on https://bitcoincore.org. The BitBox Base uses the latest stable binary release to communicate with the Bitcoin peer-to-peer network, for example to learn about current transactions and receive newly mined blocks. All data is regarded as untrusted until it is locally verified to match the consensus rules of Bitcoin Core.
master branch on GitHub reflects the current development process, a new stable release is tagged and tested every few months. This release is built from the source code in a reproducible way for various platforms by many contributors, verifying that they get the exact same binary executables by comparing the sha256 hash. These hash values for all images are provided in the
SHA256SUM.asc file, which is signed by a Bitcoin Core maintainer, currently laanwj.
Instead of compiling Bitcoin Core from source when building the Armbian image, or poviding our own binaries, we believe that following the official binary releases is a good way to minimize trusting any single entity and keep the build process performant.
To ensure that the official binary is used, we store the verified signing key
01EA 5486 DE18 A882 D4C2 6845 90C8 019E 36C2 E964 independently from the Bitcoin Core release site and validate the downloaded binary against the signed hash values. If this verification does not succeed (a single bit difference would be enough) the build script aborts with an error.
The application configuration is specified in the local
/etc/bitcoin/bitcoin.conf file. The
bitcoin.conf file is written into the Armbian image by the
# application testnet=1 server=1 listen=1 listenonion=1 daemon=1 txindex=0 prune=0 disablewallet=1 pid=/run/bitcoind/bitcoind.pid rpccookiefile=/mnt/ssd/bitcoin/.bitcoin/.cookie sysparms=1 rpcconnect=127.0.0.1 # performance dbcache=2000 maxmempool=50 maxconnections=40 maxuploadtarget=5000 # tor proxy=127.0.0.1:9050 seednode=nkf5e6b7pl4jfd4a.onion seednode=xqzfakpeuvrobvpj.onion seednode=tsyvzsqwa2kkf6b2.onion
Some notes about this specific configuration:
- Application options
testnet: the build script defaults to building a testnet node, but can be configured to run on mainnet (commenting out this line):
server: enables the RPC interface
listen: accept connections from other nodes
listenonion: create a Tor hidden service and accept incoming connections from other nodes on that address
daemon: run bitcoind as a server in the background
txindex: a full transaction index is not necessary, as we use electrs - which has its own indices - to serve transaction information.
prune: both c-lightning as well as electrs do not support pruned Bitcoin nodes at the moment.
disablewallet: wallet functionality of bitcoind is not used and therefore disabled
pid: this file contains the process id of bitcoind
rpccookiefile: other applications using the bitcoind RPC authenticate themselves by reading the access credentials from the
.cookiefile. To avoid using different storage locations when running Bitcoin mainnet or testnet, the location is explicitly specified.
sysparms: other system users that are a member of the
bitcoingroup need to have read-only access to the
.cookiefile. Using this option, bitcoind creates new files with system default permissions instead of the umask 0777.
rpcconnect: as the bitcoind rpc port is sensitive, it listens for local connections only.
- Performance options
dbcache: initially, the database cache is optimized for the initial block download (IBD), allocating 2GB memory. This value is set to a lower value (default: 300 MB) after bitcoind is fully synced.
maxmempool: upper limit in MB for mempool
maxconnections: upper limit number of connections to other Bitcoin nodes
maxuploadtarget: upper limit for daily upload data volume
proxy: set bitcoind to also use the Tor proxy for IPv4 and IPv6 connections
seednode: initial Tor nodes to bootstrap connections and discover additional nodes
The bitcoind service is managed by systemd. Relevant parameters are specified in the unit file
bitcoind.service shown below. Please check the most current initial configuration in
[Unit] Description=Bitcoin daemon After=network-online.target startup-checks.service tor.service Requires=startup-checks.service [Service] ExecStart=/opt/shift/scripts/systemd-start-bitcoind.sh RuntimeDirectory=bitcoind User=bitcoin Group=bitcoin Type=forking PIDFile=/run/bitcoind/bitcoind.pid Restart=always RestartSec=60 TimeoutSec=300 PrivateTmp=true ProtectSystem=full NoNewPrivileges=true PrivateDevices=true MemoryDenyWriteExecute=true [Install] WantedBy=multi-user.target
Some notes about this specific configuration:
After: started after network is established, Tor is enabled and startup-checks have passed.
ExecStart: instead of starting bitcoind directly, it is called with a shell script to allow for additional commands (see next paragraph)
User: runs as service user “bitcoin”
Restart: always restarted, unless manually stopped
PrivateTmp: using a private tmp directory
ProtectSystem: mount /usr, /boot/ and /etc read-only for the process
NoNewPrivileges: disallow the process and all of its children to gain new privileges through execve()
PrivateDevices: use a new /dev namespace only populated with API pseudo devices such as /dev/null, /dev/zero and /dev/random
MemoryDenyWriteExecute: deny the creation of writable and executable memory mappings
The systemd unit executes bitcoind with the shell script
systemd-start-bitcoind.sh. This allows the execution of additional commands for preparation and post-processing.
For additional details, please check the inline comments directly in the script.
As bitcoind is run as user “bitcoin”, it uses the user’s home directory (set to the SSD as
/mnt/ssd/bitcoin/) as the standard data directory and creates the directory
.bitcoin at this location.