Taiko Upgrade Guide

This guide covers upgrading your Taiko node to newer versions safely and efficiently.

Before You Start

Pre-Upgrade Checklist

# 1. Check current version
taiko-client --version

# 2. Backup your node data
sudo systemctl stop taiko-node
tar -czf taiko-backup-$(date +%Y%m%d).tar.gz ~/.taiko

# 3. Check available disk space (need at least 20GB free)
df -h

# 4. Note your current configuration
cp ~/.taiko/config.toml ~/.taiko/config.toml.backup

# 5. Check network status
curl -s localhost:8545 -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Important Notes

warning

Taiko protocol upgrades may require network-wide coordination. Check official announcements before upgrading.

info

Always check the Taiko releases page for specific upgrade instructions and breaking changes.

Upgrade Methods

Method 1: Docker Upgrade (Recommended)

Docker Compose

# 1. Stop current containers
docker-compose down

# 2. Backup current configuration
cp docker-compose.yml docker-compose.yml.backup
cp .env .env.backup

# 3. Update to latest version
# Edit docker-compose.yml to use latest tags
sed -i 's/taiko-client:.*/taiko-client:latest/g' docker-compose.yml

# 4. Pull latest images
docker-compose pull

# 5. Start with new version
docker-compose up -d

# 6. Check logs
docker-compose logs -f taiko-node

Simple Taiko Node

# If using simple-taiko-node repository
cd simple-taiko-node

# 1. Stop current node
docker-compose down

# 2. Backup configuration
cp .env .env.backup

# 3. Update repository
git fetch origin
git pull origin main

# 4. Update environment if needed
# Check .env.sample for new variables
diff .env.sample .env.backup

# 5. Start updated node
docker-compose up -d

# 6. Monitor startup
docker-compose logs -f

Method 2: Binary Upgrade

# 1. Stop the service
sudo systemctl stop taiko-node

# 2. Download latest binaries
LATEST_VERSION=$(curl -s https://api.github.com/repos/taikoxyz/taiko-mono/releases/latest | jq -r .tag_name)

# Download taiko-client
wget -O taiko-client https://github.com/taikoxyz/taiko-mono/releases/download/$LATEST_VERSION/taiko-client-linux-amd64
chmod +x taiko-client
sudo mv taiko-client /usr/local/bin/

# 3. Verify version
taiko-client --version

# 4. Start service
sudo systemctl start taiko-node

# 5. Check status
sudo systemctl status taiko-node

Network-Specific Upgrades

Mainnet Upgrade

# For mainnet upgrades, coordination is critical
# 1. Check network status first
curl -s https://rpc.mainnet.taiko.xyz -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# 2. Wait for network-wide upgrade signal
# Monitor Taiko Discord/Twitter for upgrade timing

# 3. Upgrade when network is ready
# Follow standard upgrade process but with mainnet configs

# 4. Update L1 endpoint if changed
# L1_ENDPOINT_HTTP=https://eth-mainnet.alchemyapi.io/v2/YOUR_KEY
# L1_ENDPOINT_WS=wss://eth-mainnet.alchemyapi.io/v2/YOUR_KEY

Testnet Upgrade (Holesky)

# Testnet upgrades are more frequent and experimental
# 1. Update environment variables
export NETWORK=holesky
export L1_ENDPOINT_HTTP=https://holesky.infura.io/v3/YOUR_KEY
export L1_ENDPOINT_WS=wss://holesky.infura.io/v3/YOUR_KEY

# 2. Clear testnet data if required
sudo systemctl stop taiko-node
rm -rf ~/.taiko/holesky/
sudo systemctl start taiko-node

Version-Specific Upgrades

Upgrading to Alpha-7 (Major Protocol Update)

Breaking Changes

Alpha-7 introduces significant protocol changes. Complete data reset required.

# 1. Stop node
sudo systemctl stop taiko-node

# 2. Clear all data (REQUIRED)
rm -rf ~/.taiko/data

# 3. Update configuration for Alpha-7
# Download new config template
wget -O ~/.taiko/config.toml https://raw.githubusercontent.com/taikoxyz/simple-taiko-node/main/config/alpha-7.toml

# 4. Update environment variables
# New variables for Alpha-7:
export ENABLE_PROPOSER=true
export PROPOSE_INTERVAL=30s
export PROVER_CAPACITY=8

# 5. Upgrade to Alpha-7 binaries
# [Follow binary upgrade process with Alpha-7 release]

# 6. Initialize new data
taiko-client driver --config ~/.taiko/config.toml --init

# 7. Start node
sudo systemctl start taiko-node

Upgrading to Based Contestable Rollup (BCR)

# BCR introduces new contestation mechanism
# 1. New required environment variables
export ENABLE_CONTESTATION=true
export CONTESTATION_TIER=optimistic
export BOND_AMOUNT=1000000000000000000  # 1 ETH in wei

# 2. Update prover configuration
export PROVER_ENDPOINTS="http://localhost:9090,http://backup-prover:9090"
export PROVING_TIMEOUT=3600  # 1 hour

# 3. Configure bond management
export BOND_MANAGER_PRIVATE_KEY="your_bond_manager_key"

# 4. Update to BCR-compatible version
# [Follow standard upgrade process]

Configuration Updates

Environment Variables Migration

.env

# Network Configuration
NETWORK=mainnet  # or holesky
CHAIN_ID=167000  # mainnet, 167008 for holesky

# L1 Ethereum Configuration  
L1_ENDPOINT_HTTP=https://eth-mainnet.alchemyapi.io/v2/YOUR_KEY
L1_ENDPOINT_WS=wss://eth-mainnet.alchemyapi.io/v2/YOUR_KEY

# Taiko L2 Configuration
L2_ENDPOINT_HTTP=http://localhost:8545
L2_ENDPOINT_WS=ws://localhost:8546

# Node Configuration
ENABLE_PROPOSER=false  # Set to true for proposers
ENABLE_PROVER=false    # Set to true for provers

# Proposer Settings (if enabled)
PROPOSE_INTERVAL=12s
PROPOSER_PRIVATE_KEY=your_proposer_private_key

# Prover Settings (if enabled)  
PROVER_CAPACITY=1
PROVER_PRIVATE_KEY=your_prover_private_key
PROVER_ENDPOINTS=http://localhost:9090

# Database
DATABASE_URL=postgres://user:password@localhost/taiko

# Metrics
ENABLE_METRICS=true
METRICS_PORT=9090

Config File Updates

~/.taiko/config.toml

[node]
network = "mainnet"
data_dir = "/root/.taiko/data"

[l1]
endpoint = "https://eth-mainnet.alchemyapi.io/v2/YOUR_KEY"
ws_endpoint = "wss://eth-mainnet.alchemyapi.io/v2/YOUR_KEY"

[l2]
http_port = 8545
ws_port = 8546
engine_endpoint = "http://localhost:8551"

[driver]
sync_mode = "full"
snap_sync = true

[proposer]
enabled = false
interval = "12s"
gas_limit = 15000000

[prover] 
enabled = false
capacity = 1
timeout = "1h"

[metrics]
enabled = true
port = 9090

Post-Upgrade Verification

Health Checks

# 1. Check service status
sudo systemctl status taiko-node

# 2. Verify L2 RPC is responding
curl -s localhost:8545 -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# 3. Check sync status
curl -s localhost:8545 -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'

# 4. Verify connection to L1
curl -s localhost:8545 -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"taiko_l1Origin","params":[],"id":1}'

# 5. Check proposer status (if enabled)
curl -s localhost:9090/metrics | grep taiko_proposer

# 6. Check prover status (if enabled)  
curl -s localhost:9090/metrics | grep taiko_prover

# 7. Monitor logs
journalctl -u taiko-node -f

Performance Validation

# Monitor proving performance
watch -n 5 'curl -s localhost:9090/metrics | grep taiko_prover_proof'

# Check L1 submission frequency
watch -n 30 'curl -s localhost:9090/metrics | grep taiko_proposer_proposals'

# Monitor resource usage
watch -n 10 'docker stats --no-stream'

# Check database size growth
du -sh ~/.taiko/data

Rollback Procedure

# If upgrade fails
# 1. Stop current node
sudo systemctl stop taiko-node

# 2. Restore backup
rm -rf ~/.taiko
tar -xzf taiko-backup-YYYYMMDD.tar.gz -C ~/

# 3. Revert to previous version
# For Docker:
cp docker-compose.yml.backup docker-compose.yml
docker-compose down
docker-compose up -d

# For binary:
# Download and install previous version

# 4. Start service
sudo systemctl start taiko-node

# 5. Verify rollback
curl -s localhost:8545 -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Automation Scripts

Upgrade Automation

upgrade-taiko.sh

#!/bin/bash
set -e

echo "🔄 Starting Taiko Node Upgrade..."

# Configuration  
BACKUP_DIR="$HOME/taiko-backups"
SERVICE_NAME="taiko-node"

# Create backup
mkdir -p "$BACKUP_DIR"
echo "💾 Creating backup..."
sudo systemctl stop $SERVICE_NAME
BACKUP_FILE="$BACKUP_DIR/taiko-backup-$(date +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$BACKUP_FILE" ~/.taiko .env docker-compose.yml

# Update
if [ -d "simple-taiko-node" ]; then
  echo "🔄 Updating simple-taiko-node..."
  cd simple-taiko-node
  git pull origin main
  docker-compose pull
  docker-compose up -d
else
  echo "🐳 Updating Docker containers..."
  docker-compose pull
  docker-compose up -d
fi

# Verify
echo "⏳ Waiting for startup..."
sleep 60

if curl -s localhost:8545 > /dev/null; then
  echo "🎉 Upgrade successful!"
  echo "📂 Backup: $BACKUP_FILE"
else
  echo "❌ Upgrade failed!"
  exit 1
fi

Troubleshooting Upgrades

Common Issues

Sync Issues After Upgrade

# Reset sync if corrupted
sudo systemctl stop taiko-node
rm -rf ~/.taiko/data/chaindata
sudo systemctl start taiko-node

# Check for L1 endpoint issues
curl -s $L1_ENDPOINT_HTTP -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Prover Not Working

# Check prover configuration
echo "ENABLE_PROVER: $ENABLE_PROVER"
echo "PROVER_ENDPOINTS: $PROVER_ENDPOINTS" 

# Test prover connection
curl -s localhost:9090/metrics | grep prover

# Restart prover service
docker-compose restart taiko-prover

Best Practices

1. Network Coordination: Wait for official upgrade announcements
2. Backup Strategy: Always backup before major upgrades
3. Gradual Rollout: Test on holesky before mainnet
4. Monitor Health: Watch metrics after upgrade
5. L1 Dependency: Ensure L1 endpoint compatibility
6. Resource Planning: Upgrades may increase resource needs

Resources

• Taiko Releases
• Simple Taiko Node
• Discord Announcements
• Documentation