README.md

Slashing Guard is a monitoring service for LIDO node operators that will alarm your team instantly via Telegram if a validator is getting slashed.

Table of Contents

• Requirements and Prerequisites

• Usage
  • Configuration
    • Options
    • Config file
    • Environment variables
  • Getting Started
    • Run with Docker
      • Images
      • Quick start with Docker
    • Run from source
      • Quick start from source
      • Build your Docker image locally
  • Telegram Bot
    • User Subscription
    • Group Subscription
    • Bot Commands

• Contributing
  • Recommended Software
  • Pull Requests
  • Unit Testing and Linting
  • Style Guide

• Contact

Requirements and Prerequisites

Before you start with the Slashing Guard applicaton you need:

1. API access to a fully synced Ethereum Beacon node (Consensus Client)
2. API access to a running LIDO KAPI service
3. Install Docker or optional NodeJS and npm (depending on your needs)
4. Install Telegram Messenger and create your alarming bot

While the Docker installation (#3) is a straight forward task, Stereum would be the recommended solution to setup and configure a fresh Beacon node (#1) along with the LIDO KAPI service (#2).

Afterwards you can create a new Telegram bot (#4) as follows:

1. Open your Telegram Messenger
2. Search for BotFather and create your new bot

Make sure you choose the valid one (see the blue verified sign on the screenshot)

3. Store your new bot token on a safe location (you will need that later on)

As soon as the prerequisites are done, the Slashing Guard setup can start.

Usage

There are multiple ways you can configure and run the Slashing Guard application. While the recommended setup for production environments is Docker, it is also possible to run the app directly from source with NodeJS, which is mostly preferred for develpment on your local system, however also an absolutely valid setup for production.

Configuration

The Slashing Guard options must be configured either thru a .env config file or environment variables.

Options

Name	Default	Required	Description
TELEGRAM_BOT_TOKEN	YourBotToken	Yes	The token received by Telegrams BotFather on bot creation
ETH_URL	http://localhost:5051	Yes	The URL to your Beacon node API (Consensus Client)
KAPI_URL	http://localhost:3600	Yes	The URL to your LIDO Keys API (KAPI)
OPERATOR_NAME	YourLidoOperatorName	Yes	Official LIDO node operator name (availabe thru KAPI service)
LOG_LEVEL	info	No	Log Level: "fatal", "error", "warn", "info", "debug" or "trace"
FAKE_KEYS	<string:empty>	No	For development and debugging (see description in .env.example)

Config file

By default the Slashing Guard attempts to read the configuration from an .env file where you add the config options.

Example .env.example (see .env.example):

# Bot token that was received from Telegram "BotFather"
TELEGRAM_BOT_TOKEN=YourBotToken

# API url of a fully synced consensus node
ETH_URL="http://localhost:5051"

# API url of your LIDO KAPI service
KAPI_URL="http://localhost:3600"

# Your LIDO operator name
OPERATOR_NAME=YourLidoOperatorName

Environment variables

You can also configure the Slashing Guard options by environment variables. They will overwrite all identical options that are already defined in the config file.

Environment variables must be always UPPERCASE. For example, to specify OPERATOR_NAME as environment variable:

export OPERATOR_NAME="MyLidoOperatorName"
npm i
npm run start:dev

Getting started

The recommended setup for production environments is to run the Slashing Guard with Docker but it is also possible to run the Slashing Guard directly from source with NodeJs. Make sure you've read the configuration section and then you're good to go.

Run with Docker

1. Verify that all requirements and prerequisites are met.
2. Pull the Slashing Guard Docker Image (stereum/slashing-guard) from Docker Hub and follow the quick start with Docker or build your Docker image locally.

Images

• latest - latest release of the Slashing Guard on node:19-alpine
• $version - specific release (e.g.: v0.0.1) of the Slashing Guard on node:19-alpine

Quick start with Docker

1. Create a directory (e.g: slashing-guard) where you want your Slashing Guard app running

mkdir slashing-guard
cd slashing-guard

2. Copy .env.example to .env and configure as needed

wget -O .env https://raw.githubusercontent.com/stereum-dev/slashing-guard/main/.env.example

3. Copy docker-compose.yaml.example to docker-compose.yaml

wget -O docker-compose.yaml https://raw.githubusercontent.com/stereum-dev/slashing-guard/main/docker-compose.yaml.example

4. Start the Slashing Guard Docker container (detached):

sudo docker compose --project-name slashing-guard up -d

Important

Note that the Slashing Guard application is creating a folder called "database" inside your application root. This is a level-db storage used to register and ping your bot subscribers. It is highly recommended to regulary backup this database folder to retain your bot subscribers in case of an disaster.

Deleting the database folder will require all bot subscribers to renew their subscription!

To monitor logs of your Docker container use docker logs -f slashing-guard

To stop your Docker container use docker compose --project-name slashing-guard down

5. Open Telegram and configure your bot

See the Telegram Bot section to do so.

Run from source

1. Download a release from the releases page (or clone the GitHub repository).
2. Refer to the official NodeJS docs to install NodeJS >= 16 on your OS.
3. Refer to the official npm docs to install npm on your OS.
4. Extract the release (or continue directly with step #5 if you just cloned the GitHub repository).
5. Follow the quick start from source examples.

Quick start from source

1. Move to the directory (e.g: slashing-guard) where you have unpacked or cloned the Slashing Guard app

cd slashing-guard

2. Copy .env.example to .env and configure as needed
3. Start the Slashing Guard app from source:

npm i
npm run start:dev

Build your Docker image locally

You can also build your Docker image locally from source as follows:

1. Move to the directory (e.g: slashing-guard) where you have unpacked or cloned the Slashing Guard app

cd slashing-guard

2. Copy .env.example to .env and configure as needed
3. Copy docker-compose.yaml.example to docker-compose.yaml
4. Build your docker image:

docker compose --project-name slashing-guard build

5. Start the Slashing Guard app from your local Docker build:

docker compose --project-name slashing-guard up

You can stop the Docker container by typing CTRL+C in your active terminal.

Telegram Bot

As soon as Slashing Guard is up and running your bot is available in Telegram.

Users and groups can get alarmed instantly from the bot if one of your validators got slashed - both require a subscrbtion.

User Subscription

Each user can subscribe to your bot by searching for the bot name (you got from BotFather) in the Telegram user list or by requesting http://t.me/BOTNAME and running the bot command /start@BOTNAME.

Telegram is usually providing a "Start" button to run /start@BOTNAME automatically as soon as the chat window of the bot is joined by the user.

From now the bot is subscribed and alert notifications will be sent to the user.

To unsubscribe, the user need to run /stop@BOTNAME inside the bot chat.

Replace BOTNAME with the name you received for your bot by BotFather

Group Subscription

It is also possible to receive alert notifications for a whole group. To do so, add the bot to a group and subscribe the group.

First you need to search for the bot name (you got from BotFather) in the Telegram user list or by requesting http://t.me/BOTNAME and assign the bot to your group.

Second, run /start@BOTNAME inside your group chat.

From now the bot is subscribed and alert notifications will be sent to the group.

To unsubscribe the group, run /stop@BOTNAME inside your group chat.

Replace BOTNAME with the name you received for your bot by BotFather

Bot Commands

In addition to the alert notification that are retrieved after a user or group is subscribed, the bot also supports a few other commands. Bot commands always start with a slash (/) and Telegram also provides a UI for that.

• In the bot chat a menu icon lists bot commands

  

• In the group chat a slash icon lists bot commands

  

Currently the Slashing Guard bot supports the folloowing commands:

Name	Description
start	Subscribe a user or group to the bot
status	Get current service status
operator	Get operator details
stop	Unsubscribe a user or group from the bot

All commands must be pre-fixed with a slash and su-fixed with "@" and the bot name (e.g: /start@botname)

For further information please visit the Telegram bot features page.

Contributing

Contributions are greatly appreciated and pull requests will be reviewed/merged ASAP!

Recommended Software

The easiest way to follow our Style Guide and contributor workflow is to use Visual Studio Code (VSCode) as IDE with at least the following extensions added:

• Prettier
• ESLint
• GitLens

This document will explain all further steps assuming you are using VSCode and the mentioned extensions.

If you are using Windows, we strongly recommend you to use Git Bash as terminal inside VSCode!

Pull Requests

To improve the Slashing Guard code please follow this steps:

1. Fork the project
2. Create your feature branch:
   • git checkout -b feat/new-feature
3. Commit your changes:
   • git commit -m "feat(optional): new feature"
4. Push the branch: -git push origin feat/new-feature
5. Open a pull request

Note: To test your changes in a local Docker container see the Build your Docker image locally Example.

Unit Testing and Linting

All pull requests running thru automated tests. It is recommended to run this tests locally before you open a pull request.

• Setup your local development environment, thus you're able to run from source
• Execute npm i to install packages (before you run the commands below!)
• Execute npm test .test to run Unit Tests (where no errors as result means passed)
• Execute npm run lint:fix to run Lint Tests with code formatting (where no errors as result means passed)

Style Guide

If you use the recommended software and extensions usually everything is already auto formated and/or code issues are announced in the "Problems" tab of VSCode.

However, here are a few hints you may follow to keep your code clean and pass automated tests:

• Make sure your code is properly linted:
  • Use an IDE that will show linting errors/warnings
  • Execute npm run lint:fix from the command line
  • Common rules:
    • Functions and variables should be camelCase
    • Classes should be PascalCase
    • Constants should be UPPERCASE_WITH_UNDERSCORES
    • Use " instead of '

You only have to take care about linting issues of files you have changed

• Make sure that jest tests are passing:
  • run npm run test .test from the command line

Pull requests must pass all automated Jest tests to get accepted

• Comments:
  • If your code does something that is not obvious or deviates from standards, please leave a comment for other developers to explain your logic and reasoning
  • Use // commenting format as default
  • Optional use /* */ commenting format for documenting a function, class or variable
  • Keep comments short and simple

Contact

To get in touch just join the Stereum Discord server and leave a message in one of the public channels - we are happy to get your feedback!