A professionally-architected Go CLI tool for analyzing Ethereum network peer connection health and performance using Hermes as a gossipsub listener for beacon nodes. This tool monitors peer connections, analyzes network behavior, and generates comprehensive reports with optional AI-powered insights.

Recently completed a comprehensive refactoring that transformed the monolithic codebase into a well-organized, maintainable architecture with clear separation of concerns, improved testability, and enhanced performance.

• Dual Validation Modes: Support for delegated validation (via Prysm) and independent validation (internal processing)
• Real-time Monitoring: Live peer discovery and connection tracking with detailed session analysis
• Comprehensive Reporting: Generates both JSON and HTML reports with interactive visualizations
• AI-Powered Analysis: Optional OpenRouter integration for intelligent network behavior insights
• Historical Tracking: Automated report archival with 28-day retention and GitHub Pages deployment
• Client Detection: Automatic identification of Ethereum client types and versions
• Event Analytics: Detailed tracking of peer events, handshakes, and connection patterns

• Go 1.21 or later
• Access to an Ethereum beacon node (Prysm required for both validation modes)

git clone https://github.com/ethpandaops/hermes-peer-score.git
cd hermes-peer-score
go build -o peer-score-tool

# Delegated validation (default)
./peer-score-tool --validation-mode=delegated --prysm-host=<host> --duration=30m

# Independent validation
./peer-score-tool --validation-mode=independent --prysm-host=<host> --duration=30m

--validation-mode string     Validation mode: 'delegated' or 'independent' (default "delegated")
--prysm-host string          Prysm host connection string (required for both modes)
--prysm-http-port int        Prysm HTTP port (default 443)
--prysm-grpc-port int        Prysm gRPC port (default 443)
--duration duration          Test duration for peer scoring (default 2m)
--html-only                  Generate HTML report from existing JSON without running test
--input-json string          Input JSON file for HTML-only mode (default "peer-score-report.json")
--openrouter-api-key string  OpenRouter API key for AI analysis
--skip-ai                    Skip AI analysis even if API key is available
--update-go-mod              Update go.mod for specified validation mode and exit
--validate-go-mod            Validate go.mod configuration for specified validation mode and exit

export OPENROUTER_API_KEY="your-api-key"  # For AI-powered analysis

• Delegates validation requests to Prysm for processing
• Requires Prysm connection for both beacon state access and validation logic
• Lower resource usage on the tool itself
• Uses Hermes version: v0.0.4-0.20250513093811-320c1c3ee6e2

• Uses Prysm only for beacon state and validator data access
• Performs validation logic internally within the tool
• Higher resource usage but more control over validation process
• Uses Hermes version: v0.0.4-0.20250611164742-0abea7d82cb4

The tool requires different Hermes versions for each validation mode. Use the built-in commands to manage dependencies:

# Update go.mod for delegated mode
./peer-score-tool --validation-mode=delegated --update-go-mod

# Update go.mod for independent mode
./peer-score-tool --validation-mode=independent --update-go-mod

# Validate current configuration
./peer-score-tool --validation-mode=delegated --validate-go-mod

The tool generates timestamped files to prevent conflicts:

• peer-score-report-<mode>-<timestamp>.json - Raw data in JSON format
• peer-score-report-<mode>-<timestamp>.html - Interactive HTML report
• peer-score-report-<mode>-<timestamp>-data.js - JavaScript data for HTML report

Generate HTML reports from existing JSON data:

./peer-score-tool --html-only --input-json=peer-score-report-delegated-2024-01-15_14-30-00.json

The project includes automated CI workflows:

• ci-delegated.yml: Daily delegated validation tests at 11 AM UTC
• ci-independent.yml: Daily independent validation tests at 12 PM UTC
• clear-reports.yml: Manual workflow for clearing historical reports

Reports are automatically deployed to GitHub Pages with:

• Interactive historical report browser
• Validation mode filtering
• 28-day automatic retention
• Search and sorting capabilities

./peer-score-tool \
  --validation-mode=delegated \
  --prysm-host=localhost \
  --prysm-http-port=3500 \
  --prysm-grpc-port=4000 \
  --duration=5m

./peer-score-tool \
  --validation-mode=independent \
  --prysm-host=beacon.example.com \
  --duration=1h \
  --openrouter-api-key=$OPENROUTER_API_KEY

• Connection Statistics: Total connections, successful/failed handshakes, success rates
• Peer Discovery: Unique peers, client type distribution, geographic diversity
• Event Analytics: Peer events by type, connection session details, timing analysis
• Network Health: Connection stability, handshake patterns, client version spread

When OpenRouter API key is provided:

• Intelligent pattern recognition in peer behavior
• Anomaly detection in connection patterns
• Network health insights and recommendations
• Trend analysis across historical data

The tool follows a clean, layered architecture with well-defined package boundaries and clear separation of concerns. After a comprehensive refactoring, the codebase is organized into specialized packages that promote maintainability, testability, and extensibility.

• CLI Layer (cmd/): Application entry point and command orchestration
• Core Layer (internal/core/): Business logic for peer scoring and tool orchestration
• Events Layer (internal/events/): Modular event handling with individual handlers per event type
• Peer Layer (internal/peer/): Thread-safe peer state management with repository pattern
• Reports Layer (internal/reports/): Report generation with extracted template management
• Config Layer (internal/config/): Configuration management and validation
• Constants (constants/): Centralized constants eliminating magic numbers

• Repository Pattern: Thread-safe peer data management with proper encapsulation
• Handler Pattern: Modular event processing with individual handlers for each event type
• Template Management: Extracted HTML templates with proper template engine integration
• Interface-Based Design: 15+ interfaces enabling dependency injection and comprehensive testing
• Package Boundaries: Clear separation between CLI, business logic, and infrastructure concerns

• Hermes: Gossipsub listener and peer discovery (version varies by mode)
• Prysm: Beacon chain data access and validation services
• OpenRouter: Optional AI analysis integration
• Logrus: Structured logging throughout the application

├── cmd/
│   └── main.go                    # Clean CLI entry point
├── constants/
│   ├── config.go                  # Configuration constants
│   └── strings.go                 # String constants and client types
├── internal/
│   ├── cli/
│   │   └── handler.go             # CLI orchestration and command handling
│   ├── config/
│   │   ├── interfaces.go          # Configuration contracts
│   │   └── config.go              # Configuration management
│   ├── core/
│   │   ├── interfaces.go          # Core business logic contracts
│   │   ├── tool.go                # Main tool orchestration
│   │   └── hermes_controller.go   # Hermes lifecycle management
│   ├── events/
│   │   ├── interfaces.go          # Event handling contracts
│   │   ├── manager.go             # Event routing and management
│   │   ├── utils.go               # Event utilities
│   │   ├── handlers/              # Individual event handlers
│   │   │   ├── connection.go      # Connection event handling
│   │   │   ├── disconnection.go   # Disconnection event handling
│   │   │   ├── goodbye.go         # Goodbye message handling
│   │   │   ├── mesh.go            # Mesh event handling
│   │   │   ├── peer_score.go      # Peer score event handling
│   │   │   └── status.go          # Status event handling
│   │   └── parsers/               # Event payload parsing
│   │       ├── parser.go          # Parsing interfaces and logic
│   │       └── types.go           # Parser data structures
│   ├── peer/
│   │   ├── interfaces.go          # Peer management contracts
│   │   ├── repository.go          # Thread-safe peer data storage
│   │   ├── session_manager.go     # Session lifecycle management
│   │   ├── stats_calculator.go    # Peer statistics calculation
│   │   ├── goodbye_analysis.go    # Goodbye message analysis
│   │   └── types.go               # Peer data structures
│   └── reports/
│       ├── interfaces.go          # Report generation contracts
│       ├── generator.go           # Report orchestration
│       ├── file_manager.go        # File operations and management
│       ├── data_processor.go      # Data transformation pipeline
│       ├── ai_analyzer.go         # AI integration and analysis
│       └── templates/             # Template management
│           ├── manager.go         # Template engine management
│           ├── report.html        # Main HTML report template
│           └── styles.css         # Report styling
├── templates/
│   └── report.html                # External template files
├── old-monolithic-code/           # Preserved original implementation
└── scripts/                       # Python utilities for report management
    ├── generate_index.py          # Historical report index generation
    └── download_reports.py        # Report synchronization utilities

The project recently underwent a comprehensive refactoring that delivered significant improvements:

• Files Reduced: From 9 monolithic files to 35+ well-organized files
• Largest File: Reduced from 1,320 lines to <300 lines per file
• Package Structure: Transformed from single package to 8 specialized packages
• Constants: Extracted 47+ hardcoded values to named constants
• Interfaces: Created 15+ interfaces for better architecture and testability

• Separation of Concerns: Clean boundaries between CLI, business logic, and infrastructure
• Repository Pattern: Thread-safe peer data management with proper encapsulation
• Template Management: Extracted 600+ line HTML template to separate files
• Event Handling: Modular system with individual handlers per event type
• Error Handling: Consistent patterns with proper context and wrapping

• Thread Safety: Proper mutex usage eliminates data races
• Memory Efficiency: Reduced memory allocations through optimized data structures
• Build Quality: All code compiles cleanly with comprehensive linting compliance
• Test Coverage: >80% coverage for critical components with robust test suite

• Single Responsibility: Each package has one clear, focused purpose
• Interface-Based Design: Enables dependency injection and comprehensive testing
• Developer Experience: Clear structure facilitates onboarding and development
• Future Extensibility: Easy to add new features without affecting existing code

The CI workflows provide comprehensive testing across both validation modes with real network conditions. The refactored codebase includes extensive unit tests with proper mocking and integration tests that validate the complete pipeline.

1. Fork the repository
2. Create a feature branch
3. Ensure both validation modes work correctly
4. Test report generation with and without AI analysis
5. Submit a pull request

This project is part of the Ethereum ecosystem tooling maintained by EthPandaOps.