@onekeyfe/hd-core 1.2.0-alpha.101 → 1.2.0-alpha.103

package/src/core/index.ts

@@ -64,6 +64,7 @@ import {
   isProtocolV2UiEnabled,
 } from '../protocols/protocol-v2/uiInteraction';
 import { createUiProgressMessageFilter } from '../utils/uiProgressThrottle';
+import { isLegacyProtocolV2FirmwareRecoveryMethod } from './protocolV2LegacyRecovery';
 
 import type { ConnectSettings, Features, KnownDevice } from '../types';
 import type { CoreMessage, IFrameCallMessage, UiPromise, UiPromiseResponse } from '../events';
@@ -109,6 +110,9 @@ const parseInitOptions = (method?: BaseMethod): InitOptions => ({
   connectProtocol: method?.payload.connectProtocol,
   forceProtocolDetection: method?.payload.forceProtocolDetection,
   protocolV2DeviceInfoTimeoutMs: method?.payload.protocolV2DeviceInfoTimeoutMs,
+  ...(isLegacyProtocolV2FirmwareRecoveryMethod(method)
+    ? { allowLegacyProtocolV2ProtocolInfo: true }
+    : {}),
 });
 
 let _core: Core | undefined;

package/src/core/protocolV2LegacyRecovery.ts

@@ -0,0 +1,12 @@
+import type { BaseMethod } from '../api/BaseMethod';
+
+type CoreMethodDescriptor = Pick<BaseMethod, 'name' | 'payload'>;
+
+/**
+ * TEMPORARY COMPATIBILITY: Legacy ProtocolInfo is accepted only by the
+ * firmware recovery entry points used before and during Protocol V2 updates.
+ */
+export const isLegacyProtocolV2FirmwareRecoveryMethod = (method?: CoreMethodDescriptor): boolean =>
+  method?.name === 'firmwareUpdateV4' ||
+  method?.name === 'checkAllFirmwareRelease' ||
+  (method?.name === 'getDeviceState' && method.payload.scope === 'firmware');

package/src/device/Device.ts

@@ -61,6 +61,7 @@ import {
   PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
   type ProtocolV2RuntimeMode,
   getProtocolV2RuntimeMode,
+  isLegacyProtocolV2ProtocolInfo,
   requestProtocolV2DeviceInfo,
   requestProtocolV2DeviceStatus,
   requestProtocolV2ProtocolInfo,
@@ -99,6 +100,8 @@ export type InitOptions = {
   protocolV2DeviceInfoTimeoutMs?: number;
   /** Refresh Protocol V2 runtime state before returning discovery results. */
   refreshRuntimeState?: boolean;
+  /** Recovery-only compatibility used by discovery and Protocol V2 firmware updates. */
+  allowLegacyProtocolV2ProtocolInfo?: boolean;
   /**
    * Protocol V1 Initialize response timeout override. Reboot-wait polling passes a
    * short value so an unanswered probe settles before the next poll tick.
@@ -977,10 +980,16 @@ export class Device extends EventEmitter {
       });
       // The default request excludes SE/hash data and therefore uses basic scope.
       // Full version and verification data require getDeviceState({ scope: 'firmware' }).
-      const features = await this.probeProtocolV2RuntimeState(
-        deviceInfo,
-        options?.protocolV2DeviceInfoTimeoutMs
-      );
+      const features = options?.allowLegacyProtocolV2ProtocolInfo
+        ? await this.probeProtocolV2RuntimeState(
+            deviceInfo,
+            options.protocolV2DeviceInfoTimeoutMs,
+            { allowLegacyProtocolV2ProtocolInfo: true }
+          )
+        : await this.probeProtocolV2RuntimeState(
+            deviceInfo,
+            options?.protocolV2DeviceInfoTimeoutMs
+          );
       Log.debug('Protocol V2 features:', features);
     } catch (error) {
       Log.error('Protocol V2 initialization failed:', error);
@@ -1017,7 +1026,13 @@ export class Device extends EventEmitter {
           commands: this.commands,
           request: getProtocolV2DeviceInfoRequest(),
         });
-        await this.probeProtocolV2RuntimeState(deviceInfo);
+        if (params.allowLegacyProtocolV2ProtocolInfo) {
+          await this.probeProtocolV2RuntimeState(deviceInfo, undefined, {
+            allowLegacyProtocolV2ProtocolInfo: true,
+          });
+        } else {
+          await this.probeProtocolV2RuntimeState(deviceInfo);
+        }
         refreshedDeviceInfo = deviceInfo;
         initializedWithDeviceInfo = true;
       } else {
@@ -1053,7 +1068,16 @@ export class Device extends EventEmitter {
       }
 
       if (refresh.has('status') && !initializedWithDeviceInfo) {
-        await this.probeProtocolV2RuntimeState(refreshedDeviceInfo);
+        const cachedMode = this.state?.status.mode;
+        await this.probeProtocolV2RuntimeState(refreshedDeviceInfo, undefined, {
+          // Loader firmware does not support DeviceStatusGet. Renegotiate ProtocolInfo
+          // during an explicit refresh so a device rebooted into application firmware
+          // can leave the cached loader state.
+          forceRuntimeContextRefresh: cachedMode === 'bootloader' || cachedMode === 'romloader',
+          ...(params.allowLegacyProtocolV2ProtocolInfo
+            ? { allowLegacyProtocolV2ProtocolInfo: true }
+            : {}),
+        });
       }
 
       if (refresh.has('settings') && this.state?.status.mode === 'normal') {
@@ -1124,19 +1148,39 @@ export class Device extends EventEmitter {
     return this.features;
   }
 
-  async ensureProtocolV2RuntimeContext(timeoutMs?: number): Promise<ProtocolInfo> {
+  async ensureProtocolV2RuntimeContext(
+    timeoutMs?: number,
+    options?: {
+      forceRefresh?: boolean;
+      allowLegacyProtocolV2ProtocolInfo?: boolean;
+    }
+  ): Promise<ProtocolInfo> {
+    const assertProtocolInfoAllowed = (protocolInfo: ProtocolInfo) => {
+      if (
+        isLegacyProtocolV2ProtocolInfo(protocolInfo) &&
+        options?.allowLegacyProtocolV2ProtocolInfo !== true
+      ) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.DeviceInitializeFailed,
+          'Legacy Protocol V2 ProtocolInfo is supported only during device discovery and firmware update.'
+        );
+      }
+      return protocolInfo;
+    };
     const cachedProtocolInfo =
-      this.protocolV2RuntimeContext ??
-      (!this.protocolV2StateNeedsReload
-        ? this.state?.raw?.protocolV2ProtocolInfo ?? undefined
-        : undefined);
+      options?.forceRefresh === true
+        ? undefined
+        : this.protocolV2RuntimeContext ??
+          (!this.protocolV2StateNeedsReload
+            ? this.state?.raw?.protocolV2ProtocolInfo ?? undefined
+            : undefined);
     if (cachedProtocolInfo) {
       this.protocolV2RuntimeContext = cachedProtocolInfo;
-      return cachedProtocolInfo;
+      return assertProtocolInfoAllowed(cachedProtocolInfo);
     }
 
     if (this.protocolV2RuntimeContextPromise) {
-      return this.protocolV2RuntimeContextPromise;
+      return assertProtocolInfoAllowed(await this.protocolV2RuntimeContextPromise);
     }
 
     const requestToken = {};
@@ -1158,7 +1202,7 @@ export class Device extends EventEmitter {
     this.protocolV2RuntimeContextPromise = pendingRequest;
 
     try {
-      return await pendingRequest;
+      return assertProtocolInfoAllowed(await pendingRequest);
     } finally {
       if (this.protocolV2RuntimeContextPromise === pendingRequest) {
         this.protocolV2RuntimeContextPromise = undefined;
@@ -1169,9 +1213,20 @@ export class Device extends EventEmitter {
     }
   }
 
-  async probeProtocolV2RuntimeState(deviceInfo?: ProtocolV2DeviceInfo, timeoutMs?: number) {
-    const protocolInfo = await this.ensureProtocolV2RuntimeContext(timeoutMs);
+  async probeProtocolV2RuntimeState(
+    deviceInfo?: ProtocolV2DeviceInfo,
+    timeoutMs?: number,
+    options?: {
+      forceRuntimeContextRefresh?: boolean;
+      allowLegacyProtocolV2ProtocolInfo?: boolean;
+    }
+  ) {
+    const protocolInfo = await this.ensureProtocolV2RuntimeContext(timeoutMs, {
+      forceRefresh: options?.forceRuntimeContextRefresh,
+      allowLegacyProtocolV2ProtocolInfo: options?.allowLegacyProtocolV2ProtocolInfo,
+    });
     const runtimeMode = getProtocolV2RuntimeMode(protocolInfo);
+    const legacyProtocolInfo = isLegacyProtocolV2ProtocolInfo(protocolInfo);
     const runtimeDeviceInfo = deviceInfo ?? this.state?.raw?.protocolV2DeviceInfo;
     const protocolV2DeviceType = runtimeDeviceInfo
       ? resolveProtocolV2DeviceIdentity(runtimeDeviceInfo.hw?.Device_type).deviceType
@@ -1186,10 +1241,9 @@ export class Device extends EventEmitter {
         'Protocol V2 romloader mode is only supported for Pro2 and Neo.'
       );
     }
-    const deviceStatusSupported = supportsProtocolV2Message(
-      protocolInfo,
-      PROTOCOL_V2_DEVICE_STATUS_GET_MESSAGE_TYPE
-    );
+    const deviceStatusSupported =
+      legacyProtocolInfo ||
+      supportsProtocolV2Message(protocolInfo, PROTOCOL_V2_DEVICE_STATUS_GET_MESSAGE_TYPE);
 
     if (runtimeMode === 'bootloader' || runtimeMode === 'romloader') {
       return this.updateProtocolV2Features(deviceInfo, null, runtimeMode, protocolInfo);
@@ -1491,6 +1545,10 @@ export class Device extends EventEmitter {
 
   async interruptionFromUser() {
     const error = ERRORS.TypedError(HardwareErrorCode.DeviceInterruptedFromUser);
+    // Cancellation often ends the transport session, especially during firmware
+    // update reboot or exit. Invalidate V2 state before awaiting asynchronous
+    // cancellation callbacks so the next request cannot reuse a stale runtime mode.
+    this.markTransportDisconnected();
     await this.cancelableAction?.(error);
     await this.commands?.cancel();
 

package/src/device/DevicePool.ts

@@ -182,7 +182,7 @@ export class DevicePool extends EventEmitter {
       try {
         await device.initialize(initOptions);
         if (initOptions?.refreshRuntimeState && device.isProtocolV2()) {
-          await this._refreshProtocolV2DiscoveryState(device);
+          await this._refreshProtocolV2DiscoveryState(device, initOptions);
         }
       } finally {
         await device.release();
@@ -197,7 +197,7 @@ export class DevicePool extends EventEmitter {
     await device.run(
       async () => {
         try {
-          await this._refreshProtocolV2DiscoveryState(device);
+          await this._refreshProtocolV2DiscoveryState(device, initOptions);
         } catch (error) {
           // Device.run releases after the callback; then propagate the actual read error.
           refreshError = error;
@@ -206,6 +206,9 @@ export class DevicePool extends EventEmitter {
       {
         connectProtocol: initOptions.connectProtocol,
         forceProtocolDetection: initOptions.forceProtocolDetection,
+        ...(initOptions.allowLegacyProtocolV2ProtocolInfo
+          ? { allowLegacyProtocolV2ProtocolInfo: true }
+          : {}),
       }
     );
     if (refreshError instanceof Error) throw refreshError;
@@ -217,10 +220,19 @@ export class DevicePool extends EventEmitter {
    * error; settings only supplies a label, so its failure retains the existing name.
    * Device.getDeviceState skips unsupported status/settings calls in loader mode.
    */
-  static async _refreshProtocolV2DiscoveryState(device: Device) {
-    await device.getDeviceState({ refreshSections: ['status'] });
+  static async _refreshProtocolV2DiscoveryState(device: Device, initOptions?: InitOptions) {
+    const stateReadOptions = initOptions?.allowLegacyProtocolV2ProtocolInfo
+      ? { allowLegacyProtocolV2ProtocolInfo: true as const }
+      : {};
+    await device.getDeviceState({
+      refreshSections: ['status'],
+      ...stateReadOptions,
+    });
     try {
-      await device.getDeviceState({ refreshSections: ['settings'] });
+      await device.getDeviceState({
+        refreshSections: ['settings'],
+        ...stateReadOptions,
+      });
     } catch (error) {
       Log.debug('Unable to refresh Protocol V2 device label during discovery', error);
     }

package/src/protocols/protocol-v2/features.ts

@@ -56,6 +56,16 @@ export const getProtocolV2SeType = (se?: DeviceSEInfo): string | null =>
 
 export type ProtocolV2RuntimeMode = 'normal' | 'bootloader' | 'romloader';
 
+export type ProtocolV2ProtocolInfo = ProtocolInfo & {
+  /** Present only when hd-transport decoded the pre-build-fingerprint wire layout. */
+  protobuf_definition?: string | null;
+};
+
+export const isLegacyProtocolV2ProtocolInfo = (
+  protocolInfo: ProtocolInfo
+): protocolInfo is ProtocolV2ProtocolInfo & { protobuf_definition: string | null } =>
+  Object.prototype.hasOwnProperty.call(protocolInfo, 'protobuf_definition');
+
 /**
  * Protocol V2 fingerprints use:
  * <binary>__<version>__<commit>__<PROD|DEV>__<DEBUG|RELEASE>

package/src/protocols/protocol-v2/index.ts

@@ -7,6 +7,7 @@ export {
   getProtocolV2RuntimeMode,
   getProtocolV2SeState,
   getProtocolV2SeType,
+  isLegacyProtocolV2ProtocolInfo,
   parseProtocolV2BuildFingerprint,
   requestProtocolV2ProtocolInfo,
   supportsProtocolV2Message,
@@ -18,6 +19,7 @@ export type {
   ProtocolV2SEInfo,
   ProtocolV2SeStateLabel,
   ProtocolV2RuntimeMode,
+  ProtocolV2ProtocolInfo,
 } from './features';
 export * from './firmware';
 export * from './walletSession';

package/src/types/api/getDeviceState.ts

@@ -11,6 +11,8 @@ export type GetDeviceStateParams = CommonParams & {
 export type DeviceStateReadOptions = {
   refreshSections?: DeviceStateSection[];
   includeRaw?: boolean;
+  /** Internal recovery-only compatibility used by discovery and firmware update flows. */
+  allowLegacyProtocolV2ProtocolInfo?: boolean;
 };
 
 export declare function getDeviceState(

package/src/types/api/protocolV2.ts

@@ -68,7 +68,7 @@ export declare function deviceUploadNft(
 export declare function uploadPortfolio(
   connectId: string,
   params: {
-    packageBytes: ArrayBuffer | Uint8Array | Blob;
+    packageBase64: string;
     timeoutMs?: number | string;
   }
 ): Response<FileInfo & { portfolioUpdated: true }>;

package/src/utils/pro2Nft.ts

@@ -109,6 +109,34 @@ export function buildPro2NftBundle(options: {
   const { image, thumbnail, title, subtitle, timestampMs } = options;
   assertImage('image', image, PRO2_NFT_IMAGE_WIDTH, PRO2_NFT_IMAGE_HEIGHT);
   assertImage('thumbnail', thumbnail, PRO2_NFT_THUMBNAIL_WIDTH, PRO2_NFT_THUMBNAIL_HEIGHT);
+  const encodedImage = encodePro2Image({ ...image, alphaMode: 'black-background' }).data;
+  const encodedThumbnail = encodePro2Image({
+    ...thumbnail,
+    alphaMode: 'black-background',
+  }).data;
+  return buildPro2NftBundleFromEncodedImages({
+    image: encodedImage,
+    thumbnail: encodedThumbnail,
+    title,
+    subtitle,
+    timestampMs,
+  });
+}
+
+export function buildPro2NftBundleFromEncodedImages(options: {
+  image: Uint8Array;
+  thumbnail: Uint8Array;
+  title: string;
+  subtitle: string;
+  timestampMs: number;
+}): Pro2NftBundle {
+  const { image, thumbnail, title, subtitle, timestampMs } = options;
+  if (!(image instanceof Uint8Array) || image.byteLength === 0) {
+    throw invalidParameter('Parameter [image] must contain encoded NFT image data.');
+  }
+  if (!(thumbnail instanceof Uint8Array) || thumbnail.byteLength === 0) {
+    throw invalidParameter('Parameter [thumbnail] must contain encoded NFT thumbnail data.');
+  }
   const titleLength = typeof title === 'string' ? utf8Length(title) : 0;
   const subtitleLength =
     typeof subtitle === 'string' ? utf8Length(subtitle) : Number.POSITIVE_INFINITY;
@@ -122,21 +150,16 @@ export function buildPro2NftBundle(options: {
     throw invalidParameter('Parameter [timestampMs] must be a positive safe integer.');
   }
 
-  const encodedImage = encodePro2Image({ ...image, alphaMode: 'black-background' }).data;
-  const encodedThumbnail = encodePro2Image({
-    ...thumbnail,
-    alphaMode: 'black-background',
-  }).data;
   const metadata = new TextEncoder().encode(JSON.stringify({ title, subtitle }));
   if (metadata.byteLength === 0 || metadata.byteLength > 512) {
     throw invalidParameter('Pro2 NFT metadata must contain 1 to 512 UTF-8 bytes.');
   }
 
-  const hash8 = bytesToHex(blake2s(encodedImage)).slice(0, 8);
+  const hash8 = bytesToHex(blake2s(image)).slice(0, 8);
   return {
     basename: `nft-${hash8}-${timestampMs}`,
-    image: encodedImage,
-    thumbnail: encodedThumbnail,
+    image,
+    thumbnail,
     metadata,
   };
 }