certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #1212 from cosmos/peng/add-faucet-rm-sequence 

testnet readme usability overhaul
This commit is contained in:
Ethan Buchman 2018-06-12 21:05:04 -07:00 committed by GitHub
parent 4dcf41df4b a03770d73d
commit 8e2a317681
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 103 additions and 148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

251
cmd/gaia/testnets/README.md
View File

@ -1,228 +1,189 @@
# Connect to a Testnet
# Connect to the `gaia-6001` Testnet
This document explains how to connect to the Testnet of a [Cosmos-SDK](https://github.com/cosmos/cosmos-sdk/) based blockchain. It can be used to connect to the latest Testnet for the Cosmos Hub.
NOTE: We are aware this documentation is sub-par and are actively working to
improve both the tooling and the documentation to make this as painless as
Note: We are aware this documentation is sub-par. We are working to
improve the tooling and the documentation to make this process as painless as
possible. In the meantime, join the
[chat](https://riot.im/app/#/room/#cosmos_validators:matrix.org) for technical support. Thanks very
much for your patience :)
[Validator Chat](https://riot.im/app/#/room/#cosmos_validators:matrix.org)
for technical support. Thanks very much for your patience. :)
## Software Setup (Manual Installation)
## Setting Up a New Node
Follow these instructions to install the Cosmos-SDK and connect to the latest Testnet. This instructions work for both a local machine and a VM in a cloud server.
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](#upgrading-from-previous-testnet).
If you want to run a non-validator full-node, installing the SDK on a Cloud server is a good option. However, if you are want to become a validator for the Hub's `mainnet` you should look at more complex setups, including [Sentry Node Architecture](https://github.com/cosmos/cosmos/blob/master/VALIDATORS_FAQ.md#how-can-validators-protect-themselves-from-denial-of-service-attacks), to protect your node from DDOS and ensure high-availability (see the [technical requirements](https://github.com/cosmos/cosmos/blob/master/VALIDATORS_FAQ.md#technical-requirements)). You can find more information on validators in our [website](https://cosmos.network/validators), in the [Validator FAQ](https://cosmos.network/resources/validator-faq) and in the [Validator Chat](https://riot.im/app/#/room/#cosmos_validators:matrix.org).
### Install Go
### Install [Go](https://golang.org/)
Install `go` by following the [official docs](https://golang.org/doc/install).
**Go 1.10+** is required for the Cosmos SDK.
Install `go` following the [instructions](https://golang.org/doc/install) in the official golang website.
You will require **Go 1.10+** for this tutorial.
### Install Cosmos SDK
#### Set GOPATH
First, you will need to set up your `GOPATH`. Make sure that the location `$HOME` is something like `/Users/<username>`, you can corroborate it by typing `echo $HOME` in your terminal.
Go to `$HOME` with the command `cd $HOME` and open the the hidden file `.bashrc` with a code editor and paste the following lines \(or `.bash_profile` if your're using OS X\).
Next, let's install the testnet's version of the Cosmos SDK.
```
export GOPATH=$HOME/go
export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
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.18.0
make get_tools && make get_vendor_deps && make install
```
Save and restart the terminal.
_Note_: If you can't see the hidden file, use the shortcut `Command + Shift + .` in Finder.
### Install [GNU Wget](https://www.gnu.org/software/wget/)
**MacOS**
```
brew install wget
```
**Linux**
```
sudo apt-get install wget
```
Note: You can check other available options for downloading `wget` [here](https://www.gnu.org/software/wget/faq.html#download).
### Install Gaia
Now we can fetch the correct versions of each dependency by running:
```
mkdir -p $GOPATH/src/github.com/cosmos/cosmos-sdk
git clone https://github.com/cosmos/cosmos-sdk.git
git checkout v0.18.0
make get_tools // run $ make update_tools if already installed
make get_vendor_deps
make install
```
This will install the `gaiad` and `gaiacli` binaries. Verify that everything is OK by running:
That will install the `gaiad` and `gaiacli` binaries. Verify that everything is OK:
```
gaiad version
```
You should see:
```
0.18.0-eceb56b7
```
And also:
### Node Setup
Create the required configuration files:
```
gaiacli version
gaiad init
```
You should see:
```
0.18.0-eceb56b7
```
## Full Node Setup
Copy the testnet initialization files to a new data directory:
```
mkdir -p $HOME/.gaiad/config
cp -a cmd/gaia/testnets/gaia-6001/genesis.json $HOME/.gaiad/config/genesis.json
gaiad unsafe_reset_all
```
Add a seed node by changing `seeds = ""` in `$HOME/.gaiad/config/config.toml` to
```
seeds = "38aa9bec3998f12ae9088b21a2d910d19d565c27@gaia-6001.coinculture.net:46656,80a35a46ce09cfb31ee220c8141a25e73e0b239b@seed.cosmos.cryptium.ch:46656,80a35a46ce09cfb31ee220c8141a25e73e0b239b@35.198.166.171:46656,032fa56301de335d835057fb6ad9f7ce2242a66d@165.227.236.213:46656"
```
Lastly change the `moniker` string in the `$HOME/.gaiad/config/config.toml`to identify your node.
Name your node by editing the `moniker` in `$HOME/.gaiad/config/config.toml`. Note that only ASCII characters are supported. Using Unicode renders your node unconnectable.
```
# A custom human readable name for this node
moniker = "<your_custom_name>"
```
## Upgrading from a previous network
Your full node has been initialized! Please skip to [Genesis & Seeds](#genesis--seeds).
These instructions are for anyone that ran a previous network and would like to upgrade to a newer version.
## 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.
Remove the ephemeral files and reset the data.
```
rm $HOME/.gaiad/config/addrbook.json $HOME/.gaiad/config/genesis.json
gaiad unsafe_reset_all
```
Now your node is in a prestine state without changing your validator key. If you had any
sentry nodes or full nodes setup correctly previously they should work.
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.
**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.**\
**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:
Now it is time to upgrade the software.
```
cd $GOPATH/src/github.com/cosmos/cosmos-sdk
git fetch --all
git checkout v0.18.0
make update_tools
make get_vendor_deps
make install
git fetch --all && git checkout v0.18.0
make update_tools && make get_vendor_deps && make install
```
The next step is to copy the new genesis file:
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.
```
cp -a cmd/gaia/testnets/gaia-6001/genesis.json $HOME/.gaiad/config/genesis.json
mkdir -p $HOME/.gaiad/config
cp -a $GOPATH/src/github.com/cosmos/cosmos-sdk/cmd/gaia/testnets/gaia-6001/genesis.json $HOME/.gaiad/config/genesis.json
```
The last step is the adjust the `$HOME/.gaiad/config/config.toml`. Make sure that you are connected to healthy peers or seed nodes.
These are some seeds nodes and they can be put into the config under the `seeds` key. Alternatively you can also
ask user validators directly for a persistent peer and add it under the `persisent_peers` key.
### 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:
```
38aa9bec3998f12ae9088b21a2d910d19d565c27@gaia-6001.coinculture.net:46656,80a35a46ce09cfb31ee220c8141a25e73e0b239b@seed.cosmos.cryptium.ch:46656,80a35a46ce09cfb31ee220c8141a25e73e0b239b@35.198.166.171:46656,032fa56301de335d835057fb6ad9f7ce2242a66d@165.227.236.213:46656
# Comma separated list of seed nodes to connect to
seeds = "38aa9bec3998f12ae9088b21a2d910d19d565c27@gaia-6001.coinculture.net:46656,80a35a46ce09cfb31ee220c8141a25e73e0b239b@seed.cosmos.cryptium.ch:46656,80a35a46ce09cfb31ee220c8141a25e73e0b239b@35.198.166.171:46656,032fa56301de335d835057fb6ad9f7ce2242a66d@165.227.236.213:46656"
```
You can also [ask other validators](https://riot.im/app/#/room/#cosmos_validators:matrix.org) for a persistent peer and add it under the `persistent_peers` key. For more information on seeds and peers, [read this](https://github.com/tendermint/tendermint/blob/develop/docs/using-tendermint.md#peers).
## Run a Full Node
Start the full node:
Start the full node with this command:
```
gaiad start
```
Check the everything is running smoothly:
Check that everything is running smoothly:
```
gaiacli status
```
## Generate keys
View the status of the network with the [Cosmos Explorer](https://explorecosmos.network). Once your full node syncs up to the current block height, you should see it appear on the [list of full nodes](https://explorecosmos.network/validators). If it doesn't show up, that's ok--the Explorer does not connect to every node.
## Generate Keys
You'll need a private and public key pair \(a.k.a. `sk, pk` respectively\) to be able to receive funds, send txs, bond tx, etc.
To generate your a new key \(default _ed25519_ elliptic curve\):
To generate a new key \(default _ed25519_ elliptic curve\):
```
gaiacli keys add <your_key_name>
```
Next, you will have to enter a passphrase for your key twice. Save the _seed_ _phrase_ in a safe place in case you forget the password.
Next, you will have to create a passphrase. Save the _seed_ _phrase_ in a safe place in case you forget the password.
Now if you check your private keys you will see the `<your_key_name>` key among them:
If you check your private keys, you'll now see `<your_key_name>`:
```
gaiacli keys show <your_key_name>
```
You can see all your other available keys by typing:
You can see all your available keys by typing:
```
gaiacli keys list
```
The validator pubkey from your node should be the same as the one printed with the command:
View the validator pubkey for your node by typing:
```
gaiad tendermint show_validator
```
Finally, save your address and pubkey into a variable to use them afterwards.
Save your address and pubkey to environment variables for later use:
```
MYADDR=<your_newly_generated_address>
MYPUBKEY=<your_newly_generated_public_key>
```
**IMPORTANT:** We strongly recommend to **NOT** use the same passphrase for your different keys. The Tendermint team and the Interchain Foundation will not be responsible for the lost of funds.
**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.
### Get coins
## Get Tokens
The best way to get coins at the moment is to ask in Riot chat. We plan to have a reliable faucet in future testnets.
The best way to get tokens is from the [Cosmos Testnet Faucet](https://faucetcosmos.network). If the faucet is not working for you, try asking [#cosmos-validators](https://riot.im/app/#/room/#cosmos-validators:matrix.org).
## Send tokens
After receiving tokens to your address, you can view your account's balance by typing:
```
gaiacli send --amount=1000fermion --chain-id=<name_of_testnet_chain> --sequence=0 --name=<key_name> --to=<destination_address>
gaiacli account <your_newly_generated_address>
```
The `--amount` flag defines the corresponding amount of the coin in the format `--amount=<value|coin_name>`
Note: When you query an account balance with zero tokens, you will get this error: `No account with address <your_newly_generated_address> was found in the state.` This is expected! We're working on improving our error messages.
The `--sequence` flag corresponds to the sequence number to sign the tx.
Now check the destination account and your own account to check the updated balances \(by default the latest block\):
## Send Tokens
```
gaiacli send --amount=10faucetToken --chain-id=<name_of_testnet_chain> --name=<key_name> --to=<destination_address>
```
Note: The `--amount` flag accepts the format `--amount=<value|coin_name>`.
Now, view the updated balances of the origin and destination accounts:
```
gaiacli account <origin_address>
gaiacli account <destination_address>
gaiacli account <your_address>
```
You can also check your balance at a given block by using the `--block` flag:
@ -233,71 +194,65 @@ gaiacli account <your_address> --block=<block_height>
## Run a Validator Node
[Validators](https://cosmos.network/validators) are actors from the network that are responsible from committing new blocks to the blockchain by submitting their votes. In terms of security, validators' stake is slashed in all the zones they belong if they become unavailable, double sign a transaction, or don't cast their votes. We strongly recommend entities intending to run validators in the Cosmos Hub's `mainnet` to check the [technical requirements](https://github.com/cosmos/cosmos/blob/master/VALIDATORS_FAQ.md#technical-requirements) and take the necessary precautions to ensure high-availability, such as setting a Sentry Node architecture. If you have any question about validators, read the [Validator FAQ](https://cosmos.network/resources/validator-faq) and join the [Validator Chat](https://riot.im/app/#/room/#cosmos_validators:matrix.org).
[Validators](https://cosmos.network/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](https://github.com/cosmos/cosmos/blob/master/VALIDATORS_FAQ.md#how-can-validators-protect-themselves-from-denial-of-service-attacks) to protect your node from DDOS and ensure high-availability. Also see the [technical requirements](https://github.com/cosmos/cosmos/blob/master/VALIDATORS_FAQ.md#technical-requirements)). There's also more info on our [website](https://cosmos.network/validators).
This section covers the instructions necessary to stake tokens to become a testnet validator candidate.
Your `pubkey` can be used to create a new validator by staking tokens. You can find your validator pubkey by running:
Your `pubkey` can be used to create a new validator candidate by staking some tokens:
You can find your node pubkey by running
```
gaiad tendermint show_validator
```
and this returns your public key for the declare-candidate command
Next, craft your `gaiacli stake create-validator` command:
```
gaiacli stake create-validator --amount=500steak --pubkey=<your_node_pubkey> --address-candidate=<your_address> --moniker=satoshi --chain-id=<name_of_the_testnet_chain> --sequence=1 --name=<key_name>
gaiacli stake create-validator --amount=5steak --pubkey=<your_node_pubkey> --address-validator=<your_address> --moniker=satoshi --chain-id=<name_of_the_testnet_chain> --name=<key_name>
```
You can add more information of the validator candidate such as`--website`, `--keybase-sig `or additional `--details`. If you want to edit the candidate info:
You can add more information to the validator, such as`--website`, `--keybase-sig`, or `--details`. Here's how:
```
gaiacli stake edit-validator --details="To the cosmos !" --website="https://cosmos.network"
```
Finally, you can check all the candidate information by typing:
View the validator's information with this command:
```
gaiacli stake validator --address-candidate=<your_address> --chain-id=<name_of_the_testnet_chain>
gaiacli stake validator --address-validator=<your_address> --chain-id=<name_of_the_testnet_chain>
```
To check that the validator is active you can find it on the validator set list:
To check that the validator is active, look for it here:
```
gaiacli advanced tendermint validator-set
```
**Note:** Remember that to be in the validator set you need to have more total power than the Xnd validator, where X is the assigned size for the validator set \(by default _`X = 100`_\).
**Note:** To be in the validator set, you need to have more total voting power than the 100th validator.
## Delegate your tokens
## Delegating to a Validator
You can delegate \(_i.e._ bind\) **Atoms** to a validator to become a [delegator](https://cosmos.network/resources/delegators) and obtain a part of its fee revenue in **Photons**. For more information about the Cosmos Token Model, refer to our [whitepaper](https://github.com/cosmos/cosmos/raw/master/Cosmos_Token_Model.pdf).
On the upcoming mainnet, you can delegate `atom` to a validator. These [delegators](https://cosmos.network/resources/delegators) can receive part of the validator's fee revenue. Read more about the [Cosmos Token Model](https://github.com/cosmos/cosmos/raw/master/Cosmos_Token_Model.pdf).
### Bond your tokens
### Bond Tokens
Bond your tokens to a validator candidate with the following command:
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=<your_address> --address-candidate=<bonded_validator_address> --name=<key_name> --chain-id=<name_of_testnet_chain> --sequence=2
gaiacli stake delegate --amount=10steak --address-delegator=<your_address> --address-validator=<bonded_validator_address> --name=<key_name> --chain-id=<name_of_testnet_chain>
```
When tokens are bonded, they are pooled with all the other bonded tokens in the network. Validators and delegators obtain shares that represent their stake in this pool.
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.
### Unbond
### Unbond Tokens
If for any reason the validator misbehaves or you just want to unbond a certain amount of the bonded 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 of`shares`\(eg:`12.1`\) or all of them \(`MAX`\).
```
gaiacli stake unbond --address-delegator=<your_address> --address-candidate=<bonded_validator_address> --shares=MAX --name=<key_name> --chain-id=<name_of_testnet_chain> --sequence=3
gaiacli stake unbond --address-delegator=<your_address> --address-validator=<bonded_validator_address> --shares=MAX --name=<key_name> --chain-id=<name_of_testnet_chain>
```
You can unbond a specific amount of`shares`\(eg:`12.1`\) or all of them \(`MAX`\).
You should now see the unbonded tokens reflected in your balance and in your delegator bond:
You can check your balance and your stake delegation to see that the unbonding went through successfully.
```
gaiacli account <your_address>
gaiacli stake delegation --address-delegator=<your_address> --address-candidate=<bonded_validator_address> --chain-id=<name_of_testnet_chain>
gaiacli stake delegation --address-delegator=<your_address> --address-validator=<bonded_validator_address> --chain-id=<name_of_testnet_chain>
```