qanum-rpc-explorer

Lightweight, self-hosted explorer for the Qanum L1, derived from janoside/btc-rpc-explorer (v3.5.1, MIT). It connects to a qanumd node over JSON-RPC (style Bitcoin Core) and renders the chain in a web UI.

License: MIT (see `LICENSE`) — upstream btc-rpc-explorer is also MIT
Language: Node.js (Express) / Pug
Based on: janoside/btc-rpc-explorer v3.5.1 (independent repo, no fork relationship)

Qanum is a post-quantum L1 (not Bitcoin). It uses:

• Addresses: bech32m with HRPs qn / tqn / rqn (mainnet / testnet / regtest).
• Transactions: a custom wire format with ML-DSA-44 / SLH-DSA-128s auth and amounts in jomas (1 QAN = 100 000 000 jomas).
• Consensus hash: SHA3-256 (not double-SHA256).
• Block time / difficulty: 75 s target, ASERT difficulty.
• Block subsidy: starts at 8 QAN, decays ×0.9 per year (BLOCKS_PER_YEAR = 420 480), floored at 0.2 QAN.

The explorer is not Bitcoin-compatible internally; it uses a Qanum coin definition (app/coins/qan.js) verified against the L1.

Features

• Network Summary dashboard (subsidy, supply, difficulty, mempool stats)
• View details of blocks, transactions, and addresses
• Analysis tools for viewing stats on blocks and transactions
• JSON REST API (/api/*)
• Raw JSON content from the node used to generate most pages
• Search by transaction ID, block hash/height, and address
• Optional transaction history for addresses via qanum-electrs (Electrum protocol)
• Mempool summary, with fee (jomas/vB), size, and age breakdowns
• RPC command browser and terminal

Status (read layer)

v0.1.7 — see TESTSUITE.md for the test matrix and CHANGELOG-QANUM.md for the Qanum-specific change history. Delivered:

• app/coins/qan.js — Qanum coin definition verified against qanum/src/constants.rs and src/economics.rs (jomas, 75 s block time, ASERT, subsidy function, regtest genesis hash). Select the coin with QANEXP_COIN=QAN.
• RPC layer aligned to qanumd responses (app/api/coreApi.js, app/api/rpcApi.js): block/tx normalization (coinbase marker, vout n index, synthesized scriptPubKey), validateaddress-based getAddress, and the native Core-shaped L1 RPCs where available (getchaintxstats, getindexinfo, getnettotals, getnetworkhashps, getblockstats).
• Transaction/block parser uses vout.address (Qanum returns the bech32m address on each vout; it is not scriptPubKey.address as in Bitcoin).
• /address/:addr and /api/address/:addr — wired to qanum-electrs via the Electrum protocol with scripthash = address (app/api/electrumAddressApi.js), selected with QANEXP_ADDRESS_API=electrum + QANEXP_ELECTRUM_SERVERS. Balances, tx history and per-tx in/out are rendered in QAN/jomas.
• Qanum display currency (QAN/jomas) as the default, with mempool fee rates labelled jomas/vB.
• /next-block — works for Qanum: qanumd's getblocktemplate requires net_v2 (enable it at the node with -listen=1), and its native output shape differs, so the candidate is built from the node's mempool (getrawmempool verbose).
• /tx-stats — works for Qanum via qanumd's native getchaintxstats (Core shape; one node-side window scan per request). Windows use the coin's blocksPerDay (1152 for Qanum) instead of Bitcoin's 144.
• RPC concurrency: since qanumd v0.30.3 the L1 RPC concurrency is configurable (-rpcthreads / -rpcworkqueue, defaults 16/64). The explorer's rpcConcurrency is no longer capped for Qanum — set QANEXP_RPC_CONCURRENCY freely (e.g. 16–24) to match the node's worker/queue settings.

Known limitations: Bitcoin-specific tools (Whitepaper Extractor, Quotes, Holidays) are present but not yet adapted to Qanum data; they are kept so they can be aligned later (tracked as a future phase, requires product decision).

Getting started

Prerequisites

1. Run a qanumd node (see qanum/qanum) with its JSON-RPC server reachable from the explorer. Use --rpcauth-required=0 (no auth) or set a RPC user/password, and let the node synchronize (you can use the explorer while syncing, but some pages may fail). qanumd RPC defaults: mainnet 8338 / testnet 18338 / regtest 28338, auth cookie at <datadir>/.cookie (default datadir ~/.qanum/<network>).
2. Recommended node flags: -txindex=1 (transaction lookup by txid), -addressindex=1 (address index; required if you don't use an Electrum backend) and -listen=1 (enables net_v2, needed for the mining RPCs behind /next-block). Without txindex/addressindex, some data will be incomplete or missing (e.g. prevout values, fees of confirmed txs).
3. Install Node.js (16+ required, 18+ recommended) — only needed for the source/npm installs; the Docker image already includes it.
4. Optional: run qanum-electrs on the node and select it with QANEXP_ADDRESS_API=electrum for full address pages.

Quick start (regtest)

# node (enable net_v2 so mining RPCs work on the node; the explorer reads over
# the regular RPC port regardless)
qanumd -regtest --datadir=... --rpcauth-required=0 -addressindex=1 -txindex=1 \
  --verifier=oqs -listen=1

# explorer
npm install
QANEXP_COIN=QAN \
QANEXP_QANUMD_HOST=127.0.0.1 \
QANEXP_QANUMD_PORT=28338 \
QANEXP_ADDRESS_API=electrum QANEXP_ELECTRUM_SERVERS=tcp://127.0.0.1:50001 \
npm start

The app is then available at http://127.0.0.1:3002/.

Install / Run

Install via npm (global)

npm install -g qanum-rpc-explorer
qanum-rpc-explorer --help

This installs the qanum-rpc-explorer command (all CLI options are listed in --help; see Configuration). The package is published to npm by the Qanum project as qanum-rpc-explorer.

Install from source

1. git clone https://github.com/qanum/qanum-rpc-explorer
2. cd qanum-rpc-explorer
3. npm install
4. Set your node connection and coin (see Configuration), then npm start

An AUR package, like the upstream project's, is not provided.

Run via Docker

Published images (qanum/qanum-rpc-explorer), a Dockerfile and a docker-compose.yml are provided:

# pull the published image
docker pull qanum/qanum-rpc-explorer:latest

# run it (expose on the LAN with QANEXP_HOST=0.0.0.0)
docker run -it -p 3002:3002 -e QANEXP_HOST=0.0.0.0 \
  -e QANEXP_QANUMD_URI=http://rpcuser:[email protected]:28338 \
  -e QANEXP_COIN=QAN \
  qanum/qanum-rpc-explorer:latest

Or use the included compose file (it references the published image and also builds it locally):

# build the local image and run (see docker-compose.yml for the env wiring)
docker compose up --build

docker compose up without --build pulls qanum/qanum-rpc-explorer:latest from Docker Hub. Define QANEXP_QANUMD_URI, QANEXP_ADDRESS_API and QANEXP_ELECTRUM_SERVERS in a .env file next to docker-compose.yml.

Step-by-step guides: docs/Server-Setup.md (bare metal) and docs/Server-Setup-Docker.md (Docker).

Configuration

Configuration options may be set via environment variables or CLI arguments.

Configuration with environment variables

Create one of the following files and enter the values in it:

1. ~/.config/qanum-rpc-explorer.env
2. /etc/qanum-rpc-explorer/.env
3. .env in the explorer's working directory

Refer to .env-sample for the full list of options (all QANEXP_*). The essentials:

| Variable | Purpose | |---|---| | QANEXP_COIN | Coin to run; default QAN (the only supported value) | | QANEXP_QANUMD_URI | Full node RPC URI, e.g. http://user:[email protected]:28338 (cookie via ?cookie=...) | | QANEXP_QANUMD_HOST / _PORT / _USER / _PASS / _COOKIE | …or the individual pieces (port default: mainnet 8338; testnet 18338; regtest 28338) | | QANEXP_HOST / QANEXP_PORT | Explorer listen address/port (default 127.0.0.1:3002) | | QANEXP_ADDRESS_API | electrum to use qanum-electrs for address lookups | | QANEXP_ELECTRUM_SERVERS | e.g. tcp://127.0.0.1:50001 (comma-separated for several) | | QANEXP_RPC_CONCURRENCY | Parallel RPC requests (match -rpcworkqueue, e.g. 16–24) |

Configuration with CLI args

Run qanum-rpc-explorer --help (or node bin/cli.js --help) for the full list of options. The node-connection options use Qanum names:

| Flag | Purpose | |---|---| | -b, --qanumd-uri <uri> | Connection URI for the qanumd RPC (overrides the options below) | | -H, --qanumd-host <host> | Hostname for qanumd RPC (default 127.0.0.1) | | -P, --qanumd-port <port> | Port for qanumd RPC (default 8338; testnet 18338; regtest 28338) | | -c, --qanumd-cookie <path> | Path to the qanumd RPC cookie file (default ~/.qanum/mainnet/.cookie) | | -u, --qanumd-user <user> / -w, --qanumd-pass <pass> | RPC username/password | | -p, --port / -i, --host | Explorer listen port/address | | -C, --coin <coin> | Coin (default QAN) | | -E, --electrum-servers <..> | Electrum servers for --address-api=electrum | | -a, --basic-auth-password <..> | Protect the web interface with a password |

Other options (all also available as QANEXP_* env vars): --address-api, --rpc-allowall, --rpc-blacklist, --cookie-secret, --demo, --no-rates, --slow-device-mode, --privacy-mode, --max-mem, --ganalytics-tracking, --sentry-url, --node-env. Example:

qanum-rpc-explorer -p 8080 -b http://rpcuser:[email protected]:28338

The upstream btc-rpc-explorer --bitcoind-* spellings are still accepted for compatibility; when both are given, the Qanum names take precedence.

Demo-site settings

To match the features of a full-featured public explorer, set the following non-default values:

QANEXP_DEMO=true
QANEXP_NO_RATES=false
QANEXP_SLOW_DEVICE_MODE=false
QANEXP_ADDRESS_API=electrum
QANEXP_ELECTRUM_SERVERS=tcp://your-electrum-protocol-server-host:50001
QANEXP_IPSTACK_APIKEY=your-api-key
QANEXP_MAPBOX_APIKEY=your-api-key

SSO authentication

SSO authentication can be configured (as ThunderHub and RTL provide). To enable it, make sure QANEXP_BASIC_AUTH_PASSWORD is not set and point QANEXP_SSO_TOKEN_FILE at a file write-accessible by the explorer. Your SSO provider then reads the token from this file and sets it in the URL parameter token. For security reasons the token changes with each login, so the SSO provider must read it each time. After successful access with the token, a cookie is set for authentication. Optionally set QANEXP_SSO_LOGIN_REDIRECT_URL to your SSO provider's login URL so users are redirected there when needed.

Reverse proxy with HTTPS

See docs/nginx-reverse-proxy.md for nginx + certbot (letsencrypt) instructions, and use docs/qanum-explorer.conf as the canonical nginx template.

See docs/QANUM.md for the Qanum alignment notes, TESTSUITE.md for the test matrix, and CHANGELOG-QANUM.md for the change history. INFORME_ALINEACION_EXPLORER.md records the original alignment plan.

Branding / project URL

The explorer no longer references the Bitcoin Explorer project or janoside in the UI: the footer, "View source" links, canonical/OG meta tags and the GitHub metadata (stars/forks) all point to this Qanum repo. They are configurable via:

• QANEXP_PROJECT_URL — project repo URL (default https://github.com/qanum/qanum-rpc-explorer).
• QANEXP_PROJECT_NAME — project name (default qanum-rpc-explorer).

qanumd is referred to as "your node" throughout. Bitcoin-specific tools (Whitepaper Extractor, Quotes, Holidays) remain available but are not yet adapted to Qanum data; they are kept so they can be aligned later.

License

MIT License. Full text in LICENSE: Copyright (c) 2026 Qanum.

This repository is a Qanum L1 adaptation; the upstream (janoside/btc-rpc-explorer v3.5.1, also MIT) attribution is kept in the intro of this README.