Bitcoin Node Workshop Build Your Own Bitcoin Node

Electrum Server

In this section we'll install electrs, an Electrum server that allows compatible Bitcoin wallets to connect privately to your own Bitcoin Core node. As with Bitcoin Core, we'll install the various files in accordance with the Filesystem Hierarchy Standard (FHS) discussed earlier.

These are the files and directories we'll be using for electrs:

/etc/electrs/config.toml              Configuration
/etc/systemd/system/electrs.service   System service
/var/lib/electrs                      Database
/usr/local/bin                        Symlink to binary
/usr/local/lib/electrs                Installed electrs versions
/usr/local/src/electrs                Source code

From the Terminal program on a Mac or Linux computer, or PowerShell on Windows, connect to your Bitcoin node:

ssh nelson@bitcoin-node.local

Become superuser.

su -

Install dependencies

apt install clang libclang-dev

Download the electrs source

We'll be compiling electrs from the source code because there are no digitally signed binary releases.

The electrs source code is hosted on GitHub:

https://github.com/romanz/electrs

Change to the /usr/local/src directory:

cd /usr/local/src

Clone the source code from GitHub:

git clone https://github.com/romanz/electrs.git

Change to the source directory:

cd electrs

################################

Verify the electrs release

The electrs source code is released through Git, with each release identified by a signed Git tag.

Before building electrs, we'll verify that the release tag was signed by the project maintainer.

List the available release tags:

git tag

Choose the release you want to build, which is usually the most recent release. At the time of writing this is v0.11.1.

Obtain the maintainer's Git signing key

Recent electrs releases are signed using an SSH signing key rather than an OpenPGP key.

Roman Zeyde publishes the public Git signing key on his X profile.

Visit:

https://x.com/roman_zeyde

Locate the public key beginning with:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...

Copy the entire line to the clipboard.

Create the allowed signers file

Create a directory to store trusted Git signing keys:

mkdir -p ~/.config/git

Create the Git allowed_signers file:

nano ~/.config/git/allowed_signers

Paste the copied key, prefixing it with the principal and namespace so that the line has the following format:

me@romanzey.de namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...

Save the file and exit the editor.

Verify the signing key fingerprint

Display the fingerprint of the downloaded key:

awk '{print $3, $4}' ~/.config/git/allowed_signers | ssh-keygen -lf -

You should see:

256 SHA256:GifMn7F2swVKyn6MewbQHrYCs4i/bPK7gnwxhuPz/YA me@romanzey.de (ED25519)

Compare the fingerprint

Before trusting the signing key, compare its fingerprint with another published source.

Open the electrs releases page:

https://github.com/romanz/electrs/releases

Locate the release you intend to build. GitHub marks verified releases with a Verified badge and displays the fingerprint of the SSH signing key used to create the release.

Confirm that the fingerprint shown by GitHub matches exactly:

SHA256:GifMn7F2swVKyn6MewbQHrYCs4i/bPK7gnwxhuPz/YA

Configure Git

Tell Git where to find your trusted signing keys:

git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers

Verify the release tag

Verify the Git release tag using the release number you selected:

git tag --verify v0.11.1

A successful verification will report a Good "git" signature, for example:

Good "git" signature for me@romanzey.de with ED25519 key SHA256:GifMn7F2swVKyn6MewbQHrYCs4i/bPK7gnwxhuPz/YA

The fingerprint shown should match the fingerprint you verified above.

What have we verified?

At this point you have confirmed that:

  • you obtained the maintainer's published Git signing public key;
  • the fingerprint of that key matches the fingerprint published on the GitHub releases page;
  • the electrs release tag was signed using the private key corresponding to that public key.

This provides reasonable assurance that you are building the source code released by the electrs maintainer.

Note: This verification model differs from Bitcoin Core. Bitcoin Core releases are verified using reproducible builds and signatures from multiple independent maintainers. electrs is primarily maintained by a single developer, so the verification process ultimately relies on the authenticity of that developer's published signing key.

Check out the release

######################################

cd /usr/local/src/electrs
git checkout v0.11.1

You should see output similar to:

HEAD is now at ... Release 0.11.1

Verify that you're on the correct release:

git describe --tags --exact-match

The command should display:

v0.11.1

Build electrs

Compile the electrs executable:

cargo build --release

The build can take several minutes and may appear to pause at times. This is normal.

The compiled executable will be located at:

target/release/electrs

Install the executable

As with Bitcoin Core, we'll install the executable under /usr/local/lib.

Create the installation directory:

mkdir -p /usr/local/lib/electrs/electrs-0.11.1

Copy the executable:

cp target/release/electrs \
    /usr/local/lib/electrs/electrs-0.11.1/

Create a symbolic link in /usr/local/bin:

ln -sf \
    /usr/local/lib/electrs/electrs-0.11.1/electrs \
    /usr/local/bin/electrs

Verify the installation:

electrs --version

The command should display the installed version number.

Create an electrs user

Create a dedicated system user for electrs:

useradd \
    --system \
    --home-dir /var/lib/electrs \
    --create-home \
    --shell /usr/sbin/nologin \
    electrs

Create the configuration file

Create the electrs configuration directory:

mkdir -p /etc/electrs

Create the electrs configuration file:

nano /etc/electrs/config.toml

Paste the following into the file:

network = "bitcoin"
daemon_rpc_addr = "127.0.0.1:8332"
daemon_p2p_addr = "127.0.0.1:8333"

electrum_rpc_addr = "0.0.0.0:50001"

db_dir = "/var/lib/electrs"

# Insert rpcauth.py generated password in the line below and uncomment.
# auth = "electrs:generated-password-here"

txid_limit = 100000000
jsonrpc_timeout_secs = 30

Configure RPC authentication

Rather than storing a plain text password in bitcoin.conf, Bitcoin Core uses an rpcauth entry. We'll generate one for the electrs user using the rpcauth.py utility supplied with Bitcoin Core.

Change to the Bitcoin Core installation directory:

cd /usr/local/lib/bitcoin

Change to the installed Bitcoin Core release directory:

cd bitcoin-31.0

Change to the rpcauth directory:

cd share/rpcauth

Generate an RPC authentication entry for the electrs user:

./rpcauth.py electrs

The output will look similar to:

String to be appended to bitcoin.conf:
rpcauth=electrs:49ebf1138ec6119b5899ce086a54b147$9786902ac28b740c577e40bfc8cd84276e2027a941597de76821e46816a51e05

Your password:
uL73VDNEgOcw_c42qBlWv-FkNd_5Aof5MkFgrN-q19A

Copy the entire rpcauth=... line into /etc/bitcoin.conf.

Edit the electrs configuration file:

nano /etc/electrs/config.toml

Uncomment the auth line and replace the example password with the password generated by rpcauth.py, for example:

auth = "electrs:uL73VDNEgOcw_c42qBlWv-FkNd_5Aof5MkFgrN-q19A"

Restart Bitcoin Core so the new RPC authentication settings take effect:

systemctl restart bitcoind

Test the installation

Before starting electrs, ensure that Bitcoin Core has completed the Initial Block Download (IBD). electrs cannot build its database until the blockchain is fully synchronized.

Check the synchronization status:

bitcoin-cli getblockchaininfo

The initialblockdownload field should be:

"initialblockdownload": false

Once the Initial Block Download is complete, start electrs from the command line:

###############################3

Run electrs as the electrs user:

su -s /bin/bash electrs -c "electrs --conf /etc/electrs/config.toml"

If electrs starts successfully, it will begin connecting to Bitcoin Core and building its database.

After confirming that it starts correctly, stop electrs by pressing Ctrl+C.

####################

Create the systemd service

Create the electrs system service:

nano /etc/systemd/system/electrs.service

Paste the following into the file:

[Unit]
Description=electrs Electrum server
After=network-online.target bitcoind.service
Wants=network-online.target

[Service]
User=electrs
Group=electrs
Type=simple
ExecStart=/usr/local/bin/electrs --conf /etc/electrs/config.toml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service

Reload the systemd configuration:

systemctl daemon-reload

Enable the service so it starts automatically at boot:

systemctl enable electrs

Start the service:

systemctl start electrs

Check that the service is running:

systemctl status electrs

View the electrs log:

journalctl -u electrs -f

The first time electrs starts it will build its database from the Bitcoin blockchain. Depending on your hardware, this can take several hours. Once the initial indexing is complete, subsequent startups are much faster.

At this point electrs is installed and running. During its first startup it will build an index of the Bitcoin blockchain. This process can take several hours to complete, after which electrs is ready to service incoming Electrum protocol requests.