Installation

Step 1: Node Installation

Step 1.1: Node Configuration

This step provides procedures to install BandChain's executable and sync blocks with other peers.

Assuming to run on Ubuntu 22.04 LTS allowing connection on port 26656 for P2P connection.

Before beginning instructions, the following variables should be set to be used in further instructions. Please make sure that these variables are set every time when using the new shell session.

# Chain ID of Laozi Mainnet
export CHAIN_ID=laozi-mainnet
# Wallet name to be used as validator's account, please change this into your name (no whitespace).
export WALLET_NAME=<YOUR_WALLET_NAME>
# Name of your validator node, please change this into your name.
export MONIKER=<YOUR_MONIKER>
# URL of genesis file for Laozi Mainnet
export GENESIS_FILE_URL=https://raw.githubusercontent.com/bandprotocol/launch/master/laozi-mainnet/genesis.json
# Data sources/data scripts files
export BIN_FILES_URL=https://raw.githubusercontent.com/bandprotocol/launch/master/laozi-mainnet/files.tar.gz

The following applications are required to build and run the BandChain node.

• make, gcc, g++ (can be obtained from the build-essential package on linux)
• wget, curl for downloading files

# install required tools
sudo apt-get update && \
sudo apt-get upgrade -y && \
sudo apt-get install -y build-essential curl wget jq

• Install Go 1.24.2

# Install Go 1.24.2
wget https://go.dev/dl/go1.24.2.linux-amd64.tar.gz
tar xf go1.24.2.linux-amd64.tar.gz
sudo mv go /usr/local/go

# Set Go path to $PATH variable
echo "export PATH=$PATH:/usr/local/go/bin:~/go/bin" >> $HOME/.profile
source ~/.profile

Go binary should be at /usr/local/go/bin and any executable compiled by go install command should be at ~/go/bin

Step 1.2: Clone & Install BandChain Laozi

cd ~
# Clone BandChain Laozi version v3.1.0
git clone https://github.com/bandprotocol/chain
cd chain
git fetch && git checkout v3.1.0

# Install binaries to $GOPATH/bin
make install

Step 1.3: Initialize the BandChain and download the genesis file

cd $HOME

# Initialize configuration and genesis state
bandd init --chain-id $CHAIN_ID "$MONIKER"

# Replace genesis file with our genesis file
wget $GENESIS_FILE_URL -O $HOME/.band/config/genesis.json

# Download data sources / data scripts files, and store in $HOME/.band/files
wget -qO- $BIN_FILES_URL | tar xvz -C $HOME/.band/

# Create new account
bandd keys add $WALLET_NAME

Step 1.4: Configure general settings

This can be done by editing fields in $HOME/.band/config/config.toml and $HOME/.band/config/app.toml.

For a list of seeds and peers, please see here.

For minimum-gas-prices, you can set any number but the recommendation is 0.0025uband (according to this proposal).

# List of seeds and persistent peers you want to add
# e.g. SEEDS="8d42bdcb6cced03e0b67fa3957e4e9c8fd89015a@34.87.86.195:26656,543e0cab9c3016a0e99775443a17bcf163038912@34.150.156.78:26656"
export SEEDS="<SEED>,<SEED>,..."
export PERSISTENT_PEERS="<PERSISTENT_PEER>,<PERSISTENT_PEER>,..."

# Add seeds and persistent peers to config.toml
sed -E -i \
  "s/seeds = \".*\"/seeds = \"${SEEDS}\"/" \
  $HOME/.band/config/config.toml

sed -E -i \
  "s/persistent_peers = \".*\"/persistent_peers = \"${PERSISTENT_PEERS}\"/" \
  $HOME/.band/config/config.toml

# Add minimum gas price
sed -E -i \
  "s/^minimum-gas-prices *=.*/minimum-gas-prices = \"0.0025uband\"/" \
  $HOME/.band/config/app.toml

# Set timeout propose
sed -E -i \
  "s/timeout_propose = \".*\"/timeout_propose = \"1s\"/" \
  $HOME/.band/config/config.toml

# Set timeout commit
sed -E -i \
  "s/timeout_commit = \".*\"/timeout_commit = \"500ms\"/" \
  $HOME/.band/config/config.toml

# Set peer_gossip_sleep_duration
sed -E -i \
  "s/peer_gossip_sleep_duration = \".*\"/peer_gossip_sleep_duration = \"10ms\"/" \
  $HOME/.band/config/config.toml

# Set flush_throttle_timeout
sed -E -i \
  "s/flush_throttle_timeout = \".*\"/flush_throttle_timeout = \"10ms\"/" \
  $HOME/.band/config/config.toml

Step 2: Setup Cosmovisor

Pre-Requisite Readings

• Cosmoviser

Cosmovisor is a small process manager for Cosmos SDK application binaries that monitors the governance module via stdout for incoming chain upgrade proposals

Step 2.1: Setup environment variables

Add required environment variables for Cosmovisor into your profile

cd ~
echo "export DAEMON_NAME=bandd" >> ~/.profile
echo "export DAEMON_HOME=$HOME/.band" >> ~/.profile
source ~/.profile

Step 2.2: Install and provide binaries

Install Cosmovisor and provide bandd binary to Cosmovisor

# Install Cosmovisor
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@v1.5.0

# Setup folder and provide bandd binary for Cosmovisor Genesis
mkdir -p $HOME/.band/cosmovisor/genesis/bin
mkdir -p $HOME/.band/cosmovisor/upgrades
cp $HOME/go/bin/bandd $HOME/.band/cosmovisor/genesis/bin

# Setup folder and provide bandd binary for Cosmovisor Upgrades
mkdir -p $HOME/.band/cosmovisor/upgrades/v3_1/bin
cp $HOME/go/bin/bandd $DAEMON_HOME/cosmovisor/upgrades/v3_1/bin

Step 3: Sync with the network

There are three main ways to sync a node on the BandChain; Blocksync, State Sync, and Snapshots.

info

It is highly recommended to use State Sync or Snapshots as it's faster. However, if you want to use Blocksync, please read the following section.

Block Sync

Block Sync

Blocksync is faster than traditional consensus and syncs the chain from genesis by downloading blocks and verifying against the Merkle tree of validators. For more information see Tendermint's Fastsync Docs

When syncing via Blocksync, node operators will need to provide the binary of each upgrade version for Cosmovisor to switch when it reaches the upgrade heights.

You can see the detail of genesis and each upgrade in the table below.

Upgrade name	Upgrade Height	Upgrade detail	Go version	Bandd version	Binary path
genesis	0	-	1.16.7	v2.3.6	~/.band/cosmovisor/genesis/bin
v2_4	11525000	link	1.19.1	v2.4.1	~/.band/cosmovisor/upgrades/v2_4/bin
v2_5	16562500	link	1.19.1	v2.5.4	~/.band/cosmovisor/upgrades/v2_5/bin
v3	42051400	link	1.24.2	v3.0.2	~/.band/cosmovisor/upgrades/v3/bin
v3_1	42450000	link	1.24.2	v3.1.0	~/.band/cosmovisor/upgrades/v3_1/bin

Before doing the next step, you have to build and provide each correct bandd binary version to Cosmovisor in the binary path so that Cosmovisor can automatically switch it correctly.

State Sync

State Sync

State Sync is an efficient and fast way to bootstrap a new node, and it works by replaying larger chunks of application state directly rather than replaying individual blocks or consensus rounds. For more information, see Tendermint's State Sync docs.

Setup variables

# Get trust height and trust hash

LATEST_HEIGHT=$(curl -s http://rpc.laozi1.bandchain.org/block | jq -r .result.block.header.height);
TRUST_HEIGHT=$(($LATEST_HEIGHT-60000))
TRUST_HASH=$(curl -s "http://rpc.laozi1.bandchain.org/block?height=$TRUST_HEIGHT" | jq -r .result.block_id.hash)

# show trust height and trust hash
echo "TRUST HEIGHT: $TRUST_HEIGHT"
echo "TRUST HASH: $TRUST_HASH"

Setup State Sync config

# Enable State Sync
sed -i \
    '/\[statesync\]/,+34 s/enable = false/enable = true/' \
    $HOME/.band/config/config.toml

# Set RPC Endpoint for State Sync
sed -E -i \
    "/\[statesync\]/,+34 s/rpc_servers = \".*\"/rpc_servers = \"http\:\/\/rpc.laozi1.bandchain.org\:80,https\:\/\/rpc.laozi3.bandchain.org\:443\"/" \
    $HOME/.band/config/config.toml

# Set Trust Height for State Sync
sed -i \
    "/\[statesync\]/,+34 s/trust_height = .*/trust_height = ${TRUST_HEIGHT}/" \
    $HOME/.band/config/config.toml

# Set Trust Hash for State Sync
sed -i \
    "/\[statesync\]/,+34 s/trust_hash = \".*\"/trust_hash = \"${TRUST_HASH}\"/" \
    $HOME/.band/config/config.toml

Snapshot - HighStakes

Snapshot - HighStakes

HighStakes provides the latest chain data snapshot with a very small size every day. You can download snapshot data and start to sync the block from snapshot height without syncing from the first block.

For more information, click on the link below: https://tools.highstakes.ch/snapshots/bandprotocol

Download snapshots

cd ~/.band/

wget https://tools.highstakes.ch/files/bandprotocol.tar.gz
tar -xvf bandprotocol.tar.gz

Step 4: Setup daemon service

We do recommend running the Bandchain node as a daemon, which can be set up using systemctl.

Step 4.1: Create BandChain service

Run the following command to create a new daemon for cosmovisor that runs bandd (This script work on non-root user).

# Write bandd service file to /etc/systemd/system/bandd.service
export USERNAME=$(whoami)
sudo -E bash -c 'cat << EOF > /etc/systemd/system/bandd.service
[Unit]
Description=BandChain Node Daemon
After=network-online.target

[Service]
Environment="DAEMON_NAME=bandd"
Environment="DAEMON_HOME=${HOME}/.band"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="UNSAFE_SKIP_BACKUP=true"
User=$USERNAME
ExecStart=${HOME}/go/bin/cosmovisor run start
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
EOF'

Step 4.2: Register and start bandd service

In this step, we will register and start bandd service

# Register bandd to systemctl
sudo systemctl enable bandd
# Start bandd daemon
sudo systemctl start bandd

Once bandd service has been started, logs can be queried by running journalctl -u bandd.service -f command. You will see your node beginning to sync.

Step 5: Setup Yoda

Pre-requisite Readings

• Yoda

Yoda is a program used by BandChain's validator nodes to help automatically query data from data providers by executing data source script, then submitting the result to fulfill the request.

Since a subset of validators who are selected for a data request must send the data they received as a transaction of MsgReportData to BandChain.

Yoda requires indexer to run properly. Please make sure if your node has set indexer in config.toml file as "kv"

Step 5.1: Installation

Before setting up Yoda, the Lambda function executor need to be set up to execute data sources. If this step has not been done yet, please follow the instructions on the following pages (select either one of these methods):

• AWS Lambda Function
• Google Cloud Function

To check Yoda version, use the following command.

yoda3 version
# v3.1.0

Step 5.2: Set the Yoda configurations

Use the command below to config your Yoda, replacing $VARIABLES with their actual values.

rm -rf ~/.yoda3 # clear old config if exist
yoda3 config chain-id $CHAIN_ID
yoda3 config node http://localhost:26657
yoda3 config broadcast-timeout "5m"
yoda3 config rpc-poll-interval "1s"
yoda3 config max-try 5
yoda3 config validator $(bandd keys show $WALLET_NAME -a --bech val)

Then, add multiple reporter accounts to allow Yoda to submit transactions concurrently.

yoda3 keys add REPORTER_1
yoda3 keys add REPORTER_2
yoda3 keys add REPORTER_3
yoda3 keys add REPORTER_4
yoda3 keys add REPORTER_5

Lastly, configure the Lambda Executor endpoint to helps running data source scripts and return results to Yoda. More details about the executor can be found in this section.

export EXECUTOR_URL=<YOUR_EXECUTOR_URL>
yoda3 config executor "rest:${EXECUTOR_URL}?timeout=10s"

Step 5.3: Start Yoda

To start Yoda, it's also recommended to use systemctl.

# Write yoda service to /etc/systemd/system/yoda3.service
export USERNAME=$(whoami)
sudo -E bash -c 'cat << EOF > /etc/systemd/system/yoda3.service
[Unit]
Description=Yoda Daemon
After=network-online.target

[Service]
User=$USERNAME
ExecStart=/home/$USERNAME/go/bin/yoda3 run
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
EOF'

The first time running Yoda, you will need to register and start yoda services by running the following commands.

# Register yoda3 to systemctl
sudo systemctl enable yoda3
# Start yoda3 daemon
sudo systemctl start yoda3

After yoda3 service has been started, logs can be queried by running journalctl -u yoda3.service -f command. The log should be similar to the following log example below. Once verified, you can stop tailing the log by typing Control-C.

... systemd[...]: Started Yoda Daemon.
... yoda3[...]: I[...] ⭐  Creating HTTP client with node URI: tcp://localhost:26657
... yoda3[...]: I[...] 🚀  Starting WebSocket subscriber
... yoda3[...]: I[...] 👂  Subscribing to events with query: tm.event = 'Tx'...

Step 6: Setup Bothan

Pre-requisite Readings

• Bothan

Based on design, validators need to submit prices based on current feeds interval. However, the method is quite tedios. Therefore, we have developed an application called Bothan, which is a price discovery application that help validators automatically query price from multiple sources, and process it to match with BandChain standard.

Step 6.1: Install docker

Install Docker for Ubuntu

Step 6.2: Download config file

🌍 For Non-US regions:

mkdir -p $HOME/.bothan && wget -O $HOME/.bothan/config.toml https://raw.githubusercontent.com/bandprotocol/launch/refs/heads/master/laozi-mainnet/bothan-config.toml

🇺🇸 For US region:

mkdir -p $HOME/.bothan && wget -O $HOME/.bothan/config.toml https://raw.githubusercontent.com/bandprotocol/launch/master/laozi-mainnet/bothan-config-us.toml

Step 6.3: Run Bothan docker

sudo docker pull bandprotocol/bothan-api:v0.0.1
CONTAINER_ID=$(sudo docker run --restart always --log-opt max-size=50m --log-opt max-file=5 -d --name bothan -v "$HOME/.bothan:/root/.bothan" -p 50051:50051 bandprotocol/bothan-api:v0.0.1)

Step 6.4: Save your Private Key

To export your Bothan private key, run the following command:

sudo docker exec -it $CONTAINER_ID /bin/sh -c "bothan key export"

This will display your private key. Make sure to save it in a secure location, as it is essential for recovering your key using the bothan key import command.

Step 6.5: Send your Public Key to Monitoring

To retrieve your public key, run this command:

sudo docker exec -it $CONTAINER_ID /bin/sh -c "bothan key display"

After retrieving your public key, submit it via this form. Do not share your private key.

Step 7: Setup Grogu

Pre-requisite Readings

• Grogu

Based on design, validators need to send a transaction to submit prices based on current feeds interval. The validator should submit prices within a specified timeframe. However, the method is quite tedios. Therefore, we have developed an application called Grogu, which is a bot application that help validators automatically query for current feeds, get prices from price service (Bothan), and submit prices to BandChain, so validators don't have to send the transactions manually.

Step 7.1: Set the Grogu configurations

Use the command below to config your Grogu, replacing $VARIABLES with their actual values.

grogu config chain-id $CHAIN_ID
grogu config validator $(bandd keys show $WALLET_NAME -a --bech val)
grogu config rpc-poll-interval "1s"
grogu config max-try 5
grogu config broadcast-timeout 30s
grogu config nodes http://localhost:26657

Then, add multiple feeder accounts to allow Grogu to submit transactions concurrently.

grogu keys add FEEDER_1
grogu keys add FEEDER_2
grogu keys add FEEDER_3
grogu keys add FEEDER_4
grogu keys add FEEDER_5

Lastly, configure Bothan to helps getting prices from sources.

grogu config bothan "localhost:50051"

Step 7.2: Start Grogu

To start Grogu, it's also recommended to use systemctl.

# Write grogu service to /etc/systemd/system/grogu.service
export USERNAME=$(whoami)
sudo -E bash -c 'cat << EOF > /etc/systemd/system/grogu.service
[Unit]
Description=Grogu Daemon
After=network-online.target

[Service]
User=$USERNAME
ExecStart=/home/$USERNAME/go/bin/grogu run
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
EOF'

The first time running Grogu, you will need to register and start grogu services by running the following commands.

# Register grogu to systemctl
sudo systemctl enable grogu
# Start grogu daemon
sudo systemctl start grogu

After grogu service has been started, logs can be queried by running journalctl -u grogu.service -f command. The log should be similar to the following log example below. Once verified, you can stop tailing the log by typing Control-C.

... systemd[...]: Started Grogu Daemon.
... grogu[...]: I[...] ⭐  Connecting to Bothan service at localhost:50051
... grogu[...]: I[...] 🚀  Grogu has started

Step 8: Wait for the latest blocks to be synced

It is imperative to exercise caution and allow adequate time for the newly started BandChain node to synchronize its blocks until it has reached the latest block. The latest block can be verified on CosmoScan.