Update Merge testnet tutorial (#1022)

* [WIP] Update Merge testnet tutorial Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * more updates Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * more updates Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * vale fix Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * minor updates Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * minor update Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * minor changes Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * remove space Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net>
hyperledger · Apr 20, 2022 · 1e00a2d · 1e00a2d
1 parent c3f3f09
commit 1e00a2d
Show file tree

Hide file tree

Showing 4 changed files with 120 additions and 41 deletions.
diff --git a/docs/Concepts/Merge.md b/docs/Concepts/Merge.md
@@ -16,19 +16,25 @@ After The Merge, a full Ethereum Mainnet node will be a combination of an execut
 [Ethereum 1.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client) and a consensus client (previously
 called an [Ethereum 2.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client).
 
+Execution and consensus clients communicate with each other using the
+[Engine API](../HowTo/Interact/APIs/Engine-API.md).
+
+![Ethereum Merge node](../images/Execution-Consensus-Clients.png)
+
+### Execution clients
+
 Execution clients, such as Besu, manage the state and execute transactions on the execution layer.
+Execution clients serve [JSON-RPC API](../Reference/Engine-API-Methods.md) requests and communicate with each other in a
+peer-to-peer network.
+
+### Consensus clients
+
 Consensus clients, such as [Teku], contain beacon node and validator client implementations.
 The beacon node is the primary link to the [Beacon Chain] (consensus layer).
 The validator client performs [validator duties](https://docs.teku.consensys.net/en/latest/Concepts/Proof-of-Stake/) on
 the consensus layer.
-
-Execution and consensus clients communicate with each other using the
-[Engine API](../HowTo/Interact/APIs/Engine-API.md).
-Execution clients serve [JSON-RPC API](../Reference/Engine-API-Methods.md) requests and consensus clients serve
-[REST API](https://docs.teku.consensys.net/en/stable/Reference/Rest_API/Rest/) requests.
-Execution clients communicate among each other in a peer-to-peer network, and consensus clients do the same.
-
-![Ethereum Merge node](../images/Execution-Consensus-Clients.png)
+Consensus clients serve [REST API](https://docs.teku.consensys.net/en/stable/Reference/Rest_API/Rest/) requests and
+communicate with each other in a peer-to-peer network.
 
 ### Run a node
 

diff --git a/docs/HowTo/Get-Started/Starting-node.md b/docs/HowTo/Get-Started/Starting-node.md
@@ -152,7 +152,7 @@ Where `<path>` and `<goerlidata-path>` are the path and directory to save the Go
 
 You can [test Besu as an execution client](../../Tutorials/Merge-Testnet.md#start-besu) on the
 [Kiln Merge testnet](https://blog.ethereum.org/2022/03/14/kiln-merge-testnet/).
-You must also run a [consensus client](../../Concepts/Merge.md#execution-and-consensus-clients) with Besu on the Merge
+You must also run a [consensus client](../../Concepts/Merge.md#consensus-clients) with Besu on the Merge
 testnet.
 For example, [Teku](https://docs.teku.consensys.net/en/stable/).
 

diff --git a/docs/Tutorials/Merge-Testnet.md b/docs/Tutorials/Merge-Testnet.md
@@ -2,30 +2,56 @@
 Description: How to run Besu and Teku on the Merge testnet
 ---
 
-# Run clients on the Merge testnet
+# Run Besu and Teku on the Merge testnet
 
-You can test Besu as an [execution client](../Concepts/Merge.md) and [Teku](https://docs.teku.consensys.net/en/stable/)
-as a [consensus client](../Concepts/Merge.md) on the [Kiln Merge testnet](https://blog.ethereum.org/2022/03/14/kiln-merge-testnet/).
+You can test Besu as an [execution client](../Concepts/Merge.md#execution-clients) and
+[Teku](https://docs.teku.consensys.net/en/stable/)
+as a [consensus client](../Concepts/Merge.md#consensus-clients) on the
+[Kiln Merge testnet](https://blog.ethereum.org/2022/03/14/kiln-merge-testnet/).
 
-## Prerequisites
+## 1. Install Besu and Teku
 
-- Install [Besu](../HowTo/Get-Started/Installation-Options/Options.md) and
-   [Teku](https://docs.teku.consensys.net/en/stable/HowTo/Get-Started/Installation-Options/Install-Binaries/).
+Install [Besu](../HowTo/Get-Started/Installation-Options/Install-Binaries.md) and
+[Teku](https://docs.teku.consensys.net/en/stable/HowTo/Get-Started/Installation-Options/Install-Binaries/).
 
-- Generate the JWT secret:
+Ensure you meet the prerequisites for the installation option you use.
+For example, you must have Java version 11–16 if using the Besu and Teku binary distributions.
 
-    ```bash
-    openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex
-    ```
+Ensure you meet the [system requirements for Besu on Mainnet](../HowTo/Get-Started/System-Requirements).
 
-    You must pass this file to both Besu and Teku.
-    This is a shared secret the clients use to authenticate each other when using the Engine API.
+## 2. Generate the shared secret
 
-- Create a test Ethereum address to use as the
-  [default fee recipient](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#validators-proposer-default-fee-recipient)
-  when starting Teku.
+Run the following command:
+
+```bash
+openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex
+```
+
+You will specify `jwtsecret.hex` when starting both Besu and Teku.
+This is a shared JWT secret the clients use to authenticate each other when using the
+[Engine API](../HowTo/Interact/APIs/Engine-API.md).
+
+## 3. Generate validator keys and stake ETH
+
+If you're running a [validator client](#beacon-node-and-validator-client), create a test Ethereum address (you can do
+this in
+[MetaMask](https://metamask.zendesk.com/hc/en-us/articles/360015289452-How-to-create-an-additional-account-in-your-wallet)).
+Fund this address with testnet ETH using the [Kiln Faucet](https://faucet.kiln.themerge.dev/).
+
+!!! note
 
-## Start Besu
+    If you're unable to get ETH using the faucet, you can ask for help on the
+    [EthStaker Discord](https://discord.io/ethstaker).
+
+Generate validator keys and stake your testnet ETH for one or more validators using the
+[Kiln Staking Launchpad](https://kiln.launchpad.ethereum.org/en/).
+
+!!! important
+
+    Save the password you use to generate each key pair in a `.txt` file.
+    You should also have a `.json` file for each validator key pair.
+
+## 4. Start Besu
 
 Run the following command:
 
@@ -43,31 +69,74 @@ besu \
   --engine-rpc-http-port=8550 \
   --engine-rpc-ws-port=8551   \
   --Xmerge-support=true       \
-  --engine-jwt-secret=<path_to_jwtsecret>
+  --engine-jwt-secret=<path to jwtsecret.hex>
 ```
 
-See the [`--engine-*`](../Reference/CLI/CLI-Syntax.md#engine-host-allowlist) CLI options for more information on running
+Specify the path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the
+[`--engine-jwt-secret`](../Reference/CLI/CLI-Syntax.md#engine-jwt-secret) option.
+
+See the [`--engine-*`](../Reference/CLI/CLI-Syntax.md#engine-host-allowlist) options for more information on running
 Besu as an execution client.
 
-## Start Teku
+## 5. Start Teku
 
-Run the following command:
+Open a new terminal window.
+
+### Beacon node only
+
+To run Teku as a beacon node (without validator duties), run the following command:
 
 ```bash
 teku \
-  --data-path "datadir-teku"               \
-  --network kiln                           \
-  --p2p-discovery-bootnodes "enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk" \
-  --ee-endpoint http://localhost:8550      \
-  --Xee-version kilnv2                     \
-  --ee-jwt-secret-file <path_to_jwtsecret> \
-  --log-destination console                \
-  --validators-proposer-default-fee-recipient=<eth_address_of_default_fee_recipient>
+  --data-path "datadir-teku"                   \
+  --network kiln                               \
+  --ee-endpoint http://localhost:8550          \
+  --Xee-version kilnv2                         \
+  --ee-jwt-secret-file <path to jwtsecret.hex> \
+  --log-destination console                    \
+  --rest-api-enabled=true                      \
+  --p2p-discovery-bootnodes "enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk"
 ```
 
-This runs Teku as a beacon node (without validator duties).
-See the Teku [`--validators-*`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#validator-keys) CLI
-options for information on running Teku as a validator.
+Specify the path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using
+the [`--ee-jwt-secret-file`](https://docs.teku.consensys.net/en/stable/Reference/CLI/CLI-Syntax/#ee-jwt-secret-file)
+option.
+
+### Beacon node and validator client
+
+To run Teku as a beacon node and validator in a single process, run the following command:
+
+```bash
+teku \
+  --data-path "datadir-teku"                                \
+  --network kiln                                            \
+  --ee-endpoint http://localhost:8550                       \
+  --Xee-version kilnv2                                      \
+  --ee-jwt-secret-file <path to jwtsecret.hex>              \
+  --log-destination console                                 \
+  --rest-api-enabled=true                                   \
+  --validators-proposer-default-fee-recipient=<ETH address> \
+  --validator-keys=<path to key file>:<path to mnemonic file>[,<path to key file>:<path to mnemonic file>,...] \
+  --p2p-discovery-bootnodes "enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk"
+```
+
+Specify:
+
+- The path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the
+  [`--ee-jwt-secret-file`](https://docs.teku.consensys.net/en/stable/Reference/CLI/CLI-Syntax/#ee-jwt-secret-file) option.
+- The test Ethereum address created in [step 3](#3-generate-validator-keys-and-stake-eth) as the default fee recipient
+  using the
+  [`--validators-proposer-default-fee-recipient`](https://docs.teku.consensys.net/en/stable/Reference/CLI/CLI-Syntax/#validators-proposer-default-fee-recipient)
+  option.
+- The paths to the keystore `.json` file and password `.txt` file created in
+  [step 3](#3-generate-validator-keys-and-stake-eth) for each validator using the
+  [`--validator-keys`](https://docs.teku.consensys.net/en/stable/Reference/CLI/CLI-Syntax/#validator-keys) option.
+  Separate the `.json` and `.txt` files with a colon, and separate entries for multiple validators with commas.
+
+See the Teku [`--validators-*`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#validator-keys)
+options for more information on running Teku as a validator.
+
+## 6. Check validator status
 
 After starting Besu and Teku, your node should start syncing and connecting to peers.
 
@@ -92,3 +161,7 @@ After starting Besu and Teku, your node should start syncing and connecting to p
         2022-03-21 20:44:00.339 INFO  - Syncing     *** Target slot: 76095, Head slot: 3317, Remaining slots: 72778, Connected peers: 6
         2022-03-21 20:44:12.353 INFO  - Syncing     *** Target slot: 76096, Head slot: 3519, Remaining slots: 72577, Connected peers: 9
         ```
+
+You can check your validator status by searching your Ethereum address on the
+[Kiln Beacon Chain explorer](https://beaconchain.kiln.themerge.dev/).
+It may take up to multiple days for your validator to reach `active` status.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -185,7 +185,7 @@ nav:
           - Production: Tutorials/Kubernetes/Production.md
           - Configure Kubernetes mode in NAT Manager : Tutorials/Kubernetes/Nat-Manager-Kubernetes.md
       - Deploy on Microsoft Azure: Tutorials/Private-Network-Example-Azure.md
-      - Run clients on the Merge testnet: Tutorials/Merge-Testnet.md
+      - Run Besu and Teku on the Merge testnet: Tutorials/Merge-Testnet.md
     - Concepts:
         - Architecture: Concepts/ArchitectureOverview.md
         - Consensus protocols: