ElectrumX Server Setup Guide

What is ElectrumX?

ElectrumX is a server implementation for the Electrum protocol, which is used by many cryptocurrency wallets to interact with blockchain networks. It provides a way to query blockchain data efficiently without needing to run a full node, making it an essential component for lightweight wallet applications.

Why Run Your Own ElectrumX Server?

Running your own ElectrumX server offers several important benefits:

  1. Self-Sovereignty: By running your own server, you maintain full control over your blockchain data access. You don't need to trust third-party servers that might:
  2. Track your IP address and transaction patterns
  3. Implement rate limiting or restrictions
  4. Have unreliable uptime

  5. Potentially censor transactions

  6. Privacy: When you connect to public Electrum servers, your IP address and transaction queries are visible to the server operators. Running your own server ensures that only you have access to this information.

  7. Reliability: Public Electrum servers can be:

  8. Overloaded with requests
  9. Subject to DDoS attacks
  10. Temporarily offline

  11. Rate-limited Having your own server ensures consistent and reliable access to blockchain data.

  12. Performance: Your own server can be:

  13. Optimized for your specific needs
  14. Located closer to your network
  15. Configured with appropriate resources

  16. Not shared with other users

  17. Network Health: By running your own server, you contribute to the decentralization of the Electrum network, making it more resilient and less dependent on a few large operators.

Use Cases

  • Personal Wallets: Secure and private access to your Navio wallet
  • Business Operations: Reliable blockchain data access for business applications
  • Development: Local testing and development environment
  • Network Contribution: Supporting the Navio network infrastructure

This guide explains how to set up an ElectrumX server for Navio's testnet.

Prerequisites

  • A server running Linux (Ubuntu/Debian recommended)
  • Python 3.7 or higher
  • Navio daemon installed and synced
  • SSL certificates (if offering SSL/WSS connections)
  • Domain name (optional, but recommended for SSL)

Installation Steps

  1. Clone the Navio fork of ElectrumX:
git clone https://github.com/nav-io/electrumx.git
cd electrumx
  1. Install system dependencies:
sudo apt-get update
sudo apt-get install -y python3-pip python3-dev python3-venv build-essential libssl-dev
  1. Create and activate a Python virtual environment:
python3 -m venv venv
source venv/bin/activate
  1. Install Python dependencies:
pip install -r requirements.txt
  1. Create a system user for ElectrumX:
sudo useradd -m -s /bin/bash electrumx
sudo usermod -aG sudo electrumx
  1. Create necessary directories:
sudo mkdir -p /home/electrumx/db
sudo chown -R electrumx:electrumx /home/electrumx/db

If you have a domain name and want to offer SSL/WSS connections, follow these steps:

  1. Install Certbot:
sudo apt-get install certbot
  1. Obtain SSL certificate:
sudo certbot certonly --standalone -d your-domain.com

The certificates will be stored in /etc/letsencrypt/live/your-domain.com/

Configuration

  1. Create a configuration file:
sudo nano /etc/electrumx.conf
  1. Add the following configuration (adjust values as needed):
COIN=Navio
NET=testnet
DB_DIRECTORY=/home/electrumx/db
DAEMON_URL=user:password@127.0.0.1:44444
USERNAME=electrumx
ANON_LOGS=1
SSL_CERTFILE=/etc/letsencrypt/live/your-domain.com/fullchain.pem
SSL_KEYFILE=/etc/letsencrypt/live/your-domain.com/privkey.pem
SERVICES=tcp://your-ip:40001,ssl://your-ip:40002,wss://your-ip:40004
MAX_SEND=10000000
COST_SOFT_LIMIT=0
COST_HARD_LIMIT=0

Replace: - your-domain.com with your actual domain name - your-ip with your server's IP address - user:password with your Navio daemon RPC credentials

Setting up as a Service

  1. Create a systemd service file:
sudo nano /etc/systemd/system/electrumx.service
  1. Add the following content:
[Unit]
Description=ElectrumX Server
After=network.target

[Service]
User=electrumx
Group=electrumx
EnvironmentFile=/etc/electrumx.conf
WorkingDirectory=/home/electrumx/electrumx
ExecStart=/home/electrumx/electrumx/venv/bin/python3 /home/electrumx/electrumx/electrumx_server
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
  1. Enable and start the service:
sudo systemctl enable electrumx
sudo systemctl start electrumx
  1. Check the status:
sudo systemctl status electrumx

Firewall Configuration

Configure your firewall to allow the necessary ports:

sudo ufw allow 40001/tcp  # TCP
sudo ufw allow 40002/tcp  # SSL
sudo ufw allow 40004/tcp  # WSS

Monitoring

  1. View logs:
sudo journalctl -u electrumx -f
  1. Check database status:
sudo -u electrumx /home/electrumx/electrumx/venv/bin/python3 /home/electrumx/electrumx/electrumx_rpc getinfo

Recent Updates

Latest Changes (December 2025)

The Navio ElectrumX implementation has been updated with significant improvements:

Output Hash Management

Navio now uses output hash indexing instead of traditional (transaction ID, output index) pairs. This change provides:

  • Faster lookups: Direct hash-based indexing for transaction outputs
  • Better privacy: Output hashes are used for BLSCT (BLS Confidential Transactions) compatibility
  • Improved performance: Optimized database queries for output retrieval

When using output-related RPC methods, clients should now pass output hashes (as hexadecimal strings) instead of transaction IDs and output indices.

Enhanced Error Handling

The server now includes improved error handling and logging throughout:

  • Better error messages for debugging
  • More detailed logging for troubleshooting
  • Graceful handling of edge cases and failures

New RPC Methods

Three new RPC methods have been added to support efficient blockchain data retrieval:

blockchain.block.get_txs_keys

Returns transaction keys for all transactions in a specific block.

Method: blockchain.block.get_txs_keys

Parameters: - height (integer, required): The block height

Returns: A list of tuples, where each tuple contains: - tx_hash (string): Transaction hash in hexadecimal format - keys (object): Transaction keys data

Example:

[
  ["a1b2c3d4...", {"key1": "value1", "key2": "value2"}],
  ["e5f6g7h8...", {"key1": "value1", "key2": "value2"}]
]

Use Case: Useful for retrieving all transaction keys for a specific block in a single request, enabling efficient batch processing of block data.

blockchain.block.get_range_txs_keys

Returns transaction keys for a range of blocks, automatically handling response size limits.

Method: blockchain.block.get_range_txs_keys

Parameters: - start_height (integer, required): The starting block height

Returns: A JSON object containing: - blocks (array): List of blocks, where each block is a list of (tx_hash, keys) tuples - next_height (integer): The next block height to query (for pagination)

Example:

{
  "blocks": [
    [
      ["a1b2c3d4...", {"key1": "value1"}],
      ["e5f6g7h8...", {"key1": "value1"}]
    ],
    [
      ["i9j0k1l2...", {"key1": "value1"}]
    ]
  ],
  "next_height": 12350
}

Features: - Automatically batches multiple blocks in a single response - Respects max_send protocol limits - Returns next_height for efficient pagination - Optimized for parallel database queries

Use Case: Ideal for syncing transaction keys across multiple blocks efficiently, such as when initializing a wallet or performing bulk data synchronization.

blockchain.transaction.get_output

Retrieves a serialized transaction output by its output hash.

Method: blockchain.transaction.get_output

Parameters: - output_hash (string, required): The output hash as a hexadecimal string

Returns: - serialized_output (string): The serialized raw transaction output in hexadecimal format

Example Request:

{
  "method": "blockchain.transaction.get_output",
  "params": ["a1b2c3d4e5f6..."]
}

Example Response:

"0100000001a1b2c3d4..."

Features: - Fast retrieval using output hash indexing - Returns raw serialized output (no deserialization overhead) - Optimized for Navio's output hash-based system

Use Case: Essential for retrieving transaction outputs when you have the output hash (common in BLSCT transactions). This method is faster than traditional transaction lookup methods because it uses direct hash-based indexing.

Performance Improvements

  • Parallel key reading: Transaction keys are now read in parallel for better performance
  • Optimized database queries: Batch operations for multiple blocks
  • JSON serialization: Faster serialization/deserialization using JSON format
  • Response size management: Automatic trimming to respect protocol limits

Removed Methods

The following methods have been removed as part of the cleanup: - blockchain.dao.subscribe - blockchain.stakervote.subscribe - blockchain.consensus.subscribe - blockchain.listproposals - blockchain.listconsultations - blockchain.getcfunddbstatehash

These methods were specific to older DAO functionality and are no longer needed.

Checking Logs and Troubleshooting

Check the Logs

  • The logs for the daemon are located in /home/navio/.navio/testnet5/debug.log
  • The logs for the staker are located in /home/navio/.navio/testnet5/staker.log

To view the logs, you can use the cat, less, or tail commands. For example:

cat /home/navio/.navio/testnet5/debug.log

How to Get Testnet Coins

Join our Discord at https://discord.com/invite/eBQ2QUkVXy and use the command /faucet in the #testnet channel.

How to Interact with the Daemon

You need to run navio-cli -testnet command as the navio user. You can switch to the navio user or use sudo:

To switch to the navio user:

sudo su - navio

Then run the command:

navio-cli -testnet command

Alternatively, run the command directly with sudo:

sudo -u navio navio-cli -testnet command

Available Commands

  • getnewaddress: Shows an address to receive coins
  • getbalance: Shows the wallet balance
  • sendtoblsctaddress address amount: Send coins to an address
  • stakelock amount: Stake an amount of coins (minimum is 10000)
  • stakeunlock amount: Remove from staking (the remaining staking should be 10000 at a minimum)

Troubleshooting

If you encounter any issues, consider the following steps:

  • Check the Log File: Review the log files for detailed error messages
  • Verify Service Status: Ensure the services are running using systemctl status naviod and systemctl status navio-staker
  • Check Dependencies: Make sure all dependencies are installed properly. Re-run the script to ensure no steps were missed
  • Output not found errors: When using blockchain.transaction.get_output, ensure you're using the output hash (not transaction ID) in hexadecimal format

Maintenance

  1. Regular updates:
cd /home/electrumx/electrumx
git pull
source venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart electrumx
  1. Database backup:
sudo systemctl stop electrumx
sudo tar -czf electrumx_db_backup.tar.gz /home/electrumx/db
sudo systemctl start electrumx

Remember to regularly backup your database and keep your system updated for security and performance.