MonatTGbot

MonatTGbot is a Telegram bot and backend service for monitoring Monad validators, delegators, and RPC endpoints.

It is designed to help operators and community users track:

• validator status and validator set membership;
• delegation and staking changes;
• claimable rewards and withdrawal requests;
• RPC availability, lag, and client version drift.

Features

• Telegram bot for creating and managing watches
• FastAPI backend for watch and alert rule APIs
• PostgreSQL persistence with Alembic migrations
• background worker for recurring checks and notifications
• RPC monitoring with lag detection against a reference RPC
• staking monitoring for validators and delegators
• configurable alert rules with cooldowns, thresholds, and quiet hours
• Docker Compose setup for local and VPS deployment

Supported watch types

• Validator by validatorId
• Delegator by 0x... address
• RPC endpoint by URL
• Validator link containing a validator id

Alert coverage

• RPC offline / recovered
• RPC lag started / resolved
• RPC version mismatch
• validator entered / left execution set
• validator entered / left consensus set
• validator entered / left snapshot set
• validator total stake increase / drop
• validator unclaimed rewards changed
• delegation created / increased / decreased / removed
• claimable rewards changed
• withdrawal detected / changed

Project structure

• docs/telegram-bot-spec.md - product specification
• docs/technical-architecture.md - technical architecture
• docs/project-status.md - current implementation and deployment status
• docs/deploy-ubuntu.md - Ubuntu/VPS deployment guide
• app/ - application code
• alembic/ - database migrations
• sql/ - SQL schema assets
• scripts/ - local helper scripts
• deploy/ - deployment templates and server-side helper scripts

Quick start

1. Install dependencies

pip install -e .[dev]

2. Create .env

For local development:

Copy-Item .env.local.example .env

Or use the helper:

.\scripts\bootstrap-env.ps1

For VPS / production:

cp prod.env.example .env

Minimum values to review:

• TELEGRAM_BOT_TOKEN
• DATABASE_URL
• REDIS_URL
• REFERENCE_RPC_URL

3. Run migrations

alembic upgrade head

4. Start the services

API:

uvicorn app.main:app --reload

Bot:

python -m app.bot.run

Worker:

python -m app.workers.run

Windows helper scripts

• scripts/bootstrap-env.ps1 - create .env from a template
• scripts/preflight.ps1 - run environment checks
• scripts/run-api.ps1 - start the API
• scripts/run-bot.ps1 - start the Telegram bot
• scripts/run-worker.ps1 - start the worker
• scripts/deploy-vps.ps1 - print VPS deployment commands

Recommended local order:

.\scripts\bootstrap-env.ps1
.\scripts\preflight.ps1
.\scripts\run-api.ps1
.\scripts\run-worker.ps1
.\scripts\run-bot.ps1

Docker

Local / generic Compose:

docker compose up --build

Production Compose:

docker compose -f docker-compose.prod.yml up -d --build

With bundled PostgreSQL and Redis:

docker compose -f docker-compose.prod.yml --profile with-db --profile with-redis up -d --build

Deployment assets

• docker-compose.prod.yml
• deploy/systemd/monat-api.service
• deploy/systemd/monat-bot.service
• deploy/systemd/monat-worker.service
• deploy/nginx/monat-api.conf
• docs/deploy-ubuntu.md

Server-side helper scripts:

• deploy/scripts/bootstrap-server.sh
• deploy/scripts/migrate.sh
• deploy/scripts/install-systemd.sh
• deploy/scripts/install-nginx.sh
• deploy/scripts/restart-services.sh
• deploy/scripts/smoke-test.sh

API highlights

Watches:

• GET /v1/watches
• POST /v1/watches
• GET /v1/watches/{entity_id}
• GET /v1/watches/{entity_id}/status
• POST /v1/watches/{entity_id}/refresh
• POST /v1/watches/{entity_id}/check-rpc

Resolver:

• POST /v1/watches/resolve

Alert rules:

• GET /v1/alert-rules/entity/{entity_id}
• PATCH /v1/alert-rules/{rule_id}

Health:

• GET /health

Telegram commands

• /start
• /help
• /add
• /list
• /status
• /check
• /alerts
• /alertset
• /alerton
• /alertoff

Environment notes

• DEFAULT_NETWORK controls the default network used by the bot when creating watches from Telegram.
• REFERENCE_RPC_URL is required for meaningful lag monitoring.
• TELEGRAM_BOT_TOKEN=replace-me can be used temporarily to disable Telegram delivery in local development.

Next improvements

• explicit per-user network selection in Telegram
• richer onboarding and localization
• more polished watch summaries and alert copy
• more efficient staking pagination and withdrawal scanning
• stronger production-grade delivery and suppression logic