Update Lighthouse book Sec 3-6 and FAQ (#4221)
## Issue Addressed Update Lighthouse book to include latest information especially after Capella upgrade ## Proposed Changes Notable changes: - Combine Sec 4.1 & 6.1 into Sec 4, because Sec 6.1 is importing validator key which is a required step when want to run a validator - Combine Sec 5.1 & 5.2 with Sec 5, and move Sec 5 to under Sec 9 - Added partial withdrawals in Sec 6 ## Additional Info Please provide any additional information. For example, future considerations or information useful for reviewers. Co-authored-by: chonghe <tanck2005@gmail.com>
This commit is contained in:
chonghe
parent
b1416c8a43
commit
45835f6a6b
66
book/src/LaTeX/full-withdrawal.tex
Normal file
66
book/src/LaTeX/full-withdrawal.tex
Normal 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
50
book/src/LaTeX/partial-withdrawal.tex
Normal 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}
|
||||
@ -11,15 +11,10 @@
|
||||
* [Update Priorities](./installation-priorities.md)
|
||||
* [Run a Node](./run_a_node.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)
|
||||
* [Importing from the Staking Launchpad](./validator-import-launchpad.md)
|
||||
* [Slashing Protection](./slashing-protection.md)
|
||||
* [Voluntary Exits](./voluntary-exit.md)
|
||||
* [Partial Withdrawals](./partial-withdrawal.md)
|
||||
* [Validator Monitoring](./validator-monitoring.md)
|
||||
* [Doppelganger Protection](./validator-doppelganger.md)
|
||||
* [Suggested Fee Recipient](./suggested-fee-recipient.md)
|
||||
@ -46,6 +41,8 @@
|
||||
* [Remote Signing with Web3Signer](./validator-web3signer.md)
|
||||
* [Database Configuration](./advanced_database.md)
|
||||
* [Database Migrations](./database-migrations.md)
|
||||
* [Key Management](./key-management.md)
|
||||
* [Key Recovery](./key-recovery.md)
|
||||
* [Advanced Networking](./advanced_networking.md)
|
||||
* [Running a Slasher](./slasher.md)
|
||||
* [Redundancy](./redundancy.md)
|
||||
|
||||
BIN
book/src/imgs/full-withdrawal.png
Normal file
BIN
book/src/imgs/full-withdrawal.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 257 KiB |
BIN
book/src/imgs/partial-withdrawal.png
Normal file
BIN
book/src/imgs/partial-withdrawal.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 172 KiB |
@ -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
|
||||
* Memory: 16 GB RAM or more
|
||||
* Storage: 2 TB solid state storage
|
||||
* Memory: 32 GB RAM*
|
||||
* Storage: 2 TB solid state drive
|
||||
* 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
|
||||
|
||||
@ -3,12 +3,12 @@
|
||||
[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
|
||||
keys. It is hierarchical because each validator key can be _derived_ from a
|
||||
master key, making the validators keys _children_ of the master key. This
|
||||
scheme means that a single 24-word mnemonic can be used to backup all of your
|
||||
scheme means that a single 24-word mnemonic can be used to back up all of your
|
||||
validator keys without providing any observable link between them (i.e., it is
|
||||
privacy-retaining). Hierarchical key derivation schemes are common-place in
|
||||
cryptocurrencies, they are already used by most hardware and software wallets
|
||||
@ -30,37 +30,63 @@ We defined some terms in the context of validator key management:
|
||||
keypair.
|
||||
- Defined in EIP-2335.
|
||||
- **Voting Keypair**: a BLS public and private keypair which is used for
|
||||
signing blocks, attestations and other messages on regular intervals,
|
||||
whilst staking in Phase 0.
|
||||
signing blocks, attestations and other messages on regular intervals in the beacon chain.
|
||||
- **Withdrawal Keypair**: a BLS public and private keypair which will be
|
||||
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
|
||||
items, starting at one easy-to-backup mnemonic and ending with multiple
|
||||
keypairs. Creating a single validator looks like this:
|
||||
The following example demonstrates how to create a single validator key.
|
||||
|
||||
1. Create a **wallet** and record the **mnemonic**:
|
||||
- `lighthouse --network prater account wallet create --name wally --password-file wally.pass`
|
||||
1. Create the voting and withdrawal **keystores** for one validator:
|
||||
- `lighthouse --network prater account validator create --wallet-name wally --wallet-password wally.pass --count 1`
|
||||
### Step 1: Create a wallet and record the mnemonic
|
||||
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.
|
||||
|
||||
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
|
||||
`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.
|
||||
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.
|
||||
|
||||
## Detail
|
||||
|
||||
@ -76,36 +102,17 @@ There are three important directories in Lighthouse validator key management:
|
||||
- Defaults to `~/.lighthouse/{network}/validators`
|
||||
- `secrets/`: since the validator signing keys are "hot", the validator process
|
||||
needs access to the passwords to decrypt the keystores in the validators
|
||||
dir. 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`).
|
||||
directory. These passwords are stored here.
|
||||
- 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
|
||||
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
|
||||
representation of the keystore public key. If it finds this file, it attempts
|
||||
`secrets/` directory for a file with the same name as the 0x-prefixed validator public key. If it finds this file, it attempts
|
||||
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.
|
||||
|
||||
The `validators/` and `secrets/` directories are kept separate to allow for
|
||||
ease-of-backup; you can safely backup `validators/` without worrying about
|
||||
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.
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# Key recovery
|
||||
# Key Recovery
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
|
||||
@ -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
|
||||
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
|
||||
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 a validator's success. Before submitting your mainnet deposit, we recommend:
|
||||
|
||||
Being educated is critical to validator success. Before submitting your mainnet deposit, we
|
||||
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.
|
||||
- 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/).
|
||||
- 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.
|
||||
|
||||
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
|
||||
@ -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
|
||||
> [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.
|
||||
- `lighthouse --network mainnet`: Mainnet.
|
||||
- `lighthouse --network prater`: Prater (testnet).
|
||||
There are five primary steps to become a validator:
|
||||
|
||||
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.
|
||||
1. [Create validator keys](#step-1-create-validator-keys)
|
||||
1. [Start an execution client and Lighthouse beacon node](#step-2-start-an-execution-client-and-lighthouse-beacon-node)
|
||||
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
|
||||
setting aside one or two hours for this process.
|
||||
> **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.
|
||||
|
||||
### Step 1. Create validator keys
|
||||
|
||||
The Ethereum Foundation provides a "Staking Launchpad" for creating validator keypairs and submitting
|
||||
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:
|
||||
|
||||
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:
|
||||
```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
|
||||
|
||||
*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:
|
||||
|
||||
Goerli testnet:
|
||||
```bash
|
||||
lighthouse --network mainnet bn --staking
|
||||
lighthouse --network goerli account validator import --directory $HOME/staking-deposit-cli/validator_keys
|
||||
```
|
||||
|
||||
```bash
|
||||
lighthouse --network mainnet vc
|
||||
> Note: The user must specify the consensus client network that they are importing the keys by using the `--network` flag.
|
||||
|
||||
> 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.
|
||||
> To specify a custom dir, see [Custom Directories][advanced-datadir].
|
||||
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 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:
|
||||
|
||||
```bash
|
||||
@ -167,29 +226,8 @@ $ docker run \
|
||||
lighthouse --network mainnet vc
|
||||
```
|
||||
|
||||
### Step 6. Leave Lighthouse running
|
||||
|
||||
Leave your beacon node and validator client running and you'll see logs as the
|
||||
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
|
||||
If you get stuck you can always reach out on our [Discord][discord] or [create an
|
||||
issue](https://github.com/sigp/lighthouse/issues/new).
|
||||
|
||||
Happy staking!
|
||||
|
||||
|
||||
23
book/src/partial-withdrawal.md
Normal file
23
book/src/partial-withdrawal.md
Normal 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.
|
||||
|
||||
|
||||
@ -1,77 +1,43 @@
|
||||
# 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:
|
||||
|
||||
1. Set up an [execution node](#step-1-set-up-an-execution-node);
|
||||
1. Enable [checkpoint sync](#step-2-choose-a-checkpoint-sync-provider);
|
||||
1. Run [Lighthouse](#step-3-run-lighthouse);
|
||||
1. [Check logs](#step-4-check-logs); and
|
||||
1. [Further readings](#step-5-further-readings).
|
||||
1. Create a [JWT secret file](#step-1-create-a-jwt-secret-file)
|
||||
1. Set up an [execution node](#step-2-set-up-an-execution-node);
|
||||
1. Set up a [beacon node](#step-3-set-up-a-beacon-node-using-lighthouse);
|
||||
1. [Check logs for sync status](#step-4-check-logs);
|
||||
|
||||
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
|
||||
present in blocks. Two flags are used to configure this connection:
|
||||
## Step 1: Create a JWT secret file
|
||||
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
|
||||
`http://localhost:8551`.
|
||||
- `--execution-jwt`: the *path* to the file containing the JWT secret shared by Lighthouse and the
|
||||
execution engine. This is a mandatory form of authentication that ensures that Lighthouse
|
||||
has authority to control the execution engine.
|
||||
```bash
|
||||
sudo mkdir -p /secrets
|
||||
openssl rand -hex 32 | tr -d "\n" | sudo tee /secrets/jwt.hex
|
||||
```
|
||||
|
||||
Each execution engine has its own flags for configuring the engine API and JWT.
|
||||
Please consult the relevant page of your execution engine for the required flags:
|
||||
## Step 2: Set up an execution node
|
||||
|
||||
- [Geth: Connecting to Consensus Clients](https://geth.ethereum.org/docs/getting-started/consensus-clients)
|
||||
- [Nethermind: Running Nethermind & CL](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge)
|
||||
- [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 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
|
||||
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:
|
||||
|
||||
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,
|
||||
we will enable checkpoint sync by providing the URL to the `--checkpoint-sync-url` flag.
|
||||
> 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.
|
||||
|
||||
### 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`,
|
||||
which we will use in [step 3](#step-3-run-lighthouse).
|
||||
## Step 3: Set up a beacon node using Lighthouse
|
||||
|
||||
## Step 3: Run Lighthouse
|
||||
|
||||
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.
|
||||
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:
|
||||
|
||||
### Staking
|
||||
|
||||
@ -84,9 +50,30 @@ lighthouse bn \
|
||||
--http
|
||||
```
|
||||
|
||||
A Lighthouse beacon node can be configured to expose an HTTP server by supplying the `--http` flag.
|
||||
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.
|
||||
> Note: If you download the binary file, you need to navigate to the directory of the binary file to run the above command.
|
||||
|
||||
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
|
||||
|
||||
@ -99,17 +86,19 @@ lighthouse bn \
|
||||
--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.
|
||||
|
||||
## Step 4: Check logs
|
||||
|
||||
|
||||
## Step 4: Check logs for sync status
|
||||
Several logs help you identify if Lighthouse is running correctly.
|
||||
|
||||
### 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
|
||||
@ -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
|
||||
```
|
||||
|
||||
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
|
||||
as soon as forwards sync completes.
|
||||
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.
|
||||
|
||||
> 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
|
||||
> against a trusted source like another [public endpoint](https://eth-clients.github.io/checkpoint-sync-endpoints/),
|
||||
> 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
|
||||
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
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
- 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);
|
||||
- Research on [validator management](./validator-management.md);
|
||||
- Dig into the [APIs](./api.md) that the beacon node and validator client provide;
|
||||
- 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).
|
||||
|
||||
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!
|
||||
|
||||
@ -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:
|
||||
|
||||
* Importing keys from another source (e.g. Launchpad, Teku, Prysm, `ethdo`).
|
||||
See [the docs on importing keys](./validator-import-launchpad.md).
|
||||
* 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 [import validator keys](./mainnet-validator.md#step-3-import-validator-keys-to-lighthouse).
|
||||
* Creating keys using Lighthouse itself (`lighthouse account validator create`)
|
||||
* 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
|
||||
[Import and Export](#import-and-export).
|
||||
* 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.
|
||||
|
||||
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
|
||||
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
|
||||
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.
|
||||
* 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 –
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
separately, using the instructions for [importing keystores into
|
||||
Lighthouse](./validator-import-launchpad.md).
|
||||
separately, using the instructions for [import validator keys](./mainnet-validator.md#step-3-import-validator-keys-to-lighthouse).
|
||||
|
||||
---
|
||||
|
||||
@ -93,7 +96,7 @@ up to date.
|
||||
|
||||
### 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
|
||||
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.
|
||||
@ -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
|
||||
```
|
||||
|
||||
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
|
||||
moving the slashing protection database. If you have imported your keys into a new node, you should
|
||||
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
|
||||
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
|
||||
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
|
||||
is approximately equal to the rewards earned in a day. You will get slashed if you use
|
||||
`--init-slashing-protection` incorrectly.
|
||||
|
||||
@ -1,14 +1,12 @@
|
||||
# Suggested Fee Recipient
|
||||
|
||||
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
|
||||
or is due to merge soon then you should nominate a fee recipient for your validators.
|
||||
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.
|
||||
|
||||
## Background
|
||||
|
||||
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
|
||||
coinbase and the recipient of other fees or rewards.
|
||||
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.
|
||||
|
||||
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
|
||||
@ -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
|
||||
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
|
||||
a separate fee recipient address.
|
||||
a fee recipient address.
|
||||
|
||||
@ -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.
|
||||
@ -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`.
|
||||
@ -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.
|
||||
|
||||
> 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
|
||||
> uses Teku, Lighthouse's Doppelganger Protection cannot yet be used with Infura's Eth2 service.
|
||||
> validator client, the client must be connected to a Lighthouse beacon node.
|
||||
|
||||
## 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
|
||||
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
|
||||
*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.
|
||||
|
||||
**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:
|
||||
|
||||
- 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
|
||||
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:
|
||||
|
||||
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.
|
||||
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,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.
|
||||
@ -1,10 +1,10 @@
|
||||
# Validator Management
|
||||
|
||||
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
|
||||
validators it will act for and how it should obtain their cryptographic
|
||||
validators it will act for and how it obtains their cryptographic
|
||||
signatures.
|
||||
|
||||
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
|
||||
validator "enabled".
|
||||
- `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_password_path`: The path to the password for 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
|
||||
|
||||
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
|
||||
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
|
||||
@ -71,7 +71,7 @@ recap:
|
||||
|
||||
### 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_definitions.yml` with `enabled: true`.
|
||||
|
||||
@ -89,7 +89,7 @@ name identical to the `voting_public_key` value.
|
||||
|
||||
#### Discovery Example
|
||||
|
||||
Lets assume the following directory structure:
|
||||
Let's assume the following directory structure:
|
||||
|
||||
```
|
||||
~/.lighthouse/{network}/validators
|
||||
@ -158,7 +158,7 @@ start.
|
||||
|
||||
If a validator client were to start using the [first example
|
||||
`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
|
||||
@ -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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
@ -38,7 +38,7 @@ minutes after start up.
|
||||
#### Example
|
||||
|
||||
```
|
||||
lighthouse bn --staking --validator-monitor-auto
|
||||
lighthouse bn --http --validator-monitor-auto
|
||||
```
|
||||
|
||||
### Manual
|
||||
|
||||
@ -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 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.
|
||||
|
||||
@ -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.
|
||||
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
|
||||
|
||||
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 `--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.
|
||||
|
||||
@ -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
|
||||
validator-dir path: ~/.lighthouse/prater/validators
|
||||
validator-dir path: ~/.lighthouse/goerli/validators
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
||||
PLEASE VISIT https://lighthouse-book.sigmaprime.io/voluntary-exit.html
|
||||
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
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user