How to Install Cosmos and Run Your Full Node (Mainnet)

Published in

Cryptium Labs

5 min readMar 1, 2019

Updated: 26.04.2019

This guide is dedicated to stakeholders or developers, who might want to get familiar with the Cosmos Network stack. It is a step-by-step guide from installing Go on your laptop until you have a synching full-node on the mainnet (cosmoshub-2), using gaiad on the command line.

The chain-id is now cosmoshub-2. See this article to learn how to upgrade from cosmoshub-1 to cosmoshub-2.

Learning about full nodes is not only useful for developers or validators, but also for delegators, who wish to prioritise security and to interact with the network as trust-lessly as possible, which can be achieved by running your own full node and using the command line tools (in addition to storing your funds on a Hardware wallet, such as Ledger). For beginners to Cosmos, it is also a good way to learn about the network.

About this Guide

I will be using a device with OS X. Should you be other OS such as Windows or Linux, the list of requirements is still applicable. Note that commands for Linux are very similar to the ones on OS X, but on Windows commands might significantly different.

Commands start with $

$ this is a command do not copy the dollar sign!

Comments start with #

# this is a comment make sure you read them!

Sample outputs start with an arrow:

➜ this is an example command line output useful for comparing

Requirements

In this guide, I will assume that the user does not have any of the following installed. If you are a Golang developer, you can most likely skip to the bottom of this section.

Mac OS X Requirements

XCode Command Line Tools:

$ xcode-select --install

Install/Update Brew formulae:

$ brew update

Install Mercurial (necessary if you use gvm):

$ brew install mercurial

Installing Golang

For my own sanity and the ones around you, I strongly recommend installing (even reinstalling) Golang using Go Version Manager gvm (source). As long as you are confident with your Go installation, you can skip this part.

Install GVM (change bash for zsh if applicable):

$ bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)➜ No existing Go versions detected
Installed GVM v1.0.22Please restart your terminal session or to get started right away run `source...`

2. Installing the compatible* version of Go:

$ gvm install go1.12 --binary➜ Installing go1.12 from binary source$ gvm use go1.12 --default➜ Now using version go1.12

*Note that on GVM there’s a newer version of Go go1.4, however the version that works with Cosmos is go1.12, having another version might cause issues in the next steps.

3. (Optional) Only if you’re planning on developing in Golang, I would add these lines to your .bash or .zshrc file right below #gvm’s existing line. This is recommended because otherwise whenever you are installing Go programs, gvm will put them under the Go version in use (currently go1.12, which is not the most up-to-date), so you would need to reinstall them for each Go version:

# gvm
[[ -s "/Users/<usr>/.gvm/scripts/gvm" ]] && source "/Users/<usr>/.gvm/scripts/gvm" # the above was automatically added by gvmexport GOPATH=$HOME/code/go-workspace
export PATH=$PATH:$GOPATH/bin

Installing Cosmos from Source

After successfully installing Go, we can now install Cosmos or more precisely gaia, the Cosmos Hub application. The goal of this section is to end up successfully installing two binaries:gaiad and gaiacli, which are respectively for running your own full-node and the main command-line client for the network (source).

*gaiacli will not be used in this article, but will be important for future guides.

Get the binaries from Cosmos:

$ mkdir -p $GOPATH/src/github.com/cosmos$ cd $GOPATH/src/github.com/cosmos$ git clone https://github.com/cosmos/cosmos-sdk

2. The goal this time is to join the Cosmos mainnet, which is cosmoshub-2. The latest version that works with this chain-id is v0.34.3*:

$ cd cosmos-sdk && git checkout v0.34.3➜ Note: checking out 'v0.34.3'$ make➜ Generating vendor directory via dep ensure 
[...]
# no errors

*At this moment, the latest stable release is v0.34.3. For future chains, make sure you’re on the latest stable release (find it here).

3. Let’s check the binaries:

$ gaiad version --long
➜ cosmos-sdk: 0.34.3
git commit: 1127446f71fa6aeada1bce2718f7f903cc18e548
vendor hash: b0ee613acca9a3a572b558d0481ec7baa008f732431392af81db3555c92c8dd7
build tags: netgo ledger
go version go1.11.5 darwin/amd64$ gaiacli version --long
➜ osmos-sdk: 0.34.3
git commit: 1127446f71fa6aeada1bce2718f7f903cc18e548
vendor hash: b0ee613acca9a3a572b558d0481ec7baa008f732431392af81db3555c92c8dd7
build tags: netgo ledger
go version go1.11.5 darwin/amd64

Running a Cosmos Full Node on Mainnet (Cosmos Hub-2)

After successfully installing Gaia (in particular gaiad), let’s setup a Cosmos full-node and join the latest chain.

Setup the config files. Replace <moniker> for the public alias of your node (you can edit later):

$ gaiad init <moniker>

2. Then delete the default genesis.json file:

$ rm .gaiad/config/genesis.json

3. Let’s fetch the mainnet’s genesis file. At the time of writing, the chain-id is cosmoshub-2 (check the launch version here and paste below the link to the raw genesis file):

$ curl https://raw.githubusercontent.com/cosmos/launch/master/genesis.json > $HOME/.gaiad/config/genesis.json

4. Let’s add a persistent peer*. In the gaiad/config/config.toml file, go to lines ~117–118 persistent_peers = "":

persistent_peers = "89e4b72625c0a13d6f62e3cd9d40bfc444cbfa77@34.65.6.52:26656"# this is one of public full nodes

*On mainnet, if you are a genesis validator, you might want to add seed peers, the peers that your node will connect to at the beginning but not in the future, which will be released by the Tendermint team before mainnet launch. Seed peers are used only once, whereas persistent_peers are peers to which your node continuously connects to. On mainnet, make sure you can trust the persistent peers before adding them to the config file.

5. Let’s start your Cosmos node: