cosmoshub node guide

The Cosmos Hub.

Installation

Before you start. Replace every <PLACEHOLDER> with your own value and double-check the commands against the project's official documentation. Never share your mnemonic or priv_validator_key.json, and never run the same validator key on two servers.

1. Install dependencies

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git wget htop tmux build-essential jq make lz4 gcc unzip ufw

2. Install Go

cd $HOME
VER="1.22.5"
wget "https://golang.org/dl/go$VER.linux-amd64.tar.gz"
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf "go$VER.linux-amd64.tar.gz"
rm "go$VER.linux-amd64.tar.gz"
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> $HOME/.bash_profile
source $HOME/.bash_profile
go version

3. Build the binary

cd $HOME
rm -rf gaia
git clone https://github.com/cosmos/gaia
cd gaia
git checkout <VERSION>
make install

# check the binary
gaiad version --long | grep -e version -e commit

4. Initialise the node

gaiad init <MONIKER> --chain-id cosmoshub-4 --home $HOME/.gaia
gaiad config set client chain-id cosmoshub-4 --home $HOME/.gaia
gaiad config set client keyring-backend file --home $HOME/.gaia
gaiad config set client node tcp://localhost:11657 --home $HOME/.gaia

5. Genesis and addrbook

wget -O $HOME/.gaia/config/genesis.json <GENESIS_URL>
wget -O $HOME/.gaia/config/addrbook.json <ADDRBOOK_URL>

6. Configure the node

# minimum gas price, seeds and peers
sed -i -e "s|^minimum-gas-prices *=.*|minimum-gas-prices = \"0.0025uatom\"|" $HOME/.gaia/config/app.toml
sed -i -e "s|^seeds *=.*|seeds = \"<SEEDS>\"|" $HOME/.gaia/config/config.toml
sed -i -e "s|^persistent_peers *=.*|persistent_peers = \"<PEERS>\"|" $HOME/.gaia/config/config.toml

# pruning (validator)
sed -i -e 's|^pruning *=.*|pruning = "custom"|' \
       -e 's|^pruning-keep-recent *=.*|pruning-keep-recent = "100"|' \
       -e 's|^pruning-keep-every *=.*|pruning-keep-every = "0"|' \
       -e 's|^pruning-interval *=.*|pruning-interval = "19"|' $HOME/.gaia/config/app.toml

# indexer off for a validator-only node (keep "kv" if this node serves RPC/API to users)
sed -i -e 's|^indexer *=.*|indexer = "null"|' $HOME/.gaia/config/config.toml

# prometheus metrics (bound by the port plan below, keep it firewalled)
sed -i -e 's|^prometheus *=.*|prometheus = true|' $HOME/.gaia/config/config.toml

7. Custom ports

# every chain on the server gets its own port block (11xxx) so nodes never collide
PORT=11

sed -i.bak -e "s%:26658%:${PORT}658%g; s%:26657%:${PORT}657%g; s%:6060%:${PORT}060%g; s%:26656%:${PORT}656%g; s%:26660%:${PORT}660%g" $HOME/.gaia/config/config.toml
sed -i.bak -e "s%:1317%:${PORT}317%g; s%:8080%:${PORT}080%g; s%:9090%:${PORT}090%g; s%:9091%:${PORT}091%g; s%:8545%:${PORT}545%g; s%:8546%:${PORT}546%g; s%:6065%:${PORT}065%g" $HOME/.gaia/config/app.toml

# advertise the public p2p port
EXT_IP=$(curl -s https://api.ipify.org)
sed -i -e "s|^external_address *=.*|external_address = \"${EXT_IP}:${PORT}656\"|" $HOME/.gaia/config/config.toml

# open ONLY the p2p port to the world; RPC/API/gRPC stay private
sudo ufw allow ${PORT}656/tcp comment 'gaiad p2p'

8. Create the service

sudo tee /etc/systemd/system/gaiad.service > /dev/null <<EOF2
[Unit]
Description=gaiad node
After=network-online.target

[Service]
User=$USER
ExecStart=$(which gaiad) start --home $HOME/.gaia
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF2

sudo systemctl daemon-reload
sudo systemctl enable gaiad

9. Start and sync

sudo systemctl start gaiad
sudo journalctl -u gaiad -f -o cat

# in another terminal: wait until "catching_up" is false
gaiad status 2>&1 | jq .sync_info

10. Wallet and validator

# 1) wallet (write the mnemonic down OFFLINE; never share it)
gaiad keys add wallet --keyring-backend file --home $HOME/.gaia
# or restore:  gaiad keys add wallet --recover

# 2) fund the wallet, then wait for the node to finish syncing (catching_up = false)

# 3) validator definition
cat > $HOME/validator.json <<EOF2
{
  "pubkey": $(gaiad comet show-validator --home $HOME/.gaia),
  "amount": "1000000uatom",
  "moniker": "<MONIKER>",
  "identity": "<KEYBASE_IDENTITY>",
  "website": "<WEBSITE>",
  "security": "<SECURITY_EMAIL>",
  "details": "<DETAILS>",
  "commission-rate": "0.05",
  "commission-max-rate": "0.20",
  "commission-max-change-rate": "0.01",
  "min-self-delegation": "1"
}
EOF2

# 4) create the validator
gaiad tx staking create-validator $HOME/validator.json \
  --from wallet \
  --chain-id cosmoshub-4 \
  --keyring-backend file \
  --gas auto --gas-adjustment 1.5 --gas-prices 0.0025uatom \
  --home $HOME/.gaia -y

Cheat sheet

### Node
gaiad status 2>&1 | jq .sync_info                 # sync status
sudo journalctl -u gaiad -f -o cat                  # live logs
sudo systemctl restart gaiad                        # restart
curl -s localhost:11657/net_info | jq .result.n_peers   # peers count

### Keys and balance
gaiad keys list --home $HOME/.gaia
gaiad q bank balances $(  gaiad keys show wallet -a --home $HOME/.gaia  )

### Staking
gaiad tx staking delegate <VALOPER> 1000000uatom --from wallet --chain-id cosmoshub-4 --gas auto --gas-adjustment 1.5 --gas-prices 0.0025uatom -y
gaiad tx distribution withdraw-all-rewards --from wallet --chain-id cosmoshub-4 --gas auto --gas-adjustment 1.5 --gas-prices 0.0025uatom -y
gaiad tx distribution withdraw-rewards <VALOPER> --commission --from wallet --chain-id cosmoshub-4 --gas auto --gas-adjustment 1.5 --gas-prices 0.0025uatom -y

### Validator
gaiad tx slashing unjail --from wallet --chain-id cosmoshub-4 --gas auto --gas-adjustment 1.5 --gas-prices 0.0025uatom -y
gaiad q staking validator <VALOPER>
gaiad q slashing signing-info $(gaiad comet show-validator --home $HOME/.gaia)

### Governance
gaiad q gov proposals --status voting_period
gaiad tx gov vote <PROPOSAL_ID> yes --from wallet --chain-id cosmoshub-4 --gas auto --gas-adjustment 1.5 --gas-prices 0.0025uatom -y