A step-by-step guide to join Cosmos Hub testnet

As a supporter to the Cosmos Network, we have joined the Cosmos Hub testnet as a validator. Although the documentation for joining the testnet is very clear, I saw that many of the validators found it difficult to setup a validator node smoothly. I try to write down the steps with explanations on how we connect to the Gaia-5001 testnet and hope it can help those who want to join the network.

Before you start, join the validator chat.

Step 1. Setup a Server

First, you have to setup a server. You are supposed to run your validator node all time, so you will need a server in datacenter to keep it running. Any cloud services like AWS, GCP, DigitalOcean will do.

Cosmos SDK is written in Go. It should work on any platform which can compile and run programs in Go. However, I strongly recommend running the validator node on a Linux server. I have tried to run the validator node on Windows. I could compile the codes smoothly but there were some problems when running the program. The example below will all be done on a Linux server.

Here is the configuration of the server we are using.

No. of CPUs: 2
Memory: 2GB
Disk: 20GB SSD
OS: Ubuntu 18.04 LTS
Allow all incoming connections from TCP port 46656 and 46657

Once your new server is running, login to the server and upgrade your packages.

$ sudo apt update



$ sudo apt upgrade -y

Step 2. Install Go and setup correct environment variables

$ sudo apt install -y gcc make golang-go

Now, you should be able to run Go. You should have Go 1.10.x installed.

$ go version



go version go1.10.1 linux/amd64

Edit your .profile in your home directory. Add $GOPATH and edit $PATH environment variables. It lets your system reference to the correct binary when during compilation.

$ nano $HOME/.profile

Add the following two lines at the end of the file.

GOPATH=$HOME/go
PATH=$GOPATH/bin:$PATH

Save the file and exit the editor. Then run the following to make your bash reload your profile configurations.

$ source $HOME/.profile

Now you should see something like this if you echo your $GOPATH and $PATH variables

$ echo $GOPATH



/home/forbole/go

$ echo $PATH



/home/forbole/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin

Step 3. Get Cosmos SDK and build gaia

Now you have Go setup correctly. The next step is to get the codes that you need to compile and run.

$ go get github.com/cosmos/cosmos-sdk

Then change to the directory of the cosmos-sdk

$ cd $GOPATH/src/github.com/cosmos/cosmos-sdk

Checkout the version of the testnet. It’s currently running v0.17.4.

$ git fetch --all



$ git checkout v0.17.4

And then you can build the binary by running the followings commands.

$ make get_tools



$ make get_vendor_deps



$ make install

If your environment variables have set up correctly, you should not get any errors by running the above 3 commands.Now check your gaiad version.

> gaiad version



0.17.4–19a32904

Step 4. Create genesis.json and connect to the testnet

We need the genesis validator node information to prepare our genesis file in order to connect to the testnet. You can get the files from Cosmos testnet repo.

$ go get github.com/cosmos/testnet

The validator node files can be found under /gaia-5001 directory of the testnet repo. Create a .gaiad/config/gentx directory in your home directory and copy those validator node files there.

$ mkdir -p $HOME/.gaiad/config/gentx



$ cp $GOPATH/src/github.com/cosmos/testnet/gaia-5001/* \



$HOME/.gaiad/config/gentx

You can now init and run the node.

$ gaiad init --gen-txs -o --chain-id=gaia-5001

You node is initialized and you can run the node in background logging all output to a log file.

$ gaiad start &> gaia.log &

All output will be logged in the gaia.log file. You can keep checking the output using tail -f.

$ tail -f gaia.log

To check if your node is connected to the testnet, you can run this.

$ gaiacli status

You should be seeing a returned JSON with your node status including node_info, sync_info and validator_info. If you see this, then you are connected.

Step 5. Prepare keys for your validator and get some steaks

Alright, you are now connected to the testnet. To be a validator, you will need some steaks (yes, the staking coin on testnet is steak 🥩). You first need to generate a pair of private and public keys for sending and receiving coins, and bonding stake. Run the following command.

$ gaiacli keys add <your_key_name>

<your_key_name> is any name you pick to represent this key pair. You have to refer to this <your_key_name> later when you use the keys to sign transactions. It will ask you to enter your password twice to encrypt the key. You also need to enter your password when you use your key to sign any transaction.The command returns the address, public key and a seed phrase which you can use it to recover your account if you forget your password later. Keep the seed phrase in a safe place in case you have to use them.

The address showing here is your account address. Let’s call this <your_account_address>. It stores your assets. You can now check your account with the command.

$ gaiacli account <your_account_address>

After running this, you will see the following error.

panic: UnmarshalBinaryBare cannot decode empty bytes

Yes, panic but don’t panic! This is a normal response when you don’t have any coin in the account. Simply to say, you have created the key locally but nobody notice this address on the chain yet. Once there is a transaction to this address, the account is created on the chain and you can check your account balance again with the command with a more meaningful response. It works just like you open an account at the bank. When you open an account, the teller assigns you a new account number. The account will be activated after you deposit some money to it.

So where to get some bloody juicy steaks? Join the validator chat, paste <your_account_address> and ask for coins. The genesis validators will send you some steaks when they see your request. What until you have the steaks in your account and you can continue.

Step 6. Run a validator node

Validators are actors on the network committing new blocks by submitting their votes. It refers to the node itself, not a single person or a single account. In the Cosmos whitepaper, it says,

The protocol requires a fixed known set of validators, where each validator is identified by their public key.

Therefore, the public key here is referring to the node public key, not the public key of the address you have just created.To get the node public key, run the following command.

$ gaiad show_validator

It will return a 74-character long string like this.

1624DE6220FFA6B1347B5D475B6647057E2C3DE09185A442C0AB887C268D0470C0F4591159

Let’s call it <your_node_pubkey>.The next step you have to declare a validator candidate. The validator candidate is the account which stake the coins. So the validator candidate is an account this time.To declare a validator candidate, run the following command.

$ gaiacli declare-candidacy --amount=1steak --pubkey=<your_node_pubkey> --address-candidate=<your_account_address> --moniker=<your_name> --chain-id=gaia-5001 --sequence=0 --name=<your_key_name>

Make sure the --pubkey used here is <your_node_pubkey> which is the nodee public key and --address-candidate used is <your_account_address> which holds coins. If the transaction goes well, you have declared a validator candidate with 1 bonding steak on your validator node.

You may think the account address and the validator node public key are two different things and you can declare more candidates with the same public key. This is not allowed as 1 validator node public key can only declare 1 validator candidate. I tried and the transaction went through. This is currently a bug.

You can check to see if your validator node address is in the validator set by running this command.

$ gaiacli validatorset

Your validator node address can be found in $HOME/.gaiad/config/priv_validator.json file.

$ cat $HOME/.gaiad/config/priv_validator.json

The first value of this JSON is your validator node address. If your validator node address can be found in the validator set, you have done everything ok. If not, please check the above commands and see if you have missed anything. The most common mistake is the mixing up of the use of node public key and account address while declaring candidacy.

The Tendermint team has built a validator monitor to keep tracking the performance of the validators. You can see your validator node address with the uptime of the latest 100 committed blocks.

As long as you understand which account address and validator node public key to be used, you know how to delegate and unbond coins from the candidate.

Step 7. Sentry node architecture (optional but recommended)

In the Validator FAQ, it suggests validators to setup a sentry node architecture to protect the validator node from DDOS. Sentry nodes are like avatars of the validator nodes. They work similar to reverse proxy of a webapp. The sentry nodes are also full nodes and connect to the external network while connecting your validator node in the internal network. The validator node can still communicate with the network without exposing itself to the external network.This can be done simply by editing the the $HOME/.gaiad/config/config.toml file on both the validator node and the sentry full node.

The following are the steps to setup the sentry node architecture.

1. Run another full node as a sentry node (step 1–4, you don’t need any coins here) in the same internal network of the validator node

2. On the sentry node, edit $HOME/.gaiad/config/config.toml. Put the internal IP of the validator node to the private_peer_ids. For example,

private_peer_ids = "10.10.0.1"

3. On the validator node, disallow all incoming connections in the firewall. Only allow incoming connection on 46656/tcp from the internal IP of the sentry node.

4. On the validator node, edit $HOME/.gaiad/config/config.toml. Remove all existing peer information from persistent_peers and put the node information of your sentry node in the format of id@ip:port here.

persistent_peers = "[email protected]:46656"

The node information can be found by checking the node status.

> gaiacli status

And the validator node should set pex to false.

pex = false

5. Restart both nodes.If both the validator node and sentry node can sync with the network and validator node can keep an uptime on the validator monitor, your setup is working fine.

P.S. There is still one thing I’m not so sure. I expect the validator node will be invisible to the external network but when I still see the validator information when I check the net_info of the sentry node.