diff --git a/book/src/validator-manager-create.md b/book/src/validator-manager-create.md new file mode 100644 index 00000000000..cf06dad7368 --- /dev/null +++ b/book/src/validator-manager-create.md @@ -0,0 +1,170 @@ +# Creating and Importing Validators + +[Ethereum Staking Launchpad]: https://launchpad.ethereum.org/en/ + +The `lighthouse validator-manager create` command derives validators from a +mnemonic and produces two files: + +- `validators.json`: the keystores and passwords for the newly generated + validators in JSON format. +- `deposits.json`: a JSON file of the same format as + [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli) which can + be used for deposit submission via the [Ethereum Staking + Launchpad][]. + +The `lighthouse validator-manager import` command accepts a `validators.json` +file (from the `create` command) and submits those validators to a running +Lighthouse Validator Client via the HTTP API. + +These two commands enable a workflow of: + +1. Creating the validators via the `create` command. +1. Importing the validators via the `import` command. +1. Depositing validators via the [Ethereum Staking + Launchpad][]. + +The separation of the `create` and `import` commands allows for running the +`create` command on an air-gapped host whilst performing the `import` command on +an internet-connected host. + +The `create` and `import` commands are recommended for advanced users who are +familiar with command line tools and the practicalities of managing sensitive +key information. **We recommend that novice users follow the workflow on +[Ethereum Staking Launchpad][] rather than using the `move` and `create` +tools.** + +## Simple Example + +Create validators from a mnemonic with: + +```bash +lighthouse \ + validator-manager \ + create \ + --first-index 0 \ + --count 2 \ + --eth1-withdrawal-address
\ + --output-path ./ +``` + +Import the validators to a running VC with: + +```bash +lighthouse \ + validator-manager \ + import \ + --validators-file validators.json \ + --vc-token +``` + +Be sure to remove `./validators.json` after the import is successful since it +contains unencrypted validator keystores. + +## Detailed Guide + +This guide will create two validators and import them to a VC. For simplicity, +the same host will be used to generate the keys and run the VC. In reality, +users may want to perform the `import` command on an air-gapped machine and then +move the `validators.json` and `deposits.json` files to an Internet-connected +host. This would help protect the mnemonic from being exposed to the Internet. + +### 1. Create the Validators + +Run the `create` command, subsituting `
` for an execution address that +you control. This is where all the staked ETH and rewards will ultimately +reside, so it's very important that this address is secure, acessible and +backed-up. + +```bash +lighthouse \ + validator-manager \ + create \ + --first-index 0 \ + --count 2 \ + --eth1-withdrawal-address
\ + --output-path ./ +``` + +If successful, the command output will appear like below: + +```bash +Running validator manager for mainnet network + +Enter the mnemonic phrase: + +Valid mnemonic provided. + +Starting derivation of 2 keystores. Each keystore may take several seconds. +Completed 1/2: 0x8885c29b8f88ee9b9a37b480fd4384fed74bda33d85bc8171a904847e65688b6c9bb4362d6597fd30109fb2def6c3ae4 +Completed 2/2: 0xa262dae3dcd2b2e280af534effa16bedb27c06f2959e114d53bd2a248ca324a018dc73179899a066149471a94a1bc92f +Keystore generation complete +Writing "./validators.json" +Writing "./deposits.json" +``` + +This command will create validators at indices `0, 1`. The exact indices created +can be influenced with the `--first-index` and `--count` flags. Use these flags +with caution to prevent creating the same validator twice, this may result in a +slashing! + +The command will create two files: + +- `./deposits.json`: this file does not contain sensitive information and may be uploaded to the [Ethereum Staking Launchpad]. +- `./validators.json`: this file contains **sensitive unencrypted validator keys, do not share it with anyone or upload it to any website**. + +### 2. Import the validators + +The VC which will receive the validators needs to have the following flags at a minimum: + +- `--http` +- `--unencrypted-http-transport` +- `--http-address 127.0.0.1` +- `--http-port 5062` +- `--enable-doppelganger-protection` + +Therefore, the VC command might look like: + +```bash +lighthouse \ + vc \ + --http \ + --unencrypted-http-transport \ + --http-address 127.0.0.1 \ + --http-port 5062 \ + --enable-doppelganger-protection +``` + +In order to import the validators, the location of the VC `api-token.txt` file +must be known. The location of the file varies, but it is located in the +"validator directory" of your data directory. For example: +`~/.lighthouse/mainnet/validators/api-token.txt`. We will use `` +to subsitute this value. + + +Once the VC is running, use the `import` command to import the validators to the VC: + +```bash +lighthouse \ + validator-manager \ + import \ + --validators-file validators.json \ + --vc-token +``` + +If successful, the command output will appear like below: + +```bash +Running validator manager for mainnet network +Validator client is reachable at http://localhost:5062/ and reports 0 validators +Starting to submit validators 2 to VC, each validator may take several seconds +Uploaded keystore 1 of 2 to the VC +Uploaded keystore 2 of 2 to the VC +``` + +The user should now *securely* delete the `validators.json` file (e.g., `shred -u validators.json`). +The `validators.json` contains the unencrypted validator keys and must not be +shared with anyone. + +The validators will now go through 3-4 epochs of [doppelganger +protection](./validator-doppelganger.md) and will automatically start performing +their duties when they are deposited and activated. \ No newline at end of file diff --git a/book/src/validator-manager-move.md b/book/src/validator-manager-move.md index 2abe4cf1ed8..b3ce6298201 100644 --- a/book/src/validator-manager-move.md +++ b/book/src/validator-manager-move.md @@ -27,6 +27,9 @@ having a backup of all validator keystores (e.g., the mnemonic).** ## Simple Example +The following command will move all validators from the VC running at +`http://localhost:6062` to the VC running at `http://localhost:5062`. + ``` lighthouse \ validator-manager \ @@ -38,7 +41,7 @@ lighthouse \ --validators all \ ``` -## Guide +## Detailed 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 @@ -57,7 +60,7 @@ and that the reader can SSH from `dest-host` to `src-host`. ### 1. Configure the Source VC -The source VC needs to have the following flags: +The source VC needs to have the following flags at a mininum: - `--http` - `--unencrypted-http-transport` @@ -79,7 +82,7 @@ lighthouse \ ### 2. Configure the Destination VC -The destination VC needs to have the following flags: +The destination VC needs to have the following flags at a mininum: - `--http` - `--unencrypted-http-transport` diff --git a/book/src/validator-manager.md b/book/src/validator-manager.md index 1b8b1f1a038..739a8132af5 100644 --- a/book/src/validator-manager.md +++ b/book/src/validator-manager.md @@ -1,6 +1,6 @@ # Validator Manager -[Ethereum Launchpad]: https://launchpad.ethereum.org/en/ +[Ethereum Staking Launchpad]: https://launchpad.ethereum.org/en/ [Import Validators]: #import-validators ## Introduction @@ -16,25 +16,12 @@ creates files that will be read by the VC next time it starts rather than making a live VC. The validator manager is generally superior to the account manager for the following (non-exhaustive) reasons: -- The validator manager generates deposit files compatible with the [Ethereum Launchpad](). +- The validator manager generates deposit files compatible with the [Ethereum Staking Launchpad](). - Changes made with the validator manager do not require downtime for the VC. - The "key cache" is preserved whenever a validator is added with the validator manager, this prevents long waits at start up when a new validator is added. -## Commands +### Validator Manager Documentation -### Create Validators - -The `lighthouse validator-manager create` command accepts a mnemonic and produces a JSON -file containing validator keystores that can be imported with the [Import -Validators]() command. - -For users that want to add validators to a VC from an existing mnemonic, this is the first half the -process which generates a *validator specifications* JSON file for the new validators. The second -half of the process is to upload those validator specifications to a VC (see [Import Validators](). -The command is split into two steps so that security-conscious validators can generate the validator -specifications on an "air-gapped" computer which is not connected to the Internet. Then, the -validator specifications file can be transferred to a VC for import. This means that the VC never -has access to the mnemonic, just the keystores with which it is concerned. - -### Import Validators +- [Creating and importing validators using the `create` and `import` commands](./validator-manager-create.md) +- [Moving validators between two VCs using the `move` command](./validator-manager.md) \ No newline at end of file