feat: add Qbit explorer support

Author: lacdonlang

.dockerignore

@@ -0,0 +1,8 @@
+.git
+.github
+.env
+coverage
+logs
+node_modules
+npm-debug.log*
+test

.env-sample

@@ -19,7 +19,7 @@
 #BTCEXP_SECURE_SITE=false
 
 
-# The active coin. Only officially supported value is "BTC".
+# The active coin. Supported values in this fork are "BTC" and "QBT".
 # Default: BTC
 #BTCEXP_COIN=BTC
 

.github/workflows/docker-image.yml

@@ -0,0 +1,105 @@
+name: Build and publish Docker image
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/docker-image.yml"
+      - "app.js"
+      - "app/**"
+      - "bin/**"
+      - "routes/**"
+      - "public/**"
+      - "test/**"
+      - "views/**"
+      - ".dockerignore"
+      - "Dockerfile"
+      - "docker-compose.qbit.yml"
+      - "npm-shrinkwrap.json"
+      - "package.json"
+  push:
+    branches:
+      - master
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  IMAGE_NAME: ghcr.io/luxorlabs/luxor-qbit-explorer
+
+jobs:
+  test-build-publish:
+    name: Test, build, and publish image
+    runs-on: tenki-standard-large-plus-16c-32g
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Repository checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903  # v6.0.0
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: npm-shrinkwrap.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: |
+          npm test
+          npm run test:qbit
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd  # v4.0.0
+
+      - name: Login to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121  # v4.1.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate image metadata
+        id: meta
+        shell: bash
+        run: |
+          short_sha="${GITHUB_SHA:0:7}"
+          created="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          {
+            echo "created=${created}"
+            echo "tags<<EOF"
+            echo "${IMAGE_NAME}:sha-${short_sha}"
+            if [[ "${GITHUB_REF}" == "refs/heads/master" ]]; then
+              echo "${IMAGE_NAME}:latest"
+            fi
+            if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
+              echo "${IMAGE_NAME}:${GITHUB_REF_NAME}"
+              echo "${IMAGE_NAME}:${GITHUB_REF_NAME#v}"
+            fi
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Build and publish image
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7.1.0
+        with:
+          context: .
+          file: Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          labels: |
+            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.created=${{ steps.meta.outputs.created }}

Dockerfile

@@ -1,11 +1,24 @@
-FROM node:20 as builder
+FROM node:20-bookworm AS builder
+
 WORKDIR /workspace
+
+RUN apt-get update && \
+    apt-get install --no-install-recommends --yes ca-certificates git && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY package.json npm-shrinkwrap.json ./
+RUN npm ci --omit=dev
+
 COPY . .
-RUN npm install
 
-FROM node:20-alpine
+FROM node:20-bookworm-slim
+
 WORKDIR /workspace
-COPY --from=builder /workspace .
-RUN apk --update add git
-CMD npm start
+ENV NODE_ENV=production
+
+COPY --from=builder --chown=node:node /workspace /workspace
+
+USER node
+
 EXPOSE 3002
+CMD ["npm", "start"]

README-QBIT.md

@@ -0,0 +1,107 @@
+# Qbit Explorer
+
+This Luxor fork adds a `QBT` profile to btc-rpc-explorer v3. It connects directly to Qbit Core JSON-RPC and does not require a separate explorer database.
+
+## Supported Qbit behavior
+
+- Mainnet, testnet3, testnet4, signet, and regtest network identities
+- QBT, mQBT, µQBT, and bits display units
+- 60-second aggregate block target
+- 210 QBT initial block subsidy
+- Subsidy step-down every 43,200 blocks by `598/625` (regtest uses 150 blocks)
+- P2MR addresses returned by Qbit Core's current RPC shape
+- Block, transaction, mempool, peer, node-status, and RPC views
+
+Select the Qbit profile with:
+
+```text
+BTCEXP_COIN=QBT
+```
+
+## Run Qbit mainnet and the explorer
+
+The included Compose file starts the Luxor Qbit v1.0.0 image, enables `txindex`, retains mainnet data in a named volume, and exposes only the explorer HTTP port on localhost:
+
+```bash
+export QBIT_RPC_PASSWORD="replace-with-a-local-secret"
+docker compose -f docker-compose.qbit.yml up --build -d
+```
+
+Open <http://127.0.0.1:3002>.
+
+Check synchronization:
+
+```bash
+docker compose -f docker-compose.qbit.yml exec qbit \
+  sh -lc 'qbit-cli -rpcuser="$QBIT_RPC_USER" -rpcpassword="$QBIT_RPC_PASSWORD" getblockchaininfo'
+```
+
+Stop services without deleting chain data:
+
+```bash
+docker compose -f docker-compose.qbit.yml down
+```
+
+Delete the downloaded chain data only when intentional:
+
+```bash
+docker compose -f docker-compose.qbit.yml down --volumes
+```
+
+The Qbit daemon image currently targets `linux/amd64`. Docker Desktop can emulate it on Apple Silicon. The explorer image is built for both `linux/amd64` and `linux/arm64`.
+
+## Connect to an existing Qbit node
+
+Build the explorer:
+
+```bash
+docker build -t luxor-qbit-explorer:local .
+```
+
+If the node and explorer share a Docker network named `qbit-local`:
+
+```bash
+docker run --rm \
+  --name qbit-explorer \
+  --network qbit-local \
+  -p 127.0.0.1:3002:3002 \
+  -e BTCEXP_COIN=QBT \
+  -e BTCEXP_HOST=0.0.0.0 \
+  -e BTCEXP_BITCOIND_HOST=qbit-mainnet \
+  -e BTCEXP_BITCOIND_PORT=8352 \
+  -e BTCEXP_BITCOIND_USER=qbitexplorer \
+  -e BTCEXP_BITCOIND_PASS="replace-with-your-rpc-password" \
+  -e BTCEXP_BITCOIND_RPC_TIMEOUT=30000 \
+  -e BTCEXP_NO_RATES=true \
+  -e BTCEXP_PRIVACY_MODE=true \
+  luxor-qbit-explorer:local
+```
+
+For a host-installed node, point `BTCEXP_BITCOIND_HOST` at an address reachable from the container. Do not expose Qbit RPC to the public internet.
+
+## Required Qbit node settings
+
+The explorer requires RPC access. An archive node with transaction indexing provides the complete experience:
+
+```ini
+server=1
+txindex=1
+```
+
+Qbit mainnet uses RPC port `8352` and P2P port `8355`.
+
+## Container image
+
+The GitHub workflow publishes to:
+
+```text
+ghcr.io/luxorlabs/luxor-qbit-explorer
+```
+
+Pushes to `master` publish `latest` and `sha-<short-sha>`. Tags such as `v1.2.0` publish both `v1.2.0` and `1.2.0`.
+
+## Limitations
+
+- Address transaction history requires a Qbit-compatible Electrum server. Without one, block and transaction exploration still works through Qbit Core and `txindex`.
+- Bitcoin-specific historical and external exchange-rate integrations are disabled for Qbit.
+- Keep the UI bound to localhost or protect it with `BTCEXP_BASIC_AUTH_PASSWORD` before exposing it beyond a trusted network.

README.md

@@ -1,5 +1,7 @@
 # BTC RPC Explorer
 
+> This Luxor fork adds Qbit Core support. See [README-QBIT.md](README-QBIT.md) for the Qbit mainnet Docker Compose setup, configuration, and published image.
+
 ## Self-Hosted Bitcoin explorer for everyone running [Bitcoin Core](https://github.com/bitcoin/bitcoin).
 
 [![npm version][npm-ver-img]][npm-ver-url] [![NPM downloads][npm-dl-alltime-img]][npm-dl-url]
@@ -144,6 +146,8 @@ This will cause users to be redirected to your login page if needed.
 1. `docker build -t btc-rpc-explorer .`
 2. `docker run -it -p 3002:3002 -e BTCEXP_HOST=0.0.0.0 btc-rpc-explorer`
 
+For Qbit, use `docker compose -f docker-compose.qbit.yml up --build -d` as described in [README-QBIT.md](README-QBIT.md).
+
 
 ## Reverse proxy with HTTPS
 
@@ -172,4 +176,3 @@ thanks@donate.btc21.org
 [npm-dl-monthly-img]: https://badgen.net/npm/dm/btc-rpc-explorer?icon=npm&cache=300
 [npm-dl-yearly-img]: https://badgen.net/npm/dy/btc-rpc-explorer?icon=npm&cache=300
 [npm-dl-alltime-img]: https://badgen.net/npm/dt/btc-rpc-explorer?icon=npm&cache=300&label=total%20downloads
-

app.js

@@ -513,9 +513,14 @@ async function onRpcConnectionVerified(getnetworkinfo, getblockchaininfo) {
 		global.pruneHeight = getblockchaininfo.pruneheight;
 	}
 
+	if (global.coinConfig.rpcSemverOverride) {
+		global.btcNodeVersion = getnetworkinfo.subversion;
+		global.btcNodeSemver = global.coinConfig.rpcSemverOverride;
+	}
+
 	var bitcoinCoreVersionRegex = /^.*\/Satoshi\:(.*)\/.*$/;
 
-	var match = bitcoinCoreVersionRegex.exec(getnetworkinfo.subversion);
+	var match = global.coinConfig.rpcSemverOverride ? null : bitcoinCoreVersionRegex.exec(getnetworkinfo.subversion);
 	if (match) {
 		global.btcNodeVersion = match[1];
 
@@ -547,7 +552,7 @@ async function onRpcConnectionVerified(getnetworkinfo, getblockchaininfo) {
 				global.btcNodeSemver = "1000.1000.0"
 			}
 		}
-	} else {
+	} else if (!global.coinConfig.rpcSemverOverride) {
 		// short-circuit: force all RPC calls to pass their version checks - this will likely lead to errors / instability / unexpected results
 		global.btcNodeSemver = "1000.1000.0"
 

app/coins.js

@@ -1,9 +1,11 @@
 "use strict";
 
 const btc = require("./coins/btc.js");
+const qbit = require("./coins/qbit.js");
 
 module.exports = {
 	"BTC": btc,
+	"QBT": qbit,
 
-	"coins":["BTC"]
-};
+	"coins":["BTC", "QBT"]
+};