Zingolib for developers: Running zingo-cli in regtest mode.

Intro

Mainnet vs. Testnet

Just like any other blockchain based cryptocurrency, All Zcash transactions happens on Mainnet. Mainnet is a public blockchain where blocks are mined (in Proof of work) and all value transfers happens there.

There is also the Testnet, a public blockchain that operates like the mainnet, with most of the same rules, block times and rule enforcement. The difference here is that the tokens of this chain has no real life value.

But what if you want more control over the blocks? Enter Regtest mode.

Regtest mode

Sometimes you don't want to connecto to the testnet for developing. Regtest mode is incredibly useful in this scenario where you need more control, and don't need the rules of testnet.

Regtest (Regression test) is an isolated, private version of a blockchain that don't need to follow the rules of the traditional blockchain. You can create and manage blocks without the need of mining them. In practice you don't even need a conection to the internet, since no peer conection is needed. [1]

Zingolib regtest

Good news is: Zingolib provides pre-configured files that makes running zcashd and lightwalletd in regtest mode in a easy way!

Pre-requirements

To follow this article you will need:

• Zcashd
• Lightwalletd
• Zingolib (Zingo-cli)

We'll be building all of these tools from source. For reference, I'm running Linux Mint 19.2 Tina, but the steps should be basically the same for any other OS.

Let's get started!

Zcashd and Zcash-cli

Zcashd & Zcash-cli allow you to run a full node and interact with it via a command-line interface. The zcashd full node downloads a copy of the Zcash blockchain, enforces rules of the Zcash network, and can execute all functionalities. The zcash-cli allows interactions with the node (e.g. to tell it to send a transaction) [2]

Building Zcashd and Zcash-cli

First of all, lets install the dependencies

$ sudo apt-get install \ build-essential pkg-config libc6-dev m4 g++-multilib \ autoconf libtool ncurses-dev unzip git python3 python3-zmq \ zlib1g-dev curl bsdmainutils automake libtinfo5

Then clone the git repository into any directory you want

$ git clone https://github.com/zcash/zcash.git

Enter the newly created directory

$ cd zcash

We'll be working with Zcashd version 5.3.0

$ git checkout v5.3.0

Let's fetch the zcash params with the script fetch-params.sh

$ ./zcutil/fetch-params.sh

Now, use the following commands to build zcashd and zcash-cli:

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

NOTE: If you don't have nproc, then substitute nproc with the number of cores of you CPU. If unsure, or build fails, remove the -j, e.g. $ ./zcutil/build.sh

Sit back and wait, this process will take a while.

After compiling is finished, you can verify if everything is working by running ./src/zcashd --version, you'll see something like:

$ ./src/zcashd --versionZcash Daemon version v5.3.0 In order to ensure you are adequately protecting your privacy when using Zcash,please see <https://z.cash/support/security/>. Copyright (C) 2009-2022 The Bitcoin Core DevelopersCopyright (C) 2015-2022 The Zcash Developers This is experimental software. Distributed under the MIT software license, see the accompanying file COPYINGor <https://www.opensource.org/licenses/mit-license.php>.

Lightwalletd

lightwalletd is a backend service that provides a bandwidth-efficient interface to the Zcash blockchain for mobile and other wallets, such as Zecwallet. [3]

Compiling Lightwalletd

First of all you'll ne to download and install Go version 1.17 or later. [3]

After that, clone the git repository to your computer

$ git clone https://github.com/zcash/lightwalletd.git

Then chenge into the newly created directory

$ cd lightwalletd

And run the command make

$ make

Wait until compiling is finished. To see if everything went A-OK, run the command lightwalletd version and you should see something like:

$ lightwalletd versionlightwalletd version:  v0.4.13-8-g5d174f7from commit:  5d174f7feb702dc19aec5b09d8be8b3d5b17ce45on:  2022-11-30by:  james

Zingo-cli

Zingo-cli is a command line interface tool for interactin with lightwalled servers. If you haven't read my previous article about Zingo-cli, please read it here.

Building zingo-cli debug version

You may want to build a debug version o zingo-cli if you want debug information. Follow all the steps in my previous article, and at zingolib working directory run:

$ cargo build

This will build a debug version of zingo-cli at ./target/debug/zingo-cli.

Configuration

Now that we have everything properly compiled, we just need to do a small amount of configuration. [4]

In the zingolib working directory, we can see a subdirectory called regtest. Inside this direcotry we see yet another subdirectories.

One of them is called bin. This is where you should synlink or copy zcashd, zcash-cli and lightwalletd binaries into. If not sure how to symlink, just copy the binaries into this bin directory. Something like:

$ cp /path/to/zcash/src/zcashd /path/to/zingolib/regtest/bin/$ cp /path/to/zcash/src/zcash-cli /path/to/zingolib/regtest/bin/$ cp /path/to/zcash/src/lightwalletd /path/to/zingolib/regtest/bin/

The tree structure of regtest at zingolib working directory shoud look something like:

$ tree regtest/regtest/├── bin│   ├── lightwalletd -> ../../../zcashd/lightwalletd/lightwalletd│   ├── zcash-cli -> ../../../zcashd/zcash/src/zcash-cli│   └── zcashd -> ../../../zcashd/zcash/src/zcashd├── conf│   ├── lightwalletd.yml│   └── zcash.conf├── data│   ├── lightwalletd│   ├── regtestvectors│   │   └── regtest│   │       ├── banlist.dat│   │       ├── blocks│   │       │   ├── blk00000.dat│   │       │   ├── index│   │       │   │   ├── 000005.ldb│   │       │   │   ├── 000008.ldb│   │       │   │   ├── 000009.log│   │       │   │   ├── CURRENT│   │       │   │   ├── LOCK│   │       │   │   ├── LOG│   │       │   │   ├── LOG.old│   │       │   │   └── MANIFEST-000007│   │       │   └── rev00000.dat│   │       ├── chainstate│   │       │   ├── 000005.ldb│   │       │   ├── 000008.ldb│   │       │   ├── 000009.log│   │       │   ├── CURRENT│   │       │   ├── LOCK│   │       │   ├── LOG│   │       │   ├── LOG.old│   │       │   └── MANIFEST-000007│   │       ├── database│   │       │   └── log.0000000001│   │       ├── db.log│   │       ├── fee_estimates.dat│   │       ├── peers.dat│   │       └── wallet.dat│   ├── zcashd│   └── zingo├── logs│   ├── lightwalletd│   └── zcashd└── README.md 15 directories, 30 files

Done! We've completed all the steps for working with zingo-cli in regtest!

Working with Zingo-cli in regtest mode

From the zingolib working directory, invoke zingo-cli with the --regtest flag. Zingo-cli with automatically start zcashd and lightwalletd for you. This may take a few seconds even on a fast computer. [4]

Check to see you we are on zingolib top directory

$ pwd/path/to/zingolib

Then start zingo-cli with --regtest falg

$ ./target/debug/zingo-cli --regtestzcashd is starting in regtest mode, please standby...[...]2022-12-01T20:13:52.826764Z  INFO zingo_cli: Starting Zingo-CLI    2022-12-01T20:13:52.826828Z  INFO zingo_cli: Light Client config ZingoConfig[...]Lightclient connecting to http://127.0.0.1:9067/{  "result": "success",  "latest_block": 1,  "total_blocks_synced": 1}Ready!

You should see several diagnostic messsages, and then: regtest detected and network set correctly! Lightclient connecting to http://127.0.0.1:9067/ at which point the interactive cli application should work with your regtest network. [4]

For instance, let's check the server info using the interactive cli:

(regtest) Block:1 (type 'help') >> info{  "version": "v0.4.13-8-g5d174f7",  "git_commit": "5d174f7feb702dc19aec5b09d8be8b3d5b17ce45",  "server_uri": "http://127.0.0.1:9067/",  "vendor": "ECC LightWalletD",  "taddr_support": true,  "chain_name": "regtest",  "sapling_activation_height": 1,  "consensus_branch_id": "c2d6d0b4",  "latest_block_height": 1}

We can see we're connected to 127.0.0.1, the chain name is regtest and we're at block height 1. (The block pre configured by zingolib)

Once regtest mode is running, you can manipulate the simulated chain with zcash-cli. [4]

Let's create a few blocks using zcash-cli, in the zingolib/regtest/bin/ run the command:

$ ./zcash-cli -regtest -rpcuser=xxxxxx -rpcpassword=xxxxxx -conf=../conf/zcash.conf -datadir=../data generate 11[  "04357864ce56e58da43900aab0ce9fbf37ca28bae9acdbfc885cfb9eeb7a1ec9",  "0c0de4e2505b4239095e4fac7184a11824636631831e62ecfe1bcc2e7c7bec47",  "01de51b575db5f8f63c8124317aa04ae4e7894d9cf760e84a7d0a75ca803d62f",  "03b3ad4ce54ca23db31b504f476c944f1e1d0b42a8faec6e77cb1a4c54ada216",  "0e15107cd49d65bce214ce9f767ed668cc1a8e889d86abdf8e4ff3603aab1891",  "0ad018c700aa67b13c3305ed7fb1fa2c6f33730d8b88abc951d9cca0d9953621",  "017437d6b7b7fab2b83fe78d7cd8ee82cad169d13758016ed21c26f5ab1e1c09",  "071ccd4a8c50a2b490f50b8b7cdd9cd12733724b35fa700f57e1a75590cdf3a3",  "0022df733f121246085e37305ee53d139b1eb6f25ad2c913bc795cc6985e2530",  "0b531a3a0b73270041623db92a9361ed3a735f8033a61c35b533a060b2701a43",  "0a6ba796d0d44a22d8f9d0439d7f7aabf67f81cb2912cfa5be2e2240c1120296"]

This command will generate 11 blocks on our simulated chain, and return their hashes.

Now let's take a look back in our zingo-cli, with command height we should see at what block our wallet is synched to.

(regtest) Block:1 (type 'help') >> height{  "height": 12}

Wwe are at height 12! The first block plus the 11 blocks we just generated!

Now you have everything at your control. You can mine (fake) blocks for yourself, make transfers, and everything Zcash supports in a isolated wayt from the mainnet and testnet.

CLosing words

Regtest is a great way to start developing projects with Zcash. From small applications to big projects like an exchange, testing your application in a controlled manner is crucial! And Zingolib turns this task easy and straightforward.

I really hope you all liked this article, because it was so fun to write, I had to learn new things and I'm always glad to share what I've learned.

Thanks for your time, James Katz.

References

[1] Testnet vs Regtest

[2] Zcash full node and CLI

[3] Lightwalletd github page

[4] Zingolib github page