Como a STONfi lida com endereços bounceable e non-bounceable na TON
Os endereços TON podem parecer diferentes, ainda assim apontando para a exata mesma conta on-chain.
Um exemplo comum é a diferença entre um endereço que começa com EQ... e um que começa com UQ.... O primeiro é a representação familiar bounceable (com resposta) e amigável ao usuário, enquanto o segundo é a representação non-bounceable (sem resposta). Apesar dos prefixos diferentes, ambos podem identificar a mesma conta TON subjacente porque a conta em si é determinada por seu workchain e pelo identificador da conta de 256 bits. A distinção entre bounceable ou non-bounceable é codificada como metadados na representação amigável ao usuário, em vez de criar uma conta diferente.
Essa distinção se torna especialmente importante ao interagir com protocolos DeFi como o STONfi, em que um único swap pode envolver vários endereços TON e múltiplas camadas de mensagens de contrato.
Entender o que o prefixo do endereço realmente significa torna muito mais fácil entender por que o STONfi consegue funcionar com diferentes representações de endereço sem tratá-las como destinos diferentes.
A Primeira Distinção Importante: Identidade do Endereço vs. Comportamento da Mensagem
A forma mais fácil de entender endereços da TON é separar quem é o destino de como uma mensagem deve se comportar quando é enviada para lá.
Um endereço amigável para usuários da TON contém várias informações. Entre elas estão o identificador do workchain, o identificador da conta e flags que descrevem como o endereço deve ser tratado. Em particular, as flags codificam se uma mensagem deve ser enviada como bounceable ou non-bounceable.
Isso significa que o prefixo visível não é apenas um identificador alternativo de conta.
Por exemplo:
EQ... → representação amigável bounceable
UQ... → representação amigável non-bounceable
Quando o workchain subjacente e o ID da conta são idênticos, estas são duas representações da mesma conta.
As próprias utilidades de endereço da TON podem converter um endereço em suas formas cruas, bounceable e non-bounceable — outra forma de demonstrar que são representações diferentes do mesmo destino subjacente, e não carteiras separadas.
Este é um dos conceitos mais importantes para desenvolvedores que constroem na TON:
Não compare o prefixo visual quando estiver tentando determinar se dois endereços identificam a mesma conta. Analise o endereço e compare os componentes subjacentes do endereço.
O que “Bounceable” realmente significa?
Bounceability é fundamentalmente sobre o tratamento de mensagens.
Mensagens internas da TON carregam uma flag de bounce. Quando uma mensagem bounceable é entregue a um destino e o processamento falha nas condições em que o bounce é suportado, o valor restante pode ser devolvido ao remetente. As diretrizes de contratos inteligentes da TON recomendam mensagens bounceable para a maioria das interações porque fornecem proteção contra certas falhas de destino ou de execução.
O ponto importante é que uma conta não vira permanentemente uma “conta bounceable” ou uma “conta non-bounceable”.
Em vez disso, a representação amigável do endereço contém uma flag que o software pode usar ao construir a mensagem de saída.
A TON documenta os formatos amigáveis da mainnet como:
E... para endereços bounceable
U... para endereços non-bounceable
A mesma conta, portanto, pode ser representada em qualquer uma das formas.
Então, quando alguém muda um endereço de EQ... para UQ..., não moveu fundos, não criou uma segunda carteira e não mudou a própria conta.
Elas mudaram a representação amigável e a preferência de bounce associada.
Por que a TON precisa de endereços non-bounceable?
A resposta fica mais clara quando consideramos a inicialização da conta.
A TON oferece suporte a contas de contratos cujos endereços podem ser determinados antes do contrato correspondente ser implantado. Por exemplo, um contrato de carteira pode ter um endereço determinístico derivado de seus parâmetros de inicialização mesmo antes de a conta ser ativada na blockchain. A documentação da TON descreve explicitamente casos em que um endereço existe como valor determinístico enquanto a conta em si ainda está no estado de inexistência (não existe).
Isso cria um problema importante de financiamento.
Suponha que você queira enviar TON para uma carteira cujo endereço é conhecido, mas cuja conta ainda não foi inicializada. Uma mensagem non-bounceable pode ser usada para financiar esse destino sem que o valor seja devolvido por bounce simplesmente porque a conta ainda não foi inicializada.
É por isso que representações non-bounceable estão especialmente associadas ao financiamento ou à inicialização de carteiras.
A documentação da TON recomenda endereços non-bounceable para contratos de carteira em situações em que o destino possa estar não inicializado, enquanto mensagens bounceable geralmente são preferidas para interações com contratos inteligentes em que falhas na execução devem resultar no valor sendo devolvido.
Carteiras na TON são contratos inteligentes
Outro conceito que às vezes causa confusão é a palavra “carteira”.
Na TON, uma carteira não é apenas um rótulo de conta no mesmo sentido de uma conta de uma exchange centralizada tradicional. Implementações de carteira são contratos inteligentes, e seu endereço pode ser derivado antes do deployment.
É por isso que é possível saber onde uma carteira existirá antes de o contrato da carteira ter sido inicializado de fato na blockchain.
O fluxo de endereços da TON reflete essa distinção. Quando um aplicativo de carteira prepara uma transferência, ele pode inspecionar o estado da conta do destino. A documentação da TON observa que, quando um destino ainda não foi inicializado, o software da carteira pode forçar o campo bounce da mensagem de saída para false, efetivamente preferindo a entrega non-bounceable para cenários de inicialização. Para destinos já inicializados, a carteira pode usar a preferência de bounce representada pelo endereço.
Então, o comportamento prático é mais sofisticado do que simplesmente dizer:
“EQ sempre dá bounce.”
ou
“UQ nunca dá bounce.”
O prefixo fornece uma preferência de tratamento de mensagens, enquanto o aplicativo de carteira e o estado do destino também podem influenciar como a transação é construída.
Onde o STONfi se encaixa neste modelo
Um swap do STONfi não é apenas uma única transferência de uma carteira para outra.
Um swap típico pode envolver vários endereços e várias mensagens:
Sua carteira → contrato/roteador STONfi → contratos de token ou pools → destinos de destinatário/reembolso/excesso
Dependendo da operação, a transação pode envolver endereços para:
Sua carteira conectada
Contratos-mestre de Jetton
Contratos de carteira de Jetton
Roteadores STONfi
Contratos de pool
Endereços do destinatário
Endereços de reembolso
Destinos de excesso
Cada endereço pode aparecer em uma camada diferente da transação.
Isso importa porque o endereço usado como alvo inicial da transação não é necessariamente a mesma coisa que todo endereço carregado dentro do payload do contrato.
Quando uma carteira envia uma transação do TON Connect, por exemplo, a própria mensagem tem um endereço de destino e pode conter um payload arbitrário. A interação com contratos pode então codificar valores adicionais de MsgAddress dentro desse payload. Os exemplos da TON mostram esse padrão para interações de token e NFT, em que uma mensagem de contrato pode conter endereços como um novo proprietário ou um destino de excesso.
Essa é a arquitetura que torna o tratamento de endereços dentro de um swap do STONfi mais interessante do que uma simples transferência de “enviar de A para B”.
O alvo inicial é apenas uma parte da transação
Considere o começo de um swap.
Sua carteira cria uma mensagem de saída cujo destino inicial é o contrato do STONfi que deve receber e processar a requisição.
A carteira, portanto, precisa de um endereço de destino válido para esse contrato.
Dentro do payload da requisição, porém, o protocolo também pode precisar saber para onde os ativos resultantes devem ser entregues, onde o valor excedente deve ser devolvido ou para onde um reembolso deve ir se uma determinada operação exigir isso.
Esses endereços são representados como valores normais de endereço TON nos dados do contrato.
Elas não são necessariamente interpretadas de acordo com o prefixo visual que um humano vê na interface de uma carteira.
No nível do protocolo, a informação importante é o próprio endereço TON analisado e a semântica da mensagem associada à forma como esse endereço é usado.
Por que o STONfi pode tratar EQ... e UQ... como o mesmo destino
Imagine o cenário simplificado a seguir:
EQxxxxxxxx... e UQxxxxxxxx...
podem parecer dois textos diferentes.
Uma aplicação ingênua pode compará-las como texto bruto e concluir que representam carteiras diferentes.
Em vez disso, uma aplicação ciente da TON deve analisá-los na estrutura subjacente do endereço.
Depois de analisado, o aplicativo pode identificar o workchain comum e o identificador da conta.
É por isso que o modelo mental correto é:
Representação amigável diferente ≠ conta diferente.
Esse princípio é particularmente importante para o STONfi porque uma aplicação DeFi pode receber endereços de carteiras diferentes, SDKs, exchanges, exploradores ou desenvolvedores. Diferentes ferramentas podem exibir a mesma conta usando diferentes representações amigáveis.
A TON até fornece utilidades oficiais para detectar e desempacotar essas formas em seus componentes subjacentes.
O que acontece com os parâmetros “to” do STONfi?
De acordo com o comportamento descrito para o SDK do STONfi começando na v0.5.0, os parâmetros gerados para “to” usam representações bounceable porque esses destinos de protocolo são esperados como contratos inicializados que devem receber e executar lógica.
Esse design é consistente com as orientações mais amplas da TON para contratos inteligentes.
A TON recomenda mensagens bounceable para interações com contratos inteligentes porque, quando apropriado, uma interação de contrato falha pode fazer o valor restante da mensagem retornar em vez de simplesmente desaparecer em um destino inutilizável.
Isso não significa que todo endereço envolvido em uma transação do STONfi precise visualmente começar com EQ.
Isso significa que a mensagem e a interação com o contrato devem usar o comportamento de bounce apropriado para a função que aquele endereço desempenha.
Essa distinção é crucial.
Um contrato do protocolo que recebe uma operação é diferente de uma conta de carteira sendo inicializada pela primeira vez.
Endereços do destinatário, de reembolso e de excesso
Um dos erros mais fáceis para desenvolvedores é supor que todo endereço em uma transação de swap é do mesmo tipo de destino.
Não.
Um swap pode envolver diferentes funções de endereço com finalidades diferentes.
Destinatário
O destinatário identifica para onde o ativo resultante deve ser entregue ao final.
Reembolso
Um endereço de reembolso pode ser usado quando uma operação precisa devolver valor ao usuário de origem ou a outro destino designado.
Excesso
Um destino de excesso é usado para o valor que sobra depois que os custos ou quantidades de execução exigidos foram tratados.
Esses endereços podem trafegar pelo protocolo como valores TON MsgAddress incorporados em payloads.
É por isso que apenas olhar para o primeiro endereço em uma transação de carteira não mostra tudo o que está acontecendo dentro do swap.
Por que os builders devem analisar endereços em vez de comparar strings
Para desenvolvedores, isso pode ser a lição mais prática de todas.
Não crie lógica como:
se (addressA === addressB)
quando esses valores podem ser representações amigáveis diferentes do mesmo usuário.
Em vez disso, analise ambos os valores em objetos Address apropriados da TON e compare suas identidades subjacentes.
Bibliotecas no ecossistema TON são projetadas para converter entre representações cruas e amigáveis. A documentação da TON descreve explicitamente a conversão entre formas cruas, bounceable e non-bounceable, enquanto as orientações de segurança alertam desenvolvedores a lidar corretamente com as múltiplas representações de endereço da TON.
A aplicação deve se preocupar com:
workchain + identificador da conta
em vez de:
EQ vs UQ
como um prefixo de texto.
Isso é especialmente importante para indexação, cache, armazenamento em banco de dados, acompanhamento de portfólio, validação de destinatários, análises e integrações de protocolo.
Um Modelo Mental Útil
A forma mais fácil de lembrar todo o sistema é pensar que um endereço TON tem duas camadas.
Camada 1: A Conta
Esta é a identidade subjacente:
Workchain + ID da conta de 256 bits
Isso é o que identifica a conta de destino.
Camada 2: A Representação Amigável para o Usuário
É assim que essa conta é codificada para humanos e software:
Variantes Raw / Bounceable / Non-bounceable / Testnet
A representação amigável adiciona metadados, incluindo bounceability e informações de testnet, além de uma soma de verificação (checksum).
Dois textos amigáveis, portanto, podem descrever a mesma conta subjacente.
É exatamente por isso que uma representação EQ... e uma representação UQ... não devem ser tratadas automaticamente como duas carteiras diferentes.
O que os Usuários Devem Fazer antes de um Swap do STONfi
Para usuários comuns do STONfi, a abordagem mais segura é surpreendentemente simples.
Use o endereço fornecido pela sua carteira ou por ferramentas confiáveis de TON em vez de editar prefixos manualmente.
Não mude EQ para UQ, nem UQ para EQ, apenas porque outro aplicativo exibe o endereço de forma diferente.
Mais importante ainda, sempre verifique o destino real, a rede, o valor e os detalhes da transação antes de assinar.
Carteiras da TON e aplicativos do TON Connect já entendem endereços amigáveis para usuários e o comportamento associado. A documentação do TON Connect, por exemplo, espera endereços amigáveis para mensagens de transação e fornece utilidades para renderizar o endereço da carteira conectada.
Em outras palavras, os usuários geralmente não precisam gerenciar manualmente flags de bounce ao usar uma carteira e uma interface de protocolo devidamente integradas.
O que os builders devem levar
Para desenvolvedores integrando STONfi ou construindo aplicações na TON, a normalização de endereços deve ser tratada como parte fundamental da integração, e não como um caso isolado (edge case).
Uma implementação robusta deve:
Analise os endereços antes de compará-los.
Nunca presuma que duas strings diferentes significam duas contas diferentes.
Preserve as informações do workchain.
O identificador da conta deve ser interpretado junto com o workchain correto. As orientações de segurança da TON recomendam especificamente validar a cadeia do endereço ao processar endereços.
Entenda a diferença entre uma conta e uma mensagem.
Bounceability descreve como uma mensagem deve se comportar; não é uma propriedade permanente que cria uma segunda conta.
Use mensagens bounceable para interações de contrato apropriadas.
Operações de contrato inteligente geralmente se beneficiam de entrega bounceable quando a execução falhar e deve devolver o valor restante.
Use entrega non-bounceable quando a inicialização ou o financiamento exigirem isso.
Contratos de carteira novos ou não inicializados são o caso clássico.
Deixe que SDKs confiáveis cuidem dos detalhes de representação.
O objetivo de um SDK não é apenas facilitar chamadas a contratos, mas também reduzir a quantidade de erros de tratamento de endereços em nível baixo que desenvolvedores podem cometer.
A visão mais ampla para o STONfi
À medida que o DeFi na TON fica mais sofisticado, as transações cada vez mais envolvem múltiplos contratos em vez de uma simples transferência de carteira para carteira.
Swaps do STONfi são um bom exemplo.
Um usuário pode apenas ver:
“Troque token A por token B.”
Por trás dessa interface simples, a blockchain pode estar coordenando mensagens da carteira, roteadores, carteiras de Jetton, contratos de pool, destinos do destinatário e mecanismos de devolução de valor.
O correto tratamento de endereços, portanto, passa a ser parte da confiabilidade do protocolo.
A diferença entre EQ... e UQ... pode parecer apenas estética para um usuário, mas no nível do protocolo isso representa uma distinção significativa na construção da mensagem.
Ao mesmo tempo, essa distinção nunca deve obscurecer a verdade subjacente:
O prefixo não significa automaticamente que existem duas contas diferentes.
A mesma conta TON pode ter diferentes representações amigáveis, enquanto a mensagem enviada para aquela conta pode carregar comportamentos de bounce diferentes dependendo de como o endereço é codificado e de como a transação é construída.
Conclusão Final
O sistema de endereços da TON é poderoso exatamente porque separa a identidade da conta da representação voltada ao usuário.
Um endereço EQ... e um endereço UQ... podem apontar para a mesma conta subjacente. A identidade importante é o workchain + o identificador da conta; o prefixo amigável adiciona informações de tratamento como bounceability.
Para usuários do STONfi, isso significa que você não deve se preocupar quando uma carteira ou aplicação confiável apresentar seu endereço em uma forma válida diferente.
Para builders, a lição é ainda mais importante:
Analise endereços TON. Normalize-os. Compare a identidade subjacente. E escolha o comportamento de bounce de acordo com a função do destino e o propósito da mensagem.
Uma vez que esse modelo esteja claro, o tratamento de endereços do STONfi fica muito mais fácil de entender.
Da próxima vez que você vir um endereço EQ... e UQ..., não pense imediatamente “duas carteiras”.
Pense em:
mesmo destino possível, representação diferente, preferência de tratamento de mensagens diferente.
Essa distinção é pequena na interface, mas é fundamental ao construir aplicações confiáveis na TON.
Explore mais no STON.FI app.ston.fi
Leia mais sobre o STONfi aqui BLOG.STON.FI