Update docs

book/src/validator-manager-move.md

@@ -1,16 +1,59 @@
 # Moving Validators
 
-This document describes the steps to move validators between two validator clients (VCs) which are
-able to SSH between each other. This guides assumes experience with the Linux command line and SSH
+The `lighthouse validator-manager move` command uses the VC HTTP API to move
+validators from one VC (the "src" VC) to another VC (the "dest" VC). The move
+operation is *comprehensive*; it will:
+
+- Disable the validators the src VC.
+- Remove the validator keystores from the src VC file system.
+- Export the slashing database records for the appropriate validators from the src VC to the dest VC.
+- Enable the validators on the dest VC.
+- Generally result in very little or no validator downtime.
+
+It is capable of moving all validators on the src VC, a number of validators or
+specific validators from one VC to another.
+
+The `move` command is only guaranteed to work between two Lighthouse VCs (i.e.,
+there is no guarantee that the commands will work between Lighthouse and Teku or
+another client).
+
+The `move` command only supports moving validators using a keystore on the local
+file system, it does not support `Web3Signer` validators.
+
+Although all efforts are taken to avoid it, it's possible for the `move` command
+to fail in a way removes the validator from the src VC without adding it to the
+dest VC. Therefore, it is recommended to **never use the `move` command without
+having a backup of all validator keystores (e.g., the mnemonic).**
+
+## Simple Example
+
+```
+lighthouse \
+	validator-manager \
+	move \
+	--src-vc-url http://localhost:6062 \
+	--src-vc-token ~/src-token.txt \
+	--dest-vc-url http://localhost:5062 \
+	--dest-vc-token ~/.lighthouse/mainnet/validators/api-token.txt \
+	--validators all \
+```
+
+## Guide
+
+This guide describes the steps to move validators between two validator clients (VCs) which are
+able to SSH between each other. This guide assumes experience with the Linux command line and SSH
 connections.
 
 There will be two VCs in this example:
 
 - The *source* VC which contains the validators/keystores to be moved.
 - The *destination* VC which is to take the validators/keystores from the source.
 
-This example will assume the source VC is accessible at `src-host` and the destination VC is
-accessible at `dest-host`. Replace these values with your own.
+The example will assume the source VC is accessible at `src-host` and the destination VC is
+accessible at `dest-host`. Replace these values with your own hostnames or IP addresses.
+
+The example assumes that the reader is currently logged into `dest-host` via SSH
+and that the reader can SSH from `dest-host` to `src-host`.
 
 ### 1. Configure the Source VC
 
@@ -38,15 +81,29 @@ lighthouse \
 
 The destination VC needs to have the following flags:
 
+- `--http`
+- `--unencrypted-http-transport`
+- `--http-address 127.0.0.1`
+- `--http-port 5062`
+- `--enable-doppelganger-protection`
+
+Therefore, the destination VC command might look like:
+
 ```bash
 lighthouse \
     vc \
     --http \
     --unencrypted-http-transport \
     --http-address 127.0.0.1 \
     --http-port 5062 \
+    --enable-doppelganger-protection
 ```
 
+The `--enable-doppelganger-protection` flag is not *strictly* required, however
+it is recommended for an additional layer of safety. It will result in 3-4
+epochs of downtime for the validator after it is moved, which is generally an
+inconsequential cost in lost rewards or penalties.
+
 Optionally, users can add the `--http-store-passwords-in-secrets-dir` flag if they'd like to have
 the import validator keystore passwords stored in separate files rather than in the
 `valdiator-definitions.yml` file. If you don't know what this means, you can safely omit the flag.
@@ -73,7 +130,6 @@ alongside validator keystores. For example: `~/.lighthouse/mainnet/validators/ap
 Copy the contents of that file into a new file on the **destination host** at `~/src-token.txt`. The
 API token should be similar to `api-token-0x03eace4c98e8f77477bb99efb74f9af10d800bd3318f92c33b719a4644254d4123`.
 
-
 ### 4. Create an SSH Tunnel
 
 In one terminal window, SSH to the **destination host** and establish a reverse-SSH connection
@@ -103,4 +159,14 @@ lighthouse \
 	--validators all \
 ```
 
-TODO
+The command will provide information about the progress of the operation and
+emit `Done.` when the operation has completed successfully.
+
+Once the operation completes successfully, there is nothing else to be done. The
+validators have been removed from the `src-host` and enabled at the `dest-host`.
+If the `--enable-doppelganger-protection` flag was used it may take 3-4 epochs
+for the validators to start attesting and producing blocks on the `dest-host`.
+
+Any errors encounted during the operation should include information on how to
+proceed. Assistance is also available on our
+[Discord](https://discord.gg/cyAszAh).