@onekeyfe/hwk-ledger-adapter 1.1.26-alpha.10

package/dist/index.d.ts

@@ -0,0 +1,628 @@
+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 { Address, Signature, SignerEth as SignerEth$1, TypedData } from '@ledgerhq/device-signer-kit-ethereum';
+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 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>;
+    init(_config?: unknown): Promise<void>;
+    /**
+     * Clear cached device/session state without tearing down the adapter.
+     * Call before retrying after errors or when the device state may be stale.
+     * The next operation will re-discover and re-connect automatically.
+     */
+    resetState(): void;
+    dispose(): Promise<void>;
+    uiResponse(response: UiResponseEvent): void;
+    searchDevices(): Promise<DeviceInfo[]>;
+    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>>;
+    btcSignMessage(connectId: string, deviceId: string, params: BtcSignMsgParams): Promise<Response<BtcSignature>>;
+    btcGetMasterFingerprint(connectId: string, deviceId: string): Promise<Response<{
+        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;
+    getChainFingerprint(connectId: string, deviceId: string, chain: ChainForFingerprint): Promise<Response<string>>;
+    /**
+     * Verify fingerprint using an existing sessionId directly.
+     * Safe to call inside connectorCall without causing queue deadlock.
+     */
+    private _verifyDeviceFingerprintWithSession;
+    /**
+     * Compute the chain fingerprint via a caller-supplied call strategy.
+     *
+     * Chains with a native device-side identity primitive (BTC → BIP32 master
+     * fingerprint) short-circuit at the top and return it verbatim, so the value
+     * stays reusable for higher-level use (BIP380 descriptors, PSBT signing).
+     *
+     * All other chains derive a fixed-path address and run it through
+     * `deriveDeviceFingerprint` to produce an opaque seed identifier.
+     *
+     * The two callers (`getChainFingerprint` / `_verifyDeviceFingerprintWithSession`)
+     * differ only in the underlying call mechanism, which is injected as `callMethod`
+     * to avoid queue deadlocks when running inside `connectorCall`.
+     */
+    private _computeChainFingerprint;
+    /**
+     * Ensure at least one device is connected and return a valid connectId.
+     *
+     * - 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.
+     */
+    private static readonly MAX_DEVICE_RETRY;
+    private _connectingPromise;
+    private _waitForDeviceConnect;
+    private ensureConnected;
+    private _doConnect;
+    private _connectFirstOrSelect;
+    private _chooseDeviceFromList;
+    /**
+     * Call the connector with automatic session resolution and disconnect retry.
+     *
+     * 1. Resolves a valid connectId via ensureConnected()
+     * 2. Looks up sessionId from _sessions
+     * 3. Calls connector.call()
+     * 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;
+    /**
+     * 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;
+    /**
+     * Convert a thrown error to a Response failure.
+     * Uses mapLedgerError to parse Ledger DMK error codes into HardwareErrorCode values.
+     */
+    private errorToFailure;
+    private deviceConnectHandler;
+    private deviceDisconnectHandler;
+    private uiEventForwarder;
+    private registerEventListeners;
+    private unregisterEventListeners;
+    private connectorDeviceToDeviceInfo;
+}
+
+/**
+ * A function that lazily loads and returns the transport factory
+ * for the Ledger DMK builder (e.g. webHidTransportFactory, rnBleTransportFactory).
+ */
+type TransportFactory = () => Promise<unknown>;
+interface LedgerConnectorBaseOptions {
+    /**
+     * Pre-built DMK instance. If not provided, a DMK will be created
+     * lazily on first use via the transport factory.
+     */
+    dmk?: DeviceManagementKit;
+}
+/**
+ * Shared base class for Ledger IConnector implementations.
+ *
+ * Encapsulates all shared logic: device discovery, connection management,
+ * method dispatch (EVM / BTC / SOL / TRON), signer lifecycle, event emission,
+ * and error handling.
+ *
+ * Chain-specific method implementations live in `./chains/` and receive
+ * a ConnectorContext that exposes shared helpers.
+ *
+ * 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).
+ */
+declare class LedgerConnectorBase implements IConnector {
+    private _deviceManager;
+    private _signerManager;
+    private _dmk;
+    private readonly _eventHandlers;
+    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;
+    /**
+     * Resolves a Ledger signer kit module by package name.
+     * Override via constructor to use CJS paths for Metro (React Native).
+     * Default: dynamic import with bare specifier (webpack/rspack).
+     */
+    protected _importLedgerKit: (pkg: string) => Promise<any>;
+    /** Context object passed to per-chain handler functions. */
+    private readonly _ctx;
+    constructor(createTransport: TransportFactory, options?: {
+        connectionType?: ConnectionType;
+        dmk?: DeviceManagementKit;
+        /**
+         * Override how `@ledgerhq/device-signer-kit-*` packages are imported.
+         * Default: `(pkg) => import(pkg)` — works with webpack/rspack.
+         * For Metro (React Native): pass a resolver that uses CJS paths.
+         */
+        importLedgerKit?: (pkg: string) => Promise<any>;
+    });
+    /**
+     * 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).
+     */
+    protected _resolveConnectId(descriptor: DeviceDescriptor): string;
+    searchDevices(): Promise<ConnectorDevice[]>;
+    connect(deviceId?: string): Promise<ConnectorSession>;
+    disconnect(sessionId: string): Promise<void>;
+    call(sessionId: string, method: string, params: unknown): Promise<unknown>;
+    cancel(sessionId: string): Promise<void>;
+    uiResponse(_response: UiResponseEvent): void;
+    on<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
+    off<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
+    reset(): void;
+    /**
+     * Lazily create or return the DMK instance.
+     * If a DMK was provided via constructor, it is used directly.
+     * Otherwise, one is created via the transport factory.
+     */
+    protected _getOrCreateDmk(): Promise<DeviceManagementKit>;
+    private _initManagers;
+    private _getDeviceManager;
+    private _getSignerManager;
+    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.
+     */
+    private _replaceSession;
+    /**
+     * Light reset: clear signer/session state but keep DMK, BLE scan, and ID mapping alive.
+     * Used by connect() retry — we want to re-discover with the same transport.
+     */
+    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;
+}
+
+/**
+ * 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;
+    /**
+     * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Wraps Ledger's SDK signer (Observable-based DeviceActions) into
+ * a simple async interface returning plain serializable data.
+ */
+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>;
+    signTransaction(derivationPath: string, serializedTxHex: string): Promise<SignerEvmSignature>;
+    signMessage(derivationPath: string, message: string): Promise<SignerEvmSignature>;
+    signTypedData(derivationPath: string, data: TypedData): Promise<SignerEvmSignature>;
+}
+
+type SignerEthBuilderFn = (args: {
+    dmk: DeviceManagementKit;
+    sessionId: string;
+}) => {
+    build(): SignerEth$1;
+} | Promise<{
+    build(): SignerEth$1;
+}>;
+/**
+ * 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 _dmk;
+    private readonly _builderFn;
+    constructor(dmk: DeviceManagementKit, builderFn?: SignerEthBuilderFn);
+    getOrCreate(sessionId: string): Promise<SignerEth>;
+    invalidate(_sessionId: string): void;
+    clearAll(): void;
+    private static _defaultBuilder;
+}
+
+type BtcWallet = Parameters<SignerBtc$1['getWalletAddress']>[0];
+type BtcPsbt = Parameters<SignerBtc$1['signPsbt']>[1];
+type BtcPsbtOptions = Parameters<SignerBtc$1['signPsbt']>[2];
+type BtcMessageOptions = Parameters<SignerBtc$1['signMessage']>[2];
+/**
+ * Wraps Ledger's BTC SDK signer (Observable-based DeviceActions) into
+ * a simple async interface returning plain serializable data.
+ */
+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;
+        change?: boolean;
+    }): Promise<SignerBtcAddress>;
+    getExtendedPublicKey(derivationPath: string, options?: {
+        checkOnDevice?: boolean;
+    }): Promise<string>;
+    getMasterFingerprint(options?: {
+        skipOpenApp?: boolean;
+    }): Promise<Uint8Array>;
+    /**
+     * Sign a PSBT and return the array of partial signatures.
+     * The `wallet` param is a DefaultWallet or WalletPolicy instance.
+     * The `psbt` param can be a hex string, base64 string, or Uint8Array.
+     */
+    signPsbt(wallet: BtcWallet, psbt: BtcPsbt, options?: BtcPsbtOptions): Promise<unknown[]>;
+    /**
+     * Sign a PSBT and return the fully extracted raw transaction as a hex string.
+     * Like signPsbt, but also finalises the PSBT and extracts the transaction.
+     */
+    signTransaction(wallet: BtcWallet, psbt: BtcPsbt, options?: BtcPsbtOptions): Promise<string>;
+    /**
+     * Sign a message with the BTC app (BIP-137 / "Bitcoin Signed Message").
+     * Returns `{ r, s, v }` signature object.
+     */
+    signMessage(derivationPath: string, message: string, options?: BtcMessageOptions): Promise<{
+        r: string;
+        s: string;
+        v: number;
+    }>;
+}
+
+type SolTxOptions = Parameters<SignerSolana['signTransaction']>[2];
+type SolMsgOptions = Parameters<SignerSolana['signMessage']>[2];
+/**
+ * Wraps Ledger's Solana SDK signer (Observable-based DeviceActions) into
+ * a simple async interface returning plain serializable data.
+ *
+ * The Solana signer's `getAddress` returns a base58-encoded Ed25519 public key,
+ * which is also the Solana address.
+ */
+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.
+     */
+    getAddress(derivationPath: string, options?: {
+        checkOnDevice?: boolean;
+    }): Promise<string>;
+    /**
+     * Sign a Solana transaction.
+     */
+    signTransaction(derivationPath: string, transaction: Uint8Array, options?: SolTxOptions): Promise<Uint8Array>;
+    /**
+     * Sign a message with the Solana app.
+     * DMK returns { signature: string } for signMessage (unlike signTransaction which returns Uint8Array).
+     */
+    signMessage(derivationPath: string, message: string | Uint8Array, options?: SolMsgOptions): Promise<{
+        signature: string;
+    }>;
+}
+
+/**
+ * Transport adapter that bridges Ledger's legacy hw-app-* SDKs to DMK's sendApdu.
+ *
+ * Legacy SDKs (hw-app-trx, hw-app-xrp, etc.) require a Transport instance.
+ * This adapter wraps DMK's session-based sendApdu so legacy SDKs can run
+ * over DMK's transport layer without a separate USB/HID connection.
+ *
+ * Usage:
+ *   const transport = new DmkTransport(dmk, sessionId);
+ *   const trx = new Trx(transport);
+ *   const address = await trx.getAddress("44'/195'/0'/0/0");
+ */
+declare class DmkTransport extends Transport {
+    private _dmk;
+    private _sessionId;
+    constructor(dmk: DeviceManagementKit, sessionId: string);
+    exchange(apdu: Buffer): Promise<Buffer>;
+    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;
+}
+/**
+ * Orchestrates opening / closing Ledger on-device apps so that the
+ * correct signer application is running before any signing call.
+ */
+declare class AppManager {
+    private readonly _dmk;
+    private readonly _waitMs;
+    private readonly _maxRetries;
+    constructor(dmk: DeviceManagementKit, options?: AppManagerOptions);
+    /**
+     * Return the Ledger app name for a given chain ticker,
+     * or undefined if the chain is not supported.
+     */
+    static getAppName(chain: string): string | undefined;
+    /**
+     * Ensure the target app is open on the device identified by `sessionId`.
+     *
+     * Flow:
+     * 1. Check the currently running app.
+     * 2. If it is already the target, return immediately.
+     * 3. If a different app is running (not dashboard), close it first.
+     * 4. Open the target app.
+     * 5. Poll until the device confirms the target app is running.
+     */
+    /**
+     * @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;
+    private _openApp;
+    private _closeCurrentApp;
+    /**
+     * Poll the device until the expected app is reported as running,
+     * or throw after `_maxRetries` attempts.
+     */
+    private _waitForApp;
+    private _isDashboard;
+    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.
+ * `opts.defaultAppName` fills `appName` when the raw error doesn't carry it
+ * (DMK signer errors don't).
+ */
+declare function mapLedgerError(err: unknown, opts?: WrapErrorOptions): {
+    code: HardwareErrorCode;
+    message: string;
+    appName?: string;
+};
+
+/**
+ * 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 };