docs: testnet (#458)

* testnet docs

* more changes

* testnet and validators

docs/.vuepress/config.js

@@ -94,6 +94,16 @@ module.exports = {
               directory: true,
               path: '/guides/tools'
             },
+            {
+              title: 'Validators',
+              directory: true,
+              path: '/guides/validators'
+            },
+            {
+              title: 'Key Management System',
+              directory: true,
+              path: '/guides/kms'
+            },
           ]
         },
         {
@@ -115,9 +125,14 @@ module.exports = {
           title: 'Testnet',
           children: [
             {
-              title: 'Guides',
-              directory: true,
-              path: '/testnet'
+              title: 'Join Testnet',
+              directory: false,
+              path: '/testnet/join'
+            },
+            {
+              title: 'Deploy Node on Cloud',
+              directory: false,
+              path: '/testnet/cloud_providers'
             },
           ]
         },

docs/DOCS_README.md

@@ -104,7 +104,7 @@ We are using [Algolia](https://www.algolia.com) to power full-text search. This
    1. Directly Edit API docs manually: `client/lcd/swagger-ui/swagger.yaml`.
    2. Edit API docs within the [Swagger Editor](https://editor.swagger.io/). Please refer to this [document](https://swagger.io/docs/specification/2-0/basic-structure/) for the correct structure in `.yaml`.
 3. Download `swagger.yaml` and replace the old `swagger.yaml` under fold `client/lcd/swagger-ui`.
-4. Compile gaiacli
+4. Compile ethermintd
 
    ```bash
    make install

docs/basics/tokens.md

@@ -34,7 +34,3 @@ This matches Ethereum denomination of:
 
 Ethermint is compatible with ERC20 tokens and other non-fungible token standards (EIP721, EIP1155)
 that are natively supported by the EVM.
-
-## Next {hide}
-
-Learn about the supported [JSON-RPC](./json_rpc.md) methods on Ethermint {hide}

docs/basics/transactions.md

@@ -2,11 +2,18 @@
 order: 3
 -->
 
-# Transactions
+# Transaction Lifecycle
 
+This document describes the lifecycle of a transaction from creation to committed state changes on the EVM. {synopsis}
+
+### Pre-requisite Readings
+
+- [SDK transaction lifecycle](https://docs.cosmos.network/master/basics/tx-lifecycle.html) {prereq}
+
+<!-- TODO: rewrite. This is not a lifecycle doc -->
 ## Routing
 
-Ethermint needs to parse and handle transactions routed for both the EVM and for the Cosmos hub. We
+Ethermint needs to parse and handle transactions routed for both the EVM and for Cosmos SDK modules. We
 attempt to achieve this by mimicking [geth's](https://github.com/ethereum/go-ethereum) `Transaction`
 structure and treat it as a unique Cosmos SDK message type. An Ethereum transaction is a single
 [`sdk.Msg`](https://godoc.org/github.com/cosmos/cosmos-sdk/types#Msg). All relevant Ethereum
@@ -31,7 +38,3 @@ protocol supports different signer types based on the chain configuration params
 Ethermint supports all Ethereum `Signer`s up to the latest go-ethereum version (London, Berlin,
 EIP155, Homestead and Frontier). The chain will generate the latest `Signer` type depending on the
 `ChainConfig`.
-
-## Next {hide}
-
-Learn about how [gas](./gas.md) is used on Ethermint {hide}

docs/guides/kms/kms.md

@@ -0,0 +1,34 @@
+<!--
+order: 1
+-->
+
+# Tendermint KMS
+
+[Tendermint KMS](https://github.com/iqlusioninc/tmkms) is a key management service that allows separating key management from Tendermint nodes. In addition it provides other advantages such as:
+
+- Improved security and risk management policies
+- Unified API and support for various HSM (hardware security modules)
+- Double signing protection (software or hardware based)
+
+It is recommended that the KMS service runs in a separate physical hosts.
+
+## Building
+
+Detailed build instructions can be found [here](https://github.com/iqlusioninc/tmkms#installation).
+
+::: tip
+When compiling the KMS, ensure you have enabled the applicable features:
+:::
+
+| Backend                 | Recommended Command line          |
+|-------------------------|-----------------------------------|
+| YubiHSM                 | `cargo build --features yubihsm`  |
+| Ledger + Tendermint App | `cargo build --features ledgertm` |
+
+## Configuration
+
+A KMS can be configured using the following HSMs:
+
+### Using a YubiHSM
+
+Detailed information on how to setup a KMS with YubiHSM2 can be found [here](https://github.com/iqlusioninc/tmkms/blob/master/README.yubihsm.md)

docs/guides/localnet/single_node.md

@@ -11,7 +11,7 @@ order: 1
 
 ## Automated Localnet (script)
 
-You can customize the localtestnet script by changing values for convinience for example:
+You can customize the local testnet script by changing values for convenience for example:
 
 ```bash
 # customize the name of your key, the chain-id, moniker of the node, keyring backend, and log level
@@ -42,69 +42,100 @@ init.sh
 
 This guide helps you create a single validator node that runs a network locally for testing and other development related uses.
 
-### Initialize node
+### Initialize the chain
+
+Before actually running the node, we need to initialize the chain, and most importantly its genesis file. This is done with the `init` subcommand:
 
 ```bash
 $MONIKER=testing
 $KEY=mykey
 $CHAINID="ethermint_9000-1"
 
+# The argument $MONIKER is the custom username of your node, it should be human-readable.
 ethermintd init $MONIKER --chain-id=$CHAINID
 ```
 
-::: warning
-Monikers can contain only ASCII characters. Using Unicode characters will render your node unreachable.
+::: tip
+You can [edit](./../../quickstart/binary.md#configuring-the-node) this `moniker` later by updating the `config.toml` file.
 :::
 
-You can edit this `moniker` later, in the `$(HOME)/.ethermintd/config/config.toml` file:
+The command above creates all the configuration files needed for your node and validator to run, as well as a default genesis file, which defines the initial state of the network. All these [configuration files](./../../quickstart/binary.md#configuring-the-node) are in `~/.ethermintd` by default, but you can overwrite the location of this folder by passing the `--home` flag.
+
+### Genesis Procedure
+
+### Adding Genesis Accounts
 
-```toml
-# A custom human readable name for this node
-moniker = "<your_custom_moniker>"
+Before starting the chain, you need to populate the state with at least one account using the [keyring](./../keys-wallets/keyring.md#add-keys):
+
+```bash
+ethermintd keys add my_validator --keyring-backend=test
 ```
 
-You can edit the `$HOME/.ethermintd/config/app.toml` file in order to enable the anti spam mechanism and reject incoming transactions with less than the minimum gas prices:
+Once you have created a local account, go ahead and grant it some `aphoton` tokens in your chain's genesis file. Doing so will also make sure your chain is aware of this account's existence:
 
-```toml
-# This is a TOML config file.
-# For more information, see https://github.com/toml-lang/toml
+```bash
+ethermintd add-genesis-account my_validator 10000000000aphoton --keyring-backend test
+```
 
-##### main base config options #####
+Now that your account has some tokens, you need to add a validator to your chain.
 
-# 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. 10aphoton).
+ For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`:
 
-minimum-gas-prices = ""
+```bash
+# Create a gentx
+# NOTE: this command lets you set the number of coins. 
+# Make sure this account has some coins with the genesis.app_state.staking.params.bond_denom denom
+ethermintd add-genesis-account my_validator 1000000000stake,10000000000aphoton
 ```
 
-### Genesis Procedure
+A `gentx` does three things:
+
+1. Registers the `validator` account you created as a validator operator account (i.e. the account that controls the validator).
+2. Self-delegates the provided `amount` of staking tokens.
+3. Link the operator account with a Tendermint node pubkey that will be used for signing blocks. If no `--pubkey` flag is provided, it defaults to the local node pubkey created via the `ethermintd init` command above.
+
+For more information on `gentx`, use the following command:
 
 ```bash
-# Create a key to hold your account
-ethermintd keys add $KEY
+ethermintd gentx --help
+```
 
-# Add that key into the genesis.app_state.accounts array in the genesis file
-# NOTE: this command lets you set the number of coins. Make sure this account has some coins
-# with the genesis.app_state.staking.params.bond_denom denom, the default is staking
-ethermintd add-genesis-account $(ethermintd keys show validator -a) 1000000000stake,10000000000aphoton
+### Collecting `gentx`
 
-# Generate the transaction that creates your validator
-ethermintd gentx --name $KEY
+By default, the genesis file do not contain any `gentxs`. A `gentx` is a transaction that bonds
+staking token present in the genesis file under `accounts` to a validator, essentially creating a
+validator at genesis. The chain will start as soon as more than 2/3rds of the validators (weighted
+by voting power) that are the recipient of a valid `gentx` come online after `genesis_time`.
 
-# Add the generated bonding transaction to the genesis file
-ethermintd collect-gentxs
+A `gentx` can be added manually to the genesis file, or via the following command:
 
-# Finally, check the correctness of the genesis.json file
-ethermintd validate-genesis
+```bash
+# Add the gentx to the genesis file
+ethermintd collect-gentxs
 ```
 
+This command will add all the `gentxs` stored in `~/.ethermintd/config/gentx` to the genesis file.
+
 ### Run Testnet
 
-Now its safe to start the daemon:
+Finally, check the correctness of the `genesis.json` file:
+
+```bash
+ethermintd validate-genesis
+```
+
+Now that everything is set up, you can finally start your node:
 
 ```bash
 ethermintd start
 ```
 
-You can then stop the node using Ctrl+C.
+:::tip
+To check all the available customizable options when running the node, use the `--help` flag.
+:::
+
+You should see blocks come in.
+
+The previous command allow you to run a single node. This is enough for the next section on interacting with this node, but you may wish to run multiple nodes at the same time, and see how consensus happens between them.
+
+You can then stop the node using `Ctrl+C`.

docs/guides/upgrade.md

@@ -46,7 +46,7 @@ mv new_genesis.json genesis.json
 
 Finally, go to the [reset data](./run_node.md#reset-data) section.
 
-### Export State to a new Genesis locally
+### Export State
 
 Ethermint can dump the entire application state to a JSON file. This, besides upgrades, can be
 useful for manual analysis of the state at a given height.

docs/testnet/security.md → docs/guides/validators/checklist.md

@@ -1,11 +1,14 @@
-
 <!--
-order: 5
+order: 4
 -->
 
-# Validator Security
+# Validator Security Checklist
+
+ Conduct a security checklist survey to go through the security measures of a validator {synopsis}
+
+## Pre-requisite Readings
 
-## Checklist
+- [Validator Security](./security.md) {prereq}
 
 ## Conduct Survey on General Controls of Hosting Data Centre