bitcoin-client.md

layout
title description tableOfContents outline pagination visible true visible visible true visible true visible true

2.1 Bitcoin client: Bitcoin Core

We install Bitcoin Core, the reference client implementation of the Bitcoin network.

This may take some time

Bitcoin Core will download the full Bitcoin blockchain, and validate all transactions since 2009. We're talking more than 800'000 blocks with a size of over 465 GB, so this is not an easy task.

Installation

We download the latest Bitcoin Core binary (the application) and compare this file with the signed and timestamped checksum. This is a precaution to make sure that this is an official release and not a malicious version trying to steal our money.

💡 If you want to install the Ordisrespector patch to reject the Ordinals of your mempool, follow the Ordisrespector bonus guide and come back to continue with the "Create the bitcoin user" section.

💡 If you want to install Bitcoin Core from the source code but without the Ordisrespector patch, follow the Ordisrespector bonus guide skipping Apply the patch “Ordisrespector” and come back to continue with the "Create the bitcoin user" section.

Download binaries

• Login as admin and change to a temporary directory which is cleared on reboot

cd /tmp

• Set a temporary version environment variable to the installation

VERSION=28.1

• Get the latest binaries and signatures

{% code overflow="wrap" %}

wget https://bitcoincore.org/bin/bitcoin-core-$VERSION/bitcoin-$VERSION-aarch64-linux-gnu.tar.gz

{% endcode %}

wget https://bitcoincore.org/bin/bitcoin-core-$VERSION/SHA256SUMS

wget https://bitcoincore.org/bin/bitcoin-core-$VERSION/SHA256SUMS.asc

Checksum check

• Check that the reference checksum in the file SHA256SUMS matches the checksum calculated by you (ignore the "lines are improperly formatted" warning)

sha256sum --ignore-missing --check SHA256SUMS

Example of expected output:

bitcoin-26.1-aarch64-linux-gnu.tar.gz: OK

Signature check

Bitcoin releases are signed by several individuals, each using its own key. To verify the validity of these signatures, you must first import the corresponding public keys into your GPG key database.

• The next command downloads and imports automatically all signatures from the Bitcoin Core release attestations (Guix) repository

{% code overflow="wrap" %}

curl -s "https://api.github.com/repositories/355107265/contents/builder-keys" | grep download_url | grep -oE "https://[a-zA-Z0-9./-]+" | while read url; do curl -s "$url" | gpg --import; done

{% endcode %}

Expected output:

gpg: key 17565732E08E5E41: 29 signatures not checked due to missing keys
gpg: /home/admin/.gnupg/trustdb.gpg: trustdb created
gpg: key 17565732E08E5E41: public key "Andrew Chow <[email protected]>" imported
gpg: Total number processed: 1
gpg:               imported: 1
gpg: no ultimately trusted keys found
[...]

• Verify that the checksums file is cryptographically signed by the release signing keys. The following command prints signature checks for each of the public keys that signed the checksums

gpg --verify SHA256SUMS.asc

• Check that at least a few signatures show the following text

gpg: Good signature from...
Primary key fingerprint:...

Timestamp check

• The binary checksum file is also timestamped with the Bitcoin blockchain using the OpenTimestamps protocol, proving that the file existed before some point in time. Let's verify this timestamp. On your local computer, download the checksums file and its timestamp proof:
  • Click to download the checksum file
  • Click to download its timestamp proof
• In your browser, open the OpenTimestamps website
• In the "Stamp and verify" section, drop or upload the downloaded SHA256SUMS.ots proof file in the dotted box
• In the next box, drop or upload the SHA256SUMS file
• If the timestamps are verified, you should see the following message. The timestamp proves that the checksums file existed on the release date of the latest Bitcoin Core version

The following screenshot is just an example of one of the versions:

• If you're satisfied with the checksum, signature, and timestamp checks, extract the Bitcoin Core binaries

tar -xzvf bitcoin-$VERSION-aarch64-linux-gnu.tar.gz

Example of expected output ⬇️

bitcoin-27.1/
bitcoin-27.1/README.md
bitcoin-27.1/bin/
bitcoin-27.1/bin/bitcoin-cli
bitcoin-27.1/bin/bitcoin-qt
bitcoin-27.1/bin/bitcoin-tx
bitcoin-27.1/bin/bitcoin-util
bitcoin-27.1/bin/bitcoin-wallet
bitcoin-27.1/bin/bitcoind
bitcoin-27.1/bin/test_bitcoin
bitcoin-27.1/bitcoin.conf
bitcoin-27.1/include/
bitcoin-27.1/include/bitcoinconsensus.h
bitcoin-27.1/lib/
bitcoin-27.1/lib/libbitcoinconsensus.so
bitcoin-27.1/lib/libbitcoinconsensus.so.0
bitcoin-27.1/lib/libbitcoinconsensus.so.0.0.0
bitcoin-27.1/share/
bitcoin-27.1/share/man/
bitcoin-27.1/share/man/man1/
bitcoin-27.1/share/man/man1/bitcoin-cli.1
bitcoin-27.1/share/man/man1/bitcoin-qt.1
bitcoin-27.1/share/man/man1/bitcoin-tx.1
bitcoin-27.1/share/man/man1/bitcoin-util.1
bitcoin-27.1/share/man/man1/bitcoin-wallet.1
bitcoin-27.1/share/man/man1/bitcoind.1
bitcoin-27.1/share/rpcauth/
bitcoin-27.1/share/rpcauth/README.md
bitcoin-27.1/share/rpcauth/rpcauth.py

{% hint style="info" %} If you want to generate a full bitcoin.conf file, follow the proper extra section, and then come back to continue with the next section

If you want to install the manual page for bitcoin-cli, follow the manual page for the bitcoin-cli extra section, and then come back to continue with the next section {% endhint %}

Binaries installation

• Install it

sudo install -m 0755 -o root -g root -t /usr/local/bin bitcoin-$VERSION/bin/bitcoin-cli bitcoin-$VERSION/bin/bitcoind

• Check the correct installation requesting the output of the version

bitcoind --version

The following output is just an example of one of the versions:

Bitcoin Core version v24.1.0
Copyright (C) 2009-2022 The Bitcoin Core developers
[...]

• (Optional) Delete installation files of the tmp folder to be ready for the next installation

{% code overflow="wrap" %}

sudo rm -r bitcoin-$VERSION bitcoin-$VERSION-aarch64-linux-gnu.tar.gz SHA256SUMS SHA256SUMS.asc

{% endcode %}

Create the bitcoin user & group

The Bitcoin Core application will run in the background as a daemon and use the separate user “bitcoin” for security reasons. This user does not have admin rights and cannot change the system configuration.

• Create the bitcoin user and group

sudo adduser --gecos "" --disabled-password bitcoin

Example of expected output:

Adding user `bitcoin' ...
Adding new group `bitcoin' (1004) ...
Adding new user `bitcoin' (1004) with group `bitcoin(1004)' ...
Creating home directory `/home/bitcoin' ...
Copying files from `/etc/skel' ...
Adding new user `bitcoin' to supplemental / extra groups `users' ...
Adding user `bitcoin' to group `users' ...

• Add the user admin to the group "bitcoin" as well

sudo adduser admin bitcoin

Expected output:

Adding user `admin' to group `bitcoin' ...
Done.

• Allow the user bitcoin to use the control port and configure Tor directly by adding it to the "debian-tor" group

sudo adduser bitcoin debian-tor

Expected output:

Adding user `bitcoin' to group `debian-tor' ...
Done.

Create data folder

Bitcoin Core uses by default the folder .bitcoin in the user's home. Instead of creating this directory, we create a data directory in the general data location /data and link to it.

• Create the Bitcoin data folder

sudo mkdir /data/bitcoin

• Assign as the owner to the bitcoin user

sudo chown bitcoin:bitcoin /data/bitcoin

• Switch to the user bitcoin

sudo su - bitcoin

• Create the symbolic link .bitcoin that points to that directory

ln -s /data/bitcoin /home/bitcoin/.bitcoin

• Check the symbolic link has been created correctly

ls -la .bitcoin

Expected output:

lrwxrwxrwx 1 bitcoin bitcoin   13 Nov  7 19:32 .bitcoin -> /data/bitcoin

Generate access credentials

For other programs to query Bitcoin Core they need the proper access credentials. To avoid storing the username and password in a configuration file in plaintext, the password is hashed. This allows Bitcoin Core to accept a password, hash it, and compare it to the stored hash, while it is not possible to retrieve the original password.

Another option to get access credentials is through the .cookie file in the Bitcoin data directory. This is created automatically and can be read by all users who are members of the "bitcoin" group.

Bitcoin Core provides a simple Python program to generate the configuration line for the config file.

• Enter to the bitcoin folder

cd .bitcoin

• Download the RPCAuth program

{% code overflow="wrap" %}

wget https://raw.githubusercontent.com/bitcoin/bitcoin/master/share/rpcauth/rpcauth.py

{% endcode %}

• Run the script with the Python3 interpreter, providing the username (ramix) and your "password [B]" arguments

{% hint style="warning" %} All commands entered are stored in the bash history. But we don't want the password to be stored where anyone can find it. For this, put a space ( ) in front of the command shown below {% endhint %}

 python3 rpcauth.py ramix YourPasswordB

Example of expected output:

String to be appended to bitcoin.conf:
rpcauth=ramix:00d8682ce66c9ef3dd9d0c0a6516b10e$c31da4929b3d0e092ba1b2755834889f888445923ac8fd69d8eb73efe0699afa

• Copy the rpcauth line, we'll need to paste it into the Bitcoin config file

Configuration

Now, the configuration file bitcoind needs to be created. We'll also set the proper access permissions.

• Still as the user "bitcoin", creates the bitcoin.conf file

nano /home/bitcoin/.bitcoin/bitcoin.conf

• Enter the complete next configuration. Save and exit

{% hint style="danger" %} Remember to replace the whole line starting with "rpcauth" the connection string you just generated {% endhint %}

{% hint style="warning" %} Remember to accommodate the "dbcache" parameter depending on your hardware. Recommended: dbcache=1/2 x total RAM available, e.g: 4GB RAM -> dbcache=2048 {% endhint %}

{% hint style="info" %} (Optional) Modify the "uacomment" value to your preference if you want {% endhint %}

# RaMiX: bitcoind configuration
# /data/bitcoin/bitcoin.conf

# Bitcoin daemon
server=1
txindex=1

# Append comment to the user agent string
uacomment=RaMiX node

# Disable integrated wallet
disablewallet=1

# Additional logs
debug=tor
debug=i2p

# Assign to the cookie file read permission to the Bitcoin group users
rpccookieperms=group

# Disable debug.log
nodebuglogfile=1

# Avoid assuming that a block and its ancestors are valid,
# and potentially skipping their script verification.
# We will set it to 0, to verify all.
assumevalid=0

# Enable all compact filters
blockfilterindex=1

# Serve compact block filters to peers per BIP 157
peerblockfilters=1

# Maintain coinstats index used by the gettxoutsetinfo RPC
coinstatsindex=1

# Network
listen=1

## P2P bind
bind=127.0.0.1
bind=127.0.0.1=onion

## Proxify clearnet outbound connections using Tor SOCKS5 proxy
proxy=unix:/run/tor/socks

## I2P SAM proxy to reach I2P peers and accept I2P connections
i2psam=127.0.0.1:7656

# Connections
rpcauth=<replace with your own auth line generated in the previous step>

# Initial block download optimizations
dbcache=2048
blocksonly=1

{% hint style="info" %} (Optional) If you checked on the Check IPv6 availability section and you don't have IPv6 available, you can discard cjdns of the Bitcoin Core by adding the next lines at the end of the configuration file:

# Disable cjdns network
onlynet=onion
onlynet=i2p
onlynet=ipv4
onlynet=ipv6

-> This is a standard configuration. Check this Bitcoin Core sample bitcoind.conf file with all possible options or generate one yourself following the proper extra section {% endhint %}

• Set permissions for only the user bitcoin and members of the bitcoin group can read it (needed for LND to read the "rpcauth" line)

chmod 640 /home/bitcoin/.bitcoin/bitcoin.conf

• Exit the bitcoin user session to back to the user admin

{% code fullWidth="false" %}

exit

{% endcode %}

Create systemd service

The system needs to run the bitcoin daemon automatically in the background. We use systemd, a daemon that controls the startup process using configuration files

• Create the systemd configuration

sudo nano /etc/systemd/system/bitcoind.service

• Enter the complete next configuration. Save and exit

# RaMiX: systemd unit for bitcoind
# /etc/systemd/system/bitcoind.service

[Unit]
Description=Bitcoin Core Daemon
Requires=network-online.target
After=network-online.target

[Service]
ExecStart=/usr/local/bin/bitcoind -pid=/run/bitcoind/bitcoind.pid \
                                  -conf=/home/bitcoin/.bitcoin/bitcoin.conf \
                                  -datadir=/home/bitcoin/.bitcoin \
                                  -startupnotify='systemd-notify --ready' \
                                  -shutdownnotify='systemd-notify --status="Stopping"'
# Process management
####################
Type=notify
NotifyAccess=all
PIDFile=/run/bitcoind/bitcoind.pid

Restart=on-failure
TimeoutStartSec=infinity
TimeoutStopSec=600

# Directory creation and permissions
####################################
User=bitcoin
Group=bitcoin
RuntimeDirectory=bitcoind
RuntimeDirectoryMode=0710
UMask=0027

# Hardening measures
####################
PrivateTmp=true
ProtectSystem=full
NoNewPrivileges=true
PrivateDevices=true
MemoryDenyWriteExecute=true
SystemCallArchitectures=native

[Install]
WantedBy=multi-user.target

• Enable autoboot (optional)

sudo systemctl enable bitcoind

• Prepare “bitcoind” monitoring by the systemd journal and check the logging output. You can exit monitoring at any time with Ctrl-C

journalctl -fu bitcoind

{% hint style="info" %} Keep this terminal open, you'll need to come back here on the next step to monitor the logs {% endhint %}

Run

To keep an eye on the software movements, start your SSH program (eg. PuTTY) a second time, connect to the RaMiX node, and log in as admin

• Start the service

sudo systemctl start bitcoind

Example of expected output on the first terminal with journalctl -fu bitcoind ⬇️

2022-11-24T18:08:04Z Bitcoin Core version v24.0.1.0 (release build)
2022-11-24T18:08:04Z InitParameterInteraction: parameter interaction: -proxy set -> setting -upnp=0
2022-11-24T18:08:04Z InitParameterInteraction: parameter interaction: -proxy set -> setting -natpmp=0
2022-11-24T18:08:04Z InitParameterInteraction: parameter interaction: -proxy set -> setting -discover=0
2022-11-24T18:08:04Z Using the 'sse4(1way),sse41(4way),avx2(8way)' SHA256 implementation
2022-11-24T18:08:04Z Using RdRand as an additional entropy source
2022-11-24T18:08:04Z Default data directory /home/bitcoin/.bitcoin
2022-11-24T18:08:04Z Using data directory /home/bitcoin/.bitcoin
2022-11-24T18:08:04Z Config file: /home/bitcoin/.bitcoin/bitcoin.conf
2022-11-24T18:08:04Z Config file arg: blockfilterindex="1"
2022-11-24T18:08:04Z Config file arg: coinstatsindex="1"
2022-11-24T18:08:04Z Config file arg: i2pacceptincoming="1"
2022-11-24T18:08:04Z Config file arg: i2psam="127.0.0.1:7656"
2022-11-24T18:08:04Z Config file arg: listen="1"
2022-11-24T18:08:04Z Config file arg: listenonion="1"
2022-11-24T18:08:04Z Config file arg: peerblockfilters="1"
2022-11-24T18:08:04Z Config file arg: peerbloomfilters="1"
2022-11-24T18:08:04Z Config file arg: proxy="127.0.0.1:9050"
2022-11-24T18:08:04Z Config file arg: rpcauth=****
2022-11-24T18:08:04Z Config file arg: server="1"
2022-11-24T18:08:04Z Config file arg: txindex="1"
[...]
> 2022-11-24T18:09:04Z Synchronizing blockheaders, height: 4000 (~0.56%)
[...]

{% hint style="info" %} Monitor the log file for a few minutes to see if it works. Logs like the next, indicate that the initial start-up process has been successful:

New block-relay-only v1 peer connected: version: 70016, blocks=2948133, peer=68
[..]
Synchronizing blockheaders, height: 4000 (~0.56%)
[..]
UpdateTip: new best=000000000f8d29fcf9ac45e443706c6f21a6e9cfa615f94794b726d3ba8bdc88 height=2948135 version=0x20000000 log2_work=75.951200 tx=215155316 date='2024-09-18T16:25:12Z' progress=1.000000 cache=20.9MiB(142005txo)
[..]

{% endhint %}

• Link the Bitcoin data directory from the admin user's home directory as well. This allows admin user to work with bitcoind directly, for example, by using the command bitcoin-cli

ln -s /data/bitcoin /home/admin/.bitcoin

• This symbolic link becomes active only in a new user session. Log out from SSH by entering the next command

exit

• Log in again as a user admin opening a new SSH session
• Check symbolic link have been created correctly

ls -la .bitcoin

Expected output:

lrwxrwxrwx 1 admin admin    13 Nov  7 10:41 .bitcoin -> /data/bitcoin

{% hint style="warning" %} Troubleshooting note:

If you don't obtain the before-expected output (.bitcoin -> /data/bitcoin¹) and you only have (.bitcoin), you must follow the next steps to fix that:

1. Delete the failed created symbolic link

sudo rm -r .bitcoin

2. Try to create the symbolic link again

ln -s /data/bitcoin /home/admin/.bitcoin

3. Check the symbolic link has been created correctly this time and you now have the expected output: .bitcoin -> /data/bitcoin²

ls -la .bitcoin

Expected output:

lrwxrwxrwx 1 admin admin    13 Nov  7 10:41 .bitcoin -> /data/bitcoin

{% endhint %}

• Wait a few minutes until Bitcoin Core starts, and enter the next command to obtain your Tor and I2P addresses. Take note of them, later you might need it

{% code overflow="wrap" %}

bitcoin-cli getnetworkinfo | grep address.*onion && bitcoin-cli getnetworkinfo | grep address.*i2p

{% endcode %}

Example of expected output:

"address": "vctk9tie5srguvz262xpyukkd7g4z2xxxy5xx5ccyg4f12fzop8hoiad.onion",
"address": "sesehks6xyh31nyjldpyeckk3ttpanivqhrzhsoracwqjxtk3apgq.b32.i2p",

Validation

• Check the correct enablement of the I2P and Tor networks

bitcoin-cli -netinfo

Example of expected output:

Bitcoin Core client v24.0.1 - server 70016/Satoshi:24.0.1/
          ipv4    ipv6   onion   i2p   total   block
in          0       0      25     2      27
out         7       0       2     1      10       2
total       7       0      27     3      37

Local addresses
xdtk6tie4srguvz566xpyukkd7m3z3vbby5xx5ccyg5f64fzop7hoiab.onion     port   8333    score      4
etehks3xyh55nyjldjdeckk3nwpanivqhrzhsoracwqjxtk8apgk.b32.i2p       port      0    score      4

• Ensure bitcoind is listening on the default RPC & P2P ports

sudo ss -tulpn | grep bitcoind

Expected output:

tcp   LISTEN 0      128        127.0.0.1:8332       0.0.0.0:*    users:(("bitcoind",pid=773834,fd=11))
tcp   LISTEN 0      4096       127.0.0.1:8333       0.0.0.0:*    users:(("bitcoind",pid=773834,fd=46))
tcp   LISTEN 0      4096       127.0.0.1:8334       0.0.0.0:*    users:(("bitcoind",pid=773834,fd=44))
tcp   LISTEN 0      128            [::1]:8332          [::]:*    users:(("bitcoind",pid=773834,fd=10))

• Please note:
  • When “bitcoind” is still starting, you may get an error message like “verifying blocks”. That’s normal, just give it a few minutes.
  • Among other info, the “verificationprogress” is shown. Once this value reaches almost 1 or near (0.999…), the blockchain is up-to-date and fully validated.

Bitcoin Core is syncing

{% hint style="info" %} This process is called IBD (Initial Block Download). This can take between one day and a week, depending mostly on your PC performance. It's best to wait until the synchronization is complete before going ahead {% endhint %}

Explore bitcoin-cli

If everything is running smoothly, this is the perfect time to familiarize yourself with Bitcoin, the technical aspects of Bitcoin Core, and play around with bitcoin-cli until the blockchain is up-to-date.

• The Little Bitcoin Book is a fantastic introduction to Bitcoin, focusing on the "why" and less on the "how"

• Mastering Bitcoin by Andreas Antonopoulos is a great point to start, especially chapter 3 (ignore the first part how to compile from source code):

  • You definitely need to have a real copy of this book!
  • Read it online on GitHub
  

• Learning Bitcoin from the Command Line by Christopher Allen gives a thorough deep dive into understanding the technical aspects of Bitcoin

• Also, check out the bitcoin-cli reference

Activate mempool & reduce 'dbcache' after a full sync

Once Bitcoin Core is fully synced, we can reduce the size of the database cache. A bigger cache speeds up the initial block download, now we want to reduce memory consumption to allow the Lightning client and Electrum server to run in parallel. We also now want to enable the node to listen to and relay transactions.

{% hint style="info" %} Bitcoin Core will then just use the default cache size of 450 MiB instead of your setting RAM setup. If blocksonly=1 is left uncommented it will prevent Electrum Server from receiving RPC fee data and will not work {% endhint %}

• As user admin, edit the bitcoin.conf file

sudo nano /home/bitcoin/.bitcoin/bitcoin.conf

• Comment the following lines by adding a # at the beginning. Save and exit

#assumevalid=0
#dbcache=2048
#blocksonly=1

• Restart Bitcoin Core for the settings to take effect

sudo systemctl restart bitcoind

OpenTimestamps client

When we installed Bitcoin Core, we verified the timestamp of the checksum file using the OpenTimestamp website. In the future, you will likely need to verify more timestamps, when installing additional programs (e.g. LND) and when updating existing programs to a newer version. Rather than relying on a third party, it would be preferable (and more fun) to verify the timestamps using your blockchain data. Now that Bitcoin Core is running and synced, we can install the OpenTimestamp client to locally verify the timestamp of the binaries checksums file.

• As user admin, install dependencies

sudo apt install python3-dev python3-pip python3-wheel

• Create a new virtual environment

python3 -m venv myenv

• Activate the virtual environment. You realize that "(myenv)" appear before the prompt

source myenv/bin/activate

• Install the OpenTimestamp client

pip install opentimestamps-client

• Display the OpenTimestamps client version to check that it is properly installed

ots --version

Example of expected output:

v0.7.1

• Deactivate the Python virtual environment

deactivate

{% hint style="info" %} To update the OpenTimestamps client, follow the next steps:

• Activate the Python virtual environment

source myenv/bin/activate

• Update the package in the virtual environment

pip install --upgrade opentimestamps-client

• Check the correct OTS update

ots --version

Example of expected output:

v0.7.1

{% endhint %}

Extras (optional)

Slow device mode

• As user admin edit bitcoin.conf file

sudo nano /home/bitcoin/.bitcoin/bitcoin.conf

• Add these lines at the end of the file

# Slow devices optimizations
## Limit the number of max peer connections
maxconnections=40
## Tries to keep outbound traffic under the given target per 24h
maxuploadtarget=5000
## Increase the number of threads to service RPC calls (default: 4)
rpcthreads=128
## Increase the depth of the work queue to service RPC calls (default: 16)
rpcworkqueue=256

• Comment these lines

#coinstatsindex=1
#assumevalid=0

{% hint style="info" %} Realize that with maxuploadtarget parameter enabled you will need to whitelist the connection to Electrs and Bisq by adding these parameters to bitcoin.conf:

For Electrs:

[email protected]

For Bisq:

[email protected]/16

{% endhint %}

Renovate your Bitcoin Core Tor and I2P addresses

• With user admin, stop bitcoind and dependencies

sudo systemctl stop bitcoind

• Delete

sudo rm /data/bitcoin/onion_v3_private_key && /data/bitcoin/i2p_private_key

• Start bitcoind again

sudo systemctl start bitcoind

• If you want to monitor the bitcoind logs and the starting progress, type journalctl -fu bitcoind in a separate SSH session
• Wait a minute to identify your newly generated addresses with

{% code overflow="wrap" %}

bitcoin-cli getnetworkinfo | grep address.*onion && bitcoin-cli getnetworkinfo | grep address.*i2p

{% endcode %}

Example of expected output:

"address": "vctk9tie5srguvz262xpyukkd7g4z2xxxy5xx5ccyg4f12fzop8hoiad.onion",
"address": "sesehks6xyh31nyjldpyeckk3ttpanivqhrzhsoracwqjxtk3apgq.b32.i2p",

The manual page for bitcoin-cli

• For convenience, it might be useful to have the manual page for bitcoin-cli in the same machine so that they can be consulted offline, they can be installed from the directory

{% hint style="info" %} If you followed the Ordisrespector bonus guide this section is not needed because man pages are installed by default, type directly man bitcoin-cli command to see the man pages {% endhint %}

cd bitcoin-$VERSION/share/man/man1

gzip *

sudo cp * /usr/share/man/man1/

• Now you can read the docs doing

man bitcoin-cli

{% hint style="info" %} Now come back to the section Binaries installation to continue with the Bitcoin Core installation process, not if you followed the Ordisrespector bonus guide {% endhint %}

Generate a full bitcoin.conf example file

{% hint style="success" %} This extra section is valid if you compiled it from the source code using the Ordisrespector bonus guide {% endhint %}

• Follow the complete Installation progress before or the Ordisrespector installation progress to install the bitcoind binary on the OS
• With user admin, go to the temporary folder

cd /tmp

• Clone the source code from GitHub

git clone https://github.com/bitcoin/bitcoin.git

• Copy-paste the bitcoind binary file existing on your OS to the source code folder

cp /usr/local/bin/bitcoind /tmp/bitcoin/src/

• Go to the devtools folder

cd bitcoin/contrib/devtools

• Exec the gen-bitcoin-conf script to generate the file

sudo ./gen-bitcoin-conf.sh

Expected output:

Generating example bitcoin.conf file in share/examples/

• Use cat to print it on the terminal to enable a copy-paste

cat /tmp/bitcoin/share/examples/bitcoin.conf

• Or nano to examine the content

nano /tmp/bitcoin/share/examples/bitcoin.conf

(Optional) Delete the bitcoin folder from the temporary folder

sudo rm -r /tmp/bitcoin

Upgrade

The latest release can be found on the GitHub page of the Bitcoin Core project. Always read the RELEASE NOTES first! When upgrading, there might be breaking changes or changes in the data structure that need special attention. Replace the environment variable "VERSION=x.xx" value for the latest version if it has not been already changed in this guide.

• Login as admin user and change to the temporary directory

cd /tmp

• Set a temporary version environment variable to the installation

VERSION=28.1

• Download binary, checksum, signature files, and timestamp file

{% code overflow="wrap" %}

wget https://bitcoincore.org/bin/bitcoin-core-$VERSION/bitcoin-$VERSION-aarch64-linux-gnu.tar.gz

{% endcode %}

{% code overflow="wrap" %}

wget https://bitcoincore.org/bin/bitcoin-core-$VERSION/SHA256SUMS

{% endcode %}

{% code overflow="wrap" %}

wget https://bitcoincore.org/bin/bitcoin-core-$VERSION/SHA256SUMS.asc

{% endcode %}

{% code overflow="wrap" %}

wget https://bitcoincore.org/bin/bitcoin-core-$VERSION/SHA256SUMS.ots

{% endcode %}

• Verify the new version against its checksums

sha256sum --ignore-missing --check SHA256SUMS

Example of expected output:

bitcoin-25.1-aarch64-linux-gnu.tar.gz: OK

• The next command downloads and automatically imports all signatures from the Bitcoin Core release attestations (Guix) repository

{% code overflow="wrap" %}

curl -s "https://api.github.com/repositories/355107265/contents/builder-keys" | grep download_url | grep -oE "https://[a-zA-Z0-9./-]+" | while read url; do curl -s "$url" | gpg --import; done

{% endcode %}

Expected output:

gpg: key 17565732E08E5E41: 29 signatures not checked due to missing keys
gpg: /home/admin/.gnupg/trustdb.gpg: trustdb created
gpg: key 17565732E08E5E41: public key "Andrew Chow <[email protected]>" imported
gpg: Total number processed: 1
gpg:               imported: 1
gpg: no ultimately trusted keys found
[...]

• Verify the checksums file is cryptographically signed using the release signing keys. The following command prints signature checks for each of the public keys that signed the checksums

gpg --verify SHA256SUMS.asc

• Check that at least a few signatures show the following text

gpg: Good signature from ...
Primary key fingerprint: ...

• Activate the Python virtual environment

source myenv/bin/activate

• If you completed the IBD (Initial Block Download), now you can verify the timestamp with your node

ots --no-cache verify SHA256SUMS.ots -f SHA256SUMS

{% hint style="info" %} The following output is just an example of one of the versions:

Got 1 attestation(s) from https://btc.calendar.catallaxy.com
Got 1 attestation(s) from https://finney.calendar.eternitywall.com
Got 1 attestation(s) from https://bob.btc.calendar.opentimestamps.org
Got 1 attestation(s) from https://alice.btc.calendar.opentimestamps.org
Success! Bitcoin block 766964 attests existence as of 2022-12-11 UTC

-> If the prompt shows you -bash: ots: command not found, ensure that you are installing the OTS client correctly in the proper section

-> If you obtain this output:

Calendar https://btc.calendar.catallaxy.com: Pending confirmation in Bitcoin blockchain
Calendar https://finney.calendar.eternitywall.com: Pending confirmation in Bitcoin blockchain
Calendar https://bob.btc.calendar.opentimestamps.org: Pending confirmation in Bitcoin blockchain
Calendar https://alice.btc.calendar.opentimestamps.org: Pending confirmation in Bitcoin blockchain

-> This means that the timestamp is pending confirmation on the Bitcoin blockchain. You can skip this step or wait a few hours/days to perform this verification. It is safe to skip this verification step if you followed the previous ones and continue to the next ones {% endhint %}

• Now, just check that the timestamp date is close to the release date of the version you're installing
• Deactivate the Python virtual environment

deactivate

• If you're satisfied with the checksum, signature, and timestamp checks, extract the Bitcoin Core binaries

tar -xzvf bitcoin-$VERSION-aarch64-linux-gnu.tar.gz

• Install them

{% code overflow="wrap" %}

sudo install -m 0755 -o root -g root -t /usr/local/bin bitcoin-$VERSION/bin/bitcoin-cli bitcoin-$VERSION/bin/bitcoind

{% endcode %}

• Check the new version

bitcoin-cli --version

The following output is just an example of one of the versions:

Bitcoin Core RPC client version v26.0.0
Copyright (C) 2009-2022 The Bitcoin Core developers
[...]

• (Optional) Delete installation files of the /tmp folder to be ready for the next upgrade

{% code overflow="wrap" %}

sudo rm -r bitcoin-$VERSION && sudo rm bitcoin-$VERSION-aarch64-linux-gnu.tar.gz && sudo rm SHA256SUMS && sudo rm SHA256SUMS.asc && sudo rm SHA256SUMS.ots

{% endcode %}

• Restart the Bitcoin Core to apply the new version

sudo systemctl restart bitcoind

Uninstall

Uninstall service

• Ensure you are logged in with the user admin, stop bitcoind

sudo systemctl stop bitcoind

• Disable autoboot (if enabled)

sudo systemctl disable bitcoind

• Delete the service

sudo rm /etc/systemd/system/bitcoind.service

Delete user & group

• Delete bitcoin user's group

{% code overflow="wrap" %}

sudo gpasswd -d admin bitcoin; sudo gpasswd -d fulcrum bitcoin; sudo gpasswd -d lnd bitcoin; sudo gpasswd -d btcrpcexplorer bitcoin; sudo gpasswd -d btcpay bitcoin

{% endcode %}

• Delete the bitcoin user. Don't worry about userdel: bitcoin mail spool (/var/mail/bitcoin) not found output, the uninstall has been successful

sudo userdel -rf bitcoin

• Delete the bitcoin group

sudo groupdel bitcoin

Detele data directory

• Delete the complete bitcoindirectory

sudo rm -rf /data/bitcoin/

Uninstall binaries

• Delete the binaries installed

sudo rm /usr/local/bin/bitcoin-cli && sudo rm /usr/local/bin/bitcoind

Uninstall FW configuration

If you followed the Bisq bonus guide, you needed to add an allow rule on UFW to allow the incoming connection to the 8333 port (P2P)

• Ensure you are logged in with the user admin, display the UFW firewall rules, and note the numbers of the rules for Bitcoin Core (e.g. "Y" below)

sudo ufw status numbered

Expected output:

[Y] 8333       ALLOW IN    Anywhere            # allow Bitcoin Core from anywhere

{% hint style="info" %} If you don't have any rule matched with this, you don't have to do anything, you are OK {% endhint %}

• Delete the rule with the correct number and confirm with "yes"

sudo ufw delete X

Port reference

Port	Protocol	Use
8333	TCP	Default P2P port
8332	TCP	Default RPC port
8334	TCP	Default P2P Tor port

Footnotes

1. Symbolic link ↩

2. Symbolic link ↩