Frequently Asked Questions

General Questions

What is GSwarm?

GSwarm is a dedicated Go-based Telegram monitoring service for Gensyn AI that provides real-time notifications about blockchain activity, including votes, rewards, and balance changes. It monitors the GenRL-Swarm contract (0xFaD7C5e93f28257429569B854151A1B8DCD404c2) and sends updates via Telegram.

Is GSwarm affiliated with the official Gensyn team?

No. 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.

What can GSwarm do?

GSwarm can:

Monitor blockchain activity via smart contract queries
Track votes, rewards, and balance changes
Send real-time notifications via Telegram
Provide detailed per-peer breakdown
Store configuration and data locally
Automatically detect and monitor all peer IDs associated with your EOA address

What can GSwarm NOT do?

GSwarm cannot:

Modify training algorithms
Change blockchain smart contracts
Alter model architectures
Modify core Gensyn functionality
Change the official Gensyn protocol

Installation & Setup

What are the system requirements?

Go 1.24+ (for building the Telegram monitoring service)
Network connectivity for blockchain queries and Telegram API
Telegram Bot Token (from @BotFather)
Telegram Chat ID (your chat ID or group chat ID)

How do I install GSwarm?

Option 1: Install with Go (Recommended)

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

Option 2: Build from source

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

Why can't I find the `gswarm` command after installation?

Make sure your Go bin directory is in your PATH:

For bash/zsh:

export PATH=$PATH:$(go env GOPATH)/bin

For fish:

set -gx PATH $PATH (go env GOPATH)/bin

Add this to your shell configuration file to make it permanent.

Telegram Setup

How do I create a Telegram bot?

Start a chat with @BotFather (opens in a new tab) on Telegram
Send /newbot and follow the instructions
Choose a name for your bot (e.g., "GSwarm Monitor")
Choose a username (must end with 'bot', e.g., "gswarm_monitor_bot")
Save the bot token provided by BotFather

How do I get my Telegram Chat ID?

Start a chat with your bot by clicking the link or searching for it
Send any message to the bot (e.g., "Hello")
Visit this URL in your browser (replace YOUR_BOT_TOKEN with your actual token):
```
https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
```
Find your chat ID in the response (look for "chat":{"id":123456789})

How do I get my EOA address?

Log into your Gensyn dashboard (opens in a new tab)
Navigate to your account settings or profile section
Copy your Ethereum address (EOA) - this is required for monitoring your blockchain activity

Usage

How do I start GSwarm?

Simply run:

gswarm

The service will guide you through the setup process interactively.

How often does GSwarm check for updates?

GSwarm checks for blockchain updates every 5 minutes by default.

Will I get notifications for every check?

No, GSwarm only sends notifications when there are actual changes detected. This prevents spam and ensures you only get meaningful updates.

What information is included in notifications?

Notifications include:

Total votes and rewards
Per-peer breakdown with individual vote and reward counts
Change indicators (📈 for increases, 📉 for decreases)
Timestamp of the last check
EOA address being monitored

Can I monitor multiple addresses?

Currently, GSwarm monitors one EOA address per instance. You can run multiple instances with different configuration files to monitor multiple addresses.

Can I use GSwarm in a group chat?

Yes, you can use a group chat ID instead of a personal chat ID. All members of the group will receive the notifications.

Configuration

Where are configuration files stored?

Configuration files are stored in:

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

Can I use a custom configuration path?

Yes, use the --telegram-config-path flag:

gswarm --telegram-config-path /path/to/custom/config.json

How do I update my configuration?

Use the --update-telegram-config flag to force re-entry of configuration:

gswarm --update-telegram-config

Can I use environment variables for configuration?

Yes, 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

Troubleshooting

"Bot token invalid" error

Verify your bot token from @BotFather
Make sure the token is copied correctly without extra spaces
Use --update-telegram-config to re-enter it

"Chat ID not found" error

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

"No notifications received"

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

"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

"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

"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

"Go version too old"

Update Go to version 1.24 or later
Download from golang.org/dl (opens in a new tab)
Verify with: go version

Security

Is my data secure?

Local Storage: All configuration stored locally
No Cloud Storage: No data transmitted to external services
Read-Only: Only reads blockchain data, never modifies anything
No Private Keys: Never requires or stores private keys

What data does GSwarm access?

GSwarm only accesses:

Your Telegram bot token (for sending messages)
Your chat ID (for sending messages)
Your EOA address (for blockchain queries)
Public blockchain data (votes, rewards, balances)

Can others see my notifications?

Only people in the chat where you configured the bot will see the notifications. Make sure to use a private chat or a trusted group.

Performance

How much resources does GSwarm use?

GSwarm is very lightweight:

Memory: Typically uses <50MB RAM
CPU: Minimal CPU usage for monitoring
Network: Periodic API calls every 5 minutes
Storage: Small config files (<1KB)

Can I run GSwarm on a server?

Yes, GSwarm can run on servers. Consider using:

Systemd service for automatic startup
Docker container for isolation
Cron jobs for periodic monitoring

How do I run GSwarm as a service?

Create a systemd service file:

[Unit]
Description=GSwarm Telegram Monitoring Service
After=network.target
 
[Service]
Type=simple
User=gswarm
WorkingDirectory=/home/gswarm
ExecStart=/usr/local/bin/gswarm
Restart=always
RestartSec=10
 
[Install]
WantedBy=multi-user.target

Support & Community

Where can I get help?

Documentation: Check the Telegram Monitoring guide
FAQ: This page for common questions
Issues: Report bugs on GitHub
Community: Join discussions on GitHub

How do I report a bug?

When reporting issues, please include:

GSwarm version (gswarm --version)
Operating system and version
Go version (go version)
Error messages and logs
Steps to reproduce the issue

How do I request a feature?

For feature requests:

Describe the feature clearly
Explain the use case
Consider if it fits within the project's scope
Check if similar features already exist

Legal & Licensing

What license does GSwarm use?

This project is licensed under the MIT License.

Can I use GSwarm commercially?

Yes, the MIT License allows commercial use.

How can I support the project?

You can support the project by making a donation to:

0xA22e20BA3336f5Bd6eCE959F5ac4083C9693e316

Your support helps us maintain and improve the monitoring service, add new features, and keep the project free and open source.

Technical Details

Which blockchain does GSwarm monitor?

GSwarm monitors the GenRL-Swarm contract (0xFaD7C5e93f28257429569B854151A1B8DCD404c2) on the Gensyn network.

What APIs does GSwarm use?

Telegram Bot API: For sending notifications
Alchemy API: For blockchain data queries
GenRL-Swarm Contract: For vote and reward data

How does change detection work?

GSwarm stores previous blockchain data locally and compares it with new data. Notifications are only sent when values actually change.

Can I customize the monitoring interval?

Currently, the 5-minute interval is hardcoded. This may be configurable in future versions.

What happens if the service crashes?

If running as a service, it will automatically restart. If running manually, you'll need to restart it manually.

Can I run multiple instances?

Yes, you can run multiple instances with different configuration files to monitor different addresses or send notifications to different chats.

API Endpoints Changelog