Zcash Insight Blockchain Explorer

With the launch of 2.0.7, zcashd now includes full support for the Insight blockchain explorer. The Insight explorer, which will be familiar to those who have used one of the many popular block explorers it powers, was developed by Bitpay as part of its bitcore suite of tools. The tool, released under a permissive open-source license (MIT), contains many development tools to “build bitcoin and blockchain applications” but we will concentrate on installing the explorer portion for this article which has been ported to support Zcash.

The Insight block explorer on Zcash testnet

While there are existing implementations of the Insight explorer on Zcash it relies on running a patched version of zcashd. This caused issues with maintaining multiple versions which required regular updating as versions by default reach end of support halt and shut down every 16 weeks. In addition, the Blossom network upgrade will activate on testnet at height 584000 and so a compatible version of zcashd is required to follow the upgraded chain.

These updates to zcashd specifically include new fields to the getrawtransaction RPC call as well as a set of new RPC (CLI) methods that allow, for example, to get the balance of (transparent) addresses. While you can run zcashd in isolation to extract this information, the Insight explorer user interface presents the information in a visual and easily searchable way.

For the remainder of the article, we’ll walk through installing Insight explorer on an Ubuntu 18.04 machine, such as a local machine or VM (cloud-hosted or otherwise). I’ve tested these instructions successfully on a local machine as well as on a Digital Ocean cloud instance. As this is running zcashd in addition to other components, make sure you meet the minimum specs and allow some headroom in disk space to accommodate future growth of the chain (running zcashd in this manner will also increase the disk space used by the data directory).

The following installation is heavily based on the Dockerfile in the zcash-hackworks repository. Rather than assume Docker knowledge and detail additional requirements such as persistent data volumes (you’ll want to mount the zcash data directory and parameters), I’ll outline the process on Ubuntu 18.04 which can be easily adapted to a Dockerfile if necessary or deployed as is to a cloud VM.

Installation

For this tutorial, we will be running everything as the zcashd user. As some of the paths below are absolute, you will need to either create a new user of that name or simply update references to the zcashd user to your (non-root) username.

Installation consists of building zcashd (though this isn’t strictly required, as you could substitute the pre-built binaries), installing Node.js and pulling in the relevant Zcash ported bitcore packages and editing some configuration files.

To begin, we’ll start by pulling in the required dependencies for our zcashd build:

sudo apt update
sudo apt install -y gnupg2 wget libzmq3-dev git \
    build-essential pkg-config libc6-dev m4 g++-multilib \
    autoconf libtool ncurses-dev unzip git python \
    python-zmq zlib1g-dev curl bsdmainutils automake

Next, we’ll install Node.js. We’ll use version 8 as this has been confirmed to work and we’ll use the installation tool from nodesource.com. This script involves piping to bash with the sudo command so if you don’t want to proceed with this method simply follow the instructions for a manual installation.

curl -sL https://deb.nodesource.com/setup_8.x | sudo bash -
sudo apt-get install -y nodejs

To get around some node permissions issues on this version of Node.js we’ll use the following configuration:

mkdir -p /home/zcashd/.npm-global
export NPM_CONFIG_PREFIX=/home/zcashd/.npm-global

Finally, add the installation directory to our path so we can simplify references to the Node.js libraries later in the installation and apply these changes to the current shell (note these values won’t persist so if you don’t complete the installation in a single terminal you’ll need to add these environment values again or persist them e.g. using bashrc).

export PATH=/home/zcashd/.npm-global/bin:$PATH
source ~/.profile

Next, we’ll clone the zcash repo and checkout version 2.0.7. If version 2.0.7 isn’t available at the time of reading then install the release candidate v2.0.7-rc1. Update this version tag if a later version is available or remove this line entirely to build the current master.

git clone https://github.com/zcash/zcash.git
cd zcash
git checkout v2.0.7 # ignore the detached head message

Start the build and wait for it to complete:

./zcutil/build.sh -j$(nproc)

Next, we’ll download the Zcash proving and verifying keys which will be placed in ~/.zcash-params. These keys are just under 1.7GB.

./zcutil/fetch-params.sh

Now we’ll create a zcash conf file to complete the zcashd setup. Create a file using your favourite editor named zcash.conf in the ~/zcash directory (the following instructions use the nano editor).

mkdir -p ~/.zcash
cd ~/.zcash
nano zcash.conf

Use the following values to run on testnet (see this for mainnet configuration).

testnet=1
addnode=testnet.z.cash
server=1
whitelist=127.0.0.1
zmqpubrawtx=tcp://127.0.0.1:28332
zmqpubhashblock=tcp://127.0.0.1:28332
txindex=1
experimentalfeatures=1
insightexplorer=1
addressindex=1
timestampindex=1
spentindex=1
rpcport=18232
rpcallowip=127.0.0.1
rpcuser=<username>
rpcpassword=<secretpassword>
showmetrics=0
uacomment=bitcore

You can confirm that everything is working with the command ./src/zcashd —version which should output the version information you installed.

./src/zcashd --version
Zcash Daemon version v2.0.7

Now install npm and the bitcore-node-zcash library.

cd ~
sudo npm install -g [email protected]
npm install -g zcash-hackworks/bitcore-node-zcash
bitcore-node create zc

You should see the output like the following: Successfully created node in directory: zc. This final command creates a configuration file named bitcore-node.json in the zc directory that we will need to edit to match our installation.

cd zc
nano bitcore-node.json

Update this configuration to match the below, making a note of the port and also update the paths of the datadir and zcashd executable exec if you installed as a different user.

{
  "network": "testnet",
  "port": 3001,
  "services": [
    "bitcoind",
    "web"
  ],
  "servicesConfig": {
    "bitcoind": {
      "spawn": {
        "datadir": "/home/zcashd/.zcash",
        "exec": "/home/zcashd/zcash/src/zcashd"
      }
    },
    "insight-api-zcash": {
      "routePrefix": "api"
    },
    "insight-ui-zcash": {
      "apiPrefix": "api",
      "routePrefix": ""
    }
  }
}

Then install the Insight component from this zc directory.

bitcore-node install zcash-hackworks/insight-api-zcash \
	zcash-hackworks/insight-ui-zcash

If all works, you should see Successfully added services(s): zcash-hackworks/insight-api-zcash, zcash-hackworks/insight-ui-zcash.

Finally we can start with the following command:

/home/zcashd/zc/node_modules/bitcore-node-zcash/bin/bitcore-node start

If all works after a few seconds you’ll see output similar to the below indicating that the node is syncing and you can browse to your IP and port listed above e.g. localhost:3001 and, while the explorer will not be functional until the sync completes, it will display the progress.

/home/zcashd/zc/node_modules/bitcore-node-zcash/bin/bitcore-node start
[2019-08-11T01:27:58.376Z] info: Using config: /home/zcashd/zc/bitcore-node.json
[2019-08-11T01:27:58.377Z] info: Using network: testnet
[2019-08-11T01:28:03.956Z] info: ZMQ connected to: tcp://127.0.0.1:28332
[2019-08-11T01:28:18.496Z] info: Zcash Height: 133 Percentage: 0.01
[2019-08-11T01:28:33.500Z] info: Zcash Height: 241 Percentage: 0.02

As we started this in the foreground, closing your terminal without detaching it will kill the process. Therefore it is recommended you set it up to run as a service or at a minimum detach the process from the terminal with an application such as screen or nohup.

nohup /home/zcashd/zc/node_modules/bitcore-node-zcash/bin/bitcore-node start > explorer.log 2>&1 &

The above example redirects the output to a file named explorer.log so to follow the output logs use tail -f explorer.log.

Running on mainnet

If you wish to run on mainnet (or livenet in bitcore parlance), you’ll need to update zcash.conf to the below and optionally updating the RPC port.

testnet=0 
addnode=mainnet.z.cash

Finally update var testnet = true; in /home/zcashd/zc/node_modules/insight-ui-zcash/public/src/js/app.js and stop and restart the process.

Making the explorer publically available

If you are running a local instance, you can access your explorer via localhost:3001, and wait for your node to fully sync for the explorer to function currectly. If on a public IP you can also get access via <your_ip_address:3001> if your firewall permits access to that port.

Let’s quickly add to our build to use NGINX to map port 443 to 3001 as a reverse proxy and add a free Let’s Encrypt certificate. You’ll need a domain name that has its DNS pointed to the instance IP such as explorer.mydomainname.com.

sudo apt install nginx
sudo systemctl start nginx
sudo systemctl enable nginx # optionally enable NGINX as a service

At which point you should be able to browse to <your_ip_address> and see the default NGINX screen. Next, follow the instructions to add the Certbot PPA and install Certbot:

sudo apt-get -y install certbot python-certbot-nginx
sudo certbot --nginx

Follow the command prompts, enter your domain name for the certificate request, e.g. explorer.mydomainname.com and choose the option (2) to redirect all traffic to HTTPS. Then edit the default site to pass all traffic through to port 3001.

cd /etc/nginx/sites-available
sudo nano default

Update the location of the server block for your domain name to match the below:

location / {
                proxy_pass http://localhost:3001/;
}

Finally, reload NGINX, and your site should be accessible on your domain name and served over HTTPS. While this will work for a low traffic hosted explorer, it would not be recommended for a production instance and never use the instance as a wallet to store actual funds.

sudo nginx -s reload

Insight explorer running on custom domain with Let's Encrypt cert

Examining Transactions

Zcash is best known for its shielded transactions in which transaction details are not visible on the blockchain. Let’s explore this by examining a fully shielded transaction such as this transaction via the Insight explorer.

Fully shielded transaction on the Insight explorer

As we can see, the only detail available for this fully shielded Sapling transaction is the number of shielded inputs (similar to UTXOs in Bitcoin but known as notes in Zcash) and the number of shielded outputs.

All of this data is also available on the zcashd instance and we can examine the raw transaction data using the following commands:

~/zcash/src/zcash-cli getrawtransaction 5328354a0b14c95b1f8ac26ec99c7b365638cd877a04aa3fb27d19deedc90fb7

This will output the transaction in hex format. You can decode this by passing the output into the following command:

~/zcash/src/zcash-cli decoderawtransaction <output of previous command>

This will output the full transaction detail that you can compare to the explorer output. There are also additional RPC methods such as to get the address balance, which were not previously available and allow for additional functionality.

./zcash/src/zcash-cli getaddressbalance '"tmYXBYJj1K7vhejSec5osXK2QsGa5MTisUQ"'