docs
Introduction

GSwarm - Gensyn Telegram Monitoring Service

⚠️ Important Notice: This is a third-party application

GSwarm is NOT affiliated with or endorsed by the official Gensyn team. This is an independent, community-developed Telegram monitoring service designed to enhance the user experience of monitoring Gensyn AI node activity.

A dedicated Go-based Telegram monitoring service for Gensyn AI that provides real-time notifications about blockchain activity, including votes and rewards.

✨ Features

  • 🔔 Hourly Notifications: Get updates on blockchain activity every hour

  • 📊 Vote Tracking: Monitor your voting activity and changes

  • 💰 Reward Monitoring: Track reward accumulation and changes

  • 📈 On-Demand Stats: Use /stats command in Telegram to check your current stats anytime

  • 📈 Change Detection: Only notified when values actually change

  • 🛡️ Secure Configuration: Local config file storage

  • 🔍 Peer ID Monitoring: Track all peer IDs associated with your EOA address

  • ⏰ Continuous Monitoring: Checks every 30 minutes for changes (notifications are only sent if there are updates on your peers)

🚀 Quick Start

Prerequisites

  • Go 1.24+ (for building the service) - Installation Guide
  • Telegram Bot Token (from @BotFather)
  • Telegram Chat ID (your chat ID or group chat ID)

Installing Go 1.24+

For Linux:

cd ~
wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz
 
# Set environment variables
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
echo 'export PATH=$PATH:$GOPATH/bin' >> ~/.bashrc
source ~/.bashrc
 
# Verify Go installation
go version

For macOS:

# Using Homebrew (recommended)
brew install go
 
# Or download manually
# Visit https://go.dev/dl/ and download the macOS installer

For Windows:

# Download from https://go.dev/dl/ and run the installer
# Or use Chocolatey: choco install golang

Installation

Option 1: Install with Go (Recommended)

go install github.com/Deep-Commit/gswarm/cmd/gswarm@latest

This will place the gswarm binary in your $GOPATH/bin or $HOME/go/bin (make sure this is in your PATH).

Verify installation:

gswarm --version

Option 2: Clone and Build from Source

# Clone repo to safe location
cd ~
git clone https://github.com/Deep-Commit/gswarm.git
cd gswarm
make build
sudo make install

After this, you can run gswarm from anywhere (if your Go bin directory is in your PATH).

Verify installation:

gswarm --version

Basic Usage

  1. Run the monitoring service: 
    gswarm

The service will:

  • Prompt for Telegram configuration if not already set up
  • Ask for your EOA address
  • Fetch associated peer IDs
  • Start monitoring blockchain activity every 30 minutes
  • Notifications are only sent if there are updates on your peers (no notification if nothing has changed)

🤖 Telegram Bot Setup (Step-by-Step)

To receive notifications via Telegram, you need to set up a Telegram bot and connect it to your account:

  1. Create a Telegram Bot:

  2. Get Your Chat ID:

    • Start a chat with your new bot and send any message
    • Visit https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates in your browser
    • Find your chat ID in the response
    • For groups/channels: Use the ChatID/ChannelID as the telegramId in the bot configuration

    Example: If your bot token is 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz, visit:

    https://api.telegram.org/bot1234567890:ABCdefGHIjklMNOpqrsTUVwxyz/getUpdates

    Sample Response:

    {
  "ok": true,
  "result": [
    {
      "message": {
        "message_id": 2021,
        "from": {
          "id": 123456789,
          "is_bot": false,
          "first_name": "GSwarm",
          "username": "gswarm_user",
          "language_code": "en"
        },
        "chat": {
          "id": 123456789,
          "first_name": "GSwarm",
          "username": "gswarm_user",
          "type": "private"
        },
        "date": 1704067200,
        "text": "Hello bot!"
      }
    }
  ]
}

    Extract the Chat ID: Look for the "chat":{"id":123456789} field. In this example, the chat ID is 123456789. This is your Telegram ID that the bot will use to send you notifications.

    Note: If you get an empty result {"ok":true,"result":[]}, you may need to send a message to your bot first, then refresh the URL.

  3. Configure GSwarm:

    • Run gswarm and follow the prompts to enter your bot token, chat ID, and EOA address

For a full, detailed guide (with troubleshooting and advanced options), see the Telegram Setup Guide.

🔗 Linking Discord and Telegram

To link your Discord and Telegram accounts:

  1. Get the verification code:

    • Go to Discord (swarm-link channel)
    • Type /link-telegram (this gives you a code)

  2. Verify the code:

    • Go to Telegram
    • Type /verify <code> (replace <code> with the code you received)

This will link your Discord and Telegram accounts for seamless integration.

📖 Usage

Interactive Setup (Default)

When run for the first time, the service will guide you through setup:

gswarm

You'll be prompted for:

  1. Telegram Bot Token: Get this from @BotFather on Telegram
  2. Telegram Chat ID: Your personal chat ID or group chat ID
  3. EOA Address: Your Ethereum address from the Gensyn dashboard

Command Line Options

FlagDescriptionDefaultEnvironment Variable
--telegram-config-pathPath to telegram-config.json filetelegram-config.jsonGSWARM_TELEGRAM_CONFIG_PATH
--update-telegram-configForce update of Telegram config via CLI promptsfalseGSWARM_UPDATE_TELEGRAM_CONFIG

Environment Variables

All flags can be set via environment variables with the GSWARM_ prefix:

export GSWARM_TELEGRAM_CONFIG_PATH=/path/to/config.json
export GSWARM_UPDATE_TELEGRAM_CONFIG=true
gswarm

Examples

# Start monitoring service (interactive setup)
gswarm
 
# Use custom config path
gswarm --telegram-config-path /path/to/config.json
 
# Force update Telegram config
gswarm --update-telegram-config
 
# Show version
gswarm version

📱 Telegram Monitoring

GSwarm includes a powerful Telegram monitoring service that provides real-time notifications about your blockchain activity, including votes and rewards.

Setup Instructions

The Telegram service monitors and notifies you about:

  • Vote Changes: When your vote count increases or decreases
  • Reward Changes: When your accumulated rewards change
  • On-Demand Stats: Send /stats to get your current stats anytime
  • Peer ID Activity: Monitoring of all peer IDs associated with your EOA address
  • Welcome Message: Initial setup confirmation

Sample Notifications

🚀 G-Swarm Update

📊 Blockchain Data Update

👤 EOA Address: 0x1234567890abcdef...
🔍 Peer IDs Monitored: 4

📈 Total Votes: 1,456 📈
💰 Total Rewards: 0.75 ETH 📈

📋 Per-Peer Breakdown:
🔹 Peer 1: QmZkyXja166VBTMU76xLR17XKAny9kAkFgx4fNpoceQ8LT
   📈 Votes: 22
   💰 Rewards: 3075

🔹 Peer 2: QmYJeqmiqLNC5cosqE76wZSVdBEHL5Mq9zwFUX61d2fAzn
   📈 Votes: 0
   💰 Rewards: 0

⏰ Last Check: 2025-06-20 20:05:23

Troubleshooting Telegram

  1. "Bot token invalid"

    • Verify your bot token from @BotFather
    • Use --update-telegram-config to re-enter it

  2. "Chat ID not found"

    • Make sure you've sent a message to your bot
    • Check the getUpdates URL response
    • Use --update-telegram-config to re-enter it

  3. "No notifications received"

    • Check that your bot is active
    • Verify the chat ID is correct
    • Ensure you have blockchain activity to monitor

  4. "EOA address not found"

    • Get your EOA address from the Gensyn dashboard
    • Make sure the address starts with "0x" and is 42 characters long
    • Verify the address is correct

  5. "No peer IDs found"

    • Ensure your EOA address is correct
    • Check that you have active peer IDs on the Gensyn network
    • The service will automatically detect and monitor all your peer IDs

🔧 How It Works

  1. Configuration Management:

    • Stores Telegram bot token and chat ID locally
    • Prompts for EOA address on first run
    • Supports custom config file paths

  2. Blockchain Monitoring:

    • Queries GenRL-Swarm contract (0xFaD7C5e93f28257429569B854151A1B8DCD404c2)
    • Uses Alchemy API for blockchain data access
    • Monitors votes and rewards

  3. Peer ID Detection:

    • Automatically fetches all peer IDs associated with your EOA address
    • Monitors each peer ID individually
    • Provides per-peer breakdown in notifications

  4. Change Detection:

    • Compares current values with previous values
    • Only sends notifications when changes are detected
    • Stores previous data locally for comparison

  5. Telegram Integration:

    • Sends formatted HTML messages via Telegram Bot API
    • Includes change indicators (📈 for increases, 📉 for decreases)
    • Provides detailed per-peer breakdown

📝 Logging

The service provides detailed console output including:

  • Configuration loading and validation
  • Blockchain data queries and results
  • Peer ID detection and monitoring
  • Telegram message sending status
  • Error handling and recovery

Example output:

[2025-01-01 12:00:00] Starting Telegram monitoring service...
[2025-01-01 12:00:01] Loaded Telegram config: BotToken=***, ChatID=123456789
[2025-01-01 12:00:02] Sending welcome message...
[2025-01-01 12:00:03] Message sent successfully to Telegram!
[2025-01-01 12:00:04] Please provide your EOA address to start monitoring...
[2025-01-01 12:00:10] Fetching peer IDs for address: 0x1234567890abcdef...
[2025-01-01 12:00:15] Successfully loaded 4 peer IDs for monitoring
[2025-01-01 12:00:16] Starting continuous monitoring loop (checking every 30 minutes; notifications only sent if there are updates on your peers)...

🛠️ Development

Building from Source

git clone https://github.com/Deep-Commit/gswarm.git
cd gswarm
make build
make install

Testing

make test
make test-coverage

Code Quality

make fmt
make lint

🐛 Troubleshooting

Common Issues

  1. "gswarm command not found"

    • Ensure Go 1.24+ is installed and $GOPATH/bin is in your PATH
    • Reinstall with: go install github.com/Deep-Commit/gswarm/cmd/gswarm@latest

  2. "Telegram API error"

    • Verify your bot token is correct
    • Ensure your bot is active and not blocked
    • Check that the chat ID is valid

  3. "No blockchain data found"

    • Verify your EOA address is correct
    • Check that you have active peer IDs on the Gensyn network
    • Ensure the contract address is accessible

  4. "Permission denied"

    • Make sure all files are executable as needed
    • Ensure proper file permissions for config files

Debug Mode

The service provides detailed output by default. For additional debugging, check the console output for specific error messages.

📋 Requirements

System Requirements

  • Go 1.24+
  • Network connectivity for blockchain queries and Telegram API
  • Telegram Bot Token (from @BotFather)
  • Telegram Chat ID

File Structure

~/.gswarm/
├── telegram-config.json      # Telegram configuration
└── telegram_previous_data.json # Previous blockchain data

🤝 Contributing

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

See CONTRIBUTING.md for detailed guidelines.

💝 Support the Project

If you find GSwarm helpful and would like to support its development, consider making a donation:

Ethereum Address:

0xA22e20BA3336f5Bd6eCE959F5ac4083C9693e316

Your support helps us:

  • Maintain and improve the monitoring service
  • Add new features and enhancements
  • Provide better documentation and support
  • Keep the project free and open source

Thank you for your support! 🙏

📄 License

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

🔗 Related

📋 About This Project

Third-Party Status

GSwarm is an independent, community-developed tool that provides Telegram monitoring for Gensyn AI node activity. We are not affiliated with the Gensyn team and operate as a separate monitoring service.

What We Do

  • Monitor blockchain activity via smart contract queries
  • Track votes and rewards
  • Send real-time notifications via Telegram
  • Provide detailed per-peer breakdown
  • Store configuration and data locally

Support

For issues related to the core Gensyn AI platform, please contact the official Gensyn team. For issues with GSwarm itself, please use our GitHub issues page.

🗺️ Roadmap

For detailed information about upcoming features and development plans, see our Development Roadmap.

Current Development Focus (Q3 2025)

  • Enhanced Notifications: More detailed analytics and charts
  • Custom Schedules: Configurable monitoring intervals
  • Multiple Addresses: Support for monitoring multiple EOA addresses
  • Historical Data: Track and display historical trends
  • Advanced Filtering: Custom notification filters and thresholds

Upcoming Features

  • Web Dashboard: Visual monitoring interface
  • Mobile App: Native mobile monitoring app
  • API Integration: REST API for external integrations
  • Advanced Analytics: Detailed performance metrics and insights
  • Multi-Platform Support: Support for additional messaging platforms
Go Installation