Configuration

This guide covers all configuration options for the SSV Node. Configuration is done via a YAML file, typically located at config/config.yaml.

Configuration File Location

The default configuration file location is specified when starting the node:

./bin/ssvnode start-node --config ./config/config.yaml

You can use the example configuration as a starting point:

cp config/config.example.yaml config/config.yaml

Complete Configuration Reference

Global Settings

General settings that affect the entire node operation.

global:
  # Console log level: debug, info, warn, error, fatal, panic
  LogLevel: info
  
  # Path to persistent debug log file
  LogFilePath: ./data/debug.log

global.LogLevel

string

default:"info"

Log verbosity level. Options:

debug - Detailed debugging information (verbose)
info - General informational messages (recommended)
warn - Warning messages only
error - Error messages only
fatal - Fatal errors that cause shutdown
panic - Panic-level errors

global.LogFilePath

string

default:"./data/debug.log"

File path where debug logs are written. Logs are appended to this file.

Database Configuration

Settings for the node’s persistent storage.

db:
  # Path to persistent database directory
  Path: ./data/db

db.Path

string

required

Directory path for storing the BadgerDB database. This contains:

Validator shares and metadata
Operator information
Network state

Ensure this directory has sufficient disk space and is backed up regularly.

The database uses BadgerDB for efficient key-value storage with SSZ encoding.

SSV Network

Configure which SSV network to join.

ssv:
  # Network to join: mainnet or holesky
  Network: mainnet

ssv.Network

string

default:"mainnet"

The SSV network to connect to:

mainnet - Production network on Ethereum mainnet
holesky - Testnet network on Holesky testnet

Ethereum Beacon Node (ETH2)

Configuration for connecting to the Ethereum consensus layer.

eth2:
  # HTTP(S) URL of Beacon node
  BeaconNodeAddr: http://your-beacon-node.example:5052

  ValidatorOptions:
    # Additional validator options (optional)

eth2.BeaconNodeAddr

string

required

HTTP or HTTPS URL of your Ethereum Beacon node. The node uses this to:

Fetch validator duties
Submit attestations and proposals
Monitor chain state

Supports multiple beacon nodes for redundancy (comma-separated):

BeaconNodeAddr: http://beacon1:5052,http://beacon2:5052

eth2.ValidatorOptions

object

Advanced validator configuration options. See beacon client documentation for available options.

Ensure your beacon node is fully synced before starting the SSV node. An unsynced beacon node will cause duty failures.

Ethereum Execution Node (ETH1)

Configuration for connecting to the Ethereum execution layer.

eth1:
  # WebSocket URL of Ethereum execution node
  ETH1Addr: ws://your-eth1-node.example:8546/ws

eth1.ETH1Addr

string

required

WebSocket URL of your Ethereum execution node. Used to:

Monitor SSV smart contract events
Sync operator and validator registrations
Track network state changes

Must use WebSocket protocol (ws:// or wss://) for event subscriptions.

Use a reliable execution node provider or run your own node for maximum reliability. Archive nodes are not required.

P2P Network Configuration

Peer-to-peer networking settings.

p2p:
  # External IP address (auto-detected if not specified)
  # HostAddress: 192.168.1.1
  
  # Override default ports
  # TcpPort: 13001
  # UdpPort: 12001
  
  # Discovery method (for local development)
  # Discovery: mdns

p2p.HostAddress

string

External IP address of your node.

Auto-detected if not specified
Must be set manually if behind NAT or using non-standard networking
Required for proper peer discovery

p2p.TcpPort

number

default:"13001"

TCP port for P2P communication. Must be publicly accessible for incoming connections.

p2p.UdpPort

number

default:"12001"

UDP port for P2P discovery (discv5 protocol). Must be publicly accessible for peer discovery.

p2p.Discovery

string

Discovery mechanism. Options:

Not set (default) - Uses discv5 for production
mdns - Multicast DNS for local development networks

Firewall Configuration RequiredEnsure both TCP and UDP ports are open in your firewall:

# Example for ufw
sudo ufw allow 13001/tcp
sudo ufw allow 12001/udp

Operator Keys

Configure your operator’s private key. Choose one method only.

Encrypted Keystore (Recommended)
Raw Private Key (Not Recommended)

KeyStore:
  PrivateKeyFile: /path/to/encrypted_private_key.json
  PasswordFile: /path/to/password.txt

Generate encrypted keystore:

./bin/ssvnode generate-operator-keys --password-file=password.txt

KeyStore.PrivateKeyFile

string

Path to encrypted keystore JSON file

KeyStore.PasswordFile

string

Path to file containing keystore password

Recommended for Production - Provides encryption at rest with password protection.

OperatorPrivateKey: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVB...

Generate raw key:

./bin/ssvnode generate-operator-keys

OperatorPrivateKey

string

Base64-encoded RSA private key

Not Recommended for Production - This method only encodes the key, it doesn’t encrypt it. Use encrypted keystore instead.

Converting Existing Keys

Convert a raw private key to encrypted keystore:

./bin/ssvnode generate-operator-keys \
  --password-file=password.txt \
  --operator-key-file=existing_key.txt

MEV Configuration (Optional)

Advanced settings for MEV (Maximal Extractable Value) optimization.

# Duration to wait before requesting block proposal
# Allows extracting higher MEV by waiting for better bids
# ProposerDelay: 300ms

# Safety flag for delays > 1s (dangerous!)
# AllowDangerousProposerDelay: false

ProposerDelay

duration

default:"0"

Time delay before requesting block proposals. This allows MEV relays more time to build higher-value blocks.

Default: 0 (no delay)
Recommended starting value: 300ms
Maximum safe value: 1000ms (1 second)

See docs/MEV_CONSIDERATIONS.md in the source repository for detailed information.

AllowDangerousProposerDelay

boolean

default:"false"

Safety flag that must be set to true to allow ProposerDelay values above 1 second.

Proposer Delay RisksValues above 1 second significantly increase the risk of missing block proposals! Only increase this value if you:

Fully understand the MEV documentation
Accept the risk of missed proposals
Have monitored lower delays successfully

Monitoring & Metrics

Enable monitoring interfaces for observability.

# Prometheus metrics endpoint
MetricsAPIPort: 15000

# Enable OpenTelemetry traces
EnableTraces: false

# SSV API endpoint (keep private!)
# SSVAPIPort: 16000

MetricsAPIPort

number

default:"15000"

Port for Prometheus-compatible metrics endpoint.Access metrics at: http://localhost:15000/metricsProvides metrics for:

Validator performance
P2P connectivity
Beacon node status
Consensus participation

EnableTraces

boolean

default:"false"

Enable OpenTelemetry distributed tracing for debugging.

SSVAPIPort

number

Port for SSV REST API. Documentation at ssvlabs.github.io/ssv

Keep API Private - The SSV API should not be publicly exposed as it can be resource-intensive. Bind to localhost or use firewall rules.

Local Development

Settings for running local development networks.

# Path to local events file (for testing)
# LocalEventsPath: ./config/events.yaml

LocalEventsPath

string

Path to events YAML file for simulating contract events in local development.Use with local 4-node networks to simulate validator registration without actual blockchain events.

Local Development Setup

For local testing with multiple nodes:

LocalEventsPath: ./config/events.yaml
p2p:
  Discovery: mdns

Generate local configuration:

./scripts/generate_local_config.sh 4 \
  ./keystore.json \
  "password" \
  0x1234567890123456789012345678901234567890 \
  0

Then run:

make docker-all

Example Configurations

global:
  LogLevel: info
  LogFilePath: /var/log/ssv/debug.log

db:
  Path: /var/lib/ssv/db

ssv:
  Network: mainnet

eth2:
  BeaconNodeAddr: http://localhost:5052

eth1:
  ETH1Addr: ws://localhost:8546/ws

p2p:
  HostAddress: 203.0.113.10
  TcpPort: 13001
  UdpPort: 12001

KeyStore:
  PrivateKeyFile: /etc/ssv/encrypted_private_key.json
  PasswordFile: /etc/ssv/password.txt

MetricsAPIPort: 15000

For multi-operator setups, you can use separate share configuration files:

./bin/ssvnode start-node \
  --config ./config/config.yaml \
  --share-config ./config/share1.yaml

Example share configuration (config/example_share.yaml):

db:
  Path: ./data/db/node1

OperatorPrivateKey: <operator-private-key>

This is useful when running multiple operator nodes on the same machine.

Configuration Validation

Validate your configuration before starting:

Check YAML syntax

# Using yq
yq eval '.' config/config.yaml

# Or Python
python3 -c "import yaml; yaml.safe_load(open('config/config.yaml'))"

Test connectivity

Verify your beacon and execution nodes are accessible:

# Test beacon node
curl http://your-beacon-node:5052/eth/v1/node/health

# Test execution node (HTTP endpoint)
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://your-eth1-node:8545

Verify file paths

Ensure all file paths exist and are accessible:

# Check keystore file
test -f ./encrypted_private_key.json && echo "Keystore exists" || echo "Keystore missing"

# Check password file
test -f ./password.txt && echo "Password file exists" || echo "Password missing"

Environment Variables

Some settings can be overridden via environment variables (when using Docker):

# In .env file
CONFIG_PATH=/config/config.yaml
SHARE_CONFIG=/config/share1.yaml
DEBUG_PORT=2345  # For debugging

Security Best Practices

Protect sensitive files

Set appropriate file permissions:

# Keystore and password should be readable only by the node process
chmod 600 encrypted_private_key.json
chmod 600 password.txt

# Config file
chmod 644 config/config.yaml

Firewall configuration

Only expose necessary ports:

# Allow P2P
ufw allow 13001/tcp
ufw allow 12001/udp

# Block API ports from external access
ufw deny 15000/tcp  # Metrics
ufw deny 16000/tcp  # SSV API

Backup configuration

Regularly backup your configuration and keystore:

# Backup script
tar -czf ssv-backup-$(date +%Y%m%d).tar.gz \
  config/ \
  encrypted_private_key.json \
  password.txt

Store backups securely offline.

Source Files

Configuration examples are available in the source repository:

/config/config.example.yaml - Main configuration example
/config/example_share.yaml - Share configuration template
/config/events.example.yaml - Local events example

Full documentation: GitHub - ssvlabs/ssv

Overview

Getting Started

Node Operations

Core Concepts

Deployment

Monitoring

Configuration File Location

Complete Configuration Reference

Global Settings

Database Configuration

SSV Network

Ethereum Beacon Node (ETH2)

Ethereum Execution Node (ETH1)

P2P Network Configuration

Operator Keys

Converting Existing Keys

MEV Configuration (Optional)

Monitoring & Metrics

Local Development

Example Configurations

Configuration Validation

Environment Variables

Security Best Practices

Source Files

Build docs developers (and LLMs) love

Overview

Getting Started

Node Operations

Core Concepts

Deployment

Monitoring

​Configuration File Location

​Complete Configuration Reference

​Global Settings

​Database Configuration

​SSV Network

​Ethereum Beacon Node (ETH2)

​Ethereum Execution Node (ETH1)

​P2P Network Configuration

​Operator Keys

​Converting Existing Keys

​MEV Configuration (Optional)

​Monitoring & Metrics

​Local Development

​Example Configurations

​Share Configuration

​Configuration Validation

​Environment Variables

​Security Best Practices

​Source Files

Build docs developers (and LLMs) love

Configuration File Location

Complete Configuration Reference

Global Settings

Database Configuration

SSV Network

Ethereum Beacon Node (ETH2)

Ethereum Execution Node (ETH1)

P2P Network Configuration

Operator Keys

Converting Existing Keys

MEV Configuration (Optional)

Monitoring & Metrics

Local Development

Example Configurations

Share Configuration

Configuration Validation

Environment Variables

Security Best Practices

Source Files