@onekeyfe/hwk-adapter-core 1.1.26-alpha.106 → 1.1.26-alpha.12

package/dist/index.d.mts

@@ -1,38 +1,106 @@
+/**
+ * HWK HardwareErrorCode — independent namespace from the legacy
+ * `@onekeyfe/shared` HardwareErrorCode (which occupies 0-902).
+ *
+ * All HWK codes are 5-digit (>= 10000) so the two tables never collide
+ * even if either side grows. Each sub-category gets a 100-slot block.
+ *
+ *   10000-10099  Generic / cross-cutting primitives
+ *   10100-10199  Device state
+ *   10200-10299  Firmware
+ *   10300-10399  Transport + OS-level permission
+ *   10400-10499  PIN / Passphrase
+ *   10500-10599  App lifecycle (wrong app, not open, too old)
+ *   10600-10999  RESERVED — future adapter-level categories
+ *
+ *   11000-11099  EVM APDU (reactive mapping)
+ *   11100-11199  Solana APDU
+ *   11200-11299  Tron APDU
+ *   11300-11399  BTC APDU
+ *   11400-11999  RESERVED — future chain APDU blocks (100 per chain)
+ *
+ *   12000-99999  RESERVED — future major categories
+ */
 declare enum HardwareErrorCode {
-    UnknownError = 0,
-    DeviceNotFound = 1,
-    DeviceDisconnected = 2,
-    UserRejected = 3,
-    DeviceBusy = 4,
-    FirmwareUpdateRequired = 5,
-    AppNotOpen = 6,
-    InvalidParams = 7,
-    TransportError = 8,
-    OperationTimeout = 9,
-    MethodNotSupported = 10,
-    PinInvalid = 5520,
-    PinCancelled = 5521,
-    PassphraseRejected = 5522,
-    DeviceLocked = 5530,
-    DeviceNotInitialized = 5531,
-    DeviceInBootloader = 5532,
-    FirmwareTooOld = 5533,
-    WrongApp = 5540,
-    DeviceMismatch = 5560,
-    BridgeNotFound = 5550,
-    TransportNotAvailable = 5551,
+    UnknownError = 10000,
+    UserRejected = 10001,
+    InvalidParams = 10002,
+    OperationTimeout = 10003,
+    MethodNotSupported = 10004,
+    /** User dismissed in-app cancel UI. Distinct from UserRejected (on-device). */
+    UserAborted = 10005,
+    DeviceNotFound = 10100,
+    DeviceDisconnected = 10101,
+    DeviceBusy = 10102,
+    DeviceLocked = 10103,
+    DeviceNotInitialized = 10104,
+    DeviceInBootloader = 10105,
+    DeviceMismatch = 10106,
+    /** Chain app wedged (e.g. Ledger BTC 0x6901). User must exit app on device. */
+    DeviceAppStuck = 10107,
+    /** Vendor (Ledger / Trezor) doesn't support the chain at all. */
+    ChainNotSupported = 10108,
+    FirmwareTooOld = 10200,
+    FirmwareUpdateRequired = 10201,
+    TransportError = 10300,
+    BridgeNotFound = 10301,
+    TransportNotAvailable = 10302,
+    /**
+     * OS-level permission (Bluetooth / USB / etc.) — denied, blocked,
+     * unavailable, or dismissed. Consumers surface a single "please grant
+     * permission" toast and let the user retry manually.
+     */
+    DevicePermissionDenied = 10303,
+    /**
+     * BLE SMP pairing did not complete within the GATT bonding window.
+     * GATT connected but the device didn't acknowledge SMP — typically
+     * because the user didn't confirm the passkey on the device, or the
+     * device went out of range mid-pairing. Distinct from OperationTimeout
+     * (generic) and from DeviceLocked (Secure Element actually locked).
+     */
+    BlePairingTimeout = 10304,
+    PinInvalid = 10400,
+    PinCancelled = 10401,
+    PassphraseRejected = 10402,
+    /** Chain app NOT INSTALLED on device. User must install via Ledger Live. */
+    AppNotInstalled = 10500,
+    WrongApp = 10501,
+    /** 0x911c Command code not supported — app predates current SDK. */
+    AppTooOld = 10502,
     /** 0x6a80 Invalid data — observed on blindSignTransactionFallback when the
      *  user has not enabled Blind signing on the device. */
-    EvmBlindSigningRequired = 7001,
+    EvmBlindSigningRequired = 11000,
     /** 0x6984 Plugin not installed */
-    EvmClearSignPluginMissing = 7002,
+    EvmClearSignPluginMissing = 11001,
     /** 0x6a84 Insufficient memory (typical on Nano S with large calldata) */
-    EvmDataTooLarge = 7003,
+    EvmDataTooLarge = 11002,
     /** 0x6501 TransactionType not supported (app too old for EIP-1559 / blob / 7702) */
-    EvmTxTypeNotSupported = 7004,
-    /** 0x911c Command code not supported — app predates current SDK */
-    AppTooOld = 7005
+    EvmTxTypeNotSupported = 11003,
+    /** 0x6808 Blind signing disabled for this instruction. */
+    SolanaBlindSigningRequired = 11100,
+    /** 0x6a8d Custom Contracts setting disabled (blocks TRC-20 etc.). */
+    TronCustomContractRequired = 11200,
+    /** 0x6a8b Transactions Data setting disabled. */
+    TronDataSigningRequired = 11201,
+    /** 0x6a8c Sign by Hash setting disabled (hash-signing fallback). */
+    TronSignByHashRequired = 11202,
+    /** 0xb008 Wallet policy HMAC mismatch or not registered. */
+    BtcWalletPolicyHmacMismatch = 11300,
+    /** 0xb007 Aborted due to unexpected state (malformed PSBT / missing UTXO). */
+    BtcUnexpectedState = 11301
 }
+/**
+ * Device-level failures the SDK cannot self-recover from — affect the entire
+ * batch (vs per-chain failures like AppNotInstalled / WrongApp which soft-
+ * skip in onboarding). Combined with `accounts.length === 0`, signals
+ * genuine orphan. Also reused as the batch-abort whitelist for HWK.
+ * Single source of truth.
+ *
+ * UserRejected (device-side reject) is included: pressing reject is an
+ * explicit "I don't consent" — continuing the batch to ask again on the
+ * next chain is harassment, not helpful.
+ */
+declare const ORPHAN_ELIGIBLE_ERROR_CODES: number[];
 
 interface Success<T> {
     success: true;
@@ -43,12 +111,12 @@ interface Failure {
     payload: {
         error: string;
         code: HardwareErrorCode;
-        appName?: string;
+        params?: Record<string, unknown>;
     };
 }
 type Response<T> = Success<T> | Failure;
 declare function success<T>(payload: T): Success<T>;
-declare function failure(code: HardwareErrorCode, error: string, appName?: string): Failure;
+declare function failure(code: HardwareErrorCode, error: string, params?: Record<string, unknown>): Failure;
 
 type VendorType = 'trezor' | 'ledger';
 type ConnectionType = 'usb' | 'ble';
@@ -171,13 +239,8 @@ interface EvmSignature {
     signature: string;
     address?: string;
 }
-type ProgressCallback = (progress: {
-    index: number;
-    total: number;
-}) => void;
 interface IEvmMethods {
     evmGetAddress(connectId: string, deviceId: string, params: EvmGetAddressParams): Promise<Response<EvmAddress>>;
-    evmGetAddresses(connectId: string, deviceId: string, params: EvmGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<EvmAddress[]>>;
     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>>;
@@ -250,10 +313,10 @@ interface BtcRefTransaction {
     locktime: number;
 }
 interface BtcSignedTx {
-    signatures: string[];
     serializedTx: string;
+    /** Present when the wallet returns per-input sigs separately (e.g. Trezor). */
+    signatures?: string[];
     txid?: string;
-    signedPsbt?: string;
 }
 interface BtcSignPsbtParams {
     psbt: string;
@@ -271,11 +334,11 @@ interface BtcSignMsgParams {
 }
 interface BtcSignature {
     signature: string;
-    address: string;
+    /** Optional — not all adapters return it (e.g. Ledger DMK). Derive via btcGetAddress if needed. */
+    address?: string;
 }
 interface IBtcMethods {
     btcGetAddress(connectId: string, deviceId: string, params: BtcGetAddressParams): Promise<Response<BtcAddress>>;
-    btcGetAddresses(connectId: string, deviceId: string, params: BtcGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<BtcAddress[]>>;
     btcGetPublicKey(connectId: string, deviceId: string, params: BtcGetPublicKeyParams): Promise<Response<BtcPublicKey>>;
     btcSignTransaction(connectId: string, deviceId: string, params: BtcSignTxParams): Promise<Response<BtcSignedTx>>;
     btcSignPsbt(connectId: string, deviceId: string, params: BtcSignPsbtParams): Promise<Response<BtcSignedPsbt>>;
@@ -322,7 +385,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[]>>;
     solSignTransaction(connectId: string, deviceId: string, params: SolSignTxParams): Promise<Response<SolSignedTx>>;
     solSignMessage(connectId: string, deviceId: string, params: SolSignMsgParams): Promise<Response<SolSignature>>;
 }
@@ -356,7 +418,6 @@ interface TronSignature {
 }
 interface ITronMethods {
     tronGetAddress(connectId: string, deviceId: string, params: TronGetAddressParams): Promise<Response<TronAddress>>;
-    tronGetAddresses(connectId: string, deviceId: string, params: TronGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<TronAddress[]>>;
     tronSignTransaction(connectId: string, deviceId: string, params: TronSignTxParams): Promise<Response<TronSignedTx>>;
     tronSignMessage(connectId: string, deviceId: string, params: TronSignMsgParams): Promise<Response<TronSignature>>;
 }
@@ -383,94 +444,19 @@ interface QrResponseData {
 declare const CHAIN_FINGERPRINT_PATHS: Record<ChainForFingerprint, string>;
 type ChainForFingerprint = 'evm' | 'btc' | 'sol' | 'tron';
 /**
- * Hash an address string into a 16-character hex fingerprint.
- *
- * Uses the first 16 hex chars (64 bits) of SHA-256 — sufficient for
- * device identity matching. Not used for security decisions.
- */
-declare function deriveDeviceFingerprint(address: string): string;
-
-/** 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.
+ * 16-char SHA-256 fingerprint for device-identity verification.
+ * Callers must canonicalize input (e.g. EVM address → lowercase) —
+ * encoding variations otherwise cause false DeviceMismatch.
  */
-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;
-}
+declare function deriveDeviceFingerprint(value: string): string;
 
-/**
- * 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 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";
+};
 
 declare const UI_EVENT = "UI_EVENT";
 declare const UI_REQUEST: {
@@ -483,7 +469,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 REQUEST_BTC_HIGH_INDEX_CONFIRM: "ui-request-btc-high-index-confirm";
     readonly CLOSE_UI_WINDOW: "ui-close";
     readonly DEVICE_PROGRESS: "ui-device_progress";
     readonly FIRMWARE_PROGRESS: "ui-firmware-progress";
@@ -496,9 +482,16 @@ declare const UI_RESPONSE: {
     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 RECEIVE_DEVICE_PERMISSION: "receive-device-permission";
+    readonly RECEIVE_BTC_HIGH_INDEX_CONFIRM: "receive-btc-high-index-confirm";
     readonly CANCEL: "cancel";
 };
+type DevicePermissionDeniedReason = 'bluetoothTurnedOff' | 'permissionDenied' | (string & Record<never, never>);
+type DevicePermissionResponse = {
+    granted: boolean;
+    reason?: DevicePermissionDeniedReason;
+    message?: string;
+};
 type UiResponseEvent = {
     type: typeof UI_RESPONSE.RECEIVE_PIN;
     payload: string;
@@ -526,27 +519,18 @@ type UiResponseEvent = {
         confirmed: boolean;
     };
 } | {
-    type: typeof UI_RESPONSE.RECEIVE_PREEMPTION;
+    type: typeof UI_RESPONSE.RECEIVE_DEVICE_PERMISSION;
+    payload: DevicePermissionResponse;
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_BTC_HIGH_INDEX_CONFIRM;
     payload: {
-        decision: PreemptionDecision;
+        confirmed: boolean;
     };
 } | {
     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: {
     readonly DEVICE_STUCK: "device-stuck";
@@ -555,6 +539,146 @@ declare const SDK: {
     readonly DEVICE_INTERACTION: "device-interaction";
 };
 
+/**
+ * Minimal device info returned during discovery (searchDevices).
+ * At scan time, full DeviceInfo fields like firmwareVersion are not yet available.
+ */
+interface ConnectorDevice {
+    connectId: string;
+    deviceId: string;
+    name: string;
+    model?: string;
+    /** Device capabilities — available from scan time */
+    capabilities?: DeviceCapabilities;
+}
+interface ConnectorSession {
+    sessionId: string;
+    deviceInfo: DeviceInfo;
+}
+type ConnectorEventType = 'device-connect' | 'device-disconnect' | 'ui-request' | 'ui-event';
+/**
+ * Interaction event types emitted via 'ui-event'.
+ * These map to user-facing prompts (confirm on device, open app, etc.).
+ */
+declare enum EConnectorInteraction {
+    /** Adapter is actively searching for the device (no session yet) */
+    Searching = "searching",
+    /** Device requires user to open a specific app */
+    ConfirmOpenApp = "confirm-open-app",
+    /** Device requires user to unlock */
+    UnlockDevice = "unlock-device",
+    /** Device needs user to confirm on device (sign, verify, etc.) */
+    ConfirmOnDevice = "confirm-on-device",
+    /** Previous interaction completed — clear UI prompt */
+    InteractionComplete = "interaction-complete"
+}
+type ConnectorUiEvent = {
+    type: EConnectorInteraction.Searching;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.ConfirmOpenApp;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.UnlockDevice;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.ConfirmOnDevice;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.InteractionComplete;
+    payload: {
+        sessionId: string;
+    };
+};
+interface ConnectorEventMap {
+    'device-connect': {
+        device: ConnectorDevice;
+    };
+    'device-disconnect': {
+        connectId: string;
+    };
+    'ui-request': {
+        type: string;
+        payload?: unknown;
+    };
+    'ui-event': ConnectorUiEvent;
+}
+interface IConnector {
+    /** Physical connection type this connector uses. Fixed at construction. */
+    readonly connectionType: ConnectionType;
+    searchDevices(): Promise<ConnectorDevice[]>;
+    connect(deviceId?: string): Promise<ConnectorSession>;
+    disconnect(sessionId: string): Promise<void>;
+    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: 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;
+}
+interface IHardwareBridge {
+    searchDevices(params: {
+        vendor: VendorType;
+    }): Promise<ConnectorDevice[]>;
+    connect(params: {
+        vendor: VendorType;
+        deviceId?: string;
+    }): Promise<ConnectorSession>;
+    disconnect(params: {
+        vendor: VendorType;
+        sessionId: string;
+    }): Promise<void>;
+    call(params: {
+        vendor: VendorType;
+        sessionId: string;
+        method: string;
+        callParams: unknown;
+    }): Promise<unknown>;
+    cancel(params: {
+        vendor: VendorType;
+        sessionId: string;
+    }): Promise<void>;
+    uiResponse(params: {
+        vendor: VendorType;
+        response: UiResponseEvent;
+    }): void;
+    reset(params: {
+        vendor: VendorType;
+    }): void;
+    /** Register an event handler for connector events forwarded across the bridge. */
+    onEvent(params: {
+        vendor: VendorType;
+    }, handler: (event: {
+        type: ConnectorEventType;
+        data: unknown;
+    }) => void): void;
+    /** Unregister a previously registered event handler. */
+    offEvent(params: {
+        vendor: VendorType;
+    }, handler: (event: {
+        type: ConnectorEventType;
+        data: unknown;
+    }) => void): void;
+}
+/**
+ * Adapt an IHardwareBridge (multi-vendor backend) into a single-vendor IConnector.
+ * Every IConnector method becomes a transparent forward to bridge.<method>({ vendor, ... }).
+ * Events are forwarded via bridge.onEvent / offEvent.
+ *
+ * Use this anywhere the actual hardware lives behind a process / context boundary
+ * (Electron main, extension background, native module, worker, iframe).
+ */
+declare function createBridgedConnector(vendor: VendorType, connectionType: ConnectionType, bridge: IHardwareBridge): IConnector;
+
 type ChainCapability = 'evm' | 'btc' | 'sol' | 'tron';
 interface PassphraseResponse {
     passphrase: string;
@@ -607,7 +731,11 @@ type UiRequestEvent = {
     };
 } | {
     type: typeof UI_REQUEST.REQUEST_DEVICE_PERMISSION;
-    payload: Record<string, never>;
+    payload: {
+        transportType: TransportType;
+        connectId?: string;
+        deviceId?: string;
+    };
 } | {
     type: typeof UI_REQUEST.REQUEST_SELECT_DEVICE;
     payload: {
@@ -616,19 +744,22 @@ type UiRequestEvent = {
 } | {
     type: typeof UI_REQUEST.REQUEST_DEVICE_CONNECT;
     payload: {
+        /** Vendor that emitted the request, e.g. 'ledger', 'trezor'. */
+        vendor: string;
+        /**
+         * Why the SDK is asking for a reconnect. Lets the app render
+         * vendor-aware copy without inspecting message strings.
+         * - 'device-not-found': search returned 0 / device not reachable.
+         * Future values can be added (e.g. 'pairing-failed') as new fallback
+         * causes are surfaced.
+         */
+        reason: string;
+        /**
+         * Best-effort English fallback. Apps should prefer rendering via
+         * `vendor` + `reason` for i18n; fall back to this if the combination
+         * isn't recognized.
+         */
         message: string;
-        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;
@@ -656,7 +787,7 @@ type SdkEvent = {
         connectId: string;
     };
 };
-type HardwareEvent = DeviceEvent | UiRequestEvent | SdkEvent;
+type HardwareEvent = DeviceEvent | UiRequestEvent | SdkEvent | ConnectorUiEvent;
 type DeviceEventListener = (event: HardwareEvent) => void;
 /**
  * Type-safe event map for IHardwareWallet.on / .off.
@@ -665,6 +796,7 @@ type DeviceEventListener = (event: HardwareEvent) => void;
  * and the value is the narrowed event object the listener will receive.
  */
 interface HardwareEventMap {
+    'ui-event': ConnectorUiEvent;
     [DEVICE.CONNECT]: {
         type: typeof DEVICE.CONNECT;
         payload: DeviceInfo;
@@ -719,7 +851,11 @@ interface HardwareEventMap {
     };
     [UI_REQUEST.REQUEST_DEVICE_PERMISSION]: {
         type: typeof UI_REQUEST.REQUEST_DEVICE_PERMISSION;
-        payload: Record<string, never>;
+        payload: {
+            transportType: TransportType;
+            connectId?: string;
+            deviceId?: string;
+        };
     };
     [UI_REQUEST.REQUEST_SELECT_DEVICE]: {
         type: typeof UI_REQUEST.REQUEST_SELECT_DEVICE;
@@ -730,20 +866,17 @@ interface HardwareEventMap {
     [UI_REQUEST.REQUEST_DEVICE_CONNECT]: {
         type: typeof UI_REQUEST.REQUEST_DEVICE_CONNECT;
         payload: {
+            vendor: string;
+            reason: string;
             message: string;
-            retryCount: number;
-            maxRetries: number;
         };
     };
-    [UI_REQUEST.REQUEST_PREEMPTION]: {
-        type: typeof UI_REQUEST.REQUEST_PREEMPTION;
+    [UI_REQUEST.REQUEST_BTC_HIGH_INDEX_CONFIRM]: {
+        type: typeof UI_REQUEST.REQUEST_BTC_HIGH_INDEX_CONFIRM;
         payload: {
-            deviceId: string;
-            currentJob: ActiveJobInfo;
-            newJob: {
-                label?: string;
-                interruptibility: Interruptibility;
-            };
+            vendor: string;
+            path: string;
+            accountIndex: number;
         };
     };
     [UI_REQUEST.CLOSE_UI_WINDOW]: {
@@ -776,47 +909,6 @@ interface HardwareEventMap {
         };
     };
 }
-/**
- * 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>;
-    /**
-     * Check if device access permission is already granted.
-     * Returns { granted, context? }.
-     * - granted: true → skip onDevicePermission
-     * - granted: false → adapter calls onDevicePermission with the context
-     * - context: consumer-defined data passed through to onDevicePermission
-     *
-     * When connectId/deviceId are undefined (searchDevices), check environment-level
-     * permissions (USB: any paired device exists; BLE: bluetooth on + location permission).
-     * When connectId/deviceId are provided (business methods), check device-level
-     * permissions (USB: target device authorized; BLE: bluetooth on + device connected).
-     */
-    checkDevicePermission?(params: {
-        transportType: TransportType;
-        connectId?: string;
-        deviceId?: string;
-    }): Promise<{
-        granted: boolean;
-        context?: Record<string, unknown>;
-    }>;
-    /**
-     * Request device access permission from the user.
-     * Only called when checkDevicePermission returns granted: false (or is not set).
-     *
-     * The handler decides what to do based on transportType + context:
-     * - usb/hid: open pairing page or call requestWebUSBDevice
-     * - ble: enable bluetooth, request location permission, start scanning
-     */
-    onDevicePermission(params: {
-        transportType: TransportType;
-        context?: Record<string, unknown>;
-    }): Promise<void>;
-}
 interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, ISolMethods, ITronMethods {
     readonly vendor: string;
     readonly activeTransport: TransportType | null;
@@ -829,7 +921,8 @@ interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, I
     disconnectDevice(connectId: string): Promise<void>;
     getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
     getSupportedChains(): ChainCapability[];
-    cancel(connectId: string): void;
+    /** Abort the in-flight call. Omit connectId to cancel whatever is active. */
+    cancel(connectId?: string): void;
     /** Respond to any pending `ui-request-*`. */
     uiResponse(response: UiResponseEvent): void;
     /**
@@ -842,7 +935,6 @@ interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, I
      * especially for vendors with ephemeral connectId/deviceId.
      */
     getChainFingerprint(connectId: string, deviceId: string, chain: ChainForFingerprint): Promise<Response<string>>;
-    setUiHandler(handler: Partial<IUiHandler>): void;
     on<K extends keyof HardwareEventMap>(event: K, listener: (event: HardwareEventMap[K]) => void): void;
     on(event: string, listener: DeviceEventListener): void;
     off<K extends keyof HardwareEventMap>(event: K, listener: (event: HardwareEventMap[K]) => void): void;
@@ -862,10 +954,16 @@ interface DeviceDescriptor {
     vendor?: number;
     /** Device type/model identifier */
     type?: string;
-    /** BLE device name (e.g., "Nano X 123A") — contains stable 4-digit HEX suffix */
+    /** Human-readable display name from the transport layer. */
     name?: string;
+    /** Stable Ledger BLE identifier from the raw RN BLE `Device.name` field. */
+    bleName?: string;
+    /** User-visible Ledger BLE local name from the raw RN BLE `Device.localName` field. */
+    localName?: string;
     /** Transport identifier (e.g., 'WEB-HID', 'BLE') */
     transport?: string;
+    /** BLE RSSI when provided by the transport scanner. */
+    rssi?: number | null;
 }
 interface DeviceConnectEvent {
     type: 'device-connected';
@@ -878,135 +976,51 @@ interface DeviceDisconnectEvent {
 type DeviceChangeEvent = DeviceConnectEvent | DeviceDisconnectEvent;
 
 /**
- * Minimal device info returned during discovery (searchDevices).
- * At scan time, full DeviceInfo fields like firmwareVersion are not yet available.
+ * Pure FIFO job queue. Every enqueue chains onto the tail; jobs run one at
+ * a time across all devices. The queue is intentionally passive — it does
+ * NOT decide whether to interrupt or ask the user. Those are application-
+ * layer concerns owned by the caller (e.g. a UI button handler that wants
+ * to ask "device is busy, interrupt current?" before submitting). The
+ * queue exposes inspection (`getActiveJob`) and explicit cancellation
+ * (`cancelActive` / `cancelAll`) so callers can implement those policies
+ * synchronously, without racing against in-flight enqueues.
  */
-interface ConnectorDevice {
-    connectId: string;
-    deviceId: string;
-    name: string;
-    model?: string;
-    /** Device capabilities — available from scan time */
-    capabilities?: DeviceCapabilities;
-}
-interface ConnectorSession {
-    sessionId: string;
-    deviceInfo: DeviceInfo;
-}
-type ConnectorEventType = 'device-connect' | 'device-disconnect' | 'ui-request' | 'ui-event';
-/**
- * Interaction event types emitted via 'ui-event'.
- * These map to user-facing prompts (confirm on device, open app, etc.).
- */
-declare enum EConnectorInteraction {
-    /** Device requires user to open a specific app */
-    ConfirmOpenApp = "confirm-open-app",
-    /** Device requires user to unlock */
-    UnlockDevice = "unlock-device",
-    /** Device needs user to confirm on device (sign, verify, etc.) */
-    ConfirmOnDevice = "confirm-on-device",
-    /** Previous interaction completed — clear UI prompt */
-    InteractionComplete = "interaction-complete"
-}
-type ConnectorUiEvent = {
-    type: EConnectorInteraction.ConfirmOpenApp;
-    payload: {
-        sessionId: string;
-    };
-} | {
-    type: EConnectorInteraction.UnlockDevice;
-    payload: {
-        sessionId: string;
-    };
-} | {
-    type: EConnectorInteraction.ConfirmOnDevice;
-    payload: {
-        sessionId: string;
-    };
-} | {
-    type: EConnectorInteraction.InteractionComplete;
-    payload: {
-        sessionId: string;
-    };
-};
-interface ConnectorEventMap {
-    'device-connect': {
-        device: ConnectorDevice;
-    };
-    'device-disconnect': {
-        connectId: string;
-    };
-    'ui-request': {
-        type: string;
-        payload?: unknown;
-    };
-    'ui-event': ConnectorUiEvent;
+interface JobOptions {
+    label?: string;
+    rejectIfBusy?: boolean;
+    busyError?: Error;
 }
-interface IConnector {
-    searchDevices(): Promise<ConnectorDevice[]>;
-    connect(deviceId?: string): Promise<ConnectorSession>;
-    disconnect(sessionId: string): Promise<void>;
-    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: 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;
+interface ActiveJobInfo {
+    deviceId: string;
+    label?: string;
+    startedAt: number;
 }
-interface IHardwareBridge {
-    searchDevices(params: {
-        vendor: VendorType;
-    }): Promise<ConnectorDevice[]>;
-    connect(params: {
-        vendor: VendorType;
-        deviceId?: string;
-    }): Promise<ConnectorSession>;
-    disconnect(params: {
-        vendor: VendorType;
-        sessionId: string;
-    }): Promise<void>;
-    call(params: {
-        vendor: VendorType;
-        sessionId: string;
-        method: string;
-        callParams: unknown;
-    }): Promise<unknown>;
-    cancel(params: {
-        vendor: VendorType;
-        sessionId: string;
-    }): Promise<void>;
-    uiResponse(params: {
-        vendor: VendorType;
-        response: UiResponseEvent;
-    }): void;
-    reset(params: {
-        vendor: VendorType;
-    }): void;
-    /** Register an event handler for connector events forwarded across the bridge. */
-    onEvent(params: {
-        vendor: VendorType;
-    }, handler: (event: {
-        type: ConnectorEventType;
-        data: unknown;
-    }) => void): void;
-    /** Unregister a previously registered event handler. */
-    offEvent(params: {
-        vendor: VendorType;
-    }, handler: (event: {
-        type: ConnectorEventType;
-        data: unknown;
-    }) => void): void;
+declare class DeviceJobQueue {
+    private _tail;
+    private _active;
+    private readonly _jobs;
+    /** Incremented on clear() so queued-but-not-yet-running jobs detect invalidation. */
+    private _generation;
+    private readonly _generationCancelReasons;
+    /**
+     * Enqueue a job. Runs after every previously-enqueued job has settled.
+     * `deviceId` is a label only — used by inspection / cancellation routing.
+     */
+    enqueue<T>(deviceId: string, job: (signal: AbortSignal) => Promise<T>, options?: JobOptions): Promise<T>;
+    /** Cancel the active job. If `deviceId` is given, only cancels when it matches. */
+    cancelActive(deviceId?: string): boolean;
+    /** Force cancel the active job. `reason` becomes signal.reason. */
+    forceCancelActive(deviceId?: string, reason?: Error): boolean;
+    /** Cancel the active job (alias for callers that previously needed multi-device cancel). */
+    cancelAllActive(reason?: Error): void;
+    /** Cancel the active job and invalidate queued jobs that have not started. */
+    cancelActiveAndPending(deviceId?: string, reason?: Error): boolean;
+    /** Get info about the currently active job, or null if idle. */
+    getActiveJob(deviceId?: string): ActiveJobInfo | null;
+    /** True if any job is currently running. */
+    isBusy(): boolean;
+    clear(reason?: Error): void;
 }
-/**
- * Adapt an IHardwareBridge (multi-vendor backend) into a single-vendor IConnector.
- * Every IConnector method becomes a transparent forward to bridge.<method>({ vendor, ... }).
- * Events are forwarded via bridge.onEvent / offEvent.
- *
- * Use this anywhere the actual hardware lives behind a process / context boundary
- * (Electron main, extension background, native module, worker, iframe).
- */
-declare function createBridgedConnector(vendor: VendorType, bridge: IHardwareBridge): IConnector;
 
 /**
  * Minimal typed event emitter using Map<string, Set<listener>>.
@@ -1032,6 +1046,32 @@ declare class TypedEventEmitter<TMap extends Record<string, any> = Record<string
     removeAllListeners(): void;
 }
 
+/** 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 supersedes (rejects) the prior pending entry. With the
+ * job queue running globally serially, cross-type collisions don't occur in
+ * normal flow — same-type preemption is a defensive measure for callers
+ * that fire the same request twice without waiting on the first.
+ *
+ * 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;
+}
+
 /**
  * Compare two semver strings (e.g. "2.1.0" vs "2.3.1").
  * Returns -1 if a < b, 0 if equal, 1 if a > b.
@@ -1044,7 +1084,10 @@ declare function ensure0x(hex: string): string;
 declare function stripHex(hex: string): string;
 /** Pad hex to 64 chars (32 bytes) with 0x prefix */
 declare function padHex64(hex: string): string;
-/** Convert a hex string (with or without 0x prefix) to a Uint8Array. */
+/**
+ * Convert a hex string (with or without 0x prefix) to a Uint8Array.
+ * Throws on invalid hex (non-hex characters, odd length).
+ */
 declare function hexToBytes(hex: string): Uint8Array;
 /** Convert a Uint8Array to a hex string (no 0x prefix). */
 declare function bytesToHex(bytes: Uint8Array): string;
@@ -1064,4 +1107,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 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 };
+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, type ConnectorUiEvent, DEVICE, DEVICE_EVENT, type DeviceCapabilities, type DeviceChangeEvent, type DeviceConnectEvent, type DeviceDescriptor, type DeviceDisconnectEvent, type DeviceEvent, type DeviceEventListener, type DeviceInfo, DeviceJobQueue, type DevicePermissionDeniedReason, type DevicePermissionResponse, 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 JobOptions, ORPHAN_ELIGIBLE_ERROR_CODES, type PassphraseResponse, 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 };