BTC RPC Explorer: Blake2b fork

Self-hosted explorer for the BLAKE2b chain of Bitcoin Knots.

This is a self-hosted explorer driven by RPC calls to your own Bitcoin Knots node. It is a fork of BTC RPC Explorer by Dan Janosik (MIT license), adapted to the chain that Knots follows since its BLAKE2b hard fork. It is easy to run and lacks some features compared to database-backed explorers.

Whatever reasons you may have for running a full node (trustlessness, technical curiosity, supporting the network, etc) it's valuable to appreciate the fullness of your own node. With this explorer you can explore the blockchain, and also the functional capabilities of your own node.

What is different from upstream

• Reads difficulty_blake2b as well as difficulty (Knots reports the former for BLAKE2b blocks).
• Sends the blake2b rule with getblocktemplate, which Knots requires on this chain.
• The block page shows the extended BLAKE2b header fields (nonce2, nonce3, extranonce, time offset, flags).
• The difficulty history shows the work per block (the expected number of hashes) so that the SHA-256d and BLAKE2b epochs are on one scale: the BLAKE2b difficulty of Knots already is that number, and the SHA-256d difficulty is multiplied by 2^48 / 0xffff. The fall at the fork is visible, and marked.
• No hashrate is reported for a window that reaches back before the fork, for the same reason.
• The node details page shows the BLAKE2b fork height and whether it has taken effect.
• The charts of the transaction stats and the difficulty history mark the fork (a dashed line; grey before it, red after it).
• A hand-maintained list identifies the miners seen on this chain (public/txt/mining-pools-configs-custom/).
• Red theme and the Blake2b name.
• Safer defaults: production mode, verified Electrum certificates, CSRF protection, rate-limited logins, security headers, and the RPC tools and admin pages only behind the password. See "Security" below.
• TypeScript, a build step, tests that run the whole explorer, and a Docker image.

Blocks up to the fork are shared with Bitcoin. From the fork on, blocks use BLAKE2b proof of work and difficulty is the expected number of hashes per block.

Features

• Network summary dashboard
• View details of blocks, transactions, and addresses
• Analysis tools for viewing stats on blocks, transactions, and miner activity
• JSON REST API
• See raw JSON content from bitcoind used to generate most pages
• Search by transaction ID, block hash/height, and address
• Optional transaction history for addresses by querying one or more Electrum-protocol servers (e.g. Fulcrum, Electrs, ElectrumX); with several, the answers are compared and a disagreement is shown
• Mempool summary, with fee, size, and age breakdowns
• RPC command browser and terminal

Changelog / Release notes

See CHANGELOG.md: the release notes of this fork start at 4.0.0 (read "Upgrading" there when you come from upstream), and upstream's history follows. Changes to the public API are in CHANGELOG-API.md.

Getting started

Prerequisites

1. A Bitcoin Knots node on the BLAKE2b chain (v29.4.2 or later), with its RPC server enabled (server=1).
2. Let the node synchronize (you can use this tool while synchronizing, but some pages may fail).
3. Node.js 20+ (22+ recommended).
4. Optional, for address history: an Electrum-protocol server for the same chain, such as a Fulcrum build that follows it.

Note about pruning and indexing

This tool works best with full transaction indexing enabled (txindex=1) and pruning disabled. You can run without txindex and/or with pruning, and the tool will continue to function, but some data will be incomplete or missing.

With pruning enabled and/or txindex disabled:

• You will only be able to search for mempool, recently confirmed, and wallet transactions by their txid.
• Pruned blocks will display basic header information, without the list of transactions.
• The address and amount of previous transaction outputs will not be shown, only the txid:vout.
• The mining fee will only be available for unconfirmed transactions.

For the UTXO set page, the node can also keep the coin statistics index (coinstatsindex=1 in bitcoin.conf; restart the node, wait until bitcoin-cli getindexinfo shows it as synced, then restart the explorer). It is optional: without it the page works but builds its snapshot more slowly and says so; with it the explorer uses it automatically.

Install / Run

git clone https://github.com/2rdzy/btc-rpc-explorer
cd btc-rpc-explorer
npm ci
npm run build
npm start

The app is then at http://127.0.0.1:3002/. Views are cached, so restart after editing a template.

The code runs from dist/, which npm run build compiles with TypeScript. Run npm run build again after every update (and after npm run css), then restart. npm ci installs the dev dependencies the build needs; to keep a smaller install, build first and then run npm prune --omit=dev. Errors show the original source file and line, because npm start runs Node with --enable-source-maps.

Configuration

Set options with environment variables or CLI arguments.

Environment variables

Create one of these files and enter values in it:

1. ~/.config/btc-rpc-explorer.env
2. .env in the working directory

See .env-sample for all options. A typical .env for a local node with cookie authentication and a Fulcrum server:

BTCEXP_HOST=127.0.0.1
BTCEXP_PORT=3002

BTCEXP_BITCOIND_HOST=127.0.0.1
BTCEXP_BITCOIND_PORT=8332
BTCEXP_BITCOIND_COOKIE=/path/to/.cookie

BTCEXP_ADDRESS_API=electrum
BTCEXP_ELECTRUM_SERVERS=tls://your-fulcrum-host:50002
BTCEXP_ELECTRUM_TXINDEX=true

Notes:

• The cookie file is regenerated every time bitcoind restarts. Copy it again after a restart.
• Electrum servers over tls:// are verified. A server with a self-signed certificate (Fulcrum's default) needs its fingerprint in BTCEXP_ELECTRUM_TLS_FINGERPRINT (get it with openssl x509 -in cert.pem -noout -fingerprint -sha256), or its certificate in BTCEXP_ELECTRUM_TLS_CA. See .env-sample. With several servers, the address page shows what most of them say and warns when they differ.
• To use a node on another machine without opening its RPC port, forward it over SSH: ssh -N -L 8332:127.0.0.1:8332 user@node-host, then point BTCEXP_BITCOIND_HOST at 127.0.0.1.

CLI arguments

Run node dist/bin/cli.js --help for the full list, for example:

node dist/bin/cli.js --port 8080 --bitcoind-port 8332 --bitcoind-cookie ~/.bitcoin/.cookie

SSO authentication

You can configure SSO authentication similar to what ThunderHub and RTL provide. To enable it, make sure BTCEXP_BASIC_AUTH_PASSWORD is not set and set BTCEXP_SSO_TOKEN_FILE to point to a file write-accessible by btc-rpc-explorer. Your SSO provider then needs to read the token from this file and set it in the URL parameter token. The token changes with each login, so the provider needs to read it each time.

After successful access with the token, a cookie is set for authentication. To redirect users to your login page when needed, set BTCEXP_SSO_LOGIN_REDIRECT_URL.

Run via Docker

1. docker build -t btc-rpc-explorer .
2. docker run -d --name btc-rpc-explorer --network host --env-file .env -v /path/to/.cookie:/path/to/.cookie:ro btc-rpc-explorer (with --network host the explorer reaches a node on the same machine as 127.0.0.1; otherwise publish the port with -p 127.0.0.1:3002:3002 and point BTCEXP_BITCOIND_HOST at an address the container can reach)

The image holds no settings: they come from --env-file (.env and the caches are left out of the build by .dockerignore). It runs as the unprivileged user node, so the cookie file has to be readable by user id 1000. See also docker-compose.yml and docs/Server-Setup-Docker.md.

Security

• The explorer is meant for your own node. It binds to 127.0.0.1 by default; to reach it from elsewhere put it behind a reverse proxy with HTTPS (below) and set BTCEXP_BASIC_AUTH_PASSWORD.
• The RPC browser, the RPC terminal and the admin pages are only served when the password is set and given. Without it they show a message instead. What the RPC tools can run is limited by BTCEXP_RPC_BLACKLIST (see .env-sample).
• The pages need the node's RPC login: prefer the cookie file (BTCEXP_BITCOIND_COOKIE) to a password in the environment, and never expose the RPC port of the node itself.
• Set BTCEXP_PRIVACY_MODE=true (the default is false) when you do not want the explorer to ask external services for exchange rates, IP locations and the like.
• Found a vulnerability? Please report it privately, through the "Report a vulnerability" option under the Security tab of the repository, not in a public issue.

Reverse proxy with HTTPS

See docs/nginx-reverse-proxy.md for nginx and certbot (Let's Encrypt), and docs/Server-Setup.md for a full server walkthrough.

Development

• npm test runs the tests (TypeScript is loaded with tsx), npm run lint runs ESLint (with typescript-eslint), and npm run typecheck type-checks everything with TypeScript. CI runs all three, and builds.
• TypeScript. All of the code is TypeScript, and is checked with strict and with no tolerance (tsconfig.json): app.ts, routes/, bin/, app/ (including the coin data in app/coins/), docs/api.ts and the tests in test/. What the node returns is JSON that varies by RPC method and node version, so it is typed loosely as RpcData (app/api/rpcApi.ts), and the types get tighter where a use needs it. Shared helpers are in app/helpers/, and app/utils.ts re-exports them for the code that has always imported from there. Two things to know about the order of imports: app.ts and bin/cli.ts run code between their imports on purpose (the .env files and command line settings must be in the environment before config loads), and tsc keeps the imports where they are written, so do not sort them. In the tests, test/helpers/setup.ts must be the first import of a file for the same reason.
• The only JavaScript left is eslint.config.js and what is served to the browser from public/.
• test/pages.test.ts starts the whole explorer (built with tsc, as a separate process) against a fake node, and requests about 150 pages and endpoints over HTTP (test/fixtures/pages.ts). The fake node answers questions about the chain (blocks, transactions, ...) from a recording of a real node (test/fixtures/rpc.json: public chain data), and what belongs to a node (peers, addresses, mempool, block template, uptime, ...) from made-up answers (test/fixtures/nodeSpecific.ts). When a change makes a page ask for something that is in neither, the test names the call: record again with BTCEXP_RECORD_COOKIE_FILE=/path/to/.cookie npm run record-fixtures (it needs a node; only chain data is kept, and long lists are cut) or add a made-up answer.
• Tests and the type check run on the source. The app itself runs from dist/: npm run build && npm start. Files that are not code (views/, public/, the changelogs) are read from the project root, found by app/paths.js, so do not use __dirname to reach them.
• npm run css rebuilds the three theme stylesheets from public/scss/ and rewrites the integrity hashes in app/resourceIntegrityHashes.ts. Commit the compiled *.min.css files and the hashes together, or browsers will reject the stylesheets.
• npm run miners downloads the upstream mining pool lists (it runs the built dist/bin/refresh-mining-pool-configs.js, so build first). It does not touch public/txt/mining-pools-configs-custom/.

Credits

The explorer is the work of Dan Janosik and the contributors to BTC RPC Explorer, whose design, pages and most of the features are what you see here. This fork adds, among other things:

• support for the BLAKE2b chain of Bitcoin Knots (see "What is different from upstream" above);
• the red theme and the rebrand;
• security work: CSRF protection with csrf-sync, a limit on failed logins, TLS verification and pinning for Electrum servers, no credentials in cache keys, dependency upgrades;
• the whole code base in strict TypeScript, with a build step, around 460 tests, lint, CI and a Docker image that holds no settings.

Fixes that apply to the upstream project too are welcome there as well.

License

MIT. See LICENSE. Original work by Dan Janosik; changes in this fork by its contributors.