🕋 Cube Worlds Bot 🎲

A Telegram Mini App game on the TON blockchain. Earn $CUBE through daily claims, dice games, and referrals, then mint a generative pixel-art NFT. Includes a CUBE → SATOSHI jetton swap and an idle-clicker mining mode.

---

✨ Highlights

• 🎮 Mini App game — Vue 3 frontend served straight inside Telegram, with TonConnect wallet integration.
• 🎲 Dice + claims + referrals — daily streak bonuses, dice "series" detection, premium-user multipliers.
• 🎨 AI-generated NFTs — Stability AI image-to-image + ChatGPT descriptions, pinned to IPFS, minted as TON cNFTs.
• 🔐 DOOM captcha — anti-bot challenge backed by HMAC-signed tokens (no secrets shipped to the client).
• ⛓️ On-chain transaction monitoring — Fastify worker polls TON for incoming payments and credits points automatically.
• 🧪 Heavily tested backend — 455 tests, ~92% line coverage, all on the Node.js built-in test runner.

🏗️ Architecture

┌─────────────────┐     ┌──────────────────┐     ┌────────────────┐
│  Telegram Bot   │     │  Fastify Server  │     │   Vue 3 App    │
│  (Grammy)       │────▶│  (API + Static)  │◀────│   (Vite, TMA)  │
│  src/bot/       │     │  src/server.ts   │     │  src/frontend/ │
└────────┬────────┘     └────────┬─────────┘     └────────────────┘
         │                       │
         │              ┌────────┴─────────┐
         └─────────────▶│     MongoDB      │
                        │  (Typegoose)     │
                        └────────┬─────────┘
                                 │
                        ┌────────┴─────────┐
                        │  TON Blockchain  │
                        │  (subscription)  │
                        └──────────────────┘

See ARCHITECTURE.md for the full system overview and runtime flows.

🧰 Tech Stack

Layer	Stack
Bot	Grammy + plugins (auto-retry, hydrate, parse-mode, i18n)
HTTP API	Fastify + @fastify/middie, @fastify/static
Frontend	Vue 3 + Vite + Pinia + TonConnect
Database	MongoDB via Typegoose (Mongoose decorators)
Blockchain	@ton/ton for transactions, NFT minting, jetton operations
AI	Stability AI (images) + OpenAI (story/descriptions)
Storage	Pinata IPFS for NFT metadata + artwork
Quality	@antfu/eslint-config, Prettier, tsc, Husky

🚀 Quickstart

Prerequisites: Node 18+, MongoDB, a Telegram bot token, optional TON wallet for production.

# 1. Configure
cp .env.example .env
# edit .env — BOT_TOKEN, MONGO_URL, etc.

# 2. Install (root + frontend each have their own package.json)
npm install
npm --prefix src/frontend install

# 3. Run in watch mode
npm run dev                            # backend (tsx watch)
npm --prefix src/frontend run dev      # frontend (Vite, port 5173)

📜 Scripts

Command	Purpose
npm run dev	Backend watch mode (tsx).
npm run build:all	Compile backend (tsc) + frontend (vite build).
npm run lint	Lint with @antfu/eslint-config.
npm run format	Prettier write across .ts/.js/.vue/.json/.css/.scss/.md.
npm run typecheck	tsc --noEmit strict.
npm run test:backend	Backend unit/integration suite (Node test runner).
npm run test:coverage	Coverage report via Node's --experimental-test-coverage.
npm run start	One-shot build + run (production-like).

🧪 Testing

The backend uses Node.js's built-in test runner (node --test) — no Jest/Vitest. Handlers are written with dependency injection so tests can swap in mocks without spinning up Mongo, TON, or the bot. See src/backend/auth-handler.test.ts for the canonical pattern.

npm run test:backend     # ~6s, 455 tests
npm run test:coverage    # full per-file coverage report

Coverage snapshot

npm run test:coverage produces:

Metric	Coverage
Lines	91.66 %
Branches	95.01 %
Functions	74.72 %

Areas at or near full coverage: every backend route handler, all callback-data packers, every keyboard, every middleware, plus most pure helpers (points, markdown, text, time, votes, leaderboard-rows, …). Files that still have gaps are mostly Typegoose model classes and config bootstrap — code that only meaningfully executes against a real database or environment.

🗂️ Project Layout

src/
  main.ts               # entrypoint — MongoDB → bot → server → subscription → start
  server.ts             # Fastify, registers /api/* handlers
  config.ts             # znv + Zod, lazy proxy singleton
  subscription.ts       # TON transaction poller
  bot/
    index.ts            # middleware chain (ORDER MATTERS) + feature registration
    features/*.ts       # commands: start, dice, mint, play, line, whales, admin/*
    middlewares/*.ts    # attach-user, i18n, reaction, update-logger
    keyboards/*.ts      # inline keyboards (photo, queue-menu, change-language)
  backend/              # Fastify handlers (auth, claim, leaderboard, nft, captcha, …)
  common/
    models/             # Typegoose: User, Balance, Claim, CNFT, Transaction, Vote
    helpers/            # ton, ipfs, generation, files, telegram, random, photo, …
  frontend/             # Vue 3 + Vite (separate package.json)
    captcha/            # standalone DOOM captcha (HTML/JS, not Vue)
locales/                # Fluent (.ftl) translations
docs/                   # design docs, coverage badge, future development

📚 Further Reading

• ARCHITECTURE.md — system shape, startup flow, runtime flows, security model
• AGENTS.md — orientation for AI coding agents working on this repo
• CODEX.md — quick reference for ChatGPT Codex / Cursor-style tools
• CLAUDE.md — compact context for Claude Code
• docs/FUTURE_DEVELOPMENT.md — prioritized improvements and feature ideas

🤝 Contributing

1. Fork and create a branch.
2. Run the full gate before opening a PR:

   npm run lint && npm run typecheck && npm run test:backend && npm --prefix src/frontend run build

3. Follow the existing DI handler pattern for any new route or bot command — it makes the handler testable without booting infrastructure.

📄 License

MIT — see package.json.