@onekeyfe/hd-core 1.2.0-alpha.107 → 1.2.0-alpha.109

package/src/device/Device.ts

@@ -61,6 +61,7 @@ import {
   PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
   type ProtocolV2RuntimeMode,
   getProtocolV2RuntimeMode,
+  isLegacyProtocolV2ProtocolInfo,
   requestProtocolV2DeviceInfo,
   requestProtocolV2DeviceStatus,
   requestProtocolV2ProtocolInfo,
@@ -485,6 +486,10 @@ export class Device extends EventEmitter {
       }
 
       this.commands = new DeviceCommands(this, this.mainId ?? '');
+      // Protocol V2 runtime metadata belongs to one active transport link. A
+      // successful acquire creates a fresh link/session, so never carry cached
+      // ProtocolInfo or pre-initialize state across that boundary.
+      this.invalidateProtocolV2RuntimeState();
     } catch (error) {
       if (options?.forceProtocolDetection) {
         this.originalDescriptor.protocolType = previousProtocol;
@@ -977,11 +982,7 @@ 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
-      );
-      Log.debug('Protocol V2 features:', features);
+      await this.probeProtocolV2RuntimeState(deviceInfo, options?.protocolV2DeviceInfoTimeoutMs);
     } catch (error) {
       Log.error('Protocol V2 initialization failed:', error);
       throw error;
@@ -1053,7 +1054,13 @@ 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',
+        });
       }
 
       if (refresh.has('settings') && this.state?.status.mode === 'normal') {
@@ -1101,9 +1108,10 @@ export class Device extends EventEmitter {
       source,
       changedKeys: result.changedKeys,
     };
-    Log.debug('Device state patch committed', {
+    Log.debug('Device state updated', {
       source,
-      keys: result.changedKeys,
+      revision: result.revision,
+      changedKeyCount: result.changedKeys.length,
     });
     this.emit(DEVICE.STATE, this, event);
     if (result.state.protocol === 'V1') {
@@ -1124,12 +1132,17 @@ export class Device extends EventEmitter {
     return this.features;
   }
 
-  async ensureProtocolV2RuntimeContext(timeoutMs?: number): Promise<ProtocolInfo> {
+  async ensureProtocolV2RuntimeContext(
+    timeoutMs?: number,
+    options?: { forceRefresh?: boolean }
+  ): Promise<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;
@@ -1169,10 +1182,19 @@ export class Device extends EventEmitter {
     }
   }
 
-  async probeProtocolV2RuntimeState(deviceInfo?: ProtocolV2DeviceInfo, timeoutMs?: number) {
-    const protocolInfo = await this.ensureProtocolV2RuntimeContext(timeoutMs);
-    const runtimeMode = getProtocolV2RuntimeMode(protocolInfo);
+  async probeProtocolV2RuntimeState(
+    deviceInfo?: ProtocolV2DeviceInfo,
+    timeoutMs?: number,
+    options?: {
+      forceRuntimeContextRefresh?: boolean;
+    }
+  ) {
+    const protocolInfo = await this.ensureProtocolV2RuntimeContext(timeoutMs, {
+      forceRefresh: options?.forceRuntimeContextRefresh,
+    });
     const runtimeDeviceInfo = deviceInfo ?? this.state?.raw?.protocolV2DeviceInfo;
+    const runtimeMode = getProtocolV2RuntimeMode(protocolInfo, runtimeDeviceInfo);
+    const legacyProtocolInfo = isLegacyProtocolV2ProtocolInfo(protocolInfo);
     const protocolV2DeviceType = runtimeDeviceInfo
       ? resolveProtocolV2DeviceIdentity(runtimeDeviceInfo.hw?.Device_type).deviceType
       : this.getCurrentDeviceType();
@@ -1186,10 +1208,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);
@@ -1250,8 +1271,7 @@ export class Device extends EventEmitter {
     });
   }
 
-  markTransportDisconnected() {
-    this.deviceAcquired = false;
+  private invalidateProtocolV2RuntimeState() {
     if (!this.isProtocolV2()) return;
     this.protocolV2StateNeedsReload = true;
     this.protocolV2RuntimeContext = undefined;
@@ -1260,6 +1280,11 @@ export class Device extends EventEmitter {
     this.clearPreInitialized();
   }
 
+  markTransportDisconnected() {
+    this.deviceAcquired = false;
+    this.invalidateProtocolV2RuntimeState();
+  }
+
   invalidateAfterWipe() {
     const deviceId = this.getCurrentDeviceId();
     if (deviceId) {
@@ -1269,10 +1294,7 @@ export class Device extends EventEmitter {
       if (this.originalDescriptor.path !== deviceId) {
         deviceWalletSessionStore.deleteDevice(this.originalDescriptor.path);
       }
-      this.protocolV2StateNeedsReload = true;
-      this.protocolV2RuntimeContext = undefined;
-      this.protocolV2RuntimeContextPromise = undefined;
-      this.protocolV2RuntimeContextRequestToken = undefined;
+      this.invalidateProtocolV2RuntimeState();
     }
 
     this.passphraseState = undefined;
@@ -1284,11 +1306,7 @@ export class Device extends EventEmitter {
   markProtocolV2Reboot(rebootType: DeviceRebootType) {
     if (!this.isProtocolV2()) return;
 
-    this.protocolV2StateNeedsReload = true;
-    this.protocolV2RuntimeContext = undefined;
-    this.protocolV2RuntimeContextPromise = undefined;
-    this.protocolV2RuntimeContextRequestToken = undefined;
-    this.clearPreInitialized();
+    this.invalidateProtocolV2RuntimeState();
     let loaderMode: 'bootloader' | 'romloader' | undefined;
     if (rebootType === DeviceRebootType.Bootloader) {
       loaderMode = 'bootloader';
@@ -1362,6 +1380,10 @@ export class Device extends EventEmitter {
     if (device.features) {
       this._updateFeatures(device.features);
     }
+    // Adopting another Device instance's command channel also crosses an active
+    // link boundary. Renegotiate runtime metadata on that channel instead of
+    // retaining ProtocolInfo from the previous instance/session.
+    this.invalidateProtocolV2RuntimeState();
   }
 
   async run(fn?: () => Promise<void>, options?: RunOptions) {

package/src/device/DeviceCommands.ts

@@ -304,13 +304,6 @@ export class DeviceCommands {
       const promise = this.transport.call(this.mainId, type, msg ?? {}, options) as any;
       this.callPromise = promise;
       const res = await promise;
-      if (!shouldReduceDebug) {
-        LogCore.debug(
-          '[DeviceCommands] [call] Received',
-          res.type,
-          getSafeTransportLogPayload(res.message, res.type)
-        );
-      }
       return res;
     } catch (error) {
       LogCore.debug('[DeviceCommands] [call] Received error', {
@@ -445,13 +438,10 @@ export class DeviceCommands {
       if (!shouldReduceDebugForCall(callType)) {
         Log.debug('_filterCommonTypes: ', {
           request: callType,
-          response:
-            callType === 'DeviceFirmwareUpdateStatusGet'
-              ? {
-                  type: res.type,
-                  message: getSafeTransportLogPayload(res.message, res.type),
-                }
-              : res.type,
+          response: {
+            type: res.type,
+            message: getSafeTransportLogPayload(res.message, res.type),
+          },
         });
       }
     } catch (error) {

package/src/device/DevicePool.ts

@@ -218,9 +218,13 @@ export class DevicePool extends EventEmitter {
    * Device.getDeviceState skips unsupported status/settings calls in loader mode.
    */
   static async _refreshProtocolV2DiscoveryState(device: Device) {
-    await device.getDeviceState({ refreshSections: ['status'] });
+    await device.getDeviceState({
+      refreshSections: ['status'],
+    });
     try {
-      await device.getDeviceState({ refreshSections: ['settings'] });
+      await device.getDeviceState({
+        refreshSections: ['settings'],
+      });
     } catch (error) {
       Log.debug('Unable to refresh Protocol V2 device label during discovery', error);
     }

package/src/device/DeviceStateMapper.ts

@@ -267,11 +267,11 @@ export const mapProtocolV2DeviceInfoToState = (
         }
       : { mode },
     versions: definedEntries({
-      firmware: imageVersion(info.fw?.application),
-      applicationP1: imageVersion(info.fw?.application),
-      applicationP2: imageVersion(info.fw?.application_data),
-      bootloader: imageVersion(info.fw?.bootloader),
-      board: imageVersion(info.fw?.romloader),
+      firmware: imageVersion(info.main_mcu?.application),
+      applicationP1: imageVersion(info.main_mcu?.application),
+      applicationP2: imageVersion(info.main_mcu?.application_data),
+      bootloader: imageVersion(info.main_mcu?.bootloader),
+      board: imageVersion(info.main_mcu?.romloader),
       ble: imageVersion(info.coprocessor?.application),
       se01: imageVersion(info.se1?.application),
       se02: imageVersion(info.se2?.application),
@@ -283,16 +283,16 @@ export const mapProtocolV2DeviceInfoToState = (
       se04Boot: imageVersion(info.se4?.bootloader),
     }),
     verification: definedEntries({
-      firmwareBuildId: imageBuildId(info.fw?.application),
-      firmwareHash: imageHash(info.fw?.application),
-      applicationP1BuildId: imageBuildId(info.fw?.application),
-      applicationP1Hash: imageHash(info.fw?.application),
-      applicationP2BuildId: imageBuildId(info.fw?.application_data),
-      applicationP2Hash: imageHash(info.fw?.application_data),
-      bootloaderBuildId: imageBuildId(info.fw?.bootloader),
-      bootloaderHash: imageHash(info.fw?.bootloader),
-      boardBuildId: imageBuildId(info.fw?.romloader),
-      boardHash: imageHash(info.fw?.romloader),
+      firmwareBuildId: imageBuildId(info.main_mcu?.application),
+      firmwareHash: imageHash(info.main_mcu?.application),
+      applicationP1BuildId: imageBuildId(info.main_mcu?.application),
+      applicationP1Hash: imageHash(info.main_mcu?.application),
+      applicationP2BuildId: imageBuildId(info.main_mcu?.application_data),
+      applicationP2Hash: imageHash(info.main_mcu?.application_data),
+      bootloaderBuildId: imageBuildId(info.main_mcu?.bootloader),
+      bootloaderHash: imageHash(info.main_mcu?.bootloader),
+      boardBuildId: imageBuildId(info.main_mcu?.romloader),
+      boardHash: imageHash(info.main_mcu?.romloader),
       bleBuildId: imageBuildId(info.coprocessor?.application),
       bleHash: imageHash(info.coprocessor?.application),
       se01BuildId: imageBuildId(info.se1?.application),

package/src/deviceProfile/buildDeviceFeatures.ts

@@ -216,9 +216,9 @@ export const buildProtocolV2FeaturesPayload = ({
   runtimeMode?: ProtocolV2RuntimeMode;
 }): Features => {
   const info = deviceInfo;
-  const fwApplication = info?.fw?.application;
-  const fwBootloader = info?.fw?.bootloader;
-  const fwBoard = info?.fw?.romloader;
+  const fwApplication = info?.main_mcu?.application;
+  const fwBootloader = info?.main_mcu?.bootloader;
+  const fwBoard = info?.main_mcu?.romloader;
   const bleApplication = info?.coprocessor?.application;
   const status = deviceStatus;
   const incomingSerialNo = info?.hw?.serial_no;

package/src/events/logBlockEvent.ts

@@ -17,6 +17,14 @@ const LogLabelMethod: Set<string> = new Set([
   'fileRead',
 ]);
 
+// 资源上传参数可能包含很大的 Base64 字符串。这里按方法整段跳过，避免日志层
+// 递归复制和序列化这些数据；资源 API 与传输内容本身保持不变。
+const LogPayloadBlockMethod: Set<string> = new Set([
+  'deviceUploadNft',
+  'deviceUploadWallpaper',
+  'uploadPortfolio',
+]);
+
 const SensitiveLogKeys: Set<string> = new Set([
   'devicestate',
   'entropy',
@@ -86,7 +94,12 @@ export function getLogBlockLabel(message: unknown): string | undefined {
 }
 
 export function getSafeLogPayload(value: unknown, blockLabel?: string): unknown {
-  if (blockLabel && (LogBlockEvent.has(blockLabel) || isSigningMethod(blockLabel))) {
+  if (
+    blockLabel &&
+    (LogBlockEvent.has(blockLabel) ||
+      LogPayloadBlockMethod.has(blockLabel) ||
+      isSigningMethod(blockLabel))
+  ) {
     return { method: blockLabel, payload: '[REDACTED]' };
   }
 

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>
@@ -87,11 +97,18 @@ export const parseProtocolV2BuildFingerprint = (
 };
 
 export const getProtocolV2RuntimeMode = (
-  protocolInfo: ProtocolInfo
+  protocolInfo: ProtocolInfo,
+  deviceInfo?: ProtocolV2DeviceInfo
 ): ProtocolV2RuntimeMode | undefined => {
   const binary = parseProtocolV2BuildFingerprint(protocolInfo.build_fingerprint)?.binary;
   if (binary === 'application') return 'normal';
-  return binary;
+  if (binary) return binary;
+
+  if (isLegacyProtocolV2ProtocolInfo(protocolInfo) && !deviceInfo?.main_mcu?.application) {
+    if (deviceInfo?.main_mcu?.romloader) return 'romloader';
+    if (deviceInfo?.main_mcu?.bootloader) return 'bootloader';
+  }
+  return undefined;
 };
 
 // MessageType_DeviceStatusGet in the Protocol V2 protobuf registry.
@@ -105,7 +122,7 @@ export const supportsProtocolV2Message = (
 export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
   targets: {
     hw: true,
-    fw: true,
+    main_mcu: true,
     coprocessor: true,
   },
   types: {
@@ -121,7 +138,7 @@ export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
 export const PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST = {
   targets: {
     hw: true,
-    fw: true,
+    main_mcu: true,
     coprocessor: true,
     se1: true,
     se2: true,
@@ -137,7 +154,7 @@ export const PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST = {
 export const PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST = {
   targets: {
     hw: true,
-    fw: true,
+    main_mcu: true,
     coprocessor: true,
     se1: true,
     se2: true,

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/protocols/protocol-v2/resources.ts

@@ -107,10 +107,10 @@ function parseProtocolV2ResourceManifestFile(
   }
   const file = value as Partial<IProtocolV2ResourceManifestFile>;
   const archivePath = assertManifestRelativePath(file.archive_path, `files[${index}].archive_path`);
-  const originalName = assertManifestRelativePath(
-    file.original_name,
-    `files[${index}].original_name`
-  );
+  const originalName =
+    file.original_name === undefined
+      ? archivePath.split('/').pop() ?? archivePath
+      : assertManifestRelativePath(file.original_name, `files[${index}].original_name`);
   if (originalName.includes('/')) {
     throw new Error(`Invalid Pro2 resource manifest files[${index}].original_name`);
   }
@@ -122,15 +122,6 @@ function parseProtocolV2ResourceManifestFile(
     throw new Error(`Invalid Pro2 resource manifest files[${index}].size`);
   }
   const digest = normalizeHex(file.sha256, SHA256_HEX_LENGTH, `files[${index}].sha256`);
-  if (file.signed !== true) {
-    throw new Error(`Invalid Pro2 resource manifest files[${index}].signed`);
-  }
-  if (file.sig_algo !== 'ed25519' && file.sig_algo !== 'mldsa65') {
-    throw new Error(`Invalid Pro2 resource manifest files[${index}].sig_algo`);
-  }
-  if (file.payload_version !== null && typeof file.payload_version !== 'string') {
-    throw new Error(`Invalid Pro2 resource manifest files[${index}].payload_version`);
-  }
   if (!archivePath.endsWith('.okpkg') || !originalName.endsWith('.okpkg')) {
     throw new Error(`Invalid Pro2 resource manifest files[${index}] package extension`);
   }
@@ -140,9 +131,9 @@ function parseProtocolV2ResourceManifestFile(
     device_path: devicePath,
     size: Number(file.size),
     sha256: digest,
-    signed: true,
-    sig_algo: file.sig_algo,
-    payload_version: file.payload_version ?? null,
+    ...(file.signed === undefined ? {} : { signed: file.signed }),
+    ...(file.sig_algo === undefined ? {} : { sig_algo: file.sig_algo }),
+    ...(file.payload_version === undefined ? {} : { payload_version: file.payload_version }),
   };
 }
 
@@ -151,15 +142,8 @@ export function parseProtocolV2ResourceManifest(value: unknown): IProtocolV2Reso
     throw new Error('Invalid Pro2 resource manifest');
   }
   const manifest = value as Partial<IProtocolV2ResourceManifest>;
-  if (
-    manifest.schema !== 1 ||
-    manifest.variant !== 'resource' ||
-    manifest.device_root !== 'vol0:' ||
-    manifest.restore_mode !== 'bootloader_update' ||
-    !Array.isArray(manifest.trees) ||
-    !Array.isArray(manifest.files)
-  ) {
-    throw new Error('Invalid Pro2 resource manifest contract');
+  if (!Array.isArray(manifest.files)) {
+    throw new Error('Invalid Pro2 resource manifest files');
   }
   const files = manifest.files.map(parseProtocolV2ResourceManifestFile);
   const devicePaths = new Set(files.map(file => file.device_path));
@@ -174,27 +158,6 @@ export function parseProtocolV2ResourceManifest(value: unknown): IProtocolV2Reso
     throw new Error('Invalid Pro2 resource manifest file set');
   }
   return {
-    schema: 1,
-    artifact_name: assertManifestString(manifest.artifact_name, 'artifact_name'),
-    release_name: assertManifestString(manifest.release_name, 'release_name'),
-    variant: 'resource',
-    commit: assertManifestString(manifest.commit, 'commit'),
-    short_sha: assertManifestString(manifest.short_sha, 'short_sha'),
-    timestamp_utc: assertManifestString(manifest.timestamp_utc, 'timestamp_utc'),
-    core_version: assertManifestString(manifest.core_version, 'core_version'),
-    key_set: assertManifestString(manifest.key_set, 'key_set'),
-    device_root: 'vol0:',
-    restore_mode: 'bootloader_update',
-    trees: manifest.trees.map((tree, index) => {
-      if (!tree || typeof tree !== 'object') {
-        throw new Error(`Invalid Pro2 resource manifest trees[${index}]`);
-      }
-      const item = tree as { path?: unknown; device?: unknown };
-      return {
-        path: assertManifestRelativePath(item.path, `trees[${index}].path`),
-        device: assertManifestString(item.device, `trees[${index}].device`),
-      };
-    }),
     files,
   };
 }

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/types/settings.ts

@@ -76,31 +76,16 @@ export type IProtocolV2Resources = {
 
 export type IProtocolV2ResourceManifestFile = {
   archive_path: string;
-  original_name: string;
+  original_name?: string;
   device_path: string;
   size: number;
   sha256: string;
-  signed: true;
-  sig_algo: 'ed25519' | 'mldsa65';
-  payload_version: string | null;
+  signed?: boolean;
+  sig_algo?: string;
+  payload_version?: string | null;
 };
 
 export type IProtocolV2ResourceManifest = {
-  schema: 1;
-  artifact_name: string;
-  release_name: string;
-  variant: 'resource';
-  commit: string;
-  short_sha: string;
-  timestamp_utc: string;
-  core_version: string;
-  key_set: string;
-  device_root: 'vol0:';
-  restore_mode: 'bootloader_update';
-  trees: Array<{
-    path: string;
-    device: string;
-  }>;
   files: IProtocolV2ResourceManifestFile[];
 };
 

package/src/utils/deviceSettings.ts

@@ -200,7 +200,7 @@ export const getAutoShutDownOptions = (
       return withNever([60_000, 120_000, 300_000, 600_000], protocol);
     case EDeviceType.Pro2:
     case EDeviceType.Neo:
-      return withNever([60_000, 120_000, 300_000, 600_000, 1_800_000], protocol);
+      return withNever([60_000, 120_000, 300_000, 600_000], protocol);
     default:
       return [];
   }

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,
   };
 }