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 днів.