Skip to content

Commit 45835f6

Browse files
chong-hechong-he
committed
Update Lighthouse book Sec 3-6 and FAQ (#4221)
## Issue Addressed Update Lighthouse book to include latest information especially after Capella upgrade ## Proposed Changes Notable changes: - Combine Sec 4.1 & 6.1 into Sec 4, because Sec 6.1 is importing validator key which is a required step when want to run a validator - Combine Sec 5.1 & 5.2 with Sec 5, and move Sec 5 to under Sec 9 - Added partial withdrawals in Sec 6 ## Additional Info Please provide any additional information. For example, future considerations or information useful for reviewers. Co-authored-by: chonghe <[email protected]>
1 parent b1416c8 commit 45835f6

21 files changed

+495
-577
lines changed

‎book/src/LaTeX/full-withdrawal.tex‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
% To compile the file using PdfLaTeX, you may use the latex+dvips+ps2pdf compilation. If you are using TeXstudio, this is builtin and you can choose this option by going to Options > Configure TeXstudio under Build & View, choose DVI -> PS -> PDF Chain
2+
3+
% Alternatively, you may use XeLaTeX with --shell-escape command. To do so in TeXstuidio, go to Options > Configure TeXstudio > Build. Under "Add Commands", enter a user of your choice, and in the right empty space, insert: txs:///xelatex/[--shell-escape]. When compile, go to Tools > User and select the user you just inserted.
4+
5+
\documentclass[]{article}
6+
\usepackage{pst-all}
7+
\pagestyle{empty}
8+
9+
10+
11+
\begin{document}
12+
13+
14+
\begin{figure}
15+
\psscalebox{1.0 1.0} % Change this value to rescale the drawing.
16+
{
17+
\begin{pspicture}(0,-9.09)(11.8,6.13)
18+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](7.3,6.13)(4.2,5.21)
19+
\rput[bl](4.6,5.51){Voluntary exit}
20+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{-<}(5.8,5.21)(5.8,3.71)(5.8,3.81)
21+
\psline[linecolor=black, linewidth=0.04](1.7,3.61)(9.8,3.61)
22+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(1.7,3.61)(1.7,2.61)
23+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](2.9,2.63)(0.8,1.55)
24+
\rput[bl](1.0,1.91){Type 0x00}
25+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](10.7,2.63)(8.6,1.55)
26+
\rput[bl](8.8,1.91){Type 0x01}
27+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(9.8,3.61)(9.8,2.61)
28+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(1.7,1.51)(1.7,0.61)
29+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](3.7,0.61)(0.0,-1.19)
30+
\rput[bl](0.6,-0.19){Funds locked in}
31+
\rput[bl](0.7,-0.79){Beacon chain}
32+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](11.8,0.73)(7.9,-1.39)
33+
\rput[bl](9.0,-0.59){Exit queue}
34+
\rput[bl](8.8,0.01){Varying time}
35+
\rput[bl](8.3,-1.09){32 minutes to weeks}
36+
\rput[bl](9.0,-2.89){Fixed time}
37+
\rput[bl](9.0,-3.49){27.3 hours}
38+
\rput[bl](8.8,-5.49){Varying time}
39+
\rput[bl](8.7,-5.99){validator sweep}
40+
\rput[bl](8.9,-6.59){up to 5 days}
41+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](11.6,-2.19)(8.0,-3.89)
42+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](11.7,-4.79)(7.9,-6.89)
43+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](3.7,-2.49)(0.0,-4.29)
44+
\rput[bl](1.3,-3.29){BLS to}
45+
\rput[bl](0.6,-3.89){execution change}
46+
\psline[linecolor=black, linewidth=0.04, linestyle=dashed, dash=0.17638889cm 0.10583334cm, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(1.7,-1.19)(1.7,-2.49)
47+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(9.8,1.51)(9.8,0.71)
48+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(9.8,-1.39)(9.8,-2.19)
49+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(9.8,-3.89)(9.8,-4.79)
50+
\psline[linecolor=black, linewidth=0.04, linestyle=dotted, dotsep=0.10583334cm](3.7,-3.39)(5.8,-3.39)
51+
\psline[linecolor=black, linewidth=0.04, linestyle=dotted, dotsep=0.10583334cm, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(5.8,-3.39)(5.8,-0.39)(7.9,-0.39)
52+
\psline[linecolor=black, linewidth=0.04, linestyle=dotted, dotsep=0.10583334cm, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(5.8,-3.39)(8.0,-3.39)
53+
\psline[linecolor=black, linewidth=0.04, linestyle=dotted, dotsep=0.10583334cm, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(5.8,-3.39)(5.8,-6.09)(7.9,-6.09)
54+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](11.7,-7.79)(7.9,-9.09)
55+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(9.8,-6.89)(9.8,-7.79)
56+
\rput[bl](8.1,-8.59){\Large{Full withdrawal}}
57+
\rput[bl](1.8,-2.09){\textit{\Large{anytime}}}
58+
\rput[bl](4.0,-3.19){\textit{\Large{either}}}
59+
\rput[bl](4.2,-3.89){\textit{\Large{one}}}
60+
\end{pspicture}
61+
}
62+
\end{figure}
63+
64+
65+
66+
\end{document}

‎book/src/LaTeX/partial-withdrawal.tex‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
% To compile the file using PdfLaTeX, you may use the latex+dvips+ps2pdf compilation. If you are using TeXstudio, this is builtin and you can choose this option by going to Options > Configure TeXstudio under Build & View, choose DVI -> PS -> PDF Chain
2+
3+
% Alternatively, you may use XeLaTeX with --shell-escape command. To do so in TeXstuidio, go to Options > Configure TeXstudio > Build. Under "Add Commands", enter a user of your choice, and in the right empty space, insert: txs:///xelatex/[--shell-escape]. When compile, go to Tools > User and select the user you just inserted.
4+
5+
6+
\documentclass[]{article}
7+
\usepackage{pst-all}
8+
\pagestyle{empty}
9+
10+
11+
12+
\begin{document}
13+
14+
\begin{figure}
15+
\psscalebox{1.0 1.0} % Change this value to rescale the drawing.
16+
{
17+
\begin{pspicture}(0,-8.09)(10.7,5.53)
18+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](7.14,5.53)(3.6,4.45)
19+
\rput[bl](3.8,4.81){Partial withdrawals}
20+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{-<}(5.2,4.41)(5.2,2.91)(5.2,3.01)
21+
\psline[linecolor=black, linewidth=0.04](1.8,2.81)(8.9,2.81)
22+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(1.8,2.81)(1.8,1.81)
23+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](2.7,1.83)(0.6,0.75)
24+
\rput[bl](0.8,1.09){Type 0x00}
25+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](9.8,1.83)(7.7,0.75)
26+
\rput[bl](7.92,1.07){Type 0x01}
27+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(8.9,2.81)(8.9,1.81)
28+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(1.7,0.71)(1.7,-0.19)
29+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](3.7,-0.19)(0.0,-1.99)
30+
\rput[bl](0.66,-0.99){Funds locked in}
31+
\rput[bl](0.9,-1.59){Beacon chain}
32+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](10.7,-3.29)(6.8,-5.09)
33+
\rput[bl](7.6,-3.99){validator sweep}
34+
\rput[bl](7.5,-4.69){$\sim$ every 5 days}
35+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](3.7,-3.29)(0.0,-5.09)
36+
\rput[bl](1.3,-4.09){BLS to}
37+
\rput[bl](0.5,-4.69){execution change}
38+
\psline[linecolor=black, linewidth=0.04, linestyle=dashed, dash=0.17638889cm 0.10583334cm, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(1.7,-1.99)(1.7,-3.29)
39+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(8.9,0.71)(8.9,-3.29)
40+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(3.7,-4.19)(6.7,-4.19)
41+
\psframe[linecolor=black, linewidth=0.04, dimen=outer](10.7,-6.29)(6.9,-8.09)
42+
\rput[bl](7.0,-6.99){Balance above 32 ETH}
43+
\rput[bl](7.9,-7.59){withdrawn}
44+
\psline[linecolor=black, linewidth=0.04, arrowsize=0.05291667cm 2.0,arrowlength=1.4,arrowinset=0.0]{->}(8.9,-5.09)(8.9,-6.29)
45+
\rput[bl](1.8,-2.89){\textit{\Large{anytime}}}
46+
\end{pspicture}
47+
}
48+
\end{figure}
49+
50+
\end{document}

‎book/src/SUMMARY.md‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,10 @@
1111
* [Update Priorities](./installation-priorities.md)
1212
* [Run a Node](./run_a_node.md)
1313
* [Become a Validator](./mainnet-validator.md)
14-
* [Become a Testnet Validator](./testnet-validator.md)
15-
* [Key Management](./key-management.md)
16-
* [Create a wallet](./wallet-create.md)
17-
* [Create a validator](./validator-create.md)
18-
* [Key recovery](./key-recovery.md)
1914
* [Validator Management](./validator-management.md)
20-
* [Importing from the Staking Launchpad](./validator-import-launchpad.md)
2115
* [Slashing Protection](./slashing-protection.md)
2216
* [Voluntary Exits](./voluntary-exit.md)
17+
* [Partial Withdrawals](./partial-withdrawal.md)
2318
* [Validator Monitoring](./validator-monitoring.md)
2419
* [Doppelganger Protection](./validator-doppelganger.md)
2520
* [Suggested Fee Recipient](./suggested-fee-recipient.md)
@@ -46,6 +41,8 @@
4641
* [Remote Signing with Web3Signer](./validator-web3signer.md)
4742
* [Database Configuration](./advanced_database.md)
4843
* [Database Migrations](./database-migrations.md)
44+
* [Key Management](./key-management.md)
45+
* [Key Recovery](./key-recovery.md)
4946
* [Advanced Networking](./advanced_networking.md)
5047
* [Running a Slasher](./slasher.md)
5148
* [Redundancy](./redundancy.md)

‎book/src/imgs/full-withdrawal.png‎

257 KB
Loading

‎book/src/imgs/partial-withdrawal.png‎

172 KB
Loading

‎book/src/installation.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,10 @@ After [The Merge](https://ethereum.org/en/roadmap/merge/) on 15<sup>th</sup> Sep
2929

3030

3131
* CPU: Quad-core AMD Ryzen, Intel Broadwell, ARMv8 or newer
32-
* Memory: 16 GB RAM or more
33-
* Storage: 2 TB solid state storage
32+
* Memory: 32 GB RAM*
33+
* Storage: 2 TB solid state drive
3434
* Network: 100 Mb/s download, 20 Mb/s upload broadband connection
35+
36+
> *Note: 16 GB RAM is becoming rather limited due to the increased resources required. 16 GB RAM would likely result in out of memory errors in the case of a spike in computing demand (e.g., caused by a bug) or during periods of non-finality of the beacon chain. Users with 16 GB RAM also have a limited choice when it comes to selecting an execution client, which does not help with the [client diversity](https://clientdiversity.org/). We therefore recommend users to have at least 32 GB RAM for long term health of the node, while also giving users the flexibility to change client should the thought arise.
37+
38+
Last update: April 2023

‎book/src/key-management.md‎

Lines changed: 55 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
[launchpad]: https://launchpad.ethereum.org/
44

55
>
6-
> **Note: we recommend using the [Staking launchpad][launchpad] to create validators.**
6+
> **Note: While Lighthouse is able to generate the validator keys and the deposit data file to submit to the deposit contract, we strongly recommend using the [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli) to create validators keys and the deposit data file. This is because the [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli) which has the option to assign a withdrawal address during the key generation process, while Lighthouse wallet will always generate keys with withdrawal credentials of type 0x00. This means that users who created keys using Lighthouse will have to update their withdrawal credentials in the future to enable withdrawals. In addition, Lighthouse generates the deposit data file in the form of `*.rlp`, which cannot be uploaded to the [Staking launchpad][launchpad] that accepts only `*.json` file. This means that users have to directly interact with the deposit contract to be able to submit the deposit if they were to generate the files using Lighthouse.**
77
88
Lighthouse uses a _hierarchical_ key management system for producing validator
99
keys. It is hierarchical because each validator key can be _derived_ from a
1010
master key, making the validators keys _children_ of the master key. This
11-
scheme means that a single 24-word mnemonic can be used to backup all of your
11+
scheme means that a single 24-word mnemonic can be used to back up all of your
1212
validator keys without providing any observable link between them (i.e., it is
1313
privacy-retaining). Hierarchical key derivation schemes are common-place in
1414
cryptocurrencies, they are already used by most hardware and software wallets
@@ -30,37 +30,63 @@ We defined some terms in the context of validator key management:
3030
keypair.
3131
- Defined in EIP-2335.
3232
- **Voting Keypair**: a BLS public and private keypair which is used for
33-
signing blocks, attestations and other messages on regular intervals,
34-
whilst staking in Phase 0.
33+
signing blocks, attestations and other messages on regular intervals in the beacon chain.
3534
- **Withdrawal Keypair**: a BLS public and private keypair which will be
3635
required _after_ Phase 0 to manage ETH once a validator has exited.
3736

38-
## Overview
37+
## Create a validator
38+
There are 2 steps involved to create a validator key using Lighthouse:
39+
1. [Create a wallet](#step-1-create-a-wallet-and-record-the-mnemonic)
40+
1. [Create a validator](#step-2-create-a-validator)
3941

40-
The key management system in Lighthouse involves moving down the above list of
41-
items, starting at one easy-to-backup mnemonic and ending with multiple
42-
keypairs. Creating a single validator looks like this:
42+
The following example demonstrates how to create a single validator key.
4343

44-
1. Create a **wallet** and record the **mnemonic**:
45-
- `lighthouse --network prater account wallet create --name wally --password-file wally.pass`
46-
1. Create the voting and withdrawal **keystores** for one validator:
47-
- `lighthouse --network prater account validator create --wallet-name wally --wallet-password wally.pass --count 1`
44+
### Step 1: Create a wallet and record the mnemonic
45+
A wallet allows for generating practically unlimited validators from an
46+
easy-to-remember 24-word string (a mnemonic). As long as that mnemonic is
47+
backed up, all validator keys can be trivially re-generated.
4848

49+
Whilst the wallet stores the mnemonic, it does not store it in plain-text: the
50+
mnemonic is encrypted with a password. It is the responsibility of the user to
51+
define a strong password. The password is only required for interacting with
52+
the wallet, it is not required for recovering keys from a mnemonic.
4953

50-
In step (1), we created a wallet in `~/.lighthouse/{network}/wallets` with the name
51-
`wally`. We encrypted this using a pre-defined password in the
52-
`wally.pass` file. Then, in step (2), we created one new validator in the
53-
`~/.lighthouse/{network}/validators` directory using `wally` (unlocking it with
54-
`wally.pass`) and storing the passwords to the validators voting key in
55-
`~/.lighthouse/{network}/secrets`.
54+
To create a wallet, use the `lighthouse account wallet` command. For example, if we wish to create a new wallet for the Goerli testnet named `wally` and saves it in `~/.lighthouse/goerli/wallets` with a randomly generated password saved
55+
to `./wallet.pass`:
5656

57-
Thanks to the hierarchical key derivation scheme, we can delete all of the
58-
aforementioned directories and then regenerate them as long as we remembered
59-
the 24-word mnemonic (we don't recommend doing this, though).
57+
```bash
58+
lighthouse --network goerli account wallet create --name wally --password-file wally.pass
59+
```
60+
Using the above command, a wallet will be created in `~/.lighthouse/goerli/wallets` with the name
61+
`wally`. It is encrypted using the password defined in the
62+
`wally.pass` file.
6063

61-
Creating another validator is easy, it's just a matter of repeating step (2).
62-
The wallet keeps track of how many validators it has generated and ensures that
63-
a new validator is generated each time.
64+
During the wallet creation process, a 24-word mnemonic will be displayed. Record the mnemonic because it allows you to recreate the files in the case of data loss.
65+
> Notes:
66+
> - When navigating to the directory `~/.lighthouse/goerli/wallets`, one will not see the wallet name `wally`, but a hexadecimal folder containing the wallet file. However, when interacting with `lighthouse` in the CLI, the name `wally` will be used.
67+
> - The password is not `wally.pass`, it is the _content_ of the
68+
> `wally.pass` file.
69+
> - If `wally.pass` already exists, the wallet password will be set to the content
70+
> of that file.
71+
72+
### Step 2: Create a validator
73+
Validators are fundamentally represented by a BLS keypair. In Lighthouse, we use a wallet to generate these keypairs. Once a wallet exists, the `lighthouse account validator create` command can be used to generate the BLS keypair and all necessary information to submit a validator deposit. With the `wally` wallet created in [Step 1](#step-1-create-a-wallet-and-record-the-mnemonic), we can create a validator with the command:
74+
75+
```bash
76+
lighthouse --network goerli account validator create --wallet-name wally --wallet-password wally.pass --count 1
77+
```
78+
This command will:
79+
80+
- Derive a single new BLS keypair from wallet `wally` in `~/.lighthouse/goerli/wallets`, updating it so that it generates a new key next time.
81+
- Create a new directory `~/.lighthouse/goerli/validators` containing:
82+
- An encrypted keystore file `voting-keystore.json` containing the validator's voting keypair.
83+
- An `eth1_deposit_data.rlp` assuming the default deposit amount (`32 ETH`) which can be submitted to the deposit
84+
contract for the Goerli testnet. Other networks can be set via the
85+
`--network` parameter.
86+
- Create a new directory `~/.lighthouse/goerli/secrets` which stores a password to the validator's voting keypair.
87+
88+
89+
If you want to create another validator in the future, repeat [Step 2](#step-2-create-a-validator). The wallet keeps track of how many validators it has generated and ensures that a new validator is generated each time. The important thing is to keep the 24-word mnemonic safe so that it can be used to generate new validator keys if needed.
6490

6591
## Detail
6692

@@ -76,36 +102,17 @@ There are three important directories in Lighthouse validator key management:
76102
- Defaults to `~/.lighthouse/{network}/validators`
77103
- `secrets/`: since the validator signing keys are "hot", the validator process
78104
needs access to the passwords to decrypt the keystores in the validators
79-
dir. These passwords are stored here.
80-
- Defaults to `~/.lighthouse/{network}/secrets` where `network` is the name of the network passed in the `--network` parameter (default is `mainnet`).
105+
directory. These passwords are stored here.
106+
- Defaults to `~/.lighthouse/{network}/secrets`
107+
108+
where `{network}` is the name of the network passed in the `--network` parameter.
81109

82110
When the validator client boots, it searches the `validators/` for directories
83111
containing voting keystores. When it discovers a keystore, it searches the
84-
`secrets/` dir for a file with the same name as the 0x-prefixed hex
85-
representation of the keystore public key. If it finds this file, it attempts
112+
`secrets/` directory for a file with the same name as the 0x-prefixed validator public key. If it finds this file, it attempts
86113
to decrypt the keystore using the contents of this file as the password. If it
87114
fails, it logs an error and moves onto the next keystore.
88115

89116
The `validators/` and `secrets/` directories are kept separate to allow for
90117
ease-of-backup; you can safely backup `validators/` without worrying about
91118
leaking private key data.
92-
93-
### Withdrawal Keypairs
94-
95-
In Ethereum consensus Phase 0, withdrawal keypairs do not serve any immediate purpose.
96-
However, they become very important _after_ Phase 0: they will provide the
97-
ultimate control of the ETH of withdrawn validators.
98-
99-
This presents an interesting key management scenario: withdrawal keys are very
100-
important, but not right now. Considering this, Lighthouse has adopted a
101-
strategy where **we do not save withdrawal keypairs to disk by default** (it is
102-
opt-in). Instead, we assert that since the withdrawal keys can be regenerated
103-
from a mnemonic, having them lying around on the file-system only presents risk
104-
and complexity.
105-
106-
At the time of writing, we do not expose the commands to regenerate keys from
107-
mnemonics. However, key regeneration is tested on the public Lighthouse
108-
repository and will be exposed prior to mainnet launch.
109-
110-
So, in summary, withdrawal keypairs can be trivially regenerated from the
111-
mnemonic via EIP-2333 so they are not saved to disk like the voting keypairs.

0 commit comments

Comments
 (0)