Setting up an ElectrumX Server for Dogecoin

Published on 2024-03-21

After setting up my Dogecoin node, I wanted to take it a step further. Running a node is great, but it does not allow us to query balances easily, as it only relies on the UTXO set without any indexing.

Why ElectrumX?

ElectrumX is like a specialized search engine for the blockchain. Instead of downloading the entire chain, light wallets can quickly query an ElectrumX server for just the transactions they care about.

What You’ll Need

I’m running this on the same VPS as my Dogecoin node. Here’s what you need:

A fully synced Dogecoin node (see my previous article)
About 50GB of SSD space for the ElectrumX database
Python 3.8 or newer
At least 4GB RAM (more is better)

Setting Up the Server

First, let’s configure our Dogecoin node to work with ElectrumX. Edit ~/.dogecoin/dogecoin.conf:

server=1
rpcuser=your_username
rpcpassword=your_password
rpcallowip=127.0.0.1
txindex=0  # ElectrumX handles indexing

Now install the dependencies:

sudo apt update
sudo apt install python3-pip python3-venv libleveldb-dev
sudo apt install build-essential pkg-config

Create a Python virtual environment and install ElectrumX:

git clone https://github.com/spesmilo/electrumx.git
python3 -m venv ~/electrumx
source ~/electrumx/bin/activate
cd electrumx
pip install aiohttp
pip install .

Configuration

ElectrumX needs its own config file. Create it:

sudo mkdir /etc/electrumx
sudo nano /etc/electrumx.conf

Here’s my configuration (adjust the values to your setup):

# The basics
COIN=Dogecoin
DB_DIRECTORY=/var/electrumx/db
DAEMON_URL=http://your_username:your_password@localhost:22555/
NET=mainnet

# Performance tweaks
CACHE_MB=2000
MAX_SEND=3000000
MAX_RECV=3000000

# Security (recommended)
SSL_CERTFILE=/etc/electrumx/server.crt
SSL_KEYFILE=/etc/electrumx/server.key

# Logging
LOG_LEVEL=debug
LOG_FILE=/var/electrumx/electrumx.log

# Network services
SERVICES=tcp://:50001,ssl://:50002,rpc://:8000

Create the data directory:

sudo mkdir -p /var/electrumx/db
sudo chown -R $USER:$USER /var/electrumx

SSL Setup

I highly recommend setting up SSL for secure connections:

cd /etc/electrumx
openssl req -newkey rsa:2048 -sha256 -nodes -x509 -days 1825 \
    -keyout server.key -out server.crt

You will get a few questions, just press enter to accept the defaults.

Note: You may use sudo to run the command, and the created files will be owned by root. It is necessary to change the ownership to the user running the ElectrumX server.

sudo chown $USER:$USER server.key server.crt

Running as a Service

Let’s set up systemd to manage our server. Create this file:

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

With this content:

[Unit]
Description=ElectrumX Server
After=network.target

[Service]
Environment=PYTHONPATH=/home/$USER/electrumx
Environment=ALLOW_ROOT=1
EnvironmentFile=/etc/electrumx.conf
ExecStart=/home/$USER/electrumx/bin/electrumx_server
User=$USER
LimitNOFILE=8192
TimeoutStopSec=30min

[Install]
WantedBy=multi-user.target

Start it up:

sudo systemctl enable electrumx
sudo systemctl start electrumx

Watching the Progress

The initial sync takes a while. I like to watch the progress:

journalctl -u electrumx -f

You should see something like this:

INFO:BlockProcessor:our height: 1,679,585 daemon: 5,481,680 UTXOs 1,406MB hist 50MB

This tells us:

We’ve processed about 1.6 million blocks out of 5.4 million
The UTXO set is currently using 1.4GB of memory
The history database is about 50MB

The sync is progressing steadily. Every few minutes, ElectrumX flushes data to disk:

INFO:DB:flush #16 took 7.1s.  Height 1,658,727 txs: 28,106,648 (+2,028,926)
INFO:DB:tx/sec since genesis: 9,685, since last flush: 6,590
INFO:DB:sync time: 48m 22s  ETA: 03h 26m 52s

This shows:

We’re processing about 9,685 transactions per second on average
Each flush writes about 2 million new transactions
The estimated time remaining is about 3.5 hours

The server is steadily catching up with the blockchain, and the resource usage seems reasonable on my VPS.

You can also check the status of the server with the getinfo command:

python3 electrumx_rpc getinfo

You should see something like this:

{
    "coin": "Dogecoin",
    "daemon": "localhost:22555/",
    "daemon height": 5481719,
    "db height": 1968214,
    "db_flush_count": 27,
    "groups": 0,
    "history cache": "0 lookups 0 hits 0 entries",
    "merkle cache": "0 lookups 0 hits 0 entries",
    "peers": {
        "bad": 0,
        "good": 0,
        "never": 0,
        "stale": 0,
        "total": 0
    },
    "pid": 40871,
    "request counts": {
        "getinfo": 12,
        "groups": 1,
        "peers": 1
    },
    "request total": 14,
    "sessions": {
        "count": 1,
        "count with subs": 0,
        "errors": 0,
        "logged": 0,
        "pending requests": 1,
        "subs": 0
    },
    "tx hashes cache": "0 lookups 0 hits 0 entries",
    "txs sent": 0,
    "uptime": "01h 24m 15s",
    "version": "ElectrumX 1.16.0"
}

Querying an address

You can query an address to see its balance and transaction history:

python3 electrumx_rpc query D7vo9sSwRJRP6HxQcNnEHT4bK5Xaa7U9TA

You should see something like this:

Address: D7vo9sSwRJRP6HxQcNnEHT4bK5Xaa7U9TA
History #0: height 5,458,190 tx_hash 2993d6a406b6e0f9326229455664a409f82099818b1c605e434d02b6e15049f5
History #1: height 5,458,210 tx_hash 66cf65076c709c495f87d7534f5fe4b54ff418c51862543ef1e3da9928b93e7d
History #2: height 5,459,633 tx_hash 7b23286a64aea2bc3e03ed575cf0a812e38402dd37fdb0f9cbf13da4623bf001
History #3: height 5,459,701 tx_hash 1e8df2b4a1cbb782c41917b5e362e220ef8bb07d7e690fcea5a07b54d0b8ffad
...
History #35: height 5,481,573 tx_hash 4290f07067b4d66b332f7217714a8f68123b4b7e8da620790b609959e8d3b490
History #36: height 5,482,834 tx_hash 781ac016a5deb053f4a4c7fb9f8c9f722e86b726eabd6dbc983fc8bf8d49631c
UTXO #1: tx_hash 781ac016a5deb053f4a4c7fb9f8c9f722e86b726eabd6dbc983fc8bf8d49631c tx_pos 151 height 5,482,834 value 226,101,099,574
Balance: 2,261.01099574 DOGE

Conclusion

ElectrumX serves as a bridge between full nodes and light wallets in the Dogecoin ecosystem. While our Dogecoin Core node stores the complete blockchain, ElectrumX creates specialized indexes that make it easy to query specific addresses and their transaction histories. This indexing allows light wallets to quickly access their relevant data without downloading the entire blockchain.

By running our own ElectrumX server, we’re not only contributing to the network’s infrastructure but also gaining the ability to query any address’s balance and transaction history directly from our own trusted setup. The server pulls all its data from our local Dogecoin Core node, indexes it for quick access, and makes it available to light clients through a secure interface.

This setup is particularly valuable for developers building Dogecoin applications, wallet providers needing reliable backend services, and anyone interested in analyzing specific addresses or transactions without dealing with the full node’s raw data structure. Whether you’re building a wallet, running a service, or just exploring the blockchain, having your own ElectrumX server provides fast, reliable, and trustless access to the Dogecoin network.