@onekeyfe/hwk-adapter-core 1.1.26-alpha.101 → 1.1.26-alpha.104

package/dist/index.d.mts

@@ -50,9 +50,9 @@ type Response<T> = Success<T> | Failure;
 declare function success<T>(payload: T): Success<T>;
 declare function failure(code: HardwareErrorCode, error: string, appName?: string): Failure;
 
-type VendorType = 'trezor' | 'ledger' | 'keystone' | 'keystoneqr';
-type ConnectionType = 'usb' | 'ble' | 'qr';
-type TransportType = 'usb' | 'ble' | 'hid' | 'bridge' | 'qr';
+type VendorType = 'trezor' | 'ledger';
+type ConnectionType = 'usb' | 'ble';
+type TransportType = 'usb' | 'ble' | 'hid' | 'bridge';
 /**
  * Device capabilities — describes what a specific device/connection
  * combination can or cannot do. Varies by vendor, model, and connection type.
@@ -96,14 +96,8 @@ interface EvmGetAddressParams {
 interface EvmAddress {
     address: string;
     path: string;
-}
-interface EvmGetPublicKeyParams {
-    path: string;
-    showOnDevice?: boolean;
-}
-interface EvmPublicKey {
-    publicKey: string;
-    path: string;
+    /** Device-reported secp256k1 public key; populated when the transport exposes it. */
+    publicKey?: string;
 }
 interface EvmSignTxParams {
     path: string;
@@ -184,7 +178,6 @@ type ProgressCallback = (progress: {
 interface IEvmMethods {
     evmGetAddress(connectId: string, deviceId: string, params: EvmGetAddressParams): Promise<Response<EvmAddress>>;
     evmGetAddresses(connectId: string, deviceId: string, params: EvmGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<EvmAddress[]>>;
-    evmGetPublicKey(connectId: string, deviceId: string, params: EvmGetPublicKeyParams): Promise<Response<EvmPublicKey>>;
     evmSignTransaction(connectId: string, deviceId: string, params: EvmSignTxParams): Promise<Response<EvmSignedTx>>;
     evmSignMessage(connectId: string, deviceId: string, params: EvmSignMsgParams): Promise<Response<EvmSignature>>;
     evmSignTypedData(connectId: string, deviceId: string, params: EvmSignTypedDataParams): Promise<Response<EvmSignature>>;
@@ -297,19 +290,10 @@ interface SolGetAddressParams {
     showOnDevice?: boolean;
 }
 interface SolAddress {
-    /** Base58-encoded Solana address */
+    /** Base58-encoded Solana address — this is also the Ed25519 public key. */
     address: string;
     path: string;
 }
-interface SolGetPublicKeyParams {
-    path: string;
-    showOnDevice?: boolean;
-}
-interface SolPublicKey {
-    /** Base58-encoded Ed25519 public key (same as the Solana address) */
-    publicKey: string;
-    path: string;
-}
 interface SolSignTxParams {
     path: string;
     /** Hex-encoded serialized transaction bytes (no 0x prefix) */
@@ -339,7 +323,6 @@ interface SolSignature {
 interface ISolMethods {
     solGetAddress(connectId: string, deviceId: string, params: SolGetAddressParams): Promise<Response<SolAddress>>;
     solGetAddresses(connectId: string, deviceId: string, params: SolGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<SolAddress[]>>;
-    solGetPublicKey(connectId: string, deviceId: string, params: SolGetPublicKeyParams): Promise<Response<SolPublicKey>>;
     solSignTransaction(connectId: string, deviceId: string, params: SolSignTxParams): Promise<Response<SolSignedTx>>;
     solSignMessage(connectId: string, deviceId: string, params: SolSignMsgParams): Promise<Response<SolSignature>>;
 }
@@ -415,17 +398,87 @@ type ChainForFingerprint = 'evm' | 'btc' | 'sol' | 'tron';
  */
 declare function deriveDeviceFingerprint(address: string): string;
 
-declare const DEVICE_EVENT = "DEVICE_EVENT";
-/** Events originating from the hardware device. */
-declare const DEVICE: {
-    readonly CONNECT: "device-connect";
-    readonly DISCONNECT: "device-disconnect";
-    readonly CHANGED: "device-changed";
-    readonly ACQUIRE: "device-acquire";
-    readonly RELEASE: "device-release";
-    readonly FEATURES: "features";
-    readonly SUPPORT_FEATURES: "support_features";
-};
+/** 10 min — every UI request is human-in-the-loop; bias toward "wait long". */
+declare const UI_REQUEST_DEFAULT_TIMEOUT_MS = 600000;
+declare const UI_REQUEST_PREEMPTED_TAG = "UiRequestPreempted";
+declare const UI_REQUEST_CANCELLED_TAG = "UiRequestCancelled";
+declare const UI_REQUEST_TIMEOUT_TAG = "UiRequestTimeout";
+/**
+ * Per-type single-slot registry for adapter-level UI requests. A new `wait`
+ * of the same type preempts (rejects) the prior one. Unknown response types
+ * are dropped silently so the public `uiResponse` entry never throws.
+ */
+declare class UiRequestRegistry {
+    private pending;
+    wait<T = unknown>(requestType: string, options?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    resolve(responseType: string, payload: unknown): void;
+    cancel(requestType?: string): void;
+    reset(): void;
+    hasPending(requestType: string): boolean;
+}
+
+/**
+ * Per-device serial job queue with preemption support and stuck recovery.
+ * Ensures that only one operation runs at a time per device, with intelligent
+ * handling of conflicting operations.
+ *
+ * The 'confirm' level uses the standard UI request/response flow:
+ * emits REQUEST_PREEMPTION → waits for RECEIVE_PREEMPTION via UiRequestRegistry.
+ */
+
+type Interruptibility = 'none' | 'safe' | 'confirm';
+type PreemptionDecision = 'cancel-current' | 'wait' | 'reject-new';
+interface JobOptions {
+    interruptibility?: Interruptibility;
+    label?: string;
+}
+interface ActiveJobInfo {
+    label?: string;
+    interruptibility: Interruptibility;
+    startedAt: number;
+}
+interface PreemptionEvent {
+    deviceId: string;
+    currentJob: ActiveJobInfo;
+    newJob: {
+        label?: string;
+        interruptibility: Interruptibility;
+    };
+}
+interface DeviceJobQueueDeps {
+    /** Emit a UI request event to the frontend. */
+    emit: (event: string, data: unknown) => void;
+    /** Registry for waiting on UI responses. */
+    uiRegistry: UiRequestRegistry;
+}
+declare class DeviceJobQueue {
+    private readonly _queues;
+    private readonly _active;
+    private readonly _deps;
+    constructor(deps?: DeviceJobQueueDeps);
+    /**
+     * Enqueue a job for a specific device.
+     * If a job is already running for this device, behavior depends on interruptibility:
+     * - 'none': new job queues silently (no preemption possible)
+     * - 'safe': current job is auto-cancelled, new job runs immediately after
+     * - 'confirm': emits REQUEST_PREEMPTION and waits for UI response
+     */
+    enqueue<T>(deviceId: string, job: (signal: AbortSignal) => Promise<T>, options?: JobOptions): Promise<T>;
+    /** Manually cancel the active job on a device. Returns false if job is non-interruptible. */
+    cancelActive(deviceId: string): boolean;
+    /** Force cancel regardless of interruptibility. Use for device stuck recovery. */
+    forceCancelActive(deviceId: string): boolean;
+    /** Get info about the currently active job for a device, or null if idle. */
+    getActiveJob(deviceId: string): ActiveJobInfo | null;
+    clear(): void;
+    /**
+     * Request preemption decision via UI request/response flow.
+     * Falls back to 'wait' if deps are not provided.
+     */
+    private _requestPreemptionDecision;
+}
 
 declare const UI_EVENT = "UI_EVENT";
 declare const UI_REQUEST: {
@@ -438,6 +491,7 @@ declare const UI_REQUEST: {
     readonly REQUEST_DEVICE_PERMISSION: "ui-request-device-permission";
     readonly REQUEST_SELECT_DEVICE: "ui-request-select-device";
     readonly REQUEST_DEVICE_CONNECT: "ui-request-device-connect";
+    readonly REQUEST_PREEMPTION: "ui-request-preemption";
     readonly CLOSE_UI_WINDOW: "ui-close";
     readonly DEVICE_PROGRESS: "ui-device_progress";
     readonly FIRMWARE_PROGRESS: "ui-firmware-progress";
@@ -449,8 +503,57 @@ declare const UI_RESPONSE: {
     readonly RECEIVE_PASSPHRASE_ON_DEVICE: "receive-passphrase-on-device";
     readonly RECEIVE_QR_RESPONSE: "receive-qr-response";
     readonly RECEIVE_SELECT_DEVICE: "receive-select-device";
+    readonly RECEIVE_DEVICE_CONNECT: "receive-device-connect";
+    readonly RECEIVE_PREEMPTION: "receive-preemption";
     readonly CANCEL: "cancel";
 };
+type UiResponseEvent = {
+    type: typeof UI_RESPONSE.RECEIVE_PIN;
+    payload: string;
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_PASSPHRASE;
+    payload: {
+        value: string;
+        passphraseOnDevice?: boolean;
+        save?: boolean;
+    };
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_PASSPHRASE_ON_DEVICE;
+    payload?: undefined;
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_QR_RESPONSE;
+    payload: QrResponseData;
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_SELECT_DEVICE;
+    payload: {
+        sdkConnectId: string;
+    };
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_DEVICE_CONNECT;
+    payload: {
+        confirmed: boolean;
+    };
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_PREEMPTION;
+    payload: {
+        decision: PreemptionDecision;
+    };
+} | {
+    type: typeof UI_RESPONSE.CANCEL;
+    payload?: undefined;
+};
+
+declare const DEVICE_EVENT = "DEVICE_EVENT";
+/** Events originating from the hardware device. */
+declare const DEVICE: {
+    readonly CONNECT: "device-connect";
+    readonly DISCONNECT: "device-disconnect";
+    readonly CHANGED: "device-changed";
+    readonly ACQUIRE: "device-acquire";
+    readonly RELEASE: "device-release";
+    readonly FEATURES: "features";
+    readonly SUPPORT_FEATURES: "support_features";
+};
 
 /** Events generated by SDK internal detection (not from hardware directly). */
 declare const SDK: {
@@ -525,6 +628,16 @@ type UiRequestEvent = {
         retryCount: number;
         maxRetries: number;
     };
+} | {
+    type: typeof UI_REQUEST.REQUEST_PREEMPTION;
+    payload: {
+        deviceId: string;
+        currentJob: ActiveJobInfo;
+        newJob: {
+            label?: string;
+            interruptibility: Interruptibility;
+        };
+    };
 } | {
     type: typeof UI_REQUEST.CLOSE_UI_WINDOW;
     payload: Record<string, never>;
@@ -630,6 +743,17 @@ interface HardwareEventMap {
             maxRetries: number;
         };
     };
+    [UI_REQUEST.REQUEST_PREEMPTION]: {
+        type: typeof UI_REQUEST.REQUEST_PREEMPTION;
+        payload: {
+            deviceId: string;
+            currentJob: ActiveJobInfo;
+            newJob: {
+                label?: string;
+                interruptibility: Interruptibility;
+            };
+        };
+    };
     [UI_REQUEST.CLOSE_UI_WINDOW]: {
         type: typeof UI_REQUEST.CLOSE_UI_WINDOW;
         payload: Record<string, never>;
@@ -661,15 +785,13 @@ interface HardwareEventMap {
     };
 }
 /**
- * UI handler for interactive request-response flows.
- * Adapters call these when they need user input (PIN, passphrase, QR scan).
- * Pure notifications (button confirm, progress) go through events instead.
+ * Same-process callbacks for prompts and OS-level permission.
+ * Cross-process flows use events + `uiResponse` + `UiRequestRegistry` instead.
  */
 interface IUiHandler {
     onPinRequest(device: DeviceInfo): Promise<string>;
     onPassphraseRequest(device: DeviceInfo): Promise<string | PassphraseResponse>;
     onQrDisplay(device: DeviceInfo, data: QrDisplayData): Promise<QrResponseData>;
-    onSelectDevice(devices: DeviceInfo[]): Promise<string>;
     /**
      * Check if device access permission is already granted.
      * Returns { granted, context? }.
@@ -716,12 +838,8 @@ interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, I
     getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
     getSupportedChains(): ChainCapability[];
     cancel(connectId: string): void;
-    /**
-     * Respond to a ui-request-device-connect event.
-     * Call with 'confirm' after the user connects/unlocks the device to retry,
-     * or 'cancel' to abort the operation.
-     */
-    deviceConnectResponse(type: 'confirm' | 'cancel'): void;
+    /** Respond to any pending `ui-request-*`. */
+    uiResponse(response: UiResponseEvent): void;
     /**
      * Derive a chain-specific fingerprint for the connected device.
      *
@@ -767,77 +885,6 @@ interface DeviceDisconnectEvent {
 }
 type DeviceChangeEvent = DeviceConnectEvent | DeviceDisconnectEvent;
 
-/**
- * Per-device serial job queue with preemption support and stuck recovery.
- * Ensures that only one operation runs at a time per device, with intelligent
- * handling of conflicting operations.
- */
-type Interruptibility = 'none' | 'safe' | 'confirm';
-type PreemptionDecision = 'cancel-current' | 'wait' | 'reject-new';
-interface JobOptions {
-    interruptibility?: Interruptibility;
-    label?: string;
-}
-interface ActiveJobInfo {
-    label?: string;
-    interruptibility: Interruptibility;
-    startedAt: number;
-}
-interface PreemptionEvent {
-    deviceId: string;
-    currentJob: ActiveJobInfo;
-    newJob: {
-        label?: string;
-        interruptibility: Interruptibility;
-    };
-}
-declare class DeviceJobQueue {
-    private readonly _queues;
-    private readonly _active;
-    /**
-     * Called when a new job conflicts with an active 'confirm'-level job.
-     * UI should show a dialog and return the user's decision.
-     * If not set, defaults to 'wait' (queue behind current job).
-     */
-    onPreemptionRequest?: (event: PreemptionEvent) => Promise<PreemptionDecision>;
-    /**
-     * Enqueue a job for a specific device.
-     * If a job is already running for this device, behavior depends on interruptibility:
-     * - 'none': new job queues silently (no preemption possible)
-     * - 'safe': current job is auto-cancelled, new job runs immediately after
-     * - 'confirm': onPreemptionRequest is called to ask user
-     */
-    enqueue<T>(deviceId: string, job: (signal: AbortSignal) => Promise<T>, options?: JobOptions): Promise<T>;
-    /** Manually cancel the active job on a device. Returns false if job is non-interruptible. */
-    cancelActive(deviceId: string): boolean;
-    /** Force cancel regardless of interruptibility. Use for device stuck recovery. */
-    forceCancelActive(deviceId: string): boolean;
-    /** Get info about the currently active job for a device, or null if idle. */
-    getActiveJob(deviceId: string): ActiveJobInfo | null;
-    clear(): void;
-}
-
-/**
- * Abstraction for UI communication during device interactions.
- * Implementations handle different execution contexts:
- * - DirectUiBridge: same-process event emitter (default)
- * - IframeUiBridge: postMessage-based (future)
- * - ExtensionUiBridge: chrome.runtime.sendMessage (future)
- */
-interface IUiBridge {
-    /** Ask the user for PIN entry. Returns the PIN string. */
-    requestPin(device: DeviceInfo, signal?: AbortSignal): Promise<string>;
-    /** Ask the user for passphrase entry. Returns the passphrase string. */
-    requestPassphrase(device: DeviceInfo, signal?: AbortSignal): Promise<string>;
-    /** Notify the UI about a button press request on the device. */
-    notifyButton(device: DeviceInfo, code?: string): void;
-    /**
-     * Ask the user whether to preempt the current device operation.
-     * Only called for 'confirm'-level operations.
-     */
-    requestPreemption(device: DeviceInfo, activeLabel: string, newLabel: string): Promise<PreemptionDecision>;
-}
-
 /**
  * Minimal device info returned during discovery (searchDevices).
  * At scan time, full DeviceInfo fields like firmwareVersion are not yet available.
@@ -910,10 +957,7 @@ interface IConnector {
     call(sessionId: string, method: string, params: unknown): Promise<unknown>;
     cancel(sessionId: string): Promise<void>;
     /** Send a UI response (e.g. PIN, passphrase) to the device. */
-    uiResponse(response: {
-        type: string;
-        payload: unknown;
-    }): void;
+    uiResponse(response: UiResponseEvent): void;
     on<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
     off<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
     reset(): void;
@@ -942,10 +986,7 @@ interface IHardwareBridge {
     }): Promise<void>;
     uiResponse(params: {
         vendor: VendorType;
-        response: {
-            type: string;
-            payload: unknown;
-        };
+        response: UiResponseEvent;
     }): void;
     reset(params: {
         vendor: VendorType;
@@ -1031,4 +1072,4 @@ declare function batchCall<TParam, TResult>(params: TParam[], callFn: (p: TParam
     total: number;
 }) => void): Promise<Response<TResult[]>>;
 
-export { type ActiveJobInfo, type BtcAddress, type BtcGetAddressParams, type BtcGetPublicKeyParams, type BtcPublicKey, type BtcRefTransaction, type BtcSignMsgParams, type BtcSignPsbtParams, type BtcSignTxParams, type BtcSignature, type BtcSignedPsbt, type BtcSignedTx, type BtcTxInput, type BtcTxOutput, CHAIN_FINGERPRINT_PATHS, type ChainCapability, type ChainForFingerprint, type ConnectionType, type ConnectorDevice, type ConnectorEventMap, type ConnectorEventType, type ConnectorSession, DEVICE, DEVICE_EVENT, type DeviceCapabilities, type DeviceChangeEvent, type DeviceConnectEvent, type DeviceDescriptor, type DeviceDisconnectEvent, type DeviceEvent, type DeviceEventListener, type DeviceInfo, DeviceJobQueue, type DeviceTarget, EConnectorInteraction, type EIP712Domain, type EvmAddress, type EvmGetAddressParams, type EvmGetPublicKeyParams, type EvmPublicKey, type EvmSignMsgParams, type EvmSignTxParams, type EvmSignTypedDataFull, type EvmSignTypedDataHash, type EvmSignTypedDataParams, type EvmSignature, type EvmSignedTx, type Failure, HardwareErrorCode, type HardwareEvent, type HardwareEventMap, type IBtcMethods, type IConnector, type IEvmMethods, type IHardwareBridge, type IHardwareWallet, type ISolMethods, type ITronMethods, type IUiBridge, type IUiHandler, type Interruptibility, type JobOptions, type PassphraseResponse, type PreemptionDecision, type PreemptionEvent, type ProgressCallback, type QrDisplayData, type QrResponseData, type Response, SDK, type SdkEvent, type SolAddress, type SolGetAddressParams, type SolGetPublicKeyParams, type SolPublicKey, type SolSignMsgParams, type SolSignTxParams, type SolSignature, type SolSignedTx, type Success, type TransportType, type TronAddress, type TronGetAddressParams, type TronSignMsgParams, type TronSignTxParams, type TronSignature, type TronSignedTx, TypedEventEmitter, UI_EVENT, UI_REQUEST, UI_RESPONSE, type UiRequestEvent, type VendorType, batchCall, bytesToHex, compareSemver, createBridgedConnector, deriveDeviceFingerprint, enrichErrorMessage, ensure0x, failure, hexToBytes, padHex64, stripHex, success };
+export { type ActiveJobInfo, type BtcAddress, type BtcGetAddressParams, type BtcGetPublicKeyParams, type BtcPublicKey, type BtcRefTransaction, type BtcSignMsgParams, type BtcSignPsbtParams, type BtcSignTxParams, type BtcSignature, type BtcSignedPsbt, type BtcSignedTx, type BtcTxInput, type BtcTxOutput, CHAIN_FINGERPRINT_PATHS, type ChainCapability, type ChainForFingerprint, type ConnectionType, type ConnectorDevice, type ConnectorEventMap, type ConnectorEventType, type ConnectorSession, DEVICE, DEVICE_EVENT, type DeviceCapabilities, type DeviceChangeEvent, type DeviceConnectEvent, type DeviceDescriptor, type DeviceDisconnectEvent, type DeviceEvent, type DeviceEventListener, type DeviceInfo, DeviceJobQueue, type DeviceJobQueueDeps, type DeviceTarget, EConnectorInteraction, type EIP712Domain, type EvmAddress, type EvmGetAddressParams, type EvmSignMsgParams, type EvmSignTxParams, type EvmSignTypedDataFull, type EvmSignTypedDataHash, type EvmSignTypedDataParams, type EvmSignature, type EvmSignedTx, type Failure, HardwareErrorCode, type HardwareEvent, type HardwareEventMap, type IBtcMethods, type IConnector, type IEvmMethods, type IHardwareBridge, type IHardwareWallet, type ISolMethods, type ITronMethods, type IUiHandler, type Interruptibility, type JobOptions, type PassphraseResponse, type PreemptionDecision, type PreemptionEvent, type ProgressCallback, type QrDisplayData, type QrResponseData, type Response, SDK, type SdkEvent, type SolAddress, type SolGetAddressParams, type SolSignMsgParams, type SolSignTxParams, type SolSignature, type SolSignedTx, type Success, type TransportType, type TronAddress, type TronGetAddressParams, type TronSignMsgParams, type TronSignTxParams, type TronSignature, type TronSignedTx, TypedEventEmitter, UI_EVENT, UI_REQUEST, UI_REQUEST_CANCELLED_TAG, UI_REQUEST_DEFAULT_TIMEOUT_MS, UI_REQUEST_PREEMPTED_TAG, UI_REQUEST_TIMEOUT_TAG, UI_RESPONSE, type UiRequestEvent, UiRequestRegistry, type UiResponseEvent, type VendorType, batchCall, bytesToHex, compareSemver, createBridgedConnector, deriveDeviceFingerprint, enrichErrorMessage, ensure0x, failure, hexToBytes, padHex64, stripHex, success };