
Небольшое вступление
Последние годы стали для меня переломными в карьере. В 2023 году я погрузился в блокчейн-разработку, затем открыл компанию, прошёл через серьёзный финансовый кризис и начал жизнь с чистого листа. Сейчас финансовое положение понемногу стабилизируется, но сказать, что я уже твёрдо встал на ноги и добился заметных успехов, пока не могу. Зато за это время накопил немало опыта.
Недавно я понял, что устал от фриланса: от однообразных задач, необходимости постоянно разбираться в чужом коде и тревоги о том, будет ли работа завтра. Тогда я решил сделать что-то необычное и интересное — показать, что умею, вспомнить подзабытый опыт 2D-геймдева и объединить его со знаниями, которые получил за последние годы.
В этой статье я покажу, как создаю браузерную 2D-игру для мобильных устройств: от первоначальной концепции и игрового цикла до интеграции с блокчейном TON и запуска внутри Telegram.
Кто знает, возможно, из этого что-то и выйдет :-)
Сразу уточню: в этой статье я не буду углубляться в основы программирования и разбирать каждую строчку кода. Вместо этого сделаю упор на общую концепцию и архитектуру проекта. Весь код с подробной документацией лежит в моём публичном репозитории, так что любой желающий может покопаться в нём и самостоятельно разобраться в деталях.
Также хочу пояснить, что я ни в коем случае не пропагандирую азартные игры. Видеослот в этом проекте служит лишь наглядной демонстрацией того, как можно использовать блокчейн TON для монетизации Mini App в экосистеме Telegram. Это могла быть и любая другая игра, но с учётом моего прошлого опыта выбор пал именно на такой формат.
Идея создания мобильной 2D игры
Так уж сложилось, что свой путь в IT я начал с онлайн-гемблинга. В начале 2010-х учился создавать браузерные видеослоты на классическом для того времени стеке: PHP, MySQL и Flash. Сервер рассчитывал выигрыши, база хранила пользователей и балансы, а Flash отвечал за картинку и анимации. Привет олдам :-)
Слоты мы делали разные: от простых однолинейных до более сложных, с 21 линией и бонусными раундами. Если честно, большинство были корявыми копиями хардварных аппаратов: из плат которых извлекали графику и звуки, нарезали спрайты и собирали браузерную версию. Сегодня такой подход вызвал бы немало вопросов, но тогда каждый делал как умел.

А свой первый игровой автомат я увидел ещё раньше. В начале нулевых зашёл в продуктовый магазин на соседней улице и заметил возле входа небольшой «столбик». Рядом стояла женщина и закидывала в него пятирублёвые монеты.
Выглядел он предельно просто: на каждой из трёх игровых сторон — LED-дисплей с красными цифрами, таблица выигрышей, монетоприёмник и металлический лоток. Ни одной кнопки. Бросаешь монету, цифры крутятся, а если выпадает выигрышная комбинация — в лоток со звоном сыплется мелочь.
Сначала я только проходил мимо и с дурацкой ухмылкой смотрел на играющих. Потом попробовал сам, получил пару небольших выигрышей и понял, чем эта штука цепляет. Никаких сложных правил: монета, три секунды ожидания, результат.
Со временем «столбики» исчезли из магазинов, но эта простецкая игра осталась в памяти. И вот спустя примерно 20 лет я решил воссоздать её в современном виде: сохранить механику с тремя цифрами, перенести в мобильный браузер, добавить нормальную графику и связать с экосистемой Telegram.
Итак, приступим!
Стек технологий и инструменты

Со стеком я решил особо не экспериментировать и в основном использовал привычные мне инструменты. Проект относительно не большой, поэтому усложнять его ради модной архитектуры я не вижу смысла.
Adobe Photoshop 2026
Всю графику для игры я рисую в Adobe Photoshop 2026: фон, дисплеи, кнопки, спрайты и остальные элементы интерфейса.
С Photoshop я работаю уже давно, в основном как дизайнер фирменных стилей и UI/UX. Поэтому для меня это привычный и понятный инструмент. Конечно, игровую графику можно было создавать в Figma или Illustrator, но Photoshop мне привычнее, тем более что у меня оплачена лицензия на год :-)
Godot 4 и GDScript
В качестве игрового движка я выбрал Godot 4. Почему именно его? Что ж, если честно, просто хотелось потренироваться: раньше я с ним не работал. Тем более что он бесплатный и имеет удобный визуальный редактор.
Однако в процессе выяснилось, что для моей игры, работающей в мобильном WebView, этот выбор оказался не самым удачным. Но об этом расскажу в конце статьи.
React, TypeScript и Vite
Godot отвечает за визуальную часть игры: отображает барабаны, проигрывает анимации и реагирует на действия игрока. Результаты раундов и изменения баланса рассчитывает сервер.
Вокруг игры находится Shell — веб-оболочка на React и TypeScript. Она встраивает Godot-игру через iframe и связывает её с серверным API, Telegram и криптокошельком через TON Connect. Игра и оболочка обмениваются событиями через postMessage.
React удобен для интерфейса вокруг игры, а TypeScript помогает контролировать структуру передаваемых данных. Для разработки и сборки используется Vite. Такой подход позволяет дорабатывать веб-интерфейс и интеграции независимо от игровых сцен и анимаций.
Node.js и Fastify
Бэкенд я решил писать на Node.js и TypeScript с использованием Fastify. Этот стек я использую и в других своих проектах: он мне знаком и позволяет быстро собрать API.
Бэкенд проверяет ставки, определяет результаты раундов, рассчитывает выигрыши и обновляет балансы пользователей. Доверять всё это клиенту мы не можем: код браузерной игры можно подменить, а запросы отправить напрямую в API, в обход интерфейса. Поэтому все проверки и расчёты остаются на сервере.
MySQL, Prisma и phpMyAdmin
В качестве базы данных я выбрал MySQL. В основном из-за простоты и потому, что давно с ней работаю.
Конечно, здесь вполне можно было использовать PostgreSQL. Но никаких особых требований к базе у этого проекта нет, поэтому для демонстрации возможностей MySQL более чем достаточно.
Для работы со схемой базы и запросами используется Prisma. А когда мне нужно быстро посмотреть или поправить данные вручную, я открываю старый добрый phpMyAdmin. Возможно, это не самый модный инструмент, но мне с ним удобно, поскольку я пользуюсь им уже много лет (но только в dev!).
Telegram Mini Apps и TON (The Open Network)
Игра будет запускаться в формате Telegram Mini App — прямо внутри мессенджера, без установки отдельного приложения. Для подключения кошелька в сети TON используем TON Connect: через него приложение запрашивает операции, а пользователь подтверждает их в своём кошельке.
TON я выбрал не случайно. Прежде всего из-за его связи с экосистемой Telegram. Для небольшой игры с криптотокенами это удобная связка: пользователь уже находится в мессенджере, здесь же открывает игру и может подключить кошелёк. Никаких скачиваний приложений, никаких заморочек с со сторонними кошельками — все в пределах одного мессенджера.
Docker Compose
Ну и, конечно, Docker Compose для запуска веб-клиента, API, воркеров и базы данных. Здесь особо нечего комментировать — это база.
В итоге проект будет разделён на несколько независимых частей. Godot отвечает за игровую часть и обменивается событиями с веб-оболочкой на React через postMessage. Оболочка связывает игру с Telegram и обращается к серверу на Node.js по HTTP API. Сервер проверяет действия пользователя, рассчитывает результаты раундов и сохраняет данные в MySQL. Подключение кошелька и подтверждение переводов пользователем проходят через TON Connect, а проверкой платежей и обновлением игрового баланса занимается бэкенд.
Архитектура и организация репозитория
Начать, думаю, стоит с репозитория. Я решил использовать монорепозиторий: хранить игру, веб-оболочку и бэкенд вместе, но разнести их по отдельным каталогам. Для такого проекта это удобно — всё под рукой, а изменения в связанных частях приложения можно вносить одним коммитом.
Структура получилась примерно такой:

Основное разделение проходит внутри apps. В godot находится всё, что касается игрового интерфейса: сцены, анимации, звуки и обработка действий игрока. В web живёт Shell — веб-оболочка, которая размещает игру на странице и связывает её с Telegram, кошельком и API. А api отвечает за авторизацию, расчёт результатов, балансы и обработку платежей.
Отдельно в src я положил архивы исходных материалов — PSD, WAV-файлы и шрифты. Настройки окружения вынесены в docker, служебные скрипты — в scripts, а описание архитектуры, API и интеграций — в docs.
Дизайн, звуки и интерфейс игры

Визуальная часть игры родилась, как обычно, с образа в голове, который я набросал на бумаге, а затем перешёл в свой любимый Photoshop, чтобы воплотить его уже в графике.
Кстати, по поводу названия и цветовой гаммы: логотип Crazy Cash у меня уже давно был в векторе. Примерно в 2015 году я перерисовал его с фотографии зала игровых автоматов, который в середине 2000х находился недалеко от моего дома в родном городке. Конечно, этой компании, как и многих других, уже и в помине не существует. Но ещё в середине 2010-х я собирался использовать этот логотип для одного из своих онлайн проектов, а руки тогда до него так и не дошли. Вот оттуда и взялись синий фон и общая стилистика игры.
Признаюсь, пришлось помучиться с отрисовкой рамок, таблиц выплат, панелей, спрайтов для анимации LED-циферблата, подсветки логотипа, различных кнопок, переключателей и других элементов игрового интерфейса. Но результат, как по мне, получился очень неплохой :-)
Долго останавливаться на дизайне мы не будем. Скажу лишь, что после недели-двух экспериментов у меня вырисовался законченный концепт. Затем я разбил макет на отдельные спрайты, необходимые для создания игры в Godot, и перешёл к сборке игрового интерфейса.
Что касается аудиоэффектов, сначала я пошёл лазить по бесплатным аудиостокам. Просидев там несколько часов и не найдя ничего достойного, я вдруг вспомнил о старых Flash-видеослотах, с которыми работал давным-давно. Они хранились у меня в архивах больше 15 лет.
Я расчехлил десяток-другой SWF-файлов игр, декомпилировал их и достал оттуда знакомые звуки. Обработал их в Ableton Live и получил то, что мне нужно. Кстати, те, кто знаком с такими играми, как «Клубничка», «Обезьянки» и тому подобными, вероятно, услышат знакомые нотки и поймают немного ностальгии :-)
Таблица выплат и расчет RTP

Теперь расскажу про таблицу выигрышей: она важна и для дизайна интерфейса, и для игрового опыта, и для расчёта RTP (Return to Player) — теоретического процента возврата игроку от общей суммы ставок на большой дистанции.
Таблицу выигрышей в тех самых древних автоматах-«столбиках» я, конечно же, наизусть не помнил, поэтому полез в интернет искать архивные фотографии. Нашёл несколько разных его вариантов и в итоге пришёл к тому, что вы видите сейчас. Мне было важно, чтобы количество выигрышных комбинаций было чётным: так их можно симметрично разместить в сетке таблицы.
В найденных вариантах часто встречались комбинации 7XX, 77X, 0XX, 00X, где X обозначает любую цифру, а также различные комбинации из трёх одинаковых цифр. Ну и, конечно, 777 с выплатой в 200 ставок. Вот на этой основе и сложилась моя собственная таблица выигрышей.
Но сама таблица выплат ещё не определяет RTP: он зависит и от того, с какой вероятностью выпадает каждая комбинация. Поэтому, прежде чем приступить к сборке игры в Godot, я решил заняться математикой и тестированием вероятностей на бэкенде.
Для этого я создал отдельную страницу — своего рода RTP-лабораторию. Чтобы на ней было удобно менять веса комбинаций и наглядно отслеживать, как это влияет на расчётный RTP и результаты симуляций. Целился я в диапазон 98–99%. Подобная проверка игровой математики — привычная часть Gambling-dev, с котором у меня уже было немало опыта.
Если коротко, каждой группе комбинаций назначается вес — он определяет вероятность её выпадения. Чем больше вес относительно остальных, тем чаще выпадает соответствующий результат. RTP рассчитывается как сумма произведений вероятностей исходов на их множители выплат.
Увеличиваем долю выигрышных исходов — RTP растёт, добавляем больше проигрышных — снижается. При этом один и тот же RTP можно получить разными способами: через частые небольшие выигрыши или редкие крупные. Поэтому в лаборатории я смотрел не только на итоговый процент, но и на распределение выплат, а затем проверял расчёты на большом количестве симулированных раундов.
В начале я расставил веса так:
Правило | Множитель | Вероятность | Вклад в RTP |
Без выигрыша | — | 79,496% | 0.000% |
0XX | ×1 | 8,506% | 8.506% |
7XX | x2 | 8,575% | 17.150% |
00X | x5 | 0,850% | 4.250% |
55X | x8 | 0.850% | 6.800% |
77X | x10 | 0.850% | 8.500% |
000 | x15 | 0.087% | 1.310% |
111 | x20 | 0.087% | 1.746% |
222 | x25 | 0.087% | 2.183% |
444 | x30 | 0.087% | 2.619% |
666 | x40 | 0.087% | 3.492% |
333 | x50 | 0.087% | 4.365% |
888 | x60 | 0.087% | 5.238% |
999 | x70 | 0.087% | 6.111% |
555 | x100 | 0.087% | 8.730% |
777 | x200 | 0.087% | 17.460% |
Пересекающиеся паттерны используют наибольший доступный множитель: например, 777 выплачивает ×200 вместо ×10 или ×2; 555 — ×100.
Согласитесь, достаточно топорно. Тем не менее теоретический RTP составлял 98,46%, что укладывалось в целевой показатель. Но при таком распределении весов заметная часть возврата приходилась на редкие крупные выигрыши. Поэтому фактический RTP на коротких сессиях мог сильно отклоняться от расчётного.
Для пользователя на игровом опыте это отражалось бы так. Вероятность получить 000 с множителем ×15 была бы ровно такой же, как и 777 с множителем ×200, — всего 0,087% на каждую комбинацию. При этом вклад 777 в теоретический RTP примерно в 13 раз больше, чем вклад 000.
То есть при теоретически высоком RTP игрок в основном видел бы проигрыши и мелкие выигрыши. Комбинации из трёх одинаковых цифр выпадали бы редко, а самый крупный выигрыш, на который приходилась часть расчётного возврата, за короткую сессию мог и вообще не появиться.
Поэтому я решил продолжить экспериментировать с весами, добиваясь более сбалансированного распределения выигрышей. Хотелось улучшить игровой опыт и при этом удержать RTP в целевом диапазоне 98–99%.
К слову, такой RTP в гэмблинг индустрии считается достаточно щедрым показателем. Для сравнения: у обычной европейской рулетки с одним зеро RTP составляет около 97,3%.
В результате получилось то, что вы сейчас видите в моей RTP-лаборатории. Теперь среди комбинаций из трёх одинаковых цифр чаще выпадают те, у которых меньше множитель. Например, вероятность получить 000, 111, 222, 444 или 333 заметно выросла, а шанс поймать крупный выигрыш на 555 или 777 снизился. На такой компромисс пришлось пойти, чтобы сделать игровой процесс более динамичным и при этом удержать RTP в заданном диапазоне.
Можете сами оценить результат, потестировав игру в FUN-режиме, а если захочется покрутить веса самостоятельно — исходный код лежит в публичном репозитории.
Сборка игры в Godot 4 и связь с Shell

Затем я взялся осваивать редактор Godot. Углубляться в разработку 2D-игр мы не будем: если подробно описывать всё, с чем пришлось разобраться, материала хватит на целый учебник. Поэтому ограничусь основами.
Сам редактор оказался интуитивно понятным. В основе устройства игры лежат узлы и сцены. Узел — это отдельный элемент со своей задачей: показать спрайт, проиграть звук или обработать нажатие кнопки. Узлы объединяются в иерархическое дерево, из которого и состоит сцена.
Сцены, в свою очередь, можно вкладывать друг в друга — получается что-то вроде матрёшки. Это называется композиция сцен: мы создаём отдельные сцены для барабанов видеослота, бегущей строки или кнопки, а затем вставляем их в основную сцену игры. При необходимости эти заготовки можно переиспользовать в других местах, не собирая всё заново.
Логика игрового клиента — не путать с серверной логикой — разложена по нескольким GDScript-файлам (все перечислять их не буду), прикреплённым к соответствующим узлам. Одни обрабатывают нажатия кнопок, другие управляют бегущей строкой, подсветкой выигрышных комбинаций и анимацией начисления выигрыша. Главный скрипт slots.gd выступает своего рода дирижёром: переключает состояния игры и следит, чтобы барабаны, звуки и эффекты срабатывали в нужный момент.
Отдельный модуль web_bridge.gd связывает игру с веб-оболочкой — Shell. Он передаёт ей действия игрока, а уже Shell напрямую обращается к API бэкенда и возвращает полученные ответы в Godot. Сама игра HTTP-запросов не делает и не решает, сколько вы выиграли: её задача — красиво показать то, что уже посчитал сервер.
Чтобы игра и оболочка понимали друг друга, у них есть контракт общения — набор сообщений с заранее определённой структурой. Обмен идёт через postMessage: каждое сообщение содержит type — название события, и payload — его данные. Например, при нажатии PLAY игра отправляет game:spinRequested со ставкой и режимом. Shell проверяет сообщение, отправляет запрос в API и возвращает shell:spinResult с комбинацией, выигрышем и новым балансом либо shell:spinError, если что-то пошло не так.
Полный список сообщений и их полей описан в docs/GODOT.md. Такой контракт позволяет дорабатывать игру и веб-оболочку независимо, пока обе стороны соблюдают общие правила обмена.
С клиентской частью разобрались: игра отправляет действия пользователя и показывает полученный результат. Теперь заглянем на другую сторону API — туда, где проверяются ставки, выбираются выигрышные комбинации и обновляются балансы.
Разработка API и серверная логика игры
Чтобы лучше понять, как всё устроено, давайте сначала разберёмся, что видит пользователь. Если вы зайдете на главную страницу, вы увидите, что у игры условно две версии: гостевая, которая открывается в обычном браузере, и Mini App внутри Telegram. В гостевой версии можно играть только в бесплатном FUN-режиме. В Telegram доступны оба режима: бесплатный FUN и игра с использованием криптотокенов GRAM.
Если с FUN-режимом всё понятно, то для пополнения баланса и вывода средств в GRAM-режиме нужно подключить TON-совместимый кошелёк через TON Connect (о нем мы еще поговорим позже). Shell отвечает за подключение, а сервер проверяет подтверждение владения кошельком и связывает его с аккаунтом пользователя. Само подключение токены в игру не переводит: пополнение — отдельная операция, которую пользователь подтверждает в кошельке. После её проверки GRAM зачисляются на игровой баланс пользователя в нашей базе данных, с которого уже списываются ставки и на который начисляются выигрыши.
Сессия и игровой баланс
Перед стартом игры сервер должен понять, кто к нему пришёл. Для обычного браузера создаётся гостевая сессия и временный пользователь guest. Позже фоновый воркер удаляет его из базы, когда с момента последней активности прошло 24 часа. При запуске через Telegram Mini App оболочка передаёт на сервер initData. Бэкенд проверяет подпись этих данных, находит или создаёт постоянного пользователя по его Telegram ID и открывает для него сессию.
Сессия хранится в HttpOnly cookie, которую браузер отправляет вместе с запросами. Сам Godot с ней не работает — этим занимается оболочка Shell. После авторизации Shell запрашивает GET /me/session, получает текущий режим и балансы, а затем передаёт нужные данные в игру.
Балансы FUN и REAL разделены. Первый используется для виртуальных очков, второй — для игрового учёта средств, связанных с TON. При этом REAL-баланс внутри игры и баланс подключённого кошелька — разные вещи: подключение кошелька само по себе ничего на игровой счёт не зачисляет.
Что происходит при нажатии PLAY
Shell отправляет запрос POST /crazy-cash/spins
{ "mode": "fun", "bet": "10", "requestId": "уникальный-идентификатор-запроса" }
Клиент передаёт режим, ставку и идентификатор запроса. Бэкенд проверяет сессию, допустимость ставки и наличие средств. Затем выбирает результат по настроенным весам, рассчитывает выплату и сохраняет раунд вместе с новым балансом. В ответ Shell получает выпавшие цифры, выигрышное правило, множитель, сумму выплаты и итоговый баланс, после чего передаёт результат в Godot.
К этому моменту исход раунда уже определён и сохранён. Вращение барабанов, подсветка таблицы и анимация начисления происходят позже — это всего лишь его визуальное представление.
Повторные запросы и потерянные ответы
Отдельно пришлось учесть ситуации, когда сервер обработал ставку, но ответ до клиента не дошёл. Например, пользователь переключился между приложениями или мобильный интернет решил немного отдохнуть.
Если просто отправить новый запрос, можно случайно запустить ещё один раунд и повторно списать ставку. Чтобы этого избежать, у каждого спина есть requestId, который создаёт Shell. Повторная отправка того же запроса с тем же идентификатором возвращает уже сохранённый результат. Если под этим идентификатором прислать другие параметры, сервер отклонит запрос.
Такое поведение называется идемпотентностью. Для восстановления потерянного ответа также предусмотрен отдельный метод GET /crazy-cash/spins/by-request. Поэтому тайм-аут здесь не означает проигрыш или отмену: сначала нужно выяснить, чем закончился исходный запрос.
Для пополнений, выводов и получения FUN-кредитов используется похожий принцип: у операции есть свой идентификатор, а её состояние сохраняется в таблице client_operations. Поэтому после обрыва соединения можно узнать результат исходной операции, не создавая новую.
Хранение данных и расчёты
Для хранения пользователей, сессий, балансов и истории раундов используется MySQL, а схема базы и миграции описаны через Prisma. Подробнее базу данных мы разберем дальше.
Расчёт раунда выполняется в транзакции с блокировкой записи пользователя. Проверка баланса, списание ставки, начисление выигрыша и сохранение результата проходят атомарно — как одна операция: либо все изменения фиксируются вместе, либо откатываются. Привет финтеху :-) Блокировка при этом не позволяет двум параллельным запросам потратить один и тот же остаток.
Суммы хранятся целыми числами. Для REAL-баланса используется внутренняя единица учёта: 1 GRAM = 1000 единиц (почему именно так, расскажу позже). Через JSON балансы и суммы передаются строками, чтобы не терять точность при работе с большими целыми числами в JavaScript.
Кроме истории раундов, для REAL-режима ведётся отдельный журнал движения средств — ledger_entries. В нём фиксируются ставки, выплаты, пополнения и резервирование средств на вывод. Это позволяет проверить, из каких операций сложился баланс пользователя.
Контракты API
Форматы запросов проверяются схемами Fastify, а бизнес-ограничения — серверной логикой. Например, отключённая кнопка или проверка суммы в интерфейсе помогают пользователю, но не заменяют проверку на бэкенде: обратиться к API можно и напрямую.
Помимо игровых запросов, есть методы получения истории, конфигурации ставок. Подключение кошелька, пополнения и вывод средств образуют отдельную часть API — её разберём дальше вместе с TON-интеграцией.
Эндпоинты, полные форматы запросов, ответов и ошибок описаны в docs/API.md, а правила хранения балансов, транзакций и журнала операций — в docs/DATABASE.md.
База данных и учёт балансов
С API и режимами игры вроде разобрались. Теперь посмотрим, как на сервере хранятся пользователи, игровые балансы и результаты раундов — и как сделать так, чтобы повторный запрос или обрыв соединения не привели к двойному списанию.
Как я писал ранее, для хранения данных я использую MySQL, а схему таблиц и миграции описываю через Prisma. Данные здесь можно условно разделить на несколько групп: пользователи и их сессии, игровые раунды, привязанные кошельки и финансовые операции.
В основе находится пользователь, к которому привязаны сессии и два отдельных баланса — FUN и REAL. FUN хранит виртуальные очки, а REAL используется для учёта средств в криптовалютном режиме. История раундов тоже разделена на fun_spins и real_spins, чтобы бесплатная игра и операции с реальными средствами не смешивались.
Каждый раунд сохраняется отдельно: ставка, выпавшая комбинация, правило выигрыша, множитель, выплата и баланс после расчёта. Это позволяет восстановить результат конкретного спина и вернуть его клиенту, если первоначальный ответ потерялся по дороге.
Точность расчётов
Для балансов я использую целые числа. В FUN-режиме это обычные игровые кредиты, а в REAL — внутренние единицы учёта: одна тысячная монеты GRAM. При взаимодействии с блокчейном суммы переводятся в нанотоны.
Масштаб 1 GRAM = 1000 внутренних единиц я выбрал из эстетических соображений. Изначально минимальная ставка была определена как 0,01 GRAM, что в такой шкале соответствует 10 кредитам. Почему именно 10, а не 1? Всё просто: при ставке 10 минимальная ненулевая выплата тоже составляет 10 кредитов. Анимация их зачисления со звуком падающих в лоток монет смотрится естественнее, чем если бы это был 1 кредит. То есть это решение продиктовано оформлением игры, а не какими-то техническими особенностями проекта.
Числа с плавающей точкой в таких расчётах не нужны: ошибки округления, которые почти незаметны в обычном интерфейсе, при работе с балансами могут создать вполне реальные проблемы. По той же причине через API суммы передаются строками — так JavaScript не потеряет точность при обработке больших целых значений.
Журнал движения средств
Одного поля в таблице с текущим балансом недостаточно: нужно понимать, откуда взялась сумма и какие операции её изменили. Для этого у REAL-баланса есть отдельный журнал — ledger_entries. В него добавляются записи о подтверждённых пополнениях, списанных ставках, выигрышах и резервировании средств на вывод.
Например, при запросе вывода сумма сразу убирается из доступного баланса и резервируется под операцию. После подтверждения перевода повторно списывать её уже не нужно. Если операция отменена или завершилась ошибкой до отправки средств, резерв возвращается отдельной записью. Так история изменений сохраняется, а не переписывается задним числом. Такой подход - это стандартная практика в финтехе.
Сами пополнения и выводы хранятся в таблицах deposits и withdrawals со своими статусами. Это важно, потому что запрос к API и перевод в блокчейне не происходят в одной транзакции базы данных. Между созданием операции, отправкой и подтверждением может пройти время, а её состояние должно переживать закрытие страницы и перезапуск сервера.
Подробные правила хранения данных и учёта операций описаны в docs/DATABASE.md, а схема таблиц находится в schema.prisma.
Интеграция с The Open Network (TON)
Ну вот, с основной архитектурой проекта разобрались. Теперь переходим к самому интересному — блокчейн-интеграции: как открыть игру внутри Telegram, подключить кошелёк, принять пополнение и отправить выигранные средства обратно пользователю.
Здесь участвуют несколько отдельных механизмов. Telegram сообщает приложению, кто его открыл. TON Connect связывает приложение с кошельком. Сервер проверяет владение этим кошельком, а через RPC получает данные из блокчейна. Уже на основании проверенных операций обновляется игровой баланс. Разберем все по порядку.
Как игра становится Telegram Mini App
Mini App — это веб-приложение, которое Telegram открывает во встроенном браузере WebView. В конкретно моём случае загружается React-оболочка Shell, а внутри неё — Web-сборка Godot. Сам сайт и API размещаются на моём сервере: Telegram только лишь предоставляет окружение для запуска, но не хостит игру.
Для входа в это окружение нужен бот. Создать его можно через @BotFather (официальный бот от Telegram). Создание бота описано в документации Telegram.
В настройках бота задаётся Main Mini App с публичным HTTPS-адресом игры, в нашем случае https://crazycash.app/game. После этого приложение можно открыть из профиля бота или по ссылке вида https://t.me/имя\_бота?startapp, у меня это https://t.me/CrazycshBot?startapp. Дополнительно можно настроить кнопку меню для запуска.
При открытии Telegram передаёт приложению initData. Shell отправляет исходную строку на бэкенд, где проверяются её подлинность и срок давности. Только после этого сервер создаёт пользовательскую сессию. Просто взять Telegram ID из браузера и поверить ему нельзя: клиентские данные можно подменить. Подробности запуска и авторизации есть в документации Mini Apps.
Где в этой архитектуре находится блокчейн
Как вы уже поняли, в Crazy Cash блокчейн используется только для пополнений и выплат. Сами спины, выбор комбинаций и расчёт выигрышей выполняются на сервере, а игровой баланс хранится в MySQL.
Такое разделение позволяет не просить пользователя подтверждать каждый раунд в кошельке и не платить сетевую комиссию за каждое вращение. Пользователь пополняет игровой баланс, играет, а затем запрашивает вывод. Игровой баланс — обязательство сервиса перед пользователем.
Кстати, в статье, интерфейсе и коде вы можете встретить оба обозначения — GRAM и TON. Это связано с недавним переименованием нативной монеты сети из Toncoin в Gram: в коде и настройках ещё сохраняются привычные имена TON_* и суммы в нанотонах. В контексте проекта речь идёт об одной и той же монете.
TON Connect и манифест приложения
TON Connect — протокол взаимодействия приложения с кошельком. Через него можно получить подключённый адрес, запросить подтверждение владения и предложить пользователю подписать транзакцию. Приватные ключи при этом остаются на стороне кошелька.
В React-оболочке используется пакет @tonconnect/ui-react. Он предоставляет провайдер, интерфейс выбора кошелька и методы для взаимодействия с ним. Godot сообщает Shell о нажатии кнопки подключения, а дальнейшую работу уже выполняет оболочка.
Для подключения нужен манифест — публичный JSON-файл с информацией о приложении. Например:
{ "url": "https://game.example", "name": "Crazy Cash", "iconUrl": "https://game.example/tonconnect-icon.png" }
Кошелёк загружает этот файл и показывает пользователю название и иконку приложения. В репозитории заготовка лежит в apps/web/public/tonconnect-manifest.json, а её адрес задаётся через VITE_TON_MANIFEST_URL (см. docs/CONFIGURATION.md). В моем проекте он находится тут: https://crazycash.app/tonconnect-manifest.json.
Манифест и иконка должны быть доступны извне. Авторизация, ограничения CORS или защитная страница перед файлом могут сломать подключение, даже если сама игра прекрасно открывается. Требования приведены в руководстве TON Connect.
Сам манифест не подтверждает безопасность приложения — это его описание, которое кошелёк показывает перед подключением.
Подключить кошелёк и подтвердить владение — разные вещи
Адрес кошелька публичный. Если клиент просто прислал его на сервер, это ещё не означает, что пользователь им управляет. Для проверки используется ton_proof — подписанное кошельком подтверждение.
В проекте процесс устроен так:
Shell запрашивает у API одноразовое проверочное значение —
challenge.Передаёт его в TON Connect при подключении.
Кошелёк формирует подписанное подтверждение.
Shell отправляет его на сервер.
Бэкенд проверяет подпись, домен приложения, время, выбранную сеть и соответствие ключа адресу кошелька.
Challenge привязан к пользовательской сессии, имеет срок действия и используется один раз. Это не позволяет повторно применить старое подтверждение для новой привязки. Сам ton_proof не является переводом и не требует отдельной транзакции в сети. Описание механизма.
После проверки сервер сохраняет связь между Telegram-пользователем, кошельком и сетью. Таким образом, Telegram-авторизация отвечает на вопрос «кто открыл игру», а ton_proof — «каким кошельком он управляет».
В текущей реализации проверка поддерживает контракты кошельков V4 и V5R1. Поэтому совместимость с TON Connect ещё не означает поддержку любого существующего типа кошелька: сервер тоже должен уметь корректно проверить его устройство. Детали я описал в docs/TON.md.
TON Center и RPC
TON Connect решает задачу общения с пользовательским кошельком. Но серверу нужен независимый способ узнать баланс адреса, посмотреть историю переводов и проверить поступление средств.
Для этого используется TON Center — сервис доступа к блокчейну через HTTP API. RPC, или Remote Procedure Call, позволяет вызвать нужный метод удалённо: например, запросить состояние аккаунта или отправить в сеть уже подписанное сообщение.
В проекте настроены JSON-RPC endpoints API v2:
Testnet: https://testnet.toncenter.com/api/v2/jsonRPC
Mainnet: https://toncenter.com/api/v2/jsonRPC
API и фоновые воркеры обращаются к выбранному endpoint с серверным API-ключом. Настройки эндпоинтов, ключей и хранения секретов описаны в docs/CONFIGURATION.md. Ключ TON Center нужен для доступа к RPC сервису и его лимитам, а не для кошелька - просто уточняю.
Для чтения поступлений приватный ключ вообще не нужен: адрес и история его операций публичны. А для отправки выплаты серверный процесс сначала подписывает сообщение своим ключом и только затем передаёт его через RPC.
Testnet и mainnet
У TON есть основная сеть, та что работает с реальными GRAM — mainnet, и отдельная тестовая — testnet. У них независимые состояния, балансы и история операций. Тестовые монеты нужны только для разработки, что-бы тестировать проект в реальных on-chain условиях, при этом не рискуя потерей денежных средств.
Для тестов можно получить демо-GRAM монеты через официально указанный faucet. При этом сам Telegram необязательно переводить в тестовое окружение: обычная Mini App может взаимодействовать, как с mainnet, так и с testnet.
В Crazy Cash сеть выбирается параметром TON_NETWORK. С ним должны совпадать RPC endpoint, сеть подключённого кошелька, адрес получения платежей и кошелёк выплат. В протоколе TON Connect mainnet обозначается как -239, а testnet — как -3.
Одного переключения сети недостаточно для включения всех переводов: в конфигурации есть отдельные разрешающие флаги. Это помогает отделить проверку интеграции от запуска операций с реальными средствами. Все параметры перечислены так же в docs/CONFIGURATION.md.
Как устроено пополнение
Для пополнений используется общий адрес получателя — адрес GRAM-кошелька проекта. Это может быть ваш личный или любой другой кошелек на который будут поступать токены GRAM. При каждом пополнении, счёту на оплату присваивается отдельный идентификатор — почти как номер счёта в классическом финтехе. Этот идентификатор передаётся в комментарии к платежу и позволяет связать перевод с нужной записью в базе данных.
На деле это выглядит так. Сначала Shell отправляет в POST /deposits сумму и operationId. API создаёт счёт со сроком действия и возвращает адрес получателя, точную сумму в нанотонах и payload с комментарием вида CC:D:<uuid>. Дальше Shell передаёт эти данные в TON Connect, а пользователь подтверждает перевод в кошельке.
Но успешный ответ кошелька ещё не означает, что игровой баланс можно увеличить. Проверкой занимается отдельный deposit watcher, или воркер, — фоновый процесс, работающий в отдельном Docker-контейнере. Он читает историю переводов на адрес получателя через RPC.
Воркер сопоставляет перевод со счётом: проверяет отправителя, получателя, сумму, комментарий, время и успешность операции. Если всё совпало, пополнение получает статус observed — «перевод найден, ожидает зачисления».
Перед зачислением система делает небольшую паузу и повторно проверяет перевод через RPC. Это дополнительная проверка того, что платёж действительно поступил на нужный адрес.
После успешной проверки воркер в одной транзакции базы данных записывает поступление в журнал, меняет статус пополнения на credited — «зачислено» — и увеличивает REAL-баланс игрока.
Пока это происходит, Shell запрашивает состояние операции у своего API. Закрытие интерфейса не отменяет серверную проверку. Идентификатор текущего пополнения сохраняется в sessionStorage, чтобы восстановить ожидание при перезагрузке в рамках той же браузерной сессии.
Как устроен вывод
При выводе Shell отправляет сумму и operationId в POST /withdrawals. Адрес назначения в запросе не передаётся: сервер берёт его из активной привязки кошелька пользователя, ранее подтверждённой через ton_proof при подключении через TON Connect. То есть вывести средства на произвольный адрес, просто подставив его в запрос, нельзя.
API проверяет доступный баланс и резервирует сумму. После этого в базе появляется запись о выводе, а доступный игровой баланс уменьшается. Сам HTTP-обработчик блокчейн-транзакцию не подписывает — этим занимается отдельный payout worker.
Для выплат, как и для приёма пополнений, нужен служебный кошелёк. Но здесь воркер сам подписывает переводы, поэтому ему необходим доступ к ключу. В нашем случае ключ восстанавливается из мнемоники, которая хранится в защищённом файле на сервере, вне репозитория. Настройки описаны в docs/CONFIGURATION.md. Технически можно использовать один кошелёк для пополнений и выплат, но я бы так не делал: воркеру пополнений достаточно публичного адреса, а кошелёк выплат можно держать с ограниченным запасом средств. Это уменьшает возможные потери при теоретическом взломе.
Воркер проверяет служебный кошелёк и запас на комиссии, подписывает перевод и отправляет его через RPC. Для идентификации используется комментарий CC:W:<uuid>. Затем процесс ищет подтверждение поступления на стороне получателя и только после проверки завершает вывод.
У такой операции есть несколько состояний:
held → requested → sent → finalized
Они означают резервирование средств, принятие заявки воркером, попытку отправки и окончательное подтверждение соответственно.
Самый неприятный случай — когда сообщение уже могло попасть в сеть, но процесс не получил ответ или перезапустился. Слепо повторять выплату нельзя: пользователь может получить её дважды. Поэтому неоднозначные состояния сначала сверяются с блокчейном. Возвращать резерв сразу после любого тайм-аута тоже нельзя — перевод мог состояться.
Если же ошибка подтверждённо произошла до отправки, резерв освобождается отдельной записью в журнале. Подробные переходы состояний и проверки для обоих направлений я описал в docs/PAYMENTS.md.
Что важно проверять помимо успешного перевода
Сам по себе тест «пополнил — поиграл — вывел» проверяет только самый простой сценарий. Для такой интеграции важны и отмена подтверждения в кошельке, неправильная сеть, повторная отправка команды, нехватка средств на комиссию, недоступность RPC и перезапуск воркера после отправки.
Для диагностики полезен блокчейн-эксплорер: по адресу и хешу транзакции можно посмотреть, что произошло в сети, и сопоставить это с записью операции в базе. При этом ориентироваться нужно не только на факт отправки, но и на результат обработки у получателя.
А еще у текущей реализации есть и практический предел: сверка выплат читает ограниченное число последних транзакций адреса без постраничного прохода. При росте нагрузки сюда потребуется добавить пагинацию или сохранение позиции обработки. Проверки интеграции с реальными RPC и MySQL также требуют отдельного набора тестов — эти ограничения зафиксированы в документации проекта.
Именно поэтому в архитектуре разделены пользовательское подтверждение, отправка сообщения, наблюдение перевода и окончательный расчёт. Для интерфейса всё это выглядит как одно пополнение или вывод, но сервер должен сохранять каждый этап и уметь продолжить работу после сбоя.
Запуск репозитория в dev и prod
Раз уж вы дочитали до этого места, возможно, вам захочется потестить мои наработки, поковырять код или поискать уязвимости. Поэтому кратко пробегусь по запуску через Docker Compose. Сильно размусоливать не буду — думаю, с командами вы и сами разберётесь. Отмечу лишь несколько важных, на мой взгляд, деталей.
Локальный запуск
Для разработки понадобятся Docker с Compose, Node.js 26 и pnpm 10.33.2. Godot 4.7.1 нужен, если собираетесь менять саму игру и заново экспортировать её для браузера.
После клонирования репозитория создаём файл настроек из шаблона:
cp .env.dev.example .env.dev pnpm install
В .env.dev задаём свои параметры вместо обязательных CHANGE_ME: пароли базы, адреса приложения и настройки интеграций. Все переменные описаны в docs/CONFIGURATION.md. Затем поднимаем окружение:
pnpm docker:dev:up
Compose запускает базу, API, веб-клиент и фоновые процессы. Исходники подключены к контейнерам, поэтому изменения в React и серверном коде подхватываются в режиме разработки. Первый запуск займёт немного времени: контейнерам нужно установить зависимости и подготовить базу.
Открываем http://localhost:<WEB_PORT>/game, где порт берётся из .env.dev. Здесь можно проверить игру в гостевом FUN-режиме. По пути /dev находится RTP-лаборатория — можно покрутить веса и посмотреть, как меняется математика.
Для проверки Mini App внутри Telegram уже понадобится доступный извне HTTPS-адрес: например, через туннель к локальному окружению. Его нужно согласованно указать в настройках бота, приложения, манифеста TON Connect и проверки ton_proof. Один localhost на компьютере для этого не подойдёт.
Платежи сначала проверяем в testnet, с отдельными тестовыми кошельками. Учтите, что локально воркер выплат включается отдельно через Compose-профиль ton-payout: кроме самого профиля, нужны настройки кошелька и разрешение выплат для выбранной сети.
Если меняете сцены, скрипты или ресурсы Godot, игру нужно заново экспортировать в apps/web/public/godot, а затем обновить сжатые файлы:
./scripts/compress-godot-web-build.sh
Готовые файлы экспорта вручную не редактируем. Подробности есть в docs/GODOT.md.
Запуск на сервере
Для prod понадобится сервер с Docker Compose, домен, направленный на этот сервер, и HTTPS. Перед приложением ставим reverse proxy, например Nginx: он принимает внешние запросы и передаёт их веб-контейнеру на 127.0.0.1:20069. Дальше внутренний шлюз сам разделяет запросы: /game открывает игру, а /api ведёт на бэкенд.
Настройки production создаём из отдельного шаблона:
cp .env.prod.example .env.prod
Здесь указываем публичный адрес, параметры базы, Telegram-бота и TON-интеграции. Мнемонику служебного кошелька храним отдельным файлом вне репозитория; каталог с ней подключается к воркеру выплат только для чтения.
После подготовки настроек и Web-экспорта Godot собираем и запускаем контейнеры:
docker compose --env-file .env.prod -f docker/compose.prod.yml up -d --build
Важный момент: prod не означает автоматический переход в mainnet. На сервере можно сначала прогнать весь сценарий в тестовой сети: открыть Mini App, подключить кошелёк, пополнить баланс, сыграть и вывести средства. Для mainnet отдельно переключаются сеть, адреса, RPC-настройки и разрешения пополнений и выплат.
Перед публикацией изменений запускаем основные проверки:
pnpm typecheck pnpm test pnpm build
После запуска проверяем /api/health, состояние контейнеров и логи воркеров. А для постоянной работы отдельно настраиваем резервное копирование базы: в репозитории автоматического бэкапа нет, и Docker-том сам по себе его не заменяет.
Команды диагностики и порядок обновления собраны в docs/OPERATIONS.md, а короткая инструкция для первого запуска — в docs/QUICKSTART.md.
Подведем итоги
В этой статье я попытался кратко описать процесс разработки, не упуская ключевых деталей. Насколько хорошо получилось — судить вам. Статья всё равно вышла достаточно увесистой, хотя нюансы программирования мы практически не затрагивали.
Что лично я думаю по поводу всего этого мероприятия? На создание игры ушло около четырёх месяцев — занимался я ей только в свободное время. В целом процесс мне понравился, и результатом я доволен. Но без неприятных моментов, конечно, не обошлось.
В первую очередь это связано с Godot. При всех его преимуществах для моего проекта он оказался не самым удачным выбором. Web-экспорт есть, но в небольшой браузерной игре накладные расходы движка ощущаются довольно сильно. В моём случае даже сжатая сборка занимает около 10 МБ, при этом на сами игровые ассеты приходится примерно 1 МБ. Для следующих проектов я уже присматриваюсь к Phaser или к PixiJS как основе для собственной реализации.
Отдельно пришлось повозиться с экранной клавиатурой. При тестировании на iPhone поле ввода внутри Godot не вызывало её, поэтому ввод пришлось вынести в Shell. Но и здесь нужного поведения удалось добиться не полностью: вместо цифровой клавиатуры с возможностью ввода дробной суммы открывалась буквенная. Переключиться на цифры вручную можно, вроде мелочь, но неприятно. К тому моменту, когда эти косяки стали очевидны, большая часть игры уже была собрана, и переделывать всё на другом движке не хотелось. Зато теперь у меня есть новый опыт :-)
Что можно улучшить? Во-первых, пока не хватает админки, чтобы удобно управлять игрой, смотреть статистику и разбираться с операциями пользователей. Это отдельная работа, которая тоже требует немало времени. Да и требования к ней у каждого свои. Базовую версию для собственных задач я планирую сделать в ближайшее время.
Ещё хочется доработать обработку блокчейн-транзакций: сделать отдельный сервис, который будет отслеживать новые операции и передавать их на обработку. Сейчас воркеры периодически опрашивают RPC, а такой сервис позволил бы централизовать получение событий и сократить задержки. Правда, сам по себе «стример» ещё не делает систему надёжнее: ему тоже нужны восстановление после сбоев, обработка пропущенных транзакций и защита от повторов. Здесь есть над чем поработать.
Отдельно я не упоминал ИИ-инструменты, хотя использовал их при написании кода, поиске ошибок и проверке решений. Думаю, многие разработчики уже включили их в свой рабочий процесс. Когда под рукой есть Claude или Codex, часть рутины вполне можно поручить им, а самому сосредоточиться на архитектуре, поведении приложения и проверке результата.
Лично я использую Codex и постоянно расширяю собственный набор навыков — skills — для разных задач. Skills - это инструкции и справочные материалы, которые помогают агенту учитывать особенности конкретного стека и проекта. Так например для этой игры я подготовил отдельный навык для работы с TON. Конечно, наличие такого помощника не отменяет необходимости понимать код, проверять расчёты и тестировать платежи. Но времени на рутинных задачах он экономит немало.
В общем, все исходники и документация проекта доступны в публичном репозитории, а саму игру можно попробовать в FUN-режиме. Если найдёте ошибки, захотите предложить улучшения или поделиться своим опытом — буду рад обратной связи.
Ну и напоследок
Как я писал в начале статьи, я пока еще выбираюсь из финансового кризиса и пытаюсь понять, куда двигаться дальше. Найти хорошую работу программистом, как вы знаете, сейчас очень непросто, а для развития собственного дела нужна финансовая подушка, которой у меня, к сожалению, пока нет.
Поэтому, если вам близко то, чем я занимаюсь, и вам вдруг нужен специалист или партнёр, буду рад обсудить сотрудничество. Сейчас я рассматриваю любые варианты, как разовые проекты, так и долгосрочные контракты.
Конечно, в будущем мне хотелось бы развивать собственную студию небольших мобильных Web3-игр с монетизацией через криптотокены. Я считаю такую связку очень перспективной — никаких традиционных платёжных систем и банковского эквайринга. Думаю, преимущества криптовалют в этом контексте вам и так очевидны, особенно в нынешнее непростое время.
Так что смотрю вперёд с оптимизмом и буду рад вашим предложениям! Пишите в личку на Хабре, в Telegram или WhatsApp. А некоторые из моих работ можно посмотреть в портфолио на Dribbble.
Ну вот теперь всё :-)
