Пошаговый туториал: вы создадите и задеплоите минимальный смарт-контракт для Telegram Mini App на TON и подключите его из JavaScript. Время выполнения: 90–150 минут.
Статья была полезной?
В конце вы получите рабочий контракт на TON, связанный с Telegram Mini App, и пример JavaScript-интеграции для вызова кошелька. Примерное время выполнения — 90–150 минут при наличии Node.js и 8 ГБ ОЗУ.
TON обеспечивает низкую латентность транзакций (подтверждение транзакции в пределах 1–3 секунд на тестнете, данные по сети — 2025). Платформа оптимизирована для масштабирования и интегрирована с инфраструктурой Telegram, что упрощает исполнение платежей и хранения state напрямую через кошельки Telegram — Tonkeeper, Surf и встроенные решение Telegram Wallet (релизы 2024–2026). Для mini-app важны: маленькие комиссии (ниже $0.001 в большинстве сценариев на 2025), быстрый finality и возможность подписывать транзакции из Web App внутри Telegram.
Выбор языка: Tact упрощает разработку контрактов (приближён к Rust/TS по синтаксису), FunC даёт максимальный контроль над байт-кодом. Для первого контракта рекомендую Tact 0.8.1 (релиз 2025). Ниже показан процесс установки Tact и компиляции минимального контракта.
Команда (установка Tact CLI, Ubuntu 22.04):
curl -fsSL https://github.com/tonlabs/tact/releases/download/v0.8.1/tact-linux-x86_64 -o /usr/local/bin/tact
chmod +x /usr/local/bin/tact
tact --versionПояснение: скачиваем бинарник Tact 0.8.1 (размер ~12 MB), делаем исполняемым и проверяем версию.
Ожидаемый вывод:
$ tact --version
tact 0.8.1 (2025-11-03)Типовая ошибка и фикс:
Ошибка: bash: tact: команда не найдена
Фикс: убедитесь, что /usr/local/bin в PATH. Выполните: export PATH=$PATH:/usr/local/bin и повторите.
Если проблема с правами: sudo mv tact /usr/local/bin && sudo chmod +x /usr/local/bin/tactСоздадим минимальный контракт на Tact (контракт счётчика):
// файл Counter.tact
contract Counter {
var value: int;
constructor() {
value = 0;
}
public function increment(): int {
value = value + 1;
return value;
}
}
// компиляция
tact compile Counter.tact -o build/Counter.tvcОжидаемый вывод при компиляции (~2–5 секунд):
$ tact compile Counter.tact -o build/Counter.tvc
Compiling Counter.tact...
Success: build/Counter.tvc (tvc size: 1.8 KB)Типичная ошибка и фикс:
Ошибка: Cannot find target 'tactc'
Фикс: проверьте версию Tact и корректность установки. Если ошибка связана с отсутствием зависимостей, установите clang и build-essential: sudo apt install -y clang build-essentialДля интеграции с Telegram Mini App нужен кошелёк, который может подписывать сообщения/транзакции. Используем стандартный контракт Wallet V3 (универсальный в 2025). Скачайте готовый Wallet V3 ABI и TVC из официального репозитория TON.
Команды (скачивание и проверка):
curl -fsSL https://github.com/tonlabs/ton-contracts/releases/download/v2025-05/wallet_v3.tvc -o wallet_v3.tvc
sha256sum wallet_v3.tvcОжидаемый вывод:
$ sha256sum wallet_v3.tvc
3f9c... wallet_v3.tvc
(файл размер ~8.2 KB)Типичная ошибка и фикс:
Ошибка: 404 Not Found при скачивании
Фикс: проверьте URL или версию релиза. Альтернатива — собрать Wallet V3 локально по инструкции в репозитории tonlabs/ton-contracts.Деплой кошелька на тестнет (используем tondev или tonos-cli; пример с tonos-cli 1.0.4, релиз 2025):
tonos-cli init
tonos-cli deploy wallet_v3.tvc --abi wallet_v3.abi.json --sign key.json --wc 0Пояснение: команда деплоит TVC на тестовую сеть и возвращает адрес кошелька. Время выполнения — 5–20 секунд в зависимости от сети.
Ожидаемый вывод:
$ tonos-cli deploy ...
Deploy transaction sent: 0:abcd1234...
Transaction confirmed in block 456789 (time ~3s)
Deployed at address: 0:eea1f2... (workchain 0)Типичная ошибка и фикс:
Ошибка: Transaction rejected: out of gas
Фикс: увеличьте деплой-гас лимит или предварительно пополните кошелёк адреса deployer. Пример: tonos-cli run --abi wallet_v3.abi.json sendGrams 1000000000Telegram Mini App работает в WebView и предоставляет Web Apps API. Для работы с TON из mini-app используйте tonweb 0.14.0 и интеграцию с Telegram Wallets через deeplink/peer-to-peer API. В примере ниже показано, как запросить подпись транзакции и отправить её в сеть через TonCenter API (2026).
Установка зависимостей (Node.js 18.16.0):
npm init -y
npm install tonweb@0.14.0 axios@1.4.0Ожидаемый вывод (~5–8 секунд):
+ tonweb@0.14.0
+ axios@1.4.0
added 54 packages from 30 contributors and audited 54 packages in 6.8sТипичная ошибка и фикс:
Ошибка: Unsupported engine for tonweb
Фикс: используйте Node.js 18.x. Проверьте 'node -v'. Если версия ниже — установите nvm и переключитесь: nvm install 18 && nvm use 18Пример кода для мини-приложения в Telegram (app.js):
import TonWeb from 'tonweb'
import axios from 'axios'
const tonweb = new TonWeb(new TonWeb.HttpProvider('https://toncenter.com/api/v2/jsonRPC'))
// пример: формируем тело транзакции для вызова Counter.increment
async function callIncrement(counterAddress) {
// формирование транзакции зависит от ABI, здесь упрощённый пример
const messageBody = "0x..." // payload из ABI/compile
// запрос подписи у кошелька внутри Telegram
// Telegram Web Apps: Telegram.WebApp.openInvoice / Telegram.WebApp — но для подписи используем deeplink на Tonkeeper
const deeplink = `ton://transfer/${counterAddress}?amount=0&text=call:${messageBody}`
window.open(deeplink)
// после подписи транзакция появится в сети; можно опросить TonCenter за hash
const txHash = await pollTxHash(counterAddress)
return txHash
}
async function pollTxHash(address) {
for (let i = 0; i < 20; i++) {
const res = await axios.get(`https://toncenter.com/api/v2/getTransactions?address=${address}`)
if (res.data && res.data.result && res.data.result.length) return res.data.result[0].hash
await new Promise(r => setTimeout(r, 2000))
}
throw new Error('tx not found in timeout')
}Ожидаемый результат (после подписи кошельком, 3–10 секунд):
Запрос открыл Tonkeeper, пользователь подтвердил транзакцию.
В ответ TonCenter через poll вернул tx hash: 0x9a7f...Типичная ошибка и фикc:
Ошибка: CORS / blocked by client when opening deeplink
Фикс: используйте window.open с target '_blank' и корректные deep link форматы; при интеграции в Telegram Web App предпочтительней использовать Telegram Wallet API или Tonkeeper JS SDK, если доступен в WebView.После компиляции Counter.tact нужно создать транзакцию установки контракта и задеплоить его с адреса кошелька, полученного на шаге 2. Используем tonos-cli 1.0.4 (релиз 2025) и TonCenter API для проверки состояния.
Команды деплоя:
# формируем ключи, если их нет
tonos-cli genkeypair key.json
# deploy
tonos-cli deploy build/Counter.tvc --abi build/Counter.abi.json --sign key.json --wc 0Ожидаемый вывод (10–25 секунд):
$ tonos-cli deploy ...
Deploy transaction sent: 0:bf12...
Transaction confirmed in block 458012 (time ~4s)
Deployed at address: 0:aa11bb...
Contract state: activeТипичная ошибка и фикс:
Ошибка: Action rejected: account not exist
Фикс: проверьте, что адрес deployer содержит достаточное количество граммов. Пополните кошелёк и повторите (пример: transfer с Faucet на тестнете или через TonCenter тестнет фаусет). Также проверьте workchain id (wc).Проверка функций контракта (local call):
tonos-cli call increment --abi build/Counter.abi.json --sign key.jsonОжидаемый вывод:
Call succeeded. Output: { "value": 1 }Типичная ошибка и фикс:
Ошибка: ABI mismatch or invalid function
Фикс: убедитесь, что ABI соответствует скомпилированному TVC. Если вы компилировали через Tact, используйте tact export-abi для получения актуального ABI.Автоматизация: используйте ton-sdk + jest или интеграционные тесты в GitHub Actions. Пример workflow с Node.js 18, запуск сборки Tact и unit тестов через tonos-cli и tondev. CI должен проверять компиляцию и локальные вызовы.
Пример .github/workflows/ci.yml (упрощённо):
name: CI
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
- name: Set up Node
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install tact
run: |
curl -fsSL https://github.com/tonlabs/tact/releases/download/v0.8.1/tact-linux-x86_64 -o tact
chmod +x tact
./tact --version
- name: Compile
run: ./tact compile Counter.tact -o build/Counter.tvc
- name: Run tests
run: npm ci && npm run testОжидаемый вывод CI (пример):
tact 0.8.1 (2025-11-03)
Compiling Counter.tact...
Success: build/Counter.tvcТипичная ошибка и фикс:
Ошибка: step "Install tact" failed due to permission denied
Фикс: используйте chmod +x tact и переместите в /usr/local/bin через sudo; в CI помните, что контейнеры могут иметь ограничения. Добавьте sudo при mv, если нужно.Примеры реальных сценариев, где Telegram Mini App + TON дают преимущество: микроплатежи за доступ к контенту (pay-per-view), внутриигровые покупки с мгновенным подтверждением, бот-маркетплейсы с escrow-контрактами, обещанные транзакции и NFT-эмиссия напрямую из мини-приложения. На 2025–2026 годы ценность — в быстрой оплачиваемой интерактивности: торговые предложения, голосования с оплатой и микроплатежи за уникальные ответы бота. TON позволяет снизить стоимость каждой операции до тысячной доли цента и обеспечивает скорость, необходимую для UX внутри WebView.
UX внутри Telegram Mini App должен учитывать три аспекта: поток подписи, обработка состояния транзакции и fallback-пути. Пользователь должен понимать, что происходит после нажатия кнопки «оплатить/подписать»: показывать индикатор ожидающей подписи, открывать wallet deeplink и информировать о результате транзакции. Важно: Web App не всегда возвращает управление мгновенно. Рекомендуемые задержки и таймауты — ожидание 3–10 секунд для подтверждения, общий таймаут polling 40–60 секунд. Если кошелёк не возвращает статус — предложите повторную проверку или предоставьте ссылку на просмотр транзакции по hash в TonScan или аналогичном обозревателе.
Консоль: компиляция Tact и деплой в терминале
Скриншот Telegram Mini App: подтверждение транзакции Tonkeeper
Для чтения смежных материалов по CI и инфраструктуре переходите в разделы: DevOps и для разработчиков Web3: Web3. Эти материалы помогут настроить деплой и мониторинг в продакшн.
Выбор зависит от требований к контролю над байт-кодом и скорости разработки. Tact (версия 0.8.1, 2025) подходит для большинства приложений — он компилируется в оптимизированный FunC и сокращает время разработки за счёт типизации и знакомого синтаксиса. FunC (релиз 0.20, 2025) даёт более детальный контроль, полезен для микрооптимизаций и когда необходимо уменьшить итоговый размер TVC. Для прототипа выбирайте Tact; для оптимизации газа и точного контроля — FunC.
Сначала проверьте, верно ли сформирован payload и что подпись прошла успешно (проверьте возвращаемые данные кошелька). Затем опросите публичный API (TonCenter, TonScan) за адресом и tx hash. Если транзакция не найдена — проверьте баланс кошелька (nsufficient balance) и ограничения gas. В мобильных WebView проблема может быть в том, что deeplink открывает приложение кошелька, но callback в WebView не срабатывает — реализуйте fallback polling и объясните пользователю шаги вручную.
Telegram Mini App запускается в WebView с ограничениями политики безопасности. Многие публичные узлы TON имеют CORS-политику, которая блокирует прямые вызовы с вашего домена. Решение: использовать собственный прокси на сервере (server-side) или серверный компонент, который будет обращаться к TonCenter и возвращать данные в mini-app. Это также позволяет скрыть API-ключи и управлять rate-limits.
Wallet V3 — это стандартный контракт кошелька, совместимый с популярными кошельками вроде Tonkeeper и Surf. Наличие готового TVC и ABI позволяет быстро создавать адреса и взаимодействовать программно. Tonkeeper — клиент и поставщик UX; Wallet V3 гарантирует совместимость, а Tonkeeper обеспечивает удобный пользовательский интерфейс и подпись транзакций. Используйте Wallet V3 для совместимости и обеспечения возможности восстановления ключей по seed.
Стоимость зависит от нагрузки: комиссия за транзакцию в типичных сценариях на TON в 2025–2026 составляет менее $0.001. Основные расходы — серверная часть для проксирования запросов, storage и мониторинг, а также расходы на CI/CD. При средней активности (несколько тысяч транзакций в день) месячные расходы на инфраструктуру начинаются от $50–200 на облаке, при использовании минимальной архитектуры с одним сервером для прокси и логирования. Для точной оценки промоделируйте трафик и количество транзакций за период.
Комментарии (0)
Войдите или зарегистрируйтесь, чтобы оставить комментарий
Загрузка комментариев…