# Join the Cosmos Hub Public Testnet
This tutorial will provide all necessary instructions for joining the current public testnet. If you're interested in more advanced configuration and synchronization options, see Join Mainnet for a detailed walkthrough.
- Current Version: v9-Lambda
- Chain ID:
The Cosmos Hub Public Testnet is currently running Gaia v8. Visit the testnet explorer (opens new window) to view all on-chain activity.
For those who just need instructions on performing the upgrade, see the Upgrading Your Node section.
# Version History
The table below shows all past and upcoming versions of the public testnet.
|Release||Upgrade Block Height||Upgrade Date|
See the Gaia release page (opens new window) for details on each release.
# How to Join
We offer three ways to set up a node in the testnet:
- Quickstart scripts
- The testnets (opens new window) repo has shell scripts to set up a node with a single command.
- Ansible playbooks
- The cosmos-ansible (opens new window) repo has an inventory file to set up a node with a single command.
- Step-by-step instructions
- The rest of this document provides a step-by-step walkthrough for setting up a testnet node.
We recommend running public testnet nodes on machines with at least 8 cores, 16GB of RAM, and 300GB of disk space.
# Sync Options
There are two ways to sync a testnet node, Fastsync and State Sync.
- Fast Sync (opens new window) syncs the chain from genesis by downloading blocks in parallel and then verifying them.
- State Sync (opens new window) will look for snapshots from peers at a trusted height and then verifying a minimal set of snapshot chunks against the network.
State Sync is far faster and more efficient than Fast Sync, but Fast Sync offers higher data integrity and more robust history. For those who are concerned about storage and costs, State Sync can be the better option as it minimizes storage usage when rebuilding initial state.
# Step-by-Step Setup
The following set of instructions assumes you are logged in as root.
- You can run the relevant commands from a sudoer account.
/root/part in service file paths can be changed to
# Build Tools
Install build tools and Go.
# Installation & Configuration
You will need to install and configure the Gaia binary using the script below. The Cosmos Hub Public Testnet is running Gaia
v9.0.0-rc6 (opens new window).
- For up-to-date endpoints like seeds and state sync RPC servers, visit the testnets repository (opens new window).
Build the gaiad binary and initialize the chain home folder.
Prepare the genesis file.
# State Sync Setup (Recommended)
State sync requires you to configure a trust height and trust hash. These depend on the current block height, so they will vary depending on when you are joining the network.
- Visit a testnet explorer (opens new window) to find the block and hash for the current height - 1000.
- Set these parameters in the code snippet below:
- For example, if the block explorer lists a current block height of 12,563,326, we could use a trust height of 12,562,000 (opens new window) and the trust hash would be
# Cosmovisor Setup (Optional)
Cosmovisor is a process manager that monitors the governance module for incoming chain upgrade proposals. When a proposal is approved, Cosmovisor can automatically download the new binary, stop the chain binary when it hits the upgrade height, switch to the new binary, and restart the daemon. Cosmovisor can be used with either Fast Sync or State Sync.
The instructions below provide a simple way to sync via Cosmovisor. For more information on configuration, check out the Cosmos SDK's Cosmovisor documentation (opens new window).
Cosmovisor requires the creation of the following directory structure:
Install Cosmovisor and copy Gaia binary to genesis folder
# Create Service File
- Cosmos Hub recommends running
--x-crisis-skip-assert-invariantsflag. If checking for invariants, operators are likely to see
rounding error withdrawing rewards from validator. These are expected. For more information see Verify Mainnet.
Create one of the following service files.
If you are not using Cosmovisor:
If you are using Cosmovisor:
# Start the Service
Reload the systemd manager configuration.
If you are not using Cosmovisor:
If you are using Cosmovisor:
To follow the service log, run
journalctl -fu gaiad or
journalctl -fu cosmovisor.
- If you are using State Sync, the chain will start syncing once a snapshot is found and verified. Syncing to the current block height should take less than half an hour.
- If you are using Fast Sync, the chain will start syncing once the first block after genesis is found among the peers. Syncing to the current block height will take several days.
# Create a Validator (Optional)
If you want to create a validator in the testnet, request tokens through the faucet Discord channel (opens new window) and follow the Running a validator instructions provided for mainnet.
# Upgrading Your Node
Follow these instructions if you have a node that is already synced and wish to participate in a scheduled testnet software upgrade.
When the chain reaches the upgrade block height specified by a software upgrade proposal, the chain binary will halt and expect the new binary to be run (the system log will show
ERR UPGRADE "<Upgrade name>" NEEDED at height: XXXX or something similar).
There are three ways you can update the binary:
- Without Cosmovisor: You must build or download the new binary ahead of the upgrade. When the chain binary halts at the upgrade height:
- Stop the gaiad service with
systemctl stop gaiad.service.
- Build or download the new binary, replacing the existing
- Start the gaiad service with
systemctl start gaiad.service.
- With Cosmovisor: You must build or download the new binary and copy it to the appropriate folder ahead of the upgrade.
- With Cosmovisor: Using the auto-download feature, assuming the proposal includes the binaries for your system architecture.
The instructions below are for option 2. For more information on auto-download with Cosmovisor, see the relevant documentation (opens new window) in the Cosmos SDK repo.
If the environment variable
DAEMON_ALLOW_DOWNLOAD_BINARIES is set to
false, Cosmovisor will look for the new binary in a folder that matches the name of the upgrade specified in the software upgrade proposal. For the
v9-Lambda upgrade, the expected folder structure would look as follows:
Note: for Cosmovisor v1.0.0, the upgrade name folder is not lowercased (use
Prepare the upgrade directory
Download and install the new binary version.
When the upgrade height is reached, Cosmovisor will stop the gaiad binary, copy the new binary to the
current/bin folder and restart. After a few minutes, the node should start syncing blocks using the new binary.