Tear

A bot that makes you cry.

---

Tear is an open-source edition of Xeon, that currently has 7 features:

• Contract Logs (Text & NEP-297)
• Account Info
• Token Holders
• Near TGI
• AI Moderator
• Burrow Liquidations
• Price Commands

Running

After cloning this repo, run ./setup.sh (a workaround for this issue), and then cargo run.

You need to have MAIN_TOKEN environment variable that contains Telegram bot token that you can get from botfather.

Test Server

If you want to use Telegram's test server, use the following Nginx configuration to proxy requests to the test server:

server {
    listen 5555;
    server_name localhost;

    location ~ ^/bot([^/]+)/(.*) {
        set $token $1;
        set $method_name $2;

        proxy_pass https://api.telegram.org/bot$token/test/$method_name;
        proxy_pass_request_body on; 
        proxy_pass_request_headers on;       
    }

    location ~ ^/file/([^/]+)/(.*) {
        set $token $1;
        set $method_name $2;

        proxy_pass https://api.telegram.org/file/$token/test/$method_name;
        proxy_pass_request_body on;
        proxy_pass_request_headers on;
    }
}

Contract Logs

No additional setup is required.

Account Info

No additional setup is required.

Token Holders

No additional setup is required.

Near TGI

No additional setup is required.

AI Moderator

You need to have these environment variables:

• OPENAI_API_KEY: OpenAI API key (if you plan to use GPT-4o and GPT-4o-mini)
• CEREBRAS_API_KEY: Cerebras API key (if you plan to use Llama 70B). It will fall back to GPT-4o if the message contains an image, as this version of Llama is not multimodal.

Burrow Liquidations

No additional setup is required.

Price Command

No additional setup is required.

Chart Command

The chart command is using TradingView charting library, which is not open-source, and available only by request. There is an origin that allows localhost and coding playground (codepen, jsfiddle, etc.) usage, but it doesn't work with file:// and data: URIs, so we need to proxy requests to the library. Here's a Nginx configuration that does the job:

server {
    listen 5556;
    server_name localhost;
    location ~ /.* {
        if ($request_method = OPTIONS) {
            return 204;
        }
        add_header 'Access-Control-Allow-Origin' '*' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, DELETE, PUT, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization' always;
        proxy_pass 'https://charting-library.tradingview-widget.com';
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $cookie_nocache $arg_nocache;
        proxy_pass_request_body on;
        proxy_pass_request_headers on;
        proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
        proxy_ssl_server_name on;
    }
}

Also, you need to have geckodriver installed and in your PATH.

Architecture

The bot consists of multiple modules. The first and necessary one is HubModule. It handles /start and gives buttons that help users access other modules. There are also event handlers that handle events from blockchain, they are somewhat similar to modules, and one struct can implement both traits. Check out tearbot/src/main.rs to see how to register a module. Modules in Tear are hidden behind feature flags. Some of the modules are open-source, so these features are enabled by default, but some are stored inside xeon-private-modules, which are not accessible publicly. Tear can support multiple telegram bot instances, with different or shared per-bot data and modules, check out the main.rs to see more.

There are 2 types of telegram events: Callbacks (button clicks) and Messages. Telegram has a limit of 64 characters in button metadata, so when the bot sends a button with a callback data, it creates a hash and stores its base58 representation in MongoDB. When the user clicks a button, the bot pulls the data associated with this hash, deserializes it into enum TgCommand, and lets every module handle this callback. The bot works primarily with TgContext struct, which has a method edit_or_send that is quite convenient if you want to avoid sending a new message each time a user interacts with a button. The context stores a shared reference to struct BotData, which contains various internal bot data, such as connected accounts, message commands (message requests), etc. When the bot needs to request the user to send a message, it uses bot_data.set_dm_message_command(user_id, MessageCommand::Something), which stores the MessageCommand in a PersistentCachedStore<UserId, MessageCommand> for later use. When a user sends a message, and the user exists in this data structure, the modules handle this MessageCommand, and if the message is valid and the action was successful, call bot_data.remove_dm_message_command(UserId).

One struct you would notice particularly often in the codebase is PersistentCachedStore, it's a high-level abstraction over a MongoDB key-value store. Check the comments in the struct declaration to understand more about its usage.

Event source

Some modules (for example, Contract Logs) get events from blockchain using an indexer. There are 2 event sources available:

1. WebSocket wss://ws-events-v3.intear.tech/: An indexer hosted by Intear, the easiest and the default option.
2. Self-hosted all-indexers. To use this, install Redis, run all-indexers in the background, set REDIS_URL environment variable, and run the bot with redis-events feature.