* show how to edit validator description * teach about keybase sig * add dash * add more dashes * talk about logos for validators |
||
---|---|---|
.. | ||
gaia-5001 | ||
gaia-6000 | ||
gaia-6001 | ||
gaia-6002 | ||
README.md | ||
STATUS.md |
README.md
Connect to the gaia-6002
Testnet
Note: We are aware this documentation is a work in progress. We are actively working to improve the tooling and the documentation to make this process as painless as possible. In the meantime, join the Validator Chat for technical support, and open issues if you run into any! Thanks very much for your patience and support. :)
Setting Up a New Node
These instructions are for setting up a brand new full node from scratch. If you ran a full node on a previous testnet, please skip to Upgrading From Previous Testnet.
Install Go
Install go
by following the official docs.
Go 1.10+ is required for the Cosmos SDK. Remember to properly setup your $GOPATH
, $GOBIN
, and $PATH
variables, for example:
mkdir -p $HOME/go/bin
echo "export GOPATH=$HOME/go" >> ~/.bash_profile
echo "export GOBIN=$GOPATH/bin" >> ~/.bash_profile
echo "export PATH=$PATH:$GOBIN" >> ~/.bash_profile
Install Cosmos SDK
Next, let's install the testnet's version of the Cosmos SDK.
mkdir -p $GOPATH/src/github.com/cosmos
cd $GOPATH/src/github.com/cosmos
git clone https://github.com/cosmos/cosmos-sdk
cd cosmos-sdk && git checkout v0.19.0
make get_tools && make get_vendor_deps && make install
That will install the gaiad
and gaiacli
binaries. Verify that everything is OK:
$ gaiad version
0.19.0-c6711810
$ gaiacli version
0.19.0-c6711810
Node Setup
Create the required configuration files, and initialize the node:
gaiad init --name <your_custom_name>
NOTE: Note that only ASCII characters are supported for the
--name
. Using Unicode renders your node unreachable.
You can also edit this name
in the ~/.gaiad/config/config.toml
file:
# A custom human readable name for this node
moniker = "<your_custom_name>"
Your full node has been initialized! Please skip to Genesis & Seeds.
Upgrading From Previous 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 $HOME/.gaiad/config/addrbook.json $HOME/.gaiad/config/genesis.json
gaiad unsafe_reset_all
Your node is now in a pristine state while keeping the original priv_validator.json
and 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.
WARNING: 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:
cd $GOPATH/src/github.com/cosmos/cosmos-sdk
git fetch --all && git checkout v0.19.0
make update_tools && make get_vendor_deps && make install
Your full node has been cleanly upgraded!
Genesis & Seeds
Copy the Genesis File
Copy the testnet's genesis.json
file and place it in gaiad
's config directory.
mkdir -p $HOME/.gaiad/config
cp -a $GOPATH/src/github.com/cosmos/cosmos-sdk/cmd/gaia/testnets/gaia-6002/genesis.json $HOME/.gaiad/config/genesis.json
Add Seed Nodes
Your node needs to know how to find peers. You'll need to add healthy seed nodes to $HOME/.gaiad/config/config.toml
. Here are some seed nodes you can use:
# Comma separated list of seed nodes to connect to
seeds = "38aa9bec3998f12ae9088b21a2d910d19d565c27@gaia-6002.coinculture.net:46656,80a35a46ce09cfb31ee220c8141a25e73e0b239b@seed.cosmos.cryptium.ch:46656,80a35a46ce09cfb31ee220c8141a25e73e0b239b@35.198.166.171:46656,032fa56301de335d835057fb6ad9f7ce2242a66d@165.227.236.213:46656"
If those seeds aren't working, you can find more seeds and persistent peers on the Cosmos Explorer. Open the the Full Nodes
pane and select nodes that do not have private (10.x.x.x
) or local IP addresses. The Persistent Peer
field contains the connection string. For best results use 4-6.
For more information on seeds and peers, read this.
Run a Full Node
Start the full node with this command:
gaiad start
Check that everything is running smoothly:
gaiacli status
View the status of the network with the Cosmos Explorer. Once your full node syncs up to the current block height, you should see it appear on the list of full nodes. If it doesn't show up, that's ok--the Explorer does not connect to every node.
Generating Keys
A Note on Keys in Cosmos:
There are three types of key representations that are used in this tutorial:
-
cosmosaccaddr
- Derived from account keys generated by
gaiacli keys add
- Used to receive funds
- e.g.
cosmosaccaddr15h6vd5f0wqps26zjlwrc6chah08ryu4hzzdwhc
- Derived from account keys generated by
-
cosmosaccpub
- Derived from account keys generated by
gaiacli keys add
- e.g.
cosmosaccpub1zcjduc3q7fu03jnlu2xpl75s2nkt7krm6grh4cc5aqth73v0zwmea25wj2hsqhlqzm
- Derived from account keys generated by
-
cosmosvalpub
- Generated when the node is created with
gaiad init
. - Get this value with
gaiad tendermint show_validator
- e.g.
cosmosvalpub1zcjduc3qcyj09qc03elte23zwshdx92jm6ce88fgc90rtqhjx8v0608qh5ssp0w94c
- Generated when the node is created with
Key Generation
You'll need an account private and public key pair a.k.a. `sk, pk` respectively
to be able to receive funds, send txs, bond tx, etc.
To generate a new key default _ed25519_ elliptic curve
:
gaiacli keys add <account_name>
Next, you will have to create a passphrase to protect the key on disk. The output of the above command will contain a seed phrase. Save the seed phrase in a safe place in case you forget the password!
If you check your private keys, you'll now see <account_name>
:
gaiacli keys show <account_name>
You can see all your available keys by typing:
gaiacli keys list
View the validator pubkey for your node by typing:
gaiad tendermint show_validator
WARNING: We strongly recommend NOT using the same passphrase for multiple keys. The Tendermint team and the Interchain Foundation will not be responsible for the loss of funds.
Fund your account
The best way to get tokens is from the Cosmos Testnet Faucet. If the faucet is not working for you, try asking #cosmos-validators. The faucet needs the cosmosaccaddr
from the account you wish to use for staking.
After receiving tokens to your address, you can view your account's balance by typing:
gaiacli account <account_cosmosaccaddr>
Note: When you query an account balance with zero tokens, you will get this error:
No account with address <account_cosmosaccaddr> was found in the state.
This can also happen if you fund the account before your node has fully synced with the chain. These are both normal. Also, we're working on improving our error messages!
Run a Validator Node
Validators are responsible for committing new blocks to the blockchain through voting. A validator's stake is slashed if they become unavailable, double sign a transaction, or don't cast their votes. If you only want to run a full node, a VM in the cloud is fine. However, if you are want to become a validator for the Hub's mainnet
, you should research hardened setups. Please read Sentry Node Architecture to protect your node from DDOS and ensure high-availability. Also see the technical requirements). There's also more info on our website.
Create Your Validator
Your cosmosvalpub
can be used to create a new validator by staking tokens. You can find your validator pubkey by running:
gaiad tendermint show_validator
Next, craft your gaiacli stake create-validator
command:
NOTE: Don't use more
steak
thank you have! You can always get more by using the Faucet!
gaiacli stake create-validator \
--amount=5steak \
--pubkey=$(gaiad tendermint show_validator) \
--address-validator=<account_cosmosaccaddr>
--moniker="choose a moniker" \
--chain-id=gaia-6002 \
--name=<key_name>
Edit Validator Description
You can edit your validator's public description. This info is to identify your validator, and will be relied on by delegators to decide which validators to stake to. Make sure to provide input for every flag below, otherwise the field will default to empty (--moniker
defaults to the machine name).
The --keybase-sig
is a 16-digit string that is generated with a keybase.io account. It's a cryptographically secure method of verifying your identity across multiple online networks. The Keybase API allows us to retrieve your Keybase avatar. This is how you can add a logo to your validator profile.
gaiacli stake edit-validator
--address-validator=<account_cosmosaccaddr>
--moniker="choose a moniker" \
--website="https://cosmos.network" \
--keybase-sig="6A0D65E29A4CBC8E"
--details="To infinity and beyond!"
--chain-id=gaia-6002 \
--name=<key_name>
View Validator Description
View the validator's information with this command:
gaiacli stake validator \
--address-validator=<account_cosmosaccaddr> \
--chain-id=gaia-6002
Your validator is active if the following command returns anything:
gaiacli advanced tendermint validator-set | grep "$(gaiad tendermint show_validator)"
You should also be able to see your validator on the Explorer. You are looking for the bech32
encoded address
in the ~/.gaiad/config/priv_validator.json
file.
Note: To be in the validator set, you need to have more total voting power than the 100th validator. This is not normally an issue.
Problem #1: My validator has voting_power: 0
Your validator has become auto-unbonded. In gaia-6002
, we unbond validators if they do not vote on 50
of the last 100
blocks. Since blocks are proposed every ~2 seconds, a validator unresponsive for ~100 seconds will become unbonded. This usually happens when your gaiad
process crashes.
Here's how you can return the voting power back to your validator. First, if gaiad
is not running, start it up again:
gaiad start
Wait for your full node to catch up to the latest block. Next, run the following command. Note that <cosmosaccaddr>
is the address of your validator account, and <name>
is the name of the validator account. You can find this info by running gaiacli keys list
.
gaiacli stake unrevoke <cosmosaccaddr> --chain-id=gaia-6002 --name=<name>
WARNING: If you don't wait for gaiad
to sync before running unrevoke
, you will receive an error message telling you your validator is still jailed.
Lastly, check your validator again to see if your voting power is back.
gaiacli status
You may notice that your voting power is less than it used to be. That's because you got slashed for downtime!
Problem #2: My gaiad
crashes because of too many open files
The default number of files Linux can open (per-process) is 1024
. gaiad
is known to open more than 1024
files. This causes the process to crash. A quick fix is to run ulimit -n 4096
(increase the number of open files allowed) and then restart the process with gaiad start
. If you are using systemd
or another process manager to launch gaiad
this may require some configuration at that level. A sample systemd
file to fix this issue is below:
# /etc/systemd/system/gaiad.service
[Unit]
Description=Cosmos Gaia Node
After=network.target
[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu
ExecStart=/home/ubuntu/go/bin/gaiad start
Restart=on-failure
RestartSec=3
LimitNOFILE=4096
[Install]
WantedBy=multi-user.target
Delegating to a Validator
On the upcoming mainnet, you can delegate atom
to a validator. These delegators can receive part of the validator's fee revenue. Read more about the Cosmos Token Model.
Bond Tokens
On the testnet, we delegate steak
instead of atom
. Here's how you can bond tokens to a testnet validator:
gaiacli stake delegate \
--amount=10steak \
--address-delegator=<account_cosmosaccaddr> \
--address-validator=$(gaiad tendermint show_validator) \
--name=<key_name> \
--chain-id=gaia-6002
While tokens are bonded, they are pooled with all the other bonded tokens in the network. Validators and delegators obtain a percentage of shares that equal their stake in this pool.
NOTE: Don't use more
steak
thank you have! You can always get more by using the Faucet!
Unbond Tokens
If for any reason the validator misbehaves, or you want to unbond a certain amount of tokens, use this following command. You can unbond a specific amount ofshares
eg:`12.1`
or all of them `MAX`
.
gaiacli stake unbond \
--address-delegator=<account_cosmosaccaddr> \
--address-validator=$(gaiad tendermint show_validator) \
--shares=MAX \
--name=<key_name> \
--chain-id=gaia-6002
You can check your balance and your stake delegation to see that the unbonding went through successfully.
gaiacli account <account_cosmosaccaddr>
gaiacli stake delegation \
--address-delegator=<account_cosmosaccaddr> \
--address-validator=$(gaiad tendermint show_validator) \
--chain-id=gaia-6002
Other Operations
Send Tokens
gaiacli send \
--amount=10faucetToken \
--chain-id=gaia-6002 \
--name=<key_name> \
--to=<destination_cosmosaccaddr>
Note: The
--amount
flag accepts the format--amount=<value|coin_name>
.
Now, view the updated balances of the origin and destination accounts:
gaiacli account <account_cosmosaccaddr>
gaiacli account <destination_cosmosaccaddr>
You can also check your balance at a given block by using the --block
flag:
gaiacli account <account_cosmosaccaddr> --block=<block_height>