Интеграция TON Connect для TON-приложений в мобильном кошельке

Интеграция TON Connect для TON-приложений в мобильном кошельке

TON Connect — протокол связи между dApp и кошельком в экосистеме TON Blockchain. В отличие от WalletConnect (EVM-мир), здесь собственный протокол поверх HTTP bridge с push-уведомлениями через SSE. Реализация в мобильном приложении требует понимания не только SDK, но и того, как работает транспортный уровень.

Как устроен транспорт TON Connect

Протокол работает через bridge-сервер (bridge.tonapi.io или самостоятельно развёрнутый). Кошелёк и dApp обмениваются зашифрованными сообщениями через этот bridge — прямого соединения нет. Шифрование — NaCl box (X25519 + XSalsa20-Poly1305).

Мобильное приложение-кошелёк подключается к bridge через SSE (Server-Sent Events): GET /bridge/{clientId}/events. Это долгоживущий HTTP-запрос, который держит соединение открытым. На iOS — проблема: URLSession не поддерживает SSE нативно, нужна библиотека EventSource или кастомная реализация через URLSessionDataDelegate. На Android с OkHttp — тоже нет встроенной поддержки SSE, но EventSource от OkHttp team (com.squareup.okhttp3:okhttp-sse) решает задачу.

Альтернативный транспорт — deeplink. dApp кодирует tc:// или https://ton.app/... ссылку, пользователь кликает, кошелёк открывается и получает connect request из URL-параметров. Это синхронный flow без bridge — работает проще, но требует, чтобы dApp и кошелёк были на одном устройстве.

Обработка connect request в кошельке

При получении запроса на подключение кошелёк должен:

1. Декодировать ConnectRequest из зашифрованного payload (или из deeplink-параметра r).
2. Показать пользователю: какой dApp запрашивает подключение, какие items нужны (ton_addr, ton_proof).
3. Получить одобрение пользователя.
4. Сформировать ConnectResponse с адресом кошелька, сетью (mainnet/testnet), публичным ключом и ton_proof если запрошен.

ton_proof — криптографическое доказательство владения кошельком без подписания транзакции. Формат: ton-proof-item-v2/<wc>:<addr_bytes>/<app_domain>/<timestamp>/<payload>. Подписывается приватным ключом кошелька через Ed25519. dApp верифицирует подпись через TON API, не доверяя кошельку на слово.

Типичная ошибка реализации: неправильная сериализация addr_bytes — нужен raw-формат (workchain + 32 байта hash), не user-friendly bounce/non-bounce адрес.

Подписание транзакций

После подключения dApp отправляет SendTransactionRequest с BOC (Bag of Cells) — бинарным представлением транзакции TON. Кошелёк:

1. Декодирует BOC через ton-core или @ton/ton.
2. Показывает детали транзакции пользователю: получатель, сумма, комментарий.
3. Подписывает транзакцию приватным ключом.
4. Отправляет подписанный BOC в TON сеть через tonapi.io или toncenter.com.
5. Возвращает SendTransactionResponse с хэшем транзакции dApp.

Декодирование BOC для отображения в UI — нетривиальная задача. BOC может содержать вызовы смарт-контрактов с произвольными payload'ами. Для стандартных jetton-переводов есть парсер OP-кодов (0xf8a7ea5 — jetton transfer), для остального — показываем raw hex и предупреждение.

TON Connect SDK для мобиля

Официальный @tonconnect/sdk написан для JavaScript/TypeScript — в React Native работает с полифиллами (react-native-crypto, buffer). Для нативных платформ официального SDK нет — реализуем протокол самостоятельно по спецификации или используем community-библиотеки (TonSdk.NET для MAUI, ton-kotlin для Android).

Tonkeeper — открытый исходный код, отличный референс для понимания реальной реализации TON Connect на мобиле.

Сроки

Интеграция TON Connect в существующий кошелёк (только подключение и подпись транзакций) — 3–5 недель. Полноценный TON-кошелёк с нуля (управление seed, деривация ключей, jetton-поддержка, NFT, staking) — от 4 до 6 месяцев.