eth1 docs (#6680)

Minimal quickstart for setting up the execution client

* bump mkdocs to resolve a strange cython incompatibility

Author: arnetheduck

docs/requirements.in

@@ -1,2 +1,3 @@
 pip-tools
+pyyaml >= 6.0.1
 mkdocs-material

docs/requirements.txt

@@ -1,73 +1,95 @@
 #
-# This file is autogenerated by pip-compile with python 3.10
-# To update, run:
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
 #
 #    pip-compile requirements.in
 #
-build==0.8.0
+babel==2.16.0
+    # via mkdocs-material
+build==1.2.2.post1
     # via pip-tools
-click==8.1.3
+certifi==2024.8.30
+    # via requests
+charset-normalizer==3.4.0
+    # via requests
+click==8.1.7
     # via
     #   mkdocs
     #   pip-tools
+colorama==0.4.6
+    # via mkdocs-material
 ghp-import==2.1.0
     # via mkdocs
-importlib-metadata==4.12.0
-    # via mkdocs
+idna==3.10
+    # via requests
 jinja2==3.1.4
     # via
     #   mkdocs
     #   mkdocs-material
-markdown==3.3.7
+markdown==3.7
     # via
     #   mkdocs
     #   mkdocs-material
     #   pymdown-extensions
-markupsafe==2.1.1
-    # via jinja2
+markupsafe==3.0.2
+    # via
+    #   jinja2
+    #   mkdocs
 mergedeep==1.3.4
-    # via mkdocs
-mkdocs==1.3.1
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+mkdocs==1.6.1
     # via mkdocs-material
-mkdocs-material==8.3.9
+mkdocs-get-deps==0.2.0
+    # via mkdocs
+mkdocs-material==9.5.42
     # via -r requirements.in
-mkdocs-material-extensions==1.0.3
+mkdocs-material-extensions==1.3.1
     # via mkdocs-material
-packaging==21.3
+packaging==24.1
     # via
     #   build
     #   mkdocs
-pep517==0.12.0
-    # via build
-pip-tools==6.8.0
+paginate==0.5.7
+    # via mkdocs-material
+pathspec==0.12.1
+    # via mkdocs
+pip-tools==7.4.1
     # via -r requirements.in
-pygments==2.15.0
+platformdirs==4.3.6
+    # via mkdocs-get-deps
+pygments==2.18.0
     # via mkdocs-material
-pymdown-extensions==10.0
+pymdown-extensions==10.11.2
     # via mkdocs-material
-pyparsing==3.0.9
-    # via packaging
-python-dateutil==2.8.2
+pyproject-hooks==1.2.0
+    # via
+    #   build
+    #   pip-tools
+python-dateutil==2.9.0.post0
     # via ghp-import
-pyyaml==6.0
+pyyaml==6.0.2
     # via
+    #   -r requirements.in
     #   mkdocs
+    #   mkdocs-get-deps
     #   pymdown-extensions
     #   pyyaml-env-tag
 pyyaml-env-tag==0.1
     # via mkdocs
+regex==2024.9.11
+    # via mkdocs-material
+requests==2.32.3
+    # via mkdocs-material
 six==1.16.0
     # via python-dateutil
-tomli==2.0.1
-    # via
-    #   build
-    #   pep517
-watchdog==2.1.9
+urllib3==2.2.3
+    # via requests
+watchdog==5.0.3
     # via mkdocs
-wheel==0.38.1
+wheel==0.44.0
     # via pip-tools
-zipp==3.19.1
-    # via importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip

docs/the_nimbus_book/mkdocs.yml

@@ -61,6 +61,7 @@ nav:
     - 'quick-start.md'
     - 'run-a-validator.md'
     - 'el-light-client.md'
+    - 'execution-client.md'
     - 'pi-guide.md'
 
   - How-to:
@@ -80,6 +81,7 @@ nav:
       - 'additional-validator.md'
       - 'validator-client.md'
       - 'withdrawals.md'
+      - 'voluntary-exit.md'
 
     - General:
       - 'keep-updated.md'

docs/the_nimbus_book/src/eth1.md

@@ -19,8 +19,7 @@ Select an execution client and install it, configuring it such that that the aut
 
 === "Nimbus"
 
-    In parallel to `nimbus-eth2`, we are working hard on the [Nimbus execution client](https://github.com/status-im/nimbus-eth1).
-    While this is very much a project in development (i.e. not yet ready for public consumption), we welcome you to experiment with it.
+    See the [Nimbus execution client](./execution-client.md) for installation instructions.
 
 === "Geth"
 
@@ -112,9 +111,9 @@ You will need to pass the path to the token file to Nimbus together with the web
 === "Geth"
 
     Following [Geth update instructions](https://geth.ethereum.org/docs/faq#how-to-update-geth), to update Geth you need to:
-    
 
-    1. stop the node, 
+
+    1. stop the node,
     2. download the latest release (follow [installation instructions](https://geth.ethereum.org/docs/getting-started/installing-geth)),
     3. restart the node.
 

docs/the_nimbus_book/src/execution-client.md

@@ -0,0 +1,131 @@
+# Execution client
+
+!!! warning "Pre-release software"
+    The Nimbus execution client is currently available as a proof of concept - all aspects of it, including resource requirements, command line interface and in particular the database format will change!
+
+    Have fun with it and let us know how it goes while keeping the above in mind.
+
+    If you're looking for information about setting up an execution client for validator duties or any other production usage, see the [execution clients guide](./eth1.md).
+
+The Nimbus execution client is a light-weight implementation of the Ethereum execution protocol. Paired with a [beacon node](./quick-start.md) or [light client](./el-light-client.md), it provides access to Ethereum blockchain for dapps and users alike via the standard [Web3 API](https://ethereum.github.io/execution-apis/api-documentation/).
+
+## Building from source
+
+The Nimbus execution client is currently only provided as a source code distribution.
+
+### Clone the `nimbus-eth1` repository
+
+```sh
+git clone https://github.com/status-im/nimbus-eth1
+cd nimbus-eth1
+```
+
+### Run the build process
+
+To build the Nimbus execution client and its dependencies, make sure you have [all prerequisites](./install.md) and then run:
+
+```sh
+make -j4 nimbus nrpc
+```
+
+This may take a few minutes.
+
+When the process finishes, the `nimbus_execution_client` and `nrpc` executables can be found in the `build` subdirectory.
+
+## Import era files
+
+Syncing Nimbus requires a set of `era1` and `era` files. These can be generated from a `geth` and `nimbus` consensus client respectively or downloaded from a third-party repository.
+
+In addition to the era files themselves, you will need at least 200GB of free space on a fast SSD in your data directory, as set by the `--data-dir` command line option.
+
+!!! info "`era` file download locations"
+    `era` and `era1` files for testing purposes could at the time of writing be found here - these sources may or may not be available:
+
+    === "Mainnet"
+        * https://mainnet.era.nimbus.team/
+        * https://era1.ethportal.net/
+
+    === "Holesky"
+        * https://holesky.era.nimbus.team/
+
+        The Holesky network does not have `era1` files since it never operated as a proof-of-work chain
+
+    === "Sepolia"
+        * https://sepolia.era.nimbus.team/
+        * https://sepolia.era1.nimbus.team/
+
+It is recommended that you place the era files in the data directory under `era1` and `era` respectively. Era files can be shared between multiple nodes and can reside on a slow drive - use the `--era1-dir` and `--era-dir` options if they are located outside of the data directory.
+
+See the [era file guide](./era-store.md) for more information.
+
+!!! tip ""
+    Future versions of Nimbus will support other methods of syncing
+
+=== "Mainnet"
+    !!! note ""
+        Performing a full sync of mainnet from era files takes several days - its speed varies greatly depending on hardware. Use one of the testnets to get started more quickly!
+
+    ```sh
+    build/nimbus_execution_client --data-dir=build/mainnet import
+    ```
+
+
+=== "Holesky"
+    ```sh
+    build/nimbus_execution_client --network=holesky --data-dir=build/holesky import
+    ```
+
+=== "Sepolia"
+    ```sh
+    build/nimbus_execution_client --network=sepolia --data-dir=build/sepolia import
+    ```
+
+## Launch the client
+
+In order for the execution client to operate, you need to connect a consensus node. This can be the [Nimbus beacon node](./quick-start.md), a [supported consensus client](https://ethereum.org/en/developers/docs/nodes-and-clients/#consensus-clients) or a [light client](./el-light-client.md).
+
+The consensus node connects to the execution client via the Engine API which is enabled using `--engine-api` and by default runs on port `8551`.
+
+During startup, a `jwt.hex` file will be placed in the data directory containing authentication information that the consensus node uses to connect - make sure to use the same `jwt.hex` file on both consensus and execution node.
+
+=== "Mainnet"
+    ```sh
+    build/nimbus_execution_client --data-dir=build/mainnet --engine-api
+    ```
+
+=== "Holesky"
+    ```sh
+    build/nimbus_execution_client --network=holesky --data-dir=build/holesky --engine-api
+    ```
+
+=== "Sepolia"
+    ```sh
+    build/nimbus_execution_client --network=sepolia --data-dir=build/sepolia --engine-api
+    ```
+
+## Top up blocks from the consensus node
+
+While era files cover the majority of chain history, Nimbus currenty relies on the consensus node to sync the most recent blocks using the `nrpc` helper.
+
+This method of syncing loads blocks from the consensus node and passes them to the execution client via the Engine API.
+
+=== "Mainnet"
+    ```sh
+    # Start `nrpc` every 2 seconds in case there is a fork or the execution client goes out of sync
+    while true; do build/nrpc sync --beacon-api=http://localhost:5052 --el-engine-api=http://localhost:8550 --jwt-secret=build/mainnet/jwt.hex; sleep 2; done
+    ```
+
+=== "Holesky"
+    ```sh
+    # Start `nrpc` every 2 seconds in case there is a fork or the execution client goes out of sync
+    while true; do build/nrpc sync --network=holesky --beacon-api=http://localhost:5052 --el-engine-api=http://localhost:8550 --jwt-secret=build/holesky/jwt.hex; sleep 2; done
+    ```
+
+=== "Sepolia"
+    ```sh
+    # Start `nrpc` every 2 seconds in case there is a fork or the execution client goes out of sync
+    while true; do build/nrpc sync --network=sepolia --beacon-api=http://localhost:5052 --el-engine-api=http://localhost:8550 --jwt-secret=build/sepolia/jwt.hex; sleep 2; done
+    ```
+
+!!! tip ""
+    Future versions of Nimbus will support other methods of syncing

docs/the_nimbus_book/src/index.md

@@ -2,16 +2,18 @@
 
 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 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).
+Its efficiency and low resource consumption allows it to perform well on all kinds of systems: ranging from Raspberry Pi and mobile devices — where it contributes to low power consumption and security — to powerful servers where it leaves resources free to perform other tasks.
 
-This book describes the consensus layer client, [`nimbus-eth2`](https://github.com/status-im/nimbus-eth2).
-An execution client, [nimbus-eth1](https://github.com/status-im/nimbus-eth1), is also under development.
+This book describes the consensus protocol implementation which includes a [beacon node](./quick-start.md), [validator client](./validator-client.md) and [light client](./el-light-client.md).
 
+An [execution client](https://github.com/status-im/nimbus-eth1) is also under development - see its [quickstart guide](./execution-client.md).
+
+Our companion project [fluffy](https://github.com/status-im/nimbus-eth1/tree/master/fluffy) connects to the [Ethereum portal network](https://ethportal.net/) and has its [own guide](https://fluffy.guide/).
 
 ## Feature highlights
 
 * [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
+* Stand-alone [validator client](./validator-client.md) with [sentry node](./validator-client-options.md#sentry-node-setup) support
 * Fast [Beacon](./rest-api.md) and [KeyManager](./keymanager-api.md) APIs with extensions
 * [Web3Signer](https://docs.web3signer.consensys.net/en/latest/) remote signing
 * [Validator monitoring](./validator-monitor.md) and [performance analysis](./attestation-performance.md) tooling
@@ -35,7 +37,6 @@ As part of our first design goal, our primary objective here is for Nimbus to be
 
 Our dream is for you to be able to run and monitor your validator straight from Status desktop.
 
-
 ## Book contents
 
 You can read this book from start to finish, or you might want to read just specific topics you're interested in:
@@ -46,8 +47,6 @@ You can read this book from start to finish, or you might want to read just spec
 * Interested in becoming a validator? Follow the [validator guide](./run-a-validator.md).
 * If you're not planning on becoming a validator, you can run the [light client](./el-light-client.md).
 
-
-
 ## Get in touch
 
 Need help with anything?

docs/the_nimbus_book/src/networking.md

@@ -33,7 +33,7 @@ It means that Nimbus is unable to find a sufficient number of peers to guarantee
 
 Most commonly, this happens when your computer is not reachable from the outside and therefore won't be able to accept any incoming peer connections.
 
-If you're on a home network, the fix here is to [set up port forwarding](./networking.md#set-up-port-forwarding) (this may require you to [pass the extip option](./networking.md#pass-the-extip-option) and [set enr-auto-update](./networking.md#set-enr-auto-update)).
+If you're on a home network, the fix here is to [set up port forwarding](./networking.md#set-up-port-forwarding) (this may require you to [pass the extip option](./networking.md#set-an-explicit-external-ip) and [set enr-auto-update](./networking.md#set-enr-auto-update)).
 
 The first step however, is to check for incoming connections.
 

docs/the_nimbus_book/src/pi-guide.md

@@ -1,7 +1,11 @@
-# Running on a Raspberry Pi
+# Raspberry Pi
 
 <blockquote class="twitter-tweet"><p lang="en" dir="ltr">I expect the new Raspberry Pi 4 (4GB RAM option, external SSD) to handle an Eth2 validator node without breaking a sweat. That&#39;s $100 of hardware running at 10 Watts to support a 32 ETH node (currently ~$10K stake).</p>&mdash; Justin Ðrake (@drakefjustin) <a href="https://twitter.com/drakefjustin/status/1143091047058366465?ref_src=twsrc%5Etfw">June 24, 2019</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
 
+
+!!! note
+While this guide is based on Raspberry Pi 4 which was the newest version at the time of writing, growth of the validator set and chain complexity has led to increased hardware requirements for running a node. A Pi 4 might still be able to keep up, but your experience will be much better with the 8GB version of Pi 5 (or similar single-board computer such as [Rock 5B](https://radxa.com/products/rock5/5b/)).
+
 In addition to this guide, we highly recommend this [wonderful and complementary resource](https://docs.rocketpool.net/guides/node/local/prepare-pi.html#preliminary-setup) by community member Joe Clapis.
 
 ## Introduction
@@ -419,7 +423,7 @@ You should see something like:
 peers: 15 ❯ finalized: ada7228a:8765 ❯ head: b2fe11cd:8767:2 ❯ time: 9900:7 (316807) ❯ sync: wPwwwwwDwwDPwPPPwwww:7:1.2313:1.0627:12h01m(280512)
 ```
 
-Keep an eye on the number of peers you're currently connected to (in the above case that's `15`), as well as your [sync progress](./keep-an-eye.md#syncing-progress).
+Keep an eye on the number of peers you're currently connected to (in the above case that's `15`), as well as your [sync progress](./keep-an-eye.md#keep-track-of-your-syncing-progress).
 
 !!! note
     15 - 20 peers and an average sync speed of **0.5 - 1.0** blocks per second is normal on `Holesky` with a Pi.

docs/the_nimbus_book/src/quick-start.md

@@ -6,6 +6,7 @@ The quickstart setup involves running two nodes: an [execution client](./eth1.md
 Both are needed to run a full Ethereum setup.
 
 To become a validator, you first need to set up a beacon node.
+
 The beacon node connects to the beacon chain network, syncs historical data, and provides [API's](./rest-api.md) to monitor and interact with the beacon chain.
 Running a beacon node is a [worthwhile endeavor](https://vitalik.eth.limo/general/2021/05/23/scaling.html#its-crucial-for-blockchain-decentralization-for-regular-users-to-be-able-to-run-a-node) even if you are not planning on validating yourself!
 

docs/the_nimbus_book/src/troubleshooting.md

@@ -14,7 +14,7 @@ If you can't find a solution to your problem here, get in touch with us on our [
     When installing Nimbus, you will typically be using the latest `stable` release.
 
     However, the latest changes happen in the `unstable` branch.
-    If you're looking to test the changes coming to the _next_ Nimbus release, consider building Nimbus from [source](./keep-updated.md#build-from-source) using the `unstable` branch.
+    If you're looking to test the changes coming to the _next_ Nimbus release, consider building Nimbus from [source](./keep-updated.md#install-a-specific-version) using the `unstable` branch.
 
 ## Networking