@onekeyfe/hwk-ledger-adapter 1.1.26-alpha.12 → 1.1.26-alpha.14

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-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, DeviceDescriptor, DeviceChangeEvent, ConnectionType, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, Failure, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
+import { IHardwareWallet, IConnector, TransportType, UiResponseEvent, SearchDevicesOptions, 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, DeviceDescriptor, DeviceChangeEvent, ConnectionType, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, Failure, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
 import { DeviceActionState as DeviceActionState$1, DiscoveredDevice, ExecuteDeviceActionReturnType, DeviceManagementKit } from '@ledgerhq/device-management-kit';
 import { Address, Signature, SignerEth as SignerEth$1, TypedData } from '@ledgerhq/device-signer-kit-ethereum';
+import { ContextModule } from '@ledgerhq/context-module';
 import { SignerBtc as SignerBtc$1 } from '@ledgerhq/device-signer-kit-bitcoin';
 import { SignerSolana } from '@ledgerhq/device-signer-kit-solana';
 import Transport from '@ledgerhq/hw-transport';
@@ -37,8 +38,9 @@ declare class LedgerAdapter implements IHardwareWallet {
     resetState(): void;
     dispose(): Promise<void>;
     uiResponse(response: UiResponseEvent): void;
-    searchDevices(): Promise<DeviceInfo[]>;
+    searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
     private static readonly MAX_BUSINESS_RETRY_BUDGET;
+    private static readonly STUCK_APP_RETRY_DELAY_MS;
     private static readonly MAX_DOCONNECT_CONFIRMS;
     private _lastCancelReason;
     private static _createDeviceBusyError;
@@ -132,6 +134,16 @@ declare class LedgerAdapter implements IHardwareWallet {
     private static _throwIfAborted;
     /** Actual work done under the job queue — connection, fingerprint, call, and recovery. */
     private _runConnectorCall;
+    /**
+     * Stuck-app recovery: pause for the device's UI transition, then retry once.
+     *
+     * Caller has already cleared the session + reset connector. We wait so Stax
+     * finishes its post-CloseApp animation, then go through ensureConnected +
+     * fingerprint check + call exactly once. Caller decides what to do on a
+     * second stuck-app hit.
+     */
+    private _retryAfterStuckApp;
+    private _sleepAbortable;
     /**
      * Clear stale session, reconnect, and retry the call.
      *
@@ -244,6 +256,14 @@ declare class LedgerDeviceManager {
     requestDevice(): Promise<void>;
     /** Lookup a previously-discovered device's display name. */
     getDeviceName(deviceId: string): string | undefined;
+    /** Lookup minimal model/signal info from a previously-discovered device. */
+    getDiscoveredDeviceInfo(deviceId: string): {
+        model?: string;
+        modelName?: string;
+        name?: string;
+        rssi?: number | null;
+    } | undefined;
+    hasDiscoveredDevice(deviceId: string): boolean;
     /** Connect to a previously discovered device. Returns sessionId. */
     connect(deviceId: string): Promise<string>;
     /** Disconnect a session. */
@@ -288,7 +308,14 @@ interface LedgerConnectorBaseOptions {
  * Subclasses only need to:
  * 1. Supply a transport factory via the constructor.
  * 2. Optionally override `_resolveConnectId()` for transport-specific
- *    device identity resolution (e.g. BLE hex ID extraction).
+ *    device identity resolution.
+ *
+ * Invariant: one instance = one transport. `connectionType` is fixed at
+ * construction. To switch transport (e.g. desktop BLE ↔ WebHID), the host
+ * must build a new connector instance and replace the old one — don't add
+ * multiple transports to a single instance. Lifting this constraint would
+ * require routing `connectionType` from `descriptor.transport` per-device
+ * and updating every `this.connectionType` branch in this file.
  */
 declare class LedgerConnectorBase implements IConnector {
     private _deviceManager;
@@ -298,12 +325,6 @@ declare class LedgerConnectorBase implements IConnector {
     private readonly _providedDmk;
     private readonly _createTransport;
     readonly connectionType: ConnectionType;
-    private _connectIdToPath;
-    private _pathToConnectId;
-    /** Get DMK path from external connectId. Falls back to connectId itself. */
-    private _getPathForConnectId;
-    /** Get external connectId from DMK path. Falls back to path itself. */
-    private _getConnectIdForPath;
     private readonly _cancellers;
     private readonly _sessionStateSubs;
     /**
@@ -314,6 +335,10 @@ declare class LedgerConnectorBase implements IConnector {
     protected _importLedgerKit: (pkg: string) => Promise<any>;
     /** Context object passed to per-chain handler functions. */
     private readonly _ctx;
+    /** When true, BLE direct-connect throws NotAdvertising if the pre-flight
+     *  scan can't see the device — guard for GATT stacks that wedge on
+     *  non-advertising peripherals (iOS). */
+    private readonly _requirePreFlightScan;
     constructor(createTransport: TransportFactory, options?: {
         connectionType?: ConnectionType;
         dmk?: DeviceManagementKit;
@@ -323,11 +348,13 @@ declare class LedgerConnectorBase implements IConnector {
          * For Metro (React Native): pass a resolver that uses CJS paths.
          */
         importLedgerKit?: (pkg: string) => Promise<any>;
+        /** Default false. RN-iOS subclass should pass `true`. */
+        requirePreFlightScan?: boolean;
     });
     /**
      * Resolve the connectId for a discovered device descriptor.
      * Default: use the DMK path (ephemeral UUID).
-     * Override in subclasses to extract stable identifiers (e.g. BLE hex ID).
+     * Override in subclasses only when the public connectId differs from the transport path.
      */
     protected _resolveConnectId(descriptor: DeviceDescriptor): string;
     /**
@@ -371,12 +398,11 @@ declare class LedgerConnectorBase implements IConnector {
     private _invalidateSession;
     /**
      * Replace an old session with a new one after app switch.
-     * Updates the connectId→path mapping so subsequent calls() use the new session,
-     * and emits device-connect so the adapter updates its _sessions Map.
+     * Emits device-connect so the adapter updates its _sessions Map.
      */
     private _replaceSession;
     /**
-     * Light reset: clear signer/session state but keep DMK and ID mapping alive.
+     * Light reset: clear signer/session state but keep DMK alive.
      * Used by connect() retry — we want to re-discover with the same transport.
      *
      * Note: drops the device manager but tears down its RxJS subs first via
@@ -446,8 +472,14 @@ type SignerEthBuilderFn = (args: {
     dmk: DeviceManagementKit;
     sessionId: string;
 }) => {
+    withContextModule?(contextModule: ContextModule): {
+        build(): SignerEth$1;
+    };
     build(): SignerEth$1;
 } | Promise<{
+    withContextModule?(contextModule: ContextModule): {
+        build(): SignerEth$1;
+    };
     build(): SignerEth$1;
 }>;
 /**
@@ -463,6 +495,8 @@ declare class SignerManager {
     invalidate(_sessionId: string): void;
     clearAll(): void;
     private static _defaultBuilder;
+    private static _createContextModule;
+    static wrapBlindSigningReportNonBlocking<T extends ContextModule>(contextModule: T): T;
 }
 
 type BtcWallet = Parameters<SignerBtc$1['getWalletAddress']>[0];
@@ -655,12 +689,7 @@ 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;
+declare function debugLog(...args: unknown[]): void;
 
 /**
  * Ledger DMK transport identifiers that represent BLE devices.
@@ -675,6 +704,5 @@ declare function extractBleHexId(name?: string): string | undefined;
 declare function isLedgerDmkBleTransport(transport?: string): boolean;
 declare function isLedgerBleConnectionType(connectionType?: ConnectionType): boolean;
 declare function isLedgerBleDescriptor(connectionType: ConnectionType, descriptor: DeviceDescriptor): boolean;
-declare function isValidLedgerBleConnectId(connectId?: string): boolean;
 
-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, isLedgerBleConnectionType, isLedgerBleDescriptor, isLedgerDmkBleTransport, isValidLedgerBleConnectId, ledgerFailure, mapLedgerError, offSdkEvent, onSdkEvent };
+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, debugLog, deviceActionToPromise, isDeviceLockedError, isLedgerBleConnectionType, isLedgerBleDescriptor, isLedgerDmkBleTransport, ledgerFailure, mapLedgerError, offSdkEvent, onSdkEvent };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-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, DeviceDescriptor, DeviceChangeEvent, ConnectionType, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, Failure, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
+import { IHardwareWallet, IConnector, TransportType, UiResponseEvent, SearchDevicesOptions, 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, DeviceDescriptor, DeviceChangeEvent, ConnectionType, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, Failure, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
 import { DeviceActionState as DeviceActionState$1, DiscoveredDevice, ExecuteDeviceActionReturnType, DeviceManagementKit } from '@ledgerhq/device-management-kit';
 import { Address, Signature, SignerEth as SignerEth$1, TypedData } from '@ledgerhq/device-signer-kit-ethereum';
+import { ContextModule } from '@ledgerhq/context-module';
 import { SignerBtc as SignerBtc$1 } from '@ledgerhq/device-signer-kit-bitcoin';
 import { SignerSolana } from '@ledgerhq/device-signer-kit-solana';
 import Transport from '@ledgerhq/hw-transport';
@@ -37,8 +38,9 @@ declare class LedgerAdapter implements IHardwareWallet {
     resetState(): void;
     dispose(): Promise<void>;
     uiResponse(response: UiResponseEvent): void;
-    searchDevices(): Promise<DeviceInfo[]>;
+    searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
     private static readonly MAX_BUSINESS_RETRY_BUDGET;
+    private static readonly STUCK_APP_RETRY_DELAY_MS;
     private static readonly MAX_DOCONNECT_CONFIRMS;
     private _lastCancelReason;
     private static _createDeviceBusyError;
@@ -132,6 +134,16 @@ declare class LedgerAdapter implements IHardwareWallet {
     private static _throwIfAborted;
     /** Actual work done under the job queue — connection, fingerprint, call, and recovery. */
     private _runConnectorCall;
+    /**
+     * Stuck-app recovery: pause for the device's UI transition, then retry once.
+     *
+     * Caller has already cleared the session + reset connector. We wait so Stax
+     * finishes its post-CloseApp animation, then go through ensureConnected +
+     * fingerprint check + call exactly once. Caller decides what to do on a
+     * second stuck-app hit.
+     */
+    private _retryAfterStuckApp;
+    private _sleepAbortable;
     /**
      * Clear stale session, reconnect, and retry the call.
      *
@@ -244,6 +256,14 @@ declare class LedgerDeviceManager {
     requestDevice(): Promise<void>;
     /** Lookup a previously-discovered device's display name. */
     getDeviceName(deviceId: string): string | undefined;
+    /** Lookup minimal model/signal info from a previously-discovered device. */
+    getDiscoveredDeviceInfo(deviceId: string): {
+        model?: string;
+        modelName?: string;
+        name?: string;
+        rssi?: number | null;
+    } | undefined;
+    hasDiscoveredDevice(deviceId: string): boolean;
     /** Connect to a previously discovered device. Returns sessionId. */
     connect(deviceId: string): Promise<string>;
     /** Disconnect a session. */
@@ -288,7 +308,14 @@ interface LedgerConnectorBaseOptions {
  * Subclasses only need to:
  * 1. Supply a transport factory via the constructor.
  * 2. Optionally override `_resolveConnectId()` for transport-specific
- *    device identity resolution (e.g. BLE hex ID extraction).
+ *    device identity resolution.
+ *
+ * Invariant: one instance = one transport. `connectionType` is fixed at
+ * construction. To switch transport (e.g. desktop BLE ↔ WebHID), the host
+ * must build a new connector instance and replace the old one — don't add
+ * multiple transports to a single instance. Lifting this constraint would
+ * require routing `connectionType` from `descriptor.transport` per-device
+ * and updating every `this.connectionType` branch in this file.
  */
 declare class LedgerConnectorBase implements IConnector {
     private _deviceManager;
@@ -298,12 +325,6 @@ declare class LedgerConnectorBase implements IConnector {
     private readonly _providedDmk;
     private readonly _createTransport;
     readonly connectionType: ConnectionType;
-    private _connectIdToPath;
-    private _pathToConnectId;
-    /** Get DMK path from external connectId. Falls back to connectId itself. */
-    private _getPathForConnectId;
-    /** Get external connectId from DMK path. Falls back to path itself. */
-    private _getConnectIdForPath;
     private readonly _cancellers;
     private readonly _sessionStateSubs;
     /**
@@ -314,6 +335,10 @@ declare class LedgerConnectorBase implements IConnector {
     protected _importLedgerKit: (pkg: string) => Promise<any>;
     /** Context object passed to per-chain handler functions. */
     private readonly _ctx;
+    /** When true, BLE direct-connect throws NotAdvertising if the pre-flight
+     *  scan can't see the device — guard for GATT stacks that wedge on
+     *  non-advertising peripherals (iOS). */
+    private readonly _requirePreFlightScan;
     constructor(createTransport: TransportFactory, options?: {
         connectionType?: ConnectionType;
         dmk?: DeviceManagementKit;
@@ -323,11 +348,13 @@ declare class LedgerConnectorBase implements IConnector {
          * For Metro (React Native): pass a resolver that uses CJS paths.
          */
         importLedgerKit?: (pkg: string) => Promise<any>;
+        /** Default false. RN-iOS subclass should pass `true`. */
+        requirePreFlightScan?: boolean;
     });
     /**
      * Resolve the connectId for a discovered device descriptor.
      * Default: use the DMK path (ephemeral UUID).
-     * Override in subclasses to extract stable identifiers (e.g. BLE hex ID).
+     * Override in subclasses only when the public connectId differs from the transport path.
      */
     protected _resolveConnectId(descriptor: DeviceDescriptor): string;
     /**
@@ -371,12 +398,11 @@ declare class LedgerConnectorBase implements IConnector {
     private _invalidateSession;
     /**
      * Replace an old session with a new one after app switch.
-     * Updates the connectId→path mapping so subsequent calls() use the new session,
-     * and emits device-connect so the adapter updates its _sessions Map.
+     * Emits device-connect so the adapter updates its _sessions Map.
      */
     private _replaceSession;
     /**
-     * Light reset: clear signer/session state but keep DMK and ID mapping alive.
+     * Light reset: clear signer/session state but keep DMK alive.
      * Used by connect() retry — we want to re-discover with the same transport.
      *
      * Note: drops the device manager but tears down its RxJS subs first via
@@ -446,8 +472,14 @@ type SignerEthBuilderFn = (args: {
     dmk: DeviceManagementKit;
     sessionId: string;
 }) => {
+    withContextModule?(contextModule: ContextModule): {
+        build(): SignerEth$1;
+    };
     build(): SignerEth$1;
 } | Promise<{
+    withContextModule?(contextModule: ContextModule): {
+        build(): SignerEth$1;
+    };
     build(): SignerEth$1;
 }>;
 /**
@@ -463,6 +495,8 @@ declare class SignerManager {
     invalidate(_sessionId: string): void;
     clearAll(): void;
     private static _defaultBuilder;
+    private static _createContextModule;
+    static wrapBlindSigningReportNonBlocking<T extends ContextModule>(contextModule: T): T;
 }
 
 type BtcWallet = Parameters<SignerBtc$1['getWalletAddress']>[0];
@@ -655,12 +689,7 @@ 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;
+declare function debugLog(...args: unknown[]): void;
 
 /**
  * Ledger DMK transport identifiers that represent BLE devices.
@@ -675,6 +704,5 @@ declare function extractBleHexId(name?: string): string | undefined;
 declare function isLedgerDmkBleTransport(transport?: string): boolean;
 declare function isLedgerBleConnectionType(connectionType?: ConnectionType): boolean;
 declare function isLedgerBleDescriptor(connectionType: ConnectionType, descriptor: DeviceDescriptor): boolean;
-declare function isValidLedgerBleConnectId(connectId?: string): boolean;
 
-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, isLedgerBleConnectionType, isLedgerBleDescriptor, isLedgerDmkBleTransport, isValidLedgerBleConnectId, ledgerFailure, mapLedgerError, offSdkEvent, onSdkEvent };
+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, debugLog, deviceActionToPromise, isDeviceLockedError, isLedgerBleConnectionType, isLedgerBleDescriptor, isLedgerDmkBleTransport, ledgerFailure, mapLedgerError, offSdkEvent, onSdkEvent };