-
Notifications
You must be signed in to change notification settings - Fork 697
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
remove versions, link to testnets repo (#3342)
- Loading branch information
Showing
1 changed file
with
18 additions
and
222 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,233 +3,25 @@ title: Joining Testnet | |
| order: 3 | ||
| --- | ||
|
|
||
| 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](./join-mainnet.md) for a detailed walkthrough. | ||
| Visit the [testnets repo](https://github.com/cosmos/testnets) for the most up-to-date information on the currently available public testnets: | ||
|
|
||
| * Current Version: v17 | ||
| * Chain ID: `theta-testnet-001` | ||
|
|
||
| ## Background | ||
|
|
||
| The Cosmos Hub Public Testnet is currently running Gaia v13. Visit the [testnet explorer](https://explorer.theta-testnet.polypore.xyz/) to view all on-chain activity. | ||
|
|
||
| For those who just need instructions on performing the upgrade, see the [Upgrading Your Node](#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 | | ||
| | :---------: | :------------------: | :-----------------: | | ||
| | v16.0.0-rc0 | TBA | TBA | | ||
| | v15.0.0-rc0 | 20,269,900 | 2024-02-13 | | ||
| | v14.1.0-rc0 | 18,986,400 | 2023-11-22 | | ||
| | v14.0.0-rc1 | 18,876,500 | 2023-11-15 | | ||
| | v14.0.0-rc0 | 18,766,800 | 2023-11-08 | | ||
| | v13.0.0-rc0 | 17,996,550 | 2023-09-20 | | ||
| | v12.0.0-rc0 | 17,550,150 | 2023-08-23 | | ||
| | v11.0.0-rc0 | 17,107,825 | 2023-07-26 | | ||
| | v10.0.0-rc0 | 16,117,530 | 2023-05-24 | | ||
| | v9.0.0-rc3 | 14,476,206 | 2023-02-08 | | ||
| | v8.0.0-rc3 | 14,175,595 | 2023-01-20 | | ||
| | v7.0.0-rc0 | 9,283,650 | 2022-03-17 | | ||
| | v6.0.0 | Genesis | Launched 2022-03-10 | | ||
|
|
||
| See the [Gaia release page](https://github.com/cosmos/gaia/releases) for details on each release. | ||
| * Interchain Security (ICS) Testnet: [`provider`](https://github.com/cosmos/testnets/blob/master/interchain-security/provider/README.md) | ||
| * Release Testnet: [`theta-testnet-001`](https://github.com/cosmos/testnets/blob/master/release/README.md) | ||
|
|
||
| ## How to Join | ||
|
|
||
| We offer three ways to set up a node in the testnet: | ||
|
|
||
| * Quickstart scripts | ||
| * The [testnets](https://github.com/cosmos/testnets/tree/master/public#bash-script) repo has shell scripts to set up a node with a single command. | ||
| * Ansible playbooks | ||
| * The [cosmos-ansible](https://github.com/hyphacoop/cosmos-ansible#-quick-start) 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, 32GB of RAM, and 300GB of disk space. | ||
|
|
||
| ## Sync Options | ||
|
|
||
| There are two ways to sync a testnet node, Fastsync and State Sync. | ||
|
|
||
| * [Fast Sync](https://docs.cometbft.com/v0.37/core/block-sync) syncs the chain from genesis by downloading blocks in parallel and then verifying them. | ||
| * [State Sync](https://docs.cometbft.com/v0.37/core/state-sync) 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. | ||
| * The `/root/` part in service file paths can be changed to `/home/<username>/`. | ||
|
|
||
| ### Build Tools | ||
|
|
||
| Install build tools and Go. | ||
|
|
||
| ```shell | ||
| sudo apt-get update | ||
| sudo apt-get install -y make gcc | ||
| wget https://go.dev/dl/go1.21.6.linux-amd64.tar.gz | ||
| sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.21.6.linux-amd64.tar.gz | ||
| export PATH=$PATH:/usr/local/go/bin | ||
| ``` | ||
|
|
||
| ### Installation & Configuration | ||
|
|
||
| You will need to install and configure the Gaia binary using the script below. The Cosmos Hub Public Testnet is running Gaia [`v17.0.0-rc0`](https://github.com/cosmos/gaia/releases/tag/v17.0.0-rc0). | ||
|
|
||
| * For up-to-date endpoints like seeds and state sync RPC servers, visit the [testnets repository](https://github.com/cosmos/testnets/tree/master/public). | ||
|
|
||
| Build the gaiad binary and initialize the chain home folder. | ||
|
|
||
| ```shell | ||
| cd $HOME | ||
| git clone https://github.com/cosmos/gaia | ||
| cd gaia | ||
| # To sync from genesis, comment out the next line. | ||
| git checkout v17.0.0-rc0 | ||
| # To sync from genesis, uncomment the next line and skip the State Sync Setup section. | ||
| # git checkout v6.0.4 | ||
| make install | ||
| export PATH=$PATH:$HOME/go/bin | ||
| gaiad init <custom_moniker> | ||
| ``` | ||
|
|
||
| Prepare the genesis file. | ||
|
|
||
| ```shell | ||
| cd $HOME | ||
| wget https://github.com/cosmos/testnets/raw/master/public/genesis.json.gz | ||
| gzip -d genesis.json.gz | ||
| mv genesis.json $HOME/.gaia/config/genesis.json | ||
|
|
||
| # Set minimum gas price & peers | ||
| cd $HOME/.gaia/config | ||
| sed -i 's/minimum-gas-prices = ""/minimum-gas-prices = "0.005uatom"/' app.toml | ||
| sed -i 's/seeds = ""/seeds = "639d50339d7045436c756a042906b9a69970913f@seed-01.theta-testnet.polypore.xyz:26656,3e506472683ceb7ed75c1578d092c79785c27857@seed-02.theta-testnet.polypore.xyz:26656"/' config.toml | ||
| ``` | ||
|
|
||
| #### 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](https://explorer.theta-testnet.polypore.xyz/) to find the block and hash for the current height - 1000. | ||
| * Set these parameters in the code snippet below: `<BLOCK_HEIGHT>` and `<BLOCK_HASH>`. | ||
|
|
||
| ```shell | ||
| cd $HOME/.gaia/config | ||
| sed -i 's/enable = false/enable = true/' config.toml | ||
| sed -i 's/trust_height = 0/trust_height = <BLOCK_HEIGHT>/' config.toml | ||
| sed -i 's/trust_hash = ""/trust_hash = "<BLOCK_HASH>"/' config.toml | ||
| sed -i 's/rpc_servers = ""/rpc_servers = "http:\/\/state-sync-01.theta-testnet.polypore.xyz:26657,http:\/\/state-sync-02.theta-testnet.polypore.xyz:26657"/' config.toml | ||
| ``` | ||
|
|
||
| * 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](https://explorer.theta-testnet.polypore.xyz/blocks/12562000) and the trust hash would be `6F958861E1FA409639C8F2DA899D09B9F50A66DBBD49CE021A2FF680FA8A9204`. | ||
| You can set up a testnet node with a single command using one of the options below: | ||
|
|
||
| ### 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](https://github.com/cosmos/cosmos-sdk/tree/main/tools/cosmovisor). | ||
|
|
||
| Cosmovisor requires the creation of the following directory structure: | ||
|
|
||
| ```shell | ||
| .gaia | ||
| └── cosmovisor | ||
| └── genesis | ||
| └── bin | ||
| └── gaiad | ||
| ``` | ||
|
|
||
| Install Cosmovisor and copy Gaia binary to genesis folder: | ||
|
|
||
| ```shell | ||
| go install cosmossdk.io/tools/cosmovisor/cmd/[email protected] | ||
| mkdir -p ~/.gaia/cosmovisor/genesis/bin | ||
| cp ~/go/bin/gaiad ~/.gaia/cosmovisor/genesis/bin/ | ||
| ``` | ||
|
|
||
| ### Create Service File | ||
|
|
||
| * Cosmos Hub recommends running `gaiad` or `cosmovisor` with the `--x-crisis-skip-assert-invariants` flag. If checking for invariants, operators are likely to see `rounding error withdrawing rewards from validator`. These are expected. For more information see [Verify Mainnet](./join-mainnet.md#verify-mainnet). | ||
|
|
||
| Create one of the following service files. | ||
|
|
||
| If you are not using Cosmovisor: `/etc/systemd/system/gaiad.service` | ||
|
|
||
| ```toml | ||
| [Unit] | ||
| Description=Gaia service | ||
| After=network-online.target | ||
|
|
||
| [Service] | ||
| User=root | ||
| ExecStart=/root/go/bin/gaiad start --x-crisis-skip-assert-invariants --home /root/.gaia | ||
| Restart=no | ||
| LimitNOFILE=4096 | ||
|
|
||
| [Install] | ||
| WantedBy=multi-user.target | ||
| ``` | ||
|
|
||
| If you are using Cosmovisor: `/etc/systemd/system/cosmovisor.service` | ||
|
|
||
| ```toml | ||
| [Unit] | ||
| Description=Cosmovisor service | ||
| After=network-online.target | ||
|
|
||
| [Service] | ||
| User=root | ||
| ExecStart=/root/go/bin/cosmovisor run start --x-crisis-skip-assert-invariants --home /root/.gaia | ||
| Restart=no | ||
| LimitNOFILE=4096 | ||
| Environment='DAEMON_NAME=gaiad' | ||
| Environment='DAEMON_HOME=/root/.gaia' | ||
| Environment='DAEMON_ALLOW_DOWNLOAD_BINARIES=true' | ||
| Environment='DAEMON_RESTART_AFTER_UPGRADE=true' | ||
| Environment='DAEMON_LOG_BUFFER_SIZE=512' | ||
| Environment='UNSAFE_SKIP_BACKUP=true' | ||
|
|
||
| [Install] | ||
| WantedBy=multi-user.target | ||
| ``` | ||
|
|
||
| ### Start the Service | ||
|
|
||
| Reload the systemd manager configuration. | ||
|
|
||
| ```shell | ||
| systemctl daemon-reload | ||
| systemctl restart systemd-journald | ||
| ``` | ||
|
|
||
| If you are not using Cosmovisor: | ||
|
|
||
| ```shell | ||
| systemctl enable gaiad.service | ||
| systemctl start gaiad.service | ||
| ``` | ||
|
|
||
| If you are using Cosmovisor: | ||
|
|
||
| ```shell | ||
| systemctl enable cosmovisor.service | ||
| systemctl start cosmovisor.service | ||
| ``` | ||
|
|
||
| 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 Block 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**. | ||
| * Run a shell script from the testnets repo | ||
| * [ICS Testnet](https://github.com/cosmos/testnets/tree/master/interchain-security/provider#bash-script) | ||
| * [Release testnet](https://github.com/cosmos/testnets/blob/master/release/README.md#bash-script) | ||
| * Run an Ansible playbook from the [cosmos-ansible](https://github.com/hyphacoop/cosmos-ansible) repo | ||
| * [ICS Testnet](https://github.com/hyphacoop/cosmos-ansible/blob/main/examples/README.md#provider-chain) | ||
| * [Release Testnet](https://github.com/hyphacoop/cosmos-ansible/blob/main/examples/README.md#join-the-cosmos-hub-release-testnet) | ||
|
|
||
| ## Create a Validator (Optional) | ||
|
|
||
| If you want to create a validator in the testnet, request tokens through the [faucet Discord channel](https://discord.com/channels/669268347736686612/953697793476821092) and follow the [Running a validator](../validators/validator-setup.md) instructions provided for mainnet. | ||
| If you want to create a validator in either testnet, request tokens through the [faucet Discord channel](https://discord.com/channels/669268347736686612/953697793476821092) and follow the [this guide](https://github.com/cosmos/testnets/blob/master/interchain-security/VALIDATOR_JOINING_GUIDE.md#creating-a-validator-on-the-provider-chain). If you are creating a validator in the Release Testnet, you can disregard the instructions about joining live consumer chains. | ||
|
|
||
| ## Upgrading Your Node | ||
|
|
||
|
|
@@ -248,7 +40,11 @@ There are three ways you can update the binary: | |
|
|
||
| The instructions below are for option 2. For more information on auto-download with Cosmovisor, see the relevant [documentation](https://github.com/cosmos/cosmos-sdk/tree/main/tools/cosmovisor#auto-download) 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 `v17` upgrade, the expected folder structure would look as follows: | ||
| 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. | ||
|
|
||
| ### Cosmovisor Upgrade Example | ||
|
|
||
| Using the `v17` upgrade as an example, the expected folder structure would look as follows: | ||
|
|
||
| ```shell | ||
| .gaia | ||
|
|
@@ -277,8 +73,8 @@ git pull | |
| git checkout v17.0.0-rc0 | ||
| make install | ||
|
|
||
| # Copy the new binary to the v16 upgrade directory | ||
| # Copy the new binary to the v17 upgrade directory | ||
| cp ~/go/bin/gaiad ~/.gaia/cosmovisor/upgrades/v17/bin/gaiad | ||
| ``` | ||
|
|
||
| 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. | ||
| When the upgrade height is reached, Cosmovisor will stop the gaiad binary, update the symlink from `current` to the relevant upgrade folder, and restart. After a few minutes, the node should start syncing blocks using the new binary. | ||