Running Nethermind Post Merge

Introduction

The long awaited shift from Proof of Work (POW) to Proof of Stake (POS) in Ethereum otherwise known as The Merge adds a lot to Ethereum. The most notable change is the addition of the Beacon chain (Consensus layer) which replaces Proof of Work mining. It will coordinate and pseudorandomly select block producers from the pool of stakers / validators in a way that makes it extremely difficult for validators to coordinate attacks on the network.
The Merge also changes how operators run nodes on the Ethereum blockchain. The biggest change being that a node now consists of two clients that work together as a pair. You still need to run an Execution Layer client (EL client) such as Nethermind that will connect to the existing chain. Nethermind will still build and validate blocks similar to before except mining will not longer work after The Merge. In addition to the EL client you will need a Consensus Layer client (CL client) that connects to the Beacon chain and runs the POS algorithm.
This guide will show you everything you need to know to operate an Ethereum node after The Merge. This guide will show how to connect to the Kiln and Ropsten test networks.

Installing Nethermind

Installing Nethermind is the same as before The Merge. You can choose from downloading the official release, downloading the docker image, or building Nethermind from source.
Support for post merge Ropsten is available as of Nethermind version 1.13.1

Downloading Official Release

Ubuntu

Run the following commands to enable our launchpad repository run then install Nethermind
1
sudo add-apt-repository ppa:nethermindeth/nethermind
2
sudo apt install nethermind
Copied!

macOS

Run the following commands to add the Nethermind repository to your local Homebrew and install
1
brew tap nethermindeth/nethermind
2
brew install nethermind
Copied!

Windows

On Windows all you have to do is install and unzip the packages. There are two sources that you can download from.
Downloads Page
GitHub Release Page
Nethermind - Downloads
Releases · NethermindEth/nethermind
GitHub

Downloading Docker Image

To download the latest Docker image run the following command to install the latest Debian biased Nethermind image.
1
docker pull nethermind/nethermind
Copied!
Currently Nethermind only supports images for AMD64 and ARM64 CPU architectures.

Building From Source

Installing Dependencies

To build Nethermind you will need to have Git and the .NET SDK 6.0 installed.
Git - Downloads
Download .NET (Linux, macOS, and Windows)
Microsoft
Depending on the platform you are using you may need to install extra dependencies.

Windows

You may need to install Microsoft Visual C++ Redistributable

macOS

You will need to install the following packages.
1
brew install gmp snappy lz4 zstd
Copied!

Apple Silicon (M1) users only

You will need to create symlink for homebrew dependencies.
1
sudo ln -s find /opt/homebrew/Cellar/snappy -name "libsnappy.dylib" /usr/local/lib/libsnappy.dylib
Copied!

Ubuntu 18.04 and Debian 10

You will need to install the following packages
1
sudo apt-get update && sudo apt-get install libsnappy-dev libc6-dev libc6
Copied!
Commands for other Linux distros can be found here.

Building Nethermind

After you have installed all of the dependencies for your platform you need to clone the Nethermind repo from GitHub.
Once the download has finished enter the nethermind/src/Nethermind directory and run the build command.
1
git clone --recursive https://github.com/NethermindEth/nethermind.git
2
cd nethermind/src/Nethermind
3
dotnet build Nethermind.sln -c Release
Copied!

Installing Consensus Client

On the Consensus Layer you have five client implementations to chose from. Though all CL clients are great check them out for yourself and find the client best suited to your needs.
We urge you to take client diversity into consideration when choosing your CL client and avoid majority clients.
Client Diversity | Ethereum
Client Diversity | Ethereum

Prysm

Prysmatic Labs
Prysmatic Labs

Teku

Teku | Ethereum 2.0 Client for Institutional Staking | ConsenSys
ConsenSys

Lighthouse

Lighthouse
Lighthouse

Lodestar

lodestar.chainsafe.io | Chainsafe Systems

Nimbus

Nimbus, a Lighter Ethereum Client

JSON-RPC API

The Merge adds changes the JSON-RPC API. Such as the Engine API, JWT authentication, additional RPC ports, and additional block tags.

Engine API

The Engine API adds new endpoints that allow the EL client to receive messages from the CL client.
execution-apis/specification.md at main · ethereum/execution-apis
GitHub

JWT Secrets

JSON Web Token authentication was added to the JSON-RPC API for security reasons to ensure that nothing interferes with the communication between the Execution client(Nethermind of course) and the Consensus client. This requires you to create a .txt file containing a hexadecimal “secret” that will be passed to each .
JWT.IO
To create this “Secret File” use the following command.
1
openssl rand -hex 32 | tr -d "\n" > "/tmp/jwtsecret"
Copied!
where "/tmp/jwtsecret" will be the file path and name when created.
If you do not want to install OpenSSL, you may use a random hex generator website. All you need is a 64 character hex string saved to a .txt file.
1
fcba4ab3138530cf233568bee2d518dd960da77355333d5ac856e1f27487dc9c
Copied!
We strongly recommend you use OpenSSL to generate the secret locally because it is more secure

JsonRpc Configuration Module

Nethermind has added some additional configuration settings for the JSON-RPC API.

AdditionalRpcUrls

This setting allows you to chose which port you want to use, whether its sent over HTTP and or WebSockets, which APIs you want enabled on that port, and if you want to disable JWT authentication on that port.
1
"JsonRpc": {
2
"Enabled": true,
3
"Timeout": 20000,
4
"Host": "127.0.0.1",
5
"Port": 8545,
6
"EnabledModules": ["Eth", "Subscribe", "Trace", "TxPool", "Web3", "Personal", "Proof", "Net", "Parity", "Health"],
7
"AdditionalRpcUrls": ["http://localhost:8551|http;ws|net;eth;subscribe;engine;web3;client"]
8
},
Copied!
  • Port 8551 is the default port that the EL and CL clients communicate on.

JwtSecretFile

This setting is used to identify the location of the .txt file containing the JWT secret.
Nethermind will create it's own jwtsecret file if you do not specify a location or pass the wrong location.

Block Tags

Some requests on the JSON-RPC API require a block tag for additional context. Previously there were three block tags earliest, latest, and pending. The Merge adds an additional two tags finalized and safe.
Block Tag
Description
earliest
The lowest numbered block the client has available
safe
The most recent crypto-economically secure block, cannot be re-orged outside of manual intervention driven by community coordination
finalized
The most recent crypto-economically secure block, cannot be re-orged outside of manual intervention driven by community coordination
latest
The most recent block in the canonical chain observed by the client, this block may be re-orged out of the canonical chain even under healthy/normal conditions
pending
A sample next block built by the client on top of latest and containing the set of transactions usually taken from local mempool

How to Run Nethermind

The steps to running Nethermind after The Merge have not changed much. After you have:
  • Installed Nethermind
  • Installed Consensus client
  • Created a JWT secret file
  • Ensured that an authenticated port with the Engine module is enabled
Then you are ready to start your clients. First start up Nethermind.

Ropsten Configuration

For Nethermind to sync to Ropsten you will have to set the MergeTotalTerminalDifficulty to 50000000000000000. You will need to edit your config or set manually during launch.

During Start up

Make sure the following flag is added to the start up command when launching.
1
--Merge.TotalTerminalDifficulty="50000000000000000"
Copied!

Edit Config

Open the Ropsten config of your choosing in the Nethermind.Runner/configs directory. Add the following lines to the Merge module.
1
"Merge": {
2
"Enabled": true,
3
"TerminalTotalDifficulty": "50000000000000000"
4
}
Copied!

Running Local Build

After you have built Nethermind you should be in the nethermind/src/Nethermind directory. From there you will need to run the following commands
1
cd Nethermind.Runner
2
dotnet run -c Release -- --config ropsten --JsonRpc.JwtSecretFile=PATH
Copied!
Where PATH is the path to your JWT secret. ex --JsonRpc.JwtSecretFile=/tmp/jwtsecret
and --config is the config file for the network you want to connect to.

Running Release

You have two options when running from a release. The Nethermind.Launcher which is a simple GUI with options to configure your node, or the Nethermind.Runner where you can configure your node by hand.
You will need to be in the directory that the Nethermind.Runner and Nethermind.Launcher are in to run Nethermind.

Nethermind.Launcher

Windows
Ubuntu
macOS
1
./Nethermind.Launcher
Copied!
1
nethermind
Copied!
1
nethermind-launcher
Copied!

Nethermind.Runner

Windows
Ubuntu
macOS
1
./Nethermind.Runner --config ropsten --JsonRpc.JwtSecretFile=PATH
Copied!
1
nethermind --config ropsten --JsonRpc.JwtSecretFile=PATH
Copied!
1
nethermind --config ropsten --JsonRpc.JwtSecretFile=PATH
Copied!
Where PATH is the path to your JWT secret. ex --JsonRpc.JwtSecretFile=/tmp/jwtsecret
and --config is the config file for the network you want to connect to.

Running Docker Image

Running Nethermind from a Docker image may require more configuration depending on the situation.
The commands below should work in most situations
1
docker run -it -v /home/user/data:/nethermind/data nethermind/nethermind nethermind/nethermind --config ropsten --JsonRpc.Enabled true --JsonRpc.JwtSecretFile=PATH --datadir data
Copied!

Docker Settings

  • -v /home/user/data:/nethermind/data sets local directory we will be storing our data to
On some OS like Amazon Linux ****you may need to increase the nofile limit by adding the following instruction to docker command -ulimit nofile=1000000:1000000 or you can take a look an alternative solution.

Nethermind Settings

  • --JsonRpc.JwtSecretFile=PATH where PATH is the location of your JWT secret ex. /tmp/jwtsecret
  • --config is the config file for the network you want to connect to. For kiln testnet use --config kiln
  • --datadir data maps the database, keystore, and logs all at once

How to Run Consensus Clients

Once Nethermind has started you can start the CL client. See section below for commands to run the CL client you installed. You will need to make sure the --jwt-secret has the correct path as well or the clients will not be able to communicate.
Once both clients are running watch the logs to make sure you don’t get any Unauthorized errors to ensure the clients are communicating.
That’s about all there is to it. Easy right?

Running on Kiln

To run on the kiln testnet, lodestar, nimbus and prysm require cloning the kiln configs.
1
git clone https://github.com/eth-clients/merge-testnets.git
2
cd merge-testnets/kiln
Copied!
For more detailed instructions on running the consensus clients on kiln, see here.

Running Nimbus With Nethermind

Kiln
Ropsten
1
nimbus-eth2/build/nimbus_beacon_node \
2
--network=merge-testnets/kiln \
3
--web3-url=ws://127.0.0.1:8551 \
4
--rest \
5
--metrics \
6
--log-level=DEBUG \
7
--terminal-total-difficulty-override=20000000000000 \
8
--jwt-secret="/tmp/jwtsecret" \
9
--eth1.depositContractDeployBlock=0
Copied!
1
nimbus-eth2/build/nimbus_beacon_node \
2
--network=ropsten \
3
--web3-url=http://127.0.0.1:8551 \
4
--rest \
5
--metrics \
6
--jwt-secret="/tmp/jwtsecret"
Copied!

Running Prysm With Nethermind

Kiln
Ropsten
1
cd prysm
2
bazel run //beacon-chain -- \
3
--genesis-state $genesis_state_path \
4
--datadir $db_path \
5
--http-web3provider=$execution_server \
6
--execution-provider=http://localhost:8551 \
7
--chain-config-file=$config_path \
8
--bootstrap-node=enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk
9
--jwt-secret=/tmp/jwtsecret
Copied!
1
cd prysm
2
bazel run //beacon-chain -- \
3
--ropsten \
4
--datadir $db_path \
5
--http-web3provider=http://localhost:8551 \
6
--bootstrap-node=enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk
7
--jwt-secret=/tmp/jwtsecret
Copied!

Running Lighthouse With Nethermind

Kiln
Ropsten
1
lighthouse \
2
--spec mainnet \
3
--network kiln \
4
--debug-level info \
5
beacon_node \
6
--datadir ./testnet-lh1 \
7
--eth1 \
8
--http \
9
--http-allow-sync-stalled \
10
--metrics \
11
--merge \
12
--execution-endpoints http://127.0.0.1:8551 \
13
--enr-udp-port=9000 \
14
--enr-tcp-port=9000 \
15
--discovery-port=9000 \
16
--jwt-secrets="/tmp/jwtsecret"
Copied!
1
lighthouse \
2
--spec mainnet \
3
--network ropsten \
4
--debug-level info \
5
beacon_node \
6
--datadir ./testnet-lh1 \
7
--eth1 \
8
--http \
9
--http-allow-sync-stalled \
10
--metrics \
11
--merge \
12
--execution-endpoints http://127.0.0.1:8551 \
13
--enr-udp-port=9000 \
14
--enr-tcp-port=9000 \
15
--discovery-port=9000 \
16
--jwt-secrets="/tmp/jwtsecret"
Copied!

Running Lodestar With Nethermind

Kiln
Ropsten
1
cd lodestar./lodestar beacon \
2
--rootDir="../lodestar-beacondata" \
3
--paramsFile="../config.yaml" \
4
--genesisStateFile="../genesis.ssz" \
5
--eth1.enabled=true \
6
--execution.urls="http://127.0.0.1:8551" \
7
--network.connectToDiscv5Bootnodes \
8
--network.discv5.enabled=true \
9
--jwt-secret="/tmp/jwtsecret" \
10
--network.discv5.bootEnrs="enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk"
Copied!
1
cd lodestar
2
./lodestar beacon \
3
--rootDir="../lodestar-beacondata" \
4
--network ropsten \
5
--eth1.enabled=true \
6
--execution.urls="http://127.0.0.1:8551" \
7
--network.connectToDiscv5Bootnodes \
8
--network.discv5.enabled=true \
9
--jwt-secret="/tmp/jwtsecret" \
10
--network.discv5.bootEnrs="enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk"
Copied!

Running Teku With Nethermind

Kiln
Ropsten
1
./teku/build/install/teku/bin/teku \
2
--data-path "datadir-teku" \
3
--network kiln \
4
--p2p-discovery-bootnodes "enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk" \
5
--ee-endpoint http://localhost:8551 \
6
--Xee-version kilnv2 \
7
--ee-jwt-secret-file "/tmp/jwtsecret" \
8
--log-destination console
Copied!
1
./teku/build/install/teku/bin/teku \
2
--data-path "datadir-teku" \
3
--network ropsten \
4
--ee-endpoint http://localhost:8551 \
5
--ee-jwt-secret-file "/tmp/jwtsecret" \
6
--log-destination console \
Copied!