[Merge After Upgrade] Cleanup in preparation of new docs

README.md

@@ -9,22 +9,13 @@
 [![GolangCI](https://golangci.com/badges/github.com/cosmos/gaia.svg)](https://golangci.com/r/github.com/cosmos/gaia)
 [![riot.im](https://img.shields.io/badge/riot.im-JOIN%20CHAT-green.svg)](https://riot.im/app/#/room/#cosmos-sdk:matrix.org)
 
-This repository hosts `Gaia`, the first implementation of the Cosmos Hub.
+This repository hosts `Gaia`, the first implementation of the Cosmos Hub based on the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk).
 
 **Note**: Requires [Go 1.13+](https://golang.org/dl/)
 
-**DISCLAIMER**: The current version of Gaia running the Cosmos Hub (v0.34.x) is
-__NOT__ maintained in this repository. Gaia and the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/)
-have been recently split. All future versions of Gaia, including the next major
-upgrade, will be maintained in this repository. However, until the next major upgrade,
-Gaia should be fetched and built from the latest [released](https://github.com/cosmos/cosmos-sdk/releases)
-__v0.34.x__ version in the SDK repository. In addition, this repository should be
-considered unstable until the next major release of Gaia. Please bear with us
-while we continue the migration process and update documentation.
-
 ## Cosmos Hub Mainnet
 
-To run a full-node for the mainnet of the Cosmos Hub, first [install `gaia`](./docs/installation.md), then follow [the guide](./docs/join-mainnet.md).
+To run a full-node for the mainnet of the Cosmos Hub, first [install `gaiad`](./docs/installation.md), then follow [the guide](./docs/join-mainnet.md).
 
 For status updates and genesis file, see the [launch repo](https://github.com/cosmos/launch).
 

docs/DOCS_README.md

@@ -24,13 +24,6 @@ The [README.md](./README.md) is also the landing page for the documentation
 on the website. During the Jenkins build, the current commit is added to the bottom
 of the README.
 
-## Config.js
-
-The [config.js](./.vuepress/config.js) generates the sidebar and Table of Contents
-on the website docs. Note the use of relative links and the omission of
-file extensions. Additional features are available to improve the look
-of the sidebar.
-
 ## Links
 
 **NOTE:** Strongly consider the existing links - both within this directory
@@ -90,22 +83,14 @@ python -m SimpleHTTPServer 8080
 
 then navigate to localhost:8080 in your browser.
 
-## Build RPC Docs
-
-First, run `make tools` from the root of repo, to install the swagger-ui tool.
-
-Then, edit the `swagger.yaml` manually; it is found [here](https://github.com/cosmos/gaia/blob/master/cmd/gaiacli/swagger-ui/swagger.yaml)
-
-Finally, run `make update-gaia-lite-docs` from the root of the repo.
-
 ## Search
 
 We are using [Algolia](https://www.algolia.com) to power full-text search. This uses a public API search-only key in the `config.js` as well as a [cosmos_network.json](https://github.com/algolia/docsearch-configs/blob/master/configs/cosmos_network.json) configuration file that we can update with PRs.
 
 ## Consistency
 
 Because the build processes are identical (as is the information contained herein), this file should be kept in sync as
-much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/develop/docs/DOCS_README.md).
+much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/master/docs/DOCS_README.md).
 
 ### Update and Build the RPC docs
 

docs/README.md

@@ -4,32 +4,31 @@ Welcome to the documentation of the **Cosmos Hub application: `gaia`**.
 
 ## What is Gaia?
 
-- [Gaia](./what-is-gaia.md)
+- [Intro to the `gaia` software](./gaia-tutorials/what-is-gaia.md)
 
 ## Join the Cosmos Hub Mainnet
 
-- [Install the `gaia` application](./installation.md)
-- [Set up a full node and join the mainnet](./join-mainnet.md)
+- [Install the `gaia` application](./gaia-tutorials/installation.md)
+- [Set up a full node and join the mainnet](./gaia-tutorials/join-mainnet.md)
 - [Upgrade to a validator node](./validators/validator-setup.md)
 
 ## Join the Cosmos Hub Public Testnet
 
-- [Join the testnet](./join-testnet.md)
+- [Join the testnet](./gaia-tutorials/join-testnet.md)
 
 ## Setup Your Own `gaia` Testnet
 
-- [Setup your own `gaia` testnet](./deploy-testnet.md)
+- [Setup your own `gaia` testnet](./gaia-tutorials/deploy-testnet.md)
 
 ## Additional Resources
 
-- [Intro to validators](./validators/overview.md)
-- [Validator FAQ](./validators/validator-faq.md)
-- [Validator security considerations](./validators/security.md)
-- [Reproducible builds](./reproducible-builds.md)
+- [Validator Resources](./validators/README.md): Contains documentation for `gaia` validators. 
+- [Delegator Resources](./delegators/README.md): Contains documentation for delegators. 
+- [Other Resources](./resources/README.md): Contains documentation on `gaiacli`, genesis file, service providers, ledger wallets, ...
 
 # Contribute
 
-See [this file](https://github.com/cosmos/gaia/blob/master/docs/DOCS_README.md) for details of the build process and
+See [this file](./DOCS_README.md) for details of the build process and
 considerations when making changes.
 
 # Version

docs/delegators/README.md

@@ -0,0 +1,13 @@
+---
+order: false
+parent:
+  order: 2
+---
+
+# Delegators 
+
+This folder contains documentation relevant to delegators of the Cosmos Hub and other `gaia` blockchains. 
+
+- [Delegator CLI Guide](./delegator-guide-cli.md)
+- [Delegators FAQ](./delegator-faq.md)
+- [Delegator Security Notice](./delegator-security.md)

docs/delegators/delegator-faq.md

@@ -0,0 +1,71 @@
+---
+order: 2
+---
+
+# Delegator FAQ
+
+## What is a delegator?
+
+People that cannot or do not want to operate [validator nodes](..//validators/overview.md) can still participate in the staking process as delegators. Indeed, validators are not chosen based on their self-delegated stake but based on their total stake, which is the sum of their self-delegated stake and of the stake that is delegated to them. This is an important property, as it makes delegators a safeguard against validators that exhibit bad behavior. If a validator misbehaves, their delegators will move their Atoms away from them, thereby reducing their stake. Eventually, if a validator's stake falls under the top 100 addresses with highest stake, they will exit the validator set.
+
+**Delegators share the revenue of their validators, but they also share the risks.** In terms of revenue, validators and delegators differ in that validators can apply a commission on the revenue that goes to their delegator before it is distributed. This commission is known to delegators beforehand and can only change according to predefined constraints (see [section](#choosing-a-validator) below). In terms of risk, delegators' Atoms can be slashed if their validator misbehaves. For more, see [Risks](#risks) section.
+
+To become delegators, Atom holders need to send a ["Delegate transaction"](./delegator-guide-cli.md#sending-transactions) where they specify how many Atoms they want to bond and to which validator. A list of validator candidates will be displayed in Cosmos Hub explorers. Later, if a delegator wants to unbond part or all of their stake, they needs to send an "Unbond transaction". From there, the delegator will have to wait 3 weeks to retrieve their Atoms. Delegators can also send a "Rebond Transaction" to switch from one validator to another, without having to go through the 3 weeks waiting period. 
+
+For a practical guide on how to become a delegator, click [here](./delegator-guide-cli.md).
+
+## Choosing a validator
+
+In order to choose their validators, delegators have access to a range of information directly in [Lunie](https://lunie.io) or other Cosmos block explorers.
+
+- **Validator's moniker**: Name of the validator candidate.
+- **Validator's description**: Description provided by the validator operator.
+- **Validator's website**: Link to the validator's website.
+- **Initial commission rate**: The commission rate on revenue charged to any delegator by the validator (see below for more detail).
+- **Commission max change rate:** The maximum daily increase of the validator's commission. This parameter cannot be changed by the validator operator. 
+- **Maximum commission:** The maximum commission rate this validator candidate can charge. This parameter cannot be changed by the validator operator. 
+- **Minimum self-bond amount**: Minimum amount of Atoms the validator candidate need to have bonded at all time. If the validator's self-bonded stake falls below this limit, their entire staking pool (i.e. all its delegators) will unbond. This parameter exists as a safeguard for delegators. Indeed, when a validator misbehaves, part of their total stake gets slashed. This included the validator's self-delegateds stake as well as their delegators' stake. Thus, a validator with a high amount of self-delegated Atoms has more skin-in-the-game than a validator with a low amount. The minimum self-bond amount parameter guarantees to delegators that a validator will never fall below a certain amount of self-bonded stake, thereby ensuring a minimum level of skin-in-the-game. This parameter can only be increased by the validator operator. 
+
+## Directives of delegators
+
+Being a delegator is not a passive task. Here are the main directives of a delegator:
+
+- **Perform careful due diligence on validators before delegating.** If a validator misbehaves, part of their total stake, which includes the stake of their delegators, can be slashed. Delegators should therefore carefully select validators they think will behave correctly.
+- **Actively monitor their validator after having delegated.** Delegators should ensure that the validators they delegate to behave correctly, meaning that they have good uptime, do not double sign or get compromised, and participate in governance. They should also monitor the commission rate that is applied. If a delegator is not satisfied with its validator, they can unbond or switch to another validator (Note: Delegators do not have to wait for the unbonding period to switch validators. Rebonding takes effect immediately).
+- **Participate in governance.** Delegators can and are expected to actively participate in governance. A delegator's voting power is proportional to the size of their bonded stake. If a delegator does not vote, they will inherit the vote of their validator(s). If they do vote, they override the vote of their validator(s). Delegators therefore act as a counterbalance to their validators.
+
+## Revenue
+
+Validators and delegators earn revenue in exchange for their services. This revenue is given in three forms:
+
+- **Block provisions (Atoms):** They are paid in newly created Atoms. Block provisions exist to incentivize Atom holders to stake. The yearly inflation rate is calculated to target 2/3 bonded stake. If the total bonded stake in the network is less than 2/3 of the total Atom supply, inflation increases until it reaches 20%. If the total bonded stake is more than 2/3 of the Atom supply, inflation decreases until it reaches 7%. This means that if total bonded stake stays less than 2/3 of the total Atom supply for a prolonged period of time, unbonded Atom holders can expect their Atom value to deflate by 20% (compounded) per year.
+- **Transaction fees (various tokens):** Each transfer on the Cosmos Hub comes with transactions fees. These fees can be paid in any currency that is whitelisted by the Hub's governance. Fees are distributed to bonded Atom holders in proportion to their stake. The first whitelisted token at launch is the ATOM.
+
+## Validator Commission
+
+Each validator receives revenue based on their total stake. Before this revenue is distributed to delegators, the validator can apply a commission. In other words, delegators have to pay a commission to their validators on the revenue they earn. Let us look at a concrete example:
+
+We consider a validator whose stake (i.e. self-delegated stake + delegated stake) is 10% of the total stake of all validators. This validator has 20% self-delegated stake and applies a commission of 10%. Now let us consider a block with the following revenue:
+
+- 990 Atoms in block provisions
+- 10 Atoms in transaction fees.
+
+This amounts to a total of 1000 Atoms and 100 Photons to be distributed among all staking pools.
+
+Our validator's staking pool represents 10% of the total stake, which means the pool obtains 100 Atoms and 10 Photons. Now let us look at the internal distribution of revenue:
+
+- Commission = `10% * 80% * 100` Atoms = 8 Atoms 
+- Validator's revenue = `20% * 100` Atoms + Commission = 28 Atoms
+- Delegators' total revenue = `80% * 100` Atoms - Commission = 72 Atoms
+
+Then, each delegator in the staking pool can claim their portion of the delegators' total revenue.
+
+## Risks
+
+Staking Atoms is not free of risk. First, staked Atoms are locked up, and retrieving them requires a 3 week waiting period called unbonding period. Additionally, if a validator misbehaves, a portion of their total stake can be slashed (i.e. destroyed). This includes the stake of their delegators.
+
+There is one main slashing condition:
+
+- **Double signing:** If someone reports on that a validator signed two different blocks with the same chain ID at the same height, this validator will get slashed. 
+
+This is why Atom holders should perform careful due diligence on validators before delegating. It is also important that delegators actively monitor the activity of their validators. If a validator behaves suspiciously or is too often offline, delegators can choose to unbond from them or switch to another validator. **Delegators can also mitigate risk by distributing their stake across multiple validators.**s

docs/delegator-guide-cli.md → docs/delegators/delegator-guide-cli.md

@@ -1,3 +1,7 @@
+---
+order: 1
+---
+
 # Delegator Guide (CLI)
 
 This document contains all the necessary information for delegators to interact with the Cosmos Hub through the Command-Line Interface (CLI).