Bitcoin How-to: Use ElectrumX Personal Server in Whonix
Higher Security and Privacy through using a Self-Hosted, Fully Validating Bitcoin Node (ElectrumX + Bitcoin Core)
Introduction[edit]
Using electrum with its default, public servers (which are hosted by third parties) has various security and privacy disadvantages mentioned in electrum chapter warnings. These issues can be resolved by using one's own, self-hosted, local electrum server. ElectrumX is a electrum server, which is documented on this wiki page. Under the assumption of a non-compromised system, the advantages include:
- No third party can correlate all of the user's Bitcoin addresses to the same pseudonym simply by starting the electrum Bitcoin wallet. However, this does not change recommendation regarding Coin Control. When spending Bitcoin using multiple inputs, correlation will still happen on the blockchain level.
- No third party can log how many times or the times when a user is viewing their Bitcoin addresses, transactions in their electrum Bitcoin wallet.
- A self-hosted ElectrumX will always truthfully report unconfirmed and confirmed transactions. However, the usual recommendation to wait for a number of confirmations on the blockchain remains unchanged.
- Confirmed transactions are fully verified, not only via SPV.
- Bitcoin network fee estimates are no longer dependent on third parties.
ElectrumX is developed by the same developers as electrum. Both are developed under the github organization spesmilo
.
These instructions should be compatible with Non-Qubes-Whonix™, Qubes-Whonix™ and Kicksecure™.
ElectrumX depends on Bitcoin Core to download the Bitcoin blockchain. In other words, Bitcoin Core is a dependency of ElectrumX. If Bitcoin Core could have been avoided in this setup, it would have been avoided for simplicity.
By design:
- Only Bitcoin Core will be able to establish outgoing internet connections. Only Bitcoin Core will be configured to be able to reach the Bitcoin network over Tor.
- The connection scheme is
electrum
→ElectrumX
→Bitcoin Core
→Tor
→Bitcoin network
. - Both ElextrumX and electrum will be unable to connect to the internet thanks to disabling Whonix transparent proxying feature as documented below.
- It should be expected that the proxy settings for electrum remain unchanged. That is normal and as indented. (If electrum was configured to use Tor that would actually disable the fail-safe and violate the goal of these instructions to have a fail-safe preventing electrum from connecting to third-party servers and the connection chain being
electrum
→ElectrumX
→Bitcoin Core
.) - electrum connects to ElextrumX on localhost (
127.0.0.1
). - ElextrumX connects to Bitcoin Core on localhost (
127.0.0.1
).
Inappropriate Use of Root Rights should be avoided. Instructions on this wiki page have been carefully crafted with when to use and when not to use sudo
in mind. The user should not use sudo
unless instructed in documentation. [1]
Warnings[edit]
Installation[edit]
Isolating Proxy Setup[edit]
Optional but recommended for better privacy.
Make sure the electrum is prohibited from accidentally connecting to electrum public servers and effectively only permitted to connect to ElectrumX.
1. Acquire prerequisite knowledge.
2. Do not configure electrum for use with stream isolation.
As documented on the the electrum wiki page since this would nullify, circumvent the advantage of disabling transparent proxying.
3. Disable transparent proxying.
Note: The following step should be applied in Whonix-Gateway (Qubes-Whonix: In App Qubes sys-whonix
):
Disable Transparent Proxying.
electrum Safeguard[edit]
Remove the default electrum start menu entry.
Optional but highly recommended for better privacy.
Make sure the electrum default start menu entry (which would result in using electrum public servers) gets deleted and stays deleted even after electrum package upgrades to make sure to not accidentally start the electrum using its default start menu entry.
1. dpkg-divert legacy undo command (for existing users)
Note: The following command should be applied in Whonix-Workstation™ (Qubes-Whonix: In Template whonix-workstation-17
).
sudo dpkg-divert --remove /usr/share/electrum-invalid
2. dpkg-divert
Note: The following command should be applied in Whonix-Workstation (Qubes-Whonix: In Template whonix-workstation-17
).
sudo dpkg-divert --local --divert /usr/bin/electrum-invalid --rename --add /usr/share/applications/electrum.desktop
Package Dependency Installation[edit]
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: In Template whonix-workstation-17
).
Install dependencies from the Debian repository. [2]
Install package(s) git python3-aiohttp python3-plyvel electrum
following these instructions
1 Platform specific notice.
- Non-Qubes-Whonix: No special notice.
- Qubes-Whonix: In Template.
2 Update the package lists and upgrade the system .
sudo apt update && sudo apt full-upgrade
3 Install the git python3-aiohttp python3-plyvel electrum
package(s).
Using apt
command line
--no-install-recommends
option
is in most cases optional.
sudo apt install --no-install-recommends git python3-aiohttp python3-plyvel electrum
4 Platform specific notice.
- Non-Qubes-Whonix: No special notice.
- Qubes-Whonix: Shut down Template and restart App Qubes based on it as per Qubes Template Modification .
5 Done.
The procedure of installing package(s) git python3-aiohttp python3-plyvel electrum
is complete.
Software Dependency Installation[edit]
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
1. Install the Install PyLRU. [3]
2. Install Bitcoin Core.
Source Code Download and Digital Software Signature Verification[edit]
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
1. Open a terminal.
If you are using Qubes-Whonix™, complete the following steps.
Qubes App Launcher (blue/grey "Q")
→ Whonix-Workstation™ App Qube (commonly named anon-whonix)
→ Xfce Terminal
If you are using a graphical Whonix with Xfce, run.
Start Menu
→ Xfce Terminal
2. Acquire the OpenPGP public key of ElectrumX developer SomberNight. [4]
- Digital signatures are a tool enhancing download security. They are commonly used across the internet and nothing special to worry about.
- Optional, not required: Digital signatures are optional and not mandatory for using Whonix, but an extra security measure for advanced users. If you've never used them before, it might be overwhelming to look into them at this stage. Just ignore them for now.
- Learn more: Curious? If you are interested in becoming more familiar with advanced computer security concepts, you can learn more about digital signatures here digital software signatures.
Securely download the signing key.
scurl-download https://raw.githubusercontent.com/spesmilo/electrum/master/pubkeys/sombernight.asc
Display the key's fingerprint.
gpg --keyid-format long --import --import-options show-only --with-fingerprint sombernight.asc
Verify the fingerprint. It should show.
Note: Key fingerprints provided on the Whonix website are for convenience only. The Whonix project does not have the authorization or the resources to function as a certificate authority, and therefore cannot verify the identity or authenticity of key fingerprints. The ultimate responsibility for verifying the authenticity of the key fingerprint and correctness of the verification instructions rests with the user.
In late-2021, the output is identical to the following. Key fingerprint = 4AD6 4339 DFA0 5E20 B3F6 AD51 E7B7 48CD AF5E 5ED9
The most important check is confirming the key fingerprint exactly matches the output above. [5]
Add the signing key.
gpg --import sombernight.asc
3. Download the ElectrumX server source code using git
.
git clone https://github.com/spesmilo/electrumx.git
4. Change directory.
cd electrumx
5. Digital signature verification.
Note: At the time of writing, 1.16.0
was the latest stable release. Before starting the ElectrumX source code download, browse to github.com/spesmilo/electrumx/tags
to verify the version number. Because there are no newer tags, we are using a recent commit (2024-01-05).
git verify-commit 97a016c9ca9d49b3e5b22a66fd6caab537879340
If the file is verified successfully, the output will include Good signature
, which is the most important thing to check.
gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner.
This message does not alter the validity of the signature related to the downloaded key. Rather, this warning refers to the level of trust placed in the Whonix signing key and the web of trust. To remove this warning, the Whonix signing key must be personally signed with your own key.
6. Checkout the git ref.
git checkout --quiet 97a016c9ca9d49b3e5b22a66fd6caab537879340
7. Done.
Download, digital software verification and git checkout of the ElectrumX server source code is complete.
electrumx-autostart-all Script Creation[edit]
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
1. Create folder ~/bin
.
mkdir -p ~/bin
2. Open file ~/bin/electrumx-autostart-all
in a text editor of your choice as a regular, non-root user.
If you are using a graphical environment, run. mousepad ~/bin/electrumx-autostart-all
If you are using a terminal, run. nano ~/bin/electrumx-autostart-all
3. Paste the following contents.
#!/bin/bash set -x set -e true "START: $0" if [ "$(id -u)" = "0" ]; then echo "$0: ERROR: Must not be run as root! Run as user without root/sudo." >&2 exit 112 fi if test -d ~/.bitcoin ; then true "INFO: bitcoin detected." coin=bitcoin electrum_binary=electrum coin_short=BTC elif test -d ~/.litecoin ; then true "INFO: litecoin detected." coin=litecoin coin_short=LTC electrum_binary=~/bin/electrum-ltc else true "ERROR: neither bitcoin nor litecoin was detected! Does folder ~/.bitcoin or ~/.litecoin exist?" exit 1 fi true "INFO: Terminating possibly still running leftover processes $coin Core and $electrum_binary just in case." true "INFO: (Restarting ElectrumX later below.)" true "INFO: If none running, that is OK." killall $coin-qt || true killall $electrum_binary || true true "INFO: Starting $coin Core..." cmd=~/${coin}-*/bin/${coin}-qt terminal_emulator_window_title="$cmd" \ /usr/libexec/helper-scripts/terminal-wrapper \ $cmd #coin_qt_pid=$! true "INFO: Waiting for 20 seconds to give $coin Core time to startup." sleep 20 true "INFO: Restarting ElectrumX..." systemctl --user restart electrumx true "INFO: Done, restarted ElectrumX." true "INFO: Waiting for 20 seconds to give ElectrumX time to startup." sleep 20 true "INFO: Starting ElectrumX journalctl..." cmd="journalctl --boot --user -f -u electrumx" terminal_emulator_window_title="$cmd" \ /usr/libexec/helper-scripts/terminal-wrapper \ $cmd #journalctl_pid=$! true "INFO: Started ElectrumX journalctl." true "INFO: Starting Electrum $coin_short..." cmd="$electrum_binary -v --oneserver --server 127.0.0.1:5000:t" terminal_emulator_window_title="$cmd" \ /usr/libexec/helper-scripts/terminal-wrapper \ $cmd #electrum_pid=$! true "INFO: Started Electrum $coin_short." true "END: $0"
4. Save and exit.
5. Make ~/bin/electrumx-autostart-all
executable.
chmod +x ~/bin/electrumx-autostart-all
6. Done.
electrumx-autostart-all script creation is complete.
Configuration[edit]
Bitcoin-Qt Configuration[edit]
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
1. Create folder ~/.bitcoin
.
Note: It is OK Bitcoin-Qt has been previously used and folder ~/.bitcoin
already exists. Running the following command would be optional, OK and do nothing.
mkdir -p ~/.bitcoin
2. Create the Bitcoin Core configuration file ~/.bitcoin/bitcoin.conf
.
Open file ~/.bitcoin/bitcoin.conf
in a text editor of your choice as a regular, non-root user.
If you are using a graphical environment, run. mousepad ~/.bitcoin/bitcoin.conf
If you are using a terminal, run. nano ~/.bitcoin/bitcoin.conf
3. Paste the following text. [6]
server=1 bind=127.0.0.1 rpcbind=127.0.0.1 rpcallowip=127.0.0.1 txindex=1 prune=0 rpcuser=username rpcpassword=password proxy=10.152.152.10:9111
4. Save.
5. Start Bitcoin-Qt.
Bitcoin-Qt can be started using any method (from command line or start menu entry). Starting normally. [7]
~/bitcoin-*/bin/bitcoin-qt
6. Disable pruning in Bitcoin-Qt.
Bitcoin Core
→ Settings
→ Options
→ unselect Prune block storage to
[8]
7. Disable incoming connections in Bitcoin-Qt.
Bitcoin Core
→ Settings
→ Network
→ unselect Allow incoming connections
8. Proxy Settings
Bitcoin Core
→ Settings
→ Network
→ Connect through SOCKS5 proxy (default proxy):
[10]
- Proxy IP:
10.152.152.10
- Port:
9111
9. Terminate Bitcoin-Qt.
Close terminate Bitcoin-Qt. This is required for the following next step which requires that Bitcoin-Qt is not running.
10. Reindex the blockchain using Bitcoin-Qt.
Bitcoin-Qt needs to be started at least once from the command line with the -reindex
parameter. [11]
~/bitcoin-*/bin/bitcoin-qt -reindex
When Bitcoin-Qt is started next time, there is no more need for -reindex
and it probably should not be used since it takes more time.
11. Wait for the blockchain to be synchronized.
12. Optional for better usability: Add Bitcoin-Qt start menu entry.
13. Optional for better usability: Autostart bitcoin-qt.
Autostarting Bitcoin-Qt after reboot might be desirable so it can catch up downloading the blockchain as well as to serve ElectrumX.
14. Done.
Configuration of Bitcoin-Qt is complete.
ElectrumX Configuration[edit]
ElectrumX Server Configuration[edit]
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
1. Create folder ~/.electrumx
.
mkdir -p ~/.electrumx
2. Open file ~/electrumx.conf
in a text editor of your choice as a regular, non-root user.
If you are using a graphical environment, run. mousepad ~/electrumx.conf
If you are using a terminal, run. nano ~/electrumx.conf
3. Paste the following contents.
The TCP address is used by the Electrum Wallet while the TPC address is used by the ElectrumX daemon and to send commands to the daemon. [12]
COIN=Bitcoin DB_DIRECTORY=/home/user/.electrumx DAEMON_URL=username:password@127.0.0.1 SERVICES=tcp://127.0.0.1:5000,rpc://127.0.0.1:8000 PEER_DISCOVERY=self
4. Save.
5. Done.
Server configuration of ElectrumX has been completed.
ElectrumX User Systemd Unit Configuration[edit]
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
1. Create folder ~/.config/systemd/user
.
mkdir -p ~/.config/systemd/user
2. Create file ~/.config/systemd/user/electrumx.service
.
Open file ~/.config/systemd/user/electrumx.service
in a text editor of your choice as a regular, non-root user.
If you are using a graphical environment, run. mousepad ~/.config/systemd/user/electrumx.service
If you are using a terminal, run. nano ~/.config/systemd/user/electrumx.service
3. Paste the following contents.
[Unit] Description=ElectrumX After=network.target [Service] EnvironmentFile=/home/user/electrumx.conf ExecStart=/home/user/electrumx/electrumx_server ExecStop=/home/user/electrumx/electrumx_rpc -p 8000 stop LimitNOFILE=8192 TimeoutStopSec=30min [Install] WantedBy=default.target
4. Save.
5. Reload systemd user instance.
systemctl --user daemon-reload
6. Optional: Enable autostart for the ElectrumX systemd user instance.
systemctl --user enable electrumx
7. Start ElectrumX systemd user instance.
systemctl --user restart electrumx
8. Done.
Creation and configuration of ElectrumX systemd user unit has been completed.
Electrum Bitcoin Wallet Configuration[edit]
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
Connect only to one server (own server) instead of any third party servers.
electrum --offline setconfig oneserver true
Connect to own local server.
electrum --offline setconfig server 127.0.0.1:5000:t
Avoid auto connecting to third party servers (and avoid electrum first start wizard asking to).
electrum --offline setconfig auto_connect false
Add an electrum Connecting to Local ElectrumX Start Menu Entry[edit]
Creating a electrum
start menu entry which only locally connects to ElectrumX
.
This step is optional.
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
Inside Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
1. Create folder ~/.local/share/applications
.
mkdir -p ~/.local/share/applications
2. Open file ~/.local/share/applications/electrum-connecting-to-local-electrumx.desktop
in a text editor of your choice as a regular, non-root user.
If you are using a graphical environment, run. mousepad ~/.local/share/applications/electrum-connecting-to-local-electrumx.desktop
If you are using a terminal, run. nano ~/.local/share/applications/electrum-connecting-to-local-electrumx.desktop
3. Paste the following contents.
[Desktop Entry] Name=electrum connecting to local ElectrumX Comment=electrum connecting to local ElectrumX Exec=terminal_emulator_window_title="electrum Connecting to Local ElectrumX" /usr/libexec/helper-scripts/terminal-wrapper electrum -v --oneserver --server 127.0.0.1:5000:t Terminal=false Type=Application Icon=money-manager-ex StartupWMClass=bitcoin MimeType=x-scheme-handler/bitcoin; Categories=Finance;
4. Save.
5. Qubes-Whonix: perform platform-specific steps.
In dom0
, refresh Qubes' appmenu: VM settings
→ Applications
→ Refresh Applications
→ Add desktop shortcut
.
6. Done.
The Electrum with ElectrumX
start menu entry available should be available.
Autostart electrum Connecting to Local ElectrumX[edit]
Automatically starting Electrum using local ElectrumX
which only connects to ElectrumX.
This step is optional.
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
Inside Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
1. Apply instructions Add a electrum Start Menu Entry first.
2. Create folder ~/.config/autostart
.
mkdir -p ~/.config/autostart
3. Create a symlink from ~/.local/share/applications/electrum-connecting-to-local-electrumx.desktop
to ~/.config/autostart/electrum-connecting-to-local-electrumx.desktop
.
ln -s ~/.local/share/applications/electrum-connecting-to-local-electrumx.desktop ~/.config/autostart/electrum-connecting-to-local-electrumx.desktop
4. Done.
Electrum with ElectrumX
will be automatically started the next time the VM is started.
Usage[edit]
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
1. Start Bitcoin-Qt using any method (from start menu entry, autostart or manually from the command line).
~/bitcoin-*/bin/bitcoin-qt
2. Check the the blockchain download in Bitcoin-Qt is functional.
3. Run the ElectrumX server using any method (autostart, or manually form the command line).
systemctl --user restart electrumx
4. Check that ElectrumX blockchain processing is functional.
See monitoring.
5. Start the electrum Bitcoin wallet using any method (autostart, or manually form the command line). [14]
electrum -v --oneserver --server 127.0.0.1:5000:t
If electrum shows "not connected" then that could be because Bitcoin Core has not downloaded enough blockchain yet and/or ElectrumX has not caught up with the blockchain yet. In that case, the console output would include:
I/i | interface.[127.0.0.1:5000] | connection established. version: ['ElectrumX 1.16.0', '1.4'] I/i | interface.[127.0.0.1:5000] | disconnecting due to GracefulDisconnect('server tip below max checkpoint')
Upstream bug reports:
- electrum unwanted disconnect from own ElectrumX server [15]
- ElectrumX should accept local RDP connections even if it has not fully caught up with the bitcoin daemon
electrumx-autostart-all usage[edit]
~/bin/electrumx-autostart-all
Monitoring[edit]
Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix
).
Check the status of the ElectrumX systemd user service.
systemctl --no-pager --full --user status electrumx
Follow the log of the ElectrumX systemd user service.
journalctl --boot --user -f -u electrumx
If all is going well, it should be showing output similar to the following.
electrumx_server[7426]: INFO:Prefetcher:new block height 144,270 hash 00000000000002606168ac016368896d79c591bff2b6580db2e398faef7ec093
Store ElectrumX Log to File[edit]
Write log to file electrumx.log
.
journalctl --boot --user -u electrumx > electrumx.log
See Also[edit]
- Money
- Bitcoin
- electrum
- PyLRU (Dependency of ElectrumX.)
- ElectrumX Source Code Repository
- ElectrumX Upstream Documentation
Donations[edit]
After installing the ElectrumX server, please consider making a donation to electrum Bitcoin Wallet / ElextrumX server and Whonix project (Donate) to help keep it running for many years to come.
Donate Bitcoin (BTC) to Whonix.
1EXNNzqV6wmZ51gkVz7RTp9TL323Uw1EBn
Footnotes[edit]
- ↑
The
systemctl --user
must be run as normal, non-root user withoutsudo
because these aresystemd
user units and notsystemd
system units. - ↑ Installation of the electrum Bitcoin Wallet is optional. In advanced setups, the electrum wallet might be running on a different server or in a different VM.
- ↑ Not available from packages.debian.org at time of writing. https:/packages.debian.org/pylru
- ↑
- ↑ Minor changes in the output such as new uids (email addresses) or newer expiration dates are inconsequential.
- ↑
prune=0
is the default for bitcoind but the Bitcoin-Qt GUI has a first start wizard which asks if pruning should be enabled. To avoid that first start wizard and to make sure pruning is disabled, explicitly disable pruning in configuration file.- Quote ElectrumX Upstream Documentation:
You must be running a non-pruning bitcoin daemon with
txindex=1
- ↑
"normally" meaning without
-reindex
. - ↑ 8.0 8.1 Optional since bitcoin-qt options menu says that configuration file overrides bitcoin-qt GUI settings anyhow but better just in case to avoid any potential bugs.
- ↑ Disable incoming connections in Bitcoin-Qt for better security (?) (avoiding code paths handling unsolicited incoming connections). But incoming connections are not accidentally happening inside Whonix-Workstation anyhow. That would require setting up an onion service for Bitcoin Core which is Undocumented. On the other hand, unsolicited incoming connections through an onion service might be desirable for better connectivity, to support the Bitcoin network?
- ↑
This might not be required due to
~/.bitcoin/bitcoin.conf
already above configured withproxy=10.152.152.10:9111
but shouldn't have bad effects anyhow. Not setting this causes user confusion. - ↑
Using
-reindex
is required because Bitcoin Core configuration has been changed, specificallytxindex
has been enabled. (txindex=1
)
Quote ElectrumX Upstream Documentation:You must be running a non-pruning bitcoin daemon with
txindex=1
- ↑ All environment variables are avaiable in the upstream documentation. The TCP port 5000 was chosen per the first contributor discretion. The RPC port 8000 is the default.
- ↑
Based on
~/electrumx/contrib/systemd/electrumx.service
. - ↑
-v
for verbose mode is optional but recommended. - ↑ https://github.com/spesmilo/electrum/issues/7548
We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!