Guía rápida de integración
Una integración completa tiene cinco partes. Cada paso enlaza con la página que describe el formato exacto, y cada formato tiene un vector de prueba con el que puedes comprobar tu código antes de tocar un móvil.
1. Añade un escáner de QR que entienda UR
Todos los códigos QR de BitTool Signer, salvo una dirección simple, son un Uniform Resource (UR): texto que empieza por ur:<type>/. Las cargas grandes son animadas: una secuencia de fotogramas que, en conjunto, transportan los datos. Usa un decodificador de UR en lugar de analizar el texto por tu cuenta.
| Plataforma | Biblioteca |
|---|---|
| JavaScript / TypeScript | @ngraveio/bc-ur (la que usa BitTool Signer) |
| Swift | URKit |
| Kotlin / Java | Hummingbird |
| Rust | ur |
Pasa cada fotograma escaneado al decodificador hasta que indique que está completo. Los fotogramas pueden llegar en cualquier orden y repetirse.
2. Vincula: importa las cuentas
Pide al usuario que abra Connect (conectar) en su cartera dentro de BitTool Signer. Se ofrecen dos tipos de código QR de vinculación:
- Wallet level (nivel de cartera): un código QR
ur:bytesanimado con Bitcoin (cuatro tipos de dirección), EVM, TRON y tres direcciones de Solana. Es lo mejor para una cartera multicadena. Consulta QR a nivel de cartera. - Coin level (nivel de moneda): un código QR estándar por cadena (
ur:crypto-account,ur:crypto-hdkey,ur:crypto-multi-accountso una dirección simple), los mismos formatos que usan otros dispositivos de firma QR. Consulta QR a nivel de moneda.
Guarda los xpub de las cuentas (o las direcciones de Solana), sus rutas de derivación y la huella maestra (master fingerprint). Necesitas las tres cosas para construir solicitudes de firma. Muestra la primera dirección de cada cuenta y pide al usuario que la compare con la dirección que BitTool Signer muestra debajo del código QR.
3. Construye una solicitud de firma
Cuando el usuario envíe fondos, construye la transacción sin firmar como de costumbre y después envuélvela en el tipo de solicitud de la cadena:
| Cadena | Solicitud | Qué va dentro |
|---|---|---|
| Bitcoin | ur:crypto-psbt | Un PSBT con bip32Derivation (huella + ruta completa) en cada entrada y en cada salida de cambio |
| EVM | ur:eth-sign-request | La transacción RLP sin firmar, el JSON EIP-712 o los bytes del mensaje, además de la ruta, la huella, el chain ID y la dirección |
| TRON | ur:tron-sign-request | Los bytes protobuf de raw_data, además de la ruta, la huella y la dirección |
| Solana | ur:sol-sign-request | El mensaje serializado (no la transacción), además de la ruta, la huella y la clave pública |
Muestra la solicitud como código QR animado. Guarda la transacción sin firmar y un ID de solicitud aleatorio en un registro pendiente. Consulta Firma mediante QR.
4. Escanea la firma
BitTool Signer muestra cada campo, pide la contraseña de la cartera y presenta el resultado como código QR. Escanéalo y comprueba, en este orden:
- El tipo de UR es el tipo de respuesta esperado.
- El ID de solicitud coincide con tu solicitud pendiente (Bitcoin: la transacción sin firmar dentro del PSBT no ha cambiado).
- La firma se verifica con la clave pública esperada y sobre los bytes exactos que pediste firmar.
5. Ensambla y difunde
Inserta la firma en la transacción (EVM: r, s, v; TRON: añádela a signature[]; Solana: colócala en la posición del firmante; Bitcoin: finaliza el PSBT) y difúndela a la red. BitTool Signer nunca difunde nada y nunca sabe si una transacción se llegó a enviar.
Prueba sin móvil
Todos los ejemplos de este sitio proceden del motor de BitTool Signer con la frase de prueba pública:
abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about
Impórtala en BitTool Signer en un dispositivo de pruebas (o en tus propias pruebas) y deberías ver exactamente las direcciones, los códigos QR y las firmas que aparecen en esta documentación. Descárgalos todos desde Vectores de prueba.
- Los códigos QR animados se escanean en ambos sentidos, incluso después de perder un fotograma.
- El usuario puede comparar la primera dirección de cada cuenta antes de recibir fondos.
- Cada respuesta se verifica antes de difundirla; se rechaza una respuesta que corresponda a otra solicitud.
- Las entradas de Bitcoin llevan la transacción anterior completa (
nonWitnessUtxo) en las entradas SegWit v0 y legacy. - Las transacciones de Solana usan claves de cuenta estáticas (sin tablas de búsqueda de direcciones).