doc updates

* optimise index / landing page real estate, add feature list
* fee recipient in quickstart
* recommend http over websockets  (fewer command line options needed)
* simplify PBS, fee recipient docs
* add VC role / sentry node docs (#4140)

docs/the_nimbus_book/mkdocs.yml

@@ -39,7 +39,6 @@ nav:
   - About:
     - 'index.md'
     - 'philosophy.md'
-    - 'preparation.md'
 
   - Getting started:
     - 'quick-start.md'
@@ -83,29 +82,33 @@ nav:
       - 'prater.md'
 
   - Security:
+    - 'preparation.md'
     - 'security_issues.md'
     - 'audit.md'
     - 'distribution_internals.md'
 
   - Reference:
     - 'hardware.md'
-    - 'options.md'
-    - 'networking.md'
-    - 'optimistic-sync.md'
-    - 'logging.md'
-    - 'validator-monitor.md'
-    - 'attestation-performance.md'
-    - 'rest-api.md'
-    - 'keymanager-api.md'
-    - 'data-dir.md'
-    - 'era-store.md'
+    - Advanced options:
+      - 'options.md'
+      - 'networking.md'
+      - 'optimistic-sync.md'
+      - 'light-client-data.md'
+      - 'logging.md'
+      - 'validator-client-options.md'
+      - 'validator-monitor.md'
+    - "REST API:s":
+      - 'rest-api.md'
+      - 'keymanager-api.md'
+    - Storage:
+      - 'data-dir.md'
+      - 'era-store.md'
     - 'migration-options.md'
-    - 'light-client-data.md'
+    - 'attestation-performance.md'
     - 'troubleshooting.md'
+    - 'faq.md'
     - 'developers.md'
     - 'resources.md'
-    - 'faq.md'
-    - 'api.md'
     - 'contribute.md'
 
   - Downloads:

docs/the_nimbus_book/src/attestation-performance.md

@@ -1,4 +1,4 @@
-# Attestation performance analysis
+# Attestation performance
 
 `ncli_db validatorPerf` is an advanced tool that helps you analyze the performance of your validator over time.
 

docs/the_nimbus_book/src/connect-eth2.md

@@ -1,22 +1,28 @@
 # Start validating
 
-Once your keys have been [imported](./keys.md), it is time to restart the beacon node and start validating!
+Once your keys have been [imported](./keys.md), it is time to configure a [fee recipient](./suggested-fee-recipient.md and restart the beacon node to start validating!
 
-## (Re)start the node
+## Steps
 
-Press `Ctrl-c` to stop the beacon node if it's running, then use the same command as before to run it again:
+### 1. Choose a fee recipient
+
+The [fee recipient](./suggested-fee-recipient.md) is an Ethereum address that receives transaction fees from the blocks that your validators produce. You can set up a separate address or reuse the address from which you funded your deposits.
+
+### 2. (Re)start the node
+
+Press `Ctrl-c` to stop the beacon node if it's running, then use the same command [as before]() to run it again, this time adding the `--suggested-fee-recipient` option in addition to `--web3-url`:
 
 === "Mainnet"
     ```sh
-    ./run-mainnet-beacon-node.sh
+    ./run-mainnet-beacon-node.sh --web3-url=http://127.0.0.1:8551 --suggested-fee-recipient=0x...
     ```
 
 === "Prater"
     ```sh
-    ./run-prater-beacon-node.sh
+    ./run-prater-beacon-node.sh --web3-url=http://127.0.0.1:8551 --suggested-fee-recipient=0x...
     ```
 
-## Check the logs
+### 3. Check the logs
 
 Your beacon node will launch and connect your validator to the beacon chain network. To check that keys were imported correctly, look for `Local validator attached` in the logs:
 

docs/the_nimbus_book/src/deposit.md

@@ -2,7 +2,7 @@
 
 To make a deposit, you will need to generate keys then submit a deposit transaction to the execution chain.
 
-!!! tip
+!!! tip "Launchpad"
     The process of setting up a validator is also documented at the Ethereum launchpad site:
 
     * [Mainnet](https://launchpad.ethereum.org/)
@@ -11,7 +11,9 @@ To make a deposit, you will need to generate keys then submit a deposit transact
 !!! tip
     Use Prater to stress test / future proof  your set up against peak mainnet load. See [here](./prater.md) for all you need to know
 
-## Download the deposit tool
+## Steps
+
+### 1. Download the deposit tool
 
 Start by downloading and unpacking the [deposit tool](https://github.com/ethereum/staking-deposit-cli/releases/latest) provided by the Ethereum Foundation:
 
@@ -26,14 +28,14 @@ wget https://github.com/ethereum/staking-deposit-cli/releases/download/v2.2.0/st
 tar xvf staking_deposit-cli-9ab0b05-linux-amd64.tar.gz --strip-components 2
 ```
 
-## Generate keys
+### 2. Generate keys
 
-!!! tip
+!!! tip "Live image"
     You can increase the security of this process by downloading a [Live linux image](https://ubuntu.com/tutorials/try-ubuntu-before-you-install). To do so, copy `deposit` to a USB stick, boot into the live image, and run the tool from inside the image. Make sure you **don't** enable Wifi and unplug any Ethernet cables when using this process.
 
 The deposit tool generates a seed phrase, and uses this to create validator and withdrawal keys.
 
-!!! danger
+!!! danger "Seed phrase"
     If you lose you seed phrase and your withdrawal key, your funds will be lost forever!
 
 === "Mainnet"
@@ -48,7 +50,7 @@ The deposit tool generates a seed phrase, and uses this to create validator and
     ./deposit new-mnemonic --chain prater
     ```
 
-## Make the deposit
+### 3. Make the deposit
 
 Once created, the keys are used to create a deposit transaction on the Ethereum execution chain. Follow the instructions at https://launchpad.ethereum.org/en/upload-deposit-data to upload the deposit data.
 

docs/the_nimbus_book/src/developers.md

@@ -4,6 +4,12 @@ This page contains tips and tricks for developers, further resources, along with
 
 Before building Nimbus for the first time, make sure to install the [prerequisites](./install.md).
 
+## Helpful resources
+
+* [Ethereum consensus spec](https://github.com/ethereum/consensus-specs/)
+* [Ben Edgington's annotated spec](hhttps://eth2book.info/bellatrix/)
+* [Vitalik's annotated spec](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md)
+
 ## Code style
 
 The code follows the [Status Nim Style Guide](https://status-im.github.io/nim-style-guide/).

docs/the_nimbus_book/src/el-light-client.md

@@ -3,9 +3,9 @@
 !!! warning
     The light client is currently in BETA and details around running it may change.
 
-The Nimbus Light Client is a light-weight alternative to running a full beacon node, when setting up an Ethereum execution client for read-only use cases after the merge.
+The Nimbus Light Client is a light-weight alternative to running a full beacon node, when you're not planning on becoming a validator but still want to run an Ethereum execution layer client.
 
-Execution layer (EL) clients provide the [web3 API](https://ethereum.github.io/execution-apis/api-documentation/) to expose information stored on the Ethereum blockchain. Post-merge 🐼, EL clients can no longer run standalone and require an external component to determine the latest state to sync to.
+Execution layer (EL) clients provide the [web3 API](https://ethereum.github.io/execution-apis/api-documentation/) to expose information stored on the Ethereum blockchain. Since the merge 🐼, execution clients can no longer run standalone.
 
 ## Comparison
 
@@ -69,12 +69,12 @@ In addition to the [regular instructions](./eth1.md) to run an EL client, the JW
 
     === "Mainnet"
         ```sh
-        geth --ws --authrpc.jwtsecret="$HOME/jwtsecret"
+        geth --authrpc.jwtsecret="$HOME/jwtsecret"
         ```
 
     === "Goerli"
         ```sh
-        geth --goerli --ws --authrpc.jwtsecret="$HOME/jwtsecret"
+        geth --goerli --authrpc.jwtsecret="$HOME/jwtsecret"
         ```
 
 === "Nethermind"
@@ -123,15 +123,15 @@ To start the light client, run the following commands (inserting your own truste
     ```sh
     TRUSTED_BLOCK_ROOT=0x1234567890123456789012345678901234567890123456789012345678901234
     build/nimbus_light_client \
-        --web3-url=ws://127.0.0.1:8551 --jwt-secret="$HOME/jwtsecret" \
+        --web3-url=http://127.0.0.1:8551 --jwt-secret="$HOME/jwtsecret" \
         --trusted-block-root=$TRUSTED_BLOCK_ROOT
     ```
 
 === "Goerli"
     ```sh
     TRUSTED_BLOCK_ROOT=0x1234567890123456789012345678901234567890123456789012345678901234
     build/nimbus_light_client --network=goerli \
-        --web3-url=ws://127.0.0.1:8551 --jwt-secret="$HOME/jwtsecret" \
+        --web3-url=http://127.0.0.1:8551 --jwt-secret="$HOME/jwtsecret" \
         --trusted-block-root=$TRUSTED_BLOCK_ROOT
     ```
 

docs/the_nimbus_book/src/eth1.md

@@ -32,17 +32,14 @@ Select an execution client and install it, configuring it such that that WebSock
 
     === "Mainnet"
         ```
-        geth --ws --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
+        geth --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
         ```
 
     === "Goerli"
         ```
-        geth --goerli --ws --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
+        geth --goerli --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
         ```
 
-    !!! note
-        The `--ws` flag allows Nimbus to connect using WebSockets.
-
     #### 3. Leave Geth running
 
     Let it syns - it may take anywhere between a few hours and a couple of days.
@@ -62,19 +59,19 @@ Select an execution client and install it, configuring it such that that WebSock
 
     See the [Getting started](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/getting-started) guide to set up Nethermind.
 
-    Make sure to enable the [JSON-RPC](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge#jsonrpc-configuration-module) interface over WebSockets, and pass `--JsonRpc.JwtSecretFile=/tmp/jwtsecret` to select a JWT secret file location.
+    Make sure to enable the [JSON-RPC](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge#jsonrpc-configuration-module) interface and pass `--JsonRpc.JwtSecretFile=/tmp/jwtsecret` to select a JWT secret file location.
 
 === "Besu"
 
     See the [Besu documentation](https://besu.hyperledger.org/en/stable/) for instructions on setting up Besu.
 
-    Make sure to enable the [JSON-RPC](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API/) WebSocket interface and store the JWT token in `/tmp/jwtsecret`.
+    Make sure to enable the [JSON-RPC](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API/) interface and store the JWT token in `/tmp/jwtsecret`.
 
 === "Erigon"
 
     See the [Erigon README](https://github.com/ledgerwatch/erigon#getting-started) for instructions on setting up Erigon.
 
-    Make sure to enable the [JSON-RPC](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer) WebSocket interface and use `--authrpc.jwtsecret=/tmp/jwtsecret` to set a path to the JWT token file.
+    Make sure to enable the [JSON-RPC](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer) interface and use `--authrpc.jwtsecret=/tmp/jwtsecret` to set a path to the JWT token file.
 
 ### 2. Leave the execution client running
 
@@ -91,23 +88,23 @@ Once started, the execution client will create a file containing a JWT secret to
 === "Mainnet"
     ```sh
     ./run-mainnet-beacon-node.sh \
-      --web3-url=ws://127.0.0.1:8551 \
+      --web3-url=http://127.0.0.1:8551 \
       --jwt-secret=/tmp/jwtsecret
     ```
 
 === "Prater"
     ```sh
     ./run-prater-beacon-node.sh \
-      --web3-url=ws://127.0.0.1:8551 \
+      --web3-url=http://127.0.0.1:8551 \
       --jwt-secret=/tmp/jwtsecret
     ```
 
-!!! tip
+!!! tip "Multiple execution clients"
     You can pass one or more `--web3-url` parameters to the node as long as they share JWT secret. Any additional web3 url:s will be used for backup, should the first one become unavailable:
 
     ```sh
     ./run-mainnet-beacon-node.sh \
-      --web3-url=ws://127.0.0.1:8551 \
-      --web3-url=http://other:8551 \
+      --web3-url=http://127.0.0.1:8551 \
+      --web3-url=ws://other:8551 \
       --jwt-secret=/tmp/jwtsecret
     ```

docs/the_nimbus_book/src/external-block-builder.md

@@ -1,32 +1,47 @@
 # Set up block builders / MEV
 
-[Maximal extractable value](https://ethereum.org/en/developers/docs/mev/) involves consensus clients contacting an external block builder which might maximize profit or some other defined metric in ways hindered for a purely local consensus and execution client setup. This external builder network uses the [builder API](https://ethereum.github.io/builder-specs/) which consensus clients use to access external block builder bundles found by searchers. In exchange, such searchers and builders might choose to retain some of the profit gained from such bundles. A builder API relay provides access to multiple searchers via a single URL.
+Nimbus supports outsourcing block production to an external block builder, thus presenting the opportunity to capture [Maximal Extractable Value](https://ethereum.org/en/developers/docs/mev/) (MEV).
 
-Nimbus supports this API to access these external block builders. If one is configured, the block production flow becomes modified:
+When external block building is enabled, the beacon node connects to a service using the [builder API](https://ethereum.github.io/builder-specs/) with the execution client acting as a fallback.
 
-1. attempt to use the specified external block builder relay or builder to create an execution payload
-2. if the external block builder builder or relay doesn't function, and Nimbus has not signed a blinded beacon block, then fall back to existing local execution client to produce a block
+Setting up external block building involves running an additional service on your server and choosing one or more relays to do the actual building.
 
-There exists a failure mode, intrinsic to the builder API, wherein the consensus client has signed a blinded proposal and therefore even if the external block builder relay or builder doesn't provide a full block, a consensus client such as Nimbus cannot safely proceed with step 2 and fall back on its local execution client.
+!!! warning
+    External block builders introduce additional risk to the block building process which may cause loss of rewards.
+
+    In particular, once Nimbus has signed the block header proposed by the external builder, the execution client can no longer be used as fallback and the external builder is trusted to complete the building process.
 
 !!! note
-    By default, [priority and maximum gas fees](https://eips.ethereum.org/EIPS/eip-1559#abstract) determine transaction inclusion in blocks, but external block builders may use other strategies for transaction selection, which might involve regulatory constraints and extracted value. For further information, check the documentation of the block builder.
+    By default, [priority and maximum gas fees](https://eips.ethereum.org/EIPS/eip-1559#abstract) determine transaction inclusion in blocks.
+
+    External block builders may use other strategies for transaction selection, including regulatory constraints and extracted value. For further information, check the documentation of the block builder.
+
+## Command line
+
+External block building is enabled on both beacon node and [validator client](./validator-client.md) using the `--payload-builder=true` flag.
 
-## Command line option
+Additionally, the URL of the service exposing the [builder API](https://ethereum.github.io/builder-specs/) must be provided to the beacon node:
 
-=== "Mainnet"
+=== "Mainnet Beacon Node"
     ```sh
     ./run-mainnet-beacon-node.sh --payload-builder=true --payload-builder-url=https://${HOST}:${PORT}/
     ```
 
-=== "Prater"
+=== "Prater Beacon Node"
     ```sh
     ./run-prater-beacon-node.sh --payload-builder=true --payload-builder-url=https://${HOST}:${PORT}/
     ```
 
+=== "Validator Client"
+    ```sh
+    build/nimbus_validator_client --payload-builder=true
+    ```
+
 ## Useful resources
 
-- [MEV relay list](https://github.com/remyroy/ethstaker/blob/main/MEV-relay-list.md)
+- [EthStaker MEV setup guide](https://github.com/eth-educators/ethstaker-guides/blob/main/prepare-for-the-merge.md#choosing-and-configuring-an-mev-solution)
+
+- [EthStaker MEV relay list](https://ethstaker.cc/mev-relay-list/)
 
 - [Mainnet Relay Overview](https://beaconcha.in/relays)
 

docs/the_nimbus_book/src/graffiti.md

@@ -2,6 +2,8 @@
 
 You can use your node's graffiti flag to include a short text in the blocks that your node creates. You will be able to see it using the block explorer.
 
+## Command line
+
 === "Mainnet"
     ```sh
     ./run-mainnet-beacon-node.sh --graffiti="<YOUR_WORDS>"

docs/the_nimbus_book/src/index.md

@@ -1,33 +1,25 @@
 # The Nimbus Guide
 
 !!! note ""
-    If you're eager to get started, check out our [quickstart guide](./quick-start.md).
+    Eager to get started? The [quickstart guide](./quick-start.md) is for you.
 
     Coming from a different client? Check out the [migration guide](./migration.md).
 
-Nimbus is a client for the Ethereum `consensus layer` (eth2) and `execution layer` (eth1) that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and [easy to use](./run-a-validator.md).
-
-This book describes the consensus layer client, `nimbus-eth2`, in particular.
+Nimbus is a client for the Ethereum network that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and [easy to use](./run-a-validator.md).
 
 Its efficiency and low resource consumption allows it to perform well on all kinds of systems, ranging from Raspberry Pi's and mobile devices where it contributes to low power consumption and security -- to powerful servers where it leaves resources free to perform other tasks, such as running an [execution node](./eth1.md).
 
-</br>
-
-<blockquote class="twitter-tweet"><p lang="en" dir="ltr">&quot;just because it [Nimbus] is optimized to be minimally resource intensive, doesn&#39;t mean you can&#39;t run it on a server. It means that when you do run it on a server, it is consuming a lot less resources.&quot; <a href="https://t.co/F2sdZouBtD">https://t.co/F2sdZouBtD</a></p>&mdash; Nimbus (@ethnimbus) <a href="https://twitter.com/ethnimbus/status/1376836270245154817?ref_src=twsrc%5Etfw">March 30, 2021</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
-
-</br>
-
-This book explains the ways in which you can use Nimbus to either monitor the beacon chain or become a fully-fledged validator.
-
-!!! note
-    Staking and becoming a validator on Ethereum requires 32 ETH, a stable high-speed internet connection and an always-on server. Before staking, make sure that you understand the requirements and practice setting up a validator on a testnet. [Pooled staking](https://ethereum.org/en/staking/pools/) and [Staking as a service](https://ethereum.org/en/staking/saas/) are alternative ways to stake in the network. You can also run a Nimbus node without staking.
+This book describes the consensus layer client, [`nimbus-eth2`](https://github.com/status-im/nimbus-eth2). A execution client, [nimbus-eth1](https://github.com/status-im/nimbus-eth2), is also under development.
 
-## Helpful resources
+## Feature highlights
 
-- [Ethereum consensus spec](https://github.com/ethereum/consensus-specs/)
-- [Ben Edgington's annotated spec](https://benjaminion.xyz/eth2-annotated-spec/phase0/beacon-chain/)
-- [Vitalik's annotated spec](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md)
-- [Danny Ryan's annotated spec](https://notes.ethereum.org/@djrtwo/Bkn3zpwxB)
+* [Beacon node](./quick-start.md) with integrated validator client, slashing protection and doppelganger detection
+* Stand-alone [validator client](./validator-client.md) with [sentry node](./validator-client.md#sentry-node-setup) support
+* Fast [Beacon](./rest-api.md) and [KeyManager](./keymanager-api.md) API:s with extensions
+* [Web3Signer](https://docs.web3signer.consensys.net/en/latest/) remote signing
+* [Validator monitoring](./validator-monitor.md) and [performance analysis](./attestation-performance.md) tooling
+* [External block builder](./external-block-builder.md) (PBS / mev-boost) support with execution client fallback
+* [Light consensus client](./el-light-client,md) for running an execution client without a beacon node
 
 ## Get in touch