@onekeyfe/hwk-adapter-core 1.2.8-alpha.51 → 1.2.8-alpha.52

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { HardwareErrorCode } from './errors.js';
-export { HwkError, IHwkErrorPayload, ORPHAN_ELIGIBLE_ERROR_CODES, createHwkError, enrichErrorMessage } from './errors.js';
-import { U as UiResponseEvent, a as UI_REQUEST, Q as QrDisplayData } from './ui-events-Cb7haAeE.js';
-export { D as DevicePermissionDeniedReason, b as DevicePermissionResponse, c as QrResponseData, d as UI_EVENT, e as UI_REQUEST_CANCELLED_TAG, f as UI_REQUEST_DEFAULT_TIMEOUT_MS, g as UI_REQUEST_PREEMPTED_TAG, h as UI_REQUEST_TIMEOUT_TAG, i as UI_RESPONSE, j as UiRequestRegistry } from './ui-events-Cb7haAeE.js';
+import { H as HardwareErrorCode, a as HwkErrorOrigin, b as HwkRecoveryHint } from './errors-BgJ4kzRx.js';
+export { c as HwkError, d as HwkRecoveryScope, I as IHwkErrorPayload, e as IOperationMayHaveCompletedParams, O as ORPHAN_ELIGIBLE_ERROR_CODES, f as createHwkError, g as defaultOriginForCode, h as defaultRecoveryForCode, i as enrichErrorMessage, j as isHwkRecoveryHint, o as operationMayHaveCompletedParams } from './errors-BgJ4kzRx.js';
+import { U as UiResponseEvent, E as ExportedAccountKey, a as UiRequestOperationAttribution, b as UI_REQUEST, Q as QrDisplayData, c as UiRequestRegistry, S as SaveDeviceBindingDeclineReason } from './ui-events-C61GTilK.js';
+export { D as DevicePermissionDeniedReason, d as DevicePermissionResponse, e as QrResponseData, f as UI_EVENT, g as UI_REQUEST_CANCELLED_TAG, h as UI_REQUEST_DEFAULT_TIMEOUT_MS, i as UI_REQUEST_PREEMPTED_TAG, j as UI_REQUEST_TIMEOUT_TAG, k as UI_RESPONSE } from './ui-events-C61GTilK.js';
 
 interface Success<T> {
     success: true;
@@ -12,16 +12,51 @@ interface Failure {
     payload: {
         error: string;
         code: HardwareErrorCode;
+        /** See HwkErrorOrigin, who the failure came from. Optional so an
+         *  unclassified failure degrades to code-based handling, never a guess. */
+        origin?: HwkErrorOrigin;
+        /** Connection-lifecycle recovery semantics. Optional for wire compatibility
+         *  with SDK versions that predate this field. SDK failure helpers populate it. */
+        recovery?: HwkRecoveryHint;
         params?: Record<string, unknown>;
     };
 }
 type Response<T> = Success<T> | Failure;
 declare function success<T>(payload: T): Success<T>;
-declare function failure(code: HardwareErrorCode, error: string, params?: Record<string, unknown>): Failure;
+declare function failure(code: HardwareErrorCode, error: string, params?: Record<string, unknown>, origin?: HwkErrorOrigin, recovery?: HwkRecoveryHint): Failure;
 
-type VendorType = 'trezor' | 'ledger';
-type ConnectionType = 'usb' | 'ble';
-type TransportType = 'usb' | 'ble' | 'hid' | 'bridge';
+/**
+ * Fixed derivation paths used to generate chain fingerprints.
+ * Uses standard index 0 — Ledger firmware shows device confirmation for
+ * non-standard paths (e.g., index=100), which would interrupt wallet creation.
+ * The address is hashed into a 16-char fingerprint, not exposed directly.
+ * - EVM: cointype 60 (Ledger ETH App only supports 60)
+ * - BTC: cointype 1 (testnet)
+ * - SOL: cointype 501, standard 3-level hardened
+ */
+declare const CHAIN_FINGERPRINT_PATHS: Record<ChainForFingerprint, string>;
+type ChainForFingerprint = 'evm' | 'btc' | 'sol' | 'tron' | 'zcash';
+/**
+ * Parses the complete BIP32 master fingerprint wire value: 4 bytes encoded
+ * as exactly 8 hexadecimal characters. This is protocol metadata, not a
+ * collision-resistant wallet identity.
+ */
+declare function parseBip32MasterFingerprint(value: unknown): string | undefined;
+/** Four zero bytes is how a missing master fingerprint is encoded; never a wallet identity. */
+declare const MISSING_BIP32_MASTER_FINGERPRINT = "00000000";
+/** A master fingerprint usable as a wallet identity: well-formed and not the missing marker. */
+declare function parseWalletMasterFingerprint(value: unknown): string | undefined;
+/**
+ * 16-char SHA-256 fingerprint for device-identity verification.
+ * Callers must canonicalize input (e.g. EVM address → lowercase) —
+ * encoding variations otherwise cause false DeviceMismatch.
+ */
+declare function deriveDeviceFingerprint(value: string): string;
+
+type VendorType = 'trezor' | 'ledger' | 'keystone';
+/** 'qr' is a virtual channel: UR payloads travel via app-rendered/scanned QR codes. */
+type ConnectionType = 'usb' | 'ble' | 'qr';
+type TransportType = 'usb' | 'ble' | 'hid' | 'bridge' | 'qr';
 /**
  * Device capabilities — describes what a specific device/connection
  * combination can or cannot do. Varies by vendor, model, and connection type.
@@ -31,12 +66,8 @@ type TransportType = 'usb' | 'ble' | 'hid' | 'bridge';
  */
 interface DeviceCapabilities {
     /**
-     * Whether connectId/deviceId persist across sessions.
-     *
-     * - `true`: IDs are stable (e.g., OneKey USB, Trezor USB).
-     *   Business logic can match devices by stored connectId/deviceId.
-     * - `false`: IDs are ephemeral, regenerated each session (e.g., Ledger WebHID).
-     *   Business logic should NOT rely on stored connectId/deviceId for matching.
+     * Whether the discovery handle can be reused to reconnect; `false` requires rediscovery. Says
+     * nothing about identity (Trezor BLE is false yet its device_id is stable); verify it separately.
      */
     persistentDeviceIdentity: boolean;
 }
@@ -73,6 +104,46 @@ interface DeviceTarget {
     connectId: string;
     deviceId: string;
 }
+/**
+ * How long a discovery handle remains safe to use for a new connection.
+ * This is deliberately separate from post-connect device identity.
+ */
+type SearchTargetReusePolicy = 'current-discovery' | 'reconnectable' | 'rediscover';
+declare function resolveSearchTargetReusePolicy(device: Pick<DeviceInfo, 'connectionType' | 'capabilities'>): SearchTargetReusePolicy;
+/** Search target for a physical device whose connectId is the discovery handle. */
+declare function toPhysicalDeviceSearchTarget(vendor: VendorType, device: DeviceInfo): DeviceSearchTarget;
+/**
+ * A selectable result from hardware discovery. It may represent a physical
+ * transport endpoint or an interactive entry such as Keystone QR; it is not a
+ * physical-device or wallet identity.
+ */
+interface DeviceSearchTarget {
+    /** Opaque handle scoped to the adapter's current discovery state. */
+    searchTargetId: string;
+    /** Whether the handle itself may be retried; never inferred from a stored connectId. */
+    searchTargetReusePolicy?: SearchTargetReusePolicy;
+    vendor: VendorType;
+    connectionType: ConnectionType;
+    kind: 'physical' | 'interactive';
+    label?: string;
+    model?: string;
+    modelName?: string;
+    serialNumber?: string;
+}
+type WalletIdentity = {
+    vendor: 'ledger';
+    type: 'chainFingerprint';
+    chain: ChainForFingerprint;
+    value: string;
+} | {
+    vendor: 'trezor';
+    type: 'deviceId';
+    value: string;
+} | {
+    vendor: 'keystone';
+    type: 'walletId';
+    value: string;
+};
 
 /**
  * Mixin for chain-operation params that can be pinned to a specific passphrase
@@ -133,6 +204,15 @@ interface ConnectorSession {
     sessionId: string;
     deviceInfo: DeviceInfo;
 }
+type ConnectorConnectTarget = {
+    type: 'default';
+} | {
+    type: 'search-target';
+    searchTargetId: string;
+} | {
+    type: 'expected-device-identity';
+    deviceIdentity: string;
+};
 /**
  * Vendor-agnostic bag of extra error fields. Known keys are documented for
  * discoverability; the index signature keeps it open so any connector can
@@ -245,6 +325,8 @@ interface ConnectorEventMap {
         connectId: string;
         deviceId?: string;
         credentials: Record<string, unknown>[];
+        /** Credentials the device rejected; a list kept for several devices drops these. */
+        removed?: Record<string, unknown>[];
     };
     'ui-request': {
         type: string;
@@ -253,12 +335,16 @@ interface ConnectorEventMap {
     'ui-event': ConnectorUiEvent;
 }
 interface ConnectorSearchDevicesOptions {
+    /** Select a child transport without waking/scanning the others. */
+    transportType?: ConnectionType;
     /**
      * Wait for every child transport in a fused connector. Default discovery can
      * return shortly after USB appears so BLE does not slow down USB flows;
      * binding pickers can opt in when they need BLE candidates too.
      */
     waitForAll?: boolean;
+    /** Availability probes must not invalidate user-selectable discovery targets. */
+    purpose?: 'selection' | 'availability';
 }
 interface ConnectorConfig {
     /**
@@ -273,8 +359,16 @@ interface ConnectorConfig {
 interface IConnector {
     /** Physical connection type this connector uses. Fixed at construction. */
     readonly connectionType: ConnectionType;
+    readonly availableTransports?: readonly ConnectionType[];
     searchDevices(options?: ConnectorSearchDevicesOptions): Promise<ConnectorDevice[]>;
-    connect(deviceId?: string): Promise<ConnectorSession>;
+    connect(deviceId?: string, options?: {
+        transportType: ConnectionType;
+    }): Promise<ConnectorSession>;
+    /**
+     * Structured form for connectors where a discovery handle and a stable device identity are
+     * different concepts. The string form remains for bridge and legacy compatibility.
+     */
+    connectTarget?(target: ConnectorConnectTarget): Promise<ConnectorSession>;
     disconnect(sessionId: string): Promise<void>;
     call(sessionId: string, method: string, params: unknown): Promise<ConnectorCallResult>;
     cancel(sessionId: string): Promise<void>;
@@ -299,6 +393,9 @@ interface IHardwareBridge {
     connect(params: {
         vendor: VendorType;
         deviceId?: string;
+        options?: {
+            transportType: ConnectionType;
+        };
     }): Promise<ConnectorSession>;
     disconnect(params: {
         vendor: VendorType;
@@ -400,6 +497,10 @@ interface BtcGetAddressParams extends PassphraseStateAware {
     path: string;
     coin?: string;
     showOnDevice?: boolean;
+    /**
+     * Trezor only. Ledger and Keystone ignore it and derive the script of the path's purpose
+     * (44' P2PKH, 49' P2SH-P2WPKH, 84' P2WPKH, 86' P2TR; Keystone does not support 86' yet).
+     */
     scriptType?: 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr';
     addressIndex?: number;
     change?: boolean;
@@ -407,6 +508,8 @@ interface BtcGetAddressParams extends PassphraseStateAware {
 interface BtcAddress {
     address: string;
     path: string;
+    /** Set by air-gapped wallets (Keystone): the exported key this address derives from. */
+    accountKey?: ExportedAccountKey;
 }
 interface BtcGetPublicKeyParams extends PassphraseStateAware {
     path: string;
@@ -421,6 +524,8 @@ interface BtcPublicKey {
     chainCode: string;
     path: string;
     depth: number;
+    /** Set by air-gapped wallets (Keystone): the exported key, for pinning by the host. */
+    accountKey?: ExportedAccountKey;
 }
 interface BtcSignTxParams extends PassphraseStateAware {
     psbt?: string;
@@ -561,6 +666,8 @@ interface SolAddress {
     /** Base58-encoded Solana address — this is also the Ed25519 public key. */
     address: string;
     path: string;
+    /** Set by air-gapped wallets (Keystone): the exported key this address derives from. */
+    accountKey?: ExportedAccountKey;
 }
 interface SolSignTxParams extends PassphraseStateAware {
     path: string;
@@ -581,11 +688,21 @@ interface SolSignedTx {
     /** Hex-encoded Ed25519 signature (no 0x prefix) */
     signature: string;
 }
-interface SolSignMsgParams extends PassphraseStateAware {
+interface SolSignMessageBaseParams extends PassphraseStateAware {
     path: string;
     /** Message bytes as hex string (no 0x prefix) */
     message: string;
 }
+interface SolOffchainMessageV1Params {
+    /** Finalized Solana off-chain message format. */
+    messageVersion: 1;
+    /** Complete signer set as 32-byte hex public keys. */
+    requiredSigners: string[];
+}
+type SolSignMsgParams = SolSignMessageBaseParams & ({
+    messageVersion?: undefined;
+    requiredSigners?: undefined;
+} | SolOffchainMessageV1Params);
 interface SolSignature {
     /** Hex-encoded Ed25519 signature (no 0x prefix) */
     signature: string;
@@ -604,6 +721,8 @@ interface TronAddress {
     /** Base58check-encoded TRON address (starts with 'T') */
     address: string;
     path: string;
+    /** Set by air-gapped wallets (Keystone): the exported key this address derives from. */
+    accountKey?: ExportedAccountKey;
 }
 /** TRON network resource, used by freeze/unfreeze contracts. */
 type TronResource = 'BANDWIDTH' | 'ENERGY';
@@ -712,6 +831,12 @@ interface TronSignMsgParams extends PassphraseStateAware {
     path: string;
     /** Message hex (no 0x prefix) */
     messageHex: string;
+    /**
+     * TRON message scheme: 'V1' = legacy signMessage (prefix + 32-byte hash),
+     * 'V2' = TIP-191 signMessageV2 (prefix + byte length + message). Adapters
+     * that only implement one scheme reject the other with MethodNotSupported.
+     */
+    messageType?: 'V1' | 'V2';
 }
 interface TronSignature {
     /** 65-byte hex-encoded signature (no 0x prefix) */
@@ -723,100 +848,167 @@ interface ITronMethods {
     tronSignMessage(connectId?: NullableCallArg<string>, deviceId?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<TronSignMsgParams>>): Promise<Response<TronSignature>>;
 }
 
-/**
- * Fixed derivation paths used to generate chain fingerprints.
- * Uses standard index 0 — Ledger firmware shows device confirmation for
- * non-standard paths (e.g., index=100), which would interrupt wallet creation.
- * The address is hashed into a 16-char fingerprint, not exposed directly.
- * - EVM: cointype 60 (Ledger ETH App only supports 60)
- * - BTC: cointype 1 (testnet)
- * - SOL: cointype 501, standard 3-level hardened
- */
-declare const CHAIN_FINGERPRINT_PATHS: Record<ChainForFingerprint, string>;
-type ChainForFingerprint = 'evm' | 'btc' | 'sol' | 'tron';
-/**
- * 16-char SHA-256 fingerprint for device-identity verification.
- * Callers must canonicalize input (e.g. EVM address → lowercase) —
- * encoding variations otherwise cause false DeviceMismatch.
- */
-declare function deriveDeviceFingerprint(value: string): string;
-
 /** Events generated by SDK internal detection (not from hardware directly). */
 declare const SDK: {
     readonly DEVICE_STUCK: "device-stuck";
     readonly DEVICE_UNRESPONSIVE: "device-unresponsive";
     readonly DEVICE_RECOVERED: "device-recovered";
     readonly DEVICE_INTERACTION: "device-interaction";
+    readonly OPERATION_ENDED: "operation-ended";
 };
 
+declare const OPERATION_DEFAULT_TTL_MS = 600000;
+type OperationEndReason = 'explicit' | 'disconnect' | 'timeout' | 'runtime-reset';
+type HardwareOperation = {
+    operationId: string;
+    connectId: string;
+    device: DeviceInfo;
+    /**
+     * The channel this operation runs on, set by the adapter that picked it. Never read it off
+     * `device`: a combined connector fills that snapshot with a nominal value.
+     */
+    connectionType: ConnectionType;
+    connectionKeys: string[];
+};
+type OperationRegistryOptions = {
+    vendor: VendorType;
+    ttlMs?: number;
+    onEnded?: (operation: HardwareOperation, reason: OperationEndReason) => void;
+};
+/** Runtime-only association between a public operation id and one live target. */
+declare class OperationRegistry {
+    private readonly _vendor;
+    private readonly _ttlMs;
+    private readonly _onEnded?;
+    private readonly _active;
+    private readonly _ended;
+    constructor(options: OperationRegistryOptions);
+    create(params: {
+        searchTargetId: string;
+        connectId: string;
+        device: DeviceInfo;
+        connectionType: ConnectionType;
+        connectionKeys?: string[];
+    }): HardwareOperation;
+    resolve(operationId: string): HardwareOperation;
+    /** Keep an operation alive while one device job is actively using it. */
+    retain(operationId: string): () => void;
+    /** Return a live operation without refreshing its TTL; ended and unknown ids give undefined. */
+    findActive(operationId: string): HardwareOperation | undefined;
+    /** Return active or tombstoned binding data without refreshing its TTL. */
+    find(operationId: string): HardwareOperation | undefined;
+    findActiveByConnectionKey(connectionKey: string): HardwareOperation | undefined;
+    /** Map a job queue key (an operation id or a connection key) to its live operation id. */
+    findOperationIdByJobKey(jobKey: string | undefined): string | undefined;
+    /**
+     * End an operation on the caller's explicit release. Throws for an unknown id; returns undefined
+     * when it had already ended.
+     */
+    release(operationId: string): HardwareOperation | undefined;
+    end(operationId: string, reason: OperationEndReason): HardwareOperation | undefined;
+    endByConnectionKey(connectionKey: string, reason: OperationEndReason, exceptOperationId?: string): void;
+    endAll(reason: OperationEndReason, exceptOperationId?: string): void;
+    private _touch;
+    private _createTimer;
+    private _rememberEnded;
+}
+
 type HardwareMethodMetadata = {
     chain: ChainForFingerprint;
     allNetwork: boolean;
+    /** Whether repeating the method after an ambiguous transport failure is safe. */
+    replayAfterTransportFailure: 'safe' | 'unsafe';
 };
 declare const HARDWARE_METHOD_CATALOG: {
     readonly evmGetAddress: {
         readonly chain: "evm";
         readonly allNetwork: true;
+        readonly replayAfterTransportFailure: "safe";
     };
     readonly evmSignTransaction: {
         readonly chain: "evm";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "unsafe";
     };
     readonly evmSignMessage: {
         readonly chain: "evm";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "unsafe";
     };
     readonly evmSignTypedData: {
         readonly chain: "evm";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "unsafe";
     };
     readonly btcGetAddress: {
         readonly chain: "btc";
         readonly allNetwork: true;
+        readonly replayAfterTransportFailure: "safe";
     };
     readonly btcGetPublicKey: {
         readonly chain: "btc";
         readonly allNetwork: true;
+        readonly replayAfterTransportFailure: "safe";
     };
     readonly btcSignTransaction: {
         readonly chain: "btc";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "unsafe";
     };
     readonly btcSignPsbt: {
         readonly chain: "btc";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "unsafe";
     };
     readonly btcSignMessage: {
         readonly chain: "btc";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "unsafe";
     };
     readonly btcGetMasterFingerprint: {
         readonly chain: "btc";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "safe";
     };
     readonly solGetAddress: {
         readonly chain: "sol";
         readonly allNetwork: true;
+        readonly replayAfterTransportFailure: "safe";
     };
     readonly solSignTransaction: {
         readonly chain: "sol";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "unsafe";
     };
     readonly solSignMessage: {
         readonly chain: "sol";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "unsafe";
     };
     readonly tronGetAddress: {
         readonly chain: "tron";
         readonly allNetwork: true;
+        readonly replayAfterTransportFailure: "safe";
     };
     readonly tronSignTransaction: {
         readonly chain: "tron";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "unsafe";
     };
     readonly tronSignMessage: {
         readonly chain: "tron";
         readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "unsafe";
+    };
+    readonly zcashGetFullViewingKey: {
+        readonly chain: "zcash";
+        readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "safe";
+    };
+    readonly zcashGetShieldedAddress: {
+        readonly chain: "zcash";
+        readonly allNetwork: false;
+        readonly replayAfterTransportFailure: "safe";
     };
 };
 type HardwareMethodName = keyof typeof HARDWARE_METHOD_CATALOG;
@@ -825,6 +1017,11 @@ type AllNetworkMethodName = {
 }[HardwareMethodName];
 declare const ALL_NETWORK_METHOD_NAMES: AllNetworkMethodName[];
 declare function getHardwareMethodMetadata(method: string): HardwareMethodMetadata | undefined;
+/**
+ * Conservative replay gate used only after a call may have reached hardware.
+ * Unknown methods and device mutations are unsafe by default.
+ */
+declare function canReplayHardwareMethodAfterTransportFailure(method: string): boolean;
 declare function isAllNetworkMethodName(method: string): method is AllNetworkMethodName;
 declare function getAllNetworkMethodChain(method: AllNetworkMethodName): ChainForFingerprint;
 
@@ -843,7 +1040,7 @@ type HardwareUiEvent = Exclude<ConnectorUiEvent, {
         progress: number;
     };
 };
-type ChainCapability = 'evm' | 'btc' | 'sol' | 'tron';
+type ChainCapability = 'evm' | 'btc' | 'sol' | 'tron' | 'zcash';
 type TrezorDisplayRotation = 'North' | 'East' | 'South' | 'West';
 type TrezorSafetyCheckLevel = 'Strict' | 'PromptAlways' | 'PromptTemporarily';
 type TrezorDeviceSettingsParams = {
@@ -914,19 +1111,78 @@ type DeviceAuthenticityResult = {
         };
     };
 };
+/** Persisted connection hints, never proof of device or wallet identity. */
+type KnownDeviceConnection = {
+    transport: 'usb' | 'ble';
+    connectId: string;
+} | {
+    transport: 'qr';
+};
+/** Opaque host lookup identifiers. Never forward these to firmware or logs. */
+type HardwareCallExtra = Readonly<Record<string, string>>;
+interface IHardwareConnectionContext {
+    knownConnections?: readonly KnownDeviceConnection[];
+    extra?: HardwareCallExtra;
+    /** False makes discovery fail instead of asking the user to select a new endpoint. */
+    allowDeviceSelection?: boolean;
+    /** Transports the host's model table allows; discovery never opens others. Omitted = any. */
+    supportedTransports?: readonly ('usb' | 'ble')[];
+}
+type DeviceSelectionContext = {
+    kind: 'select-device';
+    transport: 'usb';
+    reason: 'multiple-candidates';
+} | {
+    kind: 'bind-connection';
+    transport: 'ble';
+    reason: 'missing-binding' | 'known-connection-unavailable' | 'manual-rebind';
+};
+interface DeviceSelectionRequest extends UiRequestOperationAttribution {
+    devices: DeviceInfo[];
+    /** Echo this in the `RECEIVE_SELECT_DEVICE` answer; an answer without it is ignored. */
+    requestId: string;
+    context: DeviceSelectionContext;
+    extra?: HardwareCallExtra;
+    /** Repeated snapshots with this requestId update one SDK-owned binding scan. */
+    scanning?: boolean;
+    bindingSessionId?: string;
+    /** A candidate rejected by SDK identity verification in this binding session. */
+    rejectedConnectId?: string;
+}
+/** The host must persist this endpoint before acknowledging. */
+interface SaveDeviceBindingRequest extends UiRequestOperationAttribution {
+    requestId: string;
+    selectionRequestId: string;
+    connection: {
+        transport: 'ble';
+        connectId: string;
+    };
+    /** Omitted when the vendor binds the selected BLE endpoint without checking its wallet (Ledger). */
+    identity?: Extract<WalletIdentity, {
+        vendor: 'ledger' | 'trezor';
+    }>;
+    extra?: HardwareCallExtra;
+}
+type BindBleDeviceParams = Pick<SaveDeviceBindingRequest, 'identity' | 'extra'>;
+interface DeviceBindingStatus {
+    selectionRequestId: string;
+    status: 'verifying' | 'saved' | 'failed' | 'cancelled';
+}
 /**
  * Cross-chain / cross-vendor options passed alongside any chain method's
  * own params (the optional last argument). Holds operation-level switches
  * that aren't specific to one chain. Vendor-specific options can be added
  * as typed sub-fields here when a vendor actually needs them.
  */
-interface ICommonCallParams {
+interface ICommonCallParams extends IHardwareConnectionContext {
     /**
      * When the required device app is missing, prompt the user (UI request)
      * to install it, stream install progress, then retry the operation once.
      * Off by default — preserves the plain "app not installed" failure.
      */
     autoInstallApp?: boolean;
+    /** Runtime-only id from connectDevice(); when present, discovery and fallback are disabled. */
+    operationId?: string;
 }
 type NullableCallArg<T> = T | null | undefined;
 interface IPassphraseCallParams {
@@ -935,6 +1191,14 @@ interface IPassphraseCallParams {
 }
 type IHardwareCommonCallParams = ICommonCallParams & IPassphraseCallParams;
 type IHardwareCallParams<T> = T & IHardwareCommonCallParams;
+/**
+ * Runtime-only device-manager context, never forwarded to firmware. The expected identity lets an
+ * adapter fail closed before replaying a read or mutation after a reconnect.
+ */
+interface IDeviceManagerOperationContext extends IHardwareConnectionContext {
+    operationId?: string;
+    expectedDeviceIdentity?: WalletIdentity;
+}
 interface AllNetworkAddressParams {
     network: string;
     path: string;
@@ -945,16 +1209,7 @@ interface AllNetworkAddressParams {
 interface AllNetworkGetAddressParams extends IHardwareCommonCallParams {
     bundle: AllNetworkAddressParams[];
 }
-type AllNetworkDeviceIdentity = {
-    vendor: 'ledger';
-    type: 'chainFingerprint';
-    chain: ChainForFingerprint;
-    value: string;
-} | {
-    vendor: 'trezor';
-    type: 'deviceId';
-    value: string;
-};
+type AllNetworkDeviceIdentity = WalletIdentity;
 type AllNetworkAddressResponsePayload = Record<string, unknown> & {
     error?: string;
     code?: HardwareErrorCode | number;
@@ -962,6 +1217,7 @@ type AllNetworkAddressResponsePayload = Record<string, unknown> & {
     connectId?: string;
     deviceId?: string;
     deviceIdentity?: AllNetworkDeviceIdentity;
+    rootFingerprint?: number;
     chainFingerprint?: string;
     chainFingerprintChain?: ChainForFingerprint;
     params?: Record<string, unknown>;
@@ -1002,6 +1258,7 @@ type DeviceEvent = {
         connectId: string;
         deviceId?: string;
         credentials: Record<string, unknown>[];
+        removed?: Record<string, unknown>[];
     };
 };
 type UiRequestEvent = {
@@ -1010,46 +1267,50 @@ type UiRequestEvent = {
         device?: DeviceInfo;
         connectId?: string;
         type?: string;
-    };
+    } & UiRequestOperationAttribution;
 } | {
     type: typeof UI_REQUEST.REQUEST_PASSPHRASE;
     payload: {
         device: DeviceInfo;
-    };
+    } & UiRequestOperationAttribution;
 } | {
     type: typeof UI_REQUEST.REQUEST_PASSPHRASE_ON_DEVICE;
     payload: {
         device: DeviceInfo;
-    };
+    } & UiRequestOperationAttribution;
 } | {
     type: typeof UI_REQUEST.REQUEST_BUTTON;
     payload: {
         device: DeviceInfo;
         code?: string;
-    };
+    } & UiRequestOperationAttribution;
 } | {
     type: typeof UI_REQUEST.REQUEST_QR_DISPLAY;
     payload: {
         device: DeviceInfo;
         data: QrDisplayData;
-    };
+    } & UiRequestOperationAttribution;
 } | {
     type: typeof UI_REQUEST.REQUEST_QR_SCAN;
     payload: {
         device: DeviceInfo;
-    };
+    } & UiRequestOperationAttribution;
 } | {
     type: typeof UI_REQUEST.REQUEST_DEVICE_PERMISSION;
     payload: {
         transportType: TransportType;
         connectId?: string;
         deviceId?: string;
-    };
+    } & UiRequestOperationAttribution;
 } | {
     type: typeof UI_REQUEST.REQUEST_SELECT_DEVICE;
-    payload: {
-        devices: DeviceInfo[];
-    };
+    payload: DeviceSelectionRequest;
+} | {
+    type: typeof UI_REQUEST.REQUEST_SAVE_DEVICE_BINDING;
+    payload: SaveDeviceBindingRequest;
+} | {
+    type: typeof UI_REQUEST.DEVICE_BINDING_STATUS;
+    payload: DeviceBindingStatus;
 } | {
     type: typeof UI_REQUEST.REQUEST_DEVICE_CONNECT;
     payload: {
@@ -1069,13 +1330,13 @@ type UiRequestEvent = {
          * isn't recognized.
          */
         message: string;
-    };
+    } & UiRequestOperationAttribution;
 } | {
     type: typeof UI_REQUEST.REQUEST_INSTALL_APP;
     payload: {
         vendor: string;
         appName: string;
-    };
+    } & UiRequestOperationAttribution;
 } | {
     type: typeof UI_REQUEST.REQUEST_TREZOR_THP_PAIRING;
     payload: {
@@ -1083,10 +1344,10 @@ type UiRequestEvent = {
         availableMethods: number[];
         selectedMethod: number;
         nfcData?: string;
-    };
+    } & UiRequestOperationAttribution;
 } | {
     type: typeof UI_REQUEST.CLOSE_UI_WINDOW;
-    payload: Record<string, never>;
+    payload: UiRequestOperationAttribution;
 };
 type SdkEvent = {
     type: typeof SDK.DEVICE_INTERACTION;
@@ -1109,6 +1370,12 @@ type SdkEvent = {
     payload: {
         connectId: string;
     };
+} | {
+    type: typeof SDK.OPERATION_ENDED;
+    payload: {
+        operationId: string;
+        reason: OperationEndReason;
+    };
 };
 type HardwareEvent = DeviceEvent | UiRequestEvent | SdkEvent | HardwareUiEvent;
 type DeviceEventListener = (event: HardwareEvent) => void;
@@ -1119,6 +1386,14 @@ type DeviceEventListener = (event: HardwareEvent) => void;
  * and the value is the narrowed event object the listener will receive.
  */
 interface HardwareEventMap {
+    [UI_REQUEST.DEVICE_BINDING_STATUS]: {
+        type: typeof UI_REQUEST.DEVICE_BINDING_STATUS;
+        payload: DeviceBindingStatus;
+    };
+    [UI_REQUEST.REQUEST_SAVE_DEVICE_BINDING]: {
+        type: typeof UI_REQUEST.REQUEST_SAVE_DEVICE_BINDING;
+        payload: SaveDeviceBindingRequest;
+    };
     'ui-event': HardwareUiEvent;
     [DEVICE.CONNECT]: {
         type: typeof DEVICE.CONNECT;
@@ -1151,6 +1426,8 @@ interface HardwareEventMap {
             connectId: string;
             deviceId?: string;
             credentials: Record<string, unknown>[];
+            /** Credentials the device rejected; a list kept for several devices drops these. */
+            removed?: Record<string, unknown>[];
         };
     };
     [UI_REQUEST.REQUEST_PIN]: {
@@ -1159,7 +1436,7 @@ interface HardwareEventMap {
             device?: DeviceInfo;
             connectId?: string;
             type?: string;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.REQUEST_PASSPHRASE]: {
         type: typeof UI_REQUEST.REQUEST_PASSPHRASE;
@@ -1168,33 +1445,33 @@ interface HardwareEventMap {
             connectId?: string;
             passphraseState?: string;
             useEmptyPassphrase?: boolean;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.REQUEST_PASSPHRASE_ON_DEVICE]: {
         type: typeof UI_REQUEST.REQUEST_PASSPHRASE_ON_DEVICE;
         payload: {
             device: DeviceInfo;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.REQUEST_BUTTON]: {
         type: typeof UI_REQUEST.REQUEST_BUTTON;
         payload: {
             device: DeviceInfo;
             code?: string;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.REQUEST_QR_DISPLAY]: {
         type: typeof UI_REQUEST.REQUEST_QR_DISPLAY;
         payload: {
             device: DeviceInfo;
             data: QrDisplayData;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.REQUEST_QR_SCAN]: {
         type: typeof UI_REQUEST.REQUEST_QR_SCAN;
         payload: {
             device: DeviceInfo;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.REQUEST_DEVICE_PERMISSION]: {
         type: typeof UI_REQUEST.REQUEST_DEVICE_PERMISSION;
@@ -1202,13 +1479,11 @@ interface HardwareEventMap {
             transportType: TransportType;
             connectId?: string;
             deviceId?: string;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.REQUEST_SELECT_DEVICE]: {
         type: typeof UI_REQUEST.REQUEST_SELECT_DEVICE;
-        payload: {
-            devices: DeviceInfo[];
-        };
+        payload: DeviceSelectionRequest;
     };
     [UI_REQUEST.REQUEST_DEVICE_CONNECT]: {
         type: typeof UI_REQUEST.REQUEST_DEVICE_CONNECT;
@@ -1216,7 +1491,7 @@ interface HardwareEventMap {
             vendor: string;
             reason: string;
             message: string;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.REQUEST_BTC_HIGH_INDEX_CONFIRM]: {
         type: typeof UI_REQUEST.REQUEST_BTC_HIGH_INDEX_CONFIRM;
@@ -1224,14 +1499,14 @@ interface HardwareEventMap {
             vendor: string;
             path: string;
             accountIndex: number;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.REQUEST_INSTALL_APP]: {
         type: typeof UI_REQUEST.REQUEST_INSTALL_APP;
         payload: {
             vendor: string;
             appName: string;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.REQUEST_TREZOR_THP_PAIRING]: {
         type: typeof UI_REQUEST.REQUEST_TREZOR_THP_PAIRING;
@@ -1240,11 +1515,11 @@ interface HardwareEventMap {
             availableMethods: number[];
             selectedMethod: number;
             nfcData?: string;
-        };
+        } & UiRequestOperationAttribution;
     };
     [UI_REQUEST.CLOSE_UI_WINDOW]: {
         type: typeof UI_REQUEST.CLOSE_UI_WINDOW;
-        payload: Record<string, never>;
+        payload: UiRequestOperationAttribution;
     };
     [SDK.DEVICE_INTERACTION]: {
         type: typeof SDK.DEVICE_INTERACTION;
@@ -1271,16 +1546,23 @@ interface HardwareEventMap {
             connectId: string;
         };
     };
+    [SDK.OPERATION_ENDED]: {
+        type: typeof SDK.OPERATION_ENDED;
+        payload: {
+            operationId: string;
+            reason: OperationEndReason;
+        };
+    };
 }
 interface IDeviceManagerMethods {
-    getFeatures?(connectId: string): Promise<Response<Record<string, unknown>>>;
-    deviceSettings?(connectId: string, params: TrezorDeviceSettingsParams): Promise<Response<Record<string, unknown>>>;
-    setBrightness?(connectId: string, params?: TrezorBrightnessParams): Promise<Response<Record<string, unknown>>>;
-    changePin?(connectId: string, params?: TrezorChangePinParams): Promise<Response<Record<string, unknown>>>;
-    wipeDevice?(connectId: string): Promise<Response<Record<string, unknown>>>;
+    getFeatures?(connectId: string, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
+    deviceSettings?(connectId: string, params: TrezorDeviceSettingsParams, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
+    setBrightness?(connectId: string, params?: TrezorBrightnessParams, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
+    changePin?(connectId: string, params?: TrezorChangePinParams, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
+    wipeDevice?(connectId: string, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
     authenticateDevice?(connectId: string, params: {
         challenge: string;
-    }): Promise<Response<Record<string, unknown>>>;
+    }, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
 }
 interface IWalletStateMethods {
     /**
@@ -1307,20 +1589,35 @@ interface IWalletStateMethods {
      * Optional: vendors without host-managed passphrase sessions (Ledger) omit
      * it. Implemented by `TrezorAdapter`.
      */
-    getPassphraseState?(connectId: string, passphraseState?: string): Promise<Response<string | null>>;
+    getPassphraseState?(connectId: string, passphraseState?: string, operationContext?: IDeviceManagerOperationContext): Promise<Response<string | null>>;
 }
+/**
+ * `stops-waiting`: an on-device confirmation stays up until answered or timed out.
+ * `interrupts-device`: the command on the wire is withdrawn. No vendor reports it, so hosts
+ * should say "stopped waiting, answer on the device", not "cancelled".
+ */
+type CancelCapability = 'interrupts-device' | 'stops-waiting';
 interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, ISolMethods, ITronMethods, IDeviceManagerMethods, IWalletStateMethods {
     readonly vendor: string;
     readonly activeTransport: TransportType | null;
+    /** What `cancel()` reaches on this vendor. Declared, never inferred. */
+    readonly cancelCapability: CancelCapability;
     init(config: TConfig): Promise<void>;
     dispose(): Promise<void>;
     getAvailableTransports(): TransportType[];
     switchTransport(type: TransportType): Promise<void>;
     searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
-    connectDevice(connectId: string): Promise<Response<string>>;
-    disconnectDevice(connectId: string): Promise<void>;
+    /** Discover selectable hardware entries without claiming identified devices or wallets. */
+    searchDeviceTargets(options?: SearchDevicesOptions): Promise<DeviceSearchTarget[]>;
+    /** Connect or logically bind a selected search result and return a runtime-only operation id. */
+    connectDevice(searchTargetId: string): Promise<Response<string>>;
+    /** Device Manager rebind: verify the existing identity before replacing its BLE locator. */
+    bindBleDevice?(params: BindBleDeviceParams): Promise<Response<string>>;
+    /** Resolve and pin operation routing; the caller verifies wallet identity before business calls. */
+    acquireOperation?(connectId: string, context: IHardwareConnectionContext): Promise<Response<string>>;
+    /** Release a caller-owned operation. Disconnect events end matching operations automatically. */
+    releaseOperation(operationId: string): Promise<void>;
     getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
-    getSupportedChains(): ChainCapability[];
     /** Abort the in-flight call. Omit connectId to cancel whatever is active. */
     cancel(connectId?: string): void;
     allNetworkGetAddress(connectId: string, deviceId: string, params: AllNetworkGetAddressParams): Promise<Response<AllNetworkAddressResponse[]>>;
@@ -1357,6 +1654,11 @@ interface SearchDevicesOptions {
      * was discovered first.
      */
     waitForAllTransports?: boolean;
+    /**
+     * Restrict discovery to one transport. A virtual target (Keystone QR) must not start any wallet
+     * interaction during discovery; `connectDevice()` resolves it.
+     */
+    transportType?: ConnectionType;
 }
 
 interface EvmGetAddressParams extends PassphraseStateAware {
@@ -1370,6 +1672,8 @@ interface EvmAddress {
     path: string;
     /** Device-reported secp256k1 public key; populated when the transport exposes it. */
     publicKey?: string;
+    /** Set by air-gapped wallets (Keystone): the exported key this address derives from. */
+    accountKey?: ExportedAccountKey;
 }
 interface EvmSignTxBaseParams extends PassphraseStateAware {
     path: string;
@@ -1480,6 +1784,11 @@ interface EvmSignTypedDataFull extends PassphraseStateAware {
         primaryType: string;
         message: Record<string, unknown>;
     };
+    /**
+     * The dApp's original EIP-712 JSON, byte for byte. Serializing vendors (Keystone) must prefer it:
+     * re-stringifying `data` rewrites integers wider than 2^53 and exponent forms.
+     */
+    dataJson?: string;
     metamaskV4Compat?: boolean;
     showMessageHash?: boolean;
     /**
@@ -1518,6 +1827,33 @@ interface IEvmMethods {
     evmSignTypedData(connectId?: NullableCallArg<string>, deviceId?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<EvmSignTypedDataParams>>): Promise<Response<EvmSignature>>;
 }
 
+/** Which `GET_VK` encoding the Ledger Zcash app should return. */
+type ZcashFullViewingKeyMode = 'ufvk' | 'orchardFvk';
+interface ZcashGetFullViewingKeyParams extends PassphraseStateAware {
+    /** BIP44 account path `m/44'/133'/a'`; a deeper transparent path is accepted, only `a'` is used. */
+    path: string;
+    /** Default `ufvk`. */
+    mode?: ZcashFullViewingKeyMode;
+}
+interface ZcashFullViewingKey {
+    path: string;
+    mode: ZcashFullViewingKeyMode;
+    /** ZIP-316 bech32m UFVK string (mode `ufvk`). */
+    ufvk?: string;
+    /** 96-byte raw Orchard FVK as hex (mode `orchardFvk`). */
+    orchardFvk?: string;
+}
+interface ZcashGetShieldedAddressParams extends PassphraseStateAware {
+    /** Full 5-level transparent path `m/44'/133'/a'/0/i`; the Orchard path is derived from it. */
+    path: string;
+    showOnDevice?: boolean;
+}
+interface ZcashShieldedAddress {
+    /** Unified address with a single Orchard receiver. */
+    address: string;
+    path: string;
+}
+
 /**
  * Low-level device descriptor from Transport layer.
  * Represents a physical device detected by USB/BLE scanning.
@@ -1563,14 +1899,13 @@ interface DeviceDisconnectEvent {
 type DeviceChangeEvent = DeviceConnectEvent | DeviceDisconnectEvent;
 
 /**
- * Pure FIFO job queue. Every enqueue chains onto the tail; jobs run one at
- * a time across all devices. The queue is intentionally passive — it does
- * NOT decide whether to interrupt or ask the user. Those are application-
- * layer concerns owned by the caller (e.g. a UI button handler that wants
- * to ask "device is busy, interrupt current?" before submitting). The
- * queue exposes inspection (`getActiveJob`) and explicit cancellation
- * (`cancelActive` / `cancelAll`) so callers can implement those policies
- * synchronously, without racing against in-flight enqueues.
+ * Serializes every device call and gives callers one handle to cancel them. Ordering is already
+ * guaranteed by awaiting callers, so what this adds is an AbortController per job, a busy check
+ * that rejects double-submits, and generation tracking so a job queued before a teardown doesn't
+ * start after it; these races exist even for a sequential caller because cleanup is async.
+ *
+ * Interrupt-or-ask policy belongs to the caller; `getActiveJob()` is synchronous so a UI handler
+ * can look, decide, and submit in one turn without racing an in-flight enqueue.
  */
 interface JobOptions {
     label?: string;
@@ -1582,10 +1917,15 @@ interface ActiveJobInfo {
     label?: string;
     startedAt: number;
 }
+interface CancelScopeHandle {
+    signal: AbortSignal;
+    release: () => void;
+}
 declare class DeviceJobQueue {
     private _tail;
     private _active;
     private readonly _jobs;
+    private readonly _cancelScopes;
     /** Incremented on clear() so queued-but-not-yet-running jobs detect invalidation. */
     private _generation;
     private readonly _generationCancelReasons;
@@ -1594,21 +1934,64 @@ declare class DeviceJobQueue {
      * `deviceId` is a label only — used by inspection / cancellation routing.
      */
     enqueue<T>(deviceId: string, job: (signal: AbortSignal) => Promise<T>, options?: JobOptions): Promise<T>;
-    /** Cancel the active job. If `deviceId` is given, only cancels when it matches. */
-    cancelActive(deviceId?: string): boolean;
-    /** Force cancel the active job. `reason` becomes signal.reason. */
-    forceCancelActive(deviceId?: string, reason?: Error): boolean;
-    /** Cancel the active job (alias for callers that previously needed multi-device cancel). */
-    cancelAllActive(reason?: Error): void;
-    /** Cancel the active job and invalidate queued jobs that have not started. */
+    /**
+     * Holds a cancel across the gaps between a bundle's per-item jobs, when the queue is empty.
+     * Callers must `release()` when the bundle ends.
+     */
+    createCancelScope(deviceId: string): CancelScopeHandle;
+    /**
+     * Cancels the running job only; `reason` becomes signal.reason. Adapters use
+     * `cancelActiveAndPending`; this stays for a connector layer that stops only what is on the wire.
+     */
+    cancelActive(deviceId?: string, reason?: Error): boolean;
+    /**
+     * Cancels the active job and unstarted queued jobs; returns whether anything was reached. Only
+     * `undefined` means everything: an empty key matches nothing instead of tearing the queue down.
+     */
     cancelActiveAndPending(deviceId?: string, reason?: Error): boolean;
     /** Get info about the currently active job, or null if idle. */
     getActiveJob(deviceId?: string): ActiveJobInfo | null;
-    /** True if any job is currently running. */
-    isBusy(): boolean;
     clear(reason?: Error): void;
 }
 
+declare const HARDWARE_RUNTIME_ID_PREFIX = "hwk:runtime";
+/**
+ * `search-target`: one device in one discovery snapshot, dead on the next search of that kind.
+ * `link`: one open transport. `operation`: one business operation.
+ */
+type HardwareRuntimeIdKind = 'operation' | 'search-target' | 'link';
+type HardwareRuntimeId = {
+    kind: HardwareRuntimeIdKind;
+    vendor: VendorType;
+};
+/** Runtime ids are opaque and must never be persisted as device identity. */
+declare function createHardwareOperationId(vendor: VendorType): string;
+/** Search targets are valid only for the adapter's current discovery snapshot. */
+declare function createHardwareSearchTargetId(vendor: VendorType): string;
+declare function createHardwareLinkId(vendor: VendorType): string;
+declare function hasHardwareRuntimeIdPrefix(value: unknown): value is string;
+declare function parseHardwareRuntimeId(value: unknown): HardwareRuntimeId | undefined;
+declare function isHardwareOperationId(value: unknown): value is string;
+
+interface HardwareOperationTarget {
+    /** Effective target accepted by existing adapter/connector call paths. */
+    targetId: string | undefined;
+    /** Present when this operation is pinned to a live operation. */
+    operationId: string | undefined;
+}
+/**
+ * Normalizes the transitional positional operation id and the canonical
+ * common-params field. All vendors must reject conflicting bindings.
+ */
+declare function resolveHardwareOperationTarget(positionalTargetId: string | null | undefined, commonOperationId: string | null | undefined, expectedVendor?: VendorType): Response<HardwareOperationTarget>;
+/** Narrow the connection-context fields of untyped call params. */
+declare function pickConnectionContext(params: {
+    knownConnections?: unknown;
+    extra?: unknown;
+    allowDeviceSelection?: unknown;
+    supportedTransports?: unknown;
+}): IHardwareConnectionContext;
+
 /**
  * Minimal typed event emitter using Map<string, Set<listener>>.
  * Each adapter uses this for device events (connect, disconnect, pin, etc.).
@@ -1635,6 +2018,104 @@ declare class TypedEventEmitter<TMap extends Record<string, any> = Record<string
     listenerCount(event: string): number;
 }
 
+/** Serializable BLE transport data shared by Electron main and renderer runtimes. */
+interface ElectronBleDeviceInfo {
+    id: string;
+    name?: string;
+    rssi?: number;
+    advertisedServiceUuids?: string[];
+}
+/**
+ * IPC-safe peripheral match: advertises one of `serviceUuids`, or its local name matches every
+ * `namePatterns` entry (case-insensitive regex sources). The desktop noble-ble host treats this
+ * as a hint only: its vendor allowlist decides, `serviceUuids` can only narrow it, and
+ * `namePatterns` are never compiled.
+ */
+interface ElectronBleMatch {
+    serviceUuids?: string[];
+    namePatterns?: string[];
+}
+interface ElectronBleScanOptions {
+    /** Opaque partition key: results and connected devices never mix across it. */
+    vendor?: string;
+    match?: ElectronBleMatch;
+    /** @deprecated Superseded by `match.serviceUuids`. */
+    serviceUuids?: string[];
+    durationMs?: number;
+}
+/** GATT profile plus the write framing this vendor's firmware expects. */
+interface ElectronBleConnectOptions {
+    vendor: string;
+    serviceUuid: string;
+    writeUuid: string;
+    notifyUuid: string;
+    /**
+     * `padded`: fixed `chunkSize` packets, last zero-filled (Trezor firmware drops short packets).
+     * `raw`: the buffer as given, for self-length-framed protocols (Ledger).
+     */
+    write?: {
+        mode: 'padded' | 'raw';
+        chunkSize?: number;
+        chunkDelayMs?: number;
+        maxLength?: number;
+    };
+}
+/** Native code handles GATT only; framing, identity checks and wallet calls stay in the SDK. */
+interface ElectronBleApi {
+    scan(options?: ElectronBleScanOptions): Promise<ElectronBleDeviceInfo[]>;
+    stopScan(vendor?: string): Promise<void>;
+    connect(id: string, options?: ElectronBleConnectOptions): Promise<{
+        id: string;
+        name?: string;
+    }>;
+    disconnect(id: string): Promise<void>;
+    subscribe(id: string): Promise<void>;
+    unsubscribe(id: string): Promise<void>;
+    write(id: string, hexData: string): Promise<void>;
+    checkAvailability(): Promise<{
+        available: boolean;
+        state: string;
+        initialized: boolean;
+    }>;
+    getDevice(id: string): Promise<ElectronBleDeviceInfo | null>;
+    onNotification(handler: (id: string, hexData: string) => void): () => void;
+    onDeviceDisconnected(handler: (id: string) => void): () => void;
+    /** Abandon an in-flight connect in the main process. Optional for hosts that cannot cancel. */
+    cancelPairing?(options?: {
+        vendor: string;
+        id?: string;
+    }): Promise<void>;
+}
+
+declare function emitDeviceBindingStatus(emitter: TypedEventEmitter<HardwareEventMap>, selectionRequestId: string, status: DeviceBindingStatus['status']): void;
+/**
+ * A host refusal is reported, never thrown: the device is already connected, so a lost binding
+ * is worth a warning and a retry, not failing the user's work.
+ */
+type SaveDeviceBindingOutcome = {
+    saved: true;
+} | {
+    saved: false;
+    reason: SaveDeviceBindingDeclineReason;
+};
+/** Persist a binding through the host. Only a user abort throws. */
+declare function requestSaveDeviceBinding(emitter: TypedEventEmitter<HardwareEventMap>, registry: UiRequestRegistry, binding: Omit<SaveDeviceBindingRequest, 'requestId'>, signal?: AbortSignal): Promise<SaveDeviceBindingOutcome>;
+
+/** Discovery and selection share one owner; never connect until the last scan has drained. */
+declare function requestBleDeviceSelection({ emitter, registry, request, scan, signal, allowUsbFallback, pollIntervalMs, }: {
+    emitter: TypedEventEmitter<HardwareEventMap>;
+    registry: UiRequestRegistry;
+    request: Omit<DeviceSelectionRequest, 'requestId' | 'scanning'>;
+    scan: () => Promise<DeviceInfo[]>;
+    signal: AbortSignal;
+    /** The adapter must verify a returned USB candidate before dispatching any business call. */
+    allowUsbFallback?: boolean;
+    pollIntervalMs?: number;
+}): Promise<{
+    device: DeviceInfo;
+    requestId: string;
+}>;
+
 /**
  * Compare two semver strings (e.g. "2.1.0" vs "2.3.1").
  * Returns -1 if a < b, 0 if equal, 1 if a > b.
@@ -1655,7 +2136,57 @@ declare function hexToBytes(hex: string): Uint8Array;
 /** Convert a Uint8Array to a hex string (no 0x prefix). */
 declare function bytesToHex(bytes: Uint8Array): string;
 
-type DetectableHardwareVendor = 'onekey' | 'trezor' | 'ledger';
+/**
+ * Walks CBOR from an untrusted source (a scanned QR code, a device reply) before a third-party
+ * decoder sees it. Those decoders read past the end as zero and trust declared lengths, so one
+ * indefinite-length header or a huge declared count exhausts memory. This walk accepts only
+ * definite lengths that fit in the bytes actually present, bounded nesting, and no trailing bytes.
+ */
+declare function assertBoundedCbor(input: Uint8Array, maxBytes?: number): void;
+/** Hex from an untrusted source, checked as such and then as bounded CBOR. */
+declare function boundedCborFromHex(hex: string, maxBytes?: number): Buffer;
+
+interface PrepareSolanaOffchainMessageV1Params {
+    message: Uint8Array;
+    requiredSigners: readonly string[];
+}
+interface PreparedSolanaOffchainMessageV1 {
+    messageText: string;
+    requiredSigners: string[];
+    serializedMessage: Uint8Array;
+}
+declare function prepareSolanaOffchainMessageV1({ message, requiredSigners, }: PrepareSolanaOffchainMessageV1Params): PreparedSolanaOffchainMessageV1;
+
+type LogSummaryContext = {
+    /** Method name from the options, or '' when none was given. */
+    method: string;
+    role: 'params' | 'result';
+};
+/**
+ * Returns extra space-separated hints for a payload field (e.g. PSBT input/output counts), or
+ * undefined to add nothing. `key` is normalized: lower-case with `_` and `-` removed. Hints are
+ * appended verbatim, so they must not contain payload contents. A throwing describer is ignored.
+ */
+type LogPayloadDescriber = (key: string, value: string | Uint8Array, context: LogSummaryContext) => string | undefined;
+type LogSummaryOptions = {
+    /** Public or connector method name; enables chain-specific hints (EVM tx type). */
+    method?: string;
+    /** In results, transaction fields hold signed transactions rather than requests. */
+    role?: 'params' | 'result';
+    /** Chain-specific payload hints that need a decoder adapter-core does not ship. */
+    describePayload?: LogPayloadDescriber;
+};
+/**
+ * JSON-safe, log-safe summary of `value`. Never throws.
+ *
+ * Paths, chain ids, flags and error fields stay readable; payloads become
+ * `<hex|str|json len=N sha256=16hex [hints]>`, addresses `first6…last4`, xpubs `xpub… len=N`,
+ * public keys and chain codes `… len=N`, signatures `<signature len=N>` and secrets
+ * `<redacted len=N>`.
+ */
+declare function summarizeForLog(value: unknown, options?: LogSummaryOptions): unknown;
+
+type DetectableHardwareVendor = 'onekey' | 'trezor' | 'ledger' | 'keystone';
 type HardwareDeviceIdentityInput = {
     name?: string | null;
     localName?: string | null;
@@ -1718,8 +2249,19 @@ type RunAllNetworkGetAddressOptions = {
     buildTopLevelFailure?: (response: AllNetworkAddressResponse, context: AllNetworkResponseContext) => Response<AllNetworkAddressResponse[]>;
 };
 declare function runAllNetworkGetAddress({ connectId, deviceId, params, getMethodChain, normalizeItem, buildUnsupportedNetworkResponse, callItem, attachIdentity, shouldAbortBundle, buildTopLevelFailure, }: RunAllNetworkGetAddressOptions): Promise<Response<AllNetworkAddressResponse[]>>;
+/** An SDK-dialog cancel or on-device reject ends the bundle; the user already answered "no". */
+declare function isUserRefusal(code: HardwareErrorCode | number | undefined): boolean;
+/**
+ * The device or wallet could not be shown to be the one asked for: another wallet, a locked
+ * device, a wrong PIN or passphrase. No later item may derive on it, and a PIN is not retried.
+ */
+declare function isWalletSafetyFailure(code: HardwareErrorCode | number | undefined): boolean;
+/** The bundle's session is gone, so the remaining items have nothing to run against. */
+declare function isConnectionLost(code: HardwareErrorCode | number | undefined): boolean;
+/** UserAborted is a top-level abort code, so this ends the bundle. */
+declare function buildAllNetworkCancelledFailure<T>(signal: AbortSignal): Response<T>;
 declare function buildUnsupportedMethodResponse(item: AllNetworkAddressParams): AllNetworkAddressResponse;
 
 declare const DEVICE_CONNECT_RETRY_DELAY_MS = 1000;
 
-export { ALL_NETWORK_METHOD_NAMES, type ActiveJobInfo, type AllNetworkAddressParams, type AllNetworkAddressResponse, type AllNetworkAddressResponsePayload, type AllNetworkAttachIdentityContext, type AllNetworkCallItemContext, type AllNetworkGetAddressParams, type AllNetworkMethodName, type AllNetworkResponseContext, type BtcAddress, type BtcGetAddressParams, type BtcGetPublicKeyParams, type BtcPaymentRequest, type BtcPaymentRequestMemo, type BtcPublicKey, type BtcRefTransaction, type BtcSignMsgParams, type BtcSignPsbtParams, type BtcSignTxParams, type BtcSignature, type BtcSignedPsbt, type BtcSignedTx, type BtcTxInput, type BtcTxOutput, CHAIN_FINGERPRINT_PATHS, type ChainCapability, type ChainForFingerprint, type ConnectionType, type ConnectorCallResult, type ConnectorConfig, type ConnectorDevice, type ConnectorErrorParams, type ConnectorEventMap, type ConnectorEventType, type ConnectorSerializedError, type ConnectorSession, type ConnectorUiEvent, DEVICE, DEVICE_CONNECT_RETRY_DELAY_MS, DEVICE_EVENT, type DetectableHardwareVendor, type DeviceAuthenticityParams, type DeviceAuthenticityResult, type DeviceCapabilities, type DeviceChangeEvent, type DeviceConnectEvent, type DeviceDescriptor, type DeviceDisconnectEvent, type DeviceEvent, type DeviceEventListener, type DeviceInfo, DeviceJobQueue, type DeviceTarget, EConnectorInteraction, type EIP712Domain, type EvmAddress, type EvmEthereumDefinitions, type EvmGetAddressParams, type EvmPaymentRequest, type EvmPaymentRequestMemo, type EvmSignMsgParams, type EvmSignTxLedgerParams, type EvmSignTxParams, type EvmSignTxTrezorParams, type EvmSignTypedDataFull, type EvmSignTypedDataHash, type EvmSignTypedDataParams, type EvmSignature, type EvmSignedTx, type Failure, HARDWARE_METHOD_CATALOG, type HardwareDeviceIdentityInput, HardwareErrorCode, type HardwareEvent, type HardwareEventMap, type HardwareMethodMetadata, type HardwareMethodName, type HardwareUiEvent, type IBtcMethods, type ICommonCallParams, type IConnector, type IDeviceManagerMethods, type IEvmMethods, type IHardwareBridge, type IHardwareCallParams, type IHardwareCommonCallParams, type IHardwareWallet, type IPassphraseCallParams, type ISolMethods, type ITronMethods, type IWalletStateMethods, type JobOptions, type NullableCallArg, type PassphraseResponse, type PassphraseStateAware, QrDisplayData, type Response, type RunAllNetworkGetAddressOptions, SDK, type SdkEvent, type SearchDevicesOptions, type SolAddress, type SolGetAddressParams, type SolSignMsgParams, type SolSignTxParams, type SolSignature, type SolSignedTx, type Success, type TransportType, type TrezorBrightnessParams, type TrezorChangePinParams, type TrezorDeviceSettingsParams, type TrezorDisplayRotation, type TrezorSafetyCheckLevel, type TronAddress, type TronContract, type TronFreezeBalanceV2Contract, type TronGetAddressParams, type TronResource, type TronSignMsgParams, type TronSignTxParams, type TronSignature, type TronSignedTx, type TronTransferContract, type TronTriggerSmartContract, type TronUnfreezeBalanceV2Contract, type TronVote, type TronVoteWitnessContract, type TronWithdrawExpireUnfreezeContract, TypedEventEmitter, UI_REQUEST, type UiRequestEvent, UiResponseEvent, type VendorType, batchCall, buildUnsupportedMethodResponse, bytesToHex, compareSemver, createBridgedConnector, createCombinedConnector, deriveDeviceFingerprint, detectHardwareVendorFromDescriptor, ensure0x, failure, getAllNetworkMethodChain, getHardwareMethodMetadata, hexToBytes, isAllNetworkMethodName, isKnownNonTargetHardwareVendor, padHex64, rehydrateConnectorError, runAllNetworkGetAddress, serializeConnectorError, stripHex, success };
+export { ALL_NETWORK_METHOD_NAMES, type ActiveJobInfo, type AllNetworkAddressParams, type AllNetworkAddressResponse, type AllNetworkAddressResponsePayload, type AllNetworkAttachIdentityContext, type AllNetworkCallItemContext, type AllNetworkDeviceIdentity, type AllNetworkGetAddressParams, type AllNetworkMethodName, type AllNetworkResponseContext, type BindBleDeviceParams, type BtcAddress, type BtcGetAddressParams, type BtcGetPublicKeyParams, type BtcPaymentRequest, type BtcPaymentRequestMemo, type BtcPublicKey, type BtcRefTransaction, type BtcSignMsgParams, type BtcSignPsbtParams, type BtcSignTxParams, type BtcSignature, type BtcSignedPsbt, type BtcSignedTx, type BtcTxInput, type BtcTxOutput, CHAIN_FINGERPRINT_PATHS, type CancelCapability, type CancelScopeHandle, type ChainCapability, type ChainForFingerprint, type ConnectionType, type ConnectorCallResult, type ConnectorConfig, type ConnectorConnectTarget, type ConnectorDevice, type ConnectorErrorParams, type ConnectorEventMap, type ConnectorEventType, type ConnectorSearchDevicesOptions, type ConnectorSerializedError, type ConnectorSession, type ConnectorUiEvent, DEVICE, DEVICE_CONNECT_RETRY_DELAY_MS, DEVICE_EVENT, type DetectableHardwareVendor, type DeviceAuthenticityParams, type DeviceAuthenticityResult, type DeviceBindingStatus, type DeviceCapabilities, type DeviceChangeEvent, type DeviceConnectEvent, type DeviceDescriptor, type DeviceDisconnectEvent, type DeviceEvent, type DeviceEventListener, type DeviceInfo, DeviceJobQueue, type DeviceSearchTarget, type DeviceSelectionContext, type DeviceSelectionRequest, type DeviceTarget, EConnectorInteraction, type EIP712Domain, type ElectronBleApi, type ElectronBleConnectOptions, type ElectronBleDeviceInfo, type ElectronBleMatch, type ElectronBleScanOptions, type EvmAddress, type EvmEthereumDefinitions, type EvmGetAddressParams, type EvmPaymentRequest, type EvmPaymentRequestMemo, type EvmSignMsgParams, type EvmSignTxLedgerParams, type EvmSignTxParams, type EvmSignTxTrezorParams, type EvmSignTypedDataFull, type EvmSignTypedDataHash, type EvmSignTypedDataParams, type EvmSignature, type EvmSignedTx, ExportedAccountKey, type Failure, HARDWARE_METHOD_CATALOG, HARDWARE_RUNTIME_ID_PREFIX, type HardwareCallExtra, type HardwareDeviceIdentityInput, HardwareErrorCode, type HardwareEvent, type HardwareEventMap, type HardwareMethodMetadata, type HardwareMethodName, type HardwareOperation, type HardwareOperationTarget, type HardwareRuntimeId, type HardwareRuntimeIdKind, type HardwareUiEvent, HwkErrorOrigin, HwkRecoveryHint, type IBtcMethods, type ICommonCallParams, type IConnector, type IDeviceManagerMethods, type IDeviceManagerOperationContext, type IEvmMethods, type IHardwareBridge, type IHardwareCallParams, type IHardwareCommonCallParams, type IHardwareConnectionContext, type IHardwareWallet, type IPassphraseCallParams, type ISolMethods, type ITronMethods, type IWalletStateMethods, type JobOptions, type KnownDeviceConnection, type LogPayloadDescriber, type LogSummaryContext, type LogSummaryOptions, MISSING_BIP32_MASTER_FINGERPRINT, type NullableCallArg, OPERATION_DEFAULT_TTL_MS, type OperationEndReason, OperationRegistry, type PassphraseResponse, type PassphraseStateAware, type PrepareSolanaOffchainMessageV1Params, type PreparedSolanaOffchainMessageV1, QrDisplayData, type Response, type RunAllNetworkGetAddressOptions, SDK, SaveDeviceBindingDeclineReason, type SaveDeviceBindingRequest, type SdkEvent, type SearchDevicesOptions, type SearchTargetReusePolicy, type SolAddress, type SolGetAddressParams, type SolOffchainMessageV1Params, type SolSignMsgParams, type SolSignTxParams, type SolSignature, type SolSignedTx, type Success, type TransportType, type TrezorBrightnessParams, type TrezorChangePinParams, type TrezorDeviceSettingsParams, type TrezorDisplayRotation, type TrezorSafetyCheckLevel, type TronAddress, type TronContract, type TronFreezeBalanceV2Contract, type TronGetAddressParams, type TronResource, type TronSignMsgParams, type TronSignTxParams, type TronSignature, type TronSignedTx, type TronTransferContract, type TronTriggerSmartContract, type TronUnfreezeBalanceV2Contract, type TronVote, type TronVoteWitnessContract, type TronWithdrawExpireUnfreezeContract, TypedEventEmitter, UI_REQUEST, type UiRequestEvent, UiRequestOperationAttribution, UiRequestRegistry, UiResponseEvent, type VendorType, type WalletIdentity, type ZcashFullViewingKey, type ZcashFullViewingKeyMode, type ZcashGetFullViewingKeyParams, type ZcashGetShieldedAddressParams, type ZcashShieldedAddress, assertBoundedCbor, batchCall, boundedCborFromHex, buildAllNetworkCancelledFailure, buildUnsupportedMethodResponse, bytesToHex, canReplayHardwareMethodAfterTransportFailure, compareSemver, createBridgedConnector, createCombinedConnector, createHardwareLinkId, createHardwareOperationId, createHardwareSearchTargetId, deriveDeviceFingerprint, detectHardwareVendorFromDescriptor, emitDeviceBindingStatus, ensure0x, failure, getAllNetworkMethodChain, getHardwareMethodMetadata, hasHardwareRuntimeIdPrefix, hexToBytes, isAllNetworkMethodName, isConnectionLost, isHardwareOperationId, isKnownNonTargetHardwareVendor, isUserRefusal, isWalletSafetyFailure, padHex64, parseBip32MasterFingerprint, parseHardwareRuntimeId, parseWalletMasterFingerprint, pickConnectionContext, prepareSolanaOffchainMessageV1, rehydrateConnectorError, requestBleDeviceSelection, requestSaveDeviceBinding, resolveHardwareOperationTarget, resolveSearchTargetReusePolicy, runAllNetworkGetAddress, serializeConnectorError, stripHex, success, summarizeForLog, toPhysicalDeviceSearchTarget };