# Besu Execution Client Setup Guide


## Acknowledgements
Great thanks to Frank Li for his [migration guide](https://medium.com/@frank_56417/switch-to-besu-as-el-client-for-your-rocketpool-minipool-node-de7d10e0ab86) for migrating to Besu on Rocketpool. Thanks to the Besu and Teku docs and developer teams. Thanks to CoinCashew for their [great guide](https://www.coincashew.com) on all topics crypto. Thanks to Somer Esat for his [Linux set-up guide](https://someresat.medium.com/1d76eb68c180)!

## Prerequisites
**Storage:** Make sure you have the appropriate amount of storage on your set-up. With Bonsai ([our recommended storage format](https://consensys.net/blog/news/test-staking-ahead-of-the-merge-with-improved-bonsai-tries-state-storage/)), you will need around ~650GB of storage for the blockchain data after a Snap Sync on Mainnet. Testnets are much smaller, usually under 100GB. Make sure to allot additional storage for your set-up as it runs and as the Ethereum world-state grows, though Bonsai is designed to keep state bloat low and implicitly prune.

Make sure to also leave room on the box for the consensus-layer client, which at time of writing uses around 40-50GB.

**Hardware:** Our minimum and recommended specs:
2-core CPU, 8GB RAM (minimum) - With these specs, you can expect longer sync times and memory pressure + GC
4-core+ Fast CPU, 16GB RAM+ - Using SnapSync, this time should be around a day to sync with less memory pressure + GC in normal operation

A note on memory: We recommend setting the maximum heap size to ***at least*** 4GB if you have 8GB of RAM on your machine. This results in an approximate process size of 4GB (on Linux).
* This can be set in the config or on start-up via `-xmx4g` (4GB, though can be larger on machines with more memory)

**Software:** You will need Java version 11 to run Besu and Teku. Installation instructions and dependencies for [Besu](https://besu.hyperledger.org/en/1.3.8/HowTo/Get-Started/System-Requirements/) and [Teku](https://docs.teku.consensys.net/en/latest/HowTo/Get-Started/Installation-Options/Install-Binaries/) are found at the links.

**Versioning:** This guide was built using Besu version 22.4.4 and Teku version 22.6.1.

## Disclaimer
This guide is intended for testing purposes and may not work as intended with your specific platform setup or with newer versions of the client software for Besu and Teku then specified in this guide. Please try these instructions on a test network and ensure success before you attempt to stake real Ether! If you hit a snag, there are support instructions at the bottom of the guide.

## Why you should switch to a minority client
To paraphrase some of [my other writing](https://consensys.net/blog/besu/the-critical-need-for-client-diversity-ahead-of-ethereums-merge-to-proof-of-stake/):

> Client diversity means that in order for the network to be healthy and secure, it must be sufficiently decentralized through a diversity of software clients. Ethereum is at its most robust with the majority client capturing only 33% of validators in the network. This is encouraged by a variety of incentives (that are explained further [here](https://upgrading-ethereum.info/altair/part2/incentives/diversity)). If one client supports the majority of the network, that uneven distribution puts the network at risk and reincarnates the inherent shortcomings of a singular vector of attack present in centralized networks. For reasons related to the Proof of Stake protocol, a bug in a supermajority client that has over two-thirds of validators could be extremely damaging to the network. In short, client diversity means more types of client software for more security.

We need your help to secure Ethereum for the long-term by running a variety of execution clients (like Besu), and consensus clients, like Teku. This guide will help you get set up with Besu and improve network resistance!

## Guide
The overall process is just a few steps, and is laid out conceptually as follows:
* Determine and set-up your environment
* Configure Besu, set up authentication, and expose your execution endpoint
* Configure your connection to a consensus layer client, and set up authentication
* Upgrading and maintaining your nodes
* Common problems and FAQs

## Determining and setting-up your environment and validator:
While the above prerequisites outline hardware, there are many software environments that will support this set-up. We outline many supported platforms [here](https://consensys.net/blog/news/the-latest-release-of-besu-helps-test-the-merge-on-any-platform/) for Besu, and this guide will apply to any machine that can run Java 11+. Commonly recommended is [systemd](https://someresat.medium.com/1d76eb68c180) Linux configurations (this linked guide is great for helping with Linux setups). If you’re more comfortable with Docker set-ups, check out the great [Eth-Docker](https://eth-docker.net/).

Regardless of the set-up, you should use either a dedicated machine if available or a separate user to ensure proper handling of network security and storage of validator keys, should you choose to use them. If you would like to test out staking on Ropsten, you will need to follow these instructions [here](https://ropsten.launchpad.ethereum.org/en/) in addition to setting up Besu + Teku. This guide will presume you are running without a validator (though one can be added later to your set-up).
Configuring Besu:

Besu can be configured with a [`.toml` file](https://besu.hyperledger.org/en/stable/HowTo/Configure/Using-Configuration-File/) or via the command line at start-up. In this case we can use the `--networks` command to specify the network we want to interact with.

Here is a sample (this one in particular will get you up and running on the PoS Ropsten:

# data
data-path="/data"
logging="INFO"

engine-jwt-secret="/etc/besu/ee-jwt-secret.hex" 
# See below for more info on this token

network="ropsten" 
#Can point this to other networks, we provide the specifics with our Besu releases

min-gas-price=1000
sync-mode="X_SNAP" # Can use FAST or FULL (FULL will use a lot of disk and months to sync!) 
data-storage-format="BONSAI"
host-whitelist=["*"]

# identity
identity="Your Identity" # Can be an org, individual, etc.

# rpc
rpc-http-enabled=true
rpc-http-host="0.0.0.0"
rpc-http-port=8545
rpc-http-api=["TRACE","ADMIN","DEBUG","NET","ETH","MINER","WEB3","TXPOOL"] 
# Should only expose ADMIN and DEBUG if you are not making your node available to the broader internet
rpc-http-cors-origins=["all"]

# engine API port
engine-rpc-port=8551

# websockets
rpc-ws-enabled=true
rpc-ws-api=["NET","ETH","WEB3"]
rpc-ws-host="0.0.0.0"
rpc-ws-port=8546

# graphql
graphql-http-enabled=true
graphql-http-host="0.0.0.0"
graphql-http-port=8547
graphql-http-cors-origins=["all"]

# p2p
p2p-host="52.15.64.34" #p2p-host is for networks where uPnP is not available
p2p-port=30303

# metrics
metrics-enabled=true
metrics-host="0.0.0.0"
metrics-port=9545 # Grab the Grafana dashboard here!

The above should get you started! In your CLI - you can start Besu by pointing it to your config:

`Besu --config-file="Config File Path"`

There are many more configuration options you can learn about [here](https://besu.hyperledger.org/en/stable/Reference/CLI/CLI-Syntax/).

You will need to generate and specify the location of a `JWT secret` in your config. Read [here](https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md) for more on JWT Auth. The secret can be [generated](https://docs.teku.consensys.net/en/latest/HowTo/Prepare-for-The-Merge/#configure-the-java-web-token) by running something like:

`openssl rand -hex 32 | tr -d "\n" > ee-jwt-secret.hex`

Some things to call out here are the sync mode and storage mode. For sync, recommend using `SnapSync` to reduce the time to get your node up and running. There is also an experimental `X_CHECKPOINT` sync mode that uses the SnapSync process from a specified checkpoint, rather than Ethereum’s genesis. If you do use this option, please let us know of any issues you may encounter in your testing. For storage, we recommend `Bonsai` (for a number of reasons outlined [here](https://consensys.net/blog/news/test-staking-ahead-of-the-merge-with-improved-bonsai-tries-state-storage/)) because it requires less maintenance of the node and will not have much state bloat.

## Configuring and connecting to your consensus layer client:
First, choose a consensus layer client. This guide will discuss Teku, but others can (and should) be explored as client diversity requirements impact both the execution and consensus layers!

Then, you can optionally head over to the [Ropsten Launchpad](https://ropsten.launchpad.ethereum.org/en/) and read more about becoming a validator, and generating your validator keys. The [Mainnet Launchpad](https://launchpad.ethereum.org/en/) is for those that want to stake real ETH and get rewarded (this guide does not touch on the minutia of Mainnet staking at this time).

This guide will not dive into the specifics, but there are many resources out there on getting started with [Teku](https://someresat.medium.com/guide-to-staking-on-ethereum-2-0-ubuntu-teku-e4247e7c75a1). First up is configuring your Teku node to communicate with your Besu node via the Engine API port:

`ee-endpoint: "http://localhost:8551"`

The above port may change depending on your setup (like with Docker). If you are migrating from one execution client (like Geth), you can simply point your already running consensus client to the new execution endpoint. The consensus layer will wait for the execution layer to sync and then resume duties. This will cause some downtime, but is only bottlenecked by sync speeds.

You will also need to pass the generated JWT secret to Teku as well:

`ee-jwt-secret-file: "ee-jwt-secret.hex"`

Here is an example config for a Ropsten Teku node (for running from the command line):

/usr/local/bin/teku/bin/teku --log-destination=console --data-base-path=/mnt/local/ethereum --network=ropsten --ee-endpoint=http://localhost:8551 --eth1-endpoint=http://localhost:8545 --ee-jwt-secret-file=/mnt/local/ethereum/ee-jwt-secret.hex --rest-api-enabled=true --rest-api-host-allowlist=* --rest-api-interface=0.0.0.0 --rest-api-port=5051 --metrics-enabled=true --metrics-host-allowlist=* --metrics-interface=0.0.0.0 --metrics-port=8008

With these in hand, you should be good to start up and run your nodes! You can always check the status of validators using [beaconcha.in](http://beaconcha.in) tools! Additionally [Besu](https://grafana.com/grafana/dashboards/16455) and [Teku](https://grafana.com/grafana/dashboards/13457/revisions) provide dashboards for monitoring node health. These should point to the endpoints that you exposed in the Besu and Teku configs above for metrics (set-up here for [Besu](https://besu.hyperledger.org/en/stable/HowTo/Monitor/Metrics/) and [Teku](https://docs.teku.consensys.net/en/stable/HowTo/Monitor/Metrics/)).

## Upgrading and maintaining your nodes

Once your node is up and running, you shouldn’t have to fiddle with it much. After sync is completed on the execution and consensus layers and node operations are confirmed, the nodes will hum along and (slowly) accumulate state. With Bonsai mode selected, your Besu node should not grow more than a few GBs every week, but make sure to leave appropriate space. Your Teku node will also start in “prune” mode by default, which should keep the storage in check (see the Prerequisites section for more info on storage requirements).

As upgrades are released, it is recommended that you take “required” upgrades that may include network hard-forks, configuration changes, updates to the spec and more. These are point releases for Besu. The process to upgrade your Besu node is [outlined here](https://besu.hyperledger.org/en/stable/HowTo/Upgrade/Upgrade-Node/). The process for Teku depends on how it was installed; more info can be found [here](https://docs.teku.consensys.net/en/latest/HowTo/Get-Started/Installation-Options/Install-Binaries/). CoinCashew has a great section on maintenance and upgrades of nodes in their [guide here](https://www.coincashew.com/coins/overview-eth/guide-or-how-to-setup-a-validator-on-eth2-mainnet/part-ii-maintenance). If you’re running a validator, downtown may be penalized when upgrading and restarting the nodes, but should be rewarded the same amount in roughly equal uptime.

## Support

For technical support please reach out to:
* The EthStaker community on [Reddit](https://www.reddit.com/r/ethstaker/) or [Discord](https://discord.gg/7z8wzehjrJ).
* The Besu and Teku client teams on [Discord](http://discord.gg/consensys).