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