# 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 is Gaia v14.1.x (opens new window) Dec 2023.
This type of upgrade preserves the same chain-id but state before the upgrade height is only accessible by corresponding versions of the binary:
# Release History
- use
gaia v5.0.x
(Delta) for queries of state between height6,910,000
and8,695,000
- use
gaia v6.0.x
(Vega) between8,695,000
and10,085,397
- use
gaia v7.0.x
(Theta) between10,085,397
and14,099,412
- use
gaia v8.0.x
(Rho) between14,099,412
and14,470,501
- use
gaia v9.0.x
(Lambda) between14,470,501
and15,213,800
- use
gaia v9.1.x
between15,213,800
and15,816,200
- use
gaia v10.0.x
between15,816,200
and16,596,000
- use
gaia v11.x
between16,596,000
and16,985,500
- use
gaia v12.x
between16,985,500
and17,380,000
- use
gaia v13.x
between17,380,000
and18,262,000
- use
gaia v14.1.x
from18,262,000
For more details, see the history of upgrades (opens new window) or visit the migration section (opens new window) of the Hub's docs.
This guide includes full instructions for joining the mainnet either as an archive/full node or a pruned node.
For instructions to bootstrap 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).
# Overview
- Join the Cosmos Hub Mainnet
# Background
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.
# Explorers
There are many explorers for the Cosmos Hub. For reference while setting up a node, here are a few recommendations:
# 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 walk-through.
- Follow the configuration guide to initialize and prepare the node to sync with the network.
# Hardware
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:
Node Type | RAM | Storage |
---|---|---|
Validator | 32GB | 500GB-2TB* |
Full | 16GB | 2TB |
Default | 16GB | 1TB |
* 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 config
and data
. In the /config
directory, the most important files for configuration are app.toml
and config.toml
.
Note: Monikers can contain only ASCII characters. Using Unicode characters is not supported and renders the node unreachable.
The moniker
can be edited in the ~/.gaia/config/config.toml
file:
# 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 ~/.gaia/config/config.toml
Node operators can optionally download the Quicksync address book (opens new window). Make sure to move this to ~/.gaia/config/addrbook.json
.
# Gas & Fees
On Cosmos Hub mainnet, the accepted denom is uatom
, where 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
. The 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 --gas-adjustment
(default 1.0
) to ensure enough gas
is provided for the transaction.
The 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 min-gas-price
.
The transaction fees
are the product of gas
and gasPrice
. The higher the gasPrice
/fees
, the higher the chance that a transaction will get included in a block.
For mainnet, the recommended gas-prices
is 0.0025uatom
.
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 ~/.gaia/config/app.toml
.
The initial recommended min-gas-prices
is 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 ~/.gaia/config/app.toml
file.
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 thepruning-keep-recent
,pruning-keep-every
, andpruning-interval
parameters.
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.
In ~/.gaia/config/app.toml
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 gaiad start
.
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 enable
to true
in the [api]
section.
Optionally activate swagger by setting swagger
to true
or change the port of the REST API in the parameter address
.
After restarting the application, access the REST API on <NODE IP>:1317
.
# GRPC
Note: This is an optional configuration.
By default, gRPC is enabled on port 9090
. The ~/.gaia/config/app.toml
file is where changes can be made in the gRPC section. To disable the gRPC endpoint, set enable
to false
. To change the port, use the address
parameter.
# 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.
For operators interested in bootstrapping a pruned node, either Quicksync or State Sync would be sufficient.
Make sure to consult the hardware section for guidance on the best configuration for the type of node operating.
# Snapshots
Saving and serving snapshots helps nodes rapidly join the network. Snapshots are now enabled by default effective 1/20/21
.
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 pruning-keep-every
in config.toml
.
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.
In app.toml
# Releases & Upgrades
See all Gaia Releases (opens new window)
The most up to date release of Gaia is above. 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 6,910,000
, Vega at block height 8,695,000
, Theta at block height 10,085,397
, Rho at block height 14099412
and Lambda at block height 14,470,501
and so on.
The process is summarized below but make sure to follow the manual upgrade instructions for each release:
Delta Instructions (opens new window)
Once 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.
Install Gaia V5.0.0
(opens new window) and restart the daemon.
Vega Instructions (opens new window)
Once V5
reaches the upgrade block height, the chain will halt and display the following message:
Again, make sure to backup ~/.gaia
Install Gaia V6.0.0
(opens new window) and restart the daemon.
Theta Instructions (opens new window)
Once V6
reaches the upgrade block height, the chain will halt and display the following message:
Again, make sure to backup ~/.gaia
Install Gaia V7.0.0
(opens new window) and restart the daemon.
Rho Instructions (opens new window)
Once V7
reaches the upgrade block height, the chain will halt and display the following message:
Again, make sure to backup ~/.gaia
Install Gaia V8.0.0
(opens new window) and restart the daemon.
Lambda Instructions (opens new window)
Once V8
reaches the upgrade block height, the chain will halt and display the following message:
Again, make sure to backup ~/.gaia
Install Gaia V9.0.0
(opens new window) and restart the daemon.
Repeat the process for newer versions of the Gaia application at the stated block heights above.
# Cosmovisor
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:
After the LimitNOFILE
line and replace $(which gaiad)
with $(which cosmovisor)
.
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 unavailable
error.
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 --for-zero-height
flag:
# 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 --x-crisis-skip-assert-invariants 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: