Actualizar a Hardware SDK 1.2

Actualiza una integración existente de Hardware SDK 1.1.x a 1.2.x. Mantén un solo punto de entrada del SDK; Protocol V2 no exige otro SDK. Para proyectos nuevos, empieza por Primeros pasos.

Obligatorio para Protocol V2: sustituye las lecturas exclusivas de V1 y comprueba dispositivos, firmware y protocolos compatibles con cada método. Recomendado: usa selección explícita de wallet en código nuevo. Compatibilidad: puedes conservar las llamadas de cadena existentes compatibles; getPassphraseState sigue como utilidad obsoleta de compatibilidad en ambos protocolos. Según el caso: cambiar Bridge por WebUSB, cambiar el punto de entrada o implementar actualizaciones de firmware son decisiones independientes.

Lo que no cambia

• Los resultados siguen siendo { success, payload }; comprueba success antes de usar un resultado correcto. Los fallos incluyen payload.error y, cuando existe, payload.code.
• Métodos de cadena como evmGetAddress y btcSignTransaction conservan la forma pública HardwareSDK.method(connectId, deviceId?, params). Su disponibilidad sigue dependiendo del dispositivo y firmware.
• init({ env }) elige el transporte, no Protocol V1 o V2. keepSession mantiene el transporte; no selecciona una wallet.

Actualizar

Conserva el paquete de entrada adecuado para tu entorno. Para una integración common-connect existente, el comando siguiente selecciona la línea 1.2 y guarda exactamente la versión resuelta; sustituye 1.2 por la versión exacta validada para un despliegue reproducible.

npm i --save-exact @onekeyfe/[email protected]

Fija todos los paquetes @onekeyfe/hd-* instalados directamente a la misma versión exacta, incluidos los tipos compartidos y transportes; guarda el archivo de bloqueo en Git y revisa el árbol resuelto. Elige una versión alpha explícita para probar una versión preliminar. Una versión 1.2.x no garantiza todos los métodos añadidos en parches posteriores: revisa las versiones mínimas del SDK y firmware de cada API.

Con @onekeyfe/hd-web-sdk, omite connectSrc para usar la URL de iframe predeterminada del paquete instalado. Si la sustituyes o alojas tú mismo, publica los recursos compatibles correspondientes y verifica la URL, la CSP y la inicialización. Publicar npm no demuestra que el iframe alojado esté disponible. Despliega y revierte el paquete y el iframe juntos.

No cargues @onekeyfe/hd-web-sdk y @onekeyfe/hd-common-connect-sdk juntos en un mismo entorno. Las integraciones nativas también deben comprobar el plugin de transporte instalado y los permisos con la versión elegida; consulta Primeros pasos.

Sustituye estas API

No existe openWalletSession({ mode: 'resume-hidden' }). Reanuda una vinculación oculta existente mediante llamadas posteriores con passphraseState.

1. Instantánea del dispositivo

1.1.x

const features = await HardwareSDK.getFeatures(connectId);
if (!features.success) throw new Error(features.payload.error);
const deviceId = features.payload.device_id;

1.2.x

const state = await HardwareSDK.getDeviceState(connectId);
if (!state.success) throw new Error(state.payload.error);
const deviceId = state.payload.identity.deviceId;
if (!deviceId) throw new Error('Device has no wallet identity');

Por defecto, scope: 'runtime' actualiza el estado; scope: 'settings' actualiza estado y ajustes; scope: 'firmware' actualiza estado, identidad, versiones y verificación. Todos devuelven una instantánea completa, no solo la sección actualizada. Puede haber campos no disponibles en el modo actual: conserva null en lugar de convertirlo en false o 0.0.0. Los ajustes no se pueden leer en modo Bootloader / Romloader V2.

Comprueba el éxito de searchDevices antes de leer la lista. connectId identifica la conexión actual del transporte y puede cambiar al reconectar. No sustituyas un deviceId ausente por un número de serie ni uses la serie del hardware como vinculación de wallet. Consulta Identificadores y Estado del dispositivo.

2. Sesión de cartera

1.1.x — selecciona una wallet oculta y después transmite su huella:

const ps = await HardwareSDK.getPassphraseState(connectId, {
  initSession: true,
});
if (!ps.success) throw new Error(ps.payload.error);
if (typeof ps.payload !== 'string' || !ps.payload) {
  throw new Error('No hidden wallet fingerprint');
}
const address = await HardwareSDK.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/0'/0/0",
  passphraseState: ps.payload,
});
if (!address.success) throw new Error(address.payload.error);

1.2.x — ejecuta uno de los siguientes flujos según la selección del usuario. No ejecutes ambos seguidos.

Wallet estándar

import { OpenWalletSessionMode } from '@onekeyfe/hd-core';
 
const opened = await HardwareSDK.openWalletSession(connectId, {
  mode: OpenWalletSessionMode.Standard,
});
if (!opened.success) throw new Error(opened.payload.error);
if (opened.payload.walletType !== 'standard') {
  throw new Error('A standard wallet was not opened');
}
const address = await HardwareSDK.evmGetAddress(connectId, opened.payload.deviceId, {
  path: "m/44'/60'/0'/0/0",
  useEmptyPassphrase: true,
});
if (!address.success) throw new Error(address.payload.error);

Wallet oculta

import { OpenWalletSessionMode } from '@onekeyfe/hd-core';
 
const opened = await HardwareSDK.openWalletSession(connectId, {
  mode: OpenWalletSessionMode.SelectHidden,
});
if (!opened.success) throw new Error(opened.payload.error);
if (opened.payload.walletType !== 'hidden' || !opened.payload.passphraseState) {
  throw new Error('A hidden wallet was not opened');
}
const binding = opened.payload;
const address = await HardwareSDK.evmGetAddress(connectId, binding.deviceId, {
  path: "m/44'/60'/0'/0/0",
  passphraseState: binding.passphraseState,
});
if (!address.success) throw new Error(address.payload.error);

Guarda los valores devueltos walletType, deviceId y passphraseState tras comprobar el éxito y el tipo. La wallet estándar tiene una huella null. En V1 sin protección por passphrase, seleccionar una wallet oculta puede devolver una estándar; no la guardes como oculta.

No pases los parámetros antiguos useEmptyPassphrase, initSession, deviceId o passphraseState a openWalletSession, ni valores predeterminados heredados establecidos en false. Las llamadas posteriores de dirección/firma usan useEmptyPassphrase: true para la wallet estándar o el passphraseState guardado para la oculta. Omitir la huella oculta puede permitir una operación correcta en la wallet estándar sin error.

No vuelvas a seleccionar wallet antes de cada método ni automáticamente al reconectar. Reutiliza la vinculación; detente y pide selección explícita si falla la identidad o huella. No sobrescribas la vinculación con un dispositivo recién conectado. Consulta Sesiones de wallet.

UI, cancelación y reconexión

La Promise del método determina el resultado final. Clasifica errores mediante payload.code, no comparando texto localizado; distingue parámetros inválidos, métodos no compatibles, wallet incorrecta, cancelación y fallo de transporte.

Los listeners de UI_EVENT reciben un mensaje con tipo y contenido. Los de DEVICE.STATE reciben directamente el contenido del evento de estado, incluidos connectId, state y revision; sus estructuras son diferentes. Suscríbete una vez y elimina los listeners al desmontar la integración.

Serializa las llamadas por dispositivo y las solicitudes de PIN/passphrase del host entre dispositivos. Los puntos de entrada públicos actuales solo reenvían type y payload de uiResponse; no supongas que los metadatos de correlación en la raíz llegan al SDK. Invalida callbacks de modales antiguos al cerrar, cancelar o desconectar para que no respondan a una solicitud posterior.

Cancela la operación activa con HardwareSDK.cancel(connectId) y respeta la cancelación del usuario. Al desconectar, vuelve a descubrir el dispositivo, obtén la conexión actual, lee el estado y reutiliza la vinculación verificada. No repitas automáticamente firmas, borrados ni actualizaciones. Una desconexión normal no exige dispose; tras liberar explícitamente el SDK, inicialízalo antes de nuevas llamadas. Consulta Guía de API principales y Reconexión.

3. Protocol V1 y V2

Classic / Mini / Touch / Pro usan Protocol V1; Pro 2 / Neo usan Protocol V2. El SDK lo detecta mediante una consulta en vivo. No lo deduzcas del PID USB, nombre BLE o carcasa.

Normalmente deja que la detección elija el protocolo. Si pasas connectProtocol, es un requisito estricto: se rechaza una discrepancia. Versión del SDK, compatibilidad del protocolo y firmware mínimo son comprobaciones independientes; revisa la tabla de soporte de la API antes de habilitar un método.

Las cadenas exclusivas de V1 (Stellar, Alephium, Nexa, Dynex, Nervos, SCDO, Benfen y la cadena Neo) no son compatibles con Pro 2 / Neo. El nombre del dispositivo Neo no implica soporte de la cadena Neo. Consulta Protocolo y Soporte de cadenas.

4. Firmware

Si gestionas firmware, actualiza también el analizador del resultado de comprobación de versiones: las versiones para protocolo V2 pueden incluir componentes de destino y un archivo de recursos. No supongas un único binario antiguo ni una URL/huella siempre presente. Usa recursos correspondientes al modelo y el contrato de la API elegida.

Una confirmación o evento de progreso no demuestra la instalación. Tras reiniciar, reconecta y lee scope: 'firmware' para verificar las versiones instaladas. Conserva los usos necesarios de keepSession para mantener el transporte y nunca repitas automáticamente una actualización tras desconectar. Consulta Actualización de firmware.

5. Transporte

Pasar de 1.1.x a 1.2.x no exige reemplazar un transporte funcional. Si también decides migrar Bridge (env: 'web' + checkBridgeStatus) a WebUSB, sigue la guía específica:

• Bridge → common-connect WebUSB
• Bridge → iframe WebUSB

WebUSB necesita un contexto seguro y un gesto del usuario para seleccionar permisos. BLE necesita los permisos Bluetooth del sistema. Prueba en el navegador, Electron o entorno nativo que publicas.

Lista de comprobación

1. Elige una versión exacta, alinea dependencias y recursos de iframe, y conserva el archivo de bloqueo y versión anteriores.
2. Actualiza lecturas de estado y tratamiento de nulos; sustituye lecturas antiguas si necesitas V2.
3. Actualiza la selección de wallet y guarda la vinculación verificada; las conexiones y sesiones de firmware no son identidad de wallet.
4. Actualiza entrada/notificaciones, cancelación y reconexión; serializa llamadas y solicitudes de entrada del host.
5. Comprueba protocolo, cadenas y firmware; migra actualizaciones solo si tu integración las gestiona.

Ejecuta los siguientes casos en cada entorno compatible antes de publicar. Los casos de hardware requieren dispositivos reales; compilar la documentación no equivale a probar el hardware.

Compara direcciones conocidas y resultados de firma compatibles con tu base 1.1.x; comprueba fallos por código de error. No incluyas PIN, passphrases, secretos derivados ni material privado en logs o datos de prueba.

Reversión

Conserva dependencias exactas, archivo de bloqueo, recursos de iframe y configuración anteriores como una versión probada completa. Restáuralos juntos; no mezcles un paquete de entrada 1.1.x con recursos o tipos 1.2.x.

Desactiva las integraciones nuevas exclusivas de V2 al volver a la base 1.1.x. Bajar la versión del SDK no baja la del firmware. Conserva las vinculaciones de wallet como datos, pero valídalas con la integración restaurada y pide selección del usuario si no se pueden verificar. No vuelvas automáticamente a la wallet estándar ni repitas operaciones canceladas.

Siguiente

• Primeros pasos
• Guía de API principales
• Sesiones de wallet
• Reconexión y liberación