From d4f4110c942271f5e736f8615aa0d1fa2cd77c1c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philippe=20Laferri=C3=A8re?= <plafer@protonmail.com>
Date: Wed, 27 Apr 2022 07:15:52 +0000
Subject: [PATCH] Improve private keys docs (#2145)

---
 guide/src/commands/keys/index.md          | 12 ++++---
 guide/src/tutorials/local-chains/start.md | 44 +++++++++++++++++++++++
 2 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/guide/src/commands/keys/index.md b/guide/src/commands/keys/index.md
index 843736cf8d..e84200573e 100644
--- a/guide/src/commands/keys/index.md
+++ b/guide/src/commands/keys/index.md
@@ -41,17 +41,19 @@ SUBCOMMANDS:
 
 In order to execute the command below you need a private key file (JSON). The relayer uses the private key file to sign the transactions submitted to the chain.
 
-The private key file can be obtained by using the `keys add` on a Cosmos chain, for example for a `gaia` chain the command is:
+The private key file can be obtained by using the `keys add` on a Cosmos chain. For example, the command for `gaiad` is:
 
 ```shell
-gaiad keys add ...
+# The `key_name` parameter is the name of the key that will be found in the json output
+# For example, in the "Two Local Chains" tutorial, we use "testkey".
+gaiad keys add <key_name> --output json
 ```
 
-The command outputs a JSON similar to the one below. You can save this file (e.g. `key_seed.json`) and use it to add to the relayer
+The command outputs a JSON similar to the one below. 
 
 ```json
 {
-  "name": "user",
+  "name": "testkey",
   "type": "local",
   "address": "cosmos1tc3vcuxyyac0dmayf887t95tdg7qpyql48w7gj",
   "pubkey": "cosmospub1addwnpepqgg7ng4ycm60pdxfzdfh4hjvkwcr3da59mr8k883vsstx60ruv7kur4525u",
@@ -59,6 +61,8 @@ The command outputs a JSON similar to the one below. You can save this file (e.g
 }
 ```
 
+You can save this to a file (e.g. `key_seed.json`) and use it to add to the relayer with `hermes keys add <chain_id> -f key_seed.json`. See the `Adding Keys` section for more details.
+
 ### Adding Keys
 
 #### Add a private key to a chain from a key file
diff --git a/guide/src/tutorials/local-chains/start.md b/guide/src/tutorials/local-chains/start.md
index 014d3709ed..3eea44a9e5 100644
--- a/guide/src/tutorials/local-chains/start.md
+++ b/guide/src/tutorials/local-chains/start.md
@@ -51,6 +51,50 @@ vi ~/.hermes/config.toml
 
 Then just __`copy`__ the content for `config.toml` above and __`paste`__ into this file.
 
+### Generating private keys
+Next, we will need to associate a private key with chains `ibc-0` and `ibc-1` which `hermes` will use to sign transactions. There
+are two steps involved. For each chain,
+1. Generate a *Key Seed file* using `gaiad`
+2. Use the *Key Seed file* to associate the corresponding private key with the chain
+
+In this tutorial, we will only generate a single *Key Seed file*, which we will use with both chains.
+
+#### Generate a Key Seed file
+We will generate the Key Seed file for a key that we will call `testkey`.
+
+```shell
+gaiad keys add testkey --output json
+```
+This will generate an output similar to the one below (albeit all on the same line):
+```json
+{
+  "name": "testkey",
+  "type": "local",
+  "address": "cosmos1tc3vcuxyyac0dmayf887t95tdg7qpyql48w7gj",
+  "pubkey": "cosmospub1addwnpepqgg7ng4ycm60pdxfzdfh4hjvkwcr3da59mr8k883vsstx60ruv7kur4525u",
+  "mnemonic": "[24 words mnemonic]"
+}
+```
+
+Next, copy and paste the output to a new file called `key_seed.json`. This file contains all the information necessary for `hermes` to
+derive a private key from.
+
+#### Associate a private key with each chain
+Our config file specifies two chains: `ibc-0` and `ibc-1`. We will need to specify a private key that `hermes` will use for each chain. As
+previously mentioned, in this tutorial we will use the same private key for both chains.
+
+```shell
+hermes keys add ibc-0 -f key_seed.json
+hermes keys add ibc-1 -f key_seed.json
+```
+If successful, both commands should show an output similar to:
+
+```
+Success: Added key testkey ([ADDRESS]) on [CHAIN ID] chain
+```
+
+And that's it! `hermes` will now be able to sign transactions to be sent to both chains. `key_seed.json` can safely be disposed of.
+
 ### Running the script to start the chains
 
 From the `ibc-rs` repository folder run the following script with the parameters below to start the chains (`ibc-0` and `ibc-1`)