El 11 de octubre se lanzó TON Connect 5.0.0, un conjunto de bibliotecas a través de las cuales los sitios web y las miniaplicaciones conectan billeteras TON. En la ventana de selección de billetera, la billetera integrada de Telegram ahora aparece en primer lugar, con un botón separado de «Conectar Telegram», y el antiguo @wallet se denomina Walt. Para los desarrolladores cuyo inicio de sesión se basa en la firma ton_proof, el equipo recomienda verificar el servidor con la documentación: muchas miniaplicaciones no pueden verificar la firma de la billetera de Telegram, y el usuario no puede iniciar sesión con ella.
Qué debe hacer el desarrollador
Actualizar paquetes. @tonconnect/sdk, @tonconnect/ui y @tonconnect/ui-react se publicaron en la versión 5.0.0; a última hora del mismo día, los paquetes de interfaz recibieron la 5.0.1. El cambio del número de versión principal no significa que el código haya sido reescrito: según el registro de cambios, la versión 5.0.0 es el mismo código que sdk 4.1.0 y ui 3.1.0; los números simplemente se alinearon para que los tres paquetes, que se instalan juntos, tuvieran la misma versión. Si tiene ui 3.0.x, la transición a 5.0 es equivalente a la transición a 3.1 con todos sus cambios (que se detallan a continuación).
Verificar la parte del servidor de ton_proof. Esta es la firma con la que la billetera, al conectarse, demuestra al servidor de la aplicación que la dirección le pertenece: el servidor emite una cadena de un solo uso, la billetera la firma con su clave, el servidor encuentra la clave pública de la billetera y verifica la firma. Una implementación típica busca la clave en walletStateInit, el estado inicial del contrato que la billetera envía junto con la dirección: reconoce una billetera estándar (v3, v4, v5) por el hash de su código y lee la clave de sus datos. En el caso de la billetera de Telegram, este análisis no encuentra la clave, y la verificación falla.
Según la documentación actualizada, para la billetera de Telegram se necesita una rama separada:
- Comparar el hash del código en
walletStateInitcon el hash del contrato de trampolín WalletTg. - Solicitar el estado de la cuenta a la red y asegurarse de que esté activa y que el mismo trampolín esté desplegado en ella.
- Solo después de esto, llamar al get method
get_public_keydel contrato y verificar la firma con la clave devuelta.
La documentación indica que se debe rechazar una cuenta inactiva, un código que no coincida o una llamada fallida. Se subraya específicamente que la presencia del método get_public_key en un contrato por sí misma no prueba nada: solo se puede llamar a este método en un código que haya sido verificado con la lista de implementaciones aprobadas. Si el SDK pasó una clave en account.publicKey, esta debe coincidir con la encontrada; si no la pasó, no es motivo para rechazar una firma verificada con una clave de la red.
Prever una billetera inactiva. Una cuenta en TON se activa con la primera transacción saliente: antes de eso, puede haber un saldo en la dirección, pero no hay un contrato. La billetera de Telegram, a la que un usuario recibió una transferencia de terceros y desde la cual aún no se ha enviado nada, no podrá iniciar sesión a través de ton_proof según las reglas de la documentación. El mensaje de error en este punto debe ser comprensible para el usuario, no un genérico «firma rechazada».
Reestructurar el manejo de errores. En sdk 4.1.0, el error.name de todos los errores de la biblioteca se convirtió en el nombre de la clase (UserRejectsError, etc.) en lugar del anterior "Error" y no se distorsiona con la minificación. Los rastreadores de errores que agrupan por nombre y texto crearán nuevos grupos después de la actualización. La respuesta de la billetera con el código 400 ahora llega como un nuevo MethodNotSupportedError, y no como UnknownError; una respuesta incomprensible de la billetera integrada llega como WalletTransportError con el valor original en cause.
Considerar la nueva dirección de carga. En ui 5.0.1, sobre el botón de Telegram en el teléfono, apareció un cristal voluminoso. El modelo pesa alrededor de 540 KB y se carga no desde el paquete, sino desde s.ton-connect.io; en un dispositivo lento, si la animación cae por debajo de 20 frames por segundo, en su lugar permanece una imagen estática. Las aplicaciones con una política de seguridad de contenido (CSP) estricta deben permitir esta dirección o conformarse con la imagen.
Qué cambió en la ventana de selección de billetera
La biblioteca no almacena la lista de billeteras, sino que la carga de un registro común config.ton.org/wallets-v2.json cada vez que se abre; el paquete solo contiene una copia de respaldo en caso de que el registro no esté disponible. Por lo tanto, el orden de las billeteras cambió el 11 de octubre para todas las aplicaciones a la vez, mediante una modificación del registro, sin necesidad de actualizar el código. Los nuevos paquetes añadieron a esto una nueva disposición: la billetera de Telegram y Gram Wallet se han movido a botones separados sobre la fila general de billeteras, en lugar de aparecer como una ficha más entre otras.
| Posición en el registro | Nombre en la lista | Qué es | A dónde lleva |
|---|---|---|---|
| 1 | Telegram | billetera integrada en el propio mensajero | t.me/sendgrams, bridge server tonbridge.telegram.org |
| 2 | Gram Wallet | aplicación separada para iOS y Android desde gramwallet.io | connect.gramwallet.io |
| 3 | Walt (ex. Wallet) | bot del antiguo @wallet | t.me/walt |
| 4 | Keeper | antiguo Tonkeeper | app.tonkeeper.com |
Hasta el 11 de octubre, el bot @wallet ocupaba el primer lugar en el registro, y la entrada «Telegram» se añadió el 15 de septiembre al final de la lista. Las versiones antiguas de la interfaz de usuario mostraban un botón codificado «Wallet in Telegram» que llevaba al bot. En las nuevas versiones, solo las posiciones de dos botones están fijas, mientras que el nombre, el icono, el bridge server y el enlace se toman del registro, como cualquier otra billetera.
Es importante distinguir los nombres. En artículos y conversaciones, la billetera integrada de Telegram se llama Gram Wallet, y el anuncio de TON Connect también menciona «Gram Wallet in Telegram». Pero en el registro de TON Connect, la billetera integrada se registra como Telegram, y bajo el nombre Gram Wallet hay una aplicación móvil separada con su propio bridge server. El botón «Conectar Telegram» lleva a la billetera integrada, el botón transparente debajo lleva a la aplicación.
La etiqueta «Walt (ex. Wallet)» no es un nuevo cambio de nombre. El bot de la billetera TOP se convirtió en Walt el 28 de septiembre, y el registro cambió el nombre el 29 de septiembre. El 11 de octubre, se añadió la nota «ex. Wallet» al nombre, y el enlace se cambió a t.me/walt: el mismo bot se abre también a través de @wallet. La nueva interfaz mueve la nota entre paréntesis a la segunda línea de la ficha, de modo que el usuario ve «Walt» y debajo «ex. Wallet».
De paso, se corrigió el enlace por el cual la interfaz abre la billetera de Telegram: para una dirección sin nombre de miniaplicación, como t.me/sendgrams, las versiones antiguas insertaban la cadena literal appname=undefined en el enlace. Esta corrección se incluyó en ui 3.1.0, es decir, también en 5.0.
Por qué la billetera de Telegram no pasa la verificación antigua
La billetera de Telegram funciona con el contrato WalletTg, y está estructurada de manera diferente a las billeteras estándar. En cada dirección no reside la billetera en sí, sino un diminuto e inmutable contrato de trampolín: este transfiere el control al código de WalletTg, que se almacena en la configuración de la red bajo el índice −123 y solo puede ser modificado por votación de los validadores. De esta manera, una nueva versión de la billetera llega a todos los usuarios a la vez, sin necesidad de actualizar cada contrato.
De ahí la falla en la verificación. En el walletStateInit de la billetera de Telegram se encuentra el código del trampolín, y no el código de billetera v4 o v5 conocido por el analizador, por lo que la tabla de versiones no encuentra la clave. Además, WalletTg permite cambiar la clave de firma: en el almacenamiento del contrato, la clave se sobrescribe, y la única fuente de la clave actual es el get method get_public_key de una cuenta activa. La documentación de TON Connect describió esta rama el 12 de octubre, al día siguiente del lanzamiento de los paquetes.
El servidor de referencia del repositorio del SDK en la aplicación de demostración ya está configurado de esta manera: primero intenta analizar walletStateInit, y si la versión no es reconocida, solicita la clave a la red. Las aplicaciones cuyo servidor está escrito siguiendo ejemplos antiguos solo con la primera parte, rechazan la firma de la billetera de Telegram. Esta violación de la especificación es lo que el anuncio señala como la causa de los inicios de sesión fallidos.
Cómo la billetera integrada recibe las solicitudes de las aplicaciones
TON Connect transmite las solicitudes entre la aplicación y la billetera a través de un puente — un servidor por el que circulan mensajes cifrados. La billetera de Telegram tiene su propio puente, tonbridge.telegram.org, y las solicitudes llegan al cliente a través del propio protocolo de Telegram. En el esquema MTProto de la capa 230, la billetera tiene un conjunto completo de métodos wallet.tonConnect*: crear sesión, obtener solicitudes pendientes, recoger una solicitud para un dispositivo, enviar respuesta. La solicitud de la aplicación llega al cliente como un mensaje con el nombre y el tema de la aplicación, y TDLib lo describe como messageTonConnectRequest. En el mismo esquema, existe wallet.getExistingWaltBalance: TDLib explica que esto es una verificación para saber si el usuario tiene saldo en el bot t.me/walt.
Dónde ya funciona la conexión
Para el 10 de octubre, la conexión de la billetera de Telegram ya se había probado en Getgems, DeDust, STON.fi, Tonstakers, Tonnel y TON DNS. La entrada «Telegram» aparece en la ventana de selección desde el registro, por lo que figura en la lista incluso para las aplicaciones que usan una versión antigua de la biblioteca. Un botón separado sobre la fila de billeteras y el enlace corregido solo están disponibles a partir de la interfaz de usuario 3.1.0 y versiones posteriores, mientras que la decisión de si el inicio de sesión con firma se realizará correctamente la toma el servidor de la aplicación.
