Skip to content
Teku is under heavy development. If something isn't working as documented, check the changelog or get in touch on our Teku Discord channel. There may be updates that haven't yet made it to the documentation.

Updated on September 1, 2020

Connect to a testnet

The following instructions describe the process to connect Teku to an Ethereum 2.0 testnet.

Important

This example connects to the Medalla testnet. Networks can experience stability issues and are prone to regular resets. We recommend you regularly check network and client documentation for updates.

Prerequisites:

Teku allows you run a beacon chain client only, or you can run the beacon chain client with validators on a public testnet.

Run validators on a testnet

Ethereum 2.0 validators need to access an Ethereum 1.0 client to onboard new validators. Validators make deposits into Ethereum 1.0, and existing Ethereum 2.0 validators must process the deposits to allow the validators to join Ethereum 2.0.

Deposits are made into a deposit contract on the Goerli Ethereum 1.0 testnet.

The steps to run an Ethereum 2.0 validator on a testnet are:

  1. If using a local Ethereum 1.0 client, sync the Ethereum 1.0 network containing the deposit contract.

    Note

    This step is only required if using a local Ethereum 1.0 client such as Besu. If using a cloud-based service such as Infura, proceed to fund your deposit account.

  2. Fund the Ethereum 1.0 deposit account.

  3. Generate the validator key and send the deposit to the deposit contract.

    Note

    You can use the Medalla Launchpad to generate your keys and send the deposits, or you can use Teku. For convenience, we recommend using Teku if generating more than approximately 10 validators.

  4. Start Teku with the validator key.

Sync the Ethereum 1.0 network

This step is only required if using a local Ethereum 1.0 client.

This example uses Besu to connect to Ethereum 1.0, but any client can be used. Configure Besu to connect to Goerli and expose the RPC-HTTP APIs.

Example

besu --network=goerli --data-path=./goerli --rpc-http-enabled=true --rpc-http-port=8545 \
--rpc-http-api=ETH,NET,WEB3 --sync-mode=FAST --fast-sync-min-peers=2

Load the deposit account with ETH

You need an Ethereum 1.0 Goerli testnet account that contains the amount of Goerli ETH (plus gas) required to activate the validator. The medalla testnet requires 32 Goerli ETH per validator.

Tip

You can create an account on Goerli using Metamask, and use a faucet to fund the account. You can also request Goerli testnet ETH on the Medalla Discord channel.

If you use the Launchpad in the next step, then Metamask can handle your Ethereum 1.0 account. Otherwise you will need the private key of the account when sending the deposit to the deposit contract. The private key can be stored in a password protected V3 Keystore file.

Generate the validator and send the deposit

Tip

For small numbers of validators, we recommend using the Medalla Launchpad to generate your keys and send the deposits. For more than around 10 validators, the workflow below is more convenient.

Teku allows you to generate validator keys and send deposits to the deposit contract.

Example

teku validator generate-and-register --network=medalla \
--eth1-endpoint=http://localhost:8545 --keys-output-path=validator_key \
--encrypted-keystore-validator-password-file=./medalla/password.txt \
--encrypted-keystore-withdrawal-password-file=./medalla/password.txt \
--eth1-keystore-file=./medalla/walletKey --eth1-keystore-password-file=./medalla/password.txt \
--number-of-validators=1

On the command line:

It may take more than 8 hours for a deposit to become active.

Tip

View the deposit details on Etherscan by visiting https://goerli.etherscan.io/address/<accountPublicKey>.

Start the validator

Run Teku and specify the validator key file created earlier, and the text file containing the password to decrypt the validator key.

Example

teku --network=medalla --eth1-endpoint=http://localhost:8545 \
--validator-keys=validator/keys/validator_888eef.json:validator/passwords/validator_888eef.txt \
--rest-api-enabled=true --rest-api-docs-enabled=true \
--metrics-enabled

If you have multiple validator key files, place the key files and accompanying passwords in one or more directories. Use --validator-keys to specify the directory to load the keys and passwords from.

When specifying a directory, ensure the key file and password file have identical names, with the appropriate extensions. For example, a key (keys/validator1.json) matches the password (passwords/validator1.txt).

Example

teku --network=medalla --eth1-endpoint=http://localhost:8545 \
--validator-keys=validator/keys:validator/passwords \
--rest-api-enabled=true --rest-api-docs-enabled=true \
--metrics-enabled

Once the validator is activated, view it on the beacon chain explorer at https://medalla.beaconcha.in/validator/<validatorPublicKey>.

Run a beacon chain client only

You can run a Teku beacon chain node on a network without any validators.

Example

teku --network=medalla --metrics-enabled --rest-api-enabled --rest-api-docs-enabled

Add a beacon chain client to Eth2stats

You can add the beacon chain node to Eth2stats for monitoring.

Ensure you enable metrics using the --metrics-enabled option when starting Teku.

Finding help

  • The #medalla channel on the Ethereum Foundation Discord. Invite link

  • The #teku channel on the ConsenSys Discord. Invite link

  • Please raise any bugs or errors on the Teku GitHub repository.

ConsenSys has acquired Quorum from J.P. Morgan. Please read the FAQ.
Questions or feedback? You can discuss issues and obtain free support on Teku Discord channel.
For paid professional support by Pegasys, contact us at support@pegasys.tech