Розробка Telegram Mini App для GameFi

Розробка GameFi Telegram Mini App

Telegram Mini Apps відкрили несподівано ефективний канал для GameFi: аудиторія 900 мільйонів користувачів, нативне розповсюдження через посилання та ботів, вбудована система платежів, і — що важливо для Web3 — TON кошелёк прямо в додатку через TonConnect. Hamster Kombat, Notcoin, Catizen показали, що механіка tap-to-earn + referral + airdrop може зібрати десятки мільйонів користувачів за тижні.

Розробка GameFi Mini App — це перетин трьох дисциплін: Telegram Web Apps API, blockchain інтеграція (частіше TON, інколи EVM через WalletConnect), та viral growth механіки.

Telegram Mini App: технічний контекст

Mini App — це звичайне веб-приложение (HTML/JS), яке запускається в embedded WebView всередині Telegram. Доступно через:

• Кнопку в боті (keyboard_button з web_app типом)
• Inline кнопку в повідомленні
• Пряму посилання t.me/botname/appname
• @gamestore

Telegram передає додатку initData — рядок з даними користувача і підписом. Критично для GameFi: backend повинен верифікувати initData щоб довести, що запит дійсно від Telegram користувача:

import crypto from 'crypto'

function verifyTelegramInitData(initData: string, botToken: string): boolean {
  const params = new URLSearchParams(initData)
  const hash = params.get('hash')
  params.delete('hash')
  
  // Сортування параметрів і формування data-check-string
  const dataCheckString = [...params.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join('\n')
  
  // HMAC-SHA256 з ключем, виведеним від bot token
  const secretKey = crypto.createHmac('sha256', 'WebAppData')
    .update(botToken)
    .digest()
  
  const expectedHash = crypto.createHmac('sha256', secretKey)
    .update(dataCheckString)
    .digest('hex')
  
  return hash === expectedHash
}

Без верифікації initData — будь-хто може робити фальшиві запити. Дыра безпеки номер один в Mini App іграх.

TON інтеграція через TonConnect

TonConnect — стандарт для підключення TON кошельків до Mini Apps. Підтримується Tonkeeper, TON Wallet (вбудований в Telegram), MyTonWallet.

import TonConnect from '@tonconnect/sdk'

const connector = new TonConnect({
  manifestUrl: 'https://mygame.com/tonconnect-manifest.json'
})

const wallets = await connector.getWallets()
await connector.connect({ jsBridgeKey: 'tonkeeper' })

connector.onStatusChange((wallet) => {
  if (wallet) {
    updateGameState(wallet.account.address)
  }
})

Jetton transfers (TON аналог ERC-20):

import { toNano, beginCell, Address } from '@ton/core'

await connector.sendTransaction({
  messages: [{
    address: jettonWalletAddress,
    amount: toNano('0.05').toString(),
    payload: beginCell()
      .storeUint(0xf8a7ea5, 32) // op::transfer
      .storeCoins(tokenAmount)
      .storeAddress(Address.parse(recipientAddress))
      .endCell()
      .toBoc()
      .toString('base64')
  }],
  validUntil: Math.floor(Date.now() / 1000) + 300
})

TON транзакційна модель асинхронна: повідомлення в черзі між контрактами, немає atomic composability як в EVM. Для GameFi: результат вимагає polling, не можна просто await receipt.

Game Loop архітектура

Frontend (React + Telegram Web Apps SDK)

const tg = window.Telegram.WebApp

useEffect(() => {
  tg.ready()
  tg.expand()
  tg.HapticFeedback.impactOccurred('light')
}, [])

const handleTap = async () => {
  tg.HapticFeedback.impactOccurred('medium')
  
  const response = await fetch('/api/tap', {
    method: 'POST',
    headers: { 'X-Telegram-Init-Data': tg.initData }
  })
  const { newBalance, reward } = await response.json()
  setBalance(newBalance)
}

Backend (Node.js + PostgreSQL + Redis)

Ігровой стан в БД. On-chain тільки для withdraw або NFT mint. Основні endpoints:

• POST /api/tap—зареєструвати tap, повернути reward
• GET /api/leaderboard—топ гравців
• POST /api/claim—вивести в blockchain
• POST /api/referral/apply—застосувати реферальний код

Rate limiting обов'язковий: Redis + sliding window.

Blockchain Layer (TON/EVM)

Тільки для:

• Фінального балансу (claim операції)
• NFT предметів
• Governance токена

Проміжні баланси—off-chain в PostgreSQL. Єдиний підхід який працює при мільйонах користувачів.

Вірусні механіки: реферальна система

Deep link: https://t.me/${BOT_USERNAME}?start=ref_${userId} Mini App link: https://t.me/${BOT_USERNAME}/${APP_NAME}?startapp=ref_${userId}

Структура: прямі рефералы (більший бонус) + рефералы рефералов (менший). Обмежити глибину максимум 2-3 рівнями. Багаторівневе = MLM, погана репутація.

Daily missions + streak—утримання. Щоденні задання + streak bonuses.

Airdrop механіка: snapshot та distribution

Стандартний паттерн:

1. Гра N місяців—без токена
2. Snapshot балансів на дату
3. TGE—токен створюється
4. Airdrop пропорційно

Для крупного масштабу (мільйони адрес)—merkle tree distribution. Користувачи claim через merkle proof.

Монетизація моделі

Стек

HTTPS обов'язковий—Telegram Mini Apps працюють тільки по HTTPS.

Сроки

MVP tap-to-earn з базовою механікою, TON кошельком, реферальною системою, leaderboard: 3-4 тижні.

Повнофункціональний GameFi Mini App з NFT, airdrop, tournament, TON jetton, governance: 2-3 місяці.