Validator on-boarding docs (#656)

* Add first draft of validator onboarding * Update docs * Add documentation link to main README * Continue docs development * Update book readme * Update docs * Allow vc to run without testnet subcommand * Small change to onboarding docs * Tidy CLI help messages * Update docs * Add check to val client see if beacon node is synced * Add notifier service to validator client * Re-order onboarding steps * Update deposit contract address * Update testnet dir * Add note about public eth1 node * Set default eth1 endpoint to sigp * Fix broken test * Try fix eth1 cache locking * Be more specific about eth1 endpoint * Increase gas limit for deposit * Fix default deposit amount
2026-05-08 01:05:47 +00:00 · 2019-12-09 22:42:36 +11:00
parent f1edca30ff
commit 3c6c06a505
19 changed files with 548 additions and 57 deletions
--- a/book/README.md
+++ b/book/README.md
@@ -3,7 +3,7 @@
 Contains an [mdBook](https://github.com/rust-lang-nursery/mdBook) that serves
 as the primary source of Lighthouse user documentation.

-The book is hosted at [lighthouse-book.sigmaprime.io](http://lighthouse-book.sigmaprime.io).
+The book is hosted at [lighthouse-book.sigmaprime.io](http://lighthouse-book.sigmaprime.io).i

 ## Usage

@@ -14,4 +14,4 @@ best source of information for building the book.

 1. Install mdBook: `$ cargo install mdbook`
 1. Build the book, open it in a browser and build after file changes: `$ mdbook
-   watch --open`
+   serve --open`
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -1,7 +1,8 @@
 # Summary

 * [Introduction](./intro.md)
-* [Installation](./installation.md)
+* [Become a Validator](./become-a-validator.md)
+* [Introduction](./intro.md)
    * [Docker](./docker.md)
 * [CLI](./cli.md)
    * [Testnets](./testnets.md)
--- a/book/src/become-a-validator.md
+++ b/book/src/become-a-validator.md
@@ -0,0 +1,179 @@
+# Become an Ethereum 2.0 Validator*
+
+_* Testnet validator_
+
+Running Lighthouse validator is easy if you're familiar with the terminal. It
+runs on Linux, MacOS and Windows.
+
+Before you start, you'll need [Metamask](https://metamask.io/) and 3.2 gETH
+(Goerli ETH). We recommend the [mudit.blog
+faucet](https://faucet.goerli.mudit.blog/) for those familiar with Goerli, or
+[goerli.net](https://goerli.net/) for an overview of the testnet.
+
+### 1. Download and install Lighthouse
+
+If you already have Rust installed, you can install Lighthouse with the
+following three commands:
+
+- `$ git clone https://github.com/sigp/lighthouse.git`
+- `$ cd lighthouse`
+- `$ make`
+
+You've completed this step when you can run `$ lighthouse --help` and see the
+help menu.
+
+> - If you're not familiar with Rust or you'd like more detailed instructions, see
+>   the [Installation Guide](./installation.md).
+> - The [Docker Guide](./docker.md) is great if you have Docker installed and would
+>   like to avoid installing Rust.
+
+### 2. Start your Beacon Node
+
+The beacon node is the core component of Eth2, it connects to other peers over
+the Internet and maintains a view of the chain.
+
+Start your beacon node with:
+
+```bash
+$ lighthouse beacon --eth1 --http
+```
+
+You're beacon node has started syncing when you see the following (truncated)
+log:
+
+```
+Dec 09 12:57:18.026 INFO Syncing                                 distance: 16837 slots (2 days 8 hrs), ...
+```
+
+It has finished syncing once you see the following (truncated) log:
+
+```
+Dec 09 12:27:06.010 INFO Synced                                  slot: 16835, ...
+```
+
+> - The `--http` flag enables the HTTP API for the validator client.
+> - The `--eth1` flag tells the beacon node that it should sync with an Ethereum
+>   1 node (e.g., Geth). This is only required if you wish to run a validator.
+> - We are hosting a public Goerli archive node and have set this as the
+>   default, but you can specify your own Eth1 node using the `--eth1-endpoint`
+>   flag. Presently we require the node to be a full archive node, but we're
+>   working to [fix](https://github.com/sigp/lighthouse/issues/637) this.
+
+### 3. Generate your validator key
+
+Generate new validator BLS keypairs using:
+
+```shell
+$ lighthouse account validator new random
+```
+
+
+You've completed this step when you see the equivalent line:
+
+```
+Dec 02 21:42:01.337 INFO Generated validator directories         count: 1, base_path: "/home/karl/.lighthouse/validators"
+```
+
+> - This will generate a new _validator directory_ in the `.lighthouse/validators`
+>   directory. Your validator directory will be identified by it's public key,
+>   which looks something like `0xc483de...`. You'll need to find this directory
+>   for the next step.
+> - These keys are good enough for the Lighthouse testnet, however they shouldn't
+>   be considered secure until we've undergone a security audit (planned Jan
+>   2020).
+
+### 4. Start your validator client
+
+For security reasons, the validator client runs separately to the beacon node.
+The validator client stores private keys and signs messages generated by the
+beacon node.
+
+You'll need both your beacon node _and_ validator client running if you want to
+stake.
+
+Start the validator client with:
+
+```bash
+$ lighthouse validator
+```
+
+The validator client is running and has found your validator keys from step 3
+when you see the following log:
+
+```
+Dec 09 13:08:59.171 INFO Loaded validator keypair store          voting_validators: 1
+Dec 09 13:09:09.000 INFO Awaiting activation                     slot: 17787, ...
+```
+
+If your beacon node hasn't finished syncing yet, you'll see some `ERRO`
+messages indicating that your node isn't synced yet. It is safest to wait for
+your node to sync before moving onto the next step, otherwise your validator
+may active before you're able to produce blocks and attestations. However, it
+generally takes 4-8+ hours after deposit for a validator to become active. If
+your `est_time` is less than 4 hours, you _should_ be fine to just move to the
+next step. After all, this is a testnet and you're only risking Goerli ETH.
+
+### 5. Submit your deposit
+
+<div class="form-signin" id="uploadDiv">
+	<p>Upload the <code>eth1_deposit_data.rlp</code> file from your validator
+	directory (created in step 3) to submit your 3.2 Goerli-ETH
+	deposit using Metamask.</p>
+	<p>Hint: it's generally in the <code>$HOME/.lighthouse/validators/0x...</code> directory</p>
+	<input id="fileInput" type="file" style="display: none">
+	<button id="uploadButton" class="btn btn-lg btn-primary btn-block"
+							  type="submit">Upload and Submit Deposit</button>
+</div>
+
+<div class="form-signin" id="waitingDiv" style="display: none">
+	<p>Your validator deposit was submitted and this step is complete.</p>
+	<p>See the transaction on <a id="txLink" target="_blank"
+											 href="https://etherscan.io">Etherscan</a>
+	or <a href="">reload</a> to perform another deposit.</p>
+</div>
+
+<div class="form-signin" id="errorDiv" style="display: none">
+	<h4 class="h3 mb-3 font-weight-normal">Error</h4>
+	<p id="errorText">Unknown error.</p>
+</div>
+
+> This deposit is using gETH (Goerli ETH) which has no real value. Don't ever
+> send _real_ ETH to our deposit contract!
+
+## Next steps
+
+Leave your beacon node and validator client running and you'll see logs as the
+beacon node keeps synced with the network and the validator client produces
+blocks and attestations.
+
+It will take some time (minutes to 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 slot:
+
+```
+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 slot, it's less common to produce a
+block. Watch for the block production logs too:
+
+```
+Dec 03 08:49:36.225 INFO Successfully published block            slot: 98, attestations: 2, deposits: 0, service: block
+```
+
+If you see any `ERRO` (error) logs, please reach out on
+[Discord](https://discord.gg/cyAszAh) or [create an
+issue](https://github.com/sigp/lighthouse/issues/new).
+
+Happy staking!
+
+
+
+
+<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
+<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script>
+<script charset="utf-8"
+		src="https://cdn.ethers.io/scripts/ethers-v4.min.js"
+		type="text/javascript">
+</script>
+<script src="js/deposit.js"></script>
--- a/book/src/js/deposit.js
+++ b/book/src/js/deposit.js
@@ -0,0 +1,127 @@
+const NETWORK = "5";
+const NETWORK_NAME = "Goerli Test Network";
+const DEPOSIT_CONTRACT = "0x13e4d66c7215d7b63fec7b52fc65e6655093d906";
+const DEPOSIT_AMOUNT_ETH = "3.2";
+const GAS_LIMIT = "4000000";
+const DEPOSIT_DATA_BYTES = 420;
+
+let PREVIOUS_NON_ERROR_STATE = "";
+
+$(document).ready(function(){
+	if (typeof window.ethereum !== 'undefined') {
+		ethereum.on('networkChanged', function (accounts) {
+			checkNetwork()
+		})
+
+		PREVIOUS_NON_ERROR_STATE = "upload";
+		checkNetwork()
+	} else {
+		console.error("No metamask detected!")
+		triggerError("Metamask is not installed.<br> <a href='https://metamask.io'>Get Metamask.</a>")
+	}
+
+	$("#fileInput").change(function() {
+			openFile(this.files[0])
+	});
+
+	$("#uploadButton").on("click", function() {
+		$("#fileInput").trigger("click");
+	});
+});
+
+function checkNetwork() {
+		if (window.ethereum.networkVersion === NETWORK) {
+			setUiState(PREVIOUS_NON_ERROR_STATE)
+		} else {
+			triggerError("Please set Metamask to use " + NETWORK_NAME + ".")
+		}
+}
+
+function doDeposit(deposit_data) {
+	const ethereum = window.ethereum;
+	const utils = ethers.utils;
+
+	let wei = utils.parseEther(DEPOSIT_AMOUNT_ETH);
+	let gasLimit = utils.bigNumberify(GAS_LIMIT);
+
+	ethereum.enable()
+		.then(function (accounts) {
+			let params = [{
+				"from": accounts[0],
+				"to": DEPOSIT_CONTRACT,
+				"gas": utils.hexlify(gasLimit),
+				"value": utils.hexlify(wei),
+				"data": deposit_data
+			}]
+
+			ethereum.sendAsync({
+				method: 'eth_sendTransaction',
+				params: params,
+				from: accounts[0], // Provide the user's account to use.
+			}, function (err, result) {
+				if (err !== null) {
+					triggerError("<p>" + err.message + "</p><p><a href=''>Reload</a> the window to try again.</p>")
+				} else {
+					let tx_hash = result.result;
+					$("#txLink").attr("href", "https://goerli.etherscan.io/tx/" + tx_hash);
+					setUiState("waiting");
+				}
+			})
+		})
+		.catch(function (error) {
+			triggerError("Unable to get Metamask accounts.<br>Reload page to try again.")
+		})
+
+}
+
+function openFile(file) {
+  var reader = new FileReader();
+
+	reader.onload = function () {
+		let data = reader.result;
+		if (data.startsWith("0x")) {
+			if (data.length === DEPOSIT_DATA_BYTES * 2 + 2) {
+				doDeposit(data)
+			} else {
+				triggerError("Invalid eth1_deposit_file. Bad length.")
+			}
+		} else {
+			triggerError("Invalid eth1_deposit_file. Did not start with 0x.")
+		}
+  }
+
+  reader.readAsBinaryString(file);
+}
+
+function triggerError(text) {
+	$("#errorText").html(text);
+	setUiState("error");
+}
+
+function setUiState(state) {
+	if (state === "upload") {
+		$('#uploadDiv').show();
+		$('#depositDiv').hide();
+		$('#waitingDiv').hide();
+		$('#errorDiv').hide();
+	} else if (state == "deposit") {
+		$('#uploadDiv').hide();
+		$('#depositDiv').show();
+		$('#waitingDiv').hide();
+		$('#errorDiv').hide();
+	} else if (state == "error") {
+		$('#uploadDiv').hide();
+		$('#depositDiv').hide();
+		$('#waitingDiv').hide();
+		$('#errorDiv').show();
+	} else if (state == "waiting") {
+		$('#uploadDiv').hide();
+		$('#depositDiv').hide();
+		$('#waitingDiv').show();
+		$('#errorDiv').hide();
+	}
+
+	if (state !== "error") {
+		PREVIOUS_NON_ERROR_STATE = state;
+	}
+}