Формат TON-адреса: полное объяснение
У каждого аккаунта в The Open Network одна личность, но несколько равнозначных текстовых представлений. Этот гид показывает, как устроен TON-адрес, что означают префиксы EQ, UQ, kQ и 0Q и почему один и тот же кошелёк может выглядеть совершенно по-разному в разных форматах.
Из чего на самом деле состоит TON-адрес
TON-адрес — это пара значений: идентификатор workchain, указывающий, в какой цепочке живёт аккаунт, и 256-битный идентификатор аккаунта, определяющий контракт в этой цепочке. Мастерчейн — это workchain -1, но практически все кошельки и токены, с которыми вы столкнётесь, находятся в basechain, то есть в workchain 0.
Raw-формат
Raw-формат записывает эту пару буквально: workchain:account_id, где идентификатор аккаунта указан в шестнадцатеричном виде в нижнем регистре. В нём нет ни контрольной суммы, ни флагов сети и bounceable, поэтому его используют в коде, API и обозревателях, а не в общении с людьми.
0:83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8Удобочитаемый формат
Удобочитаемый формат упаковывает тот же аккаунт в 36 байт и кодирует их 48 символами base64. Именно дополнительные байты делают адрес безопасным для копирования: контрольная сумма ловит опечатки, а байт флагов хранит сеть и признак bounceable.
| Часть | Размер | Значение |
|---|---|---|
| Байт флагов | 1 | 0x11 для bounceable, 0x51 для non-bounceable; прибавьте 0x80, чтобы пометить адрес как только для testnet. |
| Workchain | 1 | 0x00 для basechain, 0xFF для мастерчейна. |
| Идентификатор аккаунта | 32 | 256-битный идентификатор аккаунта — то же значение, что и шестнадцатеричная половина raw-адреса. |
| Контрольная сумма | 2 | CRC-16 по предыдущим 34 байтам. Именно она делает адрес с опечаткой мгновенно невалидным. |
Что означают префиксы EQ, UQ, kQ и 0Q
Первые два символа удобочитаемого адреса — это прямое отражение байта флагов и workchain, поэтому сеть и признак bounceable видно сразу, без всякого декодирования.
| Префикс | Сеть | Bounceable | Workchain | Типичное применение |
|---|---|---|---|---|
| EQ | Mainnet | Да | Basechain (0) | Смарт-контракты и обозреватели — всё, что должно вернуть средства при неудачной доставке. |
| UQ | Mainnet | Нет | Basechain (0) | Кошельки и депозиты на биржах. Самый безопасный вариант для обычного получения TON. |
| kQ | Testnet | Да | Basechain (0) | Bounceable-адрес в testnet, используется при разработке и тестировании контрактов. |
| 0Q | Testnet | Нет | Basechain (0) | Non-bounceable-адрес в testnet, используется для тестовых кошельков. |
| Ef | Mainnet | Да | Мастерчейн (-1) | Bounceable в мастерчейне — валидаторы и системные контракты. |
| Uf | Mainnet | Нет | Мастерчейн (-1) | Non-bounceable в мастерчейне — редко встречается вне инфраструктуры. |
Примеры TON-адресов
Все пять строк ниже — это один и тот же аккаунт, записанный во всех форматах, которые поддерживает TON. Обратите внимание: меняются только первые два символа и контрольная сумма в конце, а середина адреса остаётся неизменной, потому что идентификатор аккаунта не меняется.
| Формат | Пример |
|---|---|
| Raw | 0:83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8 |
| Bounceable (EQ) | EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N |
| Non-bounceable (UQ) | UQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqEBI |
| Testnet bounceable (kQ) | kQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqKYH |
| Testnet non-bounceable (0Q) | 0QCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqPvC |
Правила кодирования, о которых стоит знать
- Удобочитаемый TON-адрес всегда состоит ровно из 48 символов. Если ваш короче или длиннее — это не валидный TON-адрес.
- Base64 чувствителен к регистру. EQCD… и eqcd… — разные строки, и проверку проходит только точный регистр.
- В обиходе два алфавита: обычный base64 использует + и /, а URL-safe base64 заменяет их на - и _. Оба декодируются в один и тот же аккаунт, и инструменты TON предпочитают URL-safe вариант.
- У raw-формата нет контрольной суммы, поэтому опечатку никто за вас не поймает. Всегда проверяйте raw-адрес перед отправкой средств.
Как конвертировать TON-адрес
- Вставьте один или несколько адресов в конвертер. Подходят raw, EQ, UQ, kQ и 0Q, а список можно вставить целиком, разделив пробелами или переносами строк.
- Сравните все равнозначные формы рядом — bounceable, non-bounceable, raw и нормализованную, а также пару testnet, если включить её.
- Скопируйте нужную форму или скачайте всю таблицу в CSV. Ничего не покидает браузер: конвертация выполняется локально.
Частые проблемы с адресами
- В кошельке UQ, а в обозревателе EQ
- Это один и тот же аккаунт. Обозреватели обычно показывают bounceable-форму EQ, а кошельки для пополнения — non-bounceable-форму UQ. Сконвертируйте любую из них и сравните raw-адреса, чтобы убедиться в совпадении.
- Биржа отклонила мой TON-адрес
- Большинство бирж ждут для депозита non-bounceable-форму UQ основной сети. Bounceable-адрес EQ может привести к возврату перевода, если контракт-получатель ещё не задеплоен.
- Почему testnet-адрес не работает в основной сети?
- У адреса kQ или 0Q установлен флаг «только testnet», поэтому кошельки основной сети его отклоняют. Идентификатор аккаунта при этом тот же — сконвертируйте адрес в форму EQ или UQ, чтобы использовать тот же аккаунт в mainnet.
- Адрес кошелька Telegram — это TON-адрес?
- Да. Telegram Wallet, Tonkeeper и другие TON-кошельки используют один и тот же формат адреса; различается только форма отображения в приложениях.