LaconicNetwork/cosmos-sdk
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

update docs for mainnet

Browse Source
This commit is contained in:
gamarin 2019-03-08 22:24:50 +01:00
parent 506712341d
commit 7ec3d3d6fc
9 changed files with 212 additions and 207 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -20,12 +20,12 @@ breaking changes.
**Note**: Requires [Go 1.11.5+](https://golang.org/dl/)
## Cosmos Hub Public Testnet
## Cosmos Hub Mainnet
To run a full-node in the latest public testnet of the Hub, first [install `gaia`](./docs/gaia/installation.md), then follow [the guide](./docs/gaia/join-testnet.md).
To run a full-node for the mainnet of the Cosmos Hub, first [install `gaia`](./docs/gaia/installation.md), then follow [the guide](./docs/gaia/join-mainnet.md).
For status updates and genesis files, see the
[testnets repo](https://github.com/cosmos/testnets).
For status updates and genesis file, see the
[launch repo](https://github.com/cosmos/launch).
## Quick Start

11
docs/.vuepress/config.js
View File

@ -26,7 +26,7 @@ module.exports = {
sidebar: [
{
title: "Overview",
collapsable: false,
collapsable: true,
children: [
"/intro/",
"/intro/sdk-app-architecture",
@ -35,11 +35,11 @@ module.exports = {
},
{
title: "Gaia",
collapsable: false,
collapsable: true,
children: [
"/gaia/what-is-gaia",
"/gaia/installation",
"/gaia/join-testnet",
"/gaia/join-mainnet",
"/gaia/validators/validator-setup",
"/gaia/validators/overview",
"/gaia/validators/security",
@ -47,12 +47,13 @@ module.exports = {
"/gaia/delegator-guide-cli",
"/gaia/ledger",
"/gaia/gaiacli",
"/gaia/join-testnet",
"/gaia/deploy-testnet"
]
},
{
title: "Tutorial",
collapsable: false,
collapsable: true,
children: [
"/tutorial/",
"/tutorial/app-design",
@ -74,7 +75,7 @@ module.exports = {
},
{
title: "Clients",
collapsable: false,
collapsable: true,
children: [
"/clients/",
"/clients/cli",

5
docs/README.md
View File

@ -11,9 +11,10 @@
- [SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk): Godocs of the Cosmos SDK.
- [REST API spec](https://cosmos.network/rpc/): List of endpoints to interact with a `gaia` full-node through REST.
## Cosmos Hub testnet
## Cosmos Hub
- [Join the public testnet](./gaia/join-testnet.md) of the Cosmos Hub.
- [Join the mainnet](./gaia/join-mainnet.md) of the Cosmos Hub.
- [Join the latest public testnet](./gaia/join-testnet.md) of the Cosmos Hub.
- [Start your own `gaia` testnet](./gaia/deploy-testnet.md).
## Creating a new SDK project

8
docs/gaia/README.md
View File

@ -2,12 +2,16 @@
Welcome to the `Gaia` docs. `Gaia` is the current name of the Cosmos SDK application for the Cosmos Hub.
## Join the Cosmos Hub public testnet
## Join the Cosmos Hub Mainnet
- [Install the `gaia` application](./installation.md)
- [Set up a full node and join the current public testnet](./join-testnet.md)
- [Set up a full node and join the mainnet](./join-mainnet.md)
- [Upgrade to a validator node](./validators/validator-setup.md)
## Join the Cosmos Hub Public Testnet
- [Join the testnet](./join-testnet.md)
## Setup your own `gaia` testnet
- [Setup your own `gaia` testnet](./deploy-testnet.md)

16
docs/gaia/installation.md
View File

@ -1,6 +1,6 @@
## Install Gaia
This guide will explain how to install the `gaiad` and `gaiacli` entrypoints onto your system. With these installed on a server, you can participate in the latest testnet as either a [Full Node](./join-testnet.md#run-a-full-node) or a [Validator](./validators/validator-setup.md).
This guide will explain how to install the `gaiad` and `gaiacli` entrypoints onto your system. With these installed on a server, you can participate in the latest testnet as either a [Full Node](./join-mainnet.md) or a [Validator](./validators/validator-setup.md).
### Install Go
@ -23,6 +23,10 @@ Next, let's install the latest version of Gaia. Here we'll use the `master` bran
If necessary, make sure you `git checkout` the correct
[released version](https://github.com/cosmos/cosmos-sdk/releases).
::: warning
For the mainnet, make sure your version if greather than `v0.33.0`
:::
```bash
mkdir -p $GOPATH/src/github.com/cosmos
cd $GOPATH/src/github.com/cosmos
@ -43,11 +47,11 @@ $ gaiacli version --long
`gaiacli` for instance should output something similar to:
```
cosmos-sdk: 0.31.2-10-g1fba7308
git commit: 1fba7308fa226e971964cd6baad9527d4b51d9fc
vendor hash: 1aec7edfad9888a967b3e9063e42f66b28f447e6
cosmos-sdk: 0.33.0
git commit: 7b4104aced52aa5b59a96c28b5ebeea7877fc4f0
vendor hash:
build tags: netgo ledger
go version go1.11.5 linux/amd64
go version go1.12 darwin/amd64
```
##### Build Tags
@ -66,4 +70,4 @@ Build tags indicate special features that have been enabled in the binary.
### Next
Now you can [join the public testnet](./join-testnet.md) or [create you own testnet](./deploy-testnet.md)
Now you can [join the mainnet](./join-mainnet.md), [the public testnet](./join-testnet.md) or [create you own testnet](./deploy-testnet.md)

124
docs/gaia/join-mainnet.md Normal file
View File

@ -0,0 +1,124 @@
# Join the mainnet
::: tip
See the [launch](https://github.com/cosmos/launch) for
information on the mainnet, including the correct version
of the Cosmos-SDK to use and details about the genesis file.
:::
::: warning
**You need to [install gaia](./installation.md) before you go further**
:::
## Setting Up a New Node
These instructions are for setting up a brand new full node from scratch.
First, initialize the node and create the necessary config files:
```bash
gaiad init <your_custom_moniker>
```
::: warning Note
Monikers can contain only ASCII characters. Using Unicode characters will render your node unreachable.
:::
You can edit this `moniker` later, in the `~/.gaiad/config/config.toml` file:
```toml
# A custom human readable name for this node
moniker = "<your_custom_moniker>"
```
You can edit the `~/.gaiad/config/gaiad.toml` file in order to enable the anti spam mechanism and reject incoming transactions with less than the minimum gas prices:
```
# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml
##### main base config options #####
# 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. 10uatom).
minimum-gas-prices = ""
```
Your full node has been initialized!
## Genesis & Seeds
### Copy the Genesis File
Fetch the testnet's `genesis.json` file into `gaiad`'s config directory.
```bash
mkdir -p $HOME/.gaiad/config
curl https://raw.githubusercontent.com/cosmos/launch/master/latest/genesis.json > $HOME/.gaiad/config/genesis.json
```
Note we use the `latest` directory in the [launch repo](https://github.com/cosmos/launch) which contains details for the mainnet like the latest version and the genesis file.
::: tip
If you want to connect to the public testnet instead, click [here](./join-testnet.md)
:::
To verify the correctness of the configuration run:
```bash
gaiad start
```
### 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`. The [`launch`](https://github.com/cosmos/launch) repo contains links to some seed nodes.
If those seeds aren't working, you can find more seeds and persistent peers on a Cosmos Hub explorer (a list can be found on the [launch page](https://cosmos.network/launch)).
You can also ask for peers on the [Validators Riot Room](https://riot.im/app/#/room/#cosmos-validators:matrix.org)
For more information on seeds and peers, you can [read this](https://github.com/tendermint/tendermint/blob/develop/docs/tendermint-core/using-tendermint.md#peers).
## Run a Full Node
Start the full node with this command:
```bash
gaiad start
```
Check that everything is running smoothly:
```bash
gaiacli status
```
View the status of the network with the [Cosmos Explorer](https://cosmos.network/launch).
## Export State
Gaia 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:
```bash
gaiad export > [filename].json
```
You can also export state from a particular height (at the end of processing the block of that height):
```bash
gaiad export --height [height] > [filename].json
```
If you plan to start a new network from the exported state, export with the `--for-zero-height` flag:
```bash
gaiad export --height [height] --for-zero-height > [filename].json
```
## Upgrade to Validator Node
You now have an active full node. What's the next step? You can upgrade your full node to become a Cosmos Validator. The top 100 validators have the ability to propose new blocks to the Cosmos Hub. Continue onto [the Validator Setup](./validators/validator-setup.md).

122
docs/gaia/join-testnet.md
View File

@ -1,4 +1,4 @@
# Join the public testnet
# Join the Public Testnet
::: tip Current Testnet
See the [testnet repo](https://github.com/cosmos/testnets) for
@ -10,47 +10,20 @@ of the Cosmos-SDK to use and details about the genesis file.
**You need to [install gaia](./installation.md) before you go further**
:::
## Setting Up a New Node
## Starting a new Node
> NOTE: If you ran a full node on a previous testnet, please skip to [Upgrading From Previous Testnet](#upgrading-from-previous-testnet).
These instructions are for setting up a brand new full node from scratch.
To start a new node, the mainnet instructions apply:
First, initialize the node and create the necessary config files:
- [Join the mainnet](./join-mainnet.md)
- [Deploy a validator](./validators/validator-setup.md)
```bash
gaiad init <your_custom_moniker>
```
The only difference is the SDK version and genesis file. See the [testnet repo](https://github.com/cosmos/testnets) for information on testnets, including the correct version of the Cosmos-SDK to use and details about the genesis file.
::: warning Note
Monikers can contain only ASCII characters. Using Unicode characters will render your node unreachable.
:::
## Upgrading your Node
You can edit this `moniker` later, in the `~/.gaiad/config/config.toml` file:
```toml
# A custom human readable name for this node
moniker = "<your_custom_moniker>"
```
You can edit the `~/.gaiad/config/gaiad.toml` file in order to enable the anti spam mechanism and reject incoming transactions with less than a minimum fee:
```
# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml
##### main base config options #####
# Validators reject any tx from the mempool with less than the minimum fee per gas.
minimum_fees = ""
```
Your full node has been initialized! Please skip to [Genesis & Seeds](#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.
These instructions are for full nodes that have ran on previous versions of and would like to upgrade to the latest testnet.
### Reset Data
@ -84,81 +57,6 @@ make update_tools install
:::
Note we use `master` here since it contains the latest stable release.
See the [testnet repo](https://github.com/cosmos/testnets)
for details on which version is needed for which testnet,
and the [SDK release page](https://github.com/cosmos/cosmos-sdk/releases)
for details on each release.
See the [testnet repo](https://github.com/cosmos/testnets) for details on which version is needed for which testnet, and the [SDK release page](https://github.com/cosmos/cosmos-sdk/releases) for details on each release.
Your full node has been cleanly upgraded!
## Genesis & Seeds
### Copy the Genesis File
Fetch the testnet's `genesis.json` file into `gaiad`'s config directory.
```bash
mkdir -p $HOME/.gaiad/config
curl https://raw.githubusercontent.com/cosmos/testnets/master/latest/genesis.json > $HOME/.gaiad/config/genesis.json
```
Note we use the `latest` directory in the [testnets repo](https://github.com/cosmos/testnets)
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:
```bash
gaiad start
```
### 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`. The `testnets` repo contains links to the seed nodes for each testnet. If you are looking to join the running testnet please [check the repository for details](https://github.com/cosmos/testnets) on which nodes to use.
If those seeds aren't working, you can find more seeds and persistent peers on the [Cosmos Explorer](https://explorer.cosmos.network/nodes). Open the the `Full Nodes` pane and select nodes that do not have private (`10.x.x.x`) or [local IP addresses](https://en.wikipedia.org/wiki/Private_network). The `Persistent Peer` field contains the connection string. For best results use 4-6.
You can also ask for peers on the [Validators Riot Room](https://riot.im/app/#/room/#cosmos-validators:matrix.org)
For more information on seeds and peers, you can [read this](https://github.com/tendermint/tendermint/blob/develop/docs/tendermint-core/using-tendermint.md#peers).
## Run a Full Node
Start the full node with this command:
```bash
gaiad start
```
Check that everything is running smoothly:
```bash
gaiacli status
```
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.
## Export State
Gaia 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:
```bash
gaiad export > [filename].json
```
You can also export state from a particular height (at the end of processing the block of that height):
```bash
gaiad export --height [height] > [filename].json
```
If you plan to start a new network from the exported state, export with the `--for-zero-height` flag:
```bash
gaiad export --height [height] --for-zero-height > [filename].json
```
## Upgrade to Validator Node
You now have an active full node. What's the next step? You can upgrade your full node to become a Cosmos Validator. The top 100 validators have the ability to propose new blocks to the Cosmos Hub. Continue onto [the Validator Setup](./validators/validator-setup.md).
Your full node has been cleanly upgraded!

5
docs/gaia/validators/validator-faq.md
View File

@ -218,9 +218,10 @@ We have to solve this simple equation to find the reward R for each validator:
### What are the slashing conditions?
If a validator misbehaves, their delegated stake will be partially slashed. There is currently one main fault that can result in slashing of funds for a validator and their delegators:
If a validator misbehaves, their delegated stake will be partially slashed. There are currently two faults that can result in slashing of funds for a validator and their delegators:
* **Double signing:** If someone reports on chain A that a validator signed two blocks at the same height on chain A and chain B, and if chain A and chain B share a common ancestor, then this validator will get slashed on chain A
* **Double signing:** If someone reports on chain A that a validator signed two blocks at the same height on chain A and chain B, and if chain A and chain B share a common ancestor, then this validator will get slashed by 5% on chain A.
* **Downtime:** If a validator misses more than 95% of the last 10.000 blocks, they will get slashed by 0.01%.
### Do validators need to self-delegate Atoms?

120
docs/gaia/validators/validator-setup.md
View File

@ -1,12 +1,10 @@
# Run a Validator on the public testnet
# Run a Validator on the Cosmos Hub Mainnet
::: tip
Information on how to join the current testnet (`genesis.json` file and seeds) is held [in our `testnet` repo](https://github.com/cosmos/testnets/tree/master/latest). Please check there if you are looking to join our latest testnet.
Information on how to join the mainnet (`genesis.json` file and seeds) is held [in our `launch` repo](https://github.com/cosmos/launch/tree/master/latest).
:::
__Note__: This documentation is only intended for validators of the **public testnet**
Before setting up your validator node, make sure you've already gone through the [Full Node Setup](../join-testnet.md) guide.
Before setting up your validator node, make sure you've already gone through the [Full Node Setup](../join-mainnet.md) guide.
## What is a Validator?
@ -16,7 +14,7 @@ Before setting up your validator node, make sure you've already gone through the
If you want to become a validator for the Hub's `mainnet`, you should [research security](./security.md).
:::
You may want to skip the next section if you have already [set up a full-node](../join-testnet.md).
You may want to skip the next section if you have already [set up a full-node](../join-mainnet.md).
## Create Your Validator
@ -26,10 +24,10 @@ Your `cosmosvalconspub` can be used to create a new validator by staking tokens.
gaiad tendermint show-validator
```
Next, craft your `gaiad gentx` command:
To create your validator, just use the following command:
::: warning Note
Don't use more `STAKE` thank you have! You can always get more by using the [Faucet](https://faucet.cosmos.network/)!
::: warning
Don't use more `uatom` thank you have!
:::
```bash
@ -38,86 +36,68 @@ gaiacli tx staking create-validator \
--pubkey=$(gaiad tendermint show-validator) \
--moniker="choose a moniker" \
--chain-id=<chain_id> \
--from=<key_name> \
--commission-rate="0.10" \
--commission-max-rate="0.20" \
--commission-max-change-rate="0.01"
--commission-max-change-rate="0.01" \
--from=<key_name>
```
__Note__: When specifying commission parameters, the `commission-max-change-rate`
is used to measure % _point_ change over the `commission-rate`. E.g. 1% to 2% is
a 100% rate increase, but only 1 percentage point.
::: tip
When specifying commission parameters, the `commission-max-change-rate` is used to measure % _point_ change over the `commission-rate`. E.g. 1% to 2% is a 100% rate increase, but only 1 percentage point.
:::
__Note__: If unspecified, `consensus_pubkey` will default to the output of `gaiad tendermint show-validator`.
`key_name` is the name of the private key that will be used to sign the transaction.
You can confirm that you are in the validator set by using a third party explorer.
## Participate in genesis as a validator
__Note__: This section only concerns validators that want to be in the genesis
file. If the chain you want to validate is already live, skip this section.
__Note__: `Gaia-9002` and `Game of stakes` will not use this process. They will
be bootstrapped using validators operated by Tendermint. You will just need to use the
[create-validator](#create-your-validator) command in order to join as a validator
for these networks.
If you want to participate in genesis as a validator, you need to justify that
you have some stake at genesis, create one (or multiple) transactions to bond this
stake to your validator address, and include this transaction in the genesis file.
You will need create a `gentx`:
```bash
gaiad gentx \
--amount <amount_of_delegation> \
--commission-rate <commission_rate> \
--commission-max-rate <commission_max_rate> \
--commission-max-change-rate <commission_max_change_rate> \
--pubkey <consensus_pubkey> \
--name <key_name>
```
__Note__: This command automatically store your `gentx` in `~/.gaiad/config/gentx`
for it to be processed at genesis.
::: tip
Consult `gaiad gentx --help` for more information on the flags defaults.
::: warning
This section only concerns validators that want to be in the genesis
file of the Cosmos Hub mainnet. If the mainnet is already live, skip this section.
:::
A `gentx` is a JSON file carrying a self-delegation. All genesis transactions are
collected by a `genesis coordinator` and validated against an initial `genesis.json`.
Such initial `genesis.json` contains only a list of accounts and their coins.
Once the transactions are processed, they are merged in the `genesis.json`'s `gentxs` field.
If you want to participate in genesis as a validator, you need to justify that
you have some stake at genesis, create one (or multiple) transactions to bond this stake to your validator address, and include this transaction in the genesis file.
### Copy the Initial Genesis File and Process Genesis Transactions
Fetch the `genesis.json` file into `gaiad`'s config directory.
Your `cosmosvalconspub` can be used to create a new validator by staking tokens. You can find your validator pubkey by running:
```bash
mkdir -p $HOME/.gaiad/config
curl https://raw.githubusercontent.com/cosmos/testnets/master/latest/genesis.json > $HOME/.gaiad/config/genesis.json
gaiad tendermint show-validator
```
__Note:__ We use the `latest` directory in the [testnets repo](https://github.com/cosmos/testnets)
which contains details for the latest testnet. If you are connecting to a different testnet, ensure you get the right files.
Next, craft your `gaiad gentx` command.
::: tip
A `gentx` is a JSON file carrying a self-delegation. All genesis transactions are collected by a `genesis coordinator` and validated against an initial `genesis.json`.
:::
You also need to fetch the genesis transactions of all the other genesis validators. For now there is no repository where genesis transactions can be submitted by validators, but this will as soon as we try out this feature in a testnet.
Once you've collected all genesis transactions in `~/.gaiad/config/gentx`, you can run:
::: warning Note
Don't use more `uatom` thank you have!
:::
```bash
gaiad collect-gentxs
gaiacli tx staking create-validator \
--amount=50000000uatom \
--pubkey=$(gaiad tendermint show-validator) \
--moniker="choose a moniker" \
--chain-id=<chain_id> \
--commission-rate="0.10" \
--commission-max-rate="0.20" \
--commission-max-change-rate="0.01" \
--generate-only > myUnsignedGentx.json
```
__Note:__ The accounts from which you delegate in the `gentx` transactions need to possess stake tokens in the genesis file, otherwise `collect-gentx` will fail.
::: tip
When specifying commission parameters, the `commission-max-change-rate` is used to measure % _point_ change over the `commission-rate`. E.g. 1% to 2% is a 100% rate increase, but only 1 percentage point.
:::
The previous command will collect all genesis transactions and finalise `genesis.json`. To verify the correctness of the configuration and start the node run:
After you generate your unsigned `gentx`, sign it.
```bash
gaiad start
gaiacli tx sign myUnsignedGentx.json --from <key_name> > myGentx.json
```
You can then submit your `gentx` on the [launch repository](https://github.com/cosmos/launch). These `gentx` will be used to form the final genesis file.
## 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).
@ -187,23 +167,15 @@ To be in the validator set, you need to have more total voting power than the 10
### Problem #1: My validator has `voting_power: 0`
Your validator has become auto-unbonded. In `gaia-8000`, 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.
Your validator has become jailed. Validators get jailed, i.e. get removed from the active validator set, if they do not vote on `500` of the last `10000` blocks, or if they double sign.
Here's how you can return the voting power back to your validator. First, if `gaiad` is not running, start it up again:
If you got jailed for downtime, you can get your voting power back to your validator. First, if `gaiad` is not running, start it up again:
```bash
gaiad start
```
Wait for your full node to catch up to the latest block. Next, run the following command. Note that `<cosmos>` 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`.
```bash
gaiacli tx slashing unjail <cosmos> --chain-id=<chain_id> --from=<from>
```
::: danger Warning
If you don't wait for `gaiad` to sync before running `unjail`, you will receive an error message telling you your validator is still jailed.
:::
Wait for your full node to catch up to the latest block. Next, run the following command. Then, you can [unjail your validator](#unjail-validator)
Lastly, check your validator again to see if your voting power is back.