@onekeyfe/hwk-ledger-adapter 1.1.26-alpha.106 → 1.1.26-alpha.11

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { IHardwareWallet, IConnector, TransportType, IUiHandler, UiResponseEvent, DeviceInfo, Response, ChainCapability, EvmGetAddressParams, EvmAddress, ProgressCallback, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, ChainForFingerprint, ConnectionType, DeviceDescriptor, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, DeviceChangeEvent, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
+import { IHardwareWallet, IConnector, TransportType, UiResponseEvent, DeviceInfo, Response, ChainCapability, EvmGetAddressParams, EvmAddress, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, ChainForFingerprint, ConnectionType, DeviceDescriptor, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, DeviceChangeEvent, Failure, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
 import { DeviceManagementKit, DeviceActionState as DeviceActionState$1, DiscoveredDevice, ExecuteDeviceActionReturnType } from '@ledgerhq/device-management-kit';
 import { Address, Signature, SignerEth as SignerEth$1, TypedData } from '@ledgerhq/device-signer-kit-ethereum';
 import { SignerBtc as SignerBtc$1 } from '@ledgerhq/device-signer-kit-bitcoin';
@@ -21,22 +21,28 @@ interface LedgerAdapterOptions {
  * - Translates IHardwareWallet method calls to connector.call() invocations
  * - Maps connector results/errors to our Response<T> format with enriched error messages
  * - Translates connector events to HardwareEventMap events
- * - Integrates with IUiHandler for permission flows
+ * - Emits `REQUEST_DEVICE_PERMISSION` for OS-level permission checks
  */
 declare class LedgerAdapter implements IHardwareWallet {
     readonly vendor: "ledger";
     private readonly connector;
     private readonly emitter;
-    private _uiHandler;
     private readonly _handleSelectDevice;
     private _discoveredDevices;
     private _sessions;
     private readonly _uiRegistry;
+    private readonly _jobQueue;
     constructor(connector: IConnector, options?: LedgerAdapterOptions);
+    /**
+     * Classify a method's interruptibility.
+     * - Signing / typed data / transaction → 'confirm' (user may decide via preemption UI)
+     * - Read-only queries (getAddress / getPublicKey / getMasterFingerprint) → 'safe'
+     *   (auto-cancels any pending read for the same device)
+     */
+    private static _getInterruptibility;
     get activeTransport(): TransportType | null;
     getAvailableTransports(): TransportType[];
     switchTransport(_type: TransportType): Promise<void>;
-    setUiHandler(handler: Partial<IUiHandler>): void;
     init(_config?: unknown): Promise<void>;
     /**
      * Clear cached device/session state without tearing down the adapter.
@@ -52,18 +58,11 @@ declare class LedgerAdapter implements IHardwareWallet {
     getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
     getSupportedChains(): ChainCapability[];
     private callChain;
-    /**
-     * Batch version of callChain — checks permission once,
-     * fingerprint is verified on the first call inside connectorCall.
-     */
-    private callChainBatch;
     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>>;
     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>>;
@@ -72,18 +71,16 @@ declare class LedgerAdapter implements IHardwareWallet {
         masterFingerprint: string;
     }>>;
     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>>;
     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>>;
     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;
     off(event: string, listener: DeviceEventListener): void;
-    cancel(connectId: string): void;
+    cancel(connectId?: string): void;
     getChainFingerprint(connectId: string, deviceId: string, chain: ChainForFingerprint): Promise<Response<string>>;
     /**
      * Verify fingerprint using an existing sessionId directly.
@@ -128,13 +125,38 @@ declare class LedgerAdapter implements IHardwareWallet {
      * 4. On disconnect error: clears stale session, re-connects, retries once
      */
     private connectorCall;
-    /** Clear stale session, reconnect, and retry the call. */
+    /**
+     * Race a promise against an abort signal. If the signal fires, rejects with the
+     * signal's reason (or a generic Error). The underlying connector.call() cannot
+     * actually be cancelled on Ledger DMK, but the caller gets the abort immediately.
+     */
+    private static _abortable;
+    /** Throw an AbortError if signal is already aborted. */
+    private static _throwIfAborted;
+    /** Actual work done under the job queue — connection, fingerprint, call, and recovery. */
+    private _runConnectorCall;
+    /**
+     * Clear stale session, reconnect, and retry the call.
+     *
+     * Two-stage recovery: the inner retry first re-uses the current DMK to
+     * cut latency; if that still fails with a disconnect/timeout, the DMK
+     * itself is likely wedged (transport stuck after an abnormal teardown
+     * — process killed, USB yanked, browser kept the offscreen page across
+     * a session boundary). In that case we fully `connector.reset()` to
+     * force a fresh DMK + transport on the next round.
+     */
     private _retryWithFreshConnection;
     /**
-     * Ensure device permission before proceeding.
-     * - No connectId (searchDevices): check environment-level permission
-     * - With connectId (business methods): check device-level permission
-     * If not granted, calls onDevicePermission so the consumer can request access.
+     * Ensure OS-level device permission (Bluetooth / USB) before proceeding.
+     *
+     * Emits `REQUEST_DEVICE_PERMISSION` and awaits the consumer's
+     * `RECEIVE_DEVICE_PERMISSION` reply (60s budget covers "probe → system
+     * prompt → user tap" plus a generous margin). If the consumer never wires
+     * a handler or never replies, the wait times out and the operation fails
+     * fast so scanners/callers don't hang silently.
+     *
+     * - No connectId (searchDevices): environment-level permission
+     * - With connectId (business methods): device-level permission
      */
     private _ensureDevicePermission;
     /**
@@ -144,14 +166,10 @@ declare class LedgerAdapter implements IHardwareWallet {
     private errorToFailure;
     private deviceConnectHandler;
     private deviceDisconnectHandler;
-    private uiRequestHandler;
-    private uiEventHandler;
+    private uiEventForwarder;
     private registerEventListeners;
     private unregisterEventListeners;
-    private handleUiEvent;
     private connectorDeviceToDeviceInfo;
-    private extractDeviceInfoFromPayload;
-    private unknownDevice;
 }
 
 /**
@@ -188,7 +206,7 @@ declare class LedgerConnectorBase implements IConnector {
     private readonly _eventHandlers;
     private readonly _providedDmk;
     private readonly _createTransport;
-    private readonly _connectionType;
+    readonly connectionType: ConnectionType;
     private _connectIdToPath;
     private _pathToConnectId;
     /** Register a connectId <-> path mapping from a device descriptor. */
@@ -197,6 +215,10 @@ declare class LedgerConnectorBase implements IConnector {
     private _getPathForConnectId;
     /** Get external connectId from DMK path. Falls back to path itself. */
     private _getConnectIdForPath;
+    private readonly _cancellers;
+    private readonly _sessionStateSubs;
+    private _diagDeviceListSub;
+    private _diagDeviceListPrev;
     /**
      * Resolves a Ledger signer kit module by package name.
      * Override via constructor to use CJS paths for Metro (React Native).
@@ -224,8 +246,31 @@ declare class LedgerConnectorBase implements IConnector {
     searchDevices(): Promise<ConnectorDevice[]>;
     connect(deviceId?: string): Promise<ConnectorSession>;
     disconnect(sessionId: string): Promise<void>;
+    /**
+     * Subscribe to DMK's per-session state observable so that any autonomous
+     * disconnect (USB unplug, BLE drop, device sleep, transport reset) is
+     * surfaced as a `device-disconnect` event — without this, the upstream
+     * `LedgerAdapter._sessions` map would hold a dead session entry until
+     * the next call hit `DeviceSessionNotFound`.
+     *
+     * Best-effort: any error subscribing is swallowed so a flaky DMK
+     * doesn't break the connect path.
+     */
+    private _watchSessionState;
+    private _unwatchSessionState;
+    private _handleAutonomousDisconnect;
+    /**
+     * Start a long-lived listenToAvailableDevices subscription whose only job
+     * is to log every emission (with diff vs previous) so we can determine
+     * whether DMK proactively re-emits the device list when a USB device is
+     * unplugged or a BLE peripheral disappears. Pure observation — does NOT
+     * touch any cache or emit any event. See _diagDeviceListSub comment for
+     * rationale.
+     */
+    private _startDiagnosticDeviceListListen;
     call(sessionId: string, method: string, params: unknown): Promise<unknown>;
-    cancel(_sessionId: string): Promise<void>;
+    private _dispatch;
+    cancel(sessionId: string): Promise<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;
@@ -253,6 +298,12 @@ declare class LedgerConnectorBase implements IConnector {
     private _resetSignersAndSessions;
     private _resetAll;
     protected _emit<K extends ConnectorEventType>(event: K, data: ConnectorEventMap[K]): void;
+    /**
+     * Return a per-call ctx with the chain's Ledger app name pre-bound to
+     * wrapError, so chain handlers don't need to repeat `{ defaultAppName: 'X' }`
+     * at every catch site. Falls through unchanged for unknown methods.
+     */
+    private _ctxForMethod;
     private _wrapError;
 }
 
@@ -327,6 +378,30 @@ interface SignerBtcAddress {
     address: string;
 }
 
+/** Optional context attached to the rejection when a canceller fires. */
+interface CancelReason {
+    code?: number;
+    tag?: string;
+    message?: string;
+}
+/**
+ * Convert a DMK DeviceAction (Observable-based) into a Promise.
+ * Handles pending -> completed/error state transitions and interaction callbacks.
+ *
+ * Tracks the last DMK step observed (e.g. `signer.eth.steps.blindSignTransactionFallback`)
+ * and attaches it to the rejected error as a non-enumerable `_lastStep` property,
+ * so upstream error classifiers can distinguish failure contexts (e.g. Blind signing
+ * disabled vs. generic Invalid data).
+ *
+ * @param timeoutMs  Timeout in ms. Resets each time the Observable emits (device is alive).
+ *                   Pass 0 to disable. Default: 30s.
+ * @param onRegisterCanceller  Optional callback that receives a function which, when
+ *                             called, unsubscribes and cancels the underlying DeviceAction
+ *                             (releases DMK's IntentQueue slot). Caller is responsible
+ *                             for invoking the canceller on timeout/abort scenarios.
+ */
+declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void): Promise<T>;
+
 /**
  * Wraps Ledger's SDK signer (Observable-based DeviceActions) into
  * a simple async interface returning plain serializable data.
@@ -335,6 +410,12 @@ declare class SignerEth {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
     constructor(_sdk: SignerEth$1);
+    /**
+     * Optional callback registered per-call so the caller can obtain a canceller
+     * for the underlying DeviceAction. Caller can invoke it to release DMK's
+     * IntentQueue slot and unsubscribe from the action's observable.
+     */
+    onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void;
     getAddress(derivationPath: string, options?: {
         checkOnDevice?: boolean;
     }): Promise<SignerEvmAddress>;
@@ -352,16 +433,16 @@ type SignerEthBuilderFn = (args: {
     build(): SignerEth$1;
 }>;
 /**
- * Manages per-sessionId SignerEth instances.
- * Creates on demand, caches for reuse, invalidates on session change.
+ * Per-sessionId SignerEth factory. Builds fresh on every call — DMK signers
+ * hold DeviceAction state that isn't safe to reuse, so `invalidate` /
+ * `clearAll` are kept as no-op lifecycle hooks for callers.
  */
 declare class SignerManager {
-    private readonly _cache;
     private readonly _dmk;
     private readonly _builderFn;
     constructor(dmk: DeviceManagementKit, builderFn?: SignerEthBuilderFn);
     getOrCreate(sessionId: string): Promise<SignerEth>;
-    invalidate(sessionId: string): void;
+    invalidate(_sessionId: string): void;
     clearAll(): void;
     private static _defaultBuilder;
 }
@@ -377,6 +458,7 @@ type BtcMessageOptions = Parameters<SignerBtc$1['signMessage']>[2];
 declare class SignerBtc {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
+    onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void;
     constructor(_sdk: SignerBtc$1);
     getWalletAddress(wallet: BtcWallet, addressIndex: number, options?: {
         checkOnDevice?: boolean;
@@ -422,6 +504,7 @@ type SolMsgOptions = Parameters<SignerSolana['signMessage']>[2];
 declare class SignerSol {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
+    onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void;
     constructor(_sdk: SignerSolana);
     /**
      * Get the Solana address (base58-encoded Ed25519 public key) at the given derivation path.
@@ -462,20 +545,6 @@ declare class DmkTransport extends Transport {
     close(): Promise<void>;
 }
 
-/**
- * Convert a DMK DeviceAction (Observable-based) into a Promise.
- * Handles pending -> completed/error state transitions and interaction callbacks.
- *
- * Tracks the last DMK step observed (e.g. `signer.eth.steps.blindSignTransactionFallback`)
- * and attaches it to the rejected error as a non-enumerable `_lastStep` property,
- * so upstream error classifiers can distinguish failure contexts (e.g. Blind signing
- * disabled vs. generic Invalid data).
- *
- * @param timeoutMs  Timeout in ms. Resets each time the Observable emits (device is alive).
- *                   Pass 0 to disable. Default: 30s.
- */
-declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number): Promise<T>;
-
 interface AppManagerOptions {
     waitMs?: number;
     maxRetries?: number;
@@ -505,9 +574,16 @@ declare class AppManager {
      * 5. Poll until the device confirms the target app is running.
      */
     /**
-     * @param onConfirmOnDevice Called after OpenAppCommand succeeds —
-     *   the device is now showing a confirmation prompt to the user.
-     *   NOT called if the app is already open or if the app is not installed.
+     * @param onConfirmOnDevice Called BEFORE OpenAppCommand is issued — the
+     *   device is about to display "Open <app>" on screen and wait for the
+     *   user's button press. UI consumers should show their "open app" prompt
+     *   in response. NOT called when the target app is already open (no user
+     *   interaction needed in that case).
+     *
+     * Important: OpenAppCommand is blocking. It does not resolve until the user
+     *   has physically confirmed on the device, so anything that runs AFTER
+     *   `await this._openApp(...)` lands AFTER the prompt is already gone.
+     *   Hence the callback must fire BEFORE that await.
      */
     ensureAppOpen(sessionId: string, targetAppName: string, onConfirmOnDevice?: () => void): Promise<void>;
     private _getCurrentApp;
@@ -522,16 +598,63 @@ declare class AppManager {
     private _wait;
 }
 
+/**
+ * Ledger-specific Failure: adds `appName` for "the currently-open app" — a
+ * Ledger hardware concept not shared with other vendors, so it lives here
+ * rather than in core's generic Failure.
+ */
+type LedgerFailure = Omit<Failure, 'payload'> & {
+    payload: Failure['payload'] & {
+        appName?: string;
+    };
+};
+interface WrapErrorOptions {
+    /**
+     * Fallback app name when the raw error doesn't carry `appName` itself
+     * (DMK signer errors don't). Used by mapLedgerError so downstream
+     * AppNotOpen / WrongApp / AppTooOld toasts can interpolate `{appName}`.
+     */
+    defaultAppName?: string;
+}
+/**
+ * Structurally compatible with `Failure`; writes `appName` only when provided,
+ * so `'appName' in payload` is a reliable "has info" signal for consumers.
+ */
+declare function ledgerFailure(code: HardwareErrorCode, error: string, appName?: string): LedgerFailure;
 /** Check if an error (or any error in its chain) represents a locked Ledger device. */
 declare function isDeviceLockedError(err: unknown): boolean;
 /**
- * Map a Ledger DMK error to a HardwareErrorCode and human-readable message
- * with actionable recovery information for the caller.
+ * Map a Ledger DMK error to a HardwareErrorCode and human-readable message.
+ * `opts.defaultAppName` fills `appName` when the raw error doesn't carry it
+ * (DMK signer errors don't).
  */
-declare function mapLedgerError(err: unknown): {
+declare function mapLedgerError(err: unknown, opts?: WrapErrorOptions): {
     code: HardwareErrorCode;
     message: string;
     appName?: string;
 };
 
-export { AppManager, type DeviceActionState, type DmkDiscoveredDevice, DmkTransport, LedgerAdapter, LedgerConnectorBase, type LedgerConnectorBaseOptions, LedgerDeviceManager, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, deviceActionToPromise, isDeviceLockedError, mapLedgerError };
+/**
+ * SDK-global event bus. Per-runtime singleton — each process subscribes
+ * independently; cross-process hosts forward events over their own IPC.
+ */
+type SdkLogEvent = {
+    type: 'log';
+    level: 'debug' | 'error';
+    /** Pre-stringified payload. */
+    message: string;
+};
+/** Add new variants here; hosts dispatch on `event.type`. */
+type SdkEvent = SdkLogEvent;
+type SdkEventListener = (event: SdkEvent) => void;
+declare function onSdkEvent(listener: SdkEventListener): () => void;
+declare function offSdkEvent(listener: SdkEventListener): void;
+
+/**
+ * Extract the stable 4-digit HEX identifier from a Ledger BLE device name.
+ * e.g., "Nano X 123A" -> "123A", "Ledger Nano X AB12" -> "AB12"
+ * Returns undefined if no valid HEX suffix found.
+ */
+declare function extractBleHexId(name?: string): string | undefined;
+
+export { AppManager, type DeviceActionState, type DmkDiscoveredDevice, DmkTransport, LedgerAdapter, LedgerConnectorBase, type LedgerConnectorBaseOptions, LedgerDeviceManager, type LedgerFailure, type SdkEvent, type SdkEventListener, type SdkLogEvent, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, deviceActionToPromise, extractBleHexId, isDeviceLockedError, ledgerFailure, mapLedgerError, offSdkEvent, onSdkEvent };