SSV Client Diversity

A comprehensive tool for monitoring and visualizing client diversity in the SSV (Secret Shared Validators) network. This project helps ensure network health by tracking the distribution of different SSV client implementations.

Overview

This project consists of two main components:

1. SSV Identifier (Rust): Network crawler that discovers SSV peers, identifies client types (Anchor, GoSSV, Unknown), and stores data in SQLite
2. Dashboard (Node.js): Web-based visualization dashboard for real-time client diversity metrics

┌─────────────────────────────────────────────────────────────────┐
│                     SSV Network                                  │
│  (Distributed validators using libp2p)                           │
└────────────────────────┬────────────────────────────────────────┘
                         │ discovers & handshakes
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              SSV Identifier (Rust Crawler)                       │
│  • Discovers peers via discv5                                    │
│  • Performs libp2p handshakes                                    │
│  • Identifies client types & versions                            │
│  • Tracks subnet membership                                      │
│  • Records network snapshots                                     │
└────────────────────────┬────────────────────────────────────────┘
                         │ writes to
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              SQLite Database (clients.db)                        │
│  • peers table                                                   │
│  • subnet_membership table                                       │
│  • network_snapshots table                                       │
└────────────────────────┬────────────────────────────────────────┘
                         │ reads from (read-only)
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│           Dashboard (Node.js + Nginx)                            │
│  • REST API for metrics                                          │
│  • Real-time visualizations                                      │
│  • Auto-refresh every 30s                                        │
│  • Supermajority warnings                                        │
└────────────────────────┬────────────────────────────────────────┘
                         │ displays to
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Browser (Users)                                │
│  http://localhost (or your domain)                               │
└─────────────────────────────────────────────────────────────────┘

Features

SSV Identifier

• Peer Discovery: Uses discv5 to discover SSV network peers
• Client Identification: Detects Anchor and GoSSV clients via handshake analysis
• Version Tracking: Extracts semantic versions from client strings
• Subnet Monitoring: Tracks which subnets each peer participates in
• Historical Snapshots: Periodic network composition snapshots
• Persistent Storage: SQLite database for efficient querying

Dashboard

• Client Distribution: Horizontal bar chart showing Anchor vs GoSSV vs Unknown
• Version Analytics: Top 10 versions for each client type
• Historical Trends: 24-hour time-series of client diversity
• Subnet Participation: Peer distribution across top 20 subnets

Quick Start

1. Clone the Repository

git clone <repository-url>
cd ssv-client-diversity

2. Run the SSV Identifier (Rust Crawler)

The identifier discovers peers and populates the database.

# Navigate to identifier directory
cd ssv-identifier

# Build the project
cargo build --release

# Run the identifier
cargo run --release

The identifier will:

• Start discovering SSV network peers
• Perform handshakes to identify client types
• Store data in ~/.ssv-identifier/clients.db
• Take periodic network snapshots
• Log activity to console and files

Let it run for at least 10-15 minutes to collect initial data before starting the dashboard.

3. Run the Dashboard

Option A: Development Mode (without Docker)

# Open a new terminal
cd dashboard/app

# Install dependencies
npm install

# Start the development server
npm run dev

# Dashboard available at http://localhost:3000

Option B: Production Mode (with Docker)

# Navigate to dashboard directory
cd dashboard

# Build and start containers
docker-compose up -d

# Dashboard available at http://localhost

View logs:

docker-compose logs -f

Stop containers:

docker-compose down

4. Access the Dashboard

Open your browser and navigate to:

• Development: http://localhost:3000
• Docker: http://localhost

You should see real-time metrics and visualizations of the SSV network client diversity!

Detailed Setup

SSV Identifier Configuration

The identifier can be configured via command-line arguments or environment variables.

Command-Line Options

# View all available options
cargo run --release -- --help

# Run with custom database path
cargo run --release -- --db-path /custom/path/ssv-peers.db

# Run with verbose logging
RUST_LOG=debug cargo run --release

# Run with custom snapshot interval
cargo run --release -- --snapshot-interval 600  # 10 minutes

Dashboard Configuration

Environment Variables

Create a .env file in dashboard/app/:

NODE_ENV=production
PORT=3000
SSV_DB_PATH=~/.ssv-identifier/clients.db
CACHE_REFRESH_INTERVAL=60000

Docker Configuration

Edit dashboard/docker-compose.yml to customize:

dashboard:
  environment:
    - PORT=3000
    - SSV_DB_PATH=/app/data/clients.db
    - CACHE_REFRESH_INTERVAL=60000 # 60 seconds
  volumes:
    # Mount custom data directory if identifier uses --data-dir
    - /custom/path:/app/data:ro
  ports:
    - "8080:3000" # Change external port if needed

Development

Building the Identifier

cd ssv-identifier

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Check code
cargo check

# Format code
cargo fmt

# Lint code
cargo clippy

Developing the Dashboard

cd dashboard/app

# Install dependencies
npm install

# Development mode (auto-reload)
npm run dev

# Production mode
npm start

# Build Docker image
cd ..
docker build -t ssv-dashboard .

Project Structure

ssv-client-diversity/
├── ssv-identifier/              # Rust network crawler
│   ├── src/
│   │   ├── main.rs             # Entry point
│   │   ├── network.rs          # Network discovery
│   │   ├── database.rs         # SQLite operations
│   │   ├── handshake.rs        # Client identification
│   │   ├── metrics.rs          # Network metrics
│   │   └── ...
│   ├── Cargo.toml              # Rust dependencies
│   └── data/                   # Optional custom data directory
│       └── clients.db          # SQLite database (default: ~/.ssv-identifier/clients.db)
├── dashboard/                   # Node.js dashboard
│   ├── app/
│   │   ├── server.js           # Express API
│   │   ├── package.json        # Node dependencies
│   │   ├── public/             # Static assets
│   │   │   ├── css/style.css
│   │   │   └── js/dashboard.js
│   │   └── views/
│   │       └── index.html      # Main page
│   ├── nginx/
│   │   └── nginx.conf          # Reverse proxy
│   ├── Dockerfile              # Container image
│   ├── docker-compose.yml      # Orchestration
│   └── README.md               # Dashboard docs
└── README.md                    # This file

API Reference

See dashboard/README.md for complete API documentation.

Quick reference:

• GET /api/stats - Current network statistics
• GET /api/client-versions - Version distributions
• GET /api/historical-trends?hours=24 - Time-series data
• GET /api/subnet-stats - Subnet participation
• GET /health - Health check

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Built with ❤️ by Sigma Prime