@onekeyfe/hwk-ledger-adapter 1.1.26-alpha.8 → 1.1.26-patch.1

package/dist/index.d.mts

@@ -1,45 +1,22 @@
-import { IHardwareWallet, IConnector, TransportType, 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 { 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';
 
-interface LedgerAdapterOptions {
-    /**
-     * `true` — emit `REQUEST_SELECT_DEVICE` on multi-device discovery and await
-     * `uiResponse({ type: RECEIVE_SELECT_DEVICE, payload: { sdkConnectId } })`.
-     * `false` (default) — silently pick the first device.
-     */
-    handleSelectDevice?: boolean;
-}
-/**
- * Ledger hardware wallet adapter that delegates to an IConnector.
- *
- * This is a thin translation layer that:
- * - Accepts a pre-configured IConnector (transport decisions are made at connector creation time)
- * - 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
- * - Emits `REQUEST_DEVICE_PERMISSION` for OS-level permission checks
- */
 declare class LedgerAdapter implements IHardwareWallet {
     readonly vendor: "ledger";
     private readonly connector;
     private readonly emitter;
-    private readonly _handleSelectDevice;
     private _discoveredDevices;
     private _sessions;
     private readonly _uiRegistry;
+    private _btcHighIndexConfirmedThisSession;
     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;
+    private _doConnectAbortController;
+    constructor(connector: IConnector);
     get activeTransport(): TransportType | null;
     getAvailableTransports(): TransportType[];
     switchTransport(_type: TransportType): Promise<void>;
@@ -52,24 +29,23 @@ declare class LedgerAdapter implements IHardwareWallet {
     resetState(): void;
     dispose(): Promise<void>;
     uiResponse(response: UiResponseEvent): void;
-    searchDevices(): Promise<DeviceInfo[]>;
+    searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
+    private _evictAllSessions;
+    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;
     connectDevice(connectId: string): Promise<Response<string>>;
     disconnectDevice(connectId: string): Promise<void>;
     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>>;
@@ -78,18 +54,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.
@@ -116,15 +90,23 @@ declare class LedgerAdapter implements IHardwareWallet {
      *
      * - If a session already exists for the given connectId, reuse it.
      * - If ANY session exists (Ledger IDs are ephemeral), reuse it.
-     * - Otherwise: search → 1 device: auto-connect, multiple: ask user, 0: throw.
+     * - Otherwise: search → exactly 1 USB device auto-connects; multiple or none throws.
      */
-    private static readonly MAX_DEVICE_RETRY;
     private _connectingPromise;
     private _waitForDeviceConnect;
+    /**
+     * Decide whether a BTC pubkey call needs `showOnDevice=true` because of
+     * the BTC App's account-index policy, asking the user once per session.
+     *
+     * Returns the params to pass through (with `showOnDevice` possibly
+     * promoted), or `null` if the user declined.
+     */
+    private _gateBtcHighIndex;
+    private _waitForBtcHighIndexConfirm;
     private ensureConnected;
     private _doConnect;
     private _connectFirstOrSelect;
-    private _chooseDeviceFromList;
+    private _connectDeviceOrThrow;
     /**
      * Call the connector with automatic session resolution and disconnect retry.
      *
@@ -135,16 +117,31 @@ declare class LedgerAdapter implements IHardwareWallet {
      */
     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.
+     * Race a promise against an abort signal. On abort, rejects with
+     * signal.reason → instance _lastCancelReason → generic Error('Aborted').
      */
-    private static _abortable;
+    private _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. */
+    /**
+     * 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.
+     *
+     * Timeout recovery starts with a full connector reset. After an APDU
+     * timeout, DMK/transport state may still emit malformed responses; retrying
+     * on the same DMK can poison the next chain switch.
+     */
     private _retryWithFreshConnection;
     /**
      * Ensure OS-level device permission (Bluetooth / USB) before proceeding.
@@ -166,14 +163,115 @@ 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;
+}
+
+/**
+ * Re-export DMK types under local aliases for backward compatibility.
+ * These replace the previous duck-typed interfaces with the real SDK types.
+ */
+type DmkDiscoveredDevice = DiscoveredDevice;
+/**
+ * DMK DeviceAction — the Observable-based return type of all DMK signer methods.
+ *
+ * This is a permissive alias for `ExecuteDeviceActionReturnType` that accepts
+ * any Error and IntermediateValue generics. Signer wrapper code only cares about
+ * the Output type and the observable/cancel shape.
+ */
+type DeviceAction<T> = ExecuteDeviceActionReturnType<T, any, any>;
+/**
+ * DMK DeviceActionState — re-exported with permissive Error/IntermediateValue.
+ * The real type is a discriminated union on `status`.
+ */
+type DeviceActionState<T> = DeviceActionState$1<T, any, any>;
+/** ETH address result — re-exported from DMK for backward compatibility. */
+type SignerEvmAddress = Address;
+/** ETH signature result — re-exported from DMK for backward compatibility. */
+type SignerEvmSignature = Signature;
+/** BTC address result (WalletAddress not exported from DMK top-level). */
+interface SignerBtcAddress {
+    address: string;
+}
+
+/**
+ * Manages device discovery, connection, and session tracking.
+ * Wraps DMK's Observable APIs into simpler imperative calls.
+ */
+declare class LedgerDeviceManager {
+    private readonly _dmk;
+    private readonly _discovered;
+    private readonly _sessions;
+    private readonly _sessionToDevice;
+    private _listenSub;
+    constructor(dmk: DeviceManagementKit);
+    /**
+     * One-shot enumeration: subscribe to listenToAvailableDevices,
+     * take the first emission, unsubscribe, return DeviceDescriptors.
+     */
+    enumerate(): Promise<DeviceDescriptor[]>;
+    /**
+     * Continuous listening: tracks device connect/disconnect via diffing.
+     */
+    listen(onChange: (event: DeviceChangeEvent) => void): void;
+    stopListening(): void;
+    /**
+     * Resolve to the latest snapshot of advertising devices observed within
+     * `timeoutMs`. Rewrites `_discovered` so it tracks the live list.
+     *
+     * `listenToAvailableDevices` is a BehaviorSubject — it emits the cached
+     * list on subscribe and *only* re-emits when the list changes. A stable
+     * list of currently-advertising devices therefore produces only the
+     * subscription frame; treating that frame as "fossil to be discarded"
+     * caused devices to flicker in/out of the UI as searches alternated
+     * between "saw a change frame" and "saw only the cached frame".
+     *
+     * The window still gives a chance for the active scan to update the list
+     * (e.g. drop a peripheral that just stopped broadcasting), but if nothing
+     * changes we trust the snapshot — DMK silence on a stable list means
+     * "everything's still there".
+     */
+    getLiveDevices(timeoutMs?: number): Promise<DmkDiscoveredDevice[]>;
+    /**
+     * Trigger browser device selection (WebHID requestDevice).
+     * Starts discovery for a short period, then stops.
+     */
+    /**
+     * Start BLE discovery if not already running.
+     * Does NOT stop — DMK keeps scanning in the background so that
+     * listenToAvailableDevices() always has fresh data.
+     */
+    private _discoverySub;
+    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. */
+    disconnect(sessionId: string): Promise<void>;
+    getSessionId(deviceId: string): string | undefined;
+    getDeviceId(sessionId: string): string | undefined;
+    /** Get the underlying DMK instance (needed by SignerManager). */
+    getDmk(): DeviceManagementKit;
+    stopDiscovery(): void;
+    dispose(): void;
+    /**
+     * Tear down RxJS subscriptions and local state without closing the DMK.
+     * For light-reset paths that want to drop session state but keep the
+     * underlying transport alive for retry. Call this instead of orphaning
+     * the manager — bare null assignment leaks _listenSub / _discoverySub.
+     */
+    disposeKeepingDmk(): void;
 }
 
 /**
@@ -201,7 +299,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;
@@ -211,15 +316,8 @@ declare class LedgerConnectorBase implements IConnector {
     private readonly _providedDmk;
     private readonly _createTransport;
     readonly connectionType: ConnectionType;
-    private _connectIdToPath;
-    private _pathToConnectId;
-    /** Register a connectId <-> path mapping from a device descriptor. */
-    private _registerDeviceId;
-    /** 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;
     /**
      * Resolves a Ledger signer kit module by package name.
      * Override via constructor to use CJS paths for Metro (React Native).
@@ -228,6 +326,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;
@@ -237,17 +339,39 @@ 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;
+    /**
+     * Authoritative discovery for this transport. Default = enumerate snapshot
+     * (USB/HID). BLE overrides to drive from a live scan window since DMK's
+     * enumerate() cache survives peripherals going offline.
+     */
+    protected _discoverDescriptors(dm: LedgerDeviceManager): Promise<DeviceDescriptor[]>;
+    private _assertSingleUsbDescriptor;
     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`.
+     *
+     * Subscribe failure is fatal — see the inline note at the subscribe call.
+     */
+    private _watchSessionState;
+    private _unwatchSessionState;
+    private _handleAutonomousDisconnect;
     call(sessionId: string, method: string, params: unknown): Promise<unknown>;
+    private _dispatch;
     cancel(sessionId: string): Promise<void>;
     uiResponse(_response: UiResponseEvent): void;
     on<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
@@ -265,90 +389,53 @@ 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, BLE scan, 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
+     * disposeKeepingDmk(). Bare null-assignment would leak _listenSub /
+     * _discoverySub and double-scan after the next _initManagers().
      */
     private _resetSignersAndSessions;
     private _resetAll;
     protected _emit<K extends ConnectorEventType>(event: K, data: ConnectorEventMap[K]): void;
-    private _wrapError;
-}
-
-/**
- * Manages device discovery, connection, and session tracking.
- * Wraps DMK's Observable APIs into simpler imperative calls.
- */
-declare class LedgerDeviceManager {
-    private readonly _dmk;
-    private readonly _discovered;
-    private readonly _sessions;
-    private readonly _sessionToDevice;
-    private _listenSub;
-    constructor(dmk: DeviceManagementKit);
     /**
-     * One-shot enumeration: subscribe to listenToAvailableDevices,
-     * take the first emission, unsubscribe, return DeviceDescriptors.
+     * 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.
      */
-    enumerate(): Promise<DeviceDescriptor[]>;
-    /**
-     * Continuous listening: tracks device connect/disconnect via diffing.
-     */
-    listen(onChange: (event: DeviceChangeEvent) => void): void;
-    stopListening(): void;
-    /**
-     * Trigger browser device selection (WebHID requestDevice).
-     * Starts discovery for a short period, then stops.
-     */
-    /**
-     * Start BLE discovery if not already running.
-     * Does NOT stop — DMK keeps scanning in the background so that
-     * listenToAvailableDevices() always has fresh data.
-     */
-    private _discoverySub;
-    requestDevice(): Promise<void>;
-    /** Connect to a previously discovered device. Returns sessionId. */
-    connect(deviceId: string): Promise<string>;
-    /** Disconnect a session. */
-    disconnect(sessionId: string): Promise<void>;
-    getSessionId(deviceId: string): string | undefined;
-    getDeviceId(sessionId: string): string | undefined;
-    /** Get the underlying DMK instance (needed by SignerManager). */
-    getDmk(): DeviceManagementKit;
-    stopDiscovery(): void;
-    dispose(): void;
+    private _ctxForMethod;
+    private _wrapError;
 }
 
+/** Optional context attached to the rejection when a canceller fires. */
+interface CancelReason {
+    code?: number;
+    tag?: string;
+    message?: string;
+}
 /**
- * Re-export DMK types under local aliases for backward compatibility.
- * These replace the previous duck-typed interfaces with the real SDK types.
- */
-type DmkDiscoveredDevice = DiscoveredDevice;
-/**
- * DMK DeviceAction — the Observable-based return type of all DMK signer methods.
+ * Convert a DMK DeviceAction (Observable-based) into a Promise.
+ * Handles pending -> completed/error state transitions and interaction callbacks.
  *
- * This is a permissive alias for `ExecuteDeviceActionReturnType` that accepts
- * any Error and IntermediateValue generics. Signer wrapper code only cares about
- * the Output type and the observable/cancel shape.
- */
-type DeviceAction<T> = ExecuteDeviceActionReturnType<T, any, any>;
-/**
- * DMK DeviceActionState — re-exported with permissive Error/IntermediateValue.
- * The real type is a discriminated union on `status`.
+ * 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  Idle watchdog ms. Re-armed on each emission, paused
+ *                   during interactive pending. 0 disables. Default 65s
+ *                   (covers DMK's 60s + margin; we're a backstop only).
+ * @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.
  */
-type DeviceActionState<T> = DeviceActionState$1<T, any, any>;
-/** ETH address result — re-exported from DMK for backward compatibility. */
-type SignerEvmAddress = Address;
-/** ETH signature result — re-exported from DMK for backward compatibility. */
-type SignerEvmSignature = Signature;
-/** BTC address result (WalletAddress not exported from DMK top-level). */
-interface SignerBtcAddress {
-    address: string;
-}
+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
@@ -363,7 +450,7 @@ declare class SignerEth {
      * 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;
+    onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void;
     getAddress(derivationPath: string, options?: {
         checkOnDevice?: boolean;
     }): Promise<SignerEvmAddress>;
@@ -376,8 +463,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;
 }>;
 /**
@@ -393,6 +486,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];
@@ -406,7 +501,7 @@ type BtcMessageOptions = Parameters<SignerBtc$1['signMessage']>[2];
 declare class SignerBtc {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
-    onRegisterCanceller?: (cancel: () => void) => void;
+    onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void;
     constructor(_sdk: SignerBtc$1);
     getWalletAddress(wallet: BtcWallet, addressIndex: number, options?: {
         checkOnDevice?: boolean;
@@ -452,7 +547,7 @@ type SolMsgOptions = Parameters<SignerSolana['signMessage']>[2];
 declare class SignerSol {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
-    onRegisterCanceller?: (cancel: () => void) => void;
+    onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void;
     constructor(_sdk: SignerSolana);
     /**
      * Get the Solana address (base58-encoded Ed25519 public key) at the given derivation path.
@@ -493,24 +588,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.
- * @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: () => void) => void): Promise<T>;
-
 interface AppManagerOptions {
     waitMs?: number;
     maxRetries?: number;
@@ -540,9 +617,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;
@@ -557,48 +641,59 @@ 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;
+        _tag?: 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. */
+interface WrapErrorOptions {
+    /** Fallback when err has no `appName` (DMK signer errors don't carry it). */
+    defaultAppName?: string;
+}
+declare function ledgerFailure(code: HardwareErrorCode, error: string, appName?: string, tag?: string, params?: Record<string, unknown>): LedgerFailure;
 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;
 };
 
 /**
- * Centralised debug logger for the Ledger adapter.
- *
- * Off by default. Toggle programmatically via `setDebugEnabled(true)`.
+ * SDK-global event bus. Per-runtime singleton — each process subscribes
+ * independently; cross-process hosts forward events over their own IPC.
  */
-/** Enable or disable debug logging at runtime. */
-declare function setDebugEnabled(value: boolean): void;
-/** Returns the current debug-enabled state. */
-declare function isDebugEnabled(): boolean;
+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;
+
+declare function debugLog(...args: unknown[]): 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.
+ * Ledger DMK transport identifiers that represent BLE devices.
+ *
+ * Known today:
+ * - "BLE": generic/web BLE descriptors
+ * - "RN_BLE": @ledgerhq/device-transport-kit-react-native-ble
+ *
+ * Keep the suffix check here so future DMK BLE transports (for example
+ * "FOO_BLE") are handled in one place instead of scattering string checks.
  */
-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;
 
-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 };
+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 };