This application is for a retroactive micro-grant for completed development, documentation, and production operation of SSV VOC tools in support of the SSV Verified Operator Committee’s mission. The applications, documentation, and supporting tools were developed by Metanull, former member of the SSV Verified Operator Committee.
The Solutions
Tools
ssv-performance-bot
The ssv-performance-bot posts daily messages to a select Discord channel and responds to Discord user commands. This includes an ecosystem of tools for collecting data, exporting data to Google Sheets, importing/exporting database tables, and running most applications as Docker containers.
discordata
The discordata tool listens for KYC status messages provided by SumSub, queries the SumSub API for additional data, verifies digital signatures, and posts select status details to a Discord channel.
Containerization
Included with the scripts are configuration files required to run five major scripts as Docker containers or as Docker Compose applications.
Documentation
Documentation for all scripts is included in the GitHub repository and as comments within key sample configuration files. Instructions are provided for running all scripts as stand-alone applications and Docker containers.
Production Operations
discordata has been live in production in Metanull-provided environments since September 2024. The ssv-performance-bot started in production in Amazon environments provided by marc_blockshard and later transitioned to Metanull-provided environments.
Technical Overview
ssv-performance-bot
The ssv-performance-bot is an ecosystem of scripts for running the ssv-performance-bot and managing operator performance data. It consists of the following components:
ssv-performance-bot.py
Discord bot that posts daily messages to a selected Discord channel. Alerts users to operators that fail to meet configurable performance thresholds. Posts daily messages to individual DMs for users subscribed to individual operator performance updates, responds to additional commands in the Discord channel and by DM.
-
Daily performance alert message posted to Discord once per day at a configurable time
-
Listens for commands on a single Discord channel
-
Responds to all user commands by direct messages
-
Includes options to disable 30d performance and removed operator @mentionsmentions in daily performance alerts
-
Allows an extra configurable message to be included at the end of responses
-
Stores performance data in ClickHouse database
-
Configurable performance thresholds
-
Docker Compose configuration file included for easy configuration and operation
Commands
-
/help - Provides a description of all bot commands
-
/info - Displays the last date that performance data was collected
-
/alerts - Generates the daily performance alert message, showing all operators exceeding configured performance thresholds
-
/operator - Shows recent performance for one or more operators
-
/operators - Calculates basic validator count statistics and displays a graph showing validator count distribution. Includes parameters to select public/private and verified/unverified operators.
-
/fees - Outputs basic operator fee statistics and displays a graph showing fee distribution. Includes parameters to select public/private and verified/unverified operators.
-
/subscribe - Subscribes a user to direct messa@mentionses and @mentions for performance alerts for one or more operators.
-
/unsubscribe - Unsubscribes a user from direct messages and @mentions for performance alerts for one or more operators
-
/subscriptions - Shows all current subscriptions
ssv-performance-collector.py
Python script that collects performance data and stores it in a database for access by the Discord bot and other scripts
-
Optionally queries consensus client for accurate validator status. Falls back to SSV API counts
-
Docker Compose configuration file included for easy configuration and operation
ssv-performance-sheets.py
Python script that queries ClickHouse database for performance data and uploads a time series of data to Google Sheets
-
Configurable number of days of performance data to include
-
Docker Compose configuration file included for easy configuration and operation
ssv-validator-count-sheets.py
Python script that queries for validator count data and uploads a time series of data to Google Sheets
-
Configurable number of days of validator count data to include
-
Docker Compose configuration file included for easy configuration and operation
clickhouse-export.sh
Shell script that exports performance data from the database to SQL files for backups and migrations
clickhouse-import.sh
Python script that imports performance data into the database from SQL files for migrations and database restores
csv-to-sql-perf-import.py
Python script that imports performance data into the database from CSV files for restores from backup CSV files
healthcheck.sh
Shell script that performance database liveness check when launching ssv-performance-bot and the ClickHouse database using Docker Compose.
Screenshots
Discordata
discordata
A Discord bot that listens for KYC activity from a third-party API, queries the API for additional data, and summarizes the data in a post to Discord.
-
Verifies operator digital signatures against a configurable message
-
Docker Compose configuration file included for easy configuration and operation
Source Code
The tools described here are available on GitHub, presently under a GPL v3 license:
- https://github.com/metanull-operator/ssv-performance
- https://github.com/metanull-operator/Discordata
Funding Request
This micro-grant request is for $4,000.00 USDC or an equivalent amount in SSV tokens.