# Joining a Network
After you've tried out running a simple local Terra network, you may want to participate in an existing Terra network, such as the Columbus mainnet or Tequila testnet. This document will help you configure and set up your node for just that.
These instructions are for setting up a brand new full node from scratch.
# Initialize and configure moniker
First, initialize the node and create the necessary config files:
terrad init <your_custom_moniker>
Monikers can only contain ASCII characters; using Unicode characters will render your node unreachable by other peers in the network.
You can edit this
moniker later, in the
# A custom human readable name for this node moniker = "<your_custom_moniker>"
# Set minimum gas prices for transactions (recommended)
You can edit
~/.terrad/config/app.toml in order to enable anti-spam by rejecting incoming transactions with implied gas price less than a specified minimum. The minimum gas prices recommended for the Terra mainnet network is the following:
# 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.00506uluna,0.0015uusd,0.00102usdr,1.7805ukrw,4.31626umnt"
Your full node has now been initialized!
# Picking a Network
You specify the network you want to join by setting the genesis file and seeds. If you need more information about past networks, check our Networks Repo.
# Download the genesis file
You'll need to select the network you want to join and download its
genesis.json file into your
~/.terrad/config directory. This file specifies the genesis account balances and parameters to use when replaying transactions and syncing.
mkdir -p ~/.terrad/config curl https://columbus-genesis.s3-ap-northeast-1.amazonaws.com/columbus-4-genesis.json > ~/.terrad/config/genesis.json
Note we use the
latest directory in the networks repo which contains details for the latest testnet. If you are connecting to a different testnet, ensure you get the right files.
To verify the correctness of the configuration run:
# Download address book (recommended for the mainnet)
If you have an address book of peers, download
addrbook.json and move it into
~/.terrad/config/addrbook.json. This will give your node a selection of peers to dial to find other nodes.
curl https://network.terra.dev/addrbook.json > ~/.terrad/config/addrbook.json
# Define seed nodes
For more information on seeds and peers, you can read this.
Your node needs to know how to find peers. You'll need to add healthy seed nodes to
~/.terrad/config/config.toml. Below are some sample seeds provided by Block42, a Terra validator, taken from their excellent validator setup guide.
seeds = "email@example.com:26656,firstname.lastname@example.org:26656,email@example.com:26656,firstname.lastname@example.org:26656"
Alternatively, the following are the current seeds for Terra foundation nodes:
seeds = "email@example.com:26656,firstname.lastname@example.org:26656,email@example.com:26656,firstname.lastname@example.org:26656,email@example.com:28657,firstname.lastname@example.org:28657"
# Connecting to the Network
# Run your node
Start the full node with this command:
Check that everything is running smoothly:
# Wait for node to sync
Your node should now be catching up with the network by replaying all the transactions from genesis and recreating the blockchain state locally. This will take a long time, so make sure you've set it up on a stable connection so you can leave while it syncs.
Congratulations! You've now successfully joined a network as a full node operator.
# Using a data backup (recommended for the mainnet)
If you are connecting to an existing network for which you have a data backup (from a provider you trust), you can optionally load the backup into your node storage rather than syncing from scratch.
ChainLayer has generously provided node data backups for Columbus mainnet, which you can find in their Terra QuickSync page.
# Upgrading Testnet
These instructions are for full nodes that have ran on previous testnets and would like to upgrade to the latest testnet.
# Reset data
First, remove the outdated files and reset the data.
rm ~/.terrad/config/genesis.json rm ~/.terrad/config/addrbook.json terrad unsafe-reset-all
Your node is now in a pristine state while keeping the original
config.toml. If you had any sentry nodes or full nodes setup before, your node will still try to connect to them, but may fail if they haven't also been upgraded.
Make sure that every node has a unique
priv_validator.json. Do not copy the
priv_validator.json from an old node to multiple new nodes. Running two nodes with the same
priv_validator.json will cause you to double sign.
# Software upgrade
Now it is time to upgrade the software. Go to the project directory, and run:
git checkout master && git pull make
If you have issues at this step, please check that you have the latest stable version of GO installed.
Note we use
master here since it contains the latest stable release. See the testnet repo for details on which version is needed for which testnet, and the Terra Core release page for details on each release. Your full node has been cleanly upgraded!
# Exporting state
Terra can dump the entire application state to a JSON file, which could be useful for manual analysis and can also be used as the genesis file of a new network.
Export state with:
terrad export > [filename].json
You can also export state from a particular height (at the end of processing the block of that height):
terrad export --height [height] > [filename].json
If you plan to start a new network from the exported state, export with the
terrad export --height [height] --for-zero-height > [filename].json