Litecoin How-to: Use ElectrumX Personal Server in Whonix

From Whonix
Jump to navigation Jump to search

Higher Security and Privacy through using a Self-Hosted, Fully Validating Litecoin Node (ElectrumX + Litecoin Core)

Introduction[edit]

Using Electrum-LTC 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-LTC 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 Litecoin addresses to the same pseudonym simply by starting the Electrum-LTC wallet. However, this does not change recommendation regarding Coin Control. When spending Litecoin 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 Litecoin addresses, transactions in their Electrum-LTC 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.
  • Litecoin network fee estimates are no longer dependent on third parties.

These instructions should be compatible with Non-Qubes-Whonix, Qubes-Whonix and Kicksecure.

ElectrumX depends on Litecoin Core to download the Litecoin blockchain. In other words, Litecoin Core is a dependency of ElectrumX. If Litecoin Core could have been avoided in this setup, it would have been avoided for simplicity.

By design:

  • Only Litecoin Core will be able to establish outgoing internet connections. Only Litecoin Core will be configured to be able to reach the Litecoin network over Tor.
  • The connection scheme is Electrum-LTCElectrumXLitecoin CoreTorLitecoin network.
  • Both ElextrumX and Electrum-LTC will be unable to connect to the internet thanks to enabling Whonix transparent proxying feature as documented below.
  • It should be expected that the proxy settings for Electrum-LTC remain unchanged. That is normal and as intended. (If Electrum-LTC 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-LTC from connecting to third-party servers and the connection chain being Electrum-LTCElectrumXLitecoin Core.)
  • Electrum-LTC connects to ElextrumX on localhost (127.0.0.1).
  • ElextrumX connects to Litecoin 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]

Warning: This is for testers-only!

Info COMMUNITY SUPPORT ONLY : THIS WHOLE WIKI PAGE is only supported by the community. Whonix developers are very unlikely to provide free support for this content. See Community Support for further information, including implications and possible alternatives.

warning Security warning: Installing third party software allows the vendor to potentially compromise your system. Proceed at your own risk! See Foreign Sources for further information.

Whonix default admin password is: changeme Documentation in the Whonix wiki provides guidance on installing third-party software from different upstream sources. This is especially useful as upstream often includes generic instructions for various Linux distributions, which may be complex for users to follow. Additionally, documentation Whonix usually has a higher focus on security, digital software signatures verification.

The instructions provided here serve as a "translation layer" from upstream documentation to Whonix, offering assistance in most scenarios. Nevertheless, it's important to acknowledge that upstream software may undergo changes over time. Consequently, the documentation on this wiki might need occasional updates, such as revised signing key fingerprints, to stay current and accurate.

Please note, this is a general wiki template and may not apply to all upstream documentation scenarios.

Users encountering issues, such as connectivity issues, are advised to adhere to the Self Support First Policy and engage in Generic Bug Reproduction. This involves attempting to replicate the issue on Debian bookworm (over Tor), contacting upstream directly if the issue can be reproduced as such problems are likely unspecific to Whonix. In most cases, Whonix is not responsible for, nor capable of resolving, issues stemming from third-party software.

For further information, refer to Introduction, User Expectations - What Documentation Is and What It Is Not.

Should the user encounter bugs related to third-party software, it is advisable to report these issues to the respective upstream projects. Additionally, users are encouraged to share links to upstream bug reports in the Whonix forums and/or make edits to this wiki page. For instance, if there are outdated links or key fingerprints in need of updating, please feel free to make the necessary changes. Contributions aimed at maintaining the currentness and accuracy of information are highly valued. These updates not only improve the quality of the wiki but also serve as a useful resource for other users.

The Whonix wiki is an open platform where everyone is welcome to contribute improvements and edits, with or without an account. Edits to this wiki are subject to moderation, so contributors should not worry about making mistakes. Your edits will be reviewed before being made public, ensuring the integrity and accuracy of the information provided.

Installation[edit]

Isolating Proxy Setup[edit]

Optional but recommended for better privacy.

Make sure the Electrum-LTC is prohibited from accidentally connecting to Electrum-LTC public servers and effectively only permitted to connect to ElectrumX.

1. Acquire prerequisite knowledge.

2. Do not configure Electrum-LTC for use with stream isolation.

As documented on the the Electrum-LTC 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-LTC 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.

Note: The following command should be applied in Whonix-Workstation (Qubes-Whonix: In Template whonix-workstation-17).

sudo dpkg-divert --local --divert /usr/share/applications/electrum.desktop --rename --add /usr/share/electrum-invalid

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-rocksdb python3-aiohttp python3-plyvel.

A. Update the package lists and upgrade the systemarchive.org.

sudo apt update && sudo apt full-upgrade

B. Install the git python3-rocksdb python3-aiohttp python3-plyvel package(s).

Using apt command line parameter --no-install-recommendsarchive.org is in most cases optional.

sudo apt install --no-install-recommends git python3-rocksdb python3-aiohttp python3-plyvel

C. Done.

The procedure of installing package(s) git python3-rocksdb python3-aiohttp python3-plyvel 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 Litecoin Core.

3. Install Electrum-LTC.

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 MenuXfce Terminal

2. Acquire the OpenPGP public key of ElectrumX developer SomberNight. [4]

  • Digital signatures: A tool enhancing download security. Commonly used across the internet.
  • Learn more: Curious? Learn more about digital software signatures.
  • Optional: Digital signatures are optional. If you've never used them before, there might be no need to start now.
  • No worries: New to digital software signatures? It's okay, no need to worry.
  • Not a requirement: Not mandatory for using Whonix, but an extra security measure for advanced users.

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]

warning Warning:

Do not continue if the fingerprint does not match! This risks using infected or erroneous files! The whole point of verification is to confirm file integrity.

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/tagsarchive.org to verify the version number.

git tag --verify 1.16.0

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 tag.

git checkout --quiet 1.16.0

7. Done.

Download, digital software verification and git checkout --quiet of the ElectrumX server source code is complete.

Configuration[edit]

Litecoin-Qt Configuration[edit]

Note: The following instructions should be applied in Whonix-Workstation (Qubes-Whonix: App Qube anon-whonix).

1. Create folder ~/.litecoin.

Note: It is OK Litecoin-Qt has been previously used and folder ~/.litecoin already exists. Running the following command would be optional, OK and do nothing.

mkdir -p ~/.litecoin

2. Create the Litecoin Core configuration file ~/.litecoin/litecoin.conf.

Open file ~/.litecoin/litecoin.conf in a text editor of your choice as a regular, non-root user.

If you are using a graphical environment, run. mousepad ~/.litecoin/litecoin.conf

If you are using a terminal, run. nano ~/.litecoin/litecoin.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 Litecoin-Qt.

Litecoin-Qt can be started using any method (from command line or start menu entry). Starting normally. [7]

~/litecoin-*/bin/litecoin-qt

6. Disable pruning in Litecoin-Qt.

Litecoin CoreSettingsOptionsunselect Prune block storage to [8]

7. Disable incoming connections in Litecoin-Qt.

Optional. [8] [9]

Litecoin CoreSettingsNetworkunselect Allow incoming connections

8. Terminate Litecoin-Qt.

Close terminate Litecoin-Qt. This is required for the following next step which requires that Litecoin-Qt is not running.

9. Reindex the blockchain using Litecoin-Qt.

Litecoin-Qt needs to be started at least once from the command line with the -reindex parameter. [10]

~/litecoin-*/bin/litecoin-qt -reindex

When Litecoin-Qt is started next time, there is no more need for -reindex and it probably should not be used since it takes more time.

10. Wait for the blockchain to be synchronized.

11. Optional for better usability: Add Litecoin-Qt start menu entry.

12. Optional for better usability: Autostart Litecoin-Qt.

Autostarting Litecoin-Qt after reboot might be desirable so it can catch up downloading the blockchain as well as to serve ElectrumX.

13. Done.

Configuration of Litecoin-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.

COIN=Litecoin 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:2401 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

[11]

3. Paste the following contents.

[Unit] Description=ElectrumX After=network.target [Service] EnvironmentFile=/home/user/electrumx.conf ExecStart=/home/user/electrumx/electrumx_server 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-LTC 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.

~/bin/electrum-ltc --offline setconfig oneserver true

Connect to own local server.

~/bin/electrum-ltc --offline setconfig server 127.0.0.1:5000:t

Avoid auto connecting to third party servers (and avoid Electrum-LTC first start wizard asking to).

~/bin/electrum-ltc --offline setconfig auto_connect false

Add a Electrum-LTC using Local ElectrumX Start Menu Entry[edit]

Creating a Electrum-LTC start menu entry 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. Create folder ~/.local/share/applications.

mkdir -p ~/.local/share/applications

2. Open file ~/.local/share/applications/electrum-ltc-with-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-ltc-with-electrumx.desktop

If you are using a terminal, run. nano ~/.local/share/applications/electrum-ltc-with-electrumx.desktop

3. Paste the following contents.

[Desktop Entry] Name=Electrum-LTC with ElectrumX Comment=electrum-ltc-with-electrumx Exec=bash -c '~/bin/electrum-ltc -v --oneserver --server 127.0.0.1:5000:t' Terminal=false Type=Application Icon=money-manager-ex StartupWMClass=litecoin MimeType=x-scheme-handler/litecoin; Categories=Finance;

4. Save.

5. Qubes-Whonix: perform platform-specific steps.

In dom0, refresh Qubes' appmenu: VM settingsApplicationsRefresh ApplicationsAdd desktop shortcut.

6. Done.

The Electrum-LTC with ElectrumX start menu entry available should be available.

Autostart Electrum-LTC using Local ElectrumX[edit]

Automatically starting Electrum-LTC 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-LTC Start Menu Entry first.

2. Create folder ~/.config/autostart.

mkdir -p ~/.config/autostart

3. Create a symlink from ~/.local/share/applications/electrum-ltc-with-electrumx.desktop to ~/.config/autostart/electrum-ltc-with-electrumx.desktop.

ln -s ~/.local/share/applications/electrum-ltc-with-electrumx.desktop ~/.config/autostart/electrum-ltc-with-electrumx.desktop

4. Done.

Electrum-LTC 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 Litecoin-Qt using any method (from start menu entry, autostart or manually from the command line).

~/litecoin-*/bin/litecoin-qt

2. Check the the blockchain download in Litecoin-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-LTC wallet using any method (autostart, or manually form the command line). [12]

~/bin/electrum-ltc -v --oneserver --server 127.0.0.1:5000:t

If Electrum-LTC shows "not connected" then that could be because Litecoin 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:

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

See Also[edit]

Footnotes[edit]

  1. The systemctl --user must be run as normal, non-root user without sudo because these are systemd user units and not systemd system units.
  2. Installation of the Electrum-LTC Wallet is optional. In advanced setups, the Electrum-LTC wallet might be running on a different server or in a different VM.
  3. Not available from packages.debian.org at time of writing. https:/packages.debian.org/pylru
  4. Minor changes in the output such as new uids (email addresses) or newer expiration dates are inconsequential.
    • prune=0 is the default for litecoind but the Litecoin-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 Documentationarchive.org:

      You must be running a non-pruning litecoin daemon with txindex=1

  5. "normally" meaning without -reindex.
  6. 8.0 8.1 Optional since Litecoin-Qt options menu says that configuration file overrides Litecoin-Qt GUI settings anyhow but better just in case to avoid any potential bugs.
  7. Disable incoming connections in Litecoin-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 Litecoin Core which is Undocumented. On the other hand, unsolicited incoming connections through an onion service might be desirable for better connectivity, to support the Litecoin network?
  8. Using -reindex is required because Litecoin Core configuration has been changed, specifically txindexarchive.org has been enabled. (txindex=1)
    Quote ElectrumX Upstream Documentationarchive.org:

    You must be running a non-pruning litecoin daemon with txindex=1

  9. Based on ~/electrumx/contrib/systemd/electrumx.service.
  10. -v for verbose mode is optional but recommended.
  11. https://github.com/spesmilo/electrum/issues/7548archive.org

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!