Sui TG Analyzer

Production-ready ElizaOS agent with Docker deployment, Telegram admin command controls, and health/readiness endpoints.

Business focus (what this project does)

This project is a Telegram-first Sui wallet intelligence assistant. In practice, it:

• onboards users by capturing and storing their Sui wallet address per session/profile,
• analyzes wallet state using Sui RPC data plus Suiscan snapshot signals,
• returns actionable portfolio/risk insights (balances, activity, protocol exposure, staking/LST positions), and
• gives operators secure Telegram admin controls for runtime operations.

Business-wise, it is designed to reduce manual wallet support work, standardize user guidance, and provide a controllable production service for wallet insight workflows.

How it can be extended

• Add new Lymna actions in plugins/lymna (e.g., alerting, scoring, protocol-specific playbooks).
• Provide text-to-DeFi functionality by deeplinking constructed ptbs to dApps for signing (e.g. swap 100USDC for SUI on the best possible rate)
• Expand channel support through installed ElizaOS plugins (Telegram already wired; Discord/Twitter can be enabled via env keys).
• Swap or add model providers through existing installs (openai, anthropic, ollama, etc.) without changing core flow.
• Add premium/business tiers by extending cached user profiles and gating advanced analyses.

Technical details

What is included

• Dockerized app + Postgres (docker-compose.yaml)
• Health endpoints:
  • GET /health (liveness)
  • GET /ready (readiness / config checks)
• Telegram admin command action (secret + allowlists)
• Runtime controls from Telegram:
  • status
  • maintenance mode on/off
  • log level change
  • cache clear (session scope)
  • process restart (for container restart policy)

Required environment variables

Copy .env.example to .env and set at minimum:

• One model provider:
  • OPENAI_API_KEY or ANTHROPIC_API_KEY or OLLAMA_API_ENDPOINT
• POSTGRES_URL (defaults in compose if omitted)
• TELEGRAM_BOT_TOKEN (if Telegram is enabled)
• TELEGRAM_ALLOWED_CHATS (comma-separated chat IDs)
• TELEGRAM_ADMIN_USERNAMES (comma-separated Telegram usernames)
• TELEGRAM_ADMIN_SECRET
• ELIZA_SERVER_AUTH_TOKEN (recommended for API protection)

Admin command format (Telegram)

Default prefix is /admin (override with ADMIN_COMMAND_PREFIX).

/admin <secret> status
/admin <secret> clear-cache
/admin <secret> action maintenance on
/admin <secret> action maintenance off
/admin <secret> action log-level debug
/admin <secret> restart

First-time deployment (VPS + Docker Compose + Nginx + TLS)

1. Provision server baseline

   • Ubuntu/Debian VPS, DNS A record to server IP.
   • Open firewall: 22, 80, 443.

2. Install runtime dependencies

   • Install Docker Engine + Docker Compose plugin.
   • Install Nginx + Certbot.

3. Clone and configure app

   • Clone repository to server.
   • Go to sui-agent directory.
   • Create .env from .env.example.
   • Set production secrets and API keys.

4. Start containers

   docker compose up -d --build
   docker compose ps
   docker compose logs -f lymna-agent

5. Validate app health before proxy

   curl -fsS http://127.0.0.1:3000/health
   curl -fsS http://127.0.0.1:3000/ready

6. Configure Nginx reverse proxy

   • Use template at deploy/nginx/sui-agent.conf.
   • Set your domain.
   • Enable site and reload Nginx.

7. Issue TLS certificate

   sudo certbot --nginx -d your-domain.com

8. Post-deploy checks

   • https://your-domain.com/health returns success.
   • Send Telegram admin command /admin <secret> status from an allowlisted chat/user.
   • Confirm unauthorized chat/user gets denied.

Day-2 operations

• Update app:

  git pull
  docker compose up -d --build

• Rollback:

  • Revert commit/tag.
  • Rebuild + restart compose.

• Restart containerized app:

  docker compose restart lymna-agent

• Check health and logs:

  docker compose ps
  docker compose logs --tail 200 lymna-agent

Notes

• /health is used by container healthchecks.
• /ready reports degraded (503) when no model provider is configured.
• Telegram admin command is intentionally locked to Telegram source + secret + allowlists.