🌐 Quip Global Monitor Bot

A real-time, zero-config Telegram Bot designed to monitor the health, hardware distribution, and telemetry of the Quip Network. Built specifically for Node Operators and DevOps engineers, this lightweight tool dynamically parses raw P2P node logs to map out the global network state without relying on third-party APIs.

---

🧠 How It Works (Under the Hood)

Unlike standard monitoring tools that rely on heavy RPC calls or external APIs, this bot operates entirely locally as a passive log parser. This ensures zero interference with your actual node processes.

1. Log Ingestion: It continuously reads the data/logs/quip-node.log file generated by your Quip Node in strict read-only mode.
2. Deep Parsing: It uses Regex to extract P2P JSON payloads during node handshakes, identifying peer IPs, OS ecosystems, hardware APIs (cuda, metal), and CPU thread counts.
3. State Management: Parsed telemetry is compiled into a lightweight local quip_db.json. Real-time timestamp evaluation happens upon user command execution to accurately determine if a node is 🟢 ACTIVE or 🔴 LOST.

---

✨ Key Features

• 🤖 Zero-Config Auto-Detection: Automatically detects the host machine's hardware (CPU threads, GPU models via nvidia-smi or Metal API) and self-assigns the [⭐ OWNER] tag.
• ⏱️ Strict Real-Time Pulse: Implements a 15-minute strict heartbeat tracking mechanism. Nodes failing to broadcast within this window are dynamically flagged as offline.
• 🖥️ Deep Hardware Fingerprinting: Classifies OS ecosystems (Apple Mac, Windows, Linux) and recursively counts multi-GPU setups.
• 🧹 Automated Garbage Collection: A built-in purge mechanic automatically removes stale offline nodes (>24 hours) from the local database, preventing memory bloat.
• 🏆 Live Leaderboards: Real-time top miner leaderboards dynamically filtering only currently active nodes.

---

🚀 Installation & Setup

1. Prerequisites (Python & Dependencies)

For Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3 python3-pip -y
pip3 install python-telegram-bot

For macOS (Apple Silicon / Intel): (Assuming you have Homebrew installed)

brew install python3
pip3 install python-telegram-bot

2. Create a Telegram Bot (Get your Token)

1. Open Telegram and search for @BotFather.
2. Send the command /newbot and follow the prompts.
3. Once created, BotFather will give you an HTTP API Token (e.g., 123456789:ABCdefGhIJKlmNoPQRstUVwxyZ). Copy this token.

3. Clone & Configure

Clone this repository to the same machine where your Quip Node is running:

git clone [https://github.com/ntllinh2511/Quip-Node-Monitor.git](https://github.com/ntllinh2511/Quip-Node-Monitor.git)
cd Quip-Node-Monitor

Open quip_pulse_bot.py with your favorite text editor (nano on Linux, vi on macOS):

nano quip_pulse_bot.py

Find the TOKEN variable at the top of the file and paste the token you got from BotFather:

TOKEN = "123456789:ABCdefGhIJKlmNoPQRstUVwxyZ"

(Save and exit).

---

💬 Available Commands

• 📊 /stats - Displays global network health, showing the exact number of Active vs. Offline nodes, OS distribution, and a live Network Pulse percentage.
• 🚀 /topgpu - Real-time Active GPU Miners: Ranks the top online nodes equipped with GPUs. Dead nodes are automatically excluded.
• 🖥️ /topcpu - Real-time Active CPU Miners: Ranks the top online CPU-only nodes based on core count.
• 🟢 /active - A combined, paginated list of all currently active nodes on the network.
• 🔎 /check <name_or_ip> - Deep search tool. Instantly retrieves hardware specs, OS, and the exact UTC timestamp of a node's last heartbeat.

---

🛠️ Running the Bot 24/7 (Background Execution)

For professional node operations, run the bot in the background so it stays alive after you close your terminal.

Option A: For Linux (Using Systemd)

1. Create a service file:

sudo nano /etc/systemd/system/quip-bot.service

2. Paste the following configuration (Adjust the paths to match your actual setup):

[Unit]
Description=Quip Telegram Monitor Bot
After=network.target

[Service]
User=root
WorkingDirectory=/root/Quip-Node-Monitor
ExecStart=/usr/bin/python3 /root/Quip-Node-Monitor/quip_pulse_bot.py
Restart=always

[Install]
WantedBy=multi-user.target

3. Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable quip-bot
sudo systemctl start quip-bot

(Check status anytime with: sudo systemctl status quip-bot)

Option B: For macOS (Using Screen)

macOS users can use the built-in screen utility to keep the script running in a detached session.

1. Start a new screen session named "quipbot":

screen -S quipbot

2. Run the bot inside the session:

python3 quip_pulse_bot.py

3. Detach from the session (leave it running in the background) by pressing: Control + A, then D. (To resume and check logs later, type: screen -r quipbot)

---

🤝 Contributing

Contributions, issues, and feature requests are welcome!

📄 License

This project is MIT licensed. Built with ❤️ for the Quip Community.