Joining Mainnet - Cosmos Docs

Cosmos Hub 主网的 chain-id 是 cosmoshub-4。

发布历史

在高度 6,910,000 到 8,695,000 之间查询状态时，使用 gaia v5.0.x（Delta）
在 8,695,000 到 10,085,397 之间使用 gaia v6.0.x（Vega）
在 10,085,397 到 14,099,412 之间使用 gaia v7.0.x（Theta）
在 14,099,412 到 14,470,501 之间使用 gaia v8.0.x（Rho）
在 14,470,501 到 15,213,800 之间使用 gaia v9.0.x（Lambda）
在 15,213,800 到 15,816,200 之间使用 gaia v9.1.x
在 15,816,200 到 16,596,000 之间使用 gaia v10.0.x
在 16,596,000 到 16,985,500 之间使用 gaia v11.x
在 16,985,500 到 17,380,000 之间使用 gaia v12.x
在 17,380,000 到 18,262,000 之间使用 gaia v13.x
在 18,262,000 到 19,639,600 之间使用 gaia v14.1.x
在 19,639,600 到 19,939,000 之间使用 gaia v15.1.x
在 19,939,000 到 20,440,500 之间使用 gaia v15.2.x
从 20,440,500 到 20,739,800 使用 gaia v16.x
从 20,739,800 起使用 gaia v17.1.x

本指南包含以归档/全节点或裁剪节点形式加入主网的完整说明。 如需通过 Quicksync 或 State Sync 引导节点，请参阅快速开始指南如需以验证者身份加入，请同时参阅验证者指南。

浏览器

Cosmos Hub 有许多浏览器。为了方便你在搭建节点时参考，这里推荐几个：

Mintscan

开始之前

请确保已完成以下前置条件：

选择合适的硬件/服务器配置。参见硬件指南。
确保已正确安装 Gaia。安装步骤请参见安装指南。
按照配置指南初始化并准备节点，以便与网络同步。

硬件

运行一个完整归档节点会占用较多资源，因为当前完整的 cosmoshub-4 状态已超过 1.4TB。对于希望运行状态同步或使用 quicksync 的用户，推荐以下硬件配置：

节点类型	内存	存储
验证者	32GB	500GB-2TB*
全节点	16GB	2TB
默认	16GB	1TB

* 验证者所需存储空间取决于裁剪级别。

通用配置

请务必完成基础设置与配置。运营者需要初始化 gaiad、下载 cosmoshub-4 的创世文件，并为启动设置持久对等节点和/或种子节点。

初始化链

为节点选择一个自定义 moniker 并进行初始化。默认情况下，init 命令会创建 ~/.gaia 目录，以及其中的 config 和 data 子目录。在 /config 目录中，最重要的配置文件是 app.toml 和 config.toml。

gaiad init <custom-moniker>

注意：Moniker 只能包含 ASCII 字符。不支持使用 Unicode 字符，否则节点将无法被访问。

moniker 可以在 ~/.gaia/config/config.toml 文件中编辑：

# A custom human readable name for this node
moniker = "<custom_moniker>"

创世文件

节点初始化完成后，下载创世文件并移动到 Gaia 主目录下的 /config 目录中。

wget https://raw.githubusercontent.com/cosmos/mainnet/master/genesis/genesis.cosmoshub-4.json.gz
gzip -d genesis.cosmoshub-4.json.gz
mv genesis.cosmoshub-4.json ~/.gaia/config/genesis.json

Seeds 与 Peers

节点启动时需要连接到其他对等节点。如果节点运营者希望将特定节点配置为 seeds 或 persistent peers，可在 ~/.gaia/config/config.toml 中进行设置。

# Comma separated list of seed nodes to connect to
seeds = "<seed node id 1>@<seed node address 1>:26656,<seed node id 2>@<seed node address 2>:26656"


# Comma separated list of nodes to keep persistent connections to
persistent_peers = "<node id 1>@<node address 1>:26656,<node id 2>@<node address 2>:26656"

节点运营者也可以选择下载 Quicksync address book。请确保将其移动到 ~/.gaia/config/addrbook.json。

Gas 与费用

在 Cosmos Hub 主网上，接受的 denom 是 uatom，其中 1atom = 1.000.000uatom Cosmos Hub 网络上的交易需要包含交易费才能被处理。这笔费用用于支付运行交易所需的 gas。计算公式如下：

fees = ceil(gas * gasPrices)

Gas 是执行交易所需的最小单位或计价值。不同交易需要不同数量的 gas。交易的 gas 数量会在处理过程中计算出来，但也可以通过将 gas 参数设为 auto 预先估算。可以使用 --gas-adjustment 参数（默认值为 1.0）调整 gas 估算值，以确保为交易提供足够的 gas。 gasPrice 是每单位 gas 的价格。每个验证者都会设置一个 min-gas-price 值，并且只会打包 gasPrice 高于其 min-gas-price 的交易。交易 fees 是 gas 与 gasPrice 的乘积。gasPrice/fees 越高，交易被打包进区块的概率就越高。 对于主网，推荐的 gas-prices 为 0.0025uatom。 全节点会在其 mempool 中保留未确认交易。为了防止垃圾交易，更好的做法是设置一个 minimum-gas-prices，只有达到该门槛的交易才会被节点的 mempool 接受。这个参数可以在 ~/.gaia/config/app.toml 中设置。

# The minimum gas prices a validator is willing to accept for processing a

# transaction. A transaction's fees must meet the minimum of any denomination

# specified in this config (e.g. 0.25token1;0.0001token2).
minimum-gas-prices = "0.0025uatom"

初始推荐的 min-gas-prices 是 0.0025uatom，但后续可以修改。

状态裁剪

注意：这是一个可选配置。

状态裁剪共有四种策略。这些策略只适用于状态，不适用于区块存储。如果节点存储空间是一个问题，或者你有运行归档节点的需求，可以考虑自定义裁剪。要设置裁剪，请调整 ~/.gaia/config/app.toml 文件中的 pruning 参数。可用的状态裁剪设置如下：

everything：裁剪除当前状态外的所有已保存状态。
nothing：保存所有状态，不删除任何内容。
default：保存最近 100 个状态，以及每 10,000 个区块的状态。
custom：通过 pruning-keep-recent、pruning-keep-every 和 pruning-interval 参数指定裁剪设置。

默认情况下，每个节点都处于 default 模式，这是大多数环境下推荐的设置。如果节点运营者想修改其节点的裁剪策略，那么必须在节点初始化之前完成此操作。在 ~/.gaia/config/app.toml 中：

# default: the last 100 states are kept in addition to every 500th state; pruning at 10 block intervals

# nothing: all historic states will be saved, nothing will be deleted (i.e. archiving node)

# everything: all saved states will be deleted, storing only the current state; pruning at 10 block intervals

# custom: allow pruning options to be manually specified through 'pruning-keep-recent', 'pruning-keep-every', and 'pruning-interval'
pruning = "custom"


# These are applied if and only if the pruning strategy is custom.
pruning-keep-recent = "10"
pruning-keep-every = "1000"
pruning-interval = "10"

启动 gaia 时传入的参数始终会覆盖 app.toml 文件中的设置。要将节点的裁剪设置改为 everything 模式，请在运行 gaiad start 时传入 ---pruning everything 参数。

注意：如果节点以裁剪状态运行，将无法查询不在节点存储中的高度。

REST API

注意：这是一个可选配置。

默认情况下，REST API 是禁用的。要启用 REST API，请编辑 ~/.gaia/config/app.toml 文件，并在 [api] 部分将 enable 设置为 true。

###############################################################################

###                           API Configuration                             ###
###############################################################################
[api]

# Enable defines if the API server should be enabled.
enable = true

# Swagger defines if swagger documentation should automatically be registered.
swagger = false

# Address defines the API server to listen on.
address = "tcp://0.0.0.0:1317"

你也可以选择将 swagger 设置为 true 来启用 swagger，或通过 address 参数修改 REST API 的端口。重启应用后，可以通过 <NODE IP>:1317 访问 REST API。

GRPC

注意：这是一个可选配置。

默认情况下，gRPC 在端口 9090 上启用。可以在 ~/.gaia/config/app.toml 文件的 gRPC 部分进行修改。要禁用 gRPC 端点，请将 enable 设置为 false。要修改端口，请使用 address 参数。

###############################################################################

###                           gRPC Configuration                            ###
###############################################################################
[grpc]

# Enable defines if the gRPC server should be enabled.
enable = true

# Address defines the gRPC server address to bind to.
address = "0.0.0.0:9090"

同步选项

在 Cosmos Hub 上同步节点主要有三种方式：Blocksync、State Sync 和 Quicksync。Hub 推荐的配置请见下表。本指南将重点介绍两类常见节点的同步方式：全节点和裁剪节点。若需进一步了解用于运行验证者节点的同步方式，请参阅验证者章节。在决定哪种同步方式合适时，主要有两类考量。数据完整性指的是由网络中部分参与者提供的数据有多可靠。历史数据指的是链历史的完整性和覆盖程度。

	低数据完整性	高数据完整性
最少历史数据	Quicksync - Pruned	State Sync
中等历史数据	Quicksync - Default
完整历史数据	Quicksync - Archive	Blocksync

如果节点运营者希望运行全节点，可以从零开始同步，但追上当前链高度会耗费大量时间。不关心从 cosmoshub-4 起点重建原始状态的节点运营者，也可以利用 Quicksync 提供的归档历史数据。对于希望快速启动裁剪节点的运营者来说，Quicksync 或 State Sync 都已足够。请务必参阅硬件章节，以了解适合所运行节点类型的最佳配置建议。

Blocksync

Blocksync 比传统共识更快，它通过下载区块并基于验证者的默克尔树进行校验，从创世块开始同步整条链。更多信息请参阅 CometBFT 的 Blocksync 文档通过 Blocksync 同步时，节点运营者要么需要手动升级链，要么需要配置 Cosmovisor 以实现自动升级。也可以从 Cosmos Hub 的早期版本开始同步。请参考下表选择正确的 gaia 版本。历史创世文件请参阅 mainnet archive。

Chain Id	Gaia 版本
`cosmoshub-4`	`v4.2.1`
`cosmoshub-3`	`v2.0.x`
`cosmoshub-2`	`v1.0.x`
`cosmoshub-1`	`v0.0.x`

开始使用

使用 skip-invariants 标志启动 Gaia 以开始同步。更多信息请参阅验证主网。

gaiad start --x-crisis-skip-assert-invariants

节点将开始重建状态，直到在区块 6910000 遇到第一次升级高度。如果已经配置好 Cosmovisor，则除了等待之外无需额外操作；否则，节点运营者需要手动执行两次升级。

State Sync

State Sync 是一种高效且快速的新节点启动方式，它通过直接回放更大的应用状态分片，而不是逐个回放区块或共识轮次来完成同步。更多信息请参阅 CometBFT 的 State Sync 文档。要启用 state sync，请访问区块浏览器获取最近的区块高度及其对应哈希。节点运营者可以选择当前绑定期内的任意高度/哈希，但由于推荐的快照周期是 1000 个区块，建议选择接近 当前高度 - 1000 的值。选定区块高度和哈希后，更新 ~/.gaia/config/config.toml 中的配置，将 enable = true，并填写 trust_height 和 trust_hash。节点运营者可以将 rpc 服务器配置为偏好的提供方，但列表中至少需要两个条目。重要的是，这两个 rpc 服务器必须是节点运营者信任的服务器，用于校验链状态的组成部分。虽然不推荐，但当前并不会强制要求唯一性，因此即使在列表中重复填写同一个服务器，仍然有可能成功同步。

注意：未来，RPC 服务器这一要求将被废弃，因为 state sync 将迁移到 Tendermint 0.38 的 p2p 层。

#######################################################

###         State Sync Configuration Options        ###
#######################################################
[statesync]

# State sync rapidly bootstraps a new node by discovering, fetching, and restoring a state machine

# snapshot from peers instead of fetching and replaying historical blocks. Requires some peers in

# the network to take and serve state machine snapshots. State sync is not attempted if the node

# has any local state (LastBlockHeight > 0). The node will have a truncated block history,

# starting from the height of the snapshot.
enable = true


# RPC servers (comma-separated) for light client verification of the synced state machine and

# retrieval of state data for node bootstrapping. Also needs a trusted height and corresponding

# header hash obtained from a trusted source, and a period during which validators can be trusted.
#

# For Cosmos SDK-based chains, trust_period should usually be about 2/3 of the unbonding time (~2

# weeks) during which they can be financially punished (slashed) for misbehavior.
rpc_servers = "https://cosmos-rpc.polkachu.com:443,https://rpc-cosmoshub-ia.cosmosia.notional.ventures:443"
trust_height = 8959784
trust_hash = "3D8F12EA302AEDA66E80939F7FC785206692F8B6EE6F727F1655F1AFB6A873A5"
trust_period = "168h0m0s"

启动 Gaia 开始进行 state sync。节点获取快照可能需要一些时间，但命令和输出应与以下内容类似：

$ gaiad start --x-crisis-skip-assert-invariants

...

> INF Discovered new snapshot format=1 hash="0x000..." height=8967000 module=statesync

...

> INF Fetching snapshot chunk chunk=4 format=1 height=8967000 module=statesync total=45
> INF Applied snapshot chunk to ABCI app chunk=0 format=1 height=8967000 module=statesync total=45

state sync 成功完成后，节点将开始正常处理区块。如果 state sync 失败，并且节点运营者遇到如下错误：State sync failed err="state sync aborted"，可以尝试重新启动 gaiad，或执行 gaiad unsafe-reset-all（执行前请务必备份所有配置和历史数据）。

Quicksync

Quicksync.io 提供多个 Cosmos Hub 的每日快照，裁剪级别不同（archive 1.4TB、default 540GB、pruned 265GB）。下载和安装说明请参阅 Cosmos Quicksync 指南。

快照

保存并提供快照可以帮助节点快速加入网络。自 1/20/21 起，快照已默认启用。虽然不建议这样做，但如果节点运营者需要自定义此功能，可以在 ~/.gaia/config/app.toml 中进行配置。Cosmos Hub 建议将该值设置为与 config.toml 中的 pruning-keep-every 一致。

注意：强烈建议节点运营者为 snapshot-interval 使用相同的值，以帮助快照发现。当更多节点提供相同的快照时，发现过程会更容易。

在 app.toml 中

###############################################################################

###                        State Sync Configuration                         ###
###############################################################################

# State sync snapshots allow other nodes to rapidly join the network without replaying historical

# blocks, instead downloading and applying a snapshot of the application state at a given height.
[state-sync]

# snapshot-interval specifies the block interval at which local state sync snapshots are

# taken (0 to disable). Must be a multiple of pruning-keep-every.
snapshot-interval = 1000

# snapshot-keep-recent specifies the number of recent snapshots to keep and serve (0 to keep all).
snapshot-keep-recent = 10

Cosmovisor

Cosmovisor 是一个进程管理器，旨在减轻节点运营者在每次升级时都需要手动干预的负担。Cosmovisor 会监控治理模块中的升级提案；它会负责下载新的二进制文件、停止旧版本、切换到新版本并重新启动。如需了解如何通过 Cosmovisor 运行节点，请查阅文档。

通过后台进程运行

要让节点以后台进程方式运行并自动重启，建议使用 systemd 这样的服务管理器。可通过以下命令进行设置：

sudo tee /etc/systemd/system/<service name>.service > /dev/null <<EOF  
[Unit]
Description=Gaia Daemon
After=network-online.target

[Service]
User=$USER
ExecStart=$(which gaiad) start
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
EOF

如果使用 Cosmovisor，请确保添加以下内容：

Environment="DAEMON_HOME=$HOME/.gaia"
Environment="DAEMON_NAME=gaiad"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"

将这些内容添加在 LimitNOFILE 之后，并将 $(which gaiad) 替换为 $(which cosmovisor)。运行以下命令以设置守护进程：

sudo -S systemctl daemon-reload
sudo -S systemctl enable <service name>

然后启动进程并确认其正在运行。

sudo -S systemctl start <service name>

sudo service <service name> status

导出状态

Gaia 可以将整个应用状态导出为一个 JSON 文件。这个应用状态导出对于手动分析很有用，也可以作为新网络的创世文件使用。

注意：导出状态时节点不能处于运行状态，否则运营者可能会遇到 resource temporarily unavailable 错误。

使用以下命令导出状态：

gaiad export > [filename].json

也可以从特定高度导出状态（在处理完该高度对应区块后导出）：

gaiad export --height [height] > [filename].json

如果计划基于导出的状态启动一个新网络，请使用 --for-zero-height 标志进行导出：

gaiad export --height [height] --for-zero-height > [filename].json

验证主网

通过在全节点的每个区块上运行不变量检查，帮助避免灾难性问题。其本质是，运行不变量检查可以让节点运营者确认主网状态是正确且符合预期的状态。一个关键的不变量检查是，确保没有 atom 在预期协议之外被创建或销毁，不过还有许多其他不变量检查，它们分别对应各自的模块。由于不变量检查的计算开销较高，因此默认不会启用。要在运行这些检查的情况下启动节点，请在启动时不要带上 --x-crisis-skip-assert-invariants 标志：

gaiad start

如果节点上的某个不变量被破坏，节点会 panic，并提示运营者发送一笔会使主网停止的交易。例如，给出的消息可能如下所示：

invariant broken:
    loose token invariance:
        pool.NotBondedTokens: 100
        sum of account tokens: 101
    CRITICAL please submit the following transaction:
        gaiad tx crisis invariant-broken staking supply

The chain-id of Cosmos Hub mainnet is cosmoshub-4.

Release History

use gaia v5.0.x (Delta) for queries of state between height 6,910,000 and 8,695,000
use gaia v6.0.x (Vega) between 8,695,000 and 10,085,397
use gaia v7.0.x (Theta) between 10,085,397 and 14,099,412
use gaia v8.0.x (Rho) between 14,099,412 and 14,470,501
use gaia v9.0.x (Lambda) between 14,470,501 and 15,213,800
use gaia v9.1.x between 15,213,800 and 15,816,200
use gaia v10.0.x between 15,816,200 and 16,596,000
use gaia v11.x between 16,596,000 and 16,985,500
use gaia v12.x between 16,985,500 and 17,380,000
use gaia v13.x between 17,380,000 and 18,262,000
use gaia v14.1.x between 18,262,000 and 19,639,600
use gaia v15.1.x between 19,639,600 and 19,939,000
use gaia v15.2.x between 19,939,000 and 20,440,500
use gaia v16.x from 20,440,500 and 20,739,800
use gaia v17.1.x from 20,739,800

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 For instructions to join as a validator, please also see the Validator Guide.

Overview

Release History
- Overview
Explorers
Getting Started
Hardware
General Configuration
Sync Options
Snapshots
Cosmovisor
Running via Background Process
Exporting State
Verify Mainnet

Explorers

There are many explorers for the Cosmos Hub. For reference while setting up a node, here are a few recommendations:

Mintscan

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 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.

gaiad init <custom-moniker>

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:

# A custom human readable name for this node
moniker = "<custom_moniker>"

Genesis File

Once the node is initialized, download the genesis file and move to the /config directory of the Gaia home directory.

wget https://raw.githubusercontent.com/cosmos/mainnet/master/genesis/genesis.cosmoshub-4.json.gz
gzip -d genesis.cosmoshub-4.json.gz
mv genesis.cosmoshub-4.json ~/.gaia/config/genesis.json

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

# Comma separated list of seed nodes to connect to
seeds = "<seed node id 1>@<seed node address 1>:26656,<seed node id 2>@<seed node address 2>:26656"

# Comma separated list of nodes to keep persistent connections to
persistent_peers = "<node id 1>@<node address 1>:26656,<node id 2>@<node address 2>:26656"

Node operators can optionally download the Quicksync address book. 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:

fees = ceil(gas * gasPrices)

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 minimum gas prices a validator is willing to accept for processing a
# transaction. A transaction's fees must meet the minimum of any denomination
# specified in this config (e.g. 0.25token1;0.0001token2).
minimum-gas-prices = "0.0025uatom"

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 the pruning-keep-recent, pruning-keep-every, and pruning-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

# default: the last 100 states are kept in addition to every 500th state; pruning at 10 block intervals
# nothing: all historic states will be saved, nothing will be deleted (i.e. archiving node)
# everything: all saved states will be deleted, storing only the current state; pruning at 10 block intervals
# custom: allow pruning options to be manually specified through 'pruning-keep-recent', 'pruning-keep-every', and 'pruning-interval'
pruning = "custom"

# These are applied if and only if the pruning strategy is custom.
pruning-keep-recent = "10"
pruning-keep-every = "1000"
pruning-interval = "10"

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.

###############################################################################
###                           API Configuration                             ###
###############################################################################
[api]
# Enable defines if the API server should be enabled.
enable = true
# Swagger defines if swagger documentation should automatically be registered.
swagger = false
# Address defines the API server to listen on.
address = "tcp://0.0.0.0:1317"

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.

###############################################################################
###                           gRPC Configuration                            ###
###############################################################################
[grpc]
# Enable defines if the gRPC server should be enabled.
enable = true
# Address defines the gRPC server address to bind to.
address = "0.0.0.0:9090"

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. 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.

Blocksync

Blocksync is faster than traditional consensus and syncs the chain from genesis by downloading blocks and verifying against the merkle tree of validators. For more information see CometBFT’s Blocksync Docs When syncing via Blocksync, node operators will either need to manually upgrade the chain or set up Cosmovisor to upgrade automatically. It is possible to sync from previous versions of the Cosmos Hub. See the matrix below for the correct gaia version. See the mainnet archive for historical genesis files.

Chain Id	Gaia Version
`cosmoshub-4`	`v4.2.1`
`cosmoshub-3`	`v2.0.x`
`cosmoshub-2`	`v1.0.x`
`cosmoshub-1`	`v0.0.x`

Getting Started

Start Gaia to begin syncing with the skip-invariants flag. For more information on this see Verify Mainnet.

gaiad start --x-crisis-skip-assert-invariants

The node will begin rebuilding state until it hits the first upgrade height at block 6910000. If Cosmovisor is set up then there’s nothing else to do besides wait, otherwise the node operator will need to perform the manual upgrade twice.

State Sync

State Sync is an efficient and fast way to bootstrap a new node, and it works by replaying larger chunks of application state directly rather than replaying individual blocks or consensus rounds. For more information, see CometBFT’s State Sync docs. To enable state sync, visit an explorer to get a recent block height and corresponding hash. A node operator can choose any height/hash in the current bonding period, but as the recommended snapshot period is 1000 blocks, it is advised to choose something close to current height - 1000. With the block height and hash selected, update the configuration in ~/.gaia/config/config.toml to set enable = true, and populate the trust_height and trust_hash. Node operators can configure the rpc servers to a preferred provider, but there must be at least two entries. It is important that these are two rpc servers the node operator trusts to verify component parts of the chain state. While not recommended, uniqueness is not currently enforced, so it is possible to duplicate the same server in the list and still sync successfully.

Note: In the future, the RPC server requirement will be deprecated as state sync is moved to the p2p layer in Tendermint 0.38.

#######################################################
###         State Sync Configuration Options        ###
#######################################################
[statesync]
# State sync rapidly bootstraps a new node by discovering, fetching, and restoring a state machine
# snapshot from peers instead of fetching and replaying historical blocks. Requires some peers in
# the network to take and serve state machine snapshots. State sync is not attempted if the node
# has any local state (LastBlockHeight > 0). The node will have a truncated block history,
# starting from the height of the snapshot.
enable = true

# RPC servers (comma-separated) for light client verification of the synced state machine and
# retrieval of state data for node bootstrapping. Also needs a trusted height and corresponding
# header hash obtained from a trusted source, and a period during which validators can be trusted.
#
# For Cosmos SDK-based chains, trust_period should usually be about 2/3 of the unbonding time (~2
# weeks) during which they can be financially punished (slashed) for misbehavior.
rpc_servers = "https://cosmos-rpc.polkachu.com:443,https://rpc-cosmoshub-ia.cosmosia.notional.ventures:443"
trust_height = 8959784
trust_hash = "3D8F12EA302AEDA66E80939F7FC785206692F8B6EE6F727F1655F1AFB6A873A5"
trust_period = "168h0m0s"

Start Gaia to begin state sync. It may take some time for the node to acquire a snapshot, but the command and output should look similar to the following:

$ gaiad start --x-crisis-skip-assert-invariants

...

> INF Discovered new snapshot format=1 hash="0x000..." height=8967000 module=statesync

...

> INF Fetching snapshot chunk chunk=4 format=1 height=8967000 module=statesync total=45
> INF Applied snapshot chunk to ABCI app chunk=0 format=1 height=8967000 module=statesync total=45

Once state sync successfully completes, the node will begin to process blocks normally. If state sync fails and the node operator encounters the following error: State sync failed err="state sync aborted", either try restarting gaiad or running gaiad unsafe-reset-all (make sure to backup any configuration and history before doing this).

Quicksync

Quicksync.io offers several daily snapshots of the Cosmos Hub with varying levels of pruning (archive 1.4TB, default 540GB, and pruned 265GB). For downloads and installation instructions, visit the Cosmos Quicksync guide.

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

###############################################################################
###                        State Sync Configuration                         ###
###############################################################################

# State sync snapshots allow other nodes to rapidly join the network without replaying historical
# blocks, instead downloading and applying a snapshot of the application state at a given height.
[state-sync]

# snapshot-interval specifies the block interval at which local state sync snapshots are
# taken (0 to disable). Must be a multiple of pruning-keep-every.
snapshot-interval = 1000

# snapshot-keep-recent specifies the number of recent snapshots to keep and serve (0 to keep all).
snapshot-keep-recent = 10

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.

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:

sudo tee /etc/systemd/system/<service name>.service > /dev/null <<EOF  
[Unit]
Description=Gaia Daemon
After=network-online.target

[Service]
User=$USER
ExecStart=$(which gaiad) start
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
EOF

If using Cosmovisor then make sure to add the following:

Environment="DAEMON_HOME=$HOME/.gaia"
Environment="DAEMON_NAME=gaiad"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"

After the LimitNOFILE line and replace $(which gaiad) with $(which cosmovisor). Run the following to setup the daemon:

sudo -S systemctl daemon-reload
sudo -S systemctl enable <service name>

Then start the process and confirm that it’s running.

sudo -S systemctl start <service name>

sudo service <service name> status

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:

gaiad export > [filename].json

It is also possible to export state from a particular height (at the end of processing the block of that height):

gaiad export --height [height] > [filename].json

If planning to start a new network from the exported state, export with the --for-zero-height flag:

gaiad export --height [height] --for-zero-height > [filename].json

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 without the --x-crisis-skip-assert-invariants flag:

gaiad start

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:

invariant broken:
    loose token invariance:
        pool.NotBondedTokens: 100
        sum of account tokens: 101
    CRITICAL please submit the following transaction:
        gaiad tx crisis invariant-broken staking supply

​发布历史

​概览

​浏览器

​开始之前

​硬件

​通用配置

​初始化链

​创世文件

​Seeds 与 Peers

​Gas 与费用

​状态裁剪

​REST API

​GRPC

​同步选项

​Blocksync

开始使用

​State Sync

​Quicksync

​快照

​Cosmovisor

​通过后台进程运行

​导出状态

​验证主网

​Release History

​Overview

​Explorers

​Getting Started

​Hardware

​General Configuration

​Initialize Chain

​Genesis File

​Seeds & Peers

​Gas & Fees

​Pruning of State

​REST API

​GRPC

​Sync Options

​Blocksync

Getting Started

​State Sync

​Quicksync

​Snapshots

​Cosmovisor

​Running via Background Process

​Exporting State

​Verify Mainnet

发布历史

概览

浏览器

开始之前

硬件

通用配置

初始化链

创世文件

Seeds 与 Peers

Gas 与费用

状态裁剪

REST API

GRPC

同步选项

Blocksync

State Sync

Quicksync

快照

Cosmovisor

通过后台进程运行

导出状态

验证主网

Release History

Overview

Explorers

Getting Started

Hardware

General Configuration

Initialize Chain

Genesis File

Seeds & Peers

Gas & Fees

Pruning of State

REST API

GRPC

Sync Options

Blocksync

State Sync

Quicksync

Snapshots

Cosmovisor

Running via Background Process

Exporting State

Verify Mainnet