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

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

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

Разработка GameFi Mini App — это не просто «сделать игру в Telegram». Это пересечение трёх дисциплин: 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 Mini App Store)

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 с ключом derived от 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 — любой может слать запросы на backend, притворяясь любым Telegram пользователем. Это дыра безопасности номер один в Mini App играх.

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

TON Connect — стандарт для подключения 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) {
    console.log('Connected:', wallet.account.address)
    updateGameState(wallet.account.address)
  }
})

tonconnect-manifest.json — обязательный файл с метаданными приложения, должен быть доступен по указанному URL. TON Wallet в Telegram (через window.Telegram.WebApp.openTonWallet) — упрощённый путь только для Telegram WebView, без выбора кошелька.

Транзакции в TON

TON — не EVM. Смарт-контракты написаны на FunC/Tolk, транзакционная модель другая. Для GameFi чаще всего нужны:

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

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

// Отправка Jetton (например, игрового токена)
await connector.sendTransaction({
  messages: [{
    address: jettonWalletAddress, // jetton wallet игрока, не master контракт
    amount: toNano('0.05').toString(), // TON для gas
    payload: beginCell()
      .storeUint(0xf8a7ea5, 32) // op::transfer
      .storeUint(0, 64)          // query_id
      .storeCoins(tokenAmount)   // amount
      .storeAddress(Address.parse(recipientAddress))
      .storeAddress(Address.parse(responseAddress)) // excess TON возврат
      .storeBit(0)               // custom payload = null
      .storeCoins(toNano('0'))   // forward TON amount
      .endCell()
      .toBoc()
      .toString('base64')
  }],
  validUntil: Math.floor(Date.now() / 1000) + 300 // 5 минут
})

TON транзакционная модель асинхронная: сообщения между контрактами идут через очередь, нет atomic composability как в EVM. Для GameFi это означает: результат транзакции нужно polling-ить, нельзя просто ждать receipt.

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

Типичный GameFi Mini App имеет три слоя:

Frontend (React/Vue + Telegram Web Apps SDK)

import { useEffect } from 'react'

declare global {
  interface Window { Telegram: any }
}

const tg = window.Telegram.WebApp

// Инициализация
useEffect(() => {
  tg.ready() // сигнализируем что приложение готово
  tg.expand() // разворачиваем на весь экран
  
  // Haptic feedback для tap механики
  tg.HapticFeedback.impactOccurred('light')
}, [])

// Основная tap механика
const handleTap = async () => {
  tg.HapticFeedback.impactOccurred('medium')
  
  // Отправляем tap на backend (с initData в headers)
  const response = await fetch('/api/tap', {
    method: 'POST',
    headers: {
      'X-Telegram-Init-Data': tg.initData
    }
  })
  const { newBalance, reward } = await response.json()
  setBalance(newBalance)
  showRewardAnimation(reward)
}

HapticFeedback — мелочь, которая сильно влияет на feel игры. impact типы: light, medium, heavy, rigid, soft.

Backend (Node.js/Go + PostgreSQL)

Backend хранит игровое состояние в обычной реляционной базе. On-chain операции — только при withdraw или NFT mint. Основные endpoints:

• POST /api/tap — засчитать тап, вернуть reward
• GET /api/leaderboard — топ игроков
• POST /api/claim — вывести заработанное в кошелёк (→ blockchain транзакция)
• POST /api/referral/apply — применить реферальный код

Rate limiting на уровне backend обязателен: без него боты дотянутся до любых лимитов. Redis + sliding window — стандартный подход:

const TAPS_PER_SECOND_LIMIT = 10
const DAILY_TAP_LIMIT = 100_000

async function processTap(userId: string): Promise<TapResult> {
  const rateKey = `rate:tap:${userId}`
  const dailyKey = `daily:tap:${userId}:${today()}`
  
  const [rateCount, dailyCount] = await redis.pipeline()
    .incr(rateKey)
    .incr(dailyKey)
    .expire(rateKey, 1) // 1 секунда window
    .expire(dailyKey, 86400)
    .exec()
  
  if (rateCount > TAPS_PER_SECOND_LIMIT) throw new Error('Rate limit')
  if (dailyCount > DAILY_TAP_LIMIT) throw new Error('Daily limit reached')
  
  return updateBalance(userId)
}

Blockchain layer (TON / EVM)

Blockchain только для:

• Хранения итоговых balances (claim операции)
• NFT предметов
• Governance токена (если есть)

Промежуточные игровые балансы — off-chain в PostgreSQL. Это единственный подход который работает при миллионах пользователей.

Viral механики: реферальная система

Реферальная система — основа роста. Стандартный паттерн:

// Генерация реферальной ссылки
const refLink = `https://t.me/${BOT_USERNAME}?start=ref_${userId}`
// Пользователь делится ссылкой → новый игрок использует start param
// → начислить бонус рефереру и рефералу

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

Реферальная структура: прямые рефералы (больший бонус) + рефералы рефералов (меньший). Ограничивать глубину максимум 2-3 уровнями. Многоуровневая реферальная система — это MLM, что плохо для репутации и может привлечь регуляторное внимание.

Daily missions + streak — удержание аудитории. Задания обновляются ежедневно, streak бонусы за n дней подряд.

Airdrop механика: snapshot и distribution

Большинство успешных TON GameFi использует следующий паттерн:

1. Игра в течение N месяцев — gameplay без токена
2. Snapshot балансов на определённую дату
3. TGE (Token Generation Event) — токен создаётся
4. Airdrop пропорционально snapshot

Distribution on-chain: для TON jetton airdrop крупного масштаба (миллионы адресов) — batch transfer через кастомный смарт-контракт. Merkle tree distribution — пользователи сами claim-ят через Merkle proof, что переносит gas cost на них:

// Merkle tree для airdrop (JS)
import { MerkleTree } from 'merkletreejs'
import { keccak256 } from 'ethers'

const leaves = airdropList.map(({ address, amount }) =>
  keccak256(Buffer.from(address + amount.toString()))
)
const tree = new MerkleTree(leaves, keccak256, { sortPairs: true })
const root = tree.getRoot().toString('hex')

// Для каждого пользователя при claim:
const proof = tree.getHexProof(keccak256(Buffer.from(address + amount.toString())))

Monetization модели

Telegram Stars — встроенная валюта Telegram, работает без внешних кошельков. Для монетизации casual аудитории — самый простой путь. Конвертируется в TON через Fragment.

Стек и деплой

HTTPS обязателен — Telegram Mini Apps работают только по HTTPS. Для разработки: localtunnel или ngrok.

Сроки

MVP tap-to-earn Mini App с базовой игровой механикой, TON кошелёк, реферальная система, leaderboard: 3-4 недели.

Полноценный GameFi Mini App с NFT предметами, airdrop механикой, tournament системой, TON jetton, governance: 2-3 месяца.

Основные риски: TON jetton контракты требуют понимания асинхронной модели TON — это другая парадигма по сравнению с EVM. Масштабирование backend при внезапном viral growth — Redis cluster и горизонтальный scale должны быть предусмотрены заранее.