cerc-io/lighthouse
16
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

Update Lighthouse book Sec 3-6 and FAQ (#4221)

Browse Source 
## 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 <tanck2005@gmail.com>
This commit is contained in:
chonghe 2023-05-05 00:51:56 +00:00
parent b1416c8a43
commit 45835f6a6b
21 changed files with 522 additions and 604 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
book/src/LaTeX/full-withdrawal.tex Normal file
View File

@ -0,0 +1,66 @@
% 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
% 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.
\documentclass[]{article}
\usepackage{pst-all}
\pagestyle{empty}
\begin{document}
\begin{figure}
\psscalebox{1.0 1.0} % Change this value to rescale the drawing.
{
\begin{pspicture}(0,-9.09)(11.8,6.13)
\psframe[linecolor=black, linewidth=0.04, dimen=outer](7.3,6.13)(4.2,5.21)
\rput[bl](4.6,5.51){Voluntary exit}
\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)
\psline[linecolor=black, linewidth=0.04](1.7,3.61)(9.8,3.61)
\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)
\psframe[linecolor=black, linewidth=0.04, dimen=outer](2.9,2.63)(0.8,1.55)
\rput[bl](1.0,1.91){Type 0x00}
\psframe[linecolor=black, linewidth=0.04, dimen=outer](10.7,2.63)(8.6,1.55)
\rput[bl](8.8,1.91){Type 0x01}
\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)
\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)
\psframe[linecolor=black, linewidth=0.04, dimen=outer](3.7,0.61)(0.0,-1.19)
\rput[bl](0.6,-0.19){Funds locked in}
\rput[bl](0.7,-0.79){Beacon chain}
\psframe[linecolor=black, linewidth=0.04, dimen=outer](11.8,0.73)(7.9,-1.39)
\rput[bl](9.0,-0.59){Exit queue}
\rput[bl](8.8,0.01){Varying time}
\rput[bl](8.3,-1.09){32 minutes to weeks}
\rput[bl](9.0,-2.89){Fixed time}
\rput[bl](9.0,-3.49){27.3 hours}
\rput[bl](8.8,-5.49){Varying time}
\rput[bl](8.7,-5.99){validator sweep}
\rput[bl](8.9,-6.59){up to 5 days}
\psframe[linecolor=black, linewidth=0.04, dimen=outer](11.6,-2.19)(8.0,-3.89)
\psframe[linecolor=black, linewidth=0.04, dimen=outer](11.7,-4.79)(7.9,-6.89)
\psframe[linecolor=black, linewidth=0.04, dimen=outer](3.7,-2.49)(0.0,-4.29)
\rput[bl](1.3,-3.29){BLS to}
\rput[bl](0.6,-3.89){execution change}
\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)
\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)
\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)
\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)
\psline[linecolor=black, linewidth=0.04, linestyle=dotted, dotsep=0.10583334cm](3.7,-3.39)(5.8,-3.39)
\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)
\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)
\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)
\psframe[linecolor=black, linewidth=0.04, dimen=outer](11.7,-7.79)(7.9,-9.09)
\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)
\rput[bl](8.1,-8.59){\Large{Full withdrawal}}
\rput[bl](1.8,-2.09){\textit{\Large{anytime}}}
\rput[bl](4.0,-3.19){\textit{\Large{either}}}
\rput[bl](4.2,-3.89){\textit{\Large{one}}}
\end{pspicture}
}
\end{figure}
\end{document}

50
book/src/LaTeX/partial-withdrawal.tex Normal file
View File

@ -0,0 +1,50 @@
% 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
% 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.
\documentclass[]{article}
\usepackage{pst-all}
\pagestyle{empty}
\begin{document}
\begin{figure}
\psscalebox{1.0 1.0} % Change this value to rescale the drawing.
{
\begin{pspicture}(0,-8.09)(10.7,5.53)
\psframe[linecolor=black, linewidth=0.04, dimen=outer](7.14,5.53)(3.6,4.45)
\rput[bl](3.8,4.81){Partial withdrawals}
\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)
\psline[linecolor=black, linewidth=0.04](1.8,2.81)(8.9,2.81)
\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)
\psframe[linecolor=black, linewidth=0.04, dimen=outer](2.7,1.83)(0.6,0.75)
\rput[bl](0.8,1.09){Type 0x00}
\psframe[linecolor=black, linewidth=0.04, dimen=outer](9.8,1.83)(7.7,0.75)
\rput[bl](7.92,1.07){Type 0x01}
\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)
\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)
\psframe[linecolor=black, linewidth=0.04, dimen=outer](3.7,-0.19)(0.0,-1.99)
\rput[bl](0.66,-0.99){Funds locked in}
\rput[bl](0.9,-1.59){Beacon chain}
\psframe[linecolor=black, linewidth=0.04, dimen=outer](10.7,-3.29)(6.8,-5.09)
\rput[bl](7.6,-3.99){validator sweep}
\rput[bl](7.5,-4.69){$\sim$ every 5 days}
\psframe[linecolor=black, linewidth=0.04, dimen=outer](3.7,-3.29)(0.0,-5.09)
\rput[bl](1.3,-4.09){BLS to}
\rput[bl](0.5,-4.69){execution change}
\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)
\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)
\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)
\psframe[linecolor=black, linewidth=0.04, dimen=outer](10.7,-6.29)(6.9,-8.09)
\rput[bl](7.0,-6.99){Balance above 32 ETH}
\rput[bl](7.9,-7.59){withdrawn}
\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)
\rput[bl](1.8,-2.89){\textit{\Large{anytime}}}
\end{pspicture}
}
\end{figure}
\end{document}

9
book/src/SUMMARY.md
View File

@ -11,15 +11,10 @@
* [Update Priorities](./installation-priorities.md) * [Update Priorities](./installation-priorities.md)
* [Run a Node](./run_a_node.md) * [Run a Node](./run_a_node.md)
* [Become a Validator](./mainnet-validator.md) * [Become a Validator](./mainnet-validator.md)
* [Become a Testnet Validator](./testnet-validator.md)
* [Key Management](./key-management.md)
* [Create a wallet](./wallet-create.md)
* [Create a validator](./validator-create.md)
* [Key recovery](./key-recovery.md)
* [Validator Management](./validator-management.md) * [Validator Management](./validator-management.md)
* [Importing from the Staking Launchpad](./validator-import-launchpad.md)
* [Slashing Protection](./slashing-protection.md) * [Slashing Protection](./slashing-protection.md)
* [Voluntary Exits](./voluntary-exit.md) * [Voluntary Exits](./voluntary-exit.md)
* [Partial Withdrawals](./partial-withdrawal.md)
* [Validator Monitoring](./validator-monitoring.md) * [Validator Monitoring](./validator-monitoring.md)
* [Doppelganger Protection](./validator-doppelganger.md) * [Doppelganger Protection](./validator-doppelganger.md)
* [Suggested Fee Recipient](./suggested-fee-recipient.md) * [Suggested Fee Recipient](./suggested-fee-recipient.md)
@ -46,6 +41,8 @@
* [Remote Signing with Web3Signer](./validator-web3signer.md) * [Remote Signing with Web3Signer](./validator-web3signer.md)
* [Database Configuration](./advanced_database.md) * [Database Configuration](./advanced_database.md)
* [Database Migrations](./database-migrations.md) * [Database Migrations](./database-migrations.md)
* [Key Management](./key-management.md)
* [Key Recovery](./key-recovery.md)
* [Advanced Networking](./advanced_networking.md) * [Advanced Networking](./advanced_networking.md)
* [Running a Slasher](./slasher.md) * [Running a Slasher](./slasher.md)
* [Redundancy](./redundancy.md) * [Redundancy](./redundancy.md)

BIN
book/src/imgs/full-withdrawal.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 257 KiB

BIN
book/src/imgs/partial-withdrawal.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 172 KiB

8
book/src/installation.md
View File

@ -29,6 +29,10 @@ After [The Merge](https://ethereum.org/en/roadmap/merge/) on 15<sup>th</sup> Sep
* CPU: Quad-core AMD Ryzen, Intel Broadwell, ARMv8 or newer * CPU: Quad-core AMD Ryzen, Intel Broadwell, ARMv8 or newer
* Memory: 16 GB RAM or more * Memory: 32 GB RAM*
* Storage: 2 TB solid state storage * Storage: 2 TB solid state drive
* Network: 100 Mb/s download, 20 Mb/s upload broadband connection * Network: 100 Mb/s download, 20 Mb/s upload broadband connection
> *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.
Last update: April 2023

105
book/src/key-management.md
View File

@ -3,7 +3,7 @@
[launchpad]: https://launchpad.ethereum.org/ [launchpad]: https://launchpad.ethereum.org/
> >
> **Note: we recommend using the [Staking launchpad][launchpad] to create validators.** > **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.**
Lighthouse uses a _hierarchical_ key management system for producing validator Lighthouse uses a _hierarchical_ key management system for producing validator
keys. It is hierarchical because each validator key can be _derived_ from a keys. It is hierarchical because each validator key can be _derived_ from a
@ -30,37 +30,63 @@ We defined some terms in the context of validator key management:
keypair. keypair.
- Defined in EIP-2335. - Defined in EIP-2335.
- **Voting Keypair**: a BLS public and private keypair which is used for - **Voting Keypair**: a BLS public and private keypair which is used for
signing blocks, attestations and other messages on regular intervals, signing blocks, attestations and other messages on regular intervals in the beacon chain.
whilst staking in Phase 0.
- **Withdrawal Keypair**: a BLS public and private keypair which will be - **Withdrawal Keypair**: a BLS public and private keypair which will be
required _after_ Phase 0 to manage ETH once a validator has exited. required _after_ Phase 0 to manage ETH once a validator has exited.
## Overview ## Create a validator
There are 2 steps involved to create a validator key using Lighthouse:
1. [Create a wallet](#step-1-create-a-wallet-and-record-the-mnemonic)
1. [Create a validator](#step-2-create-a-validator)
The key management system in Lighthouse involves moving down the above list of The following example demonstrates how to create a single validator key.
items, starting at one easy-to-backup mnemonic and ending with multiple
keypairs. Creating a single validator looks like this:
1. Create a **wallet** and record the **mnemonic**: ### Step 1: Create a wallet and record the mnemonic
- `lighthouse --network prater account wallet create --name wally --password-file wally.pass` A wallet allows for generating practically unlimited validators from an
1. Create the voting and withdrawal **keystores** for one validator: easy-to-remember 24-word string (a mnemonic). As long as that mnemonic is
- `lighthouse --network prater account validator create --wallet-name wally --wallet-password wally.pass --count 1` backed up, all validator keys can be trivially re-generated.
Whilst the wallet stores the mnemonic, it does not store it in plain-text: the
mnemonic is encrypted with a password. It is the responsibility of the user to
define a strong password. The password is only required for interacting with
the wallet, it is not required for recovering keys from a mnemonic.
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
to `./wallet.pass`:
```bash
lighthouse --network goerli account wallet create --name wally --password-file wally.pass
```
Using the above command, a wallet will be created in `~/.lighthouse/goerli/wallets` with the name
`wally`. It is encrypted using the password defined in the
`wally.pass` file.
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.
> Notes:
> - 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.
> - The password is not `wally.pass`, it is the _content_ of the
> `wally.pass` file.
> - If `wally.pass` already exists, the wallet password will be set to the content
> of that file.
### Step 2: Create a validator
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:
```bash
lighthouse --network goerli account validator create --wallet-name wally --wallet-password wally.pass --count 1
```
This command will:
- Derive a single new BLS keypair from wallet `wally` in `~/.lighthouse/goerli/wallets`, updating it so that it generates a new key next time.
- Create a new directory `~/.lighthouse/goerli/validators` containing:
- An encrypted keystore file `voting-keystore.json` containing the validator's voting keypair.
- An `eth1_deposit_data.rlp` assuming the default deposit amount (`32 ETH`) which can be submitted to the deposit
contract for the Goerli testnet. Other networks can be set via the
`--network` parameter.
- Create a new directory `~/.lighthouse/goerli/secrets` which stores a password to the validator's voting keypair.
In step (1), we created a wallet in `~/.lighthouse/{network}/wallets` with the name 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.
`wally`. We encrypted this using a pre-defined password in the
`wally.pass` file. Then, in step (2), we created one new validator in the
`~/.lighthouse/{network}/validators` directory using `wally` (unlocking it with
`wally.pass`) and storing the passwords to the validators voting key in
`~/.lighthouse/{network}/secrets`.
Thanks to the hierarchical key derivation scheme, we can delete all of the
aforementioned directories and then regenerate them as long as we remembered
the 24-word mnemonic (we don't recommend doing this, though).
Creating another validator is easy, it's just a matter of repeating step (2).
The wallet keeps track of how many validators it has generated and ensures that
a new validator is generated each time.
## Detail ## Detail
@ -76,36 +102,17 @@ There are three important directories in Lighthouse validator key management:
- Defaults to `~/.lighthouse/{network}/validators` - Defaults to `~/.lighthouse/{network}/validators`
- `secrets/`: since the validator signing keys are "hot", the validator process - `secrets/`: since the validator signing keys are "hot", the validator process
needs access to the passwords to decrypt the keystores in the validators needs access to the passwords to decrypt the keystores in the validators
dir. These passwords are stored here. directory. These passwords are stored here.
- Defaults to `~/.lighthouse/{network}/secrets` where `network` is the name of the network passed in the `--network` parameter (default is `mainnet`). - Defaults to `~/.lighthouse/{network}/secrets`
where `{network}` is the name of the network passed in the `--network` parameter.
When the validator client boots, it searches the `validators/` for directories When the validator client boots, it searches the `validators/` for directories
containing voting keystores. When it discovers a keystore, it searches the containing voting keystores. When it discovers a keystore, it searches the
`secrets/` dir for a file with the same name as the 0x-prefixed hex `secrets/` directory for a file with the same name as the 0x-prefixed validator public key. If it finds this file, it attempts
representation of the keystore public key. If it finds this file, it attempts
to decrypt the keystore using the contents of this file as the password. If it to decrypt the keystore using the contents of this file as the password. If it
fails, it logs an error and moves onto the next keystore. fails, it logs an error and moves onto the next keystore.
The `validators/` and `secrets/` directories are kept separate to allow for The `validators/` and `secrets/` directories are kept separate to allow for
ease-of-backup; you can safely backup `validators/` without worrying about ease-of-backup; you can safely backup `validators/` without worrying about
leaking private key data. leaking private key data.
### Withdrawal Keypairs
In Ethereum consensus Phase 0, withdrawal keypairs do not serve any immediate purpose.
However, they become very important _after_ Phase 0: they will provide the
ultimate control of the ETH of withdrawn validators.
This presents an interesting key management scenario: withdrawal keys are very
important, but not right now. Considering this, Lighthouse has adopted a
strategy where **we do not save withdrawal keypairs to disk by default** (it is
opt-in). Instead, we assert that since the withdrawal keys can be regenerated
from a mnemonic, having them lying around on the file-system only presents risk
and complexity.
At the time of writing, we do not expose the commands to regenerate keys from
mnemonics. However, key regeneration is tested on the public Lighthouse
repository and will be exposed prior to mainnet launch.
So, in summary, withdrawal keypairs can be trivially regenerated from the
mnemonic via EIP-2333 so they are not saved to disk like the voting keypairs.

6
book/src/key-recovery.md
View File

@ -1,8 +1,8 @@
# Key recovery # Key Recovery
Generally, validator keystore files are generated alongside a *mnemonic*. If Generally, validator keystore files are generated alongside a *mnemonic*. If
the keystore and/or the keystore password are lost this mnemonic can the keystore and/or the keystore password are lost, this mnemonic can
regenerate a new, equivalent keystore with a new password. regenerate a new, equivalent keystore with a new password.
There are two ways to recover keys using the `lighthouse` CLI: There are two ways to recover keys using the `lighthouse` CLI:
@ -48,7 +48,7 @@ which contains all the information necessary to run a validator using the
`lighthouse vc` command. The password to this new keystore will be placed in `lighthouse vc` command. The password to this new keystore will be placed in
the `--secrets-dir` (default `~/.lighthouse/{network}/secrets`). the `--secrets-dir` (default `~/.lighthouse/{network}/secrets`).
where `network` is the name of the consensus layer network passed in the `--network` parameter (default is `mainnet`). where `{network}` is the name of the consensus layer network passed in the `--network` parameter (default is `mainnet`).
## Recover a EIP-2386 wallet ## Recover a EIP-2386 wallet

294
book/src/mainnet-validator.md
View File

@ -12,25 +12,13 @@ Becoming an Ethereum consensus validator is rewarding, but it's not for the fain
familiar with the rules of staking (e.g., rewards, penalties, etc.) and also configuring and familiar with the rules of staking (e.g., rewards, penalties, etc.) and also configuring and
managing servers. You'll also need at least 32 ETH! managing servers. You'll also need at least 32 ETH!
For those with an understanding of Ethereum consensus and server maintenance, you'll find that running Lighthouse Being educated is critical to a validator's success. Before submitting your mainnet deposit, we recommend:
is easy. Install it, start it, monitor it and keep it updated. You shouldn't need to interact
with it on a day-to-day basis.
Being educated is critical to validator success. Before submitting your mainnet deposit, we - Thoroughly exploring the [Staking Launchpad][launchpad] website, try running through the deposit process using a testnet launchpad such as the [Goerli staking launchpad](https://goerli.launchpad.ethereum.org/en/).
recommend:
- Thoroughly exploring the [Staking Launchpad][launchpad] website
- Try running through the deposit process *without* actually submitting a deposit.
- Reading through this documentation, especially the [Slashing Protection][slashing] section.
- Running a [testnet validator][testnet-validator]. - Running a [testnet validator][testnet-validator].
- Reading through this documentation, especially the [Slashing Protection][slashing] section.
- Performing a web search and doing your own research. - Performing a web search and doing your own research.
By far, the best technical learning experience is to run a [Testnet Validator][testnet-validator].
You can get hands-on experience with all the tools and it's a great way to test your staking
hardware. We recommend *all* mainnet validators to run a testnet validator initially; 32 ETH is a
significant outlay and joining a testnet is a great way to "try before you buy".
Remember, if you get stuck you can always reach out on our [Discord][discord].
> >
> **Please note**: the Lighthouse team does not take any responsibility for losses or damages > **Please note**: the Lighthouse team does not take any responsibility for losses or damages
@ -40,116 +28,187 @@ Remember, if you get stuck you can always reach out on our [Discord][discord].
> due to the actions of other actors on the consensus layer or software bugs. See the > due to the actions of other actors on the consensus layer or software bugs. See the
> [software license][license] for more detail on liability. > [software license][license] for more detail on liability.
## Using Lighthouse for Mainnet
When using Lighthouse, the `--network` flag selects a network. E.g., ## Become a validator
- `lighthouse` (no flag): Mainnet. There are five primary steps to become a validator:
- `lighthouse --network mainnet`: Mainnet.
- `lighthouse --network prater`: Prater (testnet).
Using the correct `--network` flag is very important; using the wrong flag can 1. [Create validator keys](#step-1-create-validator-keys)
result in penalties, slashings or lost deposits. As a rule of thumb, always 1. [Start an execution client and Lighthouse beacon node](#step-2-start-an-execution-client-and-lighthouse-beacon-node)
provide a `--network` flag instead of relying on the default. 1. [Import validator keys into Lighthouse](#step-3-import-validator-keys-to-lighthouse)
1. [Start Lighthouse validator client](#step-4-start-lighthouse-validator-client)
1. [Submit deposit](#step-5-submit-deposit-32eth-per-validator)
## Joining a Testnet > **Important note**: The guide below contains both mainnet and testnet instructions. We highly recommend *all* users to **run a testnet validator** prior to staking mainnet ETH. By far, the best technical learning experience is to run a testnet validator. You can get hands-on experience with all the tools and it's a great way to test your staking
hardware. 32 ETH is a significant outlay and joining a testnet is a great way to "try before you buy".
There are five primary steps to become a testnet validator: <!--To join a testnet, for example the Goerli testnet, select `Goerli` when you are prompted to select the network in the `staking-deposit-cli` in Step 1, replace `--network mainnet` with `--network goerli` in Steps 2-4, and visit [Goerli staking launchpad](https://goerli.launchpad.ethereum.org/en/) to deposit testnet ETH in Step 5.-->
1. Create validator keys and submit deposits.
1. Start an execution client.
1. Install Lighthouse.
1. Import the validator keys into Lighthouse.
1. Start Lighthouse.
1. Leave Lighthouse running.
Each of these primary steps has several intermediate steps, so we recommend > **Never use real ETH to join a testnet!** Testnet such as the Goerli testnet uses Goerli ETH which is worthless. This allows experimentation without real-world costs.
setting aside one or two hours for this process.
### Step 1. Create validator keys ### Step 1. Create validator keys
The Ethereum Foundation provides a "Staking Launchpad" for creating validator keypairs and submitting The Ethereum Foundation provides the [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli/releases) for creating validator keys. Download and run the `staking-deposit-cli` with the command:
deposits:
- [Staking Launchpad][launchpad]
Please follow the steps on the launch pad site to generate validator keys and submit deposits. Make
sure you select "Lighthouse" as your client.
Move to the next step once you have completed the steps on the launch pad,
including generating keys via the Python CLI and submitting gETH/ETH deposits.
### Step 2. Start an execution client
Since the consensus chain relies upon the execution chain for validator on-boarding, all consensus validators must have a
connection to an execution client.
We provide instructions for using Geth, but you could use any client that implements the JSON RPC
via HTTP. A fast-synced node is sufficient.
#### Installing Geth
If you're using a Mac, follow the instructions [listed
here](https://github.com/ethereum/go-ethereum/wiki/Installation-Instructions-for-Mac) to install
geth. Otherwise [see here](https://github.com/ethereum/go-ethereum/wiki/Installing-Geth).
#### Starting Geth
Once you have geth installed, use this command to start your execution node:
```bash ```bash
geth --http ./deposit new-mnemonic
```
and follow the instructions to generate the keys. When prompted for a network, select `mainnet` if you want to run a mainnet validator, or select `goerli` if you want to run a Goerli testnet validator. A new mnemonic will be generated in the process.
> **Important note:** A mnemonic (or seed phrase) is a 24-word string randomly generated in the process. It is highly recommended to write down the mnemonic and keep it safe offline. It is important to ensure that the mnemonic is never stored in any digital form (computers, mobile phones, etc) connected to the internet. Please also make one or more backups of the mnemonic to ensure your ETH is not lost in the case of data loss. It is very important to keep your mnemonic private as it represents the ultimate control of your ETH.
Upon completing this step, the files `deposit_data-*.json` and `keystore-m_*.json` will be created. The keys that are generated from staking-deposit-cli can be easily loaded into a Lighthouse validator client (`lighthouse vc`) in [Step 3](#step-3-import-validator-keys-to-lighthouse). In fact, both of these programs are designed to work with each other.
> Lighthouse also supports creating validator keys, see [Key management](./key-management.md) for more info.
### Step 2. Start an execution client and Lighthouse beacon node
Start an execution client and Lighthouse beacon node according to the [Run a Node](./run_a_node.md) guide. Make sure that both execution client and consensus client are synced.
### Step 3. Import validator keys to Lighthouse
In [Step 1](#step-1-create-validator-keys), the staking-deposit-cli will generate the validator keys into a `validator_keys` directory. Let's assume that
this directory is `$HOME/staking-deposit-cli/validator_keys`. Using the default `validators` directory in Lighthouse (`~/.lighthouse/mainnet/validators`), run the following command to import validator keys:
Mainnet:
```bash
lighthouse --network mainnet account validator import --directory $HOME/staking-deposit-cli/validator_keys
``` ```
### Step 3. Install Lighthouse Goerli testnet:
*Note: Lighthouse only supports Windows via WSL.*
Follow the [Lighthouse Installation Instructions](./installation.md) to install
Lighthouse from one of the available options.
Proceed to the next step once you've successfully installed Lighthouse and viewed
its `--version` info.
> Note: Some of the instructions vary when using Docker, ensure you follow the
> appropriate sections later in this guide.
### Step 4. Import validator keys to Lighthouse
When Lighthouse is installed, follow the [Importing from the Ethereum Staking Launch
pad](./validator-import-launchpad.md) instructions so the validator client can
perform your validator duties.
Proceed to the next step once you've successfully imported all validators.
### Step 5. Start Lighthouse
For staking, one needs to run two Lighthouse processes:
- `lighthouse bn`: the "beacon node" which connects to the P2P network and
verifies blocks.
- `lighthouse vc`: the "validator client" which manages validators, using data
obtained from the beacon node via a HTTP API.
Starting these processes is different for binary and docker users:
#### Binary users
Those using the pre- or custom-built binaries can start the two processes with:
```bash ```bash
lighthouse --network mainnet bn --staking lighthouse --network goerli account validator import --directory $HOME/staking-deposit-cli/validator_keys
``` ```
```bash > Note: The user must specify the consensus client network that they are importing the keys by using the `--network` flag.
lighthouse --network mainnet vc
> Note: If the validator_keys directory is in a different location, modify the path accordingly.
> Note: `~/.lighthouse/mainnet` is the default directory which contains the keys and database. To specify a custom directory, see [Custom Directories][advanced-datadir].
> Docker users should use the command from the [Docker](#docker-users) documentation.
The user will be prompted for a password for each keystore discovered:
```
Keystore found at "/home/{username}/staking-deposit-cli/validator_keys/keystore-m_12381_3600_0_0_0-1595406747.json":
- Public key: 0xa5e8702533f6d66422e042a0bf3471ab9b302ce115633fa6fdc5643f804b6b4f1c33baf95f125ec21969a3b1e0dd9e56
- UUID: 8ea4cf99-8719-43c5-9eda-e97b8a4e074f
If you enter the password it will be stored as plain text in validator_definitions.yml so that it is not required each time the validator client starts.
Enter the keystore password, or press enter to omit it:
``` ```
> Note: `~/.lighthouse/mainnet` is the default directory which contains the keys and databases. The user can choose whether or not they'd like to store the validator password
> To specify a custom dir, see [Custom Directories][advanced-datadir]. in the [`validator_definitions.yml`](./validator-management.md) file. If the
password is *not* stored here, the validator client (`lighthouse vc`)
application will ask for the password each time it starts. This might be nice
for some users from a security perspective (i.e., if it is a shared computer),
however it means that if the validator client restarts, the user will be subject
to offline penalties until they can enter the password. If the user trusts the
computer that is running the validator client and they are seeking maximum
validator rewards, we recommend entering a password at this point.
#### Docker users Once the process is done the user will see:
```
Successfully imported keystore.
Successfully updated validator_definitions.yml.
Successfully imported 1 validators (0 skipped).
WARNING: DO NOT USE THE ORIGINAL KEYSTORES TO VALIDATE WITH ANOTHER CLIENT, OR YOU WILL GET SLASHED.
```
Once you see the above message, you have successfully imported the validator keys. You can now proceed to the next step to start the validator client.
### Step 4. Start Lighthouse validator client
After the keys are imported, the user can start performing their validator duties
by starting the Lighthouse validator client `lighthouse vc`:
Mainnet:
```bash
lighthouse vc --network mainnet --suggested-fee-recipient YourFeeRecipientAddress
```
Goerli testnet:
```bash
lighthouse vc --network goerli --suggested-fee-recipient YourFeeRecipientAddress
```
The `validator client` manages validators using data obtained from the beacon node via a HTTP API. You are highly recommended to enter a fee-recipient by changing `YourFeeRecipientAddress` to an Ethereum address under your control.
When `lighthouse vc` starts, check that the validator public key appears
as a `voting_pubkey` as shown below:
```
INFO Enabled validator voting_pubkey: 0xa5e8702533f6d66422e042a0bf3471ab9b302ce115633fa6fdc5643f804b6b4f1c33baf95f125ec21969a3b1e0dd9e56
```
Once this log appears (and there are no errors) the `lighthouse vc` application
will ensure that the validator starts performing its duties and being rewarded
by the protocol.
### Step 5: Submit deposit (32ETH per validator)
After you have successfully run and synced the execution client, beacon node and validator client, you can now proceed to submit the deposit. Go to the mainnet [Staking launchpad](https://launchpad.ethereum.org/en/) (or [Goerli staking launchpad](https://goerli.launchpad.ethereum.org/en/) for testnet validator) and carefully go through the steps to becoming a validator. Once you are ready, you can submit the deposit by sending 32ETH per validator to the deposit contract. Upload the `deposit_data-*.json` file generated in [Step 1](#step-1-create-validator-keys) to the Staking launchpad.
> **Important note:** Double check that the deposit contract for mainnet is `0x00000000219ab540356cBB839Cbe05303d7705Fa` before you confirm the transaction.
Once the deposit transaction is confirmed, it will take a minimum of ~16 hours to a few days/weeks for the beacon chain to process and activate your validator, depending on the queue. Refer to our [FAQ - Why does it take so long for a validator to be activated](./faq.md#why-does-it-take-so-long-for-a-validator-to-be-activated) for more info.
Once your validator is activated, the validator client will start to publish attestations each epoch:
```
Dec 03 08:49:40.053 INFO Successfully published attestation slot: 98, committee_index: 0, head_block: 0xa208…7fd5,
```
If you propose a block, the log will look like:
```
Dec 03 08:49:36.225 INFO Successfully published block slot: 98, attestations: 2, deposits: 0, service: block
```
Congratulations! Your validator is now performing its duties and you will receive rewards for securing the Ethereum network.
### What is next?
After the validator is running and performing its duties, it is important to keep the validator online to continue accumulating rewards. However, there could be problems with the computer, the internet or other factors that cause the validator to be offline. For this, it is best to subscribe to notifications, e.g., via [beaconcha.in](https://beaconcha.in/) which will send notifications about missed attestations and/or proposals. You will be notified about the validator's offline status and will be able to react promptly.
The next important thing is to stay up to date with updates to Lighthouse and the execution client. Updates are released from time to time, typically once or twice a month. For Lighthouse updates, you can subscribe to notifications on [Github](https://github.com/sigp/lighthouse) by clicking on `Watch`. If you only want to receive notification on new releases, select `Custom`, then `Releases`. You could also join [Lighthouse Discord](https://discord.gg/cyAszAh) where we will make an announcement when there is a new release.
You may also want to try out [Siren](./lighthouse-ui.md), a UI developed by Lighthouse to monitor validator performance.
Once you are familiar with running a validator and server maintenance, you'll find that running Lighthouse is easy. Install it, start it, monitor it and keep it updated. You shouldn't need to interact with it on a day-to-day basis. Happy staking!
## Docker users
### Import validator keys
The `import` command is a little more complex for Docker users, but the example
in this document can be substituted with:
```bash
docker run -it \
-v $HOME/.lighthouse:/root/.lighthouse \
-v $(pwd)/validator_keys:/root/validator_keys \
sigp/lighthouse \
lighthouse --network mainnet account validator import --directory /root/validator_keys
```
Here we use two `-v` volumes to attach:
- `~/.lighthouse` on the host to `/root/.lighthouse` in the Docker container.
- The `validator_keys` directory in the present working directory of the host
to the `/root/validator_keys` directory of the Docker container.
### Start Lighthouse beacon node and validator client
Those using Docker images can start the processes with: Those using Docker images can start the processes with:
```bash ```bash
@ -167,29 +226,8 @@ $ docker run \
lighthouse --network mainnet vc lighthouse --network mainnet vc
``` ```
### Step 6. Leave Lighthouse running
Leave your beacon node and validator client running and you'll see logs as the If you get stuck you can always reach out on our [Discord][discord] or [create an
beacon node stays synced with the network while the validator client produces
blocks and attestations.
It will take 4-8+ hours for the beacon chain to process and activate your
validator, however you'll know you're active when the validator client starts
successfully publishing attestations each epoch:
```
Dec 03 08:49:40.053 INFO Successfully published attestation slot: 98, committee_index: 0, head_block: 0xa208…7fd5,
```
Although you'll produce an attestation each epoch, it's less common to produce a
block. Watch for the block production logs too:
```
Dec 03 08:49:36.225 INFO Successfully published block slot: 98, attestations: 2, deposits: 0, service: block
```
If you see any `ERRO` (error) logs, please reach out on
[Discord](https://discord.gg/cyAszAh) or [create an
issue](https://github.com/sigp/lighthouse/issues/new). issue](https://github.com/sigp/lighthouse/issues/new).
Happy staking!

23
book/src/partial-withdrawal.md Normal file
View File

@ -0,0 +1,23 @@
# Partial Withdrawals
After the [Capella](https://ethereum.org/en/history/#capella) upgrade on 12<sup>th</sup> April 2023:
- if a validator has a withdrawal credential type `0x00`, the rewards will continue to accumulate and will be locked in the beacon chain.
- if a validator has a withdrawal credential type `0x01`, any rewards above 32ETH will be periodically withdrawn to the withdrawal address. This is also known as the "validator sweep", i.e., once the "validator sweep" reaches your validator's index, your rewards will be withdrawn to the withdrawal address. At the time of writing, with 560,000+ validators on the Ethereum mainnet, you shall expect to receive the rewards approximately every 5 days.
### FAQ
1. How to know if I have the withdrawal credentials type `0x00` or `0x01`?
Refer [here](./voluntary-exit.md#1-how-to-know-if-i-have-the-withdrawal-credentials-type-0x01).
2. My validator has withdrawal credentials type `0x00`, is there a deadline to update my withdrawal credentials?
No. You can update your withdrawal credentials **anytime**. The catch is that as long as you do not update your withdrawal credentials, your rewards in the beacon chain will continue to be locked in the beacon chain. Only after you update the withdrawal credentials, will the rewards be withdrawn to the withdrawal address.
3. Do I have to do anything to get my rewards after I update the withdrawal credentials to type `0x01`?
No. The "validator sweep" occurs automatically and you can expect to receive the rewards every few days.
Figure below summarizes partial withdrawals.
![partial](./imgs/partial-withdrawal.png)

131
book/src/run_a_node.md
View File

@ -1,77 +1,43 @@
# Run a Node # Run a Node
This document provides detail for users who want to run a Lighthouse beacon node. This section provides the detail for users who want to run a Lighthouse beacon node.
You should be finished with one [Installation](./installation.md) method of your choice to continue with the following steps: You should be finished with one [Installation](./installation.md) method of your choice to continue with the following steps:
1. Set up an [execution node](#step-1-set-up-an-execution-node); 1. Create a [JWT secret file](#step-1-create-a-jwt-secret-file)
1. Enable [checkpoint sync](#step-2-choose-a-checkpoint-sync-provider); 1. Set up an [execution node](#step-2-set-up-an-execution-node);
1. Run [Lighthouse](#step-3-run-lighthouse); 1. Set up a [beacon node](#step-3-set-up-a-beacon-node-using-lighthouse);
1. [Check logs](#step-4-check-logs); and 1. [Check logs for sync status](#step-4-check-logs);
1. [Further readings](#step-5-further-readings).
Checkpoint sync is *optional*; however, we recommend it since it is substantially faster
than syncing from genesis while still providing the same functionality.
## Step 1: Set up an execution node
The Lighthouse beacon node *must* connect to an execution engine in order to validate the transactions ## Step 1: Create a JWT secret file
present in blocks. Two flags are used to configure this connection: A JWT secret file is used to secure the communication between the execution client and the consensus client. In this step, we will create a JWT secret file which will be used in later steps.
- `--execution-endpoint`: the *URL* of the execution engine API. Often this will be ```bash
`http://localhost:8551`. sudo mkdir -p /secrets
- `--execution-jwt`: the *path* to the file containing the JWT secret shared by Lighthouse and the openssl rand -hex 32 | tr -d "\n" | sudo tee /secrets/jwt.hex
execution engine. This is a mandatory form of authentication that ensures that Lighthouse ```
has authority to control the execution engine.
Each execution engine has its own flags for configuring the engine API and JWT. ## Step 2: Set up an execution node
Please consult the relevant page of your execution engine for the required flags:
- [Geth: Connecting to Consensus Clients](https://geth.ethereum.org/docs/getting-started/consensus-clients) The Lighthouse beacon node *must* connect to an execution engine in order to validate the transactions present in blocks. The execution engine connection must be *exclusive*, i.e. you must have one execution node
- [Nethermind: Running Nethermind & CL](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge) per beacon node. The reason for this is that the beacon node _controls_ the execution node. Select an execution client from the list below and run it:
- [Besu: Connect to Mainnet](https://besu.hyperledger.org/en/stable/public-networks/get-started/connect/mainnet/)
- [Erigon: Beacon Chain (Consensus Layer)](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer)
The execution engine connection must be *exclusive*, i.e. you must have one execution node
per beacon node. The reason for this is that the beacon node _controls_ the execution node.
## Step 2: Choose a checkpoint sync provider - [Nethermind](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge)
- [Besu](https://besu.hyperledger.org/en/stable/public-networks/get-started/connect/mainnet/)
- [Erigon](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer)
- [Geth](https://geth.ethereum.org/docs/getting-started/consensus-clients)
Lighthouse supports fast sync from a recent finalized checkpoint.
The checkpoint sync is done using a [public endpoint](#use-a-community-checkpoint-sync-endpoint)
provided by the Ethereum community.
In [step 3](#step-3-run-lighthouse), when running Lighthouse, > Note: Each execution engine has its own flags for configuring the engine API and JWT secret to connect to a beacon node. Please consult the relevant page of your execution engine as above for the required flags.
we will enable checkpoint sync by providing the URL to the `--checkpoint-sync-url` flag.
### Use a community checkpoint sync endpoint
The Ethereum community provides various [public endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/) for you to choose from for your initial checkpoint state. Select one for your network and use it as the URL. Once the execution client is up, just let it continue running. The execution client will start syncing when it connects to a beacon node. Depending on the execution client and computer hardware specifications, syncing can take from a few hours to a few days. You can safely proceed to Step 3 to set up a beacon node while the execution client is still syncing.
For example, the URL for Sigma Prime's checkpoint sync server for mainnet is `https://mainnet.checkpoint.sigp.io`, ## Step 3: Set up a beacon node using Lighthouse
which we will use in [step 3](#step-3-run-lighthouse).
## Step 3: Run Lighthouse In this step, we will set up a beacon node. Use the following command to start a beacon node that connects to the execution node:
To run Lighthouse, we use the three flags from the steps above:
- `--execution-endpoint`;
- `--execution-jwt`; and
- `--checkpoint-sync-url`.
Additionally, we run Lighthouse with the `--network` flag, which selects a network:
- `lighthouse` (no flag): Mainnet.
- `lighthouse --network mainnet`: Mainnet.
- `lighthouse --network goerli`: Goerli (testnet).
Using the correct `--network` flag is very important; using the wrong flag can
result in penalties, slashings or lost deposits. As a rule of thumb, *always*
provide a `--network` flag instead of relying on the default.
For the testnets we support [Goerli](https://goerli.net/) (`--network goerli`),
[Sepolia](https://sepolia.dev/) (`--network sepolia`), and [Gnosis chain](https://www.gnosis.io/) (`--network gnosis`).
Minor modifications depend on if you want to run your node while [staking](#staking) or [non-staking](#non-staking).
In the following, we will provide examples of what a Lighthouse setup could look like.
### Staking ### Staking
@ -84,9 +50,30 @@ lighthouse bn \
--http --http
``` ```
A Lighthouse beacon node can be configured to expose an HTTP server by supplying the `--http` flag. > Note: If you download the binary file, you need to navigate to the directory of the binary file to run the above command.
The default listen address is `127.0.0.1:5052`.
The HTTP API is required for the beacon node to accept connections from the *validator client*, which manages keys. Notable flags:
- `--network` flag, which selects a network:
- `lighthouse` (no flag): Mainnet.
- `lighthouse --network mainnet`: Mainnet.
- `lighthouse --network goerli`: Goerli (testnet).
- `lighthouse --network sepolia`: Sepolia (testnet).
- `lighthouse --network gnosis`: Gnosis chain
> Note: Using the correct `--network` flag is very important; using the wrong flag can
result in penalties, slashings or lost deposits. As a rule of thumb, *always*
provide a `--network` flag instead of relying on the default.
- `--execution-endpoint`: the URL of the execution engine API. If the execution engine is running on the same computer with the default port, this will be
`http://localhost:8551`.
- `--execution-jwt`: the path to the JWT secret file shared by Lighthouse and the
execution engine. This is a mandatory form of authentication which ensures that Lighthouse has the authority to control the execution engine.
- `--checkpoint-sync-url`: Lighthouse supports fast sync from a recent finalized checkpoint. Checkpoint sync is *optional*; however, we **highly recommend** it since it is substantially faster than syncing from genesis while still providing the same functionality. The checkpoint sync is done using [public endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/) provided by the Ethereum community. For example, in the above command, we use the URL for Sigma Prime's checkpoint sync server for mainnet `https://mainnet.checkpoint.sigp.io`.
- `--http`: to expose an HTTP server of the beacon chain. The default listening address is `http://localhost:5052`. The HTTP API is required for the beacon node to accept connections from the *validator client*, which manages keys.
If you intend to run the beacon node without running the validator client (e.g., for non-staking purposes such as supporting the network), you can modify the above command so that the beacon node is configured for non-staking purposes:
### Non-staking ### Non-staking
@ -99,17 +86,19 @@ lighthouse bn \
--disable-deposit-contract-sync --disable-deposit-contract-sync
``` ```
Since we are not staking, we can use the `--disable-deposit-contract-sync` flag. Since we are not staking, we can use the `--disable-deposit-contract-sync` flag to disable syncing of deposit logs from the execution node.
---
Once Lighthouse runs, we can monitor the logs to see if it is syncing correctly. Once Lighthouse runs, we can monitor the logs to see if it is syncing correctly.
## Step 4: Check logs
## Step 4: Check logs for sync status
Several logs help you identify if Lighthouse is running correctly. Several logs help you identify if Lighthouse is running correctly.
### Logs - Checkpoint sync ### Logs - Checkpoint sync
Lighthouse will print a message to indicate that checkpoint sync is being used: If you run Lighthouse with the flag `--checkpoint-sync-url`, Lighthouse will print a message to indicate that checkpoint sync is being used:
``` ```
INFO Starting checkpoint sync remote_url: http://remote-bn:8000/, service: beacon INFO Starting checkpoint sync remote_url: http://remote-bn:8000/, service: beacon
@ -122,16 +111,17 @@ loaded from the remote beacon node:
INFO Loaded checkpoint block and state state_root: 0xe8252c68784a8d5cc7e5429b0e95747032dd1dcee0d1dc9bdaf6380bf90bc8a6, block_root: 0x5508a20147299b1a7fe9dbea1a8b3bf979f74c52e7242039bd77cbff62c0695a, slot: 2034720, service: beacon INFO Loaded checkpoint block and state state_root: 0xe8252c68784a8d5cc7e5429b0e95747032dd1dcee0d1dc9bdaf6380bf90bc8a6, block_root: 0x5508a20147299b1a7fe9dbea1a8b3bf979f74c52e7242039bd77cbff62c0695a, slot: 2034720, service: beacon
``` ```
Once the checkpoint is loaded Lighthouse will sync forwards to the head of the chain. Once the checkpoint is loaded, Lighthouse will sync forwards to the head of the chain.
If a validator client is connected to the node then it will be able to start completing its duties If a validator client is connected to the beacon node it will be able to start its duties as soon as forwards sync completes, which typically takes 1-2 minutes.
as soon as forwards sync completes.
> Note: If you have an existing Lighthouse database, you will need to delete the database by using the `--purge-db` flag or manually delete the database with `sudo rm -r /path_to_database/beacon`. If you do use a `--purge-db` flag, once checkpoint sync is complete, you can remove the flag upon a restart.
> **Security Note**: You should cross-reference the `block_root` and `slot` of the loaded checkpoint > **Security Note**: You should cross-reference the `block_root` and `slot` of the loaded checkpoint
> against a trusted source like another [public endpoint](https://eth-clients.github.io/checkpoint-sync-endpoints/), > against a trusted source like another [public endpoint](https://eth-clients.github.io/checkpoint-sync-endpoints/),
> a friend's node, or a block explorer. > a friend's node, or a block explorer.
#### Backfilling Blocks ### Backfilling Blocks
Once forwards sync completes, Lighthouse will commence a "backfill sync" to download the blocks Once forwards sync completes, Lighthouse will commence a "backfill sync" to download the blocks
from the checkpoint back to genesis. from the checkpoint back to genesis.
@ -156,16 +146,17 @@ as `verified` indicating that they have been processed successfully by the execu
INFO Synced, slot: 3690668, block: 0x1244…cb92, epoch: 115333, finalized_epoch: 115331, finalized_root: 0x0764…2a3d, exec_hash: 0x929c…1ff6 (verified), peers: 78 INFO Synced, slot: 3690668, block: 0x1244…cb92, epoch: 115333, finalized_epoch: 115331, finalized_root: 0x0764…2a3d, exec_hash: 0x929c…1ff6 (verified), peers: 78
``` ```
Once you see the above message - congratulations! This means that your node is synced and you have contributed to the decentralization and security of the Ethereum network.
## Step 5: Further readings ## Further readings
Several other resources are the next logical step to explore after running your beacon node: Several other resources are the next logical step to explore after running your beacon node:
- Learn how to [become a validator](./mainnet-validator.md); - If you intend to run a validator, proceed to [become a validator](./mainnet-validator.md);
- Explore how to [manage your keys](./key-management.md); - Explore how to [manage your keys](./key-management.md);
- Research on [validator management](./validator-management.md); - Research on [validator management](./validator-management.md);
- Dig into the [APIs](./api.md) that the beacon node and validator client provide; - Dig into the [APIs](./api.md) that the beacon node and validator client provide;
- Study even more about [checkpoint sync](./checkpoint-sync.md); or - Study even more about [checkpoint sync](./checkpoint-sync.md); or
- Investigate what steps had to be taken in the past to execute a smooth [merge migration](./merge-migration.md). - Investigate what steps had to be taken in the past to execute a smooth [merge migration](./merge-migration.md).
Finally, if you a struggling with anything, join our [Discord](https://discord.gg/cyAszAh). We are happy to help! Finally, if you are struggling with anything, join our [Discord](https://discord.gg/cyAszAh). We are happy to help!

29
book/src/slashing-protection.md
View File

@ -21,8 +21,8 @@ and carefully to keep your validators safe. See the [Troubleshooting](#troublesh
The database will be automatically created, and your validators registered with it when: The database will be automatically created, and your validators registered with it when:
* Importing keys from another source (e.g. Launchpad, Teku, Prysm, `ethdo`). * Importing keys from another source (e.g. [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli/releases), Lodestar, Nimbus, Prysm, Teku, [ethdo](https://github.com/wealdtech/ethdo)).
See [the docs on importing keys](./validator-import-launchpad.md). See [import validator keys](./mainnet-validator.md#step-3-import-validator-keys-to-lighthouse).
* Creating keys using Lighthouse itself (`lighthouse account validator create`) * Creating keys using Lighthouse itself (`lighthouse account validator create`)
* Creating keys via the [validator client API](./api-vc.md). * Creating keys via the [validator client API](./api-vc.md).
@ -45,7 +45,7 @@ Examples of circumstances where the slashing protection database is effective ar
your client to be imported into Lighthouse's slashing protection database. See your client to be imported into Lighthouse's slashing protection database. See
[Import and Export](#import-and-export). [Import and Export](#import-and-export).
* Misplacing `slashing_protection.sqlite` during a datadir change or migration between machines. * Misplacing `slashing_protection.sqlite` during a datadir change or migration between machines.
By default Lighthouse will refuse to start if it finds validator keys that are not registered By default, Lighthouse will refuse to start if it finds validator keys that are not registered
in the slashing protection database. in the slashing protection database.
Examples where it is **ineffective** are: Examples where it is **ineffective** are:
@ -54,7 +54,7 @@ Examples where it is **ineffective** are:
clients (e.g. Lighthouse and Prysm) running on the same machine, two Lighthouse instances using clients (e.g. Lighthouse and Prysm) running on the same machine, two Lighthouse instances using
different datadirs, or two clients on completely different machines (e.g. one on a cloud server different datadirs, or two clients on completely different machines (e.g. one on a cloud server
and one running locally). You are responsible for ensuring that your validator keys are never and one running locally). You are responsible for ensuring that your validator keys are never
running simultaneously – the slashing protection DB **cannot protect you in this case**. running simultaneously – the slashing protection database **cannot protect you in this case**.
* Importing keys from another client without also importing voting history. * Importing keys from another client without also importing voting history.
* If you use `--init-slashing-protection` to recreate a missing slashing protection database. * If you use `--init-slashing-protection` to recreate a missing slashing protection database.
@ -64,19 +64,22 @@ Lighthouse supports the slashing protection interchange format described in [EIP
interchange file is a record of blocks and attestations signed by a set of validator keys – interchange file is a record of blocks and attestations signed by a set of validator keys –
basically a portable slashing protection database! basically a portable slashing protection database!
With your validator client stopped, you can import a `.json` interchange file from another client To import a slashing protection database to Lighthouse, you first need to export your existing client's database. Instructions to export the slashing protection database for other clients are listed below:
- [Lodestar](https://chainsafe.github.io/lodestar/reference/cli/#validator-slashing-protection-export)
- [Nimbus](https://nimbus.guide/migration.html#2-export-slashing-protection-history)
- [Prysm](https://docs.prylabs.network/docs/wallet/slashing-protection#exporting-your-validators-slashing-protection-history)
- [Teku](https://docs.teku.consensys.net/HowTo/Prevent-Slashing#export-a-slashing-protection-file)
Once you have the slashing protection database from your existing client, you can now import the database to Lighthouse. With your validator client stopped, you can import a `.json` interchange file from another client
using this command: using this command:
```bash ```bash
lighthouse account validator slashing-protection import <my_interchange.json> lighthouse account validator slashing-protection import <my_interchange.json>
``` ```
Instructions for exporting your existing client's database are out of scope for this document,
please check the other client's documentation for instructions.
When importing an interchange file, you still need to import the validator keystores themselves When importing an interchange file, you still need to import the validator keystores themselves
separately, using the instructions for [importing keystores into separately, using the instructions for [import validator keys](./mainnet-validator.md#step-3-import-validator-keys-to-lighthouse).
Lighthouse](./validator-import-launchpad.md).
--- ---
@ -93,7 +96,7 @@ up to date.
### How Import Works ### How Import Works
Since version 1.6.0 Lighthouse will ignore any slashable data in the import data and will safely Since version 1.6.0, Lighthouse will ignore any slashable data in the import data and will safely
update the low watermarks for blocks and attestations. It will store only the maximum-slot block update the low watermarks for blocks and attestations. It will store only the maximum-slot block
for each validator, and the maximum source/target attestation. This is faster than importing for each validator, and the maximum source/target attestation. This is faster than importing
all data while also being more resilient to repeated imports & stale data. all data while also being more resilient to repeated imports & stale data.
@ -121,7 +124,7 @@ Oct 12 14:41:26.415 CRIT Failed to start validator client reason: Failed
Ensure that `slashing_protection.sqlite` is in "/home/karlm/.lighthouse/mainnet/validators" folder Ensure that `slashing_protection.sqlite` is in "/home/karlm/.lighthouse/mainnet/validators" folder
``` ```
Usually this indicates that during some manual intervention the slashing database has been Usually this indicates that during some manual intervention, the slashing database has been
misplaced. This error can also occur if you have upgraded from Lighthouse v0.2.x to v0.3.x without misplaced. This error can also occur if you have upgraded from Lighthouse v0.2.x to v0.3.x without
moving the slashing protection database. If you have imported your keys into a new node, you should moving the slashing protection database. If you have imported your keys into a new node, you should
never see this error (see [Initialization](#initialization)). never see this error (see [Initialization](#initialization)).
@ -137,7 +140,7 @@ the Lighthouse validator client with the `--init-slashing-protection` flag. This
dangerous and should not be used lightly, and we **strongly recommend** you try finding dangerous and should not be used lightly, and we **strongly recommend** you try finding
your old slashing protection database before using it. If you do decide to use it, you should your old slashing protection database before using it. If you do decide to use it, you should
wait at least 1 epoch (~7 minutes) from when your validator client was last actively signing wait at least 1 epoch (~7 minutes) from when your validator client was last actively signing
messages. If you suspect your node experienced a clock drift issue you should wait messages. If you suspect your node experienced a clock drift issue, you should wait
longer. Remember that the inactivity penalty for being offline for even a day or so longer. Remember that the inactivity penalty for being offline for even a day or so
is approximately equal to the rewards earned in a day. You will get slashed if you use is approximately equal to the rewards earned in a day. You will get slashed if you use
`--init-slashing-protection` incorrectly. `--init-slashing-protection` incorrectly.

8
book/src/suggested-fee-recipient.md
View File

@ -1,14 +1,12 @@
# Suggested Fee Recipient # Suggested Fee Recipient
The _fee recipient_ is an Ethereum address nominated by a beacon chain validator to receive The _fee recipient_ is an Ethereum address nominated by a beacon chain validator to receive
tips from user transactions. If you run validators on a network that has already merged tips from user transactions. Given that all mainnet and testnets have gone through [The Merge](https://ethereum.org/en/roadmap/merge/), if you run validators on a network, you are strongly recommended to nominate a fee recipient for your validators. Failing to nominate a fee recipient will result in losing the tips from transactions.
or is due to merge soon then you should nominate a fee recipient for your validators.
## Background ## Background
During post-merge block production, the Beacon Node (BN) will provide a `suggested_fee_recipient` to During post-merge block production, the Beacon Node (BN) will provide a `suggested_fee_recipient` to
the execution node. This is a 20-byte Ethereum address which the EL might choose to set as the the execution node. This is a 20-byte Ethereum address which the execution node might choose to set as the recipient of other fees or rewards.
coinbase and the recipient of other fees or rewards.
There is no guarantee that an execution node will use the `suggested_fee_recipient` to collect fees, There is no guarantee that an execution node will use the `suggested_fee_recipient` to collect fees,
it may use any address it chooses. It is assumed that an honest execution node *will* use the it may use any address it chooses. It is assumed that an honest execution node *will* use the
@ -189,4 +187,4 @@ accumulates other staking rewards. The reason for this is that transaction fees
validated by the execution node, and therefore need to be paid to an address that exists on the validated by the execution node, and therefore need to be paid to an address that exists on the
execution chain. Validators use BLS keys which do not correspond to Ethereum addresses, so they execution chain. Validators use BLS keys which do not correspond to Ethereum addresses, so they
have no "presence" on the execution chain. Therefore, it's necessary for each validator to nominate have no "presence" on the execution chain. Therefore, it's necessary for each validator to nominate
a separate fee recipient address. a fee recipient address.

23
book/src/testnet-validator.md
View File

@ -1,23 +0,0 @@
# Become a Testnet Validator
[mainnet-validator]: ./mainnet-validator.md
[prater-launchpad]: https://prater.launchpad.ethereum.org/
Joining an Ethereum consensus testnet is a great way to get familiar with staking in Phase 0. All users should
experiment with a testnet prior to staking mainnet ETH.
To join a testnet, you can follow the [Become an Ethereum consensus Mainnet Validator][mainnet-validator]
instructions but with a few differences:
1. Use the appropriate Staking launchpad website:
- [Prater][prater-launchpad]
1. Instead of `--network mainnet`, use the appropriate network flag:
- `--network prater`: Prater.
1. Use a Goerli execution node instead of a mainnet one:
- For Geth, this means using `geth --goerli --http`.
1. Notice that Lighthouse will store its files in a different directory by default:
- `~/.lighthouse/prater`: Prater.
>
> **Never use real ETH to join a testnet!** All of the testnets listed here use Goerli ETH which is
> basically worthless. This allows experimentation without real-world costs.

90
book/src/validator-create.md
View File

@ -1,90 +0,0 @@
# Create a validator
[launchpad]: https://launchpad.ethereum.org/
>
> **Note: we recommend using the [Staking launchpad][launchpad] to create validators.**
Validators are fundamentally represented by a BLS keypair. In Lighthouse, we
use a [wallet](./wallet-create.md) to generate these keypairs. Once a wallet
exists, the `lighthouse account validator create` command is used to generate
the BLS keypair and all necessary information to submit a validator deposit and
have that validator operate in the `lighthouse validator_client`.
## Usage
To create a validator from a [wallet](./wallet-create.md), use the `lighthouse
account validator create` command:
```bash
lighthouse account validator create --help
Creates new validators from an existing EIP-2386 wallet using the EIP-2333 HD key derivation scheme.
USAGE:
lighthouse account_manager validator create [FLAGS] [OPTIONS]
FLAGS:
-h, --help Prints help information
--stdin-inputs If present, read all user inputs from stdin instead of tty.
--store-withdrawal-keystore If present, the withdrawal keystore will be stored alongside the voting keypair.
It is generally recommended to *not* store the withdrawal key and instead
generate them from the wallet seed when required.
-V, --version Prints version information
OPTIONS:
--at-most <AT_MOST_VALIDATORS>
Observe the number of validators in --validator-dir, only creating enough to reach the given count. Never
deletes an existing validator.
--count <VALIDATOR_COUNT>
The number of validators to create, regardless of how many already exist
-d, --datadir <DIR>
Used to specify a custom root data directory for lighthouse keys and databases. Defaults to
$HOME/.lighthouse/{network} where network is the value of the `network` flag Note: Users should specify
separate custom datadirs for different networks.
--debug-level <LEVEL>
The verbosity level for emitting logs. [default: info] [possible values: info, debug, trace, warn, error,
crit]
--deposit-gwei <DEPOSIT_GWEI>
The GWEI value of the deposit amount. Defaults to the minimum amount required for an active validator
(MAX_EFFECTIVE_BALANCE)
--network <network>
Name of the Eth2 chain Lighthouse will sync and follow. [default: mainnet] [possible values: prater, mainnet]
--secrets-dir <SECRETS_DIR>
The path where the validator keystore passwords will be stored. Defaults to ~/.lighthouse/{network}/secrets
-s, --spec <DEPRECATED>
This flag is deprecated, it will be disallowed in a future release. This value is now derived from the
--network or --testnet-dir flags.
-t, --testnet-dir <DIR>
Path to directory containing eth2_testnet specs. Defaults to a hard-coded Lighthouse testnet. Only effective
if there is no existing database.
--wallet-name <WALLET_NAME> Use the wallet identified by this name
--wallet-password <WALLET_PASSWORD_PATH>
A path to a file containing the password which will unlock the wallet.
--wallets-dir <wallets-dir>
A path containing Eth2 EIP-2386 wallets. Defaults to ~/.lighthouse/{network}/wallets
```
## Example
The example assumes that the `wally` wallet was generated from the
[wallet](./wallet-create.md) example.
```bash
lighthouse --network prater account validator create --wallet-name wally --wallet-password wally.pass --count 1
```
This command will:
- Derive a single new BLS keypair from wallet `wally` in `~/.lighthouse/{network}/wallets`, updating it so that it generates a
new key next time.
- Create a new directory in `~/.lighthouse/{network}/validators` containing:
- An encrypted keystore containing the validators voting keypair.
- An `eth1_deposit_data.rlp` assuming the default deposit amount (`32 ETH`
for most testnets and mainnet) which can be submitted to the deposit
contract for the Prater testnet. Other testnets can be set via the
`--network` CLI param.
- Store a password to the validators voting keypair in `~/.lighthouse/{network}/secrets`.

11
book/src/validator-doppelganger.md
View File

@ -16,8 +16,7 @@ achieves this by staying silent for 2-3 epochs after a validator is started so i
other instances of that validator before starting to sign potentially slashable messages. other instances of that validator before starting to sign potentially slashable messages.
> Note: Doppelganger Protection is not yet interoperable, so if it is configured on a Lighthouse > Note: Doppelganger Protection is not yet interoperable, so if it is configured on a Lighthouse
> validator client, the client must be connected to a Lighthouse beacon node. Because Infura > validator client, the client must be connected to a Lighthouse beacon node.
> uses Teku, Lighthouse's Doppelganger Protection cannot yet be used with Infura's Eth2 service.
## Initial Considerations ## Initial Considerations
@ -30,9 +29,9 @@ is no guarantee that your Beacon Node (BN) will see messages from it. **It is fe
doppelganger protection to fail to detect another validator due to network faults or other common doppelganger protection to fail to detect another validator due to network faults or other common
circumstances.** circumstances.**
DP should be considered a last-line-of-defence that *might* save a validator from being slashed due DP should be considered as a last-line-of-defence that *might* save a validator from being slashed due
to operator error (i.e. running two instances of the same validator). Users should to operator error (i.e. running two instances of the same validator). Users should
*never* rely upon DP and should practice the same caution with regards to duplicating validators as *never* rely upon DP and should practice the same caution with regard to duplicating validators as
if it did not exist. if it did not exist.
**Remember: even with doppelganger protection enabled, it is not safe to run two instances of the **Remember: even with doppelganger protection enabled, it is not safe to run two instances of the
@ -44,7 +43,7 @@ DP works by staying silent on the network for 2-3 epochs before starting to sign
Staying silent and refusing to sign messages will cause the following: Staying silent and refusing to sign messages will cause the following:
- 2-3 missed attestations, incurring penalties and missed rewards. - 2-3 missed attestations, incurring penalties and missed rewards.
- 2-3 epochs of missed sync committee contributions (if the validator is in a sync committee, which is unlikely), incurring penalties and missed rewards (post-Altair upgrade only). - 2-3 epochs of missed sync committee contributions (if the validator is in a sync committee, which is unlikely), incurring penalties and missed rewards.
- Potentially missed rewards by missing a block proposal (if the validator is an elected block - Potentially missed rewards by missing a block proposal (if the validator is an elected block
proposer, which is unlikely). proposer, which is unlikely).
@ -105,7 +104,7 @@ there is no other instance of that validator running elsewhere!**
The steps to solving a doppelganger vary depending on the case, but some places to check are: The steps to solving a doppelganger vary depending on the case, but some places to check are:
1. Is there another validator process running on this host? 1. Is there another validator process running on this host?
- Unix users can check `ps aux | grep lighthouse` - Unix users can check by running the command `ps aux | grep lighthouse`
- Windows users can check the Task Manager. - Windows users can check the Task Manager.
1. Has this validator recently been moved from another host? Check to ensure it's not running. 1. Has this validator recently been moved from another host? Check to ensure it's not running.
1. Has this validator been delegated to a staking service? 1. Has this validator been delegated to a staking service?

111
book/src/validator-import-launchpad.md
View File

@ -1,111 +0,0 @@
# Importing from the Ethereum Staking Launch pad
The [Staking Launchpad](https://github.com/ethereum/eth2.0-deposit) is a website
from the Ethereum Foundation which guides users how to use the
[`eth2.0-deposit-cli`](https://github.com/ethereum/eth2.0-deposit-cli)
command-line program to generate consensus validator keys.
The keys that are generated from `eth2.0-deposit-cli` can be easily loaded into
a Lighthouse validator client (`lighthouse vc`). In fact, both of these
programs are designed to work with each other.
This guide will show the user how to import their keys into Lighthouse so they
can perform their duties as a validator. The guide assumes the user has already
[installed Lighthouse](./installation.md).
## Instructions
Whilst following the steps on the website, users are instructed to download the
[`eth2.0-deposit-cli`](https://github.com/ethereum/eth2.0-deposit-cli)
repository. This `eth2-deposit-cli` script will generate the validator BLS keys
into a `validator_keys` directory. We assume that the user's
present-working-directory is the `eth2-deposit-cli` repository (this is where
you will be if you just ran the `./deposit.sh` script from the Staking Launch pad
website). If this is not the case, simply change the `--directory` to point to
the `validator_keys` directory.
Now, assuming that the user is in the `eth2-deposit-cli` directory and they're
using the default (`~/.lighthouse/{network}/validators`) `validators` directory (specify a different one using
`--validators-dir` flag), they can follow these steps:
### 1. Run the `lighthouse account validator import` command.
Docker users should use the command from the [Docker](#docker)
section, all other users can use:
```bash
lighthouse --network mainnet account validator import --directory validator_keys
```
Note: The user must specify the consensus client network that they are importing the keys for using the `--network` flag.
After which they will be prompted for a password for each keystore discovered:
```
Keystore found at "validator_keys/keystore-m_12381_3600_0_0_0-1595406747.json":
- Public key: 0xa5e8702533f6d66422e042a0bf3471ab9b302ce115633fa6fdc5643f804b6b4f1c33baf95f125ec21969a3b1e0dd9e56
- UUID: 8ea4cf99-8719-43c5-9eda-e97b8a4e074f
If you enter a password it will be stored in validator_definitions.yml so that it is not required each time the validator client starts.
Enter a password, or press enter to omit a password:
```
The user can choose whether or not they'd like to store the validator password
in the [`validator_definitions.yml`](./validator-management.md) file. If the
password is *not* stored here, the validator client (`lighthouse vc`)
application will ask for the password each time it starts. This might be nice
for some users from a security perspective (i.e., if it is a shared computer),
however it means that if the validator client restarts, the user will be liable
to off-line penalties until they can enter the password. If the user trusts the
computer that is running the validator client and they are seeking maximum
validator rewards, we recommend entering a password at this point.
Once the process is done the user will see:
```
Successfully imported keystore.
Successfully updated validator_definitions.yml.
Successfully imported 1 validators (0 skipped).
WARNING: DO NOT USE THE ORIGINAL KEYSTORES TO VALIDATE WITH ANOTHER CLIENT, OR YOU WILL GET SLASHED..
```
The import process is complete!
### 2. Run the `lighthouse vc` command.
Now the keys are imported the user can start performing their validator duties
by running `lighthouse vc` and checking that their validator public key appears
as a `voting_pubkey` in one of the following logs:
```
INFO Enabled validator voting_pubkey: 0xa5e8702533f6d66422e042a0bf3471ab9b302ce115633fa6fdc5643f804b6b4f1c33baf95f125ec21969a3b1e0dd9e56
```
Once this log appears (and there are no errors) the `lighthouse vc` application
will ensure that the validator starts performing its duties and being rewarded
by the protocol. There is no more input required from the user.
## Docker
The `import` command is a little more complex for Docker users, but the example
in this document can be substituted with:
```bash
docker run -it \
-v $HOME/.lighthouse:/root/.lighthouse \
-v $(pwd)/validator_keys:/root/validator_keys \
sigp/lighthouse \
lighthouse --network MY_NETWORK account validator import --directory /root/validator_keys
```
Here we use two `-v` volumes to attach:
- `~/.lighthouse` on the host to `/root/.lighthouse` in the Docker container.
- The `validator_keys` directory in the present working directory of the host
to the `/root/validator_keys` directory of the Docker container.

18
book/src/validator-management.md
View File

@ -1,10 +1,10 @@
# Validator Management # Validator Management
The `lighthouse vc` command starts a *validator client* instance which connects The `lighthouse vc` command starts a *validator client* instance which connects
to a beacon node performs the duties of a staked validator. to a beacon node to perform the duties of a staked validator.
This document provides information on how the validator client discovers the This document provides information on how the validator client discovers the
validators it will act for and how it should obtain their cryptographic validators it will act for and how it obtains their cryptographic
signatures. signatures.
Users that create validators using the `lighthouse account` tool in the Users that create validators using the `lighthouse account` tool in the
@ -49,7 +49,7 @@ Each permitted field of the file is listed below for reference:
- `enabled`: A `true`/`false` indicating if the validator client should consider this - `enabled`: A `true`/`false` indicating if the validator client should consider this
validator "enabled". validator "enabled".
- `voting_public_key`: A validator public key. - `voting_public_key`: A validator public key.
- `type`: How the validator signs messages (currently restricted to `local_keystore`). - `type`: How the validator signs messages (this can be `local_keystore` or `web3signer` (see [Web3Signer](./validator-web3signer.md))).
- `voting_keystore_path`: The path to a EIP-2335 keystore. - `voting_keystore_path`: The path to a EIP-2335 keystore.
- `voting_keystore_password_path`: The path to the password for the EIP-2335 keystore. - `voting_keystore_password_path`: The path to the password for the EIP-2335 keystore.
- `voting_keystore_password`: The password to the EIP-2335 keystore. - `voting_keystore_password`: The password to the EIP-2335 keystore.
@ -59,7 +59,7 @@ Each permitted field of the file is listed below for reference:
## Populating the `validator_definitions.yml` file ## Populating the `validator_definitions.yml` file
When validator client starts and the `validator_definitions.yml` file doesn't When a validator client starts and the `validator_definitions.yml` file doesn't
exist, a new file will be created. If the `--disable-auto-discover` flag is exist, a new file will be created. If the `--disable-auto-discover` flag is
provided, the new file will be empty and the validator client will not start provided, the new file will be empty and the validator client will not start
any validators. If the `--disable-auto-discover` flag is **not** provided, an any validators. If the `--disable-auto-discover` flag is **not** provided, an
@ -71,7 +71,7 @@ recap:
### Automatic validator discovery ### Automatic validator discovery
When the `--disable-auto-discover` flag is **not** provided, the validator will search the When the `--disable-auto-discover` flag is **not** provided, the validator client will search the
`validator-dir` for validators and add any *new* validators to the `validator-dir` for validators and add any *new* validators to the
`validator_definitions.yml` with `enabled: true`. `validator_definitions.yml` with `enabled: true`.
@ -89,7 +89,7 @@ name identical to the `voting_public_key` value.
#### Discovery Example #### Discovery Example
Lets assume the following directory structure: Let's assume the following directory structure:
``` ```
~/.lighthouse/{network}/validators ~/.lighthouse/{network}/validators
@ -158,7 +158,7 @@ start.
If a validator client were to start using the [first example If a validator client were to start using the [first example
`validator_definitions.yml` file](#example) it would print the following log, `validator_definitions.yml` file](#example) it would print the following log,
acknowledging there there are two validators and one is disabled: acknowledging there are two validators and one is disabled:
``` ```
INFO Initialized validators enabled: 1, disabled: 1 INFO Initialized validators enabled: 1, disabled: 1
@ -180,8 +180,8 @@ should not be opened by another process.
1. Proceed to act for that validator, creating blocks and attestations if/when required. 1. Proceed to act for that validator, creating blocks and attestations if/when required.
If there is an error during any of these steps (e.g., a file is missing or If there is an error during any of these steps (e.g., a file is missing or
corrupt) the validator client will log an error and continue to attempt to corrupt), the validator client will log an error and continue to attempt to
process other validators. process other validators.
When the validator client exits (or the validator is deactivated) it will When the validator client exits (or the validator is deactivated), it will
remove the `voting-keystore.json.lock` to indicate that the keystore is free for use again. remove the `voting-keystore.json.lock` to indicate that the keystore is free for use again.

2
book/src/validator-monitoring.md
View File

@ -38,7 +38,7 @@ minutes after start up.
#### Example #### Example
``` ```
lighthouse bn --staking --validator-monitor-auto lighthouse bn --http --validator-monitor-auto
``` ```
### Manual ### Manual

66
book/src/voluntary-exit.md
View File

@ -1,7 +1,7 @@
# Voluntary exits # Voluntary Exits (Full Withdrawals)
A validator may chose to voluntarily stop performing duties (proposing blocks and attesting to blocks) by submitting A validator may chose to voluntarily stop performing duties (proposing blocks and attesting to blocks) by submitting
a voluntary exit transaction to the beacon chain. a voluntary exit message to the beacon chain.
A validator can initiate a voluntary exit provided that the validator is currently active, has not been slashed and has been active for at least 256 epochs (~27 hours) since it has been activated. A validator can initiate a voluntary exit provided that the validator is currently active, has not been slashed and has been active for at least 256 epochs (~27 hours) since it has been activated.
@ -10,21 +10,15 @@ A validator can initiate a voluntary exit provided that the validator is current
It takes at a minimum 5 epochs (32 minutes) for a validator to exit after initiating a voluntary exit. It takes at a minimum 5 epochs (32 minutes) for a validator to exit after initiating a voluntary exit.
This number can be much higher depending on how many other validators are queued to exit. This number can be much higher depending on how many other validators are queued to exit.
## Withdrawal of exited funds
In order to be eligible for fund withdrawal, the validator must have set a withdrawal address and fully exited the network.
For more information on how fund withdrawal works, please visit <https://ethereum.org/en/staking/withdrawals/#how-do-withdrawals-work>
## Initiating a voluntary exit ## Initiating a voluntary exit
In order to initiate an exit, users can use the `lighthouse account validator exit` command. In order to initiate an exit, users can use the `lighthouse account validator exit` command.
- The `--keystore` flag is used to specify the path to the EIP-2335 voting keystore for the validator. - The `--keystore` flag is used to specify the path to the EIP-2335 voting keystore for the validator. The path should point directly to the validator key `.json` file, _not_ the folder containing the `.json` file.
- The `--beacon-node` flag is used to specify a beacon chain HTTP endpoint that confirms to the [Beacon Node API](https://ethereum.github.io/beacon-APIs/) specifications. That beacon node will be used to validate and propagate the voluntary exit. The default value for this flag is `http://localhost:5052`. - The `--beacon-node` flag is used to specify a beacon chain HTTP endpoint that confirms to the [Beacon Node API](https://ethereum.github.io/beacon-APIs/) specifications. That beacon node will be used to validate and propagate the voluntary exit. The default value for this flag is `http://localhost:5052`.
- The `--network` flag is used to specify a particular Eth2 network (default is `mainnet`). - The `--network` flag is used to specify the network (default is `mainnet`).
- The `--password-file` flag is used to specify the path to the file containing the password for the voting keystore. If this flag is not provided, the user will be prompted to enter the password. - The `--password-file` flag is used to specify the path to the file containing the password for the voting keystore. If this flag is not provided, the user will be prompted to enter the password.
@ -36,13 +30,13 @@ The exit phrase is the following:
Below is an example for initiating a voluntary exit on the Prater testnet. Below is an example for initiating a voluntary exit on the Goerli testnet.
``` ```
$ lighthouse --network prater account validator exit --keystore /path/to/keystore --beacon-node http://localhost:5052 $ lighthouse --network goerli account validator exit --keystore /path/to/keystore --beacon-node http://localhost:5052
Running account manager for Prater network Running account manager for Prater network
validator-dir path: ~/.lighthouse/prater/validators validator-dir path: ~/.lighthouse/goerli/validators
Enter the keystore password for validator in 0xabcd Enter the keystore password for validator in 0xabcd
@ -52,6 +46,8 @@ Publishing a voluntary exit for validator 0xabcd
WARNING: WARNING: THIS IS AN IRREVERSIBLE OPERATION WARNING: WARNING: THIS IS AN IRREVERSIBLE OPERATION
PLEASE VISIT https://lighthouse-book.sigmaprime.io/voluntary-exit.html PLEASE VISIT https://lighthouse-book.sigmaprime.io/voluntary-exit.html
TO MAKE SURE YOU UNDERSTAND THE IMPLICATIONS OF A VOLUNTARY EXIT. TO MAKE SURE YOU UNDERSTAND THE IMPLICATIONS OF A VOLUNTARY EXIT.
@ -65,3 +61,47 @@ Please keep your validator running till exit epoch
Exit epoch in approximately 1920 secs Exit epoch in approximately 1920 secs
``` ```
## Full withdrawal of staked fund
After the [Capella](https://ethereum.org/en/history/#capella) upgrade on 12<sup>th</sup> April 2023, if a user initiates a voluntary exit, they will receive the full staked funds to the withdrawal address, provided that the validator has withdrawal credentials of type `0x01`. For more information on how fund withdrawal works, please visit [Ethereum.org](https://ethereum.org/en/staking/withdrawals/#how-do-withdrawals-work) website.
## FAQ
### 1. How to know if I have the withdrawal credentials type `0x01`?
There are two types of withdrawal credentials, `0x00` and `0x01`. To check which type your validator has, go to [Staking launchpad](https://launchpad.ethereum.org/en/withdrawals), enter your validator index and click `verify on mainnet`:
- `withdrawals enabled` means your validator is of type `0x01`, and you will automatically receive the full withdrawal to the withdrawal address that you set.
- `withdrawals not enabled` means your validator is of type `0x00`, and will need to update your withdrawal credentials from `0x00` type to `0x01` type (also known as BLS-to-execution-change, or BTEC) to receive the staked funds. The common way to do this is using `Staking deposit CLI` or `ethdo`, with the instructions available [here](https://launchpad.ethereum.org/en/withdrawals#update-your-keys).
### 2. What if my validator is of type `0x00` and I do not update my withdrawal credentials after I initiated a voluntary exit?
Your staked fund will continue to be locked on the beacon chain. You can update your withdrawal credentials **anytime**, and there is no deadline for that. The catch is that as long as you do not update your withdrawal credentials, your staked funds in the beacon chain will continue to be locked in the beacon chain. Only after you update the withdrawal credentials, will the staked funds be withdrawn to the withdrawal address.
### 3. How many times can I update my withdrawal credentials?
If your withdrawal credentials is of type `0x00`, you can only update it once to type `0x01`. It is therefore very important to ensure that the withdrawal address you set is an address under your control, preferably an address controlled by a hardware wallet.
If your withdrawal credentials is of type `0x01`, it means you have set your withdrawal address previously, and you will not be able to change the withdrawal address.
### 3. When will my BTEC request (update withdrawal credentials to type `0x01`) be processed ?
Your BTEC request will be included very quickly as soon as a new block is proposed. This should be the case most (if not all) of the time, given that the peak BTEC request time has now past (right after the [Capella](https://ethereum.org/en/history/#capella) upgrade on 12<sup>th</sup> April 2023 and lasted for ~ 2 days) .
### 4. When will I get my staked fund after voluntary exit if my validator is of type `0x01`?
There are 3 waiting periods until you get the staked funds in your withdrawal address:
- An exit queue: a varying time that takes at a minimum 5 epochs (32 minutes) if there is no queue; or if there are many validators exiting at the same time, it has to go through the exit queue. The exit queue can be from hours to weeks, depending on the number of validators in the exit queue. During this time your validator has to stay online to perform its duties to avoid penalties.
- A fixed waiting period of 256 epochs (27.3 hours) for the validator's status to become withdrawable.
- A varying time of "validator sweep" that can take up to 5 days (at the time of writing with ~560,000 validators on the mainnet). The "validator sweep" is the process of skimming through all validators by index number for eligible withdrawals (those with type `0x01` and balance above 32ETH). Once the "validator sweep" reaches your validator's index, your staked fund will be fully withdrawn to the withdrawal address set.
The total time taken is the summation of the above 3 waiting periods. After these waiting periods, you will receive the staked funds in your withdrawal address.
The voluntary exit and full withdrawal process is summarized in the Figure below.
![full](./imgs/full-withdrawal.png)

74
book/src/wallet-create.md
View File

@ -1,74 +0,0 @@
# Create a wallet
[launchpad]: https://launchpad.ethereum.org/
>
> **Note: we recommend using the [Staking launchpad][launchpad] to create validators.**
A wallet allows for generating practically unlimited validators from an
easy-to-remember 24-word string (a mnemonic). As long as that mnemonic is
backed up, all validator keys can be trivially re-generated.
The 24-word string is randomly generated during wallet creation and printed out
to the terminal. It's important to **make one or more backups of the mnemonic**
to ensure your ETH is not lost in the case of data loss. It is very important to
**keep your mnemonic private** as it represents the ultimate control of your
ETH.
Whilst the wallet stores the mnemonic, it does not store it in plain-text: the
mnemonic is encrypted with a password. It is the responsibility of the user to
define a strong password. The password is only required for interacting with
the wallet, it is not required for recovering keys from a mnemonic.
## Usage
To create a wallet, use the `lighthouse account wallet` command:
```bash
lighthouse account wallet create --help
Creates a new HD (hierarchical-deterministic) EIP-2386 wallet.
USAGE:
lighthouse account_manager wallet create [OPTIONS] --name <WALLET_NAME> --password-file <WALLET_PASSWORD_PATH>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-d, --datadir <DIR> Data directory for lighthouse keys and databases.
--mnemonic-output-path <MNEMONIC_PATH>
If present, the mnemonic will be saved to this file. DO NOT SHARE THE MNEMONIC.
--name <WALLET_NAME>
The wallet will be created with this name. It is not allowed to create two wallets with the same name for
the same --base-dir.
--password-file <WALLET_PASSWORD_PATH>
A path to a file containing the password which will unlock the wallet. If the file does not exist, a random
password will be generated and saved at that path. To avoid confusion, if the file does not already exist it
must include a '.pass' suffix.
-t, --testnet-dir <DIR>
Path to directory containing eth2_testnet specs. Defaults to a hard-coded Lighthouse testnet. Only effective
if there is no existing database.
--type <WALLET_TYPE>
The type of wallet to create. Only HD (hierarchical-deterministic) wallets are supported presently..
[default: hd] [possible values: hd]
```
## Example
Creates a new wallet named `wally` and saves it in `~/.lighthouse/prater/wallets` with a randomly generated password saved
to `./wallet.pass`:
```bash
lighthouse --network prater account wallet create --name wally --password-file wally.pass
```
> Notes:
>
> - The password is not `wally.pass`, it is the _contents_ of the
> `wally.pass` file.
> - If `wally.pass` already exists the wallet password will be set to contents
> of that file.