🎉 Microbolt 2.0 is out! Read more →
DocumentationBitcoinBlockchain explorerBTC RPC Explorer

BTC RPC Explorer

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

BTC RPC Explorer home screen with dark theme

Preparations

Transaction indexing

For the BTC RPC Explorer to work, you need your full node to index all transactions.

  • If you followed this guide, the transaction index parameter is already enabled (txindex=1), and you can skip to the next section.
  • If this is not the case, you need to set the txindex=1 parameter in your Bitcoin client configuration file (bitcoin.conf): Bitcoin node configuration.
  • After adding the parameter, restart Bitcoin client, which will now index the whole blockchain
$SU rc-service bitcoind restart

Please note that reindexing can take more than a day. You can follow the progress using

tail -f /var/log/bitcoind/debug.log

Install dependencies

  • Install Node.js using the apk package manager.

These are build dependencies (safe to remove after installation, if you want)

$SU apk add --virtual .build-deps git gnupg npm

These are runtime dependencies

$SU apk add nodejs-current

Create the btc-rpc-explorer user/group

$SU addgroup -S btc-rpc-explorer
$SU adduser \
    -S \
    -D \
    -H \
    -h /dev/null \
    -s /sbin/nologin \
    -G btc-rpc-explorer \
    -g btc-rpc-explorer \
    btc-rpc-explorer

Add btc-rpc-explorer user to the bitcoin group

$SU adduser btc-rpc-explorer bitcoin

Add satoshi user to the btc-rpc-explorer group

$SU adduser satoshi btc-rpc-explorer

Reverse proxy

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

  • Enable the reverse proxy to route external encrypted HTTPS traffic internally to the BTC RPC Explorer
$SU $EDITOR /etc/caddy/sites/btc-rpc-explorer.caddy
/etc/caddy/sites/btc-rpc-explorer.caddy
:4000 {
        import tls
        reverse_proxy 127.0.0.1:3002
}
  • Reload Caddy
$SU rc-service caddy reload

Firewall

  • Configure the firewall to allow incoming HTTPS requests
$SU $EDITOR /etc/awall/optional/btcrpcexpl.json
/etc/awall/optional/btcrpcexpl.json
{
  "description": "Allow BTC RPC Explorer SSL",
 
  "filter": [
    {
      "in": "internet",
      "out": "_fw",
      "service": { "proto": "tcp", "port": 4000 },
      "action": "accept",
      "conn-limit": { "count": 10, "interval": 60 }
    }
  ]
}
  • Enable it
$SU awall enable btcrpcexpl
$SU awall activate

Installation

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 client and Electrum server via RPC.

Download source code

We get the latest release of the BTC RPC Explorer source code and install it.

  • Download the source code for the latest BTC RPC Explorer release. You can check the release page to see if a newer release is available. Other releases might not have been properly tested with the rest of the Microbolt configuration, though.
cd /tmp
VERSION=3.4.0
git clone --branch v$VERSION https://github.com/janoside/btc-rpc-explorer.git && cd btc-rpc-explorer

Signature check

  • To avoid using bad source code, verify that the release has been properly signed by the main developer Dan Janosik.
wget -qO- https://github.com/janoside.gpg | gpg --import
git verify-commit v$VERSION

Configure, patch and install

sed '/"node_modules\/sharp": {/,+21{d}; /sharp/d' npm-shrinkwrap.json > _
mv -f _ npm-shrinkwrap.json
  • Install all dependencies using the Node Package Manager (NPM).
npm ci
npm i zeromq@latest
npm audit fix

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

output
up to date, audited 621 packages in 3s

93 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
  • Make it a global permanent installation
$SU install -D -m 0660 -o btc-rpc-explorer -g btc-rpc-explorer ./.env-sample /etc/btc-rpc-explorer/btc-rpc-explorer.env
$SU mv -f /tmp/btc-rpc-explorer /var/lib/
$SU ln -s /var/lib/btc-rpc-explorer /usr/lib/node_modules/btc-rpc-explorer
$SU ln -s ../lib/node_modules/btc-rpc-explorer/bin/cli.js /usr/bin/btc-rpc-explorer

Cleanup

cd
rm -rf /tmp/btc-rpc-explorer
$SU apk del .build-deps

Configuration

  • Activate any setting by removing the # at the beginning of the line.
$EDITOR /etc/btc-rpc-explorer/btc-rpc-explorer.env
/etc/btc-rpc-explorer/btc-rpc-explorer.env
[...]
BTCEXP_BITCOIND_HOST=127.0.0.1
[...]
BTCEXP_BITCOIND_PORT=8332
[...]
BTCEXP_BITCOIND_COOKIE=/var/lib/bitcoind/.cookie
[...]
BTCEXP_ADDRESS_API=electrum
[...]
BTCEXP_ELECTRUM_SERVERS=tcp://127.0.0.1:50001
[...]
BTCEXP_SLOW_DEVICE_MODE=false
[...]
BTCEXP_UI_THEME={dark|light} # Choose one
[...]
Slow device mode
/etc/btc-rpc-explorer/btc-rpc-explorer.env
[...]
BTCEXP_BITCOIND_RPC_TIMEOUT=10000
[...]
BTCEXP_SLOW_DEVICE_MODE=true
[...]
Privacy mode
  • More information mode, including Bitcoin exchange rates:
/etc/btc-rpc-explorer/btc-rpc-explorer.env
[...]
BTCEXP_PRIVACY_MODE=false
[...]
BTCEXP_NO_RATES=false
[...]
  • More privacy mode, no external queries:
/etc/btc-rpc-explorer/btc-rpc-explorer.env
[...]
BTCEXP_PRIVACY_MODE=true
[...]
BTCEXP_NO_RATES=true
[...]
Security mode
  • You can add password protection to the web interface. Simply add 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.
/etc/btc-rpc-explorer/btc-rpc-explorer.env
[...]
BTCEXP_DEMO=true
[...]
BTCEXP_BASIC_AUTH_PASSWORD=YourPassword[D]
[...]
Remote access over Tor

To use your blockchain explorer when you’re on the go, you can easily create a Tor hidden service on the Microbolt and accessing the BTC RPC Explorer with the Tor browser from any device.

  • Add the following three lines in the “location-hidden services” section in the torrc file.
$SU $EDITOR /etc/tor/torrc
/etc/tor/torrc
# Hidden Service BTC RPC Explorer
HiddenServiceDir /var/lib/tor/btc-rpc-explorer/
HiddenServiceVersion 3
HiddenServicePoWDefensesEnabled 1
HiddenServicePort 443 127.0.0.1:4000
  • Reload Tor configuration and get your connection address.
$SU rc-service tor reload
$SU cat /var/lib/tor/btc-rpc-explorer/hostname
output
abcdefg..............xyz.onion
  • You should now be able to connect to your BTC RPC Explorer remotely via Tor using your hostname and port 4000

Autostart on boot

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

  • Create the BTC RPC Explorer init.d unit and copy/paste the following configuration. Save and exit.
$SU $EDITOR /etc/init.d/btc-rpc-explorer
/etc/init.d/btc-rpc-explorer
#!/sbin/openrc-run
 
: ${BTCRPCEXPL_ENVFILE:=/etc/btc-rpc-explorer/btc-rpc-explorer.env}
: ${BTCRPCEXPL_DATADIR:=/var/lib/btc-rpc-explorer}
: ${BTCRPCEXPL_LOGDIR:=/var/log/btc-rpc-explorer}
: ${BTCRPCEXPL_USER:=btc-rpc-explorer}
: ${BTCRPCEXPL_GROUP:=btc-rpc-explorer}
: ${BTCRPCEXPL_BIN:=/usr/bin/btc-rpc-explorer}
: ${BTCRPCEXPL_OPTS=${BTCRPCEXPL_OPTS}}
: ${BTCRPCEXPL_SIGTERM_TIMEOUT:=600}
 
BTCRPCEXPL_PIDDIR="/run/btc-rpc-explorer"
 
name="BTC RPC Explorer"
description="Simple, database-free Bitcoin blockchain explorer, via RPC to Bitcoin Core"
 
directory="${BTCRPCEXPL_DATADIR}"
required_files="${BTCRPCEXPL_ENVFILE}"
pidfile="${BTCRPCEXPL_PIDDIR}/${SVCNAME}.pid"
retry="${BTCRPCEXPL_SIGTERM_TIMEOUT}"
 
command="${BTCRPCEXPL_BIN}"
command_args="${BTCRPCEXPL_OPTS}"
command_user="${BTCRPCEXPL_USER}:${BTCRPCEXPL_GROUP}"
command_background="true"
 
start_stop_daemon_args="--stdout ${BTCRPCEXPL_LOGDIR}/debug.log
                        --stderr ${BTCRPCEXPL_LOGDIR}/debug.log"
 
depend() {
    need bitcoind
 
    if service_started fulcrum; then
        need fulcrum
    elif service_started electrs; then
        need electrs
    else
        if service_exists fulcrum; then
            need fulcrum
        elif service_exists electrs; then
            need electrs
        else
            eerror "Neither fulcrum nor electrs is installed or started"
            return 1
        fi
    fi
}
 
service_exists() {
    rc-service --list | grep -q "^$1$"
}
 
start_pre() {
    checkpath --file      --mode 0660 --owner "${command_user}" "${BTCRPCEXPL_ENVFILE}"
    checkpath --directory --mode 0750 --owner "${command_user}" "${BTCRPCEXPL_DATADIR}"
    checkpath --directory --mode 0755 --owner "${command_user}" "${BTCRPCEXPL_LOGDIR}"
    checkpath --directory --mode 0755 --owner "${command_user}" "${BTCRPCEXPL_PIDDIR}"
    checkconfig
}
 
checkconfig() {
    if ! grep -qs '^BTCEXP_BITCOIND_COOKIE=' "${BTCRPCEXPL_ENVFILE}"
    then
        eerror ""
        eerror "ERROR: You must set a BTCEXP_BITCOIND_COOKIE path to run"
        eerror "BTC RPC Explorer."
        eerror "The setting must appear in ${BTCRPCEXPL_ENVFILE}"
        eerror ""
        return 1
    fi
}
  • Enable execution permission
$SU chmod +x /etc/init.d/btc-rpc-explorer

Enable logrotate

  • Enter the complete next configuration. Save and exit
$SU $EDITOR /etc/logrotate.d/btc-rpc-explorer
/etc/logrotate.d/btc-rpc-explorer
/var/log/btc-rpc-explorer/*.log {
    weekly
    missingok
    rotate 104
    compress
    delaycompress
    notifempty
    create 0640 btc-rpc-explorer btc-rpc-explorer
    sharedscripts
    postrotate
        killall -HUP `cat /run/btc-rpc-explorer/btc-rpc-explorer.pid`
    endscript
}
  • Test
$SU logrotate /etc/logrotate.d/btc-rpc-explorer --debug

Enable and start BTC RPC Explorer

$SU rc-update add btc-rpc-explorer
$SU rc-service btc-rpc-explorer start
  • Check the log to see BTC RPC Explorer output. Exit with Ctrl-C
tail -f /var/log/btc-rpc-explorer/debug.log
  • You can now access your own BTC RPC Explorer from within your local network by browsing to https://nakamoto01:4000 (or your equivalent IP address).

For the future: BTC RPC Explorer update

Follow again BTC RPC Explorer page replacing the environment variable VERSION=x.xx value for the latest if it has not been already changed in this guide.

  • Update the BTC RPC Explorer configuration if necessary (see release notes)
$SU $EDITOR /etc/btc-rpc-explorer/btc-rpc-explorer.env
  • Restart the service to apply the changes
$SU rc-service btc-rpc-explorer restart
Mempool SpaceMining Pool