2.3 Blockchain explorer: BTC RPC Explorer

Run your own private blockchain explorer with BTC RPC Explorer. Trust your node, not some external services.

Requirements

Introduction

After the MiniBolt runs your own fully validated node, and even acts as a backend for your hardware wallet with Fulcrum, the last important puzzle piece to improve privacy and financial sovereignty is your own Blockchain Explorer. It lets you query transactions, addresses, and blocks of your choice. You no longer need to leak information by querying a third-party blockchain explorer that can be used to get your location and cluster addresses.

BTC RPC Explorer provides a lightweight and easy to use web interface to accomplish just that. It's a database-free, self-hosted Bitcoin blockchain explorer, querying Bitcoin Core and Fulcrum via RPC.

Preparations

Install Node + NPM

  • With user admin, check if you have already installed Node

node -v

Example of expected output:

> v18.16.0
  • Check if you have already installed NPM

npm -v

Example of expected output:

> 9.5.1

If the version is >=18, you can move to the next section. If Nodejs is not installed, follow this Node + NPM bonus guide to install it

  • Install the next dependency package. Press "y" and enter or directly enter when the prompt asks you

sudo apt install build-essential

Reverse proxy & Firewall

In the security section, we set up Nginx as a reverse proxy. Now we can add the BTC RPC Explorer configuration.

Enable the Nginx reverse proxy to route external encrypted HTTPS traffic internally to the BTC RPC Explorer. The error_page 497 directive instructs browsers that send HTTP requests to resend them over HTTPS.

  • With user admin, create the reverse proxy configuration

sudo nano /etc/nginx/sites-available/btcrpcexplorer-reverse-proxy.conf
  • Paste the complete following configuration. Save and exit

server {
  listen 4000 ssl;
  error_page 497 =301 https://$host:$server_port$request_uri;
  location / {
    proxy_pass http://127.0.0.1:3002;
  }
}
  • Create the symbolic link that points to the directory sites-enabled

sudo ln -s /etc/nginx/sites-available/btcrpcexplorer-reverse-proxy.conf /etc/nginx/sites-enabled/
  • Test Nginx configuration

sudo nginx -t

Expected output:

> nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
> nginx: configuration file /etc/nginx/nginx.conf test is successful
  • Reload the Nginx configuration to apply changes

sudo systemctl reload nginx
  • Configure the firewall to allow incoming HTTPS requests

sudo ufw allow 4000/tcp comment 'allow BTC RPC Explorer SSL from anywhere'

Installation

For improved security, we will create a new user btcrpcexplorer that will run the block explorer. Using a dedicated user limits potential damage in case there's a security vulnerability in the code. An attacker would not be able to do much within this user's permission settings.

  • Create a new one called btcrpcexplorer user

sudo adduser --disabled-password --gecos "" btcrpcexplorer
  • Assign it to the "bitcoin" group

sudo adduser btcrpcexplorer bitcoin
  • Change to the new btcrpcexplorer user

sudo su - btcrpcexplorer
  • Set a temporary version environment variable to the installation

VERSION=3.4.0
  • Import the GPG key of the developer

curl https://github.com/janoside.gpg | gpg --import
  • Download the source code directly from GitHub and go to the btc-rpc-explorer folder

git clone --branch v$VERSION https://github.com/janoside/btc-rpc-explorer.git && cd btc-rpc-explorer
  • Verify the release

git verify-commit v$VERSION

Example of expected output:

gpg: Signature made Wed Jun 14 15:18:11 2023 CEST
gpg:                using EDDSA key 4D841E6E6B1B68EBFAB4A9E670C0B166321C0AF8
gpg: Good signature from "Dan Janosik <[email protected]>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 4D84 1E6E 6B1B 68EB FAB4  A9E6 70C0 B166 321C 0AF8
  • Install all dependencies using NPM

npm install

Installation can take some time, be patient. There might be a lot of confusing output, but if you see something similar to the following, the installation was successful

Example of expected output:

> Installed to /home/btcrpcexplorer/btc-rpc-explorer/node_modules/node-sass/vendor/linux-amd64-83/binding.node
> added 480 packages from 307 contributors and audited 482 packages in 570.14s
>
> 43 packages are looking for funding
>   run `npm fund` for details
>
> found 12 vulnerabilities (8 moderate, 4 high)
>   run `npm audit fix` to fix them, or `npm audit` for details
  • Check the correct installation by requesting the version

head -n 3 /home/btcrpcexplorer/btc-rpc-explorer/package.json | grep version

Example of expected output:

> "version": "3.4.0",

Configuration

  • Copy the configuration template

cp .env-sample .env
  • Edit the .env file.

nano .env

Activate any setting by removing the # at the beginning of the line or editing directly

  • Instruct the BTC RPC Explorer to connect to the local Bitcoin Core

# Uncomment & replace the value of these lines
BTCEXP_BITCOIND_COOKIE=/data/bitcoin/.cookie
  • To get address balances, either an Electrum server or an external service is necessary. Your local Electrum server can provide address transaction lists, balances, and more

# Uncomment & replace the value of these lines
BTCEXP_ADDRESS_API=electrum
BTCEXP_ELECTRUM_SERVERS=tcp://127.0.0.1:50001
  • Uncomment this line

BTCEXP_SLOW_DEVICE_MODE=false

You can set additional features of Privacy / Security and customize the Theme at this moment by going to the Extra section

  • Save and exit

  • Exit the btcrpcexplorer user session to return to the admin user session

exit

Create systemd service

Now we'll make sure our blockchain explorer starts as a service on the PC so that it's always running.

  • As user admin, create the service file

sudo nano /etc/systemd/system/btcrpcexplorer.service
  • Paste the following configuration. Save and exit

# MiniBolt: systemd unit for BTC RPC Explorer
# /etc/systemd/system/btcrpcexplorer.service

[Unit]
Description=BTC RPC Explorer
Requires=bitcoind.service fulcrum.service
After=bitcoind.service fulcrum.service

[Service]
WorkingDirectory=/home/btcrpcexplorer/btc-rpc-explorer
ExecStart=/usr/bin/npm start

User=btcrpcexplorer
Group=btcrpcexplorer

# Hardening Measures
####################
PrivateTmp=true
ProtectSystem=full
NoNewPrivileges=true
PrivateDevices=true

[Install]
WantedBy=multi-user.target
  • Enable autoboot (optional)

sudo systemctl enable btcrpcexplorer
  • Prepare "btcrpcexplorer" monitoring by the systemd journal and check log logging output. You can exit monitoring at any time with Ctrl-C

journalctl -fu btcrpcexplorer

Run

To keep an eye on the software movements, start your SSH program (eg. PuTTY) a second time, connect to the MiniBolt node, and log in as "admin"

  • Start the service

sudo systemctl start btcrpcexplorer
Example of expected output on the first terminal with journalctl -fu btcrpcexplorer ⬇️
Jul 18 11:08:29 minibolt systemd[1]: Started BTC RPC Explorer.
Jul 18 11:08:30 minibolt npm[140449]: > [email protected] start
Jul 18 11:08:30 minibolt npm[140449]: > node ./bin/www
Jul 18 11:08:30 minibolt npm[140461]: 2023-07-18T11:08:30.765Z btcexp:app Searching for config files...
Jul 18 11:08:30 minibolt npm[140461]: 2023-07-18T11:08:30.767Z btcexp:app Config file not found at /home/btcrpcexplorer/.config/btc-rpc-explorer.env, continuing...
Jul 18 11:08:30 minibolt npm[140461]: 2023-07-18T11:08:30.767Z btcexp:app Config file not found at /etc/btc-rpc-explorer/.env, continuing...
Jul 18 11:08:30 minibolt npm[140461]: 2023-07-18T11:08:30.767Z btcexp:app Config file found at /home/btcrpcexplorer/btc-rpc-explorer/.env, loading...
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.086Z btcexp:app Default cacheId '3.4.0'
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.122Z btcexp:app Enabling view caching (performance will be improved but template edits will not be reflected)
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.133Z btcexp:app Session config: {"secret":"*****","resave":false,"saveUninitialized":true,"cookie":{"secure":false}}
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.142Z btcexp:app Environment(development) - Node: v18.16.1, Platform: linux, Versions: {"node":"18.16.1","acorn":"8.8.2","ada":"1.0.4","ares":"1.19.1","brotli":"1.0.9","cldr":"42.0","icu":"72.1","llhttp":"6.0.11","modules":"108","napi":"8","nghttp2":"1.52.0","nghttp3":"0.7.0","ngtcp2":"0.8.1","openssl":"3.0.9+quic","simdutf":"3.2.2","tz":"2022g","undici":"5.21.0","unicode":"15.0","uv":"1.44.2","uvwasi":"0.0.15","v8":"10.2.154.26-node.26","zlib":"1.2.13"}
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.193Z btcexp:app Using sourcecode metadata as cacheId: '2023-06-14-bfc9f97715'
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.193Z btcexp:app Starting BTC RPC Explorer, v3.4.0 (commit: 'bfc9f97715', date: 2023-06-14) at http://127.0.0.1:3002/
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.194Z btcexp:app RPC Credentials: {
Jul 18 11:08:33 minibolt npm[140461]:     "host": "127.0.0.1",
Jul 18 11:08:33 minibolt npm[140461]:     "port": "8332",
Jul 18 11:08:33 minibolt npm[140461]:     "authType": "cookie",
Jul 18 11:08:33 minibolt npm[140461]:     "username": "__cookie__",
Jul 18 11:08:33 minibolt npm[140461]:     "password": "*****",
Jul 18 11:08:33 minibolt npm[140461]:     "authCookieFilepath": "/data/bitcoin/.cookie",
Jul 18 11:08:33 minibolt npm[140461]:     "timeout": 5000
Jul 18 11:08:33 minibolt npm[140461]: }
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.194Z btcexp:app Connecting to RPC node at [127.0.0.1]:8332
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.195Z btcexp:app RPC Connection properties: {
Jul 18 11:08:33 minibolt npm[140461]:     "host": "127.0.0.1",
Jul 18 11:08:33 minibolt npm[140461]:     "port": "8332",
Jul 18 11:08:33 minibolt npm[140461]:     "username": "__cookie__",
Jul 18 11:08:33 minibolt npm[140461]:     "password": "*****",
Jul 18 11:08:33 minibolt npm[140461]:     "timeout": 5000
Jul 18 11:08:33 minibolt npm[140461]: }
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.196Z btcexp:app RPC authentication is cookie based; watching for changes to the auth cookie file...
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.198Z btcexp:app Verifying RPC connection...
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.201Z btcexp:app Loading mining pools config
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.365Z btcexp:app RPC Connected: version=250000 subversion=/Satoshi:25.0.0/, parsedVersion(used for RPC versioning)=25.0.0, protocolversion=70016, chain=main, services=[NETWORK, BLOOM, WITNESS, COMPACT_FILTERS, NETWORK_LIMITED]
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.365Z btcexp:app Loading historical data for chain=main
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.365Z btcexp:app Loading holiday data
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.370Z btcexp:app txindex check: trying getindexinfo
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.371Z btcexp:app ATH difficulty: 53911173001054.59
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.376Z btcexp:app txindex check: getindexinfo={"txindex":{"synced":true,"best_block_height":799232},"coinstatsindex":{"synced":true,"best_block_height":799232},"basic block filter index":{"synced":true,"best_block_height":799232}}
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.377Z btcexp:app txindex check: available!
Jul 18 11:08:33 minibolt npm[140461]: 2023-07-18T11:08:33.426Z btcexp:app Refreshed utxo summary: {"height":799232,"bestblock":"00000000000000000000882023825176273fb8ae3ba10ab5e7bccb3f1d7e7a49","txouts":110323290,"bogosize":8350852748,"muhash":"a4a8e5dd85de604fe5c05ef0018b4eec06f5cf475ed565fd7334828759f365b5","total_amount":19432486.84621219,"total_unspendable_amount":219.40378781,"block_info":{"prevout_spent":4444.44336697,"coinbase":6.32505263,"new_outputs_ex_coinbase":4444.36831434,"unspendable":0,"unspendables":{"genesis_block":0,"bip30":0,"scripts":0,"unclaimed_rewards":0}},"usingCoinStatsIndex":true,"lastUpdated":1689678513425}
Jul 18 11:08:35 minibolt npm[140461]: 2023-07-18T11:08:35.135Z btcexp:app Network volume: {"d1":{"amt":"947555.33623057","blocks":159,"startBlock":799232,"endBlock":799074,"startTime":1689678236,"endTime":1689592319}}

Now point your browser to the secure access point provided by the NGINX web proxy, for example, "https://minibolt.local:4000" (or your node IP address) like "https://192.168.x.xxx:4000". You should see the home page of BTC RPC Explorer

Your browser will display a warning because we use a self-signed SSL certificate. We can do nothing about that because we would need a proper domain name (e.g. https://yournode.com) to get an official certificate that browsers recognize. Click on "Advanced" and proceed to the Block Explorer web interface

If you see a lot of errors on the MiniBolt command line, then Bitcoin Core might still be indexing the blockchain. You need to wait until reindexing is done before using the BTC RPC Explorer

  • Ensure the service is working and listening at the default 3002 port and the HTTPS 4000 port

sudo ss -tulpn | grep 'LISTEN.*\(4000\|3002\)'

Expected output:

> tcp   LISTEN 0      511          0.0.0.0:4000       0.0.0.0:*    users:(("nginx",pid=992796,fd=6),("nginx",pid=992795,fd=6),("nginx",pid=992794,fd=6),("nginx",pid=992793,fd=6),("nginx",pid=992792,fd=6))
> tcp   LISTEN 0      511        127.0.0.1:3002       0.0.0.0:*    users:(("node",pid=1241652,fd=26))

Congratulations! You now have the BTC RPC Explorer running to check the Bitcoin network information directly from your node

Extras (optional)

Privacy

You can decide whether you want to optimize for more information or more privacy.

  • With user admin user, edit the .env configuration file

sudo nano /home/btcrpcexplorer/btc-rpc-explorer/.env
  • More information mode, including Bitcoin exchange rates

# replace these lines
BTCEXP_PRIVACY_MODE=false
BTCEXP_NO_RATES=false
  • More privacy mode, no external queries

# uncomment these lines
BTCEXP_PRIVACY_MODE=true
BTCEXP_NO_RATES=true
  • Save and exit

Security

You can add password protection to the web interface. Simply add your password [D] for the following option, for which the browser will then prompt you. You can enter any user name; only the password is checked

  • With user admin user, edit the .env configuration file

sudo nano /home/btcrpcexplorer/btc-rpc-explorer/.env
  • Replace the next line. Save and exit

# replace `mypassword` with 'YourPassword [D] in this line
BTCEXP_BASIC_AUTH_PASSWORD=YourPassword [D]

Theme

Decide whether you prefer a light or dark theme by default. Left uncommented to dark (default dark)

  • With user admin user, edit the .env configuration file

sudo nano /home/btcrpcexplorer/btc-rpc-explorer/.env
  • Uncomment and replace this line with your selection. Save and exit

BTCEXP_UI_THEME=dark

Slow device mode (resource-intensive features are disabled)

Extend the timeout period due to the limited resources

  • With user admin user, edit the .env configuration file

sudo nano /home/btcrpcexplorer/btc-rpc-explorer/.env
  • Uncomment and change the value of this line

BTCEXP_BITCOIND_RPC_TIMEOUT=10000
  • Comment this line if it is uncommented (default value is true). Save and exit

#BTCEXP_SLOW_DEVICE_MODE=false

Sharing your explorer

You may want to share your BTC RPC Explorer onion address with confident people and limited Bitcoin Core RPC access requests (sensitive data requests will be kept disabled, don't trust, verify. Enabling DEMO mode, you will not have to provide a password, and RPC requests will be allowed (discarding rpcBlacklist commands)

  • With user admin user, edit the .env configuration file

sudo nano /home/btcrpcexplorer/btc-rpc-explorer/.env
  • Uncomment this line

BTCEXP_DEMO=true

You will need to set password authentication following the Security section, if not, a banner shows you this:

RPC Terminal / Browser require authentication. Set an authentication password via the 'BTCEXP_BASIC_AUTH_PASSWORD' environment variable (see .env-sample file for more info).

--> Remember to give them the password [D] if you added password protection in the reference step

With DEMO mode enabled, the user will see the next message:

"Sorry, that RPC command is blacklisted. If this is your server, you may allow this command by removing it from the 'rpcBlacklist' setting in config.js."

Remote access over Tor

Do you want to access your personal blockchain explorer remotely? You can easily do so by adding a Tor hidden service on the MiniBolt and accessing the BTC RPC Explorer with the Tor browser from any device.

  • With the user admin , edit the torrc file

sudo nano /etc/tor/torrc
  • Add the following lines in the "location hidden services" section, below "## This section is just for location-hidden services ##" in the torrc file. Save and exit

# Hidden Service BTC RPC Explorer
HiddenServiceDir /var/lib/tor/hidden_service_btcrpcexplorer/
HiddenServiceVersion 3
HiddenServicePoWDefensesEnabled 1
HiddenServicePort 80 127.0.0.1:3002
  • Reload the Tor configuration

sudo systemctl reload tor
  • Get your Onion address

sudo cat /var/lib/tor/hidden_service_btcrpcexplorer/hostname

Example of expected output:

> abcdefg..............xyz.onion
  • With the Tor browser, you can access this onion address from any device

Upgrade

Updating to a new release is straightforward, but make sure to check out the change log first.

  • With admin user, stop the service

sudo systemctl stop btcrpcexplorer
  • Change to the btcrpcexplorer user

sudo su - btcrpcexplorer
  • Set a temporary version environment variable to the installation

VERSION=3.4.0
  • Go to the btc-rpc-explorer folder

cd btc-rpc-explorer
  • Fetch the latest GitHub repository information

git fetch
git reset --hard HEAD
  • Display the release tags (use the latest in this example)

git tag
git checkout v$VERSION
  • Install dependencies

npm install
  • Come back to the admin user

exit
  • Start the service again

sudo systemctl start btcrpcexplorer

Uninstall

Uninstall service & user

  • Ensure you are logged in with the user admin, stop, disable, and delete the service

sudo systemctl stop btcrpcexplorer
sudo systemctl disable btcrpcexplorer
sudo rm /etc/systemd/system/btcrpcexplorer.service
  • Ensure you are logged in with the user admin. Delete the btcrpcexplorer user. Don't worry about userdel: btcrpcexplorer mail spool (/var/mail/btcrpcexplorer) not found output, the uninstall has been successful

sudo userdel -rf btcrpcexplorer

Uninstall Tor hidden service

  • Ensure that you are logged in with the user admin and delete or comment on the following lines in the "location hidden services" section, below "## This section is just for location-hidden services ##" in the torrc file. Save and exit

sudo nano /etc/tor/torrc
# Hidden Service BTC RPC Explorer
#HiddenServiceDir /var/lib/tor/hidden_service_btcrpcexplorer/
#HiddenServiceVersion 3
#HiddenServicePoWDefensesEnabled 1
#HiddenServicePort 80 127.0.0.1:3002
  • Reload the tor to apply changes

sudo systemctl reload tor

Uninstall reverse proxy & FW configuration

  • Ensure you are logged in with the user admin, delete the reverse proxy config file

sudo rm /etc/nginx/sites-available/btcrpcexplorer-reverse-proxy.conf
  • Delete the simbolic link

sudo rm /etc/nginx/sites-enabled/btcrpcexplorer-reverse-proxy.conf
  • Test Nginx configuration

sudo nginx -t

Expected output:

> nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
> nginx: configuration file /etc/nginx/nginx.conf test is successful
  • Reload the Nginx configuration to apply changes

sudo systemctl reload nginx
  • Display the UFW firewall rules, and note the numbers of the rules for BTC RPC Explorer (e.g. "Y" below)

sudo ufw status numbered

Expected output:

> [Y] 4000       ALLOW IN    Anywhere      # allow BTC RPC Explorer SSL from anywhere
  • Delete the rule with the correct number and confirm with "yes"

sudo ufw delete X

Port reference

Last updated