Setting up Ethereum private testnet with Teku

Manual Setup

It's difficult and too long to manually set everything for private testnet, so this page is mostly about tools which could make it easier and not covering line by line configurations.

ethereum-genesis-generator
Creates CL and EL configs for testnet.
To use, clone repo, edit config-example/values.env by setting at least GENESIS_TIMESTAMP to something actual and fork schedule. For validators usage either edit EL_AND_CL_MNEMONIC or run staking-deposit-cli with existing default phrase. After that create output directory in repo root folder and run

docker run --rm -it -u $UID -v $PWD/output:/data \
  -v $PWD/config-example:/config \
  ethpandaops/ethereum-genesis-generator:latest all

After docker job finished you will see two directories in output: jwt with random jwtsecret and custom_config_data with EL's genesis.json, CL's genesis.ssz and config.yaml and several other useful files to spin up testnet.

staking-deposit-cli
The tool for generating validator keys, which could be needed when nodes are configured to run not in interop mode. It's made with Python, main README contains installation and usage guide for both python virtualenv and docker variants.

Useful options:
–pbkdf2 - turns on weak keystore encryption format, useful for tesnets, features faster generation and key loading
–devnet_chain_setting - testnet configuration, could be skipped if you add validators in genesis (choose any network), otherwise a useful option to get correct deposits output.

In addition to the keys you need password files, run something like this in the keys directory after creating pass directory next to the directory with the keys.

for file in *.json; do echo "test1234" > "../pass/${file%.json}.txt"; done
So, Teku starting option will look something like this at the end –validator-keys=/home/projects/validator-keys/keys:/home/projects/validator-keys/pass

Using Kurtosis

Follow Quickstart to install the tool and start enclave. All supported features could be found in network_params.yaml, while simple configuration could look like this:

participants:
  - el_client_type: geth
    cl_client_type: teku
    cl_client_image: consensys/teku:develop
    count: 2
additional_services:
  - el_forkmon
  - tx_spammer
  - dora
snooper_enabled: true

Check for other configuration examples in test directory
After starting enclave you could run kurtosis web and check status, logs, dora block explorer etc from the browser or use command line tools.

To specify JVM Xmx it is possible to use param cl_extra_env_vars like:

participants:
  - el_client_type: geth
    cl_client_type: teku
    cl_client_image: consensys/teku:develop
    cl_extra_env_vars: {"JAVA_OPTS": "-Xmx4G"}

Aliases/Functions

Below there are two suggested functions that can be added to your bash/zsh profile to simplify running the commands:

function ktr() {
  kurtosis clean -a && kurtosis run --enclave "$1" github.com/ethpandaops/ethereum-package --args-file "$1".yml --image-download always
}

function ktc() {
  kurtosis enclave rm -f "$1"
}

Using these functions, you can start kurtosis using:

ktr config

This will start a kurtosis network using the file config.yml

And stop it running:
ktc config

These functions are only suggestions, you do not need them to run kurtosis. Feel free to update them to your liking.

Interop

One thing that Kurtosis allows, is starting a test network with multiple CL clients.

participants_matrix:
  el:
    - el_type: ethereumjs
      el_image: 192.168.45.152:80/dh/ethpandaops/ethereumjs:master
    - el_type: nethermind
      el_image: 192.168.45.152:80/dh/nethermindeth/nethermind:pectra
  cl:
    - cl_type: teku
      cl_image: 192.168.45.152:80/dh/ethpandaops/teku:master
    - cl_type: lighthouse
      cl_image: 92.168.45.152:80/dh/ethpandaops/lighthouse:ef-tests-electra
network_params:
  network: pectra-devnet-0
additional_services:
  - dora
  - el_forkmon

The matrix is short-hand for specifying all combinations of several clients. In this case, because it’s specifying 2 x CL and 2 x EL, we get teku+ethereumjs, teku+nethermind, lighthouse+ethereumjs, lighthouse+nethermind.

Testing

Assertor runs test cases on the Kurtosis stack. It can be used to run specific tests, as shown below.

participants:
  - el_type: besu
    el_image: 192.168.45.152:80/dh/ethpandaops/besu:eip-7685-deposits
    cl_type: teku
    cl_image: consensys/teku:develop
    count: 1
  - el_type: nethermind
    el_image: 192.168.45.152:80/dh/nethermindeth/nethermind:pectra
    cl_type: teku
    cl_image: consensys/teku:develop
    count: 1
network_params:
  num_validator_keys_per_node: 256
  #preset: minimal
  electra_fork_epoch: 1
additional_services:
  - dora
  - el_forkmon
  - assertoor

assertoor_params:
  run_stability_check: false
  run_block_proposal_check: false
  tests:
    - file: https://raw.githubusercontent.com/ethpandaops/assertoor-test/master/assertoor-tests/pectra-dev/massive-deposit-0x02.yaml