@onekeyfe/hd-core 1.2.0-alpha.67 → 1.2.0-alpha.68

package/src/types/api/index.ts

@@ -1,6 +1,7 @@
 import type {
   deviceGetOnboardingStatus,
   deviceReboot,
+  deviceUploadNft,
   deviceUploadWallpaper,
   testProtocolV2Ping,
   uploadPortfolio,
@@ -18,6 +19,7 @@ import type { checkBootloaderRelease } from './checkBootloaderRelease';
 import type { checkAllFirmwareRelease } from './checkAllFirmwareRelease';
 import type { checkFirmwareTypeAvailable } from './checkFirmwareTypeAvailable';
 import type { searchDevices } from './searchDevices';
+import type { detectDeviceConnectProtocol } from './detectDeviceConnectProtocol';
 import type { getFeatures } from './getFeatures';
 import type { getDeviceState } from './getDeviceState';
 import type { getOnekeyFeatures } from './getOnekeyFeatures';
@@ -152,6 +154,7 @@ import type { benfenSignMessage } from './benfenSignMessage';
 import type { neoGetAddress } from './neoGetAddress';
 import type { neoSignTransaction } from './neoSignTransaction';
 import type { ConnectSettings } from '../settings';
+import type { HardwareConnectProtocol } from '@onekeyfe/hd-shared';
 
 export * from './export';
 export type { DeviceStateScope, GetDeviceStateParams } from './getDeviceState';
@@ -176,6 +179,14 @@ export type CoreApi = {
   removeAllListeners: typeof removeAllListeners;
   dispose: () => void | Promise<void>;
   call: (params: any) => Promise<any>;
+  /**
+   * Bind a protocol that has already been verified for one transport endpoint.
+   * Every later SDK call for the same connectId uses it as a strict expectation.
+   */
+  setDeviceConnectProtocol: (
+    connectId: string,
+    connectProtocol: HardwareConnectProtocol | undefined
+  ) => void;
   uiResponse: typeof uiResponse;
   cancel: (connectId?: string) => void;
   updateSettings: typeof updateSettings;
@@ -203,6 +214,7 @@ export type CoreApi = {
    * Device function
    */
   searchDevices: typeof searchDevices;
+  detectDeviceConnectProtocol: typeof detectDeviceConnectProtocol;
   promptWebDeviceAccess: typeof promptWebDeviceAccess;
   getFeatures: typeof getFeatures;
   getDeviceState: typeof getDeviceState;
@@ -248,6 +260,7 @@ export type CoreApi = {
    */
   deviceReboot: typeof deviceReboot;
   deviceGetOnboardingStatus: typeof deviceGetOnboardingStatus;
+  deviceUploadNft: typeof deviceUploadNft;
   deviceUploadWallpaper: typeof deviceUploadWallpaper;
   uploadPortfolio: typeof uploadPortfolio;
 

package/src/types/api/protocolV2.ts

@@ -5,6 +5,10 @@ import type {
   DeviceUploadWallpaperParams,
   DeviceUploadWallpaperResponse,
 } from '../../api/protocol-v2/DeviceUploadWallpaper';
+import type {
+  DeviceUploadNftParams,
+  DeviceUploadNftResponse,
+} from '../../api/protocol-v2/DeviceUploadNft';
 
 // Re-export implementation parameter types as the single source of truth.
 export type { DeviceRebootParams, RebootTypeInput } from '../../api/protocol-v2/helpers';
@@ -12,6 +16,10 @@ export type {
   DeviceUploadWallpaperParams,
   DeviceUploadWallpaperResponse,
 } from '../../api/protocol-v2/DeviceUploadWallpaper';
+export type {
+  DeviceUploadNftParams,
+  DeviceUploadNftResponse,
+} from '../../api/protocol-v2/DeviceUploadNft';
 
 // ── Shared response shapes (Protocol V2 file system) ────────────────────
 
@@ -52,6 +60,11 @@ export declare function deviceUploadWallpaper(
   params: CommonParams & DeviceUploadWallpaperParams
 ): Response<DeviceUploadWallpaperResponse>;
 
+export declare function deviceUploadNft(
+  connectId: string,
+  params: CommonParams & DeviceUploadNftParams
+): Response<DeviceUploadNftResponse>;
+
 export declare function uploadPortfolio(
   connectId: string,
   params: {

package/src/types/device.ts

@@ -210,7 +210,9 @@ export type DeviceStateStatus = {
   recoveryMode: boolean | null;
   passphraseProtection: boolean | null;
   pinProtection: boolean | null;
+  /** `attach_to_pin_enabled`：是否至少存在一个 Attach PIN 绑定。 */
   attachToPinEnabled: boolean | null;
+  /** `unlocked_by_attach_to_pin`：本次解锁是否由 Attach PIN 完成。 */
   unlockedAttachPin: boolean | null;
 };
 
@@ -321,6 +323,7 @@ export type NormalizedFeatures = {
   sdProtection: boolean | null;
   wipeCodeProtection: boolean | null;
   passphraseAlwaysOnDevice: boolean | null;
+  /** `attach_to_pin_enabled`：是否至少存在一个 Attach PIN 绑定。 */
   attachToPinEnabled?: boolean | null;
   safetyChecks: Enum_SafetyCheckLevel | null;
   autoLockDelayMs: number | null;
@@ -371,14 +374,21 @@ export type IDeviceType =
   | EDeviceType.Mini
   | EDeviceType.Touch
   | EDeviceType.Pro
-  | EDeviceType.Pro2;
+  | EDeviceType.Pro2
+  | EDeviceType.Neo;
 
 /**
  * model_classic: 'classic' | 'classic1s' | 'classicpure'
  * model_mini: 'classic' | 'classic1s' | 'classicpure' | 'mini'
  * model_touch: 'touch' | 'pro'
+ * model_pro2: 'pro2' | 'neo'
  */
-export type IDeviceModel = 'model_classic' | 'model_mini' | 'model_touch' | 'model_classic1s';
+export type IDeviceModel =
+  | 'model_classic'
+  | 'model_mini'
+  | 'model_touch'
+  | 'model_classic1s'
+  | 'model_pro2';
 
 export const DeviceModelToTypes: { [deviceModel in IDeviceModel]: IDeviceType[] } = {
   model_mini: [
@@ -388,6 +398,7 @@ export const DeviceModelToTypes: { [deviceModel in IDeviceModel]: IDeviceType[]
     EDeviceType.Mini,
   ],
   model_touch: [EDeviceType.Touch, EDeviceType.Pro],
+  model_pro2: [EDeviceType.Pro2, EDeviceType.Neo],
   model_classic: [EDeviceType.Classic, EDeviceType.Classic1s, EDeviceType.ClassicPure],
   model_classic1s: [EDeviceType.Classic1s, EDeviceType.ClassicPure],
 };
@@ -399,7 +410,8 @@ export const DeviceTypeToModels: { [deviceType in IDeviceType]: IDeviceModel[] }
   [EDeviceType.Mini]: ['model_mini'],
   [EDeviceType.Touch]: ['model_touch'],
   [EDeviceType.Pro]: ['model_touch'],
-  [EDeviceType.Pro2]: [],
+  [EDeviceType.Pro2]: ['model_pro2'],
+  [EDeviceType.Neo]: ['model_pro2'],
   [EDeviceType.Unknown]: [],
 };
 

package/src/types/params.ts

@@ -61,9 +61,15 @@ export interface CommonParams {
 
   /**
    * Strictly expected transport protocol. The SDK actively verifies this value and
-   * rejects a mismatch. If omitted, a cached protocol only influences probe order.
+   * rejects a mismatch. After a successful probe, the cached protocol is also strict.
    */
   connectProtocol?: HardwareConnectProtocol;
+
+  /**
+   * Ignore a previously bound protocol for this call and actively detect the
+   * protocol again. Intended for the first verified connection or explicit recovery.
+   */
+  forceProtocolDetection?: boolean;
 }
 
 export type Params<T> = CommonParams & T & { bundle?: undefined };

package/src/types/settings.ts

@@ -64,6 +64,49 @@ export type IProtocolV2FirmwareComponent = {
   version?: IVersionArray;
 };
 
+export type IProtocolV2ResourceType =
+  | 'images'
+  | 'animation'
+  | 'wallpaper'
+  | 'translations'
+  | 'roobert'
+  | 'noto';
+
+/** Pro2 RES package descriptor. Hashes identify content without a human-managed version. */
+export type IProtocolV2Resource = {
+  type: IProtocolV2ResourceType;
+  url: string;
+  /** Complete okpkg file size in bytes. */
+  size: number;
+  /** SHA-256 of the complete okpkg file. */
+  fileHash: string;
+  /** SHA3-512 header_hash from the signed okpkg header. */
+  headerHash: string;
+};
+
+/** A file from the Protocol V2 resource manifest, written directly with FileWrite. */
+export type IProtocolV2ResourceFile = {
+  name?: string;
+  url: string;
+  devicePath: string;
+  size: number;
+  /** SHA-256 of the complete file. */
+  fileHash: string;
+};
+
+/** Optional Protocol V2 boot resources restored as individual files. */
+export type IProtocolV2BootResources = {
+  required: false;
+  target: 'RES';
+  manifestUrl?: string;
+  files: IProtocolV2ResourceFile[];
+};
+
+export type IProtocolV2Resources = {
+  stable: IProtocolV2Resource[];
+  boot?: IProtocolV2BootResources;
+};
+
 /** Pro2 RESC bundle okpkg descriptor for incremental FileWrite synchronization. */
 export type IProtocolV2ResourceBundle = {
   /** Bundle name, such as images, animation, translations, or fonts_roobert. */
@@ -139,17 +182,25 @@ export type IBLEFirmwareReleaseInfo = {
 };
 
 type IKnownDevice = Exclude<IDeviceType, 'unknown'>;
+type ILegacyKnownDevice = Exclude<IKnownDevice, 'neo'>;
+
+type IDeviceReleaseInfo = {
+  firmware: IFirmwareReleaseInfo[];
+  /** Protocol V2 payload package set */
+  'firmware-v1'?: IFirmwareReleaseInfo[];
+  'firmware-v2'?: IFirmwareReleaseInfo[];
+  'firmware-v8'?: IFirmwareReleaseInfo[];
+  'firmware-btc-v8'?: IFirmwareReleaseInfo[];
+  ble: IBLEFirmwareReleaseInfo[];
+  /** Independent Protocol V2 resource release configuration. */
+  resources?: IProtocolV2Resources;
+};
 
 export type DeviceTypeMap = {
-  [k in IKnownDevice]: {
-    firmware: IFirmwareReleaseInfo[];
-    /** Pro2 Protocol V2 payload package set */
-    'firmware-v1'?: IFirmwareReleaseInfo[];
-    'firmware-v2'?: IFirmwareReleaseInfo[];
-    'firmware-v8'?: IFirmwareReleaseInfo[];
-    'firmware-btc-v8'?: IFirmwareReleaseInfo[];
-    ble: IBLEFirmwareReleaseInfo[];
-  };
+  [k in ILegacyKnownDevice]: IDeviceReleaseInfo;
+} & {
+  /** Optional until every remote-config producer publishes a Neo entry. */
+  neo?: IDeviceReleaseInfo;
 };
 
 export type AssetsMap = {

package/src/utils/deviceFeaturesCompat.ts

@@ -66,6 +66,8 @@ export const resolveDeviceType = (features?: DeviceFeaturesInput): IDeviceType =
       return EDeviceType.Pro;
     case 'PRO2':
       return EDeviceType.Pro2;
+    case 'NEO':
+      return EDeviceType.Neo;
     case 'PURE':
       return EDeviceType.ClassicPure;
     default:
@@ -75,6 +77,9 @@ export const resolveDeviceType = (features?: DeviceFeaturesInput): IDeviceType =
   if (compatible.model?.toString().toLowerCase() === EDeviceType.Pro2) {
     return EDeviceType.Pro2;
   }
+  if (compatible.model?.toString().toLowerCase() === EDeviceType.Neo) {
+    return EDeviceType.Neo;
+  }
 
   const serialNo = resolveDeviceSerialNo(features);
   const prefix = serialNo.slice(0, 2).toLowerCase();

package/src/utils/deviceFeaturesUtils.ts

@@ -74,7 +74,8 @@ export const supportInputPinOnSoftware = (features?: Features): SupportFeatureTy
   if (
     deviceType === EDeviceType.Touch ||
     deviceType === EDeviceType.Pro ||
-    deviceType === EDeviceType.Pro2
+    deviceType === EDeviceType.Pro2 ||
+    deviceType === EDeviceType.Neo
   ) {
     return { support: false };
   }
@@ -90,7 +91,8 @@ export const supportNewPassphrase = (features?: Features): SupportFeatureType =>
   if (
     deviceType === EDeviceType.Touch ||
     deviceType === EDeviceType.Pro ||
-    deviceType === EDeviceType.Pro2
+    deviceType === EDeviceType.Pro2 ||
+    deviceType === EDeviceType.Neo
   ) {
     return { support: true };
   }
@@ -106,6 +108,8 @@ export const getPassphraseStateWithRefreshDeviceInfo = async (
     expectPassphraseState?: string;
     onlyMainPin?: boolean;
     initSession?: boolean;
+    deriveCardano?: boolean;
+    rejectAttachPinForMainWallet?: boolean;
   }
 ) => {
   if (device.isProtocolV2()) {
@@ -121,6 +125,8 @@ export const getPassphraseStateWithRefreshDeviceInfo = async (
       initSession: options?.initSession,
       expectedPassphraseState: options?.expectPassphraseState,
       onlyMainPin: options?.onlyMainPin,
+      deriveCardano: options?.deriveCardano,
+      rejectAttachPinForMainWallet: options?.rejectAttachPinForMainWallet,
     });
   }
 
@@ -139,7 +145,8 @@ export const getPassphraseStateWithRefreshDeviceInfo = async (
   const isModeT =
     deviceType === EDeviceType.Touch ||
     deviceType === EDeviceType.Pro ||
-    deviceType === EDeviceType.Pro2;
+    deviceType === EDeviceType.Pro2 ||
+    deviceType === EDeviceType.Neo;
 
   // 如果可以获取到 passphraseState，但是设备 features 显示设备未开启 passphrase，需要刷新设备状态
   // if passphraseState can be obtained, but the device features show that the device has not enabled passphrase, the device status needs to be refreshed
@@ -185,6 +192,8 @@ export const getPassphraseState = async (
     expectPassphraseState?: string;
     onlyMainPin?: boolean;
     initSession?: boolean;
+    deriveCardano?: boolean;
+    rejectAttachPinForMainWallet?: boolean;
   }
 ): Promise<{
   passphraseState: string | undefined;
@@ -205,6 +214,8 @@ export const getPassphraseState = async (
       initSession: options?.initSession,
       expectedPassphraseState: options?.expectPassphraseState,
       onlyMainPin: options?.onlyMainPin,
+      deriveCardano: options?.deriveCardano,
+      rejectAttachPinForMainWallet: options?.rejectAttachPinForMainWallet,
     });
   }
 

package/src/utils/deviceInfoUtils.ts

@@ -31,6 +31,7 @@ export const getDeviceTypeByBleName = (name?: string): IDeviceType => {
   if (/^Touch/i.test(name)) return EDeviceType.Touch;
 
   if (/\bPro\s*2\b/i.test(name) || /^Pro2/i.test(name)) return EDeviceType.Pro2;
+  if (/\bNeo\b/i.test(name) || /^Neo/i.test(name)) return EDeviceType.Neo;
   if (/\bPro\b/i.test(name) || /^Pro/i.test(name)) return EDeviceType.Pro;
 
   return EDeviceType.Unknown;
@@ -93,6 +94,7 @@ export const getMethodVersionRange = (
   }
 
   const modelFallbacks: IDeviceModel[] = [
+    'model_pro2',
     'model_classic1s',
     'model_classic',
     'model_mini',

package/src/utils/deviceSettings.ts

@@ -127,6 +127,7 @@ export const getLanguageConfig = (deviceType: IDeviceType): Record<string, strin
       keys = Object.keys(LANGUAGE_LABELS) as LanguageKey[];
       break;
     case EDeviceType.Pro2:
+    case EDeviceType.Neo:
       return PRO2_LANGUAGE_OPTIONS.map(option => ({ ...option }));
     default:
       keys = [];
@@ -176,6 +177,7 @@ export const getAutoLockOptions = (
     case EDeviceType.Touch:
     case EDeviceType.Pro:
     case EDeviceType.Pro2:
+    case EDeviceType.Neo:
       return withNever([30_000, 60_000, 120_000, 300_000, 600_000, 1_800_000], protocol);
     default:
       return [];
@@ -197,6 +199,7 @@ export const getAutoShutDownOptions = (
     case EDeviceType.Pro:
       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);
     default:
       return [];

package/src/utils/homescreen.ts

@@ -4,6 +4,12 @@ import { EDeviceType } from '@onekeyfe/hd-shared';
 import { getDeviceType } from './deviceInfoUtils';
 import { getDeviceFirmwareVersion } from './deviceVersionUtils';
 import { PRO2_WALLPAPER_HEIGHT, PRO2_WALLPAPER_WIDTH } from './pro2Wallpaper';
+import {
+  PRO2_NFT_IMAGE_HEIGHT,
+  PRO2_NFT_IMAGE_WIDTH,
+  PRO2_NFT_THUMBNAIL_HEIGHT,
+  PRO2_NFT_THUMBNAIL_WIDTH,
+} from './pro2Nft';
 
 import type { Features, IDeviceType } from '../types';
 
@@ -302,6 +308,31 @@ type SizeConfig = {
   radius?: number;
 };
 
+export const getNftSize = ({
+  deviceType,
+  thumbnail,
+}: {
+  deviceType: IDeviceType;
+  thumbnail?: boolean;
+}): SizeConfig | undefined => {
+  const sizes: Partial<Record<IDeviceType, { full: SizeConfig; thumbnail: SizeConfig }>> = {
+    touch: {
+      full: { width: 480, height: 800 },
+      thumbnail: { width: 238, height: 238 },
+    },
+    pro: {
+      full: { width: 480, height: 800 },
+      thumbnail: { width: 226, height: 226, radius: 40 },
+    },
+    pro2: {
+      full: { width: PRO2_NFT_IMAGE_WIDTH, height: PRO2_NFT_IMAGE_HEIGHT },
+      thumbnail: { width: PRO2_NFT_THUMBNAIL_WIDTH, height: PRO2_NFT_THUMBNAIL_HEIGHT },
+    },
+  };
+
+  return sizes[deviceType]?.[thumbnail ? 'thumbnail' : 'full'];
+};
+
 export const getHomeScreenSize = ({
   deviceType,
   homeScreenType,
@@ -312,12 +343,7 @@ export const getHomeScreenSize = ({
   thumbnail?: boolean;
 }) => {
   if (deviceType === EDeviceType.Pro2) {
-    return thumbnail
-      ? undefined
-      : {
-          width: PRO2_WALLPAPER_WIDTH,
-          height: PRO2_WALLPAPER_HEIGHT,
-        };
+    return thumbnail ? undefined : { width: PRO2_WALLPAPER_WIDTH, height: PRO2_WALLPAPER_HEIGHT };
   }
 
   const sizes: Partial<

package/src/utils/index.ts

@@ -54,7 +54,12 @@ export { getHDPath, getScriptType, getOutputScriptType } from '../api/helpers/pa
 
 export const isBleConnect = (env: string) => env === 'react-native' || env === 'lowlevel';
 
-export { getHomeScreenHex, getHomeScreenDefaultList, getHomeScreenSize } from './homescreen';
+export {
+  getHomeScreenHex,
+  getHomeScreenDefaultList,
+  getHomeScreenSize,
+  getNftSize,
+} from './homescreen';
 export { encodePro2Wallpaper, PRO2_WALLPAPER_HEIGHT, PRO2_WALLPAPER_WIDTH } from './pro2Wallpaper';
 export type { Pro2WallpaperColorFormat } from './pro2Wallpaper';
 

package/src/utils/pro2Nft.ts

@@ -0,0 +1,142 @@
+import { blake2s } from '@noble/hashes/blake2s';
+import { bytesToHex } from '@noble/hashes/utils';
+
+import { invalidParameter } from '../api/helpers/filesystemValidation';
+import { encodePro2Image } from './pro2Wallpaper';
+
+export const PRO2_NFT_IMAGE_WIDTH = 540;
+export const PRO2_NFT_IMAGE_HEIGHT = 540;
+export const PRO2_NFT_THUMBNAIL_WIDTH = 263;
+export const PRO2_NFT_THUMBNAIL_HEIGHT = 263;
+export const PRO2_NFT_DIRECTORY = 'vol1:/nft';
+export const PRO2_NFT_DEFAULT_CHUNK_SIZE = 2048;
+export const PRO2_NFT_DEFAULT_PACE_MS = 0;
+export const PRO2_NFT_DEFAULT_TIMEOUT_MS = 15_000;
+export const PRO2_NFT_MIN_CHUNK_SIZE = 64;
+export const PRO2_NFT_MAX_CHUNK_SIZE = 2048;
+export const PRO2_NFT_MAX_ITEMS = 10;
+
+export type Pro2NftImage = {
+  width: number;
+  height: number;
+  rgba: Uint8Array | ArrayBuffer;
+};
+
+export type Pro2NftBundle = {
+  basename: string;
+  image: Uint8Array;
+  thumbnail: Uint8Array;
+  metadata: Uint8Array;
+};
+
+const PRO2_NFT_BASENAME_PATTERN = /^nft-[0-9a-f]{8}-[1-9][0-9]*$/;
+
+type Pro2NftFileType = 'image' | 'thumbnail' | 'metadata';
+
+function parsePro2NftFile(listedPath: string):
+  | {
+      basename: string;
+      fileType: Pro2NftFileType;
+    }
+  | undefined {
+  const filename = listedPath.trim().split('/').at(-1);
+  if (!filename) return undefined;
+
+  let basename: string | undefined;
+  let fileType: Pro2NftFileType | undefined;
+  if (filename.endsWith('_m.bin')) {
+    basename = filename.slice(0, -'_m.bin'.length);
+    fileType = 'thumbnail';
+  } else if (filename.endsWith('.json')) {
+    basename = filename.slice(0, -'.json'.length);
+    fileType = 'metadata';
+  } else if (filename.endsWith('.bin')) {
+    basename = filename.slice(0, -'.bin'.length);
+    fileType = 'image';
+  }
+
+  return basename && fileType && PRO2_NFT_BASENAME_PATTERN.test(basename)
+    ? { basename, fileType }
+    : undefined;
+}
+
+export function getCompletePro2NftBasenames(childFiles?: string): Set<string> {
+  const filesByBasename = new Map<string, Set<Pro2NftFileType>>();
+
+  for (const listedPath of childFiles?.split('\n') ?? []) {
+    const file = parsePro2NftFile(listedPath);
+    if (file) {
+      const fileTypes = filesByBasename.get(file.basename) ?? new Set<Pro2NftFileType>();
+      fileTypes.add(file.fileType);
+      filesByBasename.set(file.basename, fileTypes);
+    }
+  }
+
+  return new Set(
+    [...filesByBasename.entries()]
+      .filter(([, fileTypes]) => fileTypes.size === 3)
+      .map(([basename]) => basename)
+  );
+}
+
+function utf8Length(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function assertImage(
+  name: string,
+  image: Pro2NftImage,
+  expectedWidth: number,
+  expectedHeight: number
+) {
+  if (image.width !== expectedWidth || image.height !== expectedHeight) {
+    throw invalidParameter(
+      `Pro2 NFT ${name} dimensions must be ${expectedWidth}x${expectedHeight}.`
+    );
+  }
+  if (!(image.rgba instanceof ArrayBuffer) && !ArrayBuffer.isView(image.rgba)) {
+    throw invalidParameter(`Parameter [${name}.rgba] must be an ArrayBuffer or Uint8Array.`);
+  }
+}
+
+export function buildPro2NftBundle(options: {
+  image: Pro2NftImage;
+  thumbnail: Pro2NftImage;
+  title: string;
+  subtitle: string;
+  timestampMs: number;
+}): Pro2NftBundle {
+  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 titleLength = typeof title === 'string' ? utf8Length(title) : 0;
+  const subtitleLength =
+    typeof subtitle === 'string' ? utf8Length(subtitle) : Number.POSITIVE_INFINITY;
+  if (titleLength < 1 || titleLength > 63) {
+    throw invalidParameter('Pro2 NFT title must contain 1 to 63 UTF-8 bytes.');
+  }
+  if (subtitleLength > 95) {
+    throw invalidParameter('Pro2 NFT subtitle must contain at most 95 UTF-8 bytes.');
+  }
+  if (!Number.isSafeInteger(timestampMs) || timestampMs <= 0) {
+    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);
+  return {
+    basename: `nft-${hash8}-${timestampMs}`,
+    image: encodedImage,
+    thumbnail: encodedThumbnail,
+    metadata,
+  };
+}

package/src/utils/pro2Wallpaper.ts

@@ -8,6 +8,8 @@ export const PRO2_WALLPAPER_HEIGHT = 1024;
 
 export type Pro2WallpaperColorFormat = 'RGB565' | 'RGB565A8';
 
+export type Pro2ImageAlphaMode = 'preserve' | 'black-background';
+
 const COLOR_FORMAT_RGB565 = 0x12;
 const COLOR_FORMAT_RGB565A8 = 0x14;
 
@@ -36,10 +38,11 @@ function align(value: number, boundary: number): number {
   return Math.ceil(value / boundary) * boundary;
 }
 
-export function encodePro2Wallpaper(options: {
+export function encodePro2Image(options: {
   width: number;
   height: number;
   rgba: Uint8Array | ArrayBuffer;
+  alphaMode?: Pro2ImageAlphaMode;
 }): { data: Uint8Array; colorFormat: Pro2WallpaperColorFormat } {
   const { width, height } = options;
   if (!Number.isInteger(width) || width <= 0 || width > 0xffff) {
@@ -57,11 +60,14 @@ export function encodePro2Wallpaper(options: {
     );
   }
 
+  const alphaMode = options.alphaMode ?? 'preserve';
   let hasTransparency = false;
-  for (let index = 3; index < rgba.length; index += 4) {
-    if (rgba[index] !== 0xff) {
-      hasTransparency = true;
-      break;
+  if (alphaMode === 'preserve') {
+    for (let index = 3; index < rgba.length; index += 4) {
+      if (rgba[index] !== 0xff) {
+        hasTransparency = true;
+        break;
+      }
     }
   }
 
@@ -85,9 +91,22 @@ export function encodePro2Wallpaper(options: {
     for (let x = 0; x < width; x += 1) {
       const sourceOffset = (y * width + x) * 4;
       const thresholdIndex = ((y & 7) << 3) + (x & 7);
-      const red = Math.min(rgba[sourceOffset] + RED_THRESHOLD[thresholdIndex], 0xff) & 0xf8;
-      const green = Math.min(rgba[sourceOffset + 1] + GREEN_THRESHOLD[thresholdIndex], 0xff) & 0xfc;
-      const blue = Math.min(rgba[sourceOffset + 2] + BLUE_THRESHOLD[thresholdIndex], 0xff) & 0xf8;
+      const alpha = rgba[sourceOffset + 3];
+      const redChannel =
+        alphaMode === 'black-background'
+          ? Math.round((rgba[sourceOffset] * alpha) / 0xff)
+          : rgba[sourceOffset];
+      const greenChannel =
+        alphaMode === 'black-background'
+          ? Math.round((rgba[sourceOffset + 1] * alpha) / 0xff)
+          : rgba[sourceOffset + 1];
+      const blueChannel =
+        alphaMode === 'black-background'
+          ? Math.round((rgba[sourceOffset + 2] * alpha) / 0xff)
+          : rgba[sourceOffset + 2];
+      const red = Math.min(redChannel + RED_THRESHOLD[thresholdIndex], 0xff) & 0xf8;
+      const green = Math.min(greenChannel + GREEN_THRESHOLD[thresholdIndex], 0xff) & 0xfc;
+      const blue = Math.min(blueChannel + BLUE_THRESHOLD[thresholdIndex], 0xff) & 0xf8;
       const rgb565 = ((red >> 3) << 11) | ((green >> 2) << 5) | (blue >> 3);
       const rgbOffset = 12 + y * stride + x * 2;
       data[rgbOffset] = rgb565 & 0xff;
@@ -101,3 +120,11 @@ export function encodePro2Wallpaper(options: {
 
   return { data, colorFormat };
 }
+
+export function encodePro2Wallpaper(options: {
+  width: number;
+  height: number;
+  rgba: Uint8Array | ArrayBuffer;
+}): { data: Uint8Array; colorFormat: Pro2WallpaperColorFormat } {
+  return encodePro2Image(options);
+}