Conversor de Endereço TON – Raw ↔ Bounceable (EQ) e Non-Bounceable (UQ)

O que é um conversor de endereço TON?

Um conversor de endereço TON traduz uma conta da The Open Network entre sua forma raw (workchain:hash, por exemplo 0:83df…31a8) e as formas user-friendly definidas na documentação de endereços da TON: uma estrutura de 36 bytes com flags, workchain, hash e checksum CRC16, codificada em base64 nas conhecidas strings de 48 caracteres EQ… (bounceable) e UQ… (non-bounceable). Todas as formas identificam a mesma conta de contrato inteligente; elas diferem apenas em como o remetente é instruído a tratá-la.

Anatomia de um endereço user-friendly

Bytes	Campo	Significado
0	Tag	0x11 bounceable, 0x51 non-bounceable; some 0x80 para somente testnet (0x91, 0xD1)
1	Workchain	0x00 basechain, 0xFF masterchain (-1 como byte com sinal)
2–33	Hash da conta	SHA-256 do estado inicial do contrato (código + dados)
34–35	CRC16	CRC-16/XMODEM sobre os bytes 0–33, big-endian

O base64 de 36 bytes tem exatamente 48 caracteres sem preenchimento, e é por isso que todo endereço TON user-friendly tem o mesmo comprimento. Os dois primeiros caracteres vêm do tag e dos bits superiores do byte de workchain: EQ e UQ para o workchain 0 da mainnet, Ef e Uf para a masterchain, kQ e 0Q para testnet.

Exemplo prático

Tome o endereço raw 0:83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8. Prefixe o tag 0x11 e o workchain 0x00, acrescente o CRC-16/XMODEM desses 34 bytes e codifique em base64url: o resultado é a forma bounceable EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N. Trocar o tag para 0x51 muda o primeiro caractere e o checksum, resultando em UQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqEBI. Os 43 caracteres do meio são idênticos porque o hash é idêntico. Cole qualquer uma das duas strings acima e a ferramenta recupera a forma raw e mostra as quatro variantes.

Bounceable ou non-bounceable: qual usar

Enviar para uma pessoa. Use a forma non-bounceable UQ…. Se o contrato da carteira dela ainda não foi implantado (uma carteira recém-criada), uma transferência bounceable voltaria e ela não receberia nada.
Chamar um contrato inteligente. Use a forma bounceable EQ…. Se a chamada falhar, o contrato devolve a mensagem e os TON retornam para você, descontadas as taxas, em vez de ficarem presos.
Depósitos em exchanges. Siga as instruções da exchange, incluindo o memo ou comentário. A forma do endereço não muda o destino, mas o flag muda o que acontece em caso de falha.

Por que a verificação CRC importa

Endereços TON são base64, então um único caractere errado muda o hash silenciosamente, e um hash diferente é uma conta diferente, provavelmente inexistente. O CRC16 pega todo erro de um caractere e a maioria dos erros de vários caracteres. Esta ferramenta se recusa a converter qualquer endereço user-friendly cujo checksum falhe, e nunca adivinha o que você quis dizer. Endereços raw não têm checksum algum, então ao converter um endereço raw o resultado é tão correto quanto o hex que você colou; compare os primeiros e os últimos caracteres com a origem.

Usos típicos

Transformar o endereço raw impresso por um nó, pela API de um explorador ou por um manifesto do TON Connect na forma que uma carteira aceita.
Trocar um endereço bounceable de uma listagem de contratos para a forma non-bounceable antes de enviar para uma carteira nova.
Verificar se um endereço que alguém lhe enviou é uma forma somente de testnet.

Outras ferramentas de endereço neste site: o validador de endereço cripto e o conversor de endereço Tron.

Perguntas frequentes

Qual é a diferença entre endereços TON EQ… e UQ…?

São a mesma conta. EQ… é a forma bounceable (byte de tag 0x11): se o contrato de destino não existe ou rejeita a mensagem, os TON voltam para o remetente. UQ… é non-bounceable (tag 0x51): a transferência é creditada mesmo em uma carteira não inicializada. Os apps de carteira mostram UQ… para receber; EQ… é usado para contratos inteligentes.

Qual forma devo dar a alguém para receber TON?

A forma non-bounceable UQ…, principalmente para uma carteira nova que ainda não enviou nada. Uma transferência bounceable para uma carteira não inicializada volta e o destinatário não recebe nada. Depois que a carteira está implantada, as duas formas funcionam, e a maioria das carteiras modernas cuida dessa escolha por você.

O que é a forma raw 0:…?

O endereço canônico: workchain (0 para a basechain, onde ficam as carteiras, -1 para a masterchain) e o hash de 256 bits do código e dos dados iniciais do contrato, escritos como workchain:hex. Não tem checksum nem flag de bounce, e é por isso que as formas user-friendly existem.

O que significam kQ… e 0Q…?

As mesmas duas formas com o bit de somente testnet (0x80) ligado no byte de tag: kQ… é bounceable de testnet, 0Q… non-bounceable de testnet. Carteiras de mainnet as recusam. O endereço raw subjacente é idêntico ao da mainnet.

Como o checksum do endereço TON é calculado?

A forma user-friendly de 36 bytes é tag (1 byte), workchain (1 byte), hash (32 bytes) e um CRC-16/XMODEM de 2 bytes (polinômio 0x1021, valor inicial 0) sobre os primeiros 34 bytes, depois codificada em base64 ou base64 URL-safe. A ferramenta recalcula o CRC e recusa endereços em que ele não confere.

Por que vejo versões com - _ e com + /?

O base64 padrão usa + e /, o base64 URL-safe usa - e _. Os dois decodificam para os mesmos bytes e os dois são endereços TON válidos. Exploradores e carteiras geralmente mostram a forma URL-safe para que ela possa ser embutida em links; o conversor mostra as duas.