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.0.1
git clone https://github.com/bandprotocol/chain
cd chain
git fetch && git checkout v3.0.1
# 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
Step 2: Setup Cosmovisor
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 github.com/cosmos/cosmos-sdk/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/bin
cp $HOME/go/bin/bandd $DAEMON_HOME/cosmovisor/upgrades/v3/bin
Step 3: Sync with the network
There are three main ways to sync a node on the BandChain; Blocksync, State Sync, and Snapshots.
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
- State Sync
- Snapshot - HighStakes
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.1 | ~/.band/cosmovisor/upgrades/v3/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 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
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
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):
To check Yoda version, use the following command.
yoda3 version
# v3.0.1
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
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
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
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.