Конвертер TON-адресов – Raw ↔ Bounceable (EQ) и Non-Bounceable (UQ)

Что такое конвертер TON-адресов?

Конвертер TON-адресов переводит один аккаунт в The Open Network между его сырой формой (workchain:hash, например 0:83df…31a8) и удобными формами, определёнными в документации TON по адресам: 36-байтовая структура из флагов, workchain, хеша и контрольной суммы CRC16, закодированная в base64 в знакомые 48-символьные строки EQ… (bounceable) и UQ… (non-bounceable). Все формы обозначают один и тот же аккаунт смарт-контракта; они различаются лишь тем, как отправителю предписано с ним обращаться.

Строение удобного адреса

Байты	Поле	Значение
0	Тег	0x11 bounceable, 0x51 non-bounceable; +0x80 для варианта только тестовой сети (0x91, 0xD1)
1	Workchain	0x00 basechain, 0xFF masterchain (-1 как знаковый байт)
2–33	Хеш аккаунта	SHA-256 начального состояния контракта (код + данные)
34–35	CRC16	CRC-16/XMODEM над байтами 0–33, big-endian

Base64 от 36 байт — это ровно 48 символов без дополнения, поэтому у всех удобных TON-адресов одинаковая длина. Первые два символа определяются тегом и старшими битами байта workchain: EQ и UQ для workchain 0 в mainnet, Ef и Uf для masterchain, kQ и 0Q для тестовой сети.

Пример

Возьмём сырой адрес 0:83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8. Добавим спереди тег 0x11 и workchain 0x00, допишем CRC-16/XMODEM этих 34 байт и закодируем в base64url: получаем bounceable-форму EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N. Замена тега на 0x51 меняет первый символ и контрольную сумму, давая UQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqEBI. 43 средних символа идентичны, потому что идентичен хеш. Вставьте любую из строк выше — инструмент восстановит сырую форму и покажет все четыре варианта.

Bounceable или non-bounceable: что использовать

Перевод человеку. Используйте non-bounceable форму UQ…. Если контракт его кошелька ещё не развёрнут (совсем новый кошелёк), bounceable-перевод вернётся обратно, и получатель ничего не получит.
Вызов смарт-контракта. Используйте bounceable форму EQ…. Если вызов завершится ошибкой, контракт вернёт сообщение, и TON вернутся вам за вычетом комиссии, а не застрянут.
Депозиты на биржу. Следуйте инструкциям биржи, включая memo или комментарий. Форма адреса не меняет получателя, но флаг меняет то, что произойдёт при ошибке.

Почему важна проверка CRC

TON-адреса записаны в base64, поэтому один неверный символ незаметно меняет хеш, а изменённый хеш — это другой, скорее всего несуществующий, аккаунт. CRC16 ловит любую одиночную ошибку и большинство многосимвольных. Этот инструмент отказывается преобразовывать любой удобный адрес с неверной контрольной суммой и никогда не угадывает, что вы имели в виду. У сырых адресов контрольной суммы нет вовсе, поэтому при преобразовании сырого адреса результат верен ровно настолько, насколько верен вставленный hex; сравните первые и последние символы с источником.

Типичные применения

Перевод сырого адреса, выданного нодой, API обозревателя или манифестом TON Connect, в форму, которую принимает кошелёк.
Переключение bounceable-адреса из листинга контрактов в non-bounceable форму перед отправкой на новый кошелёк.
Проверка, не является ли присланный вам адрес формой только для тестовой сети.

Другие инструменты для адресов на этом сайте: валидатор крипто-адресов и конвертер Tron-адресов.

Часто задаваемые вопросы

В чём разница между TON-адресами EQ… и UQ…?

Это один и тот же аккаунт. EQ… — bounceable-форма (байт тега 0x11): если контракт назначения не существует или отклоняет сообщение, TON возвращаются отправителю. UQ… — non-bounceable (тег 0x51): перевод зачисляется даже на неинициализированный кошелёк. Приложения-кошельки показывают UQ… для получения; EQ… используется для смарт-контрактов.

Какую форму дать человеку, чтобы получить TON?

Non-bounceable форму UQ…, особенно для нового кошелька, который ещё ничего не отправлял. Bounceable-перевод на неинициализированный кошелёк возвращается обратно, и получатель ничего не получает. После развёртывания кошелька работают обе формы, и большинство современных кошельков делают выбор за вас.

Что такое сырая форма 0:…?

Каноничный адрес: workchain (0 для basechain, где живут кошельки, -1 для masterchain) и 256-битный хеш начального кода и данных контракта, записанные как workchain:hex. У него нет ни контрольной суммы, ни флага bounce — именно поэтому существуют удобные формы.

Что означают kQ… и 0Q…?

Те же две формы с установленным в байте тега битом «только тестовая сеть» (0x80): kQ… — bounceable для тестовой сети, 0Q… — non-bounceable для тестовой сети. Кошельки mainnet их отклоняют. Лежащий в основе сырой адрес идентичен адресу в mainnet.

Как вычисляется контрольная сумма TON-адреса?

36-байтовая удобная форма — это тег (1 байт), workchain (1 байт), хеш (32 байта) и 2-байтовый CRC-16/XMODEM (полином 0x1021, начальное значение 0) над первыми 34 байтами, затем кодирование в base64 или URL-safe base64. Инструмент пересчитывает CRC и отклоняет адреса, где он не совпадает.

Почему я вижу версии и с - _, и с + /?

Стандартный base64 использует + и /, URL-safe base64 — - и _. Обе декодируются в одни и те же байты, и обе являются валидными TON-адресами. Обозреватели и кошельки обычно показывают URL-safe форму, чтобы её можно было встраивать в ссылки; конвертер показывает обе.