# 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)

### 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
- **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)

---

Written in node.js and mongodb, eIquidus is the most stable, secure, customizable and feature-rich open-source block explorer with support for virtually any altcoin that implements some form of the [Bitcoin RPC API protocol](https://developer.bitcoin.org/reference/rpc/index.html) (EVM blockchains such as ETH, BNB, etc. are not supported). Originally built for the [Exor blockchain](https://github.com/team-exor/exor), eIquidus has since grown into a fully-featured explorer with a focus on stability and security at its core. All features from the [original iquidus explorer](https://github.com/iquidus/explorer) are included here along with many new ideas from other iquidus forks, and an absolute ton of new custom changes and bug fixes that were developed specifically for eIquidus.

Table of Contents
------------------

- [Features](#features)
- [Quick Start (Docker)](#quick-start-docker)
- [Configuration](#configuration)
- [Docker Management](#docker-management)
- [Backup & Restore](#backup--restore)
- [Wallet Settings](#wallet-settings)
- [CORS Support](#cors-support)
- [Known Issues](#known-issues)
- [Special Thanks](#special-thanks)
- [License](#license)

### Features

- Built using the following scripts and technologies:
  - Node.js (v20.9.0 or newer recommended)
  - MongoDB (v7.0.2 or newer recommended)
  - jQuery v3.7.1
  - Bootstrap v5.1.3
  - DataTables v1.13.6
  - Font Awesome v6.4.2
  - Luxon v3.4.3
  - Chart.js v4.4.7
    - chartjs-plugin-crosshair v2.0.5
    - chartjs-chart-financial v0.1.1
    - chartjs-adapter-luxon v1.3.1
    - chartjs-plugin-annotation v3.1.0
  - OverlayScrollbars v2.3.2
  - flag-icons v6.11.1
- Mobile-friendly
- Multi-threaded block sync
- Sass support
- Pages/features:
  - **Home/Explorer:** Displays latest blockchain transactions
  - **Movement:** Displays latest blockchain transactions greater than a configurable amount
  - **Network:** Displays peers that connected to the node in the past 24 hours
  - **Top 100:** Richest wallet addresses and wealth distribution chart
  - **API:** Public REST APIs for block data, address balances, network stats, and more
  - **Orphaned Blocks:** List of orphaned blocks with links to neighboring valid blocks
  - **Block Info:** Block summary and transaction list for a specific block height
  - **Transaction Info:** Input/output addresses, OP_RETURN value, coinbase info
  - **Address Info:** Balance, total sent/received, QR code, and transaction history
- Choose from 26 built-in Bootswatch themes plus the custom **Purple** theme included in this fork
- Configurable network charts (hashrate and difficulty) displayed in the page header
- Custom social links in the footer

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

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

# 3. Check that the web explorer is up
curl http://localhost:3001

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

The stack starts four containers:

| Container | Role |
|---|---|
| `purple-explorer-mongodb` | MongoDB 7 (internal network only) |
| `purple-explorer` | Web UI on port 3001 |
| `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 |
| `EXPLORER_PORT` | Host port for the web UI (default `3001`) |

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 & Restore

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.

#### Create a backup

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

#### Restore a backup

```bash
docker stop purple-explorer-mongodb
sudo rm -rf ~/purple-explorer/db/*
sudo tar -xzf ~/purple-explorer/db_backup_YYYY-MM-DD.tar.gz -C ~/purple-explorer
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: bind EACCES ...**

This error appears when trying to run the explorer on a port lower than 1024 without root permissions. In the Docker setup this is not an issue since the internal port is always 3001; use a reverse proxy (e.g. Caddy) on the host to expose port 80/443.

**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.