Guía rápida de integración
Una integración completa tiene cinco partes. Cada paso enlaza a la página con el formato exacto, y cada formato tiene un vector de prueba con el que puedes comprobar tu código antes de tocar un teléfono.
1. Agrega un escáner 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 con ur:<type>/. Las cargas útiles grandes son animadas: una secuencia de fotogramas que, en conjunto, transportan los datos. Usa un decodificador 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. Empareja: importa las cuentas
Pide al usuario que abra Connect (Conectar) en su billetera dentro de BitTool Signer. Se ofrecen dos tipos de código QR de emparejamiento:
- Wallet level (nivel de billetera): un código QR animado
ur:bytescon Bitcoin (cuatro tipos de dirección), EVM, TRON y tres direcciones de Solana. Es lo mejor para una billetera multicadena. Consulta QR a nivel de billetera. - 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 firmadores QR. Consulta QR a nivel de moneda.
Guarda los xpubs de las cuentas (o las direcciones de Solana), sus rutas de derivación y la huella digital maestra (master fingerprint). Necesitas los tres 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 luego envuélvela en el tipo de solicitud de la cadena:
| Cadena | Solicitud | Qué va dentro |
|---|---|---|
| Bitcoin | ur:crypto-psbt | Un PSBT con bip32Derivation (huella digital + 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 digital, 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 digital y la dirección |
| Solana | ur:sol-sign-request | El mensaje serializado (no la transacción), además de la ruta, la huella digital y la clave pública |
Muestra la solicitud como un 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 billetera y presenta el resultado como un código QR. Escanéalo y verifica, en este orden:
- El tipo 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 cambió).
- La firma es válida para la clave pública esperada y los bytes exactos que pediste firmar.
5. Ensambla y transmite
Inserta la firma en la transacción (EVM: r, s, v; TRON: agrégala a signature[]; Solana: colócala en el espacio del firmante; Bitcoin: finaliza el PSBT) y transmítela a la red. BitTool Signer nunca transmite nada y nunca sabe si una transacción se envió.
Prueba sin teléfono
Todos los ejemplos de este sitio provienen 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 prueba (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 ambas direcciones, 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 transmitirla; se rechaza una respuesta que corresponde a otra solicitud.
- Las entradas de Bitcoin incluyen la transacción previa completa (
nonWitnessUtxo) para entradas SegWit v0 y legacy. - Las transacciones de Solana usan claves de cuenta estáticas (sin tablas de búsqueda de direcciones).