CSM Sentinel

CSM Sentinel is a Telegram bot that sends you notifications for your CSM Node Operator events.

This bot was developed and is maintained by @skhomuti, a member of the Lido Protocol community, to simplify the process of subscribing to the important events for CSM. You can either run the bot yourself or use the community-supported public instance, depending on your privacy preferences.

Public Instances

These bots are owned by @skhomuti: Ethereum and Hoodi. The Holesky instance is no longer supported.

Please note that no guarantee is given for the availability of the bot. Also consider privacy concerns when using a public instance.

Running your own instance

First, you need to create a bot on Telegram. You can do this by talking to the BotFather.

Then, you need to create a .env by copying one of the .env.sample.ethereum or .env.sample.hoodi files and filling in the required fields:

• TOKEN: The token you received from the BotFather
• WEB3_SOCKET_PROVIDER: The websocket provider for your node. Preferably, use your own local node e.g. you already have for CSM validators. But it is also possible to use a public node of any web3 providers.

All other fields are pre-filled with the contracts from the corresponding network.

Run the CSM Sentinel using Docker compose:

docker compose up -d

Or using Docker:

docker build -t csm-sentinel .
docker volume create csm-sentinel-persistent

docker run -d --env-file=.env --name csm-sentinel -v csm-sentinel-persistent:/app/.storage csm-sentinel

Container images

Public container images are published to GitHub Container Registry for this repository:

docker pull ghcr.io/skhomuti/csm-sentinel:latest

Image tags follow the Git ref that triggered the workflow:

• Pull requests build the image for validation but do not publish it
• Each merge to main refreshes a draft prerelease suggestion in GitHub Releases
• Publishing a prerelease with tag vX.Y.ZrcN publishes ghcr.io/skhomuti/csm-sentinel:X.Y.ZrcN
• Publishing a stable release with tag vX.Y.Z publishes ghcr.io/skhomuti/csm-sentinel:X.Y.Z, X.Y, X, and latest

Suggested prerelease bumps are driven by pull request labels:

• release:major for breaking changes
• release:minor for backward-compatible features
• release:patch for fixes and other release-worthy changes

If no release:* label is applied, the next draft prerelease treats the change as a patch.

Local development

Install dependencies and run the bot with uv:

uv sync
uv run python -m sentinel.main

Running alongside eth-docker

If you are running the bot on the same machine as the eth-docker, you can use the execution client with no need to expose it outside the container.

You need to use a special docker-compose file that connects the Sentinel instance to the eth-docker network.

docker compose -f docker-compose-ethd.yml up -d

WEB3_SOCKET_PROVIDER env variable is set to ws://execution:8546 via docker-compose file, so you don't need to specify it in the .env file.

Extra configuration

Pass the BLOCK_FROM environment variable to specify the block the bot should start monitoring events from. Note that this may result in duplicate events if you set it to a block that the bot has already processed before. BLOCK_FROM=0 allows you to skip processing past blocks and always start from the head. In general, you don't need to set this variable.

BLOCK_BATCH_SIZE controls how many blocks are fetched per RPC request when processing historical events. The default value is 10000.

PROCESS_BLOCKS_REQUESTS_PER_SECOND caps how many historical RPC requests process_blocks_from issues per second when backfilling. Leave unset to disable throttling.

Admin access (ADMIN_IDS)

Some maintenance commands are restricted to admins. To enable them, set your Telegram user ID in the ADMIN_IDS environment variable.

How to find your Telegram user ID:

• Open a chat with @userinfobot, send /start, and copy the numeric Id value.

Configure the ID in your .env:

# Single admin
ADMIN_IDS=123456789

# Multiple admins (comma or space separated)
ADMIN_IDS=123456789,987654321
# or
ADMIN_IDS=123456789 987654321

Admin broadcasts

Admins can broadcast messages via the in-bot Admin panel:

• Open Admin → Broadcast.
• Choose All subscribers to send a message to every chat subscribed to any node operator, then enter your message.
• Or choose By node operator and enter comma-separated node operator IDs (e.g., 1,2,3), then enter your message.

Integration test suite

End-to-end verification for on-chain events lives under tests/integration. Each scenario replays a real transaction through a lightweight harness that exposes the same process_blocks_from and subscribe entrypoints as the real subscription, allowing EventMessages to render the expected Markdown for every event.

To enable the suite:

1. Install a local fork provider:
   • anvil
2. Ensure .env contains a WEB3_SOCKET_PROVIDER that can serve archive data; the tests reuse this value as the fork source (WebSocket URLs are translated to their HTTP equivalents automatically)

Each test spawns a dedicated local fork pinned to the case's block to keep state deterministic. Run the suite with:

uv run pytest -m integration