Skip to content

Run an execution client

In order to perform validation duties, you must have an execution client running — at least one for each beacon node. Relying on third-party services such as Infura, Alchemy and Pocket is no longer possible. Sharing the same execution client between multiple beacon nodes is not supported.

Nimbus has been tested with all major execution clients. See the execution client comparison for more information.

Info

Syncing an execution client may take hours or even days, depending on your hardware!

Steps

1. Install execution client

Select an execution client and install it, configuring it such that the authenticated JSON-RPC interface is enabled and a JWT secret file is created.

See the Nimbus execution client for installation instructions.

1. Install Geth

See the Installing Geth guide for instructions on installing Geth.

2. Start Geth

Once you have geth installed, make sure to enable the authenticated JSON-RPC interface when running geth:

geth --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret

geth --hoodi --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret

See the Installing Nethermind guide to set up Nethermind.

Make sure to enable the JSON-RPC interface and pass --JsonRpc.JwtSecretFile=/tmp/jwtsecret to select a JWT secret file location.

See the Besu documentation for instructions on setting up Besu.

Make sure to enable the JSON-RPC interface and store the JWT token in /tmp/jwtsecret.

See the Erigon README for instructions on setting up Erigon.

Make sure to enable the JSON-RPC interface and use --authrpc.jwtsecret=/tmp/jwtsecret to set a path to the JWT token file.

2. Leave the execution client running

The execution client needs to be running at all times in order for the beacon node to be able to support validators. It will start its syncing process as soon as the beacon node connects to it. Once both are synced, they will continue to work in tandem to validate the latest Ethereum state.

It is safe to start the beacon node even if the execution client is not yet fully synced, and vice versa.

3. Pass the URL and JWT secret to Nimbus

The --el option informs the beacon node how to connect to the execution client — both http:// and ws:// URLs are supported.

Info

By default, the execution client accepts connections on the localhost interface (127.0.0.1), with default authenticated RPC port 8551. When the --el option is not explicitly specified, Nimbus will assume that the execution client is running on the same machine with such default settings.

Once started, the execution client will create a file containing a JWT secret token. The token file is needed for Nimbus to authenticate itself with the execution client and perform trusted operations. You will need to pass the path to the token file to Nimbus together with the web3 URL.

./run-mainnet-beacon-node.sh \
    --el=http://127.0.0.1:8551 \
    --jwt-secret=/tmp/jwtsecret

build/nimbus_beacon_node \
    --network=hoodi \
    --data-dir=build/data/shared_hoodi_0 \
    --el=http://127.0.0.1:8551 \
    --jwt-secret=/tmp/jwtsecret

Upgrade execution client

In the nimbus-eth1 directory, run the following commands: 

git pull
make -j4 update
make -j4 nimbus

Following Geth update instructions, to update Geth you need to:

  1. stop the node,
  2. download the latest release (follow installation instructions),
  3. restart the node.

There are several ways of updating Nethermind, depending on the installation method. Follow Nethermind upgrade instructions.

Follow Besu upgrade instructions.

Advanced setups

Running multiple execution clients

You can increase the resilience of your setup and eliminate any downtime during upgrade procedure of the execution client software by allowing your beacon node to manage multiple execution clients. To enable this mode, just specify multiple URLs through the --el option when starting your beacon node:

./run-mainnet-beacon-node.sh \
    --el=http://127.0.0.1:8551 \
    --el=ws://other:8551 \
    --jwt-secret=/tmp/jwtsecret

Tip

You can use a different secret for each connection by specifying jwt-secret or jwt-secret-file as a query parameter in the anchor section of the URL (e.g. http://127.0.0.1:8551/#jwt-secret=0x12345... or http://127.0.0.1:8551/#jwt-secret-file=/tmp/jwtsecret). If you use a TOML config file, you can also use the following, more natural, syntax:

data-dir = "my-data-dir"
rest = true
...

[[el]]
url = "http://127.0.0.1:8551"
jwt-secret-file="/path/to/jwt/file"

[[el]]
url = "http://192.168.1.2:8551"
jwt-secret = ""

As long as any of execution clients remains operational and fully synced, Nimbus will keep performing all validator duties.

Tip

To carry out an upgrade procedure without any downtime, just restart the execution clients one by one, waiting for each instance to re-sync before moving to the next one.

If you use this mode with different execution client implementations, Nimbus will act as an execution layer consensus violation detector, preventing the publishing of blocks that may trigger a catastrophic partitioning in the network.