How to Install an Electrum Server using Full Bitcoin Node and ElectrumX

In the event of a contentious hard fork and a possible coin split, user's wealth may be in danger without a proper "replay protection" being implemented. This holds true even more so when a user runs a lightweight wallet such as Electrum.

Electrum's developer Thomas Voegtlin has published a document on how to safely split coins should such event occur.

However, this method relies on 3rd party servers that the wallet connects to. In the Bitcoin world, 3rd parties should not be trusted under any circumstances.

I'll show you how to overcome this limitation by setting up your own Electrum server.

This tutorial is aimed at Mac OS X and Debian-based Linux distributions. It should work with other Linux distros too. Sorry, I don't have a Windows machine.

Before you start, make sure to install a full Bitcoin node first and set at least the following minimum options in bitcoin.conf:

server=1
listen=1
daemon=1
txindex=1
rpcuser=<random username>
rpcpassword=<strong password>

Use random string generator for rpcuser and rpcpassword. The longer, the better.

If you already have bitcoin node installed, you need to reindex the blockchain:

bitcoin-cli stop
bitcoind -reindex

When running Bitcoin-Qt it should be enough to just close and reopen the wallet. It will reindex the chain automatically.

#1 Install LevelDB

A database engine is required to store transaction information. I use leveldb only because I haven't had luck installing RocksDB.

On Mac OS X

Install leveldb using homebrew:

brew install leveldb

On Linux

If you have a Debian-based Linux distribution you can use the following command:

sudo apt-get install python3-leveldb libleveldb-dev

If you don't, then you'll have to figure it out. I haven't had luck installing from source.

#2 Install Python 3

ElectrumX developer decided to use newer Python 3 which isn't installed on many operating systems by default.

Let's install it manually.

on Mac OS X

Install the latest version of Python 3 with homebrew:

brew install python3

on Linux distributions

There are many different options to install Python 3.7 based on your Linux distribution.

Ubuntu (option 1)

Install the latest python 3.9 on Ubuntu:

sudo apt-get update && sudo apt-get install python3.9 python3.9-dev python3-pip

Other Debian-based distro (option 2)

Some Debian-based distributions may already be shipped with the latest Python.

Let's see:

sudo apt-get install python3.9 python3.9-dev python3-pip

In a case of an error try using the following option instead.

From a source (option 3)

If you can't install it from a repository, just compile it from the source code. It should work for most distros.

cd /tmp
wget https://www.python.org/ftp/python/3.10.6/Python-3.10.6.tgz
tar xvf Python-3.10.6.tgz
cd Python-3.10.6
./configure --enable-optimizations
make -j4
sudo make altinstall
python3 --version

Please note that the compilation will take "forever".

However, if your CPU has more than 4 cores, you can speed it up a bit by using make -j8 instead.

Install required Python packages

You will also need to install some Python 3 dependencies for ElectrumX.

Let's first upgrade setuptools:

python3 -m pip install --upgrade pip setuptools wheel

then install some required packages:

python3 -m pip install --upgrade aiohttp pylru leveldb plyvel aiorpcx ecdsa

If the above command gives you an error, try installing it with sudo (try to avoid it as much as possible, though).

#3 Install and set up ElectrumX

Clone the ElectrumX code from a GitHub repository using git:

mkdir ~/source
cd ~/source
git clone https://github.com/mariodian/electrumx-no-shitcoins
cd electrumx-no-shitcoins

Run the installation script (use sudo if it doesn't work):

python3 setup.py install

Next, create a data folder where the blockchain data will be stored:

Synchronizing with a Bitcoin node takes anywhere between 1-5 days depending on your hardware.

If you want to speed up the process a bit, download one of these data files and put it in the ~/.electrumx folder.

#4 Create a self-signed certificate

To allow Electrum wallets to connect to your server over SSL you need to create a self-signed certificate.

Go to the data folder:

cd ~/.electrumx

and generate your key:

openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr

Follow the on-screen information. It will ask for certificate details such as your country and password. You can leave those fields empty.

When done, create a certificate:

openssl x509 -req -days 1825 -in server.csr -signkey server.key -out server.crt

These commands will create 2 files: server.key and server.crt.

When configuring the ElectrumX instance, make sure to add server.key to SSL_KEYFILE and server.crt to SSL_CERTFILE. More on this in the next step.

#5 Launch ElectrumX as service

First, make sure a fully validating Bitcoin node is running:

bitcoin-cli getinfo

It should output information about your node such as block height, open connections etc.

If it doesn't, run the node first.

on OS X

OS X lacks Systemd to manage system services, so we will use UNIX's default svscan instead.

Create a service folder that will hold symlinks to ElectrumX scripts.

mkdir ~/service

Copy daemontools scripts from the GitHub repo to your home directory:

mkdir -p ~/scripts/electrumx
cp -R ~/source/electrumx/contrib/daemontools/ ~/scripts/electrumx

Set up ENV variables within ~/scripts/electrumx/env folder. Each variable is located in a separate file.

Please refer to ElectrumX's documentation or have a look at my settings and change it accordingly.

When finished open the log/run file:

vim ~/scripts/electrumx/log/run

and edit the log path. In my case it is /Users/bitcoin/ElectrumX/logs, yours may be different.

Save the file by pressing ESC and typing :wqa followed by ENTER.

Change the permissions for the file so it can be executed:

chmod +x ~/scripts/electrumx/log/run

Also, change the permission for another file that executes the server:

chmod +x ~/scripts/electrumx/run

Initialize svscan process to monitor electrumx services:

svscan ~/service & disown

Add services to the folder:

cd ~/service
ln -s ~/scripts/electrumx electrumx

They should be immediately recognized by svscan.

Check the last few lines of the log to see whether the service outputs any errors:

tail -F ~/.electrumx/logs/current | tai64nlocal

If it does, check your configuration again. Errors are pretty self-explanatory but if you're stuck, let me know in the comments section below.

ElectrumX is very resource intensive when it comes to open files so it needs a higher limit:

ulimit -n 10000

Check that it worked:

ulimit -a | grep 'open files'

Make sure the limit is set after every restart:

echo "ulimit -n 10000" >> ~/.bash_profile

If the above method doesn't work, try the following:

sudo launchctl limit maxfiles 10000 unlimited

Restart the service for new changes to take effect.

Stop the service:

svc -d ~/service/electrumx

Always wait for the service to be terminated properly by checking with logs.

Start the service again:

svc -u ~/service/electrumx

Above commands will only execute when svscan is already initialized. You can check the service's status with:

svstat ~/service/electrumx

on Linux

Most if not all Debian-based distribution use Systemd by default. Make sure that is the case for your system:

sudo stat /proc/1/exe | grep systemd

If it outputs something like File: '/proc/1/exe' -> '/lib/systemd/systemd' you're good to go.

Open a sudo session and copy a service file from the ElectrumX repo to your Systemd directory:

sudo -s
cp ~/source/electrumx/contrib/systemd/electrumx.service /lib/systemd/system/

Edit the file to match your setup:

vim /lib/systemd/system/electrumx.service

Press i and start editing.

You need to edit at least ExecStart and User variables.

ExecStart=/home/bitcoin/source/electrumx/electrumx_server
User=bitcoin

When you're happy with the changes, hit ESC and type :wqa followed by ENTER.

Create a configuration file for the server:

touch /etc/electrumx.conf
vim /etc/electrumx.conf

and configure it according to your environment.

Please refer to ElectrumX's documentation or have a look at my settings.

Start the service:

systemctl start electrumx

and check the output:

journalctl -u bitcoin -f

If it gives you no errors, enable the service:

systemctl enable electrumx

You can exit the sudo session now:

exit

#6 Set up a Banner file

Say hi to connecting Electrum wallets (via Electrum console) using a banner file.

It may contain any information such as your server version, donation address, contacts and even info on other services you offer. It's purely up to you.

The content of my banner.txt file looks like this:

Welcome to electrum.onthewifi.com, a Taiwanese Bitcoin Electrum node sponsored by freedomnode.com!
Donation address: $DONATION_ADDRESS
Bitcoin Core $DAEMON_VERSION
$VERSION
If you would like to support this server you can donate by clicking
Help -> Donate to server
in your Electrum Client or use $DONATION_ADDRESS directly.
Thank you!
Contact: [email protected]

and is located in the data folder ~/electrumx.

You can save it to any location and let ElectrumX know via BANNER_FILE variable in either env/ folder or /etc/electrumx.conf depending on your operating system.

Don't forget to restart the server after changing any server's settings.

How to Create and Use an Offline Bitcoin Wallet aka Cold Storage with Electrum

If you care about security and don’t feel like buying Trezor, you may want to keep your bitcoins in an offline wallet also known as cold storage. Cold storage is a wallet that isn’t connected to any network thus it’s not vulnerable to online attacks. It can only be accessed

freedomnode.comMario Dian

#7 Accept incoming connections

If you want to help the network and let others connect to your server, you have to open specific TCP ports.

For a default Electrum set up, those ports are 50001 and 50002.

On Linux, this can be easily done via iptables:

sudo iptables -A INPUT -p tcp --dport 50001 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 50002 -j ACCEPT

However, Mac OS X users will need to install some kind of firewall. The built-in one only manages outgoing connections.

There are a few options such as Little Snitch but none of them are free to my knowledge. If you know about one, please let me know.

Also, don't forget to open ports on your router if applicable. There are too many routers to cover them in this tutorial. Sorry.

To test the connection, open your Electrum wallet. Start it with an argument --oneserver for extra privacy.

On Mac OS X the command is:

open -a /Applications/Electrum.app --args --oneserver

On Linux:

electrum --oneserver

Click a green/red dot in the bottom right corner. A server configuration will pop up.

Unclick "Select server automatically" and type in your server's local/remote IP address or a hostname. Click "Use SSL" and confirm.

If you did everything right, your wallet should start synchronizing the chain data immediately. It shouldn't take more than 10 seconds to finish.

Congratulations! You no longer rely on "trusted" 3rd parties. You also made yourself protected from contentious hard forks and coin splits.

My big thank you goes to Mashuri Clark that gave me some useful tips and corrected some steps for the OS X part.