Token-Gated Verification System (Telegram)

Access control system for private Telegram communities based on on-chain wallet balance verification and wallet ownership validation.

This project implements a Telegram bot that validates both token holdings and wallet control before granting access to a private group.

---

Problem

Managing token-based private communities manually introduces several issues:

• users selling the token after gaining access
• shared or resold invite links
• lack of wallet ownership verification
• absence of periodic revalidation
• error-prone and time-consuming manual checks

This system automates access control while ensuring that users both hold the required tokens and control the wallet they claim to own.

---

High-level flow

1. A user starts the verification process via Telegram
2. The user selects a supported blockchain network
3. The user provides a wallet address
4. The system verifies on-chain that the wallet meets the required token balance
5. If the balance requirement is met, the system generates a random small transfer amount
6. The user is instructed to send that exact amount to the bot’s verification wallet
7. After the transfer is made, the user confirms verification via Telegram
8. The system checks the blockchain for the exact transfer amount
9. Upon successful validation, a single-use invite link is generated
10. Verified users are periodically revalidated:
    • if token requirements are no longer met, access is automatically revoked

---

Key features

• On-chain token balance verification
• Wallet ownership validation via micro-transfer
• Multi-network support
• ERC-20 token balance checks
• Single-use Telegram invite links
• Periodic automatic revalidation
• Automatic removal on rule violation
• Persistent verification state
• Designed for continuous execution (always-on)

---

Architecture overview

• Off-chain logic (Node.js)
• Blockchain RPC integrations
• Telegram bot as user interface
• On-chain transaction monitoring
• Local persistence for verification state
• Designed to run privately on a VPS

---

Usage (high-level)

This system is designed to be deployed as a private, self-hosted service.

At a high level, usage involves:

1. Running the bot as a long-lived process (e.g. on a VPS)
2. Defining supported networks and token balance requirements
3. Connecting the bot to a private Telegram group
4. Allowing users to initiate verification via Telegram
5. Letting the system handle wallet validation, access control, and periodic revalidation automatically

Deployment steps, credentials, and production configuration details are intentionally omitted from this repository.

---

Security and privacy

This system is intentionally designed as a private, non-custodial tool.

The public repository contains a sanitized version:

• no real API keys or secrets
• no production wallet addresses or group identifiers
• no real user data

---

Runtime state

User verification state is stored locally in JSON files generated at runtime.

These files are intentionally not tracked in version control and are created automatically when the system is executed.

Setup notes

Telegram requires a numeric group_id to generate invite links programmatically.

A small helper script is included under /scripts to retrieve the group ID after adding the bot to the target group. This script is only used during initial setup and is not part of the core verification logic.

Project status

This is a functional system actively used in private environments.

The repository is published for demonstrative and educational purposes, focusing on system design, verification flow, and access-control logic rather than deployment configuration.