Em 11 de outubro, foi lançado o TON Connect 5.0.0, um conjunto de bibliotecas que sites e miniaplicativos usam para conectar carteiras TON. Na janela de seleção de carteira, a carteira integrada do Telegram agora aparece em primeiro lugar, com um botão separado "Conectar Telegram", e a antiga @wallet é identificada como Walt. Para desenvolvedores cujo login é baseado na assinatura ton_proof, a equipe recomenda verificar o servidor com a documentação: muitos miniaplicativos não conseguem verificar a assinatura da carteira do Telegram, e o usuário não consegue fazer login com ela.
O que o desenvolvedor precisa fazer
Atualizar pacotes. @tonconnect/sdk, @tonconnect/ui e @tonconnect/ui-react foram publicados na versão 5.0.0; no final do mesmo dia, os pacotes de interface receberam a 5.0.1. A mudança do número da versão principal não significa um código reescrito: de acordo com o changelog, a 5.0.0 é o mesmo código que o sdk 4.1.0 e o ui 3.1.0, e os números foram simplesmente alinhados para que os três pacotes, que são instalados juntos, tivessem a mesma versão. Se você usa o ui 3.0.x, a transição para a 5.0 é equivalente à transição para a 3.1, com todas as suas mudanças (listadas abaixo).
Verificar a parte do servidor ton_proof. Esta é a assinatura pela qual a carteira, ao se conectar, prova ao servidor do aplicativo que o endereço pertence a ela: o servidor emite uma string de uso único, a carteira a assina com uma chave, o servidor encontra a chave pública da carteira e verifica a assinatura. Uma implementação típica busca a chave em walletStateInit, o estado inicial do contrato que a carteira envia junto com o endereço: reconhece uma carteira padrão (v3, v4, v5) pelo hash do código e lê a chave de seus dados. No caso da carteira do Telegram, essa análise de chave não funciona, e a verificação falha.
De acordo com a documentação atualizada, para a carteira do Telegram é necessário um fluxo separado:
- Comparar o hash do código em
walletStateInitcom o hash do contrato-trampolim WalletTg. - Solicitar o estado da conta da rede e garantir que ela esteja ativa e que o mesmo trampolim esteja implantado nela.
- Somente depois disso, chamar o get-method
get_public_keydo contrato e verificar a assinatura com a chave retornada.
A documentação instrui a rejeitar uma conta inativa, um código incompatível ou uma chamada que falhou. É enfatizado separadamente que a presença de um método get_public_key em um contrato por si só não prova nada: ele só pode ser chamado em um código que tenha sido verificado em relação a uma lista de implementações confiáveis. Se o SDK passou uma chave em account.publicKey, ela deve corresponder à encontrada; se não passou, isso não é motivo para rejeitar a assinatura verificada com a chave da rede.
Prever carteira inativa. Uma conta na TON se torna ativa com a primeira transação de saída: antes disso, pode haver saldo no endereço, mas nenhum contrato. A carteira do Telegram, que foi ativada por uma transferência de terceiros e da qual nada foi enviado ainda, não poderá fazer login via ton_proof de acordo com as regras da documentação. A mensagem de erro neste ponto deve ser escrita de forma compreensível, e não um genérico "assinatura rejeitada".
Recompilar a captura de erros. No sdk 4.1.0, todos os erros da biblioteca error.name se tornaram o nome da classe (UserRejectsError, etc.) em vez do antigo "Error" e não são distorcidos pela minificação. Os rastreadores de erros que agrupam por nome e texto criarão novos grupos após a atualização. A resposta da carteira com o código 400 agora chega como um novo MethodNotSupportedError, e não UnknownError; uma resposta incompreensível da carteira integrada chega como WalletTransportError com o valor original em cause.
Considerar o novo endereço de carregamento. No ui 5.0.1, um cristal volumoso apareceu acima do botão do Telegram no telefone. O modelo pesa cerca de 540 KB e é carregado não do pacote, mas de s.ton-connect.io; em um dispositivo fraco, se a animação cair abaixo de 20 quadros por segundo, uma imagem estática permanece em seu lugar. Aplicativos com uma política de carregamento rigorosa (CSP) precisam permitir este endereço ou aceitar a imagem.
O que mudou na janela de seleção de carteira
A biblioteca não armazena a lista de carteiras, mas a carrega do registro geral config.ton.org/wallets-v2.json a cada abertura; o pacote contém apenas uma cópia de backup caso o registro esteja indisponível. Portanto, a ordem das carteiras mudou em 11 de outubro para todos os aplicativos de uma vez, por meio de uma alteração no registro, sem atualização de código. Os novos pacotes adicionaram a isso um layout: a carteira do Telegram e a Gram Wallet foram movidas para botões separados acima da linha geral de carteiras, em vez de aparecerem como um bloco entre as outras.
| Posição no registro | Nome na lista | O que é | Para onde leva |
|---|---|---|---|
| 1 | Telegram | carteira integrada ao próprio mensageiro | t.me/sendgrams, ponte tonbridge.telegram.org |
| 2 | Gram Wallet | aplicativo separado para iOS e Android do site gramwallet.io | connect.gramwallet.io |
| 3 | Walt (ex. Wallet) | bot da antiga @wallet | t.me/walt |
| 4 | Keeper | antiga Tonkeeper | app.tonkeeper.com |
Até 11 de outubro, o bot @wallet estava em primeiro lugar no registro, e a entrada "Telegram" foi adicionada em 15 de setembro no final da lista. Versões antigas da UI exibiam um botão "Wallet in Telegram" fixo, que levava ao bot. Nas novas versões, apenas as posições de dois botões são fixas, e o nome, ícone, ponte e link são obtidos do registro, como em qualquer outra carteira.
Os nomes devem ser diferenciados. Em artigos e conversas, a carteira integrada do Telegram é chamada de Gram Wallet, e o anúncio do TON Connect também escreve "Gram Wallet in Telegram". Mas no registro do TON Connect, a carteira integrada é registrada como Telegram, e sob o nome Gram Wallet há um aplicativo móvel separado com sua própria ponte. O botão "Conectar Telegram" leva à carteira integrada, o botão transparente abaixo dele leva ao aplicativo.
A assinatura "Walt (ex. Wallet)" não é uma nova renomeação. O bot da carteira TOP se tornou Walt em 28 de setembro, e o registro mudou o nome em 29 de setembro. Em 11 de outubro, a anotação "ex. Wallet" foi adicionada ao nome, e o link foi alterado para t.me/walt: o mesmo bot também abre via @wallet. A nova interface move a anotação entre parênteses para a segunda linha do bloco, de modo que o usuário vê "Walt" e abaixo "ex. Wallet".
Simultaneamente, o link pelo qual a interface abre a carteira do Telegram foi corrigido: para um endereço sem o nome do miniaplicativo, como t.me/sendgrams, as versões antigas inseriam a string literal appname=undefined no link. Esta correção foi incluída no ui 3.1.0, ou seja, também na 5.0.
Por que a carteira do Telegram não passa na verificação antiga
A carteira do Telegram funciona com o contrato WalletTg, e ele é estruturado de forma diferente das carteiras padrão. Em cada endereço não está a própria carteira, mas um pequeno trampolim imutável: ele transfere o controle para o código WalletTg, que é armazenado na configuração da rede sob o índice −123 e só pode ser alterado por votação dos validadores. Uma nova versão da carteira é assim disponibilizada a todos os usuários de uma vez, sem a necessidade de atualizar cada contrato.
Daí a falha na verificação. Em walletStateInit da carteira do Telegram, está o código do trampolim, e não o código da carteira v4 ou v5 conhecido pelo analisador, portanto, a tabela de versões não encontra a chave. Além disso, o WalletTg permite alterar a chave de assinatura: no armazenamento do contrato, a chave é sobrescrita, e a única fonte da chave atual é o get-method get_public_key de uma conta ativa. A documentação do TON Connect descreveu este fluxo em 12 de outubro, no dia seguinte ao lançamento dos pacotes.
O servidor de referência do repositório do SDK no aplicativo de demonstração já está estruturado dessa forma: primeiro tenta analisar walletStateInit, e se a versão não for reconhecida, solicita a chave da rede. Aplicativos cujo servidor foi escrito com base em exemplos antigos apenas com a primeira parte rejeitam a assinatura da carteira do Telegram. É exatamente essa violação da especificação que o anúncio aponta como a causa dos logins malsucedidos.
Como a carteira integrada recebe solicitações de aplicativos
TON Connect transmite solicitações entre o aplicativo e a carteira através de uma ponte — um servidor por onde trafegam mensagens criptografadas. A carteira Telegram tem sua própria ponte, tonbridge.telegram.org, e as solicitações chegam ao cliente através do próprio protocolo do Telegram. No esquema MTProto da camada 230, a carteira possui um conjunto completo de métodos wallet.tonConnect*: criar uma sessão, obter solicitações pendentes, coletar uma solicitação para um único dispositivo, enviar uma resposta. A solicitação do aplicativo chega ao cliente como uma mensagem com o nome e o tópico do aplicativo, e o TDLib a descreve como messageTonConnectRequest. No mesmo esquema, existe wallet.getExistingWaltBalance: o TDLib explica que isso é uma verificação para saber se o usuário tem saldo no bot t.me/walt.
Onde a conexão já funciona
Até 10 de outubro, a conexão com a carteira Telegram foi testada em Getgems, DeDust, STON.fi, Tonstakers, Tonnel e TON DNS. A entrada «Telegram» aparece na janela de seleção a partir do registro, por isso ela surge na lista mesmo para aplicativos com versões antigas da biblioteca. Um botão separado acima da linha de carteiras e um link corrigido — isso só está disponível a partir do ui 3.1.0 e versões mais recentes, e se o login com assinatura será bem-sucedido, é o servidor do aplicativo que decide.
