ElectrumX with Palladium (PLM) Support

This repository provides a Dockerized setup of ElectrumX with support for the Palladium (PLM) coin. It also includes a test script (test-server.py) to verify the connection and main functionalities of the ElectrumX server.

Tested on:

• ✅ Debian 12
• ✅ Ubuntu 24.04

🔗 Palladium Full Node: davide3011/palladiumcore

---

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Electrum      │    │   ElectrumX     │    │   Palladium     │
│   Clients       │◄──►│   Server        │◄──►│   Full Node     │
│                 │    │   (Docker)      │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

---

Requirements

• Docker
• Docker Compose
• Python 3.10+ (to use test-server.py)
• A running Palladium full node (NotRin7/Palladium)

System Architecture: This server requires a 64-bit system (both AMD64 and ARM64 architectures are supported, but 32-bit systems are not compatible).

Recommendation: to ensure maximum stability and reduce communication latency, it is strongly recommended to run the Palladium node on the same machine that hosts the ElectrumX container.

---

Docker Installation

If you don't have Docker installed yet, follow the official guide:

• Install Docker

For Docker Compose:

• Install Docker Compose

---

Configuration

In the docker-compose.yml file, you can set the RPC credentials of the Palladium full node that ElectrumX will use:

environment:
  DAEMON_URL: "http://<rpcuser>:<rpcpassword>@host.docker.internal:<port>/"

Replace with your actual values:

• <rpcuser> → RPC username of the node
• <rpcpassword> → RPC password of the node
• <port> → RPC port of the node (2332 for mainnet, 12332 for testnet)

Note: The compose uses host.docker.internal to connect to the Palladium node running on your host machine (outside the container). This works on both Windows/Mac and Linux thanks to the extra_hosts configuration.

Ports: ElectrumX exposes:

• 50001 → TCP (unencrypted)
• 50002 → SSL (encrypted, recommended)

Important: never include real credentials in files you upload to GitHub.

---

Network Support (Mainnet & Testnet)

This ElectrumX server supports both Palladium mainnet and testnet. You can switch between networks by modifying the docker-compose.yml configuration.

Network Comparison

Network	COIN Value	NET Value	RPC Port	Bech32 Prefix	Address Prefix
Mainnet	Palladium	mainnet	2332	plm	Standard (starts with 1 or 3)
Testnet	Palladium	testnet	12332	tplm	Testnet (starts with t)

---

Running on Mainnet (Default)

The default configuration is set for mainnet. No changes are needed if you want to run on mainnet.

Configuration in docker-compose.yml:

environment:
  COIN: "Palladium"
  NET: "mainnet"
  DAEMON_URL: "http://<rpcuser>:<rpcpassword>@host.docker.internal:2332/"

Requirements:

• Palladium Core node running on mainnet
• RPC port: 2332
• RPC credentials configured in palladium.conf

---

Switching to Testnet

To run ElectrumX on testnet, follow these steps:

Step 1: Configure Palladium Core for Testnet

Edit your Palladium Core configuration file (palladium.conf) and add:

# Enable testnet
testnet=1

# RPC settings for testnet
rpcuser=your_rpc_username
rpcpassword=your_rpc_password
rpcport=12332

# Allow RPC connections
server=1

⚠️ Linux Systems - Important:

If you're running on Linux, you must also add the following lines to allow Docker containers to connect to your Palladium node:

# Allow Docker network connections (required on Linux)
rpcbind=0.0.0.0
rpcallowip=127.0.0.1
rpcallowip=172.17.0.0/16
rpcallowip=172.18.0.0/16

Why is this needed?

• On Linux, Docker containers run in isolated network bridges (typically 172.17.0.0/16 or 172.18.0.0/16)
• Without rpcallowip, the Palladium node only accepts connections from localhost (127.0.0.1)
• On Windows/Mac with Docker Desktop, this is handled automatically by the Docker engine
• rpcbind=0.0.0.0 makes the RPC server listen on all network interfaces (not just localhost)

Restart your Palladium Core node to apply testnet configuration.

Step 2: Modify docker-compose.yml

Open docker-compose.yml and change these two values in the environment section:

Before (Mainnet):

environment:
  COIN: "Palladium"
  NET: "mainnet"
  DAEMON_URL: "http://<rpcuser>:<rpcpassword>@host.docker.internal:2332/"

After (Testnet):

environment:
  COIN: "Palladium"
  NET: "testnet"
  DAEMON_URL: "http://<rpcuser>:<rpcpassword>@host.docker.internal:12332/"

Important changes:

1. Change NET from "mainnet" to "testnet"
2. Change port in DAEMON_URL from 2332 to 12332
3. Replace <rpcuser> and <rpcpassword> with your actual testnet RPC credentials

Step 3: Clear Existing Database (Important!)

When switching networks, you must clear the ElectrumX database to avoid conflicts:

# Stop the container
docker compose down

# Remove the database
rm -rf ./data/*

# Or on Windows:
# rmdir /s /q data
# mkdir data

Step 4: Rebuild and Restart

# Rebuild and start the container
docker compose up -d --build

# Monitor the logs
docker compose logs -f

The ElectrumX server will now sync with the Palladium testnet blockchain.

---

Testnet-Specific Information

Genesis Block Hash (Testnet):

000000000933ea01ad0ee984209779baaec3ced90fa3f408719526f8d77f4943

Address Examples:

• Legacy (P2PKH): starts with t (e.g., tPLMAddress123...)
• SegWit (Bech32): starts with tplm (e.g., tplm1q...)

Network Ports:

• Palladium Core RPC: 12332
• Palladium Core P2P: 12333
• ElectrumX TCP: 50001 (same as mainnet)
• ElectrumX SSL: 50002 (same as mainnet)

---

Switching Back to Mainnet

To switch back from testnet to mainnet:

1. Edit palladium.conf and remove or comment testnet=1
2. Change rpcport=2332 in palladium.conf
3. Restart Palladium Core node
4. In docker-compose.yml, change:
   • NET: "testnet" → NET: "mainnet"
   • Port in DAEMON_URL from 12332 → 2332
5. Clear database: rm -rf ./data/*
6. Restart ElectrumX: docker compose down && docker compose up -d

---

Build and Start the Project

1. Navigate to the directory containing docker-compose.yml and Dockerfile.

2. Start the containers with Docker Compose (builds the image automatically on first run):

   docker compose up -d
   

   Note: Docker Compose will automatically build the image if it doesn't exist. No need to run docker build manually!

3. Check the logs to verify that ElectrumX started correctly:

   docker compose logs -f
   

Manual Build (Optional)

If you want to manually rebuild the Docker image (e.g., after code changes):

# Rebuild the image
docker compose build

# Or rebuild and restart in one command
docker compose up -d --build

---

Testing with test-server.py

The test-server.py script allows you to connect to the ElectrumX server and test its APIs.

Usage example:

python test-server.py 127.0.0.1:50002

The script will perform:

• Handshake (server.version)
• Feature request (server.features)
• Block header subscription (blockchain.headers.subscribe)

---

Notes

• coins_plm.py defines both Palladium (PLM) mainnet and PalladiumTestnet classes

• See "Network Support" section for switching between mainnet and testnet

• Production recommendations:

  • Protect RPC credentials
  • Use valid SSL certificates
  • Monitor containers (logs, metrics, alerts)

---

License

Distributed under the MIT license. See the LICENSE file for details.