Telos EVM v2.0 Installer

Description

This repo contains a script to install the Telos EVM automatically from backup as well as detailed manual install instructions.

Quick Start

To install with 1 line, ensure that wget and sudo are already installed and then run:

TEMP_DIR=$(mktemp -d) && curl -o "$TEMP_DIR/run.sh" https://raw.githubusercontent.com/telosnetwork/telos-evm-installer/refs/heads/main/run.sh && bash "$TEMP_DIR/run.sh" && rm -rf "$TEMP_DIR"

Alternatively, the automated script for install can be downloaded from https://raw.githubusercontent.com/telosnetwork/telos-evm-installer/refs/heads/main/run.sh

Fast mode is the default and is suitable for most Telos EVM RPC nodes:

bash run.sh --bootstrap-mode fast

Archive mode also restores native nodeos block logs and SHiP state-history:

bash run.sh --bootstrap-mode archive

Telos EVM 2.0 Node Installation Script Documentation

This document explains how to use and configure the Telos node installation script. The script automates the process of setting up a complete Telos node environment including nodeos, reth, and the consensus client.

Prerequisites

Before running the script, ensure your system meets these requirements:

• Ubuntu 22.04 or 24.04 LTS
• Sudo privileges
• Internet connectivity
• Minimum 16GB RAM, 32GB recommended
• Minimum 8 Cores, 16 cores recommended
• At least 500GB of solid-state storage
• Archive mode requires multiple TiB of solid-state storage
• Ports available for node operation

Configuration Options

The script will prompt for several configuration options. Here's what each one means:

Installation Directory

• Default: ./telos or /telos if run from root
• Purpose: Base directory where all Telos node components will be installed
• Storage requirements: Ensure sufficient disk space in the chosen location

Version Tag

• Default: telos-v1.0.1
• Purpose: Specifies which version of the Telos software to install
• Format: Must match a valid release tag from the Telos repositories

Bootstrap Mode

• Default: fast
• fast: Restores nodeos from a state snapshot and restores reth from the latest validated backup. Native nodeos block history starts at the snapshot block, not block 1.
• archive: Restores the same EVM stack plus native block logs and SHiP state-history from mainnet-ship into nodeos-ship. This is intended for operators who need native historical blocks or SHiP history.

The installer discovers dated backup artifacts from https://storage.telos.net/evm_backups/mainnet. Nodeos snapshots are read from the main backup folder, while Telos EVM 2 reth backups are read from https://storage.telos.net/evm_backups/mainnet/telos-evm-2. The reth folder must contain a matching reth-data-*.tar.zst, reth-data-*.tar.zst.sha256, and reth-data-*.tar.zst.manifest.txt.

The installer reads the reth manifest and compares the backup height against live Telos mainnet. Stale Reth backups warn by default and are allowed to sync forward. The default warning threshold is 345600 blocks, about two days at 0.5 second block times.

In fast mode, the installer chooses the newest nodeos snapshot at or before the Reth backup height. This preserves native block continuity from the restored Reth point forward while still allowing older Reth backups to catch up.

Keep at least one compatible nodeos snapshot at or before each retained Reth backup height. If every available nodeos snapshot is newer than the Reth backup, fast mode will fail and ask for a matching snapshot, a newer Reth backup, or archive mode.

The default telos-v1.0.1 install expects a reth backup produced by Reth 1.0.8. The installer checks the manifest reth_binary field before downloading the backup and refuses backups generated by a different Reth version. This prevents accidentally restoring a Telos EVM 3 / Reth 2 datadir into the Telos EVM 2 installer.

Disk-space checks also run before large downloads:

• Fast mode default requirement: 500 GiB
• Archive mode default requirement: 3800 GiB

To turn the freshness warning into a hard guard:

STRICT_BACKUP_FRESHNESS_CHECK=true bash run.sh --bootstrap-mode fast

To bypass the strict freshness guard intentionally:

STRICT_BACKUP_FRESHNESS_CHECK=true ALLOW_STALE_BACKUPS=true bash run.sh --bootstrap-mode fast

If you intentionally change the telos-reth release tag, set the matching expected Reth binary version:

EXPECTED_RETH_VERSION=1.0.8 bash run.sh --bootstrap-mode fast

To point at a staging backup folder while validating a new publication:

RETH_BACKUP_BASE_URL=https://storage.telos.net/evm_backups/mainnet/telos-evm-2-staging bash run.sh --bootstrap-mode fast

Only bypass the reth backup compatibility guard after independently verifying datadir compatibility:

SKIP_RETH_BACKUP_COMPATIBILITY_CHECK=true bash run.sh --bootstrap-mode fast

Geographic Region

• Options: east or west
• Default: west
• Purpose: Optimizes peer connections based on your location
  • East: Asia/Europe
  • West: North/South America
• Impact: Affects which peer list is used for node connections

Port Configuration

The script requires several ports for different services. Default ports are:

Service	Port Type	Default Port	Listen Address	Description
Nodeos HTTP	RPC	8888	127.0.0.1	Main API endpoint
Nodeos HTTP	P2P	9876	127.0.0.1	Peer communication
Nodeos SHIP	RPC	9888	127.0.0.1	State-History endpoint
Nodeos SHIP	WebSocket	18999	0.0.0.0	SHIP WebSocket
Nodeos SHIP	P2P	9877	127.0.0.1	SHIP peer communication
Reth	RPC	8545	0.0.0.0	EVM RPC endpoint
Reth	WebSocket	8546	0.0.0.0	EVM WebSocket endpoint
Reth	Auth RPC	8551	127.0.0.1	JWT-protected endpoint
Reth	Discovery	30303	127.0.0.1	Network discovery

Installation Components

The script installs and configures several components:

System Dependencies

• git
• curl
• build-essential
• clang
• libclang-dev
• gcc
• make
• zstd
• pkg-config
• jq
• libatomic1
• libcurl4
• libgmp10
• zlib1g
• libssl-dev

Core Components

1. Nodeos (TelosZero Core 1.2.2): Telos-maintained Antelope-derived node software

   • Installed from: telosnetwork/teloszero-core release teloszero-v1.2.2
   • Package: teloszero-core_1.2.2_amd64.deb
   • Configuration location: {install_dir}/nodeos-http/config.ini and {install_dir}/nodeos-ship/config.ini
   • Log location: {install_dir}/nodeos-http/nodeos.log and {install_dir}/nodeos-ship/nodeos.log

2. Reth: Telos EVM execution client

   • Configuration location: {install_dir}/telos-reth/.env
   • Log location: {install_dir}/telos-reth/reth.log

3. Consensus Client: Telos consensus layer

   • Configuration location: {install_dir}/telos-consensus-client/config.toml
   • Log location: {install_dir}/telos-consensus-client/consensus.log

Backup Validation

Before downloading large artifacts, the installer:

• Resolves a dated nodeos snapshot instead of relying on an opaque latest alias. In fast mode, it chooses the newest snapshot at or before the Reth backup height.
• Resolves the latest dated Telos EVM 2 reth backup manifest and backup archive from telos-evm-2/
• Verifies the reth backup manifest was produced by the expected Reth binary version
• Verifies the reth backup checksum when the .sha256 file is published
• Compares the reth backup height to live Telos mainnet
• In archive mode, verifies the native SHiP archive advertises earliest_available_block_num=1
• Waits for local nodeos to reach the reth backup height before starting reth/consensus
• Verifies reth can serve EVM block 0x0 and a finalized block before generating consensus config

Publishing Telos EVM 2 Reth Backups

Use scripts/publish-telos-evm2-reth-backup.sh on a synced production Telos EVM 2 Reth 1.0.8 host to publish the installer-compatible backup folder. The script validates web3_clientVersion, checks the local block hash against public RPC, stages the datadir, writes the manifest, produces a .sha256, and uploads the artifact set to telos-evm-2/ on the storagebox.

Run it from a host that has the storagebox key and a local Reth 1 RPC:

INSTALL_DIR=/opt/telos-evm-2 \
RETH_BACKUP_DATADIR=/opt/telos-evm-2/telos-reth-data \
RETH_BACKUP_LOCAL_RPC=http://127.0.0.1:8545 \
RETH_BACKUP_PUBLIC_RPC=https://rpc.telos.net/evm \
STORAGEBOX_BASE=telos-evm-2 \
scripts/publish-telos-evm2-reth-backup.sh

For a fully consistent final pass, drain the node from public traffic and provide the service names:

RETH_BACKUP_STOP_SERVICES=1 \
RETH_SERVICE=telos-reth.service \
CONSENSUS_SERVICE=telos-consensus-client.service \
scripts/publish-telos-evm2-reth-backup.sh

If the node is managed by local start/stop scripts instead of systemd units, provide commands:

RETH_BACKUP_STOP_SERVICES=1 \
RETH_STOP_COMMAND=/telos/telos-reth/stop.sh \
RETH_START_COMMAND=/telos/telos-reth/start.sh \
CONSENSUS_STOP_COMMAND=/telos/telos-consensus-client/stop.sh \
CONSENSUS_START_COMMAND=/telos/telos-consensus-client/start.sh \
scripts/publish-telos-evm2-reth-backup.sh

Log Management

The script configures logrotate for all service logs:

• Rotation frequency: Daily
• Number of backups: 5
• Compression: Enabled
• File permissions: 0644 (root:root)

Security Considerations

1. Network Security

   • Most services listen on localhost (127.0.0.1)
   • Only Reth RPC/WS ports are exposed publicly
   • Recommended to use a reverse proxy with SSL for public endpoints

2. Configuration Security

   • JWT authentication between Reth and consensus client
   • Default signer key should be updated for production use
   • Access control headers can be customized in nodeos config

Post-Installation

After installation completes:

1. Verify all services are running using the provided status scripts
2. Configure your reverse proxy for the public RPC endpoints
3. Monitor the logs for any synchronization issues at the below path. When syncing gets to the head block, you will see a rate of 2 blocks per second.
   • tail -f {install_dir}/telos-consensus-client/consensus.log | grep sec

Service Management

Each component has its own start/stop scripts:

# Start a service
{install_dir}/{service}/start.sh

# Stop a service
{install_dir}/{service}/stop.sh

Troubleshooting

Common issues and solutions:

1. Port Conflicts

   • The script checks for port availability
   • Change ports if conflicts occur
   • Verify no other services are using the required ports

2. Resource Issues

   • Monitor system resources during sync
   • Adjust chain-state-db-size-mb if needed
   • Check disk space regularly

3. Network Issues

   • Verify peer connections in nodeos logs
   • Check firewall settings for required ports
   • Monitor network bandwidth usage

Additional Resources

• Telos Documentation
• Telos EVM Documentation
• Telos Network Monitor

For support, join the Telos Discord or open an issue on GitHub.