How to Join a Testnet as a Validator on Cosmos Based Blockchain.

8 min readOct 30, 2021

In the Cosmos ecosystem, it’s important to understand the role of a testnet. Before launching the mainnet of a blockchain a series of testnets are created in order to test the genesis, validators, simulate upgrades, etc. This is where validators that are looking to participate on the mainnet get a chance to contribute and learn about becoming validators with a testnet.

The best place to learn is by looking at the launch process of other testnets such. For example: https://github.com/CosmosContracts/testnets

In this example I will join a blockchain called alien-chain. Each chain has a unique chain-id. Our chain id will be called ufo. This guide is meant for people who are building a blockchain and are trying to understand the process that validators will go through in order to join a testnet.

This guide will walk you through the following process:

Setting up the server (Ubuntu, will be used for this Example)
Install Starport on the server
Install the Blockchain’s Binary from source.
Create a local account
Initialize the Genesis
Adding the validator address and balance to the genesis (not required as a validator but important to understand for the team managing the chain launch).
Create a gentx transaction file
Submit the Gentx to the Chain’s Testnet Repository

Background

The purpose of this guide is to go into as many details as possible in order to explain the process of joining a testnet in a Cosmos based blockchain. Do not expect this to be as simple as running one command on a server. Practice is your friend.

This Alien blockchain is work in progress and will be officially announced in a couple of weeks. (I guess you know first about it now 🤫). The idea is to share as much as possible while working on it and hopefully attract other people to join the project. More details will be available soon.

Recommended Skills

Reading Cosmos’ Starport : https://starport.com/
Reading Cosmos’s Documentation: https://docs.cosmos.network/
Linux/Server management : Learn the basics here
Basic git command skills : Introduction to Git

Setting up a Server

Let’s start by creating a brand new server on DigitalOcean. If this . Use this tutorial as reference here. This step can be skipped the if the blockchain is already running on a server and you are familiar with managing it.

Select Ubuntu 20.4, Shared CPU, $12/month 2gb Memory.

Select all the default options except for the size. I selected a $12/month server to run things a little smoother. I also recommend connecting via SSH keys. You can learn more about this here.

Login to the newly created server. The first time you login with your ssh-key you will be asked to accept the server to list of known hosts.

ssh root@128.199.6.43

Create a new user. I’m calling this user “valuser” (Make sure to save the user’s sudo password).

adduser valuser

Adding Sudo User from Usermod Command

usermod -aG sudo valuser

To be able to login as valuser, copy the ssh public key to the new home directory for valuser:

rsync --archive --chown=valuser:valuser ~/.ssh /home/valuser

Switch to the new user. Next time you login to the server, use
ssh valuser@128.199.6.43.

su - valuser

Install Golang, you will be asked for the valuser’s password.

wget https://golang.org/dl/go1.17.2.linux-amd64.tar.gz
sudo tar -xvf go1.17.2.linux-amd64.tar.gz -C /usr/local
sudo chown -R valuser:valuser /usr/local/go

Add Go to the paths in the local profile:

nano ~/.profile

At the end of the file add the following:

export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin:/usr/local/go/bin

Command + x to exit, then type “yes” to save changes

Refresh the profile & check version

source ~/.profile
go version

Result:

Install Starport on the server

curl https://get.starport.network/starport! | sudo bash

Install the Blockchain’s Binary from source.

Download the alien-chain’s repo and build the binary from source.

cd ~/
git clone https://github.com/alien-chain/alien.git
cd alien
starport chain build

The aliend binary was installed and it’s ready for user’s inputs.

Create a local account

An account is a pair of a private key and a public key.

What is keyring-backend?

The keyring holds the private/public keypairs used to interact with a node. For instance, a validator key needs to be set up before running the blockchain node, so that blocks can be correctly signed. The private key can be stored in different locations, called “backends”, such as a file or the operating system’s own key storage.

There are different types of backends for keyring. In this case we are using the test keyring for testing purposes. Please learn more about the different types available on the Cosmos documentation.

Add a local account

aliend keys add validator_one --keyring-backend test

List the current accounts on this system

aliend keys list --keyring-backend test

— — — — — DELETE FROM TUTORIAL

Create a local variable to get the validator address

MY_VALIDATOR_ADDRESS=$(aliend keys show validator_one -a --keyring-backend test)

Test the variable

echo $MY_VALIDATOR_ADDRESS

Init the Genesis

aliend init ufo --chain-id=ufo

The genesis filehas been created, however it does not have a validator in it. It’s just an empty genesis we will use to generate a gentx file that will be submitted to the Alien’s chain repository to be consolidated into a single genesis with all of the validator addresses, balances and gentx.

⚠️ These next two steps are not necessary on this tutorial but it’s important to understand.

Adding the validator address and balance to the genesis

1. In order for the gentx to be accepted, the address and balance of the validator must exist in the genesis. The chain’s team will run the following command to add the validator account to the genesis. Where alien1lh5zzm7r4vx6jx5x4qmqs889gkzk6xr30jqy60 was generated when the “aliend keys add” was executed.

aliend add-genesis-account alien1lh5zzm7r4vx6jx5x4qmqs889gkzk6xr30jqy60 100000000000stake

2. They will follow this by running another command to add the gentx file you will submit to the repository. This command processes the gentx files and adds them as actual transactions on the genesis.

aliend collect-gentxs

⚠️ Ok, continuing with the tutorial.

Create a gentx transaction file

A genesis transaction that lives locally in the ~/.alien/config.gentx folder.

aliend gentx validator_one 100000000stake --chain-id ufo --keyring-backend test

Submit the Gentx to the Chain’s Testnet Repository

Most Cosmos projects will have a repo that will contain the genesis for their testnets and another repo that contains geneses and gentx for the mainnet. In this example we will fork the testnet called ufo in the Alien chain project.

Fork the alien-chain/testnets repo

Download the forked repo to the server’s home directory. If you don’t know what a fork is, or how to submit a PR from your fork to the original repo, this would be a good time to learn the git basics. I’ll try to explain this as much as possible.

cd ~/
git clone https://github.com/daniel-farina/testnets.git

Copy the gentx transactions that was created on the previous step to this repo’s genx folder.

cp ~/.alien/config/gentx/gentx-ac8ec7ccd1b0bd531ad6bfa628e1e7128f0216d8.json ~/testnets/ufo/gentx/

Basically a new gentx transaction will be added to your fork of the testnet repo from the Alien-chain which we will then submit to the alien-chain repo via a pull request.

The file has been added but not added to the repo. gentx-ac8ec7ccd1b0bd531ad6bfa628e1e7128f0216d8.json is the name of the gentx transaction. It will be a different name in your server. Add the file by running this command. Make sure that this name matches the file that was just copied on the previous step.

cd ~/testnets
git add ufo/gentx/gentx-ac8ec7ccd1b0bd531ad6bfa628e1e7128f0216d8.json

Check your git repository status. A new file has been added to this repo

git status

Commit changes (Include your validator’s name on the commit title possible)

git commit -m "Adding gentx for Validator"

Push the commits to Github. If you are not logged in to Github, then login with your email and token. Learn how to obtain a token here.

If this is a brand new server, configure the Github email and name.

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

Now push the changes.

cd ~/testnets
git push

A Github username and token will be required to login. Password do not work, it must be a generated token.

Then the changes are uploaded to the forked repository.

Create a PR (Pull Request) from Github to add the changes from your fork into the alien-chain’s repo.

Click create new pull request. Make sure the correct file is sent on this pull request.

Add a nice title and description.

That’s it. Now the team will review this testnet and add it to the main genesis which will be used and shared with all validators once the testnet is launched.

How about running the Blockchain on the server?

To learn how to run this blockchain on the server make sure to view this other guide :https://medium.com/@elchileno/deploy-cosmos-starport-dapp-to-digitalocean-b4b9593906fb

Thank you!

Follow me on Twitter: https://twitter.com/Daniel_Farinax