Running a Node

Once you’ve installed and configured your Tempo node, you’re ready to start it and connect to the network.

Starting Your Node

Quick Start (Testnet)

The fastest way to get a node running on testnet:

tempo node --chain moderato --follow

This runs a non-validating follower node that syncs from the official Moderato testnet RPC.

Full Node (Testnet)

Run a full testnet node with RPC access:

tempo node \
  --chain moderato \
  --datadir ~/.tempo/moderato \
  --http --http.addr 0.0.0.0 --http.port 8545 \
  --ws --ws.addr 0.0.0.0 --ws.port 8546

Your node will:

Connect to Moderato testnet peers
Download and verify the blockchain
Expose RPC endpoints at localhost:8545 (HTTP) and localhost:8546 (WebSocket)

Validator Node (Mainnet)

Run a validator node on mainnet:

tempo node \
  --chain mainnet \
  --datadir /var/lib/tempo \
  --consensus.signing-key /etc/tempo/signing-key.hex \
  --consensus.signing-share /etc/tempo/signing-share.hex \
  --consensus.fee-recipient 0xYourFeeRecipientAddress \
  --consensus.listen-address 0.0.0.0:8000 \
  --http --http.addr 127.0.0.1 --http.port 8545

Important for validators:

Ensure ports are properly configured and firewall rules allow consensus traffic
Set a secure fee recipient address
Keep signing keys secure and backed up
Monitor your validator’s performance

Syncing

Initial Sync

When first starting, your node needs to sync with the network.

Method 1: Snapshot Sync (Recommended)

Fast sync using official snapshots:

# Download snapshot first
tempo download --chain moderato

# Then start node
tempo node --chain moderato --datadir ~/.tempo/moderato

Snapshot locations:

Mainnet: https://snapshots.tempoxyz.dev/4217
Moderato (Testnet): https://snapshots.tempoxyz.dev/42431
Andantino (Testnet): https://snapshots.tempoxyz.dev/42429

Method 2: Full Sync

Sync from genesis (slower but trustless):

tempo node --chain moderato --datadir ~/.tempo/moderato

Monitoring Sync Progress

Check sync status via RPC:

cast rpc eth_syncing --rpc-url http://localhost:8545

Output when syncing:

{
  "startingBlock": "0x0",
  "currentBlock": "0x3e8",
  "highestBlock": "0x4e20"
}

Output when synced:

false

Sync Times

Method	Time (Moderato)	Notes
Snapshot	~30 minutes	Recommended for quick start
Full sync	Hours to days	Complete verification from genesis
Follow mode	~5 minutes	Uses existing RPC, minimal storage

Operating Modes

Follow Mode

Run a lightweight node that follows a trusted RPC:

# Auto-detect official RPC
tempo node --chain moderato --follow

# Follow specific RPC
tempo node --chain moderato --follow https://rpc.moderato.tempo.xyz

Advantages:

Fast startup (no historical sync)
Lower storage requirements
Full RPC functionality

Use cases:

Development and testing
RPC gateway
Fast node deployment

Full Node Mode

Run a full node that validates all blocks:

tempo node \
  --chain moderato \
  --datadir ~/.tempo/moderato

Advantages:

Complete chain validation
No trust in external RPC
Can serve as RPC endpoint for others

Use cases:

Production RPC service
Independent verification
Archive node

Validator Mode

Participate in consensus and earn rewards:

tempo node \
  --chain mainnet \
  --consensus.signing-key /path/to/key \
  --consensus.signing-share /path/to/share \
  --consensus.fee-recipient 0xYourAddress

Requirements:

Validator credentials (signing key and share)
Stable infrastructure with high uptime
Open consensus ports
Fee recipient address

Use cases:

Network validation
Earning block rewards
Supporting network security

Development Mode

Run a local development network:

tempo node \
  --dev \
  --http --http.addr 0.0.0.0 --http.port 8545 \
  --http.corsdomain "*"

Features:

Instant block production
Pre-funded dev accounts
All hardforks active
No P2P networking

Use cases:

Smart contract development
Integration testing
Rapid prototyping

Connecting to Networks

Mainnet (Presto)

Production network:

tempo node --chain mainnet

Network details:

Chain ID: 4217
Currency: USD
RPC: https://rpc.testnet.tempo.xyz
Explorer: https://explore.tempo.xyz

Testnet (Moderato)

Primary testnet:

tempo node --chain moderato

Network details:

Chain ID: 42431
Currency: USD
RPC: https://rpc.moderato.tempo.xyz
WebSocket: wss://rpc.moderato.tempo.xyz
Explorer: https://explore.tempo.xyz
Faucet: Available

Alternative Testnet (Andantino)

tempo node --chain testnet

Network details:

Chain ID: 42429
RPC: wss://rpc.testnet.tempo.xyz

Testing Your Node

Check Node Health

Verify your node is running:

cast block-number --rpc-url http://localhost:8545

Test RPC Endpoint

Make a basic RPC call:

cast rpc eth_blockNumber --rpc-url http://localhost:8545

Check Peer Count

cast rpc net_peerCount --rpc-url http://localhost:8545

Healthy nodes typically have 5-50 peers.

Get Chain ID

cast chain-id --rpc-url http://localhost:8545

Test WebSocket Connection

wscat -c ws://localhost:8546 -x '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Monitoring

Logs

View node logs:

# If running in foreground, logs appear in terminal

# If running as systemd service:
sudo journalctl -u tempo -f

# If running in Docker:
docker logs -f tempo-node

Metrics

Consensus metrics are exposed on the metrics endpoint:

curl http://localhost:8001/metrics

Key metrics to monitor:

consensus_block_height: Current block height
consensus_peer_count: Number of connected consensus peers
consensus_proposals_total: Proposals made
consensus_view_number: Current consensus view

System Resources

Monitor resource usage:

# CPU and memory
top -p $(pgrep tempo)

# Disk I/O
iotop -p $(pgrep tempo)

# Network
iftop

Health Checks

Create a simple health check script:

health-check.sh

#!/bin/bash

# Check if process is running
if ! pgrep -x "tempo" > /dev/null; then
    echo "ERROR: Tempo process not running"
    exit 1
fi

# Check RPC responsiveness
if ! cast block-number --rpc-url http://localhost:8545 > /dev/null 2>&1; then
    echo "ERROR: RPC not responding"
    exit 1
fi

echo "OK: Node is healthy"
exit 0

Running as a Service

Systemd Service

Create a systemd service for automatic startup:

/etc/systemd/system/tempo.service

[Unit]
Description=Tempo Node
After=network.target

[Service]
Type=simple
User=tempo
Group=tempo
WorkingDirectory=/var/lib/tempo
ExecStart=/usr/local/bin/tempo node \
  --chain moderato \
  --datadir /var/lib/tempo \
  --http --http.addr 0.0.0.0 --http.port 8545 \
  --ws --ws.addr 0.0.0.0 --ws.port 8546
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=tempo

[Install]
WantedBy=multi-user.target

Manage the service:

# Create tempo user
sudo useradd -r -s /bin/false tempo
sudo mkdir -p /var/lib/tempo
sudo chown tempo:tempo /var/lib/tempo

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable tempo
sudo systemctl start tempo

# Check status
sudo systemctl status tempo

# View logs
sudo journalctl -u tempo -f

Docker Service

Run as a Docker container:

docker run -d \
  --name tempo-node \
  --restart unless-stopped \
  -p 30303:30303 \
  -p 8545:8545 \
  -p 8546:8546 \
  -v tempo-data:/data \
  ghcr.io/tempoxyz/tempo:latest \
  node \
  --chain moderato \
  --datadir /data \
  --http --http.addr 0.0.0.0 --http.port 8545 \
  --ws --ws.addr 0.0.0.0 --ws.port 8546

Firewall Configuration

Required Ports

Open these ports in your firewall:

Port	Protocol	Purpose	Required For
30303	TCP/UDP	P2P execution layer	All nodes
8000	TCP	Consensus P2P	Validators
8545	TCP	HTTP RPC	Optional (if exposing RPC)
8546	TCP	WebSocket RPC	Optional (if exposing RPC)
8001	TCP	Consensus metrics	Optional (internal only)

UFW Configuration

# Allow P2P
sudo ufw allow 30303/tcp
sudo ufw allow 30303/udp

# Allow consensus (validators only)
sudo ufw allow 8000/tcp

# Allow RPC (if exposing publicly)
sudo ufw allow 8545/tcp
sudo ufw allow 8546/tcp

iptables Configuration

# Allow P2P
sudo iptables -A INPUT -p tcp --dport 30303 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 30303 -j ACCEPT

# Allow consensus
sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT

Stopping Your Node

Graceful Shutdown

# If running in foreground
Ctrl+C

# If running as systemd service
sudo systemctl stop tempo

# If running in Docker
docker stop tempo-node

Force Stop

Only if graceful shutdown fails:

# Kill process
kill $(pgrep tempo)

# Force kill if necessary
kill -9 $(pgrep tempo)

Troubleshooting

Node Won’t Start

Check logs for errors:

tempo node --chain moderato 2>&1 | tee tempo-startup.log

Common issues:

Port already in use
Insufficient disk space
Corrupted database
Missing signing keys (validators)

No Peers

If your node has zero peers:

# Check firewall
sudo ufw status

# Verify port is listening
netstat -tulpn | grep 30303

# Check network connectivity
ping -c 3 rpc.moderato.tempo.xyz

Sync Stuck

If sync appears stuck:

# Check if still progressing (wait a few minutes between checks)
cast block-number --rpc-url http://localhost:8545

# Restart node
sudo systemctl restart tempo

# If still stuck, resync from snapshot
rm -rf ~/.tempo/moderato/db
tempo download --chain moderato

High Resource Usage

# Check disk usage
df -h ~/.tempo/moderato

# Check memory
free -h

# Reduce memory usage by limiting cache
tempo node --chain moderato --max-cache-size 2048

Next Steps

Maintenance - Keep your node updated and healthy
API Reference - Learn how to interact with your node’s RPC

Get Started

Core Concepts

Running a Node

Building on Tempo

SDKs

​Starting Your Node

​Quick Start (Testnet)

​Full Node (Testnet)

​Validator Node (Mainnet)

​Syncing

​Initial Sync

​Method 1: Snapshot Sync (Recommended)

​Method 2: Full Sync

​Monitoring Sync Progress

​Sync Times

​Operating Modes

​Follow Mode

​Full Node Mode

​Validator Mode

​Development Mode

​Connecting to Networks

​Mainnet (Presto)

​Testnet (Moderato)

​Alternative Testnet (Andantino)

​Testing Your Node

​Check Node Health

​Test RPC Endpoint

​Check Peer Count

​Get Chain ID

​Test WebSocket Connection

​Monitoring

​Logs

​Metrics

​System Resources

​Health Checks

​Running as a Service

​Systemd Service

​Docker Service

​Firewall Configuration

​Required Ports

​UFW Configuration

​iptables Configuration

​Stopping Your Node

​Graceful Shutdown

​Force Stop

​Troubleshooting

​Node Won’t Start

​No Peers

​Sync Stuck

​High Resource Usage

​Next Steps

Starting Your Node

Quick Start (Testnet)

Full Node (Testnet)

Validator Node (Mainnet)

Syncing

Initial Sync

Method 1: Snapshot Sync (Recommended)

Method 2: Full Sync

Monitoring Sync Progress

Sync Times

Operating Modes

Follow Mode

Full Node Mode

Validator Mode

Development Mode

Connecting to Networks

Mainnet (Presto)

Testnet (Moderato)

Alternative Testnet (Andantino)

Testing Your Node

Check Node Health

Test RPC Endpoint

Check Peer Count

Get Chain ID

Test WebSocket Connection

Monitoring

Logs

Metrics

System Resources

Health Checks

Running as a Service

Systemd Service

Docker Service

Firewall Configuration

Required Ports

UFW Configuration

iptables Configuration

Stopping Your Node

Graceful Shutdown

Force Stop

Troubleshooting

Node Won’t Start

No Peers

Sync Stuck

High Resource Usage

Next Steps