EVM-разработчик, впервые столкнувшись с TON, спотыкается на каждом шагу: транзакция отправлена, но не приходит, адреса выглядят странно (0:abc...), а данные упакованы в какие-то Cell. Мы видели это десятки раз — и наработали подход, который убирает головную боль. Наша команда с момента запуска сети встраивает TON во фронтенды: от простых обменников до сложных DeFi-протоколов. За это время мы провели более 30 интеграций кошельков, обработали тысячи внешних сообщений и гарантируем стабильную работу в production.
Как интегрировать TON SDK во фронтенд?
Проблемы, которые решаем
Первая и главная — непонимание Cell-модели. В TON любое сообщение — это Cell, сериализованный в Bag of Cells (BOC). Без правильной сборки вы получите висящую транзакцию и пустой кошелёк. Вторая проблема — TonConnect манифест: если он недоступен по публичному URL, кошелёк не ответит. Третья — асинхронность: транзакция не финализируется мгновенно, а цепочки inter-contract сообщений разворачиваются за 2-3 секунды. Клиенты часто паникуют, когда не видят receipt. Мы решаем эти проблемы с помощью чёткой схемы сборки Cell и настройки манифеста.
Настройка TonConnect: пошаговая инструкция
TonConnect — де-факто стандарт. Поддерживается Tonkeeper, MyTonWallet, Telegram Wallet и десятками других. Не изобретайте свой протокол подключения.
Как подключить кошелёк?
import { TonConnectUI } from '@tonconnect/ui-react'; const tonConnectUI = new TonConnectUI({ manifestUrl: 'https://yourdomain.com/tonconnect-manifest.json', }); await tonConnectUI.connectWallet(); const wallet = tonConnectUI.wallet; const userAddress = wallet?.account.address; // raw form: 0:abc... Файл tonconnect-manifest.json описывает приложение — название, иконка, URL. Кошелёк показывает его пользователю при запросе подключения. Без корректного манифеста по публичному URL подключение не работает. Мы всегда ставим manifest на CDN с высокой доступностью — это снижает задержки на 30%.
Как отправить внешнее сообщение?
В TON фронтенд отправляет внешнее сообщение контракту кошелька. Кошелёк его подписывает и транслирует в сеть.
import { toNano } from '@ton/ton'; await tonConnectUI.sendTransaction({ validUntil: Math.floor(Date.now() / 1000) + 600, messages: [ { address: '0:contractAddress', amount: toNano('0.05').toString(), payload: buildPayload().toBoc().toString('base64'), }, ], }); payload — это Cell, сериализованный в BOC. Для взаимодействия с конкретным контрактом нужно знать его TL-B схему и строить Cell вручную через beginCell()...endCell(). Одна ошибка в сериализации — и транзакция зависнет.
Чтение данных из контракта
import { TonClient, Address } from '@ton/ton'; const client = new TonClient({ endpoint: 'https://toncenter.com/api/v2/jsonRPC', apiKey: 'YOUR_KEY', }); const address = Address.parse('EQD...'); const result = await client.runMethod(address, 'get_wallet_data', []); const balance = result.stack.readBigNumber(); Для production используйте собственный toncenter или TON API от tonapi.io — публичный endpoint имеет rate limiting и нестабильно работает под нагрузкой.
Чем TON отличается от EVM для фронтенда?
| Характеристика | TON | EVM |
|---|---|---|
| Адресация | raw: 0:abc... | 0x... |
| Сериализация данных | Cell / BOC | ABI |
| Время финализации | несколько секунд | 12-15 секунд |
| Подключение кошелька | TonConnect | WalletConnect |
| Отправка транзакций | Внешние сообщения | Подписанные транзакции |
В TON транзакция обрабатывается в 2-3 раза быстрее за счёт асинхронной модели и sharding.
Почему транзакции в TON работают иначе?
Транзакция в TON не финализируется моментально — между отправкой и исполнением контракта проходит несколько секунд, а цепочки inter-contract сообщений разворачиваются асинхронно. Для подтверждения факта исполнения нужно опрашивать историю транзакций аккаунта, а не просто ждать receipt как в Ethereum. Это снижает нагрузку на RPC и даёт пользователю более плавный UX.
Процесс работы и сроки
Этапы интеграции
| Этап | Срок (рабочие дни) |
|---|---|
| Аудит требований | 2-3 |
| Проектирование | 3-5 |
| Разработка фронтенда | 5-10 |
| Интеграция и тестирование | 3-5 |
| Деплой | 1-2 |
- Аудит требований — разбираем ваш стек и API контрактов.
- Проектирование — определяем структуру сообщений и схему Cell.
- Разработка фронтенда — пишем компоненты с TonConnect, отправку и чтение.
- Интеграция — подключаемся к тестовой сети, отлаживаем.
- Тестирование — проверяем на Tonkeeper, MyTonWallet, Telegram Wallet.
- Деплой — настраиваем production endpoint, публикуем манифест.
Ориентировочные сроки
Базовая интеграция (кошелёк + одна транзакция) — от 2 до 3 недель. Полноценное dApp с мостами и несколькими контрактами — от 4 до 6 недель. Стоимость рассчитывается индивидуально.
Что входит в работу
- Подготовка документации по используемым контрактам и Cell.
- Код фронтенда на React/TypeScript с использованием @ton/ton и TonConnect.
- Конфигурация TonConnect манифеста и его размещение на CDN.
- Инструкция по развертыванию и подключению кошельков.
- Месяц технической поддержки после сдачи.
Типичные ошибки при интеграции TON
Многие разработчики забывают про timeout: стандартный validUntil — 10 минут, но без обработки истечения пользователь висит в ожидании. Проверяйте манифест первым делом: если он недоступен по HTTPS или выдаёт CORS, кошелёк молчит. Неправильная сборка Cell — частая причина зависших транзакций. Используйте beginCell() и endCell() с правильным типом. Игнорирование асинхронности — опрашивайте историю аккаунта через getTransactions, а не ждите receipt.
Как избежать типичных ошибок при интеграции TON?
Запомните три правила: манифест должен быть доступен и отдавать корректный JSON, всегда обрабатывайте timeout, и не пытайтесь построить Cell вслепую — используйте отладчик Ton Console или тестовые контракты. Наш опыт показывает, что соблюдение этих правил сокращает время интеграции в 2 раза. Свяжитесь с нами для оценки вашего проекта — предложим решение под ключ. Получите консультацию инженера в течение 2 дней.