Multi-Network Distributor Monitor

A Golang tool that monitors multiple blockchain networks simultaneously for RootSubmitted events and sends notifications to Slack.

Features

• 🌐 Multi-Network Support: Monitors 11+ blockchain networks simultaneously
• 🔍 Real-time Event Monitoring: Tracks RootSubmitted events from your smart contracts
• 📢 Rich Slack Notifications: Network-specific notifications with emojis and detailed information
• ⚙️ Flexible Configuration: YAML config or environment variables
• 🛡️ Robust: Handles network failures, reconnections, and graceful shutdowns
• 🚀 Production Ready: Concurrent monitoring with proper resource management

Supported Networks

The tool supports monitoring on the following blockchain networks:

Network	Chain ID	Emoji	Environment Variable
Ethereum	1	🔹	ETH_NODE_URL
Polygon	137	🟣	POLYGON_NODE_URL
BSC	56	🟡	BSC_NODE_URL
Arbitrum	42161	🔵	ARBITRUM_NODE_URL
Avalanche	43114	🔴	AVAX_NODE_URL
Base	8453	🔷	BASE_NODE_URL
Berachain	80094	🐻	BERA_NODE_URL
Mantle	5000	🟤	MANTLE_NODE_URL
Optimism	10	🔸	OPTIMISM_NODE_URL
Sonic	146	💫	SONIC_NODE_URL
Unichain	1301	🦄	UNICHAIN_NODE_URL

Event Structure

The tool monitors the following Solidity event across all networks:

event RootSubmitted(bytes32 indexed campaignId, bytes32 pendingRoot, uint256 effectiveTimestamp);

Prerequisites

• Go 1.21 or later
• Ethereum node access (Infura, Alchemy, or your own node)
• Slack Bot Token with appropriate permissions

Installation

1. Clone or create the project directory:

mkdir distributor-monitor
cd distributor-monitor

2. Initialize the Go module:

go mod init distributor-monitor

3. Install dependencies:

go mod tidy

Configuration

Option 1: Environment Variables (Recommended)

1. Copy the example environment file:

cp env.example .env

2. Update .env with your settings:

# Global contract address (if same across all networks)
CONTRACT_ADDRESS=0x1234567890123456789012345678901234567890

# Network-specific RPC URLs
ETH_NODE_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID
POLYGON_NODE_URL=https://polygon-mainnet.infura.io/v3/YOUR_PROJECT_ID
# ... (add only the networks you want to monitor)

# Slack configuration
SLACK_TOKEN=xoxb-your-slack-bot-token
SLACK_CHANNEL=#distributor-alerts

Option 2: YAML Configuration

1. Update config.yaml to specify networks directly:

networks:
  - name: "ethereum"
    chain_id: 1
    rpc_url: "https://mainnet.infura.io/v3/YOUR_PROJECT_ID"
    contract_address: "0x1234567890123456789012345678901234567890"
    start_block: 0
  - name: "polygon"
    chain_id: 137
    rpc_url: "https://polygon-mainnet.infura.io/v3/YOUR_PROJECT_ID"
    contract_address: "0x1234567890123456789012345678901234567890"
    start_block: 0

Configuration Options

• Network-specific contract addresses: Set {NETWORK}_CONTRACT_ADDRESS if contracts differ per network
• Global contract address: Set CONTRACT_ADDRESS if all networks use the same contract
• Selective monitoring: Only configure RPC URLs for networks you want to monitor
• Custom start blocks: Set different starting blocks per network if needed

Setting Up Slack Bot

1. Go to Slack API Apps
2. Create a new app
3. Add the following OAuth scopes:
   • chat:write
   • chat:write.public
4. Install the app to your workspace
5. Copy the Bot User OAuth Token (starts with xoxb-)
6. Invite the bot to your desired channel

Running the Monitor

1. Development:

go run main.go

2. Production Build:

go build -o distributor-monitor main.go
./distributor-monitor

3. With Custom Config:

./distributor-monitor -config custom-config.yaml

Example Slack Notification

When a RootSubmitted event is detected, you'll receive a network-specific Slack message like:

🔹 RootSubmitted Event Detected - ethereum

Network: 🔹 ethereum (Chain ID: 1)
Contract Address: 0x1234...567890
Campaign ID: 0x1234...abcd
Pending Root: 0x5678...efgh
Effective Timestamp: 2024-01-15 14:30:25 UTC
Block Number: 18956789
Transaction Hash: 0x9abc...def0
Block Timestamp: 2024-01-15 14:30:23 UTC

Each network has its own emoji for easy identification in your Slack channel!

Deployment Options

Docker

Create a Dockerfile:

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o distributor-monitor main.go

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/distributor-monitor .
COPY --from=builder /app/config.yaml .
CMD ["./distributor-monitor"]

Build and run:

docker build -t distributor-monitor .
docker run -d --name distributor-monitor distributor-monitor

Systemd Service

Create /etc/systemd/system/distributor-monitor.service:

[Unit]
Description=Distributor Monitor
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/distributor-monitor
ExecStart=/path/to/distributor-monitor/distributor-monitor
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable distributor-monitor
sudo systemctl start distributor-monitor

Monitoring and Logs

The application provides structured logging with configurable levels:

• debug: Detailed information for debugging
• info: General information about operations
• warn: Warning messages for potential issues
• error: Error messages for failures

View logs in real-time:

./distributor-monitor 2>&1 | tee monitor.log

Troubleshooting

Common Issues

1. Connection Failed:

   • Verify your RPC URLs are correct for each network
   • Check if your node providers are accessible
   • Ensure you have sufficient API rate limits
   • The tool will skip networks with invalid configurations

2. No Networks Monitored:

   • Check that at least one {NETWORK}_NODE_URL environment variable is set
   • Verify contract addresses are configured
   • Check logs for "Skipping network" messages

3. Slack Messages Not Sending:

   • Verify your bot token is correct
   • Check if the bot is invited to the channel
   • Ensure the bot has chat:write permissions

4. Events Not Detected:

   • Verify contract addresses are correct for each network
   • Check if contracts have emitted any events
   • Monitor logs for network-specific error messages
   • Use different starting blocks if needed

5. High Resource Usage:

   • Increase poll_interval to reduce API calls
   • Decrease batch_size for slower networks
   • Monitor only essential networks

Performance Tuning

• Adjust poll_interval based on your needs (lower = more responsive, higher = less load)
• Set appropriate batch_size to handle high-volume contracts
• Use WebSocket connection for real-time monitoring (if supported by your provider)

Project Structure

distributor-monitor/
├── main.go                    # Main application entry point
├── internal/
│   └── config/               # Configuration management
│       ├── config.go         # Main config struct and loading
│       ├── networks.go       # Network definitions and utilities
│       └── README.md         # Config package documentation
├── config.yaml              # Configuration template
├── env.example              # Environment variables template
├── Dockerfile               # Container configuration
├── Makefile                 # Build and deployment commands
└── README.md                # This file

Development

Running Tests

go test ./...

Adding New Networks

To add support for a new blockchain network:

1. Edit internal/config/networks.go:

   • Add network to LoadNetworksFromEnv function
   • Add emoji in GetNetworkEmoji function
   • Add to SupportedNetworks function

2. Update environment variable template in env.example

3. Update documentation in relevant README files

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

1. Check the troubleshooting section
2. Review the logs for error messages
3. Create an issue in the repository