palladium-stack/README.md

# 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](https://github.com/davide3011/palladiumcore)

---

## Architecture

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

---

## Requirements

* [Docker](https://docs.docker.com/get-docker/)
* [Docker Compose](https://docs.docker.com/compose/install/)
* Python 3.10+ (to use `test-server.py`)
* A running **Palladium** full node ([NotRin7/Palladium](https://github.com/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](https://docs.docker.com/get-docker/)

For Docker Compose:
- [Install Docker Compose](https://docs.docker.com/compose/install/)

---

## Configuration

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

```yaml
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`:**
```yaml
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:

```conf
# 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:

```conf
# 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):**
```yaml
environment:
  COIN: "Palladium"
  NET: "mainnet"
  DAEMON_URL: "http://<rpcuser>:<rpcpassword>@host.docker.internal:2332/"
```

**After (Testnet):**
```yaml
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:

```bash
# 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

```bash
# 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):

   ```bash
   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:

   ```bash
   docker compose logs -f
   ```

### Manual Build (Optional)

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

```bash
# 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:

```bash
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.