docs: Add new section "Running a Node" (#7701)

* docs: Add new section "Running a Node"

* Add running-node

* Add docker compose

* Update title

* Typos

* Wording

* Fix links

* Update docs/run-node/keyring.md

Co-authored-by: Cory <[email protected]>

* Update docs/run-node/run-node.md

Co-authored-by: Robert Zaremba <[email protected]>

* Address reviews

* rc2

* Update docs/run-node/keyring.md

Co-authored-by: Cory <[email protected]>

* Address more comments

* Reviews

* Fix run node

* Fix todo

Co-authored-by: Cory <[email protected]>
Co-authored-by: Robert Zaremba <[email protected]>
Co-authored-by: Alessio Treglia <[email protected]>

crypto/keyring/doc.go

@@ -32,7 +32,7 @@
 // 			that the keyring keyring may be kept unlocked for the whole duration of the user
 // 			session.
 // 	file	This backend more closely resembles the previous keyring storage used prior to
-// 			v0.38.1. It stores the keyring encrypted within the apps configuration directory.
+// 			v0.38.1. It stores the keyring encrypted within the app's configuration directory.
 // 			This keyring will request a password each time it is accessed, which may occur
 // 			multiple times in a single command resulting in repeated password prompts.
 // 	kwallet	This backend uses KDE Wallet Manager as a credentials management application:

docs/interfaces/README.md

@@ -1,7 +1,7 @@
 <!--
 order: false
 parent:
-  order: 5
+  order: 6
 -->
 
 # Interfaces
@@ -12,4 +12,3 @@ This repository contains documentation on interfaces for Cosmos SDK applications
 2. [Lifecycle of a Query](./query-lifecycle.md)
 3. [Command-Line Interface](./cli.md)
 4. [Rest Interface](./rest.md)
-

docs/run-node/README.md

@@ -0,0 +1,13 @@
+<!--
+order: false
+parent:
+  order: 5
+-->
+
+# Running a Node
+
+This folder contains documentation on how to run a node and interact with it.
+
+1. [Setting up the keyring](./keyring.md)
+2. [Running a Node](./run-node.md)
+3. [Interacting with a Node](./interact-node.md)

docs/run-node/interact-node.md

@@ -0,0 +1,46 @@
+<!--
+order: 3
+-->
+
+# Interacting with the Node
+
+## Pre-requisite Readings
+
+- [Running a Node](./run-node.md) {prereq}
+
+## Via CLI
+
+Now that your chain is running, it is time to try sending tokens from the first account you created to a second account. In a new terminal window, start by running the following query command:
+
+```bash
+simd query account $MY_VALIDATOR_ADDRESS --chain-id my-test-chain
+```
+
+You should see the current balance of the account you created, equal to the original balance of `stake` you granted it minus the amount you delegated via the `gentx`. Now, create a second account:
+
+```bash
+simd keys add recipient
+
+# Put the generated address in a variable for later use.
+RECIPIENT=$(simd keys show recipient -a)
+```
+
+The command above creates a local key-pair that is not yet registered on the chain. An account is created the first time it receives tokens from another account. Now, run the following command to send tokens to the `recipient` account:
+
+```bash
+simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake --chain-id my-test-chain
+
+# Check that the recipient account did receive the tokens.
+simd query account $RECIPIENT --chain-id my-test-chain
+```
+
+Finally, delegate some of the stake tokens sent to the `recipient` account to the validator:
+
+```bash
+simd tx staking delegate $(simd keys show my_validator --bech val -a) 500stake --from recipient --chain-id my-test-chain
+
+# Query the total delegations to `validator`.
+simd query staking delegations-to $(simd keys show my_validator --bech val -a) --chain-id my-test-chain
+```
+
+You should see two delegations, the first one made from the `gentx`, and the second one you just performed from the `recipient` account.

docs/interfaces/keyring.md → docs/run-node/keyring.md

@@ -1,28 +1,32 @@
 <!--
-order: 3
+order: 1
 -->
 
-# The keyring
+# Setting up the keyring
 
-This document describes how to configure and use the keyring and its various backends for an [**application**](../basics/app-anatomy.md). A separate document for implementing a CLI for an SDK [**module**](../building-modules/intro.md) can be found [here](#../building-modules/module-interfaces.md#cli). {synopsis}
+This document describes how to configure and use the keyring and its various backends for an [**application**](../basics/app-anatomy.md). {synopsis}
+
+The keyring holds the private/public keypairs used to interact with a node. For instance, a validator key needs to be set up before running the blockchain node, so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage.
+
+## Available backends for the keyring
 
 Starting with the v0.38.0 release, Cosmos SDK comes with a new keyring implementation
 that provides a set of commands to manage cryptographic keys in a secure fashion. The
 new keyring supports multiple storage backends, some of which may not be available on
 all operating systems.
 
-## The `os` backend
+### The `os` backend
 
 The `os` backend relies on operating system-specific defaults to handle key storage
-securely. Typically, operating systems credentials sub-systems handle passwords prompt,
-private keys storage, and user sessions according to their users password policies. Here
+securely. Typically, an operating system's credential sub-system handles password prompts,
+private keys storage, and user sessions according to the user's password policies. Here
 is a list of the most popular operating systems and their respective passwords manager:
 
-* macOS (since Mac OS 8.6): [Keychain](https://support.apple.com/en-gb/guide/keychain-access/welcome/mac)
-* Windows: [Credentials Management API](https://docs.microsoft.com/en-us/windows/win32/secauthn/credentials-management)
-* GNU/Linux:
-  * [libsecret](https://gitlab.gnome.org/GNOME/libsecret)
-  * [kwallet](https://api.kde.org/frameworks/kwallet/html/index.html)
+- macOS (since Mac OS 8.6): [Keychain](https://support.apple.com/en-gb/guide/keychain-access/welcome/mac)
+- Windows: [Credentials Management API](https://docs.microsoft.com/en-us/windows/win32/secauthn/credentials-management)
+- GNU/Linux:
+  - [libsecret](https://gitlab.gnome.org/GNOME/libsecret)
+  - [kwallet](https://api.kde.org/frameworks/kwallet/html/index.html)
 
 GNU/Linux distributions that use GNOME as default desktop environment typically come with
 [Seahorse](https://wiki.gnome.org/Apps/Seahorse). Users of KDE based distributions are
@@ -34,10 +38,10 @@ client.
 designed to meet users' most common needs and provide them with a comfortable
 experience without compromising on security.
 
-## The `file` backend
+### The `file` backend
 
 The `file` backend more closely resembles the keybase implementation used prior to
-v0.38.1. It stores the keyring encrypted within the apps configuration directory. This
+v0.38.1. It stores the keyring encrypted within the app's configuration directory. This
 keyring will request a password each time it is accessed, which may occur multiple
 times in a single command resulting in repeated password prompts. If using bash scripts
 to execute commands using the `file` option you may want to utilize the following format
@@ -54,7 +58,7 @@ $ echo $KEYPASSWD | gaiacli keys show me                          # single promp
 The first time you add a key to an empty keyring, you will be prompted to type the password twice.
 :::
 
-## The `pass` backend
+### The `pass` backend
 
 The `pass` backend uses the [pass](https://www.passwordstore.org/) utility to manage on-disk
 encryption of keys' sensitive data and metadata. Keys are stored inside `gpg` encrypted files
@@ -78,15 +82,42 @@ $ pass init <GPG_KEY_ID>
 Replace `<GPG_KEY_ID>` with your GPG key ID. You can use your personal GPG key or an alternative
 one you may want to use specifically to encrypt the password store.
 
-## The `test` backend
+### The `test` backend
 
 The `test` backend is a password-less variation of the `file` backend. Keys are stored
 unencrypted on disk. This backend is meant for testing purposes only and **should never be used
 in production environments**.
 
-## The `kwallet` backend
+### The `kwallet` backend
 
 The `kwallet` backend uses `KDE Wallet Manager`, which comes installed by default on the
 GNU/Linux distributions that ships KDE as default desktop environment. Please refer to
 [KWallet Handbook](https://docs.kde.org/stable5/en/kdeutils/kwallet5/index.html) for more
 information.
+
+## Adding keys to the keyring
+
+::: warning
+Make sure you can build your own binary, and replace `simd` with the name of your binary in the snippets.
+:::
+
+Applications developed using the Cosmos SDK come with the `keys` subcommand. For the purpose of this tutorial, we're running the `simd` CLI, which is an application built using the Cosmos SDK for testing and educational purposes. For more information, see [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/v0.40.0-rc2/simapp).
+
+You can use `simd keys` for help about the keys command and `simd keys [command] --help` for more information about a particular subcommand.
+
+::: tip
+You can also enable auto-completion with the `simd completion` command. For example, at the start of a bash session, run `. <(simd completion)`, and all `simd` subcommands will be auto-completed.
+:::
+
+To create a new key in the keyring, run the `add` subcommand with a `<key_name>` argument. For the purpose of this tutorial, we will solely use the `test` backend, and call our new key `my_validator`. This key will be used in the next section.
+
+```bash
+$ simd keys add my_validator --keyring-backend test
+
+# Put the generated address in a variable for later use.
+MY_VALIDATOR_ADDRESS=$(simd keys show my_validator -a)
+```
+
+This command generates a new 24-word mnemonic phrase, persists it to the relevant backend, and outputs information about the keypair. If this keypair will be used to hold value-bearing tokens, be sure to write down the mnemonic phrase somewhere safe!
+
+By default, the keyring generates a `secp256k1` keypair. The keyring also supports `ed25519` keys, which may be created by passing the `--algo ed25519` flag. A keyring can of course hold both types of keys simultaneously, and the Cosmos SDK's `x/auth` module (in particular its [AnteHandlers](../core/baseapp.md#antehandler)) supports natively these two public key algorithms.

docs/run-node/run-node.md

@@ -0,0 +1,90 @@
+<!--
+order: 2
+-->
+
+# Running a Node
+
+Now that the application is ready and the keyring populated, it's time to see how to run the blockchain node. In this section, the application we are running is called [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/v0.40.0-rc2/simapp), and its corresponding CLI binary `simd`. {synopsis}
+
+## Pre-requisite Readings
+
+- [Anatomy of an SDK Application](../basics/app-anatomy.md) {prereq}
+- [Setting up the keyring](./keyring.md) {prereq}
+
+## Initialize the Chain
+
+::: warning
+Make sure you can build your own binary, and replace `simd` with the name of your binary in the snippets.
+:::
+
+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
+# The argument <moniker> is the custom username of your node, it should be human-readable.
+simd init <moniker> --chain-id my-test-chain
+```
+
+The command above creates all the configuration files needed for your node to run, as well as a default genesis file, which defines the initial state of the network. All these configuration files are in `~/.simapp` by default, but you can overwrite the location of this folder by passing the `--home` flag.
+
+The `~/.simapp` folder has the following structure:
+
+```bash
+.                                   # ~/.simapp
+  |- data                           # Contains the databases used by the node.
+  |- config/
+      |- app.toml                   # Application-related configuration file.
+      |- config.toml                # Tendermint-related configuration file.
+      |- genesis.json               # The genesis file.
+      |- node_key.json              # Private key to use for node authentication in the p2p protocol.
+      |- priv_validator_key.json    # Private key to use as a validator in the consensus protocol.
+```
+
+Before starting the chain, you need to populate the state with at least one account. To do so, first [create a new account in the keyring](./keyring.md#adding-keys-to-the-keyring) named `my_validator` (feel free to choose another name).
+
+Now that you have created a local account, go ahead and grant it some `stake` tokens in your chain's genesis file. Doing so will also make sure your chain is aware of this account's existence:
+
+```bash
+simd add-genesis-account $(simd keys show my_validator -a) 100000000stake --chain-id my-test-chain
+```
+
+Recall that `$MY_VALIDATOR_ADDRESS` is a variable that holds the address of the `my_validator` key in the [keyring](./keyring.md#adding-keys-to-the-keyring). Also note that the tokens in the SDK have the `{amount}{denom}` format: `amount` is is a 18-digit-precision decimal number, and `denom` is the unique token identifier with its denomination key (e.g. `atom` or `uatom`). Here, we are granting `stake` tokens, as `stake` is the token identifier used for staking in [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/v0.40.0-rc2/simapp). For your own chain with its own staking denom, that token identifier should be used instead.
+
+Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the [underlying consensus engine](../intro/sdk-app-architecture.md#tendermint)) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). 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`:
+
+```bash
+# Create a gentx.
+simd gentx --name my_validator --amount 100000stake --chain-id my-test-chain
+
+# Add the gentx to the genesis file.
+simd collect-gentxs --chain-id my-test-chain
+```
+
+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 `simd init` command above.
+
+For more information on `gentx`, use the following command:
+
+```bash
+simd gentx --help
+```
+
+## Run a Localnet
+
+Now that everything is set up, you can finally start your node:
+
+```bash
+simd start
+```
+
+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.
+
+The naive way would be to run the same commands again in separate terminal windows. This is possible, however in the SDK, we leverage the power of [Docker Compose](https://docs.docker.com/compose/) to run a localnet. If you need inspiration on how to set up your own localnet with Docker Compose, you can have a look at the SDK's [`docker-compose.yml`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/docker-compose.yml).
+
+## Next {hide}
+
+Read about the [Interacting with your Node](./interact-node.md) {hide}