Configuration

This guide covers all configuration options for the Somnia Validator Monitor Bot.

Environment Variables

Required Variables

These variables MUST be set for the bot to function:

`BOT_TOKEN`

Description: Telegram bot token from BotFather
Format: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Example: BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

`TELEGRAM_ADMIN_IDS`

Description: Comma-separated list of Telegram user IDs with admin access
Format: Numeric IDs separated by commas
Example: TELEGRAM_ADMIN_IDS=123456789,987654321

`SOMNIA_RPC_URL`

Description: Somnia Network RPC endpoint URL
Format: Full HTTPS URL
Example: SOMNIA_RPC_URL=https://dream.somnia.network

`NODE_COMMITTEE_CONTRACT_ADDRESS`

Description: Address of the Node Committee smart contract
Format: Ethereum address (0x...)
Example: NODE_COMMITTEE_CONTRACT_ADDRESS=0x7b8b1bb68c6f0e29f3addcb45a6c0bb8e8e331c7

`SOMNIA_STAKING_CONTRACT_ADDRESS`

Description: Address of the Staking smart contract
Format: Ethereum address (0x...)
Example: SOMNIA_STAKING_CONTRACT_ADDRESS=0x44c185a0604b1227092305542a176840742f5342

Optional Variables

These variables have defaults but can be customized:

Monitoring Settings

# How often to check validator states (seconds)
MONITORING_INTERVAL_SEC=300  # Default: 5 minutes

# How often to check committee status (seconds)
COMMITTEE_MONITORING_INTERVAL_SEC=60  # Default: 1 minute

# Number of validators to check per batch
MONITORING_BATCH_SIZE=50  # Default: 50

Database Settings

# Path to SQLite database file
DATABASE_PATH=./somnia_validator_bot.db  # Default

# Database timeout (milliseconds)
DATABASE_TIMEOUT=5000  # Default: 5 seconds

Redis Settings (Optional Queue System)

# Enable Redis for queue management
REDIS_ENABLED=false  # Default: false

# Redis connection settings
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password  # Optional
REDIS_DB=0  # Default: 0

Display Settings

# What information to show in validator details
DISPLAY_NODE_ADDRESS=true
DISPLAY_STAKE_AMOUNT=true
DISPLAY_REWARDS=true
DISPLAY_COMMITTEE_STATUS=true
DISPLAY_EVENTS=true

Performance Settings

# Cache time-to-live in seconds
CACHE_TTL=300  # Default: 5 minutes

# Maximum retry attempts for failed operations
MAX_RETRIES=3  # Default: 3

# Initial retry delay in milliseconds
RETRY_DELAY=1000  # Default: 1 second

# Maximum retry delay in milliseconds
MAX_RETRY_DELAY=30000  # Default: 30 seconds

Logging Settings

# Log level: debug, info, warn, error
LOG_LEVEL=info  # Default: info

# Log file retention
LOG_MAX_FILES=30d  # Keep logs for 30 days

# Log file size before rotation
LOG_MAX_SIZE=20m  # 20 megabytes

Network Settings

# Chain ID for Somnia Network
CHAIN_ID=50311  # Default for testnet

# Chain name
CHAIN_NAME=somniaTestnet  # Default

# Request timeout for RPC calls (milliseconds)
RPC_TIMEOUT=30000  # Default: 30 seconds

Bot Settings

# Path to allowed users JSON file (optional)
ALLOWED_USERS_PATH=./allowed_users.json

# Enable/disable features
ENABLE_EVENTS_COMMAND=true
ENABLE_ADMIN_PANEL=true
ENABLE_USER_STATS=true

# Rate limiting
RATE_LIMIT_MESSAGES=30  # Max messages per minute
RATE_LIMIT_WINDOW=60000  # Window in milliseconds

Configuration File (.env)

Create a .env file in the project root:

# Required Configuration
BOT_TOKEN=your_bot_token_here
TELEGRAM_ADMIN_IDS=123456789,987654321
SOMNIA_RPC_URL=https://dream.somnia.network
NODE_COMMITTEE_CONTRACT_ADDRESS=0x7b8b1bb68c6f0e29f3addcb45a6c0bb8e8e331c7
SOMNIA_STAKING_CONTRACT_ADDRESS=0x44c185a0604b1227092305542a176840742f5342

# Optional - Monitoring
MONITORING_INTERVAL_SEC=300
COMMITTEE_MONITORING_INTERVAL_SEC=60

# Optional - Database
DATABASE_PATH=./data/somnia_validator_bot.db

# Optional - Logging
LOG_LEVEL=info
LOG_MAX_FILES=30d

# Optional - Performance
CACHE_TTL=300
MAX_RETRIES=3

Allowed Users Configuration

If you want to restrict bot access, create allowed_users.json:

{
  "allowed_users": [
    123456789,
    987654321,
    555555555
  ],
  "description": "List of Telegram user IDs allowed to use the bot"
}

Configuration Validation

The bot validates configuration on startup:

Required variables: Bot won't start without them
Type validation: Numbers are parsed correctly
Format validation: Addresses are checked for validity
Range validation: Intervals must be positive

Common Validation Errors

Error: BOT_TOKEN is required
→ Set the BOT_TOKEN environment variable

Error: Invalid Ethereum address for NODE_COMMITTEE_CONTRACT_ADDRESS
→ Ensure address starts with 0x and is 42 characters

Error: MONITORING_INTERVAL_SEC must be a positive number
→ Set a value greater than 0

Configuration Best Practices

Security

Never commit .env files to version control
Use strong, unique bot tokens
Limit admin IDs to trusted users only
Use environment-specific configurations

Performance

Monitoring intervals: Balance between real-time updates and resource usage
Batch sizes: Larger batches are more efficient but use more memory
Cache TTL: Longer cache reduces RPC calls but may show stale data

Maintenance

Backup configuration before changes
Test changes in development first
Document any non-standard settings
Monitor after configuration changes

Environment-Specific Configurations

Development

LOG_LEVEL=debug
MONITORING_INTERVAL_SEC=60  # Faster for testing
CACHE_TTL=30  # Shorter cache for development

Production

LOG_LEVEL=info
MONITORING_INTERVAL_SEC=300
CACHE_TTL=300
REDIS_ENABLED=true  # Enable queue for scale

Testing

LOG_LEVEL=error
DATABASE_PATH=:memory:  # In-memory database
MONITORING_INTERVAL_SEC=5  # Very fast for tests

Updating Configuration

Runtime Updates

Some configurations can be updated without restart:

Log level (via admin panel)
Monitoring intervals (via admin commands)
Cache settings

Restart Required

These changes require bot restart:

Bot token
Admin IDs
RPC URL
Contract addresses
Database path

Update Process

Update .env file
Stop bot gracefully
Verify configuration
Start bot
Check logs for errors
Verify functionality

Admin Overview Monitoring & Maintenance