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

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, 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, 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';
@@ -32,7 +32,15 @@ declare class LedgerAdapter implements IHardwareWallet {
     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>;
@@ -128,6 +136,16 @@ declare class LedgerAdapter implements IHardwareWallet {
      * 4. On disconnect error: clears stale session, re-connects, retries once
      */
     private connectorCall;
+    /**
+     * 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. */
     private _retryWithFreshConnection;
     /**
@@ -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,7 @@ declare class LedgerConnectorBase implements IConnector {
     private _getPathForConnectId;
     /** Get external connectId from DMK path. Falls back to path itself. */
     private _getConnectIdForPath;
+    private readonly _cancellers;
     /**
      * Resolves a Ledger signer kit module by package name.
      * Override via constructor to use CJS paths for Metro (React Native).
@@ -225,7 +244,7 @@ declare class LedgerConnectorBase implements IConnector {
     connect(deviceId?: string): Promise<ConnectorSession>;
     disconnect(sessionId: string): Promise<void>;
     call(sessionId: string, method: string, params: unknown): Promise<unknown>;
-    cancel(_sessionId: string): Promise<void>;
+    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;
@@ -335,6 +354,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: () => void) => void;
     getAddress(derivationPath: string, options?: {
         checkOnDevice?: boolean;
     }): Promise<SignerEvmAddress>;
@@ -352,16 +377,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 +402,7 @@ type BtcMessageOptions = Parameters<SignerBtc$1['signMessage']>[2];
 declare class SignerBtc {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
+    onRegisterCanceller?: (cancel: () => void) => void;
     constructor(_sdk: SignerBtc$1);
     getWalletAddress(wallet: BtcWallet, addressIndex: number, options?: {
         checkOnDevice?: boolean;
@@ -422,6 +448,7 @@ type SolMsgOptions = Parameters<SignerSolana['signMessage']>[2];
 declare class SignerSol {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
+    onRegisterCanceller?: (cancel: () => void) => void;
     constructor(_sdk: SignerSolana);
     /**
      * Get the Solana address (base58-encoded Ed25519 public key) at the given derivation path.
@@ -473,8 +500,12 @@ declare class DmkTransport extends Transport {
  *
  * @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): Promise<T>;
+declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: () => void) => void): Promise<T>;
 
 interface AppManagerOptions {
     waitMs?: number;
@@ -522,6 +553,21 @@ 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;
+    };
+};
+/**
+ * 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;
 /**
@@ -534,4 +580,21 @@ declare function mapLedgerError(err: unknown): {
     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 };
+/**
+ * Centralised debug logger for the Ledger adapter.
+ *
+ * Off by default. Toggle programmatically via `setDebugEnabled(true)`.
+ */
+/** Enable or disable debug logging at runtime. */
+declare function setDebugEnabled(value: boolean): void;
+/** Returns the current debug-enabled state. */
+declare function isDebugEnabled(): boolean;
+
+/**
+ * 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, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, deviceActionToPromise, extractBleHexId, isDebugEnabled, isDeviceLockedError, ledgerFailure, mapLedgerError, setDebugEnabled };

package/dist/index.d.ts

@@ -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, 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, 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';
@@ -32,7 +32,15 @@ declare class LedgerAdapter implements IHardwareWallet {
     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>;
@@ -128,6 +136,16 @@ declare class LedgerAdapter implements IHardwareWallet {
      * 4. On disconnect error: clears stale session, re-connects, retries once
      */
     private connectorCall;
+    /**
+     * 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. */
     private _retryWithFreshConnection;
     /**
@@ -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,7 @@ declare class LedgerConnectorBase implements IConnector {
     private _getPathForConnectId;
     /** Get external connectId from DMK path. Falls back to path itself. */
     private _getConnectIdForPath;
+    private readonly _cancellers;
     /**
      * Resolves a Ledger signer kit module by package name.
      * Override via constructor to use CJS paths for Metro (React Native).
@@ -225,7 +244,7 @@ declare class LedgerConnectorBase implements IConnector {
     connect(deviceId?: string): Promise<ConnectorSession>;
     disconnect(sessionId: string): Promise<void>;
     call(sessionId: string, method: string, params: unknown): Promise<unknown>;
-    cancel(_sessionId: string): Promise<void>;
+    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;
@@ -335,6 +354,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: () => void) => void;
     getAddress(derivationPath: string, options?: {
         checkOnDevice?: boolean;
     }): Promise<SignerEvmAddress>;
@@ -352,16 +377,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 +402,7 @@ type BtcMessageOptions = Parameters<SignerBtc$1['signMessage']>[2];
 declare class SignerBtc {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
+    onRegisterCanceller?: (cancel: () => void) => void;
     constructor(_sdk: SignerBtc$1);
     getWalletAddress(wallet: BtcWallet, addressIndex: number, options?: {
         checkOnDevice?: boolean;
@@ -422,6 +448,7 @@ type SolMsgOptions = Parameters<SignerSolana['signMessage']>[2];
 declare class SignerSol {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
+    onRegisterCanceller?: (cancel: () => void) => void;
     constructor(_sdk: SignerSolana);
     /**
      * Get the Solana address (base58-encoded Ed25519 public key) at the given derivation path.
@@ -473,8 +500,12 @@ declare class DmkTransport extends Transport {
  *
  * @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): Promise<T>;
+declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: () => void) => void): Promise<T>;
 
 interface AppManagerOptions {
     waitMs?: number;
@@ -522,6 +553,21 @@ 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;
+    };
+};
+/**
+ * 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;
 /**
@@ -534,4 +580,21 @@ declare function mapLedgerError(err: unknown): {
     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 };
+/**
+ * Centralised debug logger for the Ledger adapter.
+ *
+ * Off by default. Toggle programmatically via `setDebugEnabled(true)`.
+ */
+/** Enable or disable debug logging at runtime. */
+declare function setDebugEnabled(value: boolean): void;
+/** Returns the current debug-enabled state. */
+declare function isDebugEnabled(): boolean;
+
+/**
+ * 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, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, deviceActionToPromise, extractBleHexId, isDebugEnabled, isDeviceLockedError, ledgerFailure, mapLedgerError, setDebugEnabled };