Skip to main content

Connect to a testnet

Run Teku as a consensus client with any execution client on a testnet (for example Holesky or Sepolia).

If you're using Hyperledger Besu as an execution client, you can follow the Besu and Teku testnet tutorial.

note

Sepolia is a permissioned network and you can't run a validator client on it without requesting to become a validator first. You can connect your consensus client using the beacon node only, without any validator duties.

Prerequisites​

1. Generate the shared secret​

Run the following command:

openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex

You will specify jwtsecret.hex when starting Teku and the execution client. This is a shared JWT secret the clients use to authenticate each other when using the Engine API.

2. Generate validator keys​

If you're running a beacon node only, skip to the next step.

If you're also running a validator client, create a test Ethereum address (you can do this in MetaMask). Fund this address with testnet ETH (32 ETH and gas fees for each validator) using a faucet. See the list of Holesky faucets or Sepolia faucets.

note

If you're unable to get ETH using the faucet, you can ask for help on the EthStaker Discord.

Generate validator keys for one or more validators using the Holesky Staking Launchpad.

Remember the passwords that you use to create the validator keys, because you need them to create the validator password files.

Create a password file for each validator key​

For each validator key, create a text file containing the password to decrypt the key.

Teku allows you to specify individual keys and passwords in the command line, or you can specify directories from which to load keys and passwords. If specifying directories, password files must have the same name as the keys, but use the .txt extension.

info

  • If the Launchpad creates a key named keystore-m_12381_3600_0_0_0-1596485378.json, then the password file must be named keystore-m_12381_3600_0_0_0-1596485378.txt.

  • The password file format follows EIP-2335 requirements (UTF-8 encoded file, unicode normalization, and control code removal).

3. Start the execution client​

Refer to your execution client documentation to configure and start the execution client. Make sure you specify the shared secret generated in step 1.

If you're using Besu, you can follow the Besu and Teku testnet tutorial.

4. Start Teku​

Open a new terminal window.

Beacon node only​

To run Teku as a beacon node only (without validator duties), run the following command or specify the options in a configuration file:

teku \
    --network=holesky                             \
    --ee-endpoint=http://localhost:8551          \
    --ee-jwt-secret-file=<path to jwtsecret.hex> \
    --metrics-enabled=true                       \
    --rest-api-enabled=true                      \
    --checkpoint-sync-url=<checkpoint sync URL>

Specify:

You can modify the option values and add other command line options as needed.

Beacon node and validator client​

You can run the Teku beacon node and validator client as a single process or as separate processes.

You can check your validator status by searching your Ethereum address on the Holesky Beacon Chain explorer. It may take up to multiple days for your validator to be activated and start proposing blocks.

You can also use Prometheus and Grafana to monitor your nodes.

Single process​

To run the Teku beacon node and validator client in a single process, run the following command or specify the options in the configuration file:

teku \
  --network=holesky                                         \
  --ee-endpoint=http://localhost:8551                       \
  --ee-jwt-secret-file=<path to jwtsecret.hex>              \
  --metrics-enabled=true                                    \
  --rest-api-enabled=true                                   \
  --checkpoint-sync-url=<checkpoint sync URL>               \
  --validators-proposer-default-fee-recipient=<ETH address> \
  --validator-keys=<path to key file>:<path to password file>[,<path to key file>:<path to password file>,...]

Specify:

  • The path to the jwtsecret.hex file generated in step 1 using the --ee-jwt-secret-file option.
  • The URL of a checkpoint sync endpoint using the --checkpoint-sync-url option.
  • An Ethereum address you own as the default fee recipient using the --validators-proposer-default-fee-recipient option.
  • The paths to the keystore .json file and password .txt file created in step 2 for each validator using the --validator-keys option. Separate the .json and .txt files with a colon, and separate entries for multiple validators with commas. Alternatively, specify paths to directories to load multiple keys and passwords from.

You can modify the option values and add other command line options as needed.

Separate processes​

To run the Teku beacon node and validator client as separate processes, first start Teku as a beacon node only.

On a separate machine, run Teku using the validator-client subcommand:

teku validator-client \
    --network=holesky                      \
    --beacon-node-api-endpoint=<endpoint> \
    --validator-keys=<path to key file>:<path to password file>[,<path to key file>:<path to password file>,...]

Specify:

  • The location of one or more beacon node API endpoints using the --beacon-node-api-endpoint option.
  • The paths to the keystore .json file and password .txt file created in step 2 for each validator using the --validator-keys option. Separate the .json and .txt files with a colon, and separate entries for multiple validators with commas. Alternatively, specify paths to directories to load multiple keys and passwords from.

5. Wait for the clients to sync​

After starting the execution client and Teku, your node starts syncing and connecting to peers.

If you're running Teku as a beacon node only, you're all set. If you're also running Teku as a validator client, ensure your clients are fully synced before submitting your staking deposit in the next step. Syncing the execution client can take several days.

6. Stake ETH​

Stake your testnet ETH for one or more validators using the Holesky Staking Launchpad.

You can check your validator status by searching your Ethereum address on the Holesky Beacon Chain explorer. It may take up to multiple days for your validator to be activated and start proposing blocks.