@onekeyfe/hwk-ledger-adapter 1.1.26-alpha.105 → 1.1.26-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- 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';
1
+ 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';
2
2
  import { DeviceManagementKit, DeviceActionState as DeviceActionState$1, DiscoveredDevice, ExecuteDeviceActionReturnType } from '@ledgerhq/device-management-kit';
3
3
  import { Address, Signature, SignerEth as SignerEth$1, TypedData } from '@ledgerhq/device-signer-kit-ethereum';
4
4
  import { SignerBtc as SignerBtc$1 } from '@ledgerhq/device-signer-kit-bitcoin';
@@ -32,7 +32,15 @@ declare class LedgerAdapter implements IHardwareWallet {
32
32
  private _discoveredDevices;
33
33
  private _sessions;
34
34
  private readonly _uiRegistry;
35
+ private readonly _jobQueue;
35
36
  constructor(connector: IConnector, options?: LedgerAdapterOptions);
37
+ /**
38
+ * Classify a method's interruptibility.
39
+ * - Signing / typed data / transaction → 'confirm' (user may decide via preemption UI)
40
+ * - Read-only queries (getAddress / getPublicKey / getMasterFingerprint) → 'safe'
41
+ * (auto-cancels any pending read for the same device)
42
+ */
43
+ private static _getInterruptibility;
36
44
  get activeTransport(): TransportType | null;
37
45
  getAvailableTransports(): TransportType[];
38
46
  switchTransport(_type: TransportType): Promise<void>;
@@ -91,16 +99,20 @@ declare class LedgerAdapter implements IHardwareWallet {
91
99
  */
92
100
  private _verifyDeviceFingerprintWithSession;
93
101
  /**
94
- * Derive an address at the fixed testnet path for fingerprint generation.
95
- * Uses connectorCall (goes through ensureConnected). For public API use.
96
- */
97
- private _deriveAddressForFingerprint;
98
- /**
99
- * Derive an address using an existing sessionId directly.
100
- * Does NOT go through connectorCall safe to call inside connectorCall
101
- * without causing queue deadlock.
102
+ * Compute the chain fingerprint via a caller-supplied call strategy.
103
+ *
104
+ * Chains with a native device-side identity primitive (BTC → BIP32 master
105
+ * fingerprint) short-circuit at the top and return it verbatim, so the value
106
+ * stays reusable for higher-level use (BIP380 descriptors, PSBT signing).
107
+ *
108
+ * All other chains derive a fixed-path address and run it through
109
+ * `deriveDeviceFingerprint` to produce an opaque seed identifier.
110
+ *
111
+ * The two callers (`getChainFingerprint` / `_verifyDeviceFingerprintWithSession`)
112
+ * differ only in the underlying call mechanism, which is injected as `callMethod`
113
+ * to avoid queue deadlocks when running inside `connectorCall`.
102
114
  */
103
- private _deriveAddressWithSession;
115
+ private _computeChainFingerprint;
104
116
  /**
105
117
  * Ensure at least one device is connected and return a valid connectId.
106
118
  *
@@ -124,6 +136,16 @@ declare class LedgerAdapter implements IHardwareWallet {
124
136
  * 4. On disconnect error: clears stale session, re-connects, retries once
125
137
  */
126
138
  private connectorCall;
139
+ /**
140
+ * Race a promise against an abort signal. If the signal fires, rejects with the
141
+ * signal's reason (or a generic Error). The underlying connector.call() cannot
142
+ * actually be cancelled on Ledger DMK, but the caller gets the abort immediately.
143
+ */
144
+ private static _abortable;
145
+ /** Throw an AbortError if signal is already aborted. */
146
+ private static _throwIfAborted;
147
+ /** Actual work done under the job queue — connection, fingerprint, call, and recovery. */
148
+ private _runConnectorCall;
127
149
  /** Clear stale session, reconnect, and retry the call. */
128
150
  private _retryWithFreshConnection;
129
151
  /**
@@ -184,7 +206,7 @@ declare class LedgerConnectorBase implements IConnector {
184
206
  private readonly _eventHandlers;
185
207
  private readonly _providedDmk;
186
208
  private readonly _createTransport;
187
- private readonly _connectionType;
209
+ readonly connectionType: ConnectionType;
188
210
  private _connectIdToPath;
189
211
  private _pathToConnectId;
190
212
  /** Register a connectId <-> path mapping from a device descriptor. */
@@ -193,6 +215,7 @@ declare class LedgerConnectorBase implements IConnector {
193
215
  private _getPathForConnectId;
194
216
  /** Get external connectId from DMK path. Falls back to path itself. */
195
217
  private _getConnectIdForPath;
218
+ private readonly _cancellers;
196
219
  /**
197
220
  * Resolves a Ledger signer kit module by package name.
198
221
  * Override via constructor to use CJS paths for Metro (React Native).
@@ -221,7 +244,7 @@ declare class LedgerConnectorBase implements IConnector {
221
244
  connect(deviceId?: string): Promise<ConnectorSession>;
222
245
  disconnect(sessionId: string): Promise<void>;
223
246
  call(sessionId: string, method: string, params: unknown): Promise<unknown>;
224
- cancel(_sessionId: string): Promise<void>;
247
+ cancel(sessionId: string): Promise<void>;
225
248
  uiResponse(_response: UiResponseEvent): void;
226
249
  on<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
227
250
  off<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
@@ -331,6 +354,12 @@ declare class SignerEth {
331
354
  private readonly _sdk;
332
355
  onInteraction?: (interaction: string) => void;
333
356
  constructor(_sdk: SignerEth$1);
357
+ /**
358
+ * Optional callback registered per-call so the caller can obtain a canceller
359
+ * for the underlying DeviceAction. Caller can invoke it to release DMK's
360
+ * IntentQueue slot and unsubscribe from the action's observable.
361
+ */
362
+ onRegisterCanceller?: (cancel: () => void) => void;
334
363
  getAddress(derivationPath: string, options?: {
335
364
  checkOnDevice?: boolean;
336
365
  }): Promise<SignerEvmAddress>;
@@ -348,16 +377,16 @@ type SignerEthBuilderFn = (args: {
348
377
  build(): SignerEth$1;
349
378
  }>;
350
379
  /**
351
- * Manages per-sessionId SignerEth instances.
352
- * Creates on demand, caches for reuse, invalidates on session change.
380
+ * Per-sessionId SignerEth factory. Builds fresh on every call — DMK signers
381
+ * hold DeviceAction state that isn't safe to reuse, so `invalidate` /
382
+ * `clearAll` are kept as no-op lifecycle hooks for callers.
353
383
  */
354
384
  declare class SignerManager {
355
- private readonly _cache;
356
385
  private readonly _dmk;
357
386
  private readonly _builderFn;
358
387
  constructor(dmk: DeviceManagementKit, builderFn?: SignerEthBuilderFn);
359
388
  getOrCreate(sessionId: string): Promise<SignerEth>;
360
- invalidate(sessionId: string): void;
389
+ invalidate(_sessionId: string): void;
361
390
  clearAll(): void;
362
391
  private static _defaultBuilder;
363
392
  }
@@ -373,6 +402,7 @@ type BtcMessageOptions = Parameters<SignerBtc$1['signMessage']>[2];
373
402
  declare class SignerBtc {
374
403
  private readonly _sdk;
375
404
  onInteraction?: (interaction: string) => void;
405
+ onRegisterCanceller?: (cancel: () => void) => void;
376
406
  constructor(_sdk: SignerBtc$1);
377
407
  getWalletAddress(wallet: BtcWallet, addressIndex: number, options?: {
378
408
  checkOnDevice?: boolean;
@@ -418,6 +448,7 @@ type SolMsgOptions = Parameters<SignerSolana['signMessage']>[2];
418
448
  declare class SignerSol {
419
449
  private readonly _sdk;
420
450
  onInteraction?: (interaction: string) => void;
451
+ onRegisterCanceller?: (cancel: () => void) => void;
421
452
  constructor(_sdk: SignerSolana);
422
453
  /**
423
454
  * Get the Solana address (base58-encoded Ed25519 public key) at the given derivation path.
@@ -469,8 +500,12 @@ declare class DmkTransport extends Transport {
469
500
  *
470
501
  * @param timeoutMs Timeout in ms. Resets each time the Observable emits (device is alive).
471
502
  * Pass 0 to disable. Default: 30s.
503
+ * @param onRegisterCanceller Optional callback that receives a function which, when
504
+ * called, unsubscribes and cancels the underlying DeviceAction
505
+ * (releases DMK's IntentQueue slot). Caller is responsible
506
+ * for invoking the canceller on timeout/abort scenarios.
472
507
  */
473
- declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number): Promise<T>;
508
+ declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: () => void) => void): Promise<T>;
474
509
 
475
510
  interface AppManagerOptions {
476
511
  waitMs?: number;
@@ -518,6 +553,21 @@ declare class AppManager {
518
553
  private _wait;
519
554
  }
520
555
 
556
+ /**
557
+ * Ledger-specific Failure: adds `appName` for "the currently-open app" — a
558
+ * Ledger hardware concept not shared with other vendors, so it lives here
559
+ * rather than in core's generic Failure.
560
+ */
561
+ type LedgerFailure = Omit<Failure, 'payload'> & {
562
+ payload: Failure['payload'] & {
563
+ appName?: string;
564
+ };
565
+ };
566
+ /**
567
+ * Structurally compatible with `Failure`; writes `appName` only when provided,
568
+ * so `'appName' in payload` is a reliable "has info" signal for consumers.
569
+ */
570
+ declare function ledgerFailure(code: HardwareErrorCode, error: string, appName?: string): LedgerFailure;
521
571
  /** Check if an error (or any error in its chain) represents a locked Ledger device. */
522
572
  declare function isDeviceLockedError(err: unknown): boolean;
523
573
  /**
@@ -530,4 +580,14 @@ declare function mapLedgerError(err: unknown): {
530
580
  appName?: string;
531
581
  };
532
582
 
533
- 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 };
583
+ /**
584
+ * Centralised debug logger for the Ledger adapter.
585
+ *
586
+ * Off by default. Toggle programmatically via `setDebugEnabled(true)`.
587
+ */
588
+ /** Enable or disable debug logging at runtime. */
589
+ declare function setDebugEnabled(value: boolean): void;
590
+ /** Returns the current debug-enabled state. */
591
+ declare function isDebugEnabled(): boolean;
592
+
593
+ 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, isDebugEnabled, isDeviceLockedError, ledgerFailure, mapLedgerError, setDebugEnabled };
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- 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';
1
+ 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';
2
2
  import { DeviceManagementKit, DeviceActionState as DeviceActionState$1, DiscoveredDevice, ExecuteDeviceActionReturnType } from '@ledgerhq/device-management-kit';
3
3
  import { Address, Signature, SignerEth as SignerEth$1, TypedData } from '@ledgerhq/device-signer-kit-ethereum';
4
4
  import { SignerBtc as SignerBtc$1 } from '@ledgerhq/device-signer-kit-bitcoin';
@@ -32,7 +32,15 @@ declare class LedgerAdapter implements IHardwareWallet {
32
32
  private _discoveredDevices;
33
33
  private _sessions;
34
34
  private readonly _uiRegistry;
35
+ private readonly _jobQueue;
35
36
  constructor(connector: IConnector, options?: LedgerAdapterOptions);
37
+ /**
38
+ * Classify a method's interruptibility.
39
+ * - Signing / typed data / transaction → 'confirm' (user may decide via preemption UI)
40
+ * - Read-only queries (getAddress / getPublicKey / getMasterFingerprint) → 'safe'
41
+ * (auto-cancels any pending read for the same device)
42
+ */
43
+ private static _getInterruptibility;
36
44
  get activeTransport(): TransportType | null;
37
45
  getAvailableTransports(): TransportType[];
38
46
  switchTransport(_type: TransportType): Promise<void>;
@@ -91,16 +99,20 @@ declare class LedgerAdapter implements IHardwareWallet {
91
99
  */
92
100
  private _verifyDeviceFingerprintWithSession;
93
101
  /**
94
- * Derive an address at the fixed testnet path for fingerprint generation.
95
- * Uses connectorCall (goes through ensureConnected). For public API use.
96
- */
97
- private _deriveAddressForFingerprint;
98
- /**
99
- * Derive an address using an existing sessionId directly.
100
- * Does NOT go through connectorCall safe to call inside connectorCall
101
- * without causing queue deadlock.
102
+ * Compute the chain fingerprint via a caller-supplied call strategy.
103
+ *
104
+ * Chains with a native device-side identity primitive (BTC → BIP32 master
105
+ * fingerprint) short-circuit at the top and return it verbatim, so the value
106
+ * stays reusable for higher-level use (BIP380 descriptors, PSBT signing).
107
+ *
108
+ * All other chains derive a fixed-path address and run it through
109
+ * `deriveDeviceFingerprint` to produce an opaque seed identifier.
110
+ *
111
+ * The two callers (`getChainFingerprint` / `_verifyDeviceFingerprintWithSession`)
112
+ * differ only in the underlying call mechanism, which is injected as `callMethod`
113
+ * to avoid queue deadlocks when running inside `connectorCall`.
102
114
  */
103
- private _deriveAddressWithSession;
115
+ private _computeChainFingerprint;
104
116
  /**
105
117
  * Ensure at least one device is connected and return a valid connectId.
106
118
  *
@@ -124,6 +136,16 @@ declare class LedgerAdapter implements IHardwareWallet {
124
136
  * 4. On disconnect error: clears stale session, re-connects, retries once
125
137
  */
126
138
  private connectorCall;
139
+ /**
140
+ * Race a promise against an abort signal. If the signal fires, rejects with the
141
+ * signal's reason (or a generic Error). The underlying connector.call() cannot
142
+ * actually be cancelled on Ledger DMK, but the caller gets the abort immediately.
143
+ */
144
+ private static _abortable;
145
+ /** Throw an AbortError if signal is already aborted. */
146
+ private static _throwIfAborted;
147
+ /** Actual work done under the job queue — connection, fingerprint, call, and recovery. */
148
+ private _runConnectorCall;
127
149
  /** Clear stale session, reconnect, and retry the call. */
128
150
  private _retryWithFreshConnection;
129
151
  /**
@@ -184,7 +206,7 @@ declare class LedgerConnectorBase implements IConnector {
184
206
  private readonly _eventHandlers;
185
207
  private readonly _providedDmk;
186
208
  private readonly _createTransport;
187
- private readonly _connectionType;
209
+ readonly connectionType: ConnectionType;
188
210
  private _connectIdToPath;
189
211
  private _pathToConnectId;
190
212
  /** Register a connectId <-> path mapping from a device descriptor. */
@@ -193,6 +215,7 @@ declare class LedgerConnectorBase implements IConnector {
193
215
  private _getPathForConnectId;
194
216
  /** Get external connectId from DMK path. Falls back to path itself. */
195
217
  private _getConnectIdForPath;
218
+ private readonly _cancellers;
196
219
  /**
197
220
  * Resolves a Ledger signer kit module by package name.
198
221
  * Override via constructor to use CJS paths for Metro (React Native).
@@ -221,7 +244,7 @@ declare class LedgerConnectorBase implements IConnector {
221
244
  connect(deviceId?: string): Promise<ConnectorSession>;
222
245
  disconnect(sessionId: string): Promise<void>;
223
246
  call(sessionId: string, method: string, params: unknown): Promise<unknown>;
224
- cancel(_sessionId: string): Promise<void>;
247
+ cancel(sessionId: string): Promise<void>;
225
248
  uiResponse(_response: UiResponseEvent): void;
226
249
  on<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
227
250
  off<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
@@ -331,6 +354,12 @@ declare class SignerEth {
331
354
  private readonly _sdk;
332
355
  onInteraction?: (interaction: string) => void;
333
356
  constructor(_sdk: SignerEth$1);
357
+ /**
358
+ * Optional callback registered per-call so the caller can obtain a canceller
359
+ * for the underlying DeviceAction. Caller can invoke it to release DMK's
360
+ * IntentQueue slot and unsubscribe from the action's observable.
361
+ */
362
+ onRegisterCanceller?: (cancel: () => void) => void;
334
363
  getAddress(derivationPath: string, options?: {
335
364
  checkOnDevice?: boolean;
336
365
  }): Promise<SignerEvmAddress>;
@@ -348,16 +377,16 @@ type SignerEthBuilderFn = (args: {
348
377
  build(): SignerEth$1;
349
378
  }>;
350
379
  /**
351
- * Manages per-sessionId SignerEth instances.
352
- * Creates on demand, caches for reuse, invalidates on session change.
380
+ * Per-sessionId SignerEth factory. Builds fresh on every call — DMK signers
381
+ * hold DeviceAction state that isn't safe to reuse, so `invalidate` /
382
+ * `clearAll` are kept as no-op lifecycle hooks for callers.
353
383
  */
354
384
  declare class SignerManager {
355
- private readonly _cache;
356
385
  private readonly _dmk;
357
386
  private readonly _builderFn;
358
387
  constructor(dmk: DeviceManagementKit, builderFn?: SignerEthBuilderFn);
359
388
  getOrCreate(sessionId: string): Promise<SignerEth>;
360
- invalidate(sessionId: string): void;
389
+ invalidate(_sessionId: string): void;
361
390
  clearAll(): void;
362
391
  private static _defaultBuilder;
363
392
  }
@@ -373,6 +402,7 @@ type BtcMessageOptions = Parameters<SignerBtc$1['signMessage']>[2];
373
402
  declare class SignerBtc {
374
403
  private readonly _sdk;
375
404
  onInteraction?: (interaction: string) => void;
405
+ onRegisterCanceller?: (cancel: () => void) => void;
376
406
  constructor(_sdk: SignerBtc$1);
377
407
  getWalletAddress(wallet: BtcWallet, addressIndex: number, options?: {
378
408
  checkOnDevice?: boolean;
@@ -418,6 +448,7 @@ type SolMsgOptions = Parameters<SignerSolana['signMessage']>[2];
418
448
  declare class SignerSol {
419
449
  private readonly _sdk;
420
450
  onInteraction?: (interaction: string) => void;
451
+ onRegisterCanceller?: (cancel: () => void) => void;
421
452
  constructor(_sdk: SignerSolana);
422
453
  /**
423
454
  * Get the Solana address (base58-encoded Ed25519 public key) at the given derivation path.
@@ -469,8 +500,12 @@ declare class DmkTransport extends Transport {
469
500
  *
470
501
  * @param timeoutMs Timeout in ms. Resets each time the Observable emits (device is alive).
471
502
  * Pass 0 to disable. Default: 30s.
503
+ * @param onRegisterCanceller Optional callback that receives a function which, when
504
+ * called, unsubscribes and cancels the underlying DeviceAction
505
+ * (releases DMK's IntentQueue slot). Caller is responsible
506
+ * for invoking the canceller on timeout/abort scenarios.
472
507
  */
473
- declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number): Promise<T>;
508
+ declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: () => void) => void): Promise<T>;
474
509
 
475
510
  interface AppManagerOptions {
476
511
  waitMs?: number;
@@ -518,6 +553,21 @@ declare class AppManager {
518
553
  private _wait;
519
554
  }
520
555
 
556
+ /**
557
+ * Ledger-specific Failure: adds `appName` for "the currently-open app" — a
558
+ * Ledger hardware concept not shared with other vendors, so it lives here
559
+ * rather than in core's generic Failure.
560
+ */
561
+ type LedgerFailure = Omit<Failure, 'payload'> & {
562
+ payload: Failure['payload'] & {
563
+ appName?: string;
564
+ };
565
+ };
566
+ /**
567
+ * Structurally compatible with `Failure`; writes `appName` only when provided,
568
+ * so `'appName' in payload` is a reliable "has info" signal for consumers.
569
+ */
570
+ declare function ledgerFailure(code: HardwareErrorCode, error: string, appName?: string): LedgerFailure;
521
571
  /** Check if an error (or any error in its chain) represents a locked Ledger device. */
522
572
  declare function isDeviceLockedError(err: unknown): boolean;
523
573
  /**
@@ -530,4 +580,14 @@ declare function mapLedgerError(err: unknown): {
530
580
  appName?: string;
531
581
  };
532
582
 
533
- 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 };
583
+ /**
584
+ * Centralised debug logger for the Ledger adapter.
585
+ *
586
+ * Off by default. Toggle programmatically via `setDebugEnabled(true)`.
587
+ */
588
+ /** Enable or disable debug logging at runtime. */
589
+ declare function setDebugEnabled(value: boolean): void;
590
+ /** Returns the current debug-enabled state. */
591
+ declare function isDebugEnabled(): boolean;
592
+
593
+ 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, isDebugEnabled, isDeviceLockedError, ledgerFailure, mapLedgerError, setDebugEnabled };