# Join the Cosmos Hub Mainnet
The current Cosmos Hub mainnet,
cosmoshub-4, has been performing in place store migration upgrades as of the Delta Upgrade (opens new window) July 2021. The most recent upgrade was Theta (opens new window) April 2022. This type of upgrade preserves the same chain-id but state before the upgrade height is only accessible by corresponding versions of the binary (ie. queries of state between height
8695000 should use
gaia v5.0.x (Delta) after
86950000 and before
10085397 should use
gaia v6.0.x (Vega) to guarantee correctly encoded responses. The roadmap documentation contains a history of upgrades (opens new window).). Visit the migration section (opens new window) of the Hub's docs for more information on previous chain migrations.
This guide includes full instructions for joining the mainnet either as an archive/full node or a pruned node.
For instructions to boostrap a node via Quicksync or State Sync, see the Quickstart Guide (opens new window)
For instructions to join as a validator, please also see the Validator Guide (opens new window).
- Getting Started
- Hardware Requirements
- General Configuration
- Sync Options
- Running via Background Process
- Exporting State
- Verify Mainnet
The current Cosmos Hub mainnet
cosmoshub-4. Visit the migration section (opens new window) of the Hub's docs for more information on previous chain migrations.
There are many explorers for the Cosmos Hub. For reference while setting up a node, here are a few recommendations:
- Mintscan (opens new window)
- Big Dipper (opens new window)
- Hubble (opens new window)
- Stake ID (opens new window)
# Getting Started
Make sure the following prerequisites are completed:
- Choose the proper hardware/server configuration. See the hardware guide.
- Ensure Gaia is properly installed. See the installation guide (opens new window) for a walkthrough.
- Follow the configuration guide to intialize and prepare the node to sync with the network.
Running a full archive node can be resource intensive as the full current
cosmoshub-4 state is over
1.4TB. For those who wish to run state sync or use quicksync, the following hardware configuration is recommended:
* Storage size for validators will depend on level of pruning.
# General Configuration
Make sure to walk through the basic setup and configuration. Operators will need to initialize
gaiad, download the genesis file for
cosmoshub-4, and set persistent peers and/or seeds for startup.
# Initialize Chain
Choose a custom moniker for the node and initialize. By default, the
init command creates the
~/.gaia directory with subfolders
data. In the
/config directory, the most important files for configuration are
Note: Monikers can contain only ASCII characters. Using Unicode characters is not supported and renders the node unreachable.
moniker can be edited in the
# Genesis File
Once the node is initialized, download the genesis file and move to the
/config directory of the Gaia home directory.
# Seeds & Peers
Upon startup the node will need to connect to peers. If there are specific nodes a node operator is interested in setting as seeds or as persistent peers, this can be configured in
Node operators can optionally download the Quicksync address book (opens new window). Make sure to move this to
# Gas & Fees
On Cosmos Hub mainnet, the accepted denom is
1atom = 1.000.000uatom
Transactions on the Cosmos Hub network need to include a transaction fee in order to be processed. This fee pays for the gas required to run the transaction. The formula is the following:
Gas is the smallest unit or pricing value required to perform a transaction. Different transactions require different amounts of
gas amount for a transaction is calculated as it is being processed, but it can be estimated beforehand by using the
auto value for the
gas flag. The gas estimate can be adjusted with the flag
1.0) to ensure enough
gas is provided for the transaction.
gasPrice is the price of each unit of
gas. Each validator sets a
min-gas-price value, and will only include transactions that have a
gasPrice greater than their
fees are the product of
gasPrice. The higher the
fees, the higher the chance that a transaction will get included in a block.
For mainnet, the recommended
A full-node keeps unconfirmed transactions in its mempool. In order to protect it from spam, it is better to set a
minimum-gas-prices that the transaction must meet in order to be accepted in the node's mempool. This parameter can be set in
The initial recommended
0.0025uatom, but this can be changed later.
# Pruning of State
Note: This is an optional configuration.
There are four strategies for pruning state. These strategies apply only to state and do not apply to block storage. A node operator may want to consider custom pruning if node storage is a concern or there is an interest in running an archive node.
To set pruning, adjust the
pruning parameter in the
The following pruning state settings are available:
everything: Prune all saved states other than the current state.
nothing: Save all states and delete nothing.
default: Save the last 100 states and the state of every 10,000th block.
custom: Specify pruning settings with the
By default, every node is in
default mode which is the recommended setting for most environments.
If a node operator wants to change their node's pruning strategy then this must be done before the node is initialized.
Passing a flag when starting
gaia will always override settings in the
app.toml file. To change the node's pruning setting to
everything mode then pass the
---pruning everything flag when running
Note: If running the node with pruned state, it will not be possible to query the heights that are not in the node's store.
# REST API
Note: This is an optional configuration.
By default, the REST API is disabled. To enable the REST API, edit the
~/.gaia/config/app.toml file, and set
true in the
Optionally activate swagger by setting
true or change the port of the REST API in the parameter
After restarting the application, access the REST API on
Note: This is an optional configuration.
By default, gRPC is enabled on port
~/.gaia/config/app.toml file is where changes can be made in the gRPC section. To disable the gRPC endpoint, set
false. To change the port, use the
# Sync Options
There are three main ways to sync a node on the Cosmos Hub; Blocksync, State Sync, and Quicksync. See the matrix below for the Hub's recommended setup configuration. This guide will focus on syncing two types of common nodes; full and pruned. For further information on syncing to run a validator node, see the section on Validators (opens new window).
There are two types of concerns when deciding which sync option is right. Data integrity refers to how reliable the data provided by a subset of network participants is. Historical data refers to how robust and inclusive the chain’s history is.
|Low Data Integrity||High Data Integrity|
|Minimal Historical Data||Quicksync - Pruned||State Sync|
|Moderate Historical Data||Quicksync - Default|
|Full Historical Data||Quicksync - Archive||Blocksync|
If a node operator wishes to run a full node, it is possible to start from scratch but will take a significant amount of time to catch up. Node operators not concerned with rebuilding original state from the beginning of
cosmoshub-4 can also leverage Quicksync's available archive history.
Make sure to consult the hardware section for guidance on the best configuration for the type of node operating.
Saving and serving snapshots helps nodes rapidly join the network. Snapshots are now enabled by default effective
While not advised, if a node operator needs to customize this feature, it can be configured in
~/.gaia/config/app.toml. The Cosmos Hub recommends setting this value to match
Note: It is highly recommended that node operators use the same value for snapshot-interval in order to aid snapshot discovery. Discovery is easier when more nodes are serving the same snapshots.
# Releases & Upgrades
See all Gaia Releases (opens new window)
The most up to date release of Gaia is
V6.0.0 (opens new window). For those that want to use state sync or quicksync to get their node up to speed, starting with the most recent version of Gaia is sufficient.
To sync an archive or full node from scratch, it is important to note that you must start with
V4.2.1 (opens new window) and proceed through two different upgrades Delta at block height
6910000 and Vega at block height
The process is summarized below but make sure to follow the manual upgrade instructions for each release:
Delta Instructions (opens new window)
V4 reaches the upgrade block height, expect the chain to halt and to see the following message:
Make sure to save a backup of
~/.gaia in case rolling back is necessary.
V5.0.0 (opens new window) and restart the daemon.
V5 reaches the upgrade block height, the chain will halt and display the following message:
Again, make sure to backup
V6.0.0 (opens new window) and restart the daemon.
Cosmovisor is a process manager developed to relieve node operators of having to manually intervene every time there is an upgrade. Cosmovisor monitors the governance module for upgrade proposals; it will take care of downloading the new binary, stopping the old one, switching to the new one, and restarting.
For more information on how to run a node via Cosmovisor, check out the docs (opens new window).
# Running via Background Process
To run the node in a background process with automatic restarts, it's recommended to use a service manager like
systemd. To set this up run the following:
If using Cosmovisor then make sure to add the following:
LimitNOFILE line and replace
$(which gaiad) with
Run the following to setup the daemon:
Then start the process and confirm that it's running.
# Exporting State
Gaia can dump the entire application state into a JSON file. This application state dump is useful for manual analysis and can also be used as the genesis file of a new network.
Note: The node can't be running while exporting state, otherwise the operator can expect a
resource temporarily unavailableerror.
Export state with:
It is also possible to export state from a particular height (at the end of processing the block of that height):
If planning to start a new network from the exported state, export with the
# Verify Mainnet
Help to prevent a catastrophe by running invariants on each block on your full node. In essence, by running invariants the node operator ensures that the state of mainnet is the correct expected state. One vital invariant check is that no atoms are being created or destroyed outside of expected protocol, however there are many other invariant checks each unique to their respective module. Because invariant checks are computationally expensive, they are not enabled by default. To run a node with these checks start your node with the assert-invariants-blockly flag:
If an invariant is broken on the node, it will panic and prompt the operator to send a transaction which will halt mainnet. For example the provided message may look like: