purple-explorer/README.md

# BitcoinPurple Explorer

> **Fork of [team-exor/eiquidus](https://github.com/team-exor/eiquidus)**
> Customized for the [BitcoinPurple](https://bitcoinpurple.org) blockchain.

![GitHub](https://img.shields.io/github/license/team-exor/eiquidus?color=7c3aed)

> **Designed to run alongside [purple-stack](https://github.com/BitcoinPurpleBlockchain/purple-stack).**
> That repository provides the `bitcoinpurpled` node and creates the shared `purple` Docker network that this explorer connects to. Start `purple-stack` first, then bring up this explorer.

### BitcoinPurple Customizations

The following changes were made on top of the upstream eIquidus codebase:

- **Docker Compose stack** — `Dockerfile`, `docker-compose.yml`, `docker/entrypoint.sh`, `docker/settings.json.tmpl`: single image supporting `web`, `sync-blocks`, and `sync-peers` run modes; joins the external `purple` Docker network to reach the `bitcoinpurpled` RPC at `bitcoinpurpled:13495`; MongoDB runs in an isolated internal network
- **Caddy reverse proxy** — automatic HTTPS via Let's Encrypt; domain configurable via `DOMAIN` in `.env`
- **Coin supply via TXOUTSET** — BitcoinPurple has no `getinfo` RPC; supply is fetched via `gettxoutsetinfo` (`sync.supply: "TXOUTSET"` in settings)
- **Purple/violet dark theme** — `public/css/themes/purple/` + `public/css/custom.scss`: high-contrast 4-level luminance palette, pill-shaped search bar, glowing stat panels, styled chart cards
- **Hashrate auto-scaling** — `public/js/custom.js`: the network hashrate panel and chart Y-axis auto-scale to keep values in the 1–999 range with the correct unit (H/s → KH/s → MH/s → GH/s → TH/s → PH/s)

---

### Quick Start (Docker)

**Prerequisites:** Docker, Docker Compose, and the `purple` Docker network already running (created by the `purple-stack` that runs `bitcoinpurpled`).

```bash
# 1. Copy and fill in the env file
cp .env.example .env
nano .env   # set WALLET_RPC_USER, WALLET_RPC_PASS, MONGO_PASSWORD, DOMAIN

# 2. Build the image and start all services
docker compose up -d --build

# 3. Check that the web explorer is up
#    Dev (DOMAIN=localhost):  http://localhost
#    Prod (DOMAIN=your.domain.com):  https://your.domain.com
curl http://localhost

# 4. Watch the block sync log
docker logs -f purple-explorer-sync-blocks
```

The stack starts five containers:

| Container | Role |
|---|---|
| `purple-explorer-caddy` | Caddy reverse proxy — ports 80/443, automatic HTTPS via Let's Encrypt |
| `purple-explorer-mongodb` | MongoDB 7 (internal network only) |
| `purple-explorer` | Web UI on port 3001 (internal only, proxied by Caddy) |
| `purple-explorer-sync-blocks` | Syncs blocks every `SYNC_BLOCKS_INTERVAL` seconds (default 120) |
| `purple-explorer-sync-peers` | Syncs peers every `SYNC_PEERS_INTERVAL` seconds (default 300) |

To run a full reindex from genesis:

```bash
docker compose run --rm explorer reindex
```

### Configuration

All settings are injected at container start via `docker/settings.json.tmpl` + environment variables. Copy `.env.example` to `.env` and set at minimum:

| Variable | Description |
|---|---|
| `WALLET_RPC_USER` | `rpcuser` from `bitcoinpurple.conf` |
| `WALLET_RPC_PASS` | `rpcpassword` from `bitcoinpurple.conf` |
| `MONGO_PASSWORD` | Password for the MongoDB app user |
| `DOMAIN` | Domain served by Caddy. Use `localhost` for local development (HTTP, no certificate needed). Use a real domain for production — Caddy will obtain a Let's Encrypt certificate automatically. |

You can further customize the site by adding javascript to `public/js/custom.js` and CSS rules to `public/css/custom.scss`. Changes to these files require rebuilding the image (`docker compose up -d --build`).

### Docker Management

```bash
# Start / stop all services
docker compose up -d
docker compose down

# Rebuild after code changes
docker compose up -d --build

# View logs
docker logs -f purple-explorer
docker logs -f purple-explorer-sync-blocks

# Open a shell inside the explorer container
docker exec -it purple-explorer sh
```

### Backup

MongoDB's data files are stored in the `./db` directory (bind-mounted into the container). Because the files are owned by the MongoDB process (root inside the container), `sudo` is required.

Stop MongoDB first to ensure a consistent snapshot, then archive the `./db` directory:

```bash
docker stop purple-explorer-mongodb
sudo tar -czf ~/purple-explorer/db_backup_$(date +%Y-%m-%d).tar.gz -C ~/purple-explorer db
docker start purple-explorer-mongodb
```

### Wallet Settings

The `bitcoinpurpled` wallet must be running with the following options in `bitcoinpurple.conf`:

```
daemon=1
txindex=1
```

In most cases the blockchain must be synced with `txindex=1` enabled to have access to all transactions.

### CORS Support

eIquidus has basic CORS support which is useful to prevent other sites from consuming public APIs while still allowing specific websites whitelisted access.

Enable CORS by editing `docker/settings.json.tmpl` and setting `webserver.cors.enabled` to `true`. Set `webserver.cors.corsorigin` to the specific origin you want to allow (defaults to `"*"` which allows all origins — not recommended for production):

```json
"webserver": {
  "cors": {
    "enabled": true,
    "corsorigin": "https://example.com"
  }
}
```

### Known Issues

**Error: Callback was already called**

Typically a connection issue between the explorer and the wallet daemon. The most common cause is configuring the P2P port instead of the RPC port in the settings. Also check that `bitcoinpurpled` is running and accepting RPC connections.

### Special Thanks

- **[Luke Williams (aka iquidus)](https://github.com/iquidus):** for creating the original [Iquidus explorer](https://github.com/iquidus/explorer)
- **[Alan Rudolf (aka suprnurd)](https://github.com/suprnurd):** for the custom changes found in the [Ciquidus explorer](https://github.com/suprnurd/ciquidus)
- **[Tim Garrity (aka uaktags)](https://github.com/uaktags):** for his many contributions to the Iquidus explorer
- **[TheHolyRoger](https://github.com/TheHolyRoger):** for his continued work and contributions to the Iquidus explorer
- **[Team Exor](https://github.com/team-exor):** for the eIquidus explorer this fork is based on
- All the rest of the Iquidus contributors who helped shape the Iquidus explorer

### License

Copyright (c) 2019-2025, The Exor Community<br />
Copyright (c) 2017, The Chaincoin Community<br />
Copyright (c) 2015, Iquidus Technology<br />
Copyright (c) 2015, Luke Williams<br />
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of Iquidus Technology nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.