Skip to main content
Version: 1.0.0

Quick Start Guide: zigchaind

zigchaind is the ZIGChain CLI. It is a command line tool that allows you to interact with the ZIGChain network. It is the primary tool for managing your ZIGChain node, wallet, and other related tasks on the ZIGChain network.

Quick Start on a Local Machine​

The following steps guide you through installing ZIGChain on an x86 Linux machine or a Mac with an Apple Silicon Processor.

You will need to have Go and WASM library installed before setting up the ZIGChain CLI.

💡 Windows Users:
We recommend using Windows Subsystem for Linux (WSL) to run the Linux commands on your Windows machine.
Follow the steps below to get started with WSL and then continue with the Linux instructions.

Setting Up WSL (for Windows users)​

  1. Enable WSL
    Open PowerShell or Command Prompt as Administrator and run:

    wsl --install

    This installs WSL with Ubuntu as the default distribution. Restart your computer if prompted.

  2. Initialize Ubuntu
    Open WSL from your Start menu and create your UNIX username/password when prompted.

    Alternatively, you can also launch WSL anytime by running:

    wsl

  3. Update packages

    sudo apt update

  4. Install build tools

    sudo apt install build-essential

✅ Once WSL is ready, you can continue with the Linux instructions below as if you're on a native Linux system.

🔗 For more information: Microsoft WSL Documentation

Install Go​

Check if Go is installed:

go version

If you have a lower version than 1.23.6 (at the time of writing), uninstall the old version to upgrade to the needed version.

Uninstall old Go version: First, remove the golang-go package and its dependencies:

sudo apt-get remove --auto-remove golang-go

Then purge all configuration and data:

sudo apt-get purge golang-go
sudo apt-get purge --auto-remove golang-go

Finally, verify the uninstallation:

go version

Using apt install would install an outdated version of Go (e.g., 1.18 at the time of writing). Instead, we will install the latest version from the official website.

Check Your CPU Architecture

Before downloading the Go binary, check your CPU architecture to ensure you download the correct version.

Check your CPU architecture:

lscpu | grep -e "Model name" -e "Architecture"

You should see something like:

Architecture:                    x86_64
Model name:                      Intel(R) Xeon(R) CPU @ 2.30GHz

Download the Correct Go Binary

Based on your architecture, download the appropriate Go binary from the Go official website.

  • x86_64/amd64 architecture: use linux-amd64 (default below)
  • arm64 architecture: use linux-arm64 instead
cd /tmp/
wget https://go.dev/dl/go1.23.6.linux-amd64.tar.gz
sudo tar -zxvf go1.23.6.linux-amd64.tar.gz -C /usr/local/

Lastly (if go was not previously installed) you will need to add the following to your .bashrc or .zshrc file:

echo 'export GOROOT=/usr/local/go' >> ~/.zshrc
echo 'export GOPATH=$HOME/go' >> ~/.zshrc
echo 'export PATH=$PATH:$GOROOT/bin:$GOPATH/bin' >> ~/.zshrc

Source the file to apply the changes (or exit and log back in):

source ~/.zshrc

Verify if go is installed by running the following command:

go version

Get Cosmwasm Library​

Get the Cosmwasm Library:

sudo wget -O /usr/lib/libwasmvm.x86_64.so https://github.com/CosmWasm/wasmvm/releases/download/v2.2.3/libwasmvm.x86_64.so

Install ZIGChain Binary​

Install the ZIGChain CLI by downloading the latest pre-built binaries. The tar file also contains the script to launch and generate the genesis.
Check the latest binaries here: https://github.com/ZIGChain/networks

cd /tmp/
LATEST_VERSION=$(curl -s https://raw.githubusercontent.com/ZIGChain/networks/refs/heads/main/zig-test-2/version.txt)
wget "https://raw.githubusercontent.com/ZIGChain/networks/refs/heads/main/zig-test-2/binaries/zigchaind-${LATEST_VERSION}-linux-amd64.tar.gz"
tar -zxvf "zigchaind-${LATEST_VERSION}-linux-amd64.tar.gz"
mkdir -p $HOME/go/bin
mv ./zigchaind $HOME/go/bin/zigchaind

Check that it works by running the following command:

zigchaind --help

If you have problem with permissions, ensure the folder has the correct permissions.

With the genesis you have also downloaded a script that setups genesis and some initial test accounts

First, check if installed and if not, install jq:

Check if jq is installed:

which jq

Install jq (if not installed):

sudo apt install jq

Execute the script with:

cd /tmp/
chmod +x ./zigchain_local_setup.sh
./zigchain_local_setup.sh

Start the blockchain with:

zigchaind start

Test accounts created​

On genesis, the following accounts are created for testing purposes with the following mnemonics

VAL_KEY="valuser1"
VAL_MNEMONIC="debate pottery prize tag lottery lounge protect fancy keep orbit person stage ten possible expect spend utility estate hope people attack input oval bird"

ZUSER1_KEY="zuser1"
ZUSER1_MNEMONIC="horse elite dog fix slide moon rely wife convince pear visa woman make rent giraffe under lawn impulse visit improve together above mixed what"

ZUSER2_KEY="zuser2"
ZUSER2_MNEMONIC="motion toddler sad surge present spot destroy clarify lyrics drastic cactus rhythm cupboard govern space soft fan accuse source spend artwork state smart motor"

ZUSER3_KEY="zuser3"
ZUSER3_MNEMONIC="design coral crawl aerobic airport engine spice impulse hobby limit twelve budget praise dog usage comic rain icon miss custom worth upper blade path"

ZUSER4_KEY="zuser4"
ZUSER4_MNEMONIC="blue define teach split satisfy mention food loop economy gravity lobster keep card milk smile unable barely attack shoot bulk vapor hybrid board drift"

ZUSER5_KEY="zuser5"
ZUSER5_MNEMONIC="net impact drift popular debris coast wrong iron amazing patient poet forward occur any private chunk tonight final clump general video bracket abstract fade"

Examples to interact with the zigchaind​

Example: Send and broadcast a transaction​

In this example, we will:

  1. Send a transaction from one account to another using the ZIGChain CLI.
  2. Broadcast the transaction.

Step 1️⃣: Get the initial balance of the accounts​

zigchaind query bank balances zuser1 --chain-id zigchain-1
zigchaind query bank balances zuser5 --chain-id zigchain-1

Step 2️⃣: Send a transaction​

zigchaind tx bank send $(zigchaind keys show zuser1 -a) $(zigchaind keys show zuser5 -a) 100uzig --from zuser1 --gas auto --gas-adjustment 1.3 --gas-prices 0.00025uzig --chain-id zigchain-1

Get the transaction id (txhash) from the response

Step 3️⃣: Check the transaction​

TX_ID=REPLACE_ME
zigchaind query tx $TX_ID --chain-id zigchain-1

Check the information under the "raw_log" field. If empty, means that everything went well.

Step 4️⃣: Verify that the sender's balance has decreased by the transferred amount plus gas fees​

zigchaind query bank balances zuser1 --chain-id zigchain-1
zigchaind query bank balances zuser5 --chain-id zigchain-1

Troubleshooting​

Handling "failed to initialize database: resource temporarily unavailable"​

If you encounter the following error when starting zigchaind:

Error: failed to initialize database: resource temporarily unavailable

This typically means a zigchaind process is already running in the background, which is locking the database.

Step 1️⃣: Check Running Processes​

Use the following command to list any running zigchaind processes:

ps -ef | grep zigchaind

Example output:

501 91972 88195   0  8:43PM ??        52:43.17 zigchaind start
501  7790  5112   0  4:46PM ttys008    0:00.00 grep --color=auto zigchaind

Look for a line showing zigchaind start. Note the process ID (e.g., 91972).

Step 2️⃣: Kill the Process​

Terminate the process using the following command:

kill -9 [PROCESS_ID]

Example:

kill -9 91972

💡 Tip: Stop from the Terminal Tab​

If you started zigchaind in a terminal tab, you can stop it directly with:

Ctrl + C

Once the process is stopped, you can retry your zigchaind command.

✅ This should resolve the database initialization issue and allow you to continue working with your local ZIGChain node.