Guide: How to stake on ETH2 Mainnet with Teku on Ubuntu

Become a validator and help secure eth2, a proof-of-stake blockchain. Anyone with 32 ETH can join.

Nov 24 2020 Update: The new mainnet guide is located here.

Instructions below are now deprecated and for reference only.

PegaSys Teku (formerly known as Artemis) is a Java-based Ethereum 2.0 client designed & built to meet institutional needs and security requirements. PegaSys is an arm of ConsenSys dedicated to building enterprise-ready clients and tools for interacting with the core Ethereum platform. Teku is Apache 2 licensed and written in Java, a language notable for its materity & ubiquity.

🏁 0. Prerequisites

👩💻 Skills for operating a eth2 validator and beacon node

As a validator for eth2, you will typically have the following abilities:

🎗 Minimum Setup Requirements

  • Operating system: 64-bit Linux (i.e. Ubuntu 20.04 LTS)

  • Processor: Dual core CPU, Intel Core i5–760 or AMD FX-8100 or better

  • Memory: 8GB RAM

  • Storage: 20GB SSD

  • Internet: Broadband internet connection with speeds at least 1 Mbps.

  • Power: Reliable electrical power.

  • ETH balance: at least 32 ETH and some ETH for deposit transaction fees

  • Wallet: Metamask installed

  • Operating system: 64-bit Linux (i.e. Ubuntu 20.04 LTS)

  • Processor: Quad core CPU, Intel Core i7–4770 or AMD FX-8310 or better

  • Memory: 16 GB RAM or more

  • Storage: 1TB SSD or more

  • Internet: Broadband internet connections with speeds at least 10 Mbps

  • Power: Reliable electrical power with uninterruptible power supply (UPS)

  • ETH balance: at least 32 ETH and some ETH for deposit transaction fees

  • Wallet: Metamask installed

Pro Validator Tip: Highly recommend you begin with a brand new instance of an OS, VM, and/or machine. Avoid headaches by NOT reusing testnet keys, wallets, or databases for your mainnet validator.

If you need ideas or a reminder on how to secure your validator, refer to

🛠 Setup Ubuntu

If you need to install Ubuntu, refer to

🎭 Setup Metamask

If you need to install Metamask, refer to

🌱 1. Buy/exchange or consolidate ETH

Every 32 ETH you own allows you to make 1 validator. You can run thousands of validators with your beacon node.

Your ETH (or multiples of 32 ETH) should be consolidated into a single address accessible with Metamask.

If you need to buy/exchange or top up your ETH to a multiple of 32, check out:

👩💻2. Signup to be a validator at the Launchpad

  1. Install dependencies, the ethereum foundation deposit tool and generate your two sets of key pairs.

Each validator will have two sets of key pairs. A signing key and a withdrawal key. These keys are derived from a single mnemonic phrase. Learn more about keys.

You have the choice of downloading the pre-built ethereum foundation deposit tool or building it from source.

Pre-built eth2deposit-cli
Build from source code
Advanced - Most Secure
Pre-built eth2deposit-cli

Download eth2deposit-cli.

cd $HOME
wget https://github.com/ethereum/eth2.0-deposit-cli/releases/download/v1.0.0/eth2deposit-cli-9310de0-linux-amd64.tar.gz

Verify the SHA256 Checksum matches the checksum on the releases page.

sha256sum eth2deposit-cli-9310de0-linux-amd64.tar.gz
# SHA256 should be
# b09da136895a7f77a4b430924ea2ae5827fa47b2bf444c4ea6fcfac5b04b8c8a

Extract the archive.

tar -xvf eth2deposit-cli-9310de0-linux-amd64.tar.gz
cd eth2deposit-cli-9310de0-linux-amd64

Make a new mnemonic.

./deposit new-mnemonic --chain mainnet
Build from source code

Install dependencies.

sudo apt update
sudo apt install python3-pip git -y

Download source code and install.

mkdir ~/git
cd ~/git
git clone https://github.com/ethereum/eth2.0-deposit-cli.git
cd eth2.0-deposit-cli
sudo ./deposit.sh install

Make a new mnemonic.

./deposit.sh new-mnemonic --chain mainnet
Advanced - Most Secure

🔥[ Optional ] Pro Security Tip: Run the eth2deposit-cli tool and generate your mnemonic seed for your validator keys on an air-gapped offline machine.

You can copy via USB key the pre-built eth2deposit-cli binaries from an online machine to an air-gapped offline machine.

  • Protects against key-logging attacks, malware/virus based attacks and other firewall or security exploits.

  • Physically isolated from the rest of your network.

  • Must not have a network connection, wired or wireless.

  • Is not a VM on a machine with a network connection.

  • Learn more about air-gapping at wikipedia.

2. Follow the prompts and pick a password. Write down your mnemonic and keep this safe and offline.

3. Follow the steps at https://launchpad.ethereum.org/ while skipping over the steps you already just completed. Study the eth2 phase 0 overview material. Understanding eth2 is the key to success!

4. Back on the launchpad website, upload yourdeposit_data-#########.json found in the validator_keys directory.

5. Connect to the launchpad with your Metamask wallet, review and accept terms.

6. Confirm the transaction(s). There's one deposit transaction of 32 ETH for each validator.

Your transaction is sending and depositing your ETH to the official ETH2 deposit contract address.

Check, double-check, triple-check that the official Eth2 deposit contract address is correct.0x00000000219ab540356cBB839Cbe05303d7705Fa

Be sure to write down or record your mnemonic seed offline. Not email. Not cloud.

Make offline backups, such as to a USB key, of your validator_keys directory.

🛸3. Install a ETH1 node

Ethereum 2.0 requires a connection to Ethereum 1.0 in order to monitor for 32 ETH validator deposits. Hosting your own Ethereum 1.0 node is the best way to maximize decentralization and minimize dependency on third parties such as Infura.

The subsequent steps assume you have completed the best practices security guide.

Your choice of either OpenEthereum, Geth, Besu or Nethermind.

OpenEthereum (Parity)
Geth
Besu
Nethermind
Minimum Hardware Setup
OpenEthereum (Parity)

🤖 Install and run OpenEthereum.

mkdir ~/openethereum && cd ~/openethereum
wget https://github.com/openethereum/openethereum/releases/download/v3.0.1/openethereum-linux-v3.0.1.zip
unzip openethereum*.zip
chmod +x openethereum
rm openethereum*.zip

Setup and configure systemd

Run the following to create a unit file to define your eth1.service configuration.

cat > $HOME/eth1.service << EOF
[Unit]
Description = openethereum eth1 service
Wants = network-online.target
After = network-online.target
[Service]
User = $(whoami)
WorkingDirectory= /home/$(whoami)/openethereum
ExecStart = /home/$(whoami)/openethereum/openethereum --chain foundation
Restart = on-failure
[Install]
WantedBy = multi-user.target
EOF

Move the unit file to /etc/systemd/system and give it permissions.

sudo mv $HOME/eth1.service /etc/systemd/system/eth1.service
sudo chmod 644 /etc/systemd/system/eth1.service

Run the following to enable auto-start at boot time.

sudo systemctl daemon-reload
sudo systemctl enable eth1

Start OpenEthereum on mainnet.

sudo systemctl start eth1
Geth

🧬 Install from the repository.

sudo add-apt-repository -y ppa:ethereum/ethereum
sudo apt-get update -y
sudo apt-get install ethereum -y

Setup and configure systemd

Run the following to create a unit file to define your eth1.service configuration.

cat > $HOME/eth1.service << EOF
[Unit]
Description = geth eth1 service
Wants = network-online.target
After = network-online.target
[Service]
User = $(whoami)
ExecStart = /usr/bin/geth --http
Restart = on-failure
[Install]
WantedBy = multi-user.target
EOF

Move the unit file to /etc/systemd/system and give it permissions.

sudo mv $HOME/eth1.service /etc/systemd/system/eth1.service
sudo chmod 644 /etc/systemd/system/eth1.service

Run the following to enable auto-start at boot time.

sudo systemctl daemon-reload
sudo systemctl enable eth1

Start geth on mainnet.

sudo systemctl start eth1
Besu

🧬 Install java dependency.

sudo apt install openjdk-11-jdk

🌜 Download and unzip Besu.

cd
wget -O besu.tar.gz https://bintray.com/hyperledger-org/besu-repo/download_file?file_path=besu-1.5.0.tar.gz
tar -xvf besu.tar.gz
rm besu.tar.gz
mv besu-1.5.0 besu

Setup and configure systemd

Run the following to create a unit file to define your eth1.service configuration.

cat > $HOME/eth1.service << EOF
[Unit]
Description = openethereum eth1 service
Wants = network-online.target
After = network-online.target
[Service]
User = $(whoami)
WorkingDirectory= /home/$(whoami)/besu/bin
ExecStart = /home/$(whoami)/besu/bin/besu --data-path="$HOME/.ethereum_besu"
Restart = on-failure
[Install]
WantedBy = multi-user.target
EOF

Move the unit file to /etc/systemd/system and give it permissions.

sudo mv $HOME/eth1.service /etc/systemd/system/eth1.service
sudo chmod 644 /etc/systemd/system/eth1.service

Run the following to enable auto-start at boot time.

sudo systemctl daemon-reload
sudo systemctl enable eth1

Start besu on mainnet.

sudo systemctl start eth1
Nethermind

Install dependencies.

sudo apt-get update && sudo apt-get install libsnappy-dev libc6-dev libc6 unzip -y

🌜 Download and unzip Nethermind.

mkdir ~/nethermind && cd ~/nethermind
wget -O nethermind.zip https://nethdev.blob.core.windows.net/builds/nethermind-linux-amd64-1.8.77-9d3a58a.zip
unzip nethermind.zip
rm nethermind.zip

🛸 Launch Nethermind.

./Nethermind.Launcher
  • Select Ethereum Node

  • Select Ethereum (mainnet) then select Fast sync

  • Yes to enable web3 / JSON RPC

  • Accept default IP

  • Skip ethstats registration

Minimum Hardware Setup

🚧 Untested - TBD - Work in progress 🚧

Use a third party by signing up for an API access key at https://infura.io/

Syncing the eth1 node could take up to 24 hour.

Your eth1 node is fully sync'd when these events occur.

  • OpenEthereum: Imported #<block number>

  • Geth: Imported new chain segment

  • Besu: Imported #<block number>

  • Nethermind: No longer syncing Old Headers

🛠 Helpful eth1.service commands

​​ 🗒 To view and follow eth1 logs

journalctl -u eth1 -f

🗒 To stop eth1 service

sudo systemctl stop eth1

🛑 Before continuing the rest of this guide, we recommend you wait until closer to Dec 1st as the Teku code is rapidly preparing for mainnet. 🚧

💡 4. Build Teku from source

Install git.

sudo apt-get install git -y

Install Java 11.

Ubuntu 20.x
Ubuntu 18.x
Ubuntu 20.x
sudo apt update
sudo apt install openjdk-11-jdk
Ubuntu 18.x
sudo add-apt-repository ppa:linuxuprising/java
sudo apt update
sudo apt install oracle-java11-set-default

Install and build Teku.

cd ~/git
git clone https://github.com/PegaSysEng/teku.git
cd teku
./gradlew distTar installDist

This build process may take a few minutes.

Verify Teku was installed properly by displaying the version.

cd $HOME/git/teku/build/install/teku/bin
./teku --version

Copy the teku binary files to /usr/local/teku

sudo cp -r $HOME/git/teku/build/install/teku/. /usr/bin/teku

🔥 5. Configure port forwarding and/or firewall

Specific to your networking setup or cloud provider settings, ensure your validator's firewall ports are open and reachable.

  • Teku beacon chain node will use port 9001 for tcp and udp

  • eth1 node requires port 30303 for tcp and udp

Port Forwarding Tip: You'll need to forward and open ports to your validator. Verify it's working with https://www.yougetsignal.com/tools/open-ports/ or https://canyouseeme.org/ .

🏂 6. Start the beacon chain and validator

Teku combines both the beacon chain and validator into one process.

If you participated in any of the prior test nets, you need to clear the database.

rm -rf $HOME/.local/share/teku/data

Setup a directory structure for Teku.

sudo mkdir -p /var/lib/teku
sudo mkdir -p /etc/teku

Copy your validator_files directory to the data directory we created above.

Pre-built eth2deposit-cli
Built from source code
Pre-built eth2deposit-cli
sudo cp -r $HOME/eth2deposit-cli-9310de0-linux-amd64/validator_keys /var/lib/teku
Built from source code
sudo cp -r $HOME/git/eth2.0-deposit-cli/validator_keys /var/lib/teku

Store your validator's password in a file.

echo "my_password_goes_here" > $HOME/validators-password.txt
sudo mv $HOME/validators-password.txt /etc/teku/validators-password.txt

Generate your Teku Config file.

cat > $HOME/teku.yaml << EOF
# network
network: "mainnet"
# p2p
p2p-enabled: true
p2p-port: 9001
# validators
validator-keys: "/var/lib/teku/validator_keys:/etc/teku/validator_keys"
validators-graffiti: "Teku validator & CoinCashew.com"
# Eth 1
eth1-endpoint: "http://localhost:8545"
# metrics
metrics-enabled: true
metrics-categories: ["BEACON","LIBP2P","NETWORK"]
metrics-port: 8008
# database
data-path: "$(echo $HOME)/tekudata"
data-storage-mode: "archive"
# rest api
rest-api-port: 5051
rest-api-docs-enabled: true
rest-api-enabled: true
# logging
log-include-validator-duties-enabled: true
log-destination: CONSOLE
EOF

Move the config file to /etc/teku

sudo mv $HOME/teku.yaml /etc/teku/teku.yaml

When specifying directories for your validator-keys, Teku expects to find identically named keystore and password files.

For example keystore-m_12221_3600_1_0_0-11222333.json and keystore-m_12221_3600_1_0_0-11222333.txt

Create a corresponding password file for every one of your validators.

for f in /var/lib/teku/validator_keys/keystore*.json; do cp /etc/teku/validators-password.txt /var/lib/teku/validator_keys/$(basename $f .json).txt; doneYour choice of running a beacon chain and validator manually from command line or automatically with systemd.
Systemd - Automated
CLI - Manual
Systemd - Automated

🍰 Benefits of using systemd for your beacon chain and validator

  1. Auto-start your beacon chain when the computer reboots due to maintenance, power outage, etc.

  2. Automatically restart crashed beacon chain processes.

  3. Maximize your beacon chain up-time and performance.

🛠 Setup Instructions

Run the following to create a unit file to define yourbeacon-chain.service configuration.

cat > $HOME/beacon-chain.service << EOF
# The eth2 beacon chain service (part of systemd)
# file: /etc/systemd/system/beacon-chain.service
[Unit]
Description = eth2 beacon chain service
Wants = network-online.target
After = network-online.target
[Service]
User = $(whoami)
WorkingDirectory= /usr/local/teku/bin
ExecStart = /usr/local/teku/bin/teku -c /etc/teku/teku.yaml
Restart = on-failure
[Install]
WantedBy = multi-user.target
EOF

Move the unit file to /etc/systemd/system and give it permissions.

sudo mv $HOME/beacon-chain.service /etc/systemd/system/beacon-chain.service
sudo chmod 644 /etc/systemd/system/beacon-chain.service

Run the following to enable auto-start at boot time and then start your beacon node service.

sudo systemctl daemon-reload
sudo systemctl enable beacon-chain
sudo systemctl start beacon-chain

Nice work. Your beacon chain is now managed by the reliability and robustness of systemd. Below are some commands for using systemd.

🛠 Some helpful systemd commands

Check whether the beacon chain is active

sudo systemctl is-active beacon-chain

🔎 View the status of the beacon chain

sudo systemctl status beacon-chain

🔄 Restarting the beacon chain

sudo systemctl reload-or-restart beacon-chain

🛑 Stopping the beacon chain

sudo systemctl stop beacon-chain

🗄 Viewing and filtering logs

journalctl --unit=beacon-chain --since=yesterday
journalctl --unit=beacon-chain --since=today
journalctl --unit=beacon-chain --since='2020-12-01 00:00:00' --until='2020-12-02 12:00:00'
CLI - Manual

In a new terminal, start the beacon chain.

/usr/local/teku/bin/teku -c /etc/teku/teku.yaml

WARNING: DO NOT USE THE ORIGINAL KEYSTORES TO VALIDATE WITH ANOTHER CLIENT, OR YOU WILL GET SLASHED.

Validator client - Responsible for producing new blocks and attestations in the beacon chain and shard chains.

Beacon chain client - Responsible for managing the state of the beacon chain, validator shuffling, and more.

Congratulations. Once your beacon-chain is sync'd, validator up and running, you just wait for activation. This process takes up to 24 hours. When you're assigned, your validator will begin creating and voting on blocks while earning ETH staking rewards.

Use beaconcha.in and register an account to create alerts and track your validator's performance.

🕒 7. Time Synchronization

Because beacon chain relies on accurate times to perform attestations and produce blocks, your computer's time must be accurate to real NTP or NTS time within 0.5 seconds.

Setup Chrony with the following guide.

chrony is an implementation of the Network Time Protocol and helps to keep your computer's time synchronized with NTP.

🔎 8. Monitoring your validator with Grafana and Prometheus

Prometheus is a monitoring platform that collects metrics from monitored targets by scraping metrics HTTP endpoints on these targets. Official documentation is available here. Grafana is a dashboard used to visualize the collected data.

🐣 8.1 Installation

Install prometheus and prometheus node exporter.

sudo apt-get install -y prometheus prometheus-node-exporter

Install grafana.

wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
echo "deb https://packages.grafana.com/oss/deb stable main" > grafana.list
sudo mv grafana.list /etc/apt/sources.list.d/grafana.list
sudo apt-get update && sudo apt-get install -y grafana

Enable services so they start automatically.

sudo systemctl enable grafana-server.service
sudo systemctl enable prometheus.service
sudo systemctl enable prometheus-node-exporter.service

Update prometheus.yml located in /etc/prometheus/prometheus.yml

cat > $HOME/prometheus.yml << EOF
global:
scrape_interval: 15s # By default, scrape targets every 15 seconds.
# Attach these labels to any time series or alerts when communicating with
# external systems (federation, remote storage, Alertmanager).
external_labels:
monitor: 'codelab-monitor'
# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
- job_name: 'node_exporter'
static_configs:
- targets: ['localhost:9100']
- job_name: 'nodes'
metrics_path: /metrics
static_configs:
- targets: ['localhost:8008']
EOF
sudo mv $HOME/prometheus.yml /etc/prometheus/prometheus.yml

Finally, restart the services.

sudo systemctl restart grafana-server.service
sudo systemctl restart prometheus.service
sudo systemctl restart prometheus-node-exporter.service

Verify that the services are running properly:

sudo systemctl status grafana-server.service prometheus.service prometheus-node-exporter.service

💡 Reminder: Ensure port 3000 is open on the firewall and/or port forwarded if you intend to view monitoring info from a different machine.

📶8.2 Setting up Grafana Dashboards

  1. Open http://localhost:3000 or http://<your validator's ip address>:3000 in your local browser.

  2. Login with admin / admin

  3. Change password

  4. Click the configuration gear icon, then Add data Source

  5. Select Prometheus

  6. Set Name to "Prometheus"

  7. Set URL to http://localhost:9090

  8. Click Save & Test

  9. Download and save this json file.

  10. Click Create + icon > Import

  11. Add dashboard by Upload JSON file

  12. Click the Import button.

8.3 Setup Alert Notifications

Setup alerts to get notified if your validators go offline.

Get notified of problems with your validators. Choose between email, telegram, discord or slack.

Email Notifications
Telegram Notifications
Discord Notifications
Slack Notifications
Email Notifications
  1. Sign Up for an account

  2. Verify your email

  3. Search for your validator's public address

  4. Add validators to your watchlist by clicking the bookmark symbol.

Telegram Notifications
  1. On the menu of Grafana, select Notification channels under the bell icon.

  2. Click on Add channel.

  3. Give the notification channel a name.

  4. Select Telegram from the Type list.

  5. To complete the Telegram API settings, a Telegram channel and bot are required. For instructions on setting up a bot with @Botfather, see this section of the Telegram documentation.

  6. Once completed, invite the bot to the newly created channel.

Discord Notifications
  1. On the menu of Grafana, select Notification channels under the bell icon.

  2. Click on Add channel.

  3. Add a name to the notification channel.

  4. Select Discord from the Type list.

  5. To complete the set up, a Discord server (and a text channel available) as well as a Webhook URL are required. For instructions on setting up a Discord's Webhooks, see this section of their documentation.

  6. Enter the Webhook URL in the Discord notification settings panel.

  7. Click Send Test, which will push a confirmation message to the Discord channel.

Slack Notifications
  1. On the menu of Grafana, select Notification channels under the bell icon.

  2. Click on Add channel.

  3. Add a name to the notification channel.

  4. Select Slack from the Type list.

  5. For instructions on setting up a Slack's Incoming Webhooks, see this section of their documentation.

  6. Enter the Slack Incoming Webhook URL in the URL field.

  7. Click Send Test, which will push a confirmation message to the Slack channel.

🎉 Congrats on setting up your validator! You're good to go on eth2.0.

Did you find our guide useful? Let us know with a tip and we'll keep updating it.

Use cointr.ee to find our donation addresses. 🙏

Any feedback and all pull requests much appreciated. 😊

Hang out and chat with fellow stakers on telegram @ https://t.me/coincashew 🌛

🧙♂ 9. Updating Teku

cd ~/git/teku
git pull
./gradlew distTar installDist

Restart beacon chain and validator as per normal operating procedures.

Systemd - Automated
CLI - Manual
Systemd - Automated
sudo systemctl stop beacon-chain
sudo cp -r $HOME/git/teku/build/install/teku/. /usr/bin/teku
sudo systemctl reload-or-restart beacon-chain
CLI - Manual
killall teku
sudo cp -r $HOME/git/teku/build/install/teku/. /usr/bin/teku
/usr/local/teku/bin/teku -c /etc/teku/teku.yaml

🧩 10. Reference Material

Appreciate the hard work done by the fine folks at the following links which served as a foundation for creating this guide.

🎉 11. Bonus Links

🌰 CoinCashew Guides for other ETH2 Clients

🧱 ETH2 Block Explorers

🗒 Latest Eth2 Info

🔥 12. Additional Useful Tips

🛑 12.1 Voluntary exit a validator

Use this command to signal your intentions to stop validating with your validator. This means you no longer want to stake with your validator and want to turn off your node.

  • Voluntary exiting takes a minimum of 2048 epochs (or ~9days). There is a queue to exit and a delay before your validator is finally exited.

  • Once a validator is exited in phase 0, this is non-reversible and you can no longer restart validating again.

  • Your funds will not be available for withdrawal until phase 1.5 or later.

  • After your validator leaves the exit queue and is truely exited, it is safe to turn off your beacon node and validator.

#TO BE DETERMINED

🔐 12.2 Verify your mnemonic phrase

Using the eth2deposit-cli tool, ensure you can regenerate the same eth2 key pairs by restoring your validator_keys

./deposit existing-mnemonic --chain mainnet

When the pubkey is identical, this means your keystore file you correctly verified your mnemonic phrase. Other fields will be different because of salting.

🤖 12.3 Add additional validators

Using the eth2deposit-cli tool, you can add more validators by creating a new deposit data file and validator_keys

For example, in case we originally created 3 validators but now wish to add 5 more validators, we could use the following command.

./deposit existing-mnemonic --validator_start_index 3 --num_validators 5 --chain mainnet

Complete the steps of uploading the deposit_data-#########.json to the launch pad site.