@onekeyfe/hwk-adapter-core 1.1.27-alpha.42 → 1.1.27-alpha.43

package/dist/index.d.mts

@@ -40,6 +40,8 @@ declare enum HardwareErrorCode {
     DeviceAppStuck = 10107,
     /** Vendor (Ledger / Trezor) doesn't support the chain at all. */
     ChainNotSupported = 10108,
+    /** Current operation supports only one connected device. */
+    DeviceOneDeviceOnly = 10109,
     FirmwareTooOld = 10200,
     FirmwareUpdateRequired = 10201,
     TransportError = 10300,
@@ -67,6 +69,8 @@ declare enum HardwareErrorCode {
     WrongApp = 10501,
     /** 0x911c Command code not supported — app predates current SDK. */
     AppTooOld = 10502,
+    /** Not enough free storage for install/update; user must uninstall apps first. */
+    DeviceOutOfMemory = 10503,
     /** 0x6a80 Invalid data — observed on blindSignTransactionFallback when the
      *  user has not enabled Blind signing on the device. */
     EvmBlindSigningRequired = 11000,
@@ -141,13 +145,22 @@ interface DeviceCapabilities {
 }
 interface DeviceInfo {
     vendor: VendorType;
+    /** Machine model id (e.g. "nanoX"). */
     model: string;
+    /** Human-readable model name (e.g. "Ledger Nano X"). */
+    modelName?: string;
     firmwareVersion: string;
     deviceId: string;
     connectId: string;
     label?: string;
     connectionType: ConnectionType;
     battery?: number;
+    /** BLE signal strength (BLE only). */
+    rssi?: number | null;
+    /** BLE connectable flag (BLE only). */
+    isConnectable?: boolean | null;
+    /** USB serial number (USB only). */
+    serialNumber?: string;
     /** Device capabilities — varies by vendor, model, and connection type */
     capabilities?: DeviceCapabilities;
 }
@@ -156,95 +169,321 @@ interface DeviceTarget {
     deviceId: string;
 }
 
-interface EvmGetAddressParams {
-    path: string;
-    showOnDevice?: boolean;
-    chainId?: number;
+interface QrDisplayData {
+    urType: string;
+    urData: string;
+    animated: boolean;
 }
-interface EvmAddress {
-    address: string;
-    path: string;
-    /** Device-reported secp256k1 public key; populated when the transport exposes it. */
-    publicKey?: string;
+interface QrResponseData {
+    urType: string;
+    urData: string;
 }
-interface EvmSignTxParams {
-    path: string;
+
+declare const UI_EVENT = "UI_EVENT";
+declare const UI_REQUEST: {
+    readonly REQUEST_PIN: "ui-request-pin";
+    readonly REQUEST_PASSPHRASE: "ui-request-passphrase";
+    readonly REQUEST_PASSPHRASE_ON_DEVICE: "ui-request-passphrase-on-device";
+    readonly REQUEST_BUTTON: "ui-request-button";
+    readonly REQUEST_QR_DISPLAY: "ui-request-qr-display";
+    readonly REQUEST_QR_SCAN: "ui-request-qr-scan";
+    readonly REQUEST_DEVICE_PERMISSION: "ui-request-device-permission";
+    readonly REQUEST_SELECT_DEVICE: "ui-request-select-device";
+    readonly REQUEST_DEVICE_CONNECT: "ui-request-device-connect";
+    readonly REQUEST_BTC_HIGH_INDEX_CONFIRM: "ui-request-btc-high-index-confirm";
+    readonly REQUEST_INSTALL_APP: "ui-request-install-app";
+    readonly CLOSE_UI_WINDOW: "ui-close";
+    readonly DEVICE_PROGRESS: "ui-device_progress";
+    readonly FIRMWARE_PROGRESS: "ui-firmware-progress";
+    readonly FIRMWARE_TIP: "ui-firmware-tip";
+};
+declare const UI_RESPONSE: {
+    readonly RECEIVE_PIN: "receive-pin";
+    readonly RECEIVE_PASSPHRASE: "receive-passphrase";
+    readonly RECEIVE_PASSPHRASE_ON_DEVICE: "receive-passphrase-on-device";
+    readonly RECEIVE_QR_RESPONSE: "receive-qr-response";
+    readonly RECEIVE_SELECT_DEVICE: "receive-select-device";
+    readonly RECEIVE_DEVICE_CONNECT: "receive-device-connect";
+    readonly RECEIVE_DEVICE_PERMISSION: "receive-device-permission";
+    readonly RECEIVE_BTC_HIGH_INDEX_CONFIRM: "receive-btc-high-index-confirm";
+    readonly RECEIVE_INSTALL_APP: "receive-install-app";
+    readonly CANCEL: "cancel";
+};
+type DevicePermissionDeniedReason = 'bluetoothTurnedOff' | 'permissionDenied' | (string & Record<never, never>);
+type DevicePermissionResponse = {
+    granted: boolean;
+    reason?: DevicePermissionDeniedReason;
+    message?: string;
+};
+type UiResponseEvent = {
+    type: typeof UI_RESPONSE.RECEIVE_PIN;
+    payload: string;
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_PASSPHRASE;
+    payload: {
+        value: string;
+        passphraseOnDevice?: boolean;
+        save?: boolean;
+    };
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_PASSPHRASE_ON_DEVICE;
+    payload?: undefined;
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_QR_RESPONSE;
+    payload: QrResponseData;
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_SELECT_DEVICE;
+    payload: {
+        sdkConnectId: string;
+    };
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_DEVICE_CONNECT;
+    payload: {
+        confirmed: boolean;
+    };
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_DEVICE_PERMISSION;
+    payload: DevicePermissionResponse;
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_BTC_HIGH_INDEX_CONFIRM;
+    payload: {
+        confirmed: boolean;
+    };
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_INSTALL_APP;
+    payload: {
+        confirmed: boolean;
+    };
+} | {
+    type: typeof UI_RESPONSE.CANCEL;
+    payload?: undefined;
+};
+
+/**
+ * Minimal device info returned during discovery (searchDevices).
+ * At scan time, full DeviceInfo fields like firmwareVersion are not yet available.
+ */
+interface ConnectorDevice {
+    connectId: string;
+    deviceId: string;
+    name: string;
+    /** Machine model id (e.g. "nanoX"). */
+    model?: string;
+    /** Human-readable model name (e.g. "Ledger Nano X"). */
+    modelName?: string;
+    /** BLE signal strength (BLE only). */
+    rssi?: number | null;
+    /** BLE connectable flag (BLE only). */
+    isConnectable?: boolean | null;
+    /** USB serial number (USB only). */
+    serialNumber?: string;
+    /** Device capabilities — available from scan time */
+    capabilities?: DeviceCapabilities;
+}
+interface ConnectorSession {
+    sessionId: string;
+    deviceInfo: DeviceInfo;
+}
+/**
+ * Vendor-agnostic bag of extra error fields. Known keys are documented for
+ * discoverability; the index signature keeps it open so any connector can
+ * carry vendor-specific data without losing it across the bridge.
+ */
+interface ConnectorErrorParams {
+    /** Vendor SDK error tag (e.g. Ledger DMK `_tag`). */
+    _tag?: string;
+    /** App involved, e.g. the Ledger app being opened/installed. */
+    appName?: string;
+    /** Transport / APDU status code (string or number depending on vendor). */
+    statusCode?: unknown;
     /**
-     * RLP-serialized transaction hex (0x-prefixed or plain).
-     * When provided, the connector uses this directly instead of individual fields.
-     * Required for Ledger; Trezor may use individual fields instead.
+     * Shallow snapshot of a nested cause. A raw Error does not survive JSON
+     * serialization (its `message`/`stack` are non-enumerable), so recovery
+     * predicates that recurse into a cause get this plain-object copy instead.
      */
-    serializedTx?: string;
-    /** Contract address or recipient. Optional for contract deployment transactions. */
-    to?: string;
-    value?: string;
-    chainId?: number;
-    nonce?: string;
-    gasLimit?: string;
-    gasPrice?: string;
-    maxFeePerGas?: string;
-    maxPriorityFeePerGas?: string;
-    accessList?: Array<{
-        address: string;
-        storageKeys: string[];
-    }>;
-    data?: string;
-}
-interface EvmSignedTx {
-    /** Recovery id as `0x`-prefixed hex string. */
-    v: string;
-    /** ECDSA `r` value as `0x`-prefixed, zero-padded 64-char hex string (32 bytes). */
-    r: string;
-    /** ECDSA `s` value as `0x`-prefixed, zero-padded 64-char hex string (32 bytes). */
-    s: string;
-    serializedTx?: string;
+    originalError?: {
+        message?: string;
+        code?: number;
+        errorCode?: string;
+        statusCode?: unknown;
+        _tag?: string;
+    };
+    [key: string]: unknown;
 }
-interface EvmSignMsgParams {
-    path: string;
+interface ConnectorSerializedError {
     message: string;
-    hex?: boolean;
-}
-type EvmSignTypedDataParams = EvmSignTypedDataFull | EvmSignTypedDataHash;
-interface EvmSignTypedDataFull {
-    path: string;
-    /** Defaults to `'full'` when omitted. */
-    mode?: 'full';
-    data: {
-        domain: EIP712Domain;
-        types: Record<string, Array<{
-            name: string;
-            type: string;
-        }>>;
-        primaryType: string;
-        message: Record<string, unknown>;
-    };
-    metamaskV4Compat?: boolean;
+    code?: number;
+    errorCode?: string;
+    params?: ConnectorErrorParams;
 }
-interface EvmSignTypedDataHash {
-    path: string;
-    mode: 'hash';
-    domainSeparatorHash: string;
-    messageHash: string;
+type ConnectorCallResult = {
+    success: true;
+    payload: unknown;
+} | {
+    success: false;
+    error: ConnectorSerializedError;
+};
+type ConnectorEventType = 'device-connect' | 'device-disconnect' | 'ui-request' | 'ui-event';
+/**
+ * Interaction event types emitted via 'ui-event'.
+ * These map to user-facing prompts (confirm on device, open app, etc.).
+ */
+declare enum EConnectorInteraction {
+    /** Adapter is actively searching for the device (no session yet) */
+    Searching = "searching",
+    /** Device requires user to open a specific app */
+    ConfirmOpenApp = "confirm-open-app",
+    /** Device requires user to unlock */
+    UnlockDevice = "unlock-device",
+    /** Device needs user to confirm on device (sign, verify, etc.) */
+    ConfirmOnDevice = "confirm-on-device",
+    /** Previous interaction completed — clear UI prompt */
+    InteractionComplete = "interaction-complete",
+    /**
+     * OS-level Ledger app install progress. `progress` is a 0..1 fraction
+     * reported by DMK's InstallOrUpdateAppsDeviceAction. Emitted from inside
+     * the connector so the progress callback ref never has to cross the
+     * IHardwareBridge boundary.
+     */
+    AppInstallProgress = "app-install-progress"
 }
-interface EIP712Domain {
-    name?: string;
-    version?: string;
-    chainId?: number;
-    verifyingContract?: string;
-    salt?: string;
-    [key: string]: unknown;
+type ConnectorUiEvent = {
+    type: EConnectorInteraction.Searching;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.ConfirmOpenApp;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.UnlockDevice;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.ConfirmOnDevice;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.InteractionComplete;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.AppInstallProgress;
+    payload: {
+        sessionId: string;
+        appName: string;
+        progress: number;
+    };
+};
+interface ConnectorEventMap {
+    'device-connect': {
+        device: ConnectorDevice;
+    };
+    'device-disconnect': {
+        connectId: string;
+    };
+    'ui-request': {
+        type: string;
+        payload?: unknown;
+    };
+    'ui-event': ConnectorUiEvent;
 }
-interface EvmSignature {
-    /** `0x`-prefixed hex string (r + s + v). */
-    signature: string;
-    address?: string;
+interface IConnector {
+    /** Physical connection type this connector uses. Fixed at construction. */
+    readonly connectionType: ConnectionType;
+    searchDevices(): Promise<ConnectorDevice[]>;
+    connect(deviceId?: string): Promise<ConnectorSession>;
+    disconnect(sessionId: string): Promise<void>;
+    call(sessionId: string, method: string, params: unknown): Promise<ConnectorCallResult>;
+    cancel(sessionId: string): Promise<void>;
+    /** Send a UI response (e.g. PIN, passphrase) to the device. */
+    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;
 }
-interface IEvmMethods {
-    evmGetAddress(connectId: string, deviceId: string, params: EvmGetAddressParams): 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>>;
+interface IHardwareBridge {
+    searchDevices(params: {
+        vendor: VendorType;
+    }): Promise<ConnectorDevice[]>;
+    connect(params: {
+        vendor: VendorType;
+        deviceId?: string;
+    }): Promise<ConnectorSession>;
+    disconnect(params: {
+        vendor: VendorType;
+        sessionId: string;
+    }): Promise<void>;
+    call(params: {
+        vendor: VendorType;
+        sessionId: string;
+        method: string;
+        callParams: unknown;
+    }): Promise<ConnectorCallResult>;
+    cancel(params: {
+        vendor: VendorType;
+        sessionId: string;
+    }): Promise<void>;
+    uiResponse(params: {
+        vendor: VendorType;
+        response: UiResponseEvent;
+    }): void;
+    reset(params: {
+        vendor: VendorType;
+    }): void;
+    /** Register an event handler for connector events forwarded across the bridge. */
+    onEvent(params: {
+        vendor: VendorType;
+    }, handler: (event: {
+        type: ConnectorEventType;
+        data: unknown;
+    }) => void): void;
+    /** Unregister a previously registered event handler. */
+    offEvent(params: {
+        vendor: VendorType;
+    }, handler: (event: {
+        type: ConnectorEventType;
+        data: unknown;
+    }) => void): void;
 }
+/**
+ * Adapt an IHardwareBridge (multi-vendor backend) into a single-vendor IConnector.
+ * Every IConnector method becomes a transparent forward to bridge.<method>({ vendor, ... }).
+ * Events are forwarded via bridge.onEvent / offEvent.
+ *
+ * Use this anywhere the actual hardware lives behind a process / context boundary
+ * (Electron main, extension background, native module, worker, iframe).
+ */
+declare function createBridgedConnector(vendor: VendorType, connectionType: ConnectionType, bridge: IHardwareBridge): IConnector;
+/**
+ * Flatten a thrown error into the cross-boundary-safe `ConnectorSerializedError`
+ * shape. `message`/`code`/`errorCode` are lifted to the top level; every other
+ * own-enumerable field is copied into `params` so NO domain data is lost when
+ * the result crosses a host bridge (which may run thrown errors through a
+ * field whitelist). A nested `originalError` is shallow-snapshotted because a
+ * raw Error does not survive JSON serialization.
+ */
+declare function serializeConnectorError(err: unknown): ConnectorSerializedError;
+/**
+ * Inverse of `serializeConnectorError`: rebuild a flat Error instance, lifting
+ * `params.*` back to own-properties so existing throw-based classifiers/recovery
+ * logic (which read `err._tag` / `err.code` / `err.appName` / …) keep working
+ * unchanged. The Result shape stays confined to the connector boundary.
+ */
+declare function rehydrateConnectorError(error: ConnectorSerializedError): Error;
+
+declare const DEVICE_EVENT = "DEVICE_EVENT";
+/** Events originating from the hardware device. */
+declare const DEVICE: {
+    readonly CONNECT: "device-connect";
+    readonly DISCONNECT: "device-disconnect";
+    readonly CHANGED: "device-changed";
+};
 
 interface BtcGetAddressParams {
     path: string;
@@ -338,12 +577,12 @@ interface BtcSignature {
     address?: string;
 }
 interface IBtcMethods {
-    btcGetAddress(connectId: string, deviceId: string, params: BtcGetAddressParams): 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<{
+    btcGetAddress(connectId: string, deviceId: string, params: BtcGetAddressParams, commonParams?: ICommonCallParams): Promise<Response<BtcAddress>>;
+    btcGetPublicKey(connectId: string, deviceId: string, params: BtcGetPublicKeyParams, commonParams?: ICommonCallParams): Promise<Response<BtcPublicKey>>;
+    btcSignTransaction(connectId: string, deviceId: string, params: BtcSignTxParams, commonParams?: ICommonCallParams): Promise<Response<BtcSignedTx>>;
+    btcSignPsbt(connectId: string, deviceId: string, params: BtcSignPsbtParams, commonParams?: ICommonCallParams): Promise<Response<BtcSignedPsbt>>;
+    btcSignMessage(connectId: string, deviceId: string, params: BtcSignMsgParams, commonParams?: ICommonCallParams): Promise<Response<BtcSignature>>;
+    btcGetMasterFingerprint(connectId: string, deviceId: string, commonParams?: ICommonCallParams): Promise<Response<{
         masterFingerprint: string;
     }>>;
 }
@@ -384,9 +623,9 @@ interface SolSignature {
     signature: string;
 }
 interface ISolMethods {
-    solGetAddress(connectId: string, deviceId: string, params: SolGetAddressParams): Promise<Response<SolAddress>>;
-    solSignTransaction(connectId: string, deviceId: string, params: SolSignTxParams): Promise<Response<SolSignedTx>>;
-    solSignMessage(connectId: string, deviceId: string, params: SolSignMsgParams): Promise<Response<SolSignature>>;
+    solGetAddress(connectId: string, deviceId: string, params: SolGetAddressParams, commonParams?: ICommonCallParams): Promise<Response<SolAddress>>;
+    solSignTransaction(connectId: string, deviceId: string, params: SolSignTxParams, commonParams?: ICommonCallParams): Promise<Response<SolSignedTx>>;
+    solSignMessage(connectId: string, deviceId: string, params: SolSignMsgParams, commonParams?: ICommonCallParams): Promise<Response<SolSignature>>;
 }
 
 interface TronGetAddressParams {
@@ -415,121 +654,30 @@ interface TronSignMsgParams {
 interface TronSignature {
     /** 65-byte hex-encoded signature (no 0x prefix) */
     signature: string;
-}
-interface ITronMethods {
-    tronGetAddress(connectId: string, deviceId: string, params: TronGetAddressParams): Promise<Response<TronAddress>>;
-    tronSignTransaction(connectId: string, deviceId: string, params: TronSignTxParams): Promise<Response<TronSignedTx>>;
-    tronSignMessage(connectId: string, deviceId: string, params: TronSignMsgParams): Promise<Response<TronSignature>>;
-}
-
-interface QrDisplayData {
-    urType: string;
-    urData: string;
-    animated: boolean;
-}
-interface QrResponseData {
-    urType: string;
-    urData: string;
-}
-
-/**
- * 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;
-
-declare const DEVICE_EVENT = "DEVICE_EVENT";
-/** Events originating from the hardware device. */
-declare const DEVICE: {
-    readonly CONNECT: "device-connect";
-    readonly DISCONNECT: "device-disconnect";
-    readonly CHANGED: "device-changed";
-};
-
-declare const UI_EVENT = "UI_EVENT";
-declare const UI_REQUEST: {
-    readonly REQUEST_PIN: "ui-request-pin";
-    readonly REQUEST_PASSPHRASE: "ui-request-passphrase";
-    readonly REQUEST_PASSPHRASE_ON_DEVICE: "ui-request-passphrase-on-device";
-    readonly REQUEST_BUTTON: "ui-request-button";
-    readonly REQUEST_QR_DISPLAY: "ui-request-qr-display";
-    readonly REQUEST_QR_SCAN: "ui-request-qr-scan";
-    readonly REQUEST_DEVICE_PERMISSION: "ui-request-device-permission";
-    readonly REQUEST_SELECT_DEVICE: "ui-request-select-device";
-    readonly REQUEST_DEVICE_CONNECT: "ui-request-device-connect";
-    readonly REQUEST_BTC_HIGH_INDEX_CONFIRM: "ui-request-btc-high-index-confirm";
-    readonly CLOSE_UI_WINDOW: "ui-close";
-    readonly DEVICE_PROGRESS: "ui-device_progress";
-    readonly FIRMWARE_PROGRESS: "ui-firmware-progress";
-    readonly FIRMWARE_TIP: "ui-firmware-tip";
-};
-declare const UI_RESPONSE: {
-    readonly RECEIVE_PIN: "receive-pin";
-    readonly RECEIVE_PASSPHRASE: "receive-passphrase";
-    readonly RECEIVE_PASSPHRASE_ON_DEVICE: "receive-passphrase-on-device";
-    readonly RECEIVE_QR_RESPONSE: "receive-qr-response";
-    readonly RECEIVE_SELECT_DEVICE: "receive-select-device";
-    readonly RECEIVE_DEVICE_CONNECT: "receive-device-connect";
-    readonly RECEIVE_DEVICE_PERMISSION: "receive-device-permission";
-    readonly RECEIVE_BTC_HIGH_INDEX_CONFIRM: "receive-btc-high-index-confirm";
-    readonly CANCEL: "cancel";
-};
-type DevicePermissionDeniedReason = 'bluetoothTurnedOff' | 'permissionDenied' | (string & Record<never, never>);
-type DevicePermissionResponse = {
-    granted: boolean;
-    reason?: DevicePermissionDeniedReason;
-    message?: string;
-};
-type UiResponseEvent = {
-    type: typeof UI_RESPONSE.RECEIVE_PIN;
-    payload: string;
-} | {
-    type: typeof UI_RESPONSE.RECEIVE_PASSPHRASE;
-    payload: {
-        value: string;
-        passphraseOnDevice?: boolean;
-        save?: boolean;
-    };
-} | {
-    type: typeof UI_RESPONSE.RECEIVE_PASSPHRASE_ON_DEVICE;
-    payload?: undefined;
-} | {
-    type: typeof UI_RESPONSE.RECEIVE_QR_RESPONSE;
-    payload: QrResponseData;
-} | {
-    type: typeof UI_RESPONSE.RECEIVE_SELECT_DEVICE;
-    payload: {
-        sdkConnectId: string;
-    };
-} | {
-    type: typeof UI_RESPONSE.RECEIVE_DEVICE_CONNECT;
-    payload: {
-        confirmed: boolean;
-    };
-} | {
-    type: typeof UI_RESPONSE.RECEIVE_DEVICE_PERMISSION;
-    payload: DevicePermissionResponse;
-} | {
-    type: typeof UI_RESPONSE.RECEIVE_BTC_HIGH_INDEX_CONFIRM;
-    payload: {
-        confirmed: boolean;
-    };
-} | {
-    type: typeof UI_RESPONSE.CANCEL;
-    payload?: undefined;
-};
+}
+interface ITronMethods {
+    tronGetAddress(connectId: string, deviceId: string, params: TronGetAddressParams, commonParams?: ICommonCallParams): Promise<Response<TronAddress>>;
+    tronSignTransaction(connectId: string, deviceId: string, params: TronSignTxParams, commonParams?: ICommonCallParams): Promise<Response<TronSignedTx>>;
+    tronSignMessage(connectId: string, deviceId: string, params: TronSignMsgParams, commonParams?: ICommonCallParams): 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: {
@@ -540,146 +688,35 @@ declare const SDK: {
 };
 
 /**
- * Minimal device info returned during discovery (searchDevices).
- * At scan time, full DeviceInfo fields like firmwareVersion are not yet available.
- */
-interface ConnectorDevice {
-    connectId: string;
-    deviceId: string;
-    name: string;
-    model?: string;
-    /** Device capabilities — available from scan time */
-    capabilities?: DeviceCapabilities;
-}
-interface ConnectorSession {
-    sessionId: string;
-    deviceInfo: DeviceInfo;
-}
-type ConnectorEventType = 'device-connect' | 'device-disconnect' | 'ui-request' | 'ui-event';
-/**
- * Interaction event types emitted via 'ui-event'.
- * These map to user-facing prompts (confirm on device, open app, etc.).
+ * Wallet-level `ui-event` variants. Same shape as `ConnectorUiEvent` except
+ * the AppInstallProgress variant's payload is re-keyed by the adapter from
+ * connector-internal `sessionId` to the public `connectId`.
  */
-declare enum EConnectorInteraction {
-    /** Adapter is actively searching for the device (no session yet) */
-    Searching = "searching",
-    /** Device requires user to open a specific app */
-    ConfirmOpenApp = "confirm-open-app",
-    /** Device requires user to unlock */
-    UnlockDevice = "unlock-device",
-    /** Device needs user to confirm on device (sign, verify, etc.) */
-    ConfirmOnDevice = "confirm-on-device",
-    /** Previous interaction completed — clear UI prompt */
-    InteractionComplete = "interaction-complete"
-}
-type ConnectorUiEvent = {
-    type: EConnectorInteraction.Searching;
-    payload: {
-        sessionId: string;
-    };
-} | {
-    type: EConnectorInteraction.ConfirmOpenApp;
-    payload: {
-        sessionId: string;
-    };
-} | {
-    type: EConnectorInteraction.UnlockDevice;
-    payload: {
-        sessionId: string;
-    };
-} | {
-    type: EConnectorInteraction.ConfirmOnDevice;
-    payload: {
-        sessionId: string;
-    };
-} | {
-    type: EConnectorInteraction.InteractionComplete;
+type HardwareUiEvent = Exclude<ConnectorUiEvent, {
+    type: EConnectorInteraction.AppInstallProgress;
+}> | {
+    type: EConnectorInteraction.AppInstallProgress;
     payload: {
-        sessionId: string;
-    };
-};
-interface ConnectorEventMap {
-    'device-connect': {
-        device: ConnectorDevice;
-    };
-    'device-disconnect': {
         connectId: string;
+        appName: string;
+        progress: number;
     };
-    'ui-request': {
-        type: string;
-        payload?: unknown;
-    };
-    'ui-event': ConnectorUiEvent;
-}
-interface IConnector {
-    /** Physical connection type this connector uses. Fixed at construction. */
-    readonly connectionType: ConnectionType;
-    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>;
-    /** Send a UI response (e.g. PIN, passphrase) to the device. */
-    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;
-}
-interface IHardwareBridge {
-    searchDevices(params: {
-        vendor: VendorType;
-    }): Promise<ConnectorDevice[]>;
-    connect(params: {
-        vendor: VendorType;
-        deviceId?: string;
-    }): Promise<ConnectorSession>;
-    disconnect(params: {
-        vendor: VendorType;
-        sessionId: string;
-    }): Promise<void>;
-    call(params: {
-        vendor: VendorType;
-        sessionId: string;
-        method: string;
-        callParams: unknown;
-    }): Promise<unknown>;
-    cancel(params: {
-        vendor: VendorType;
-        sessionId: string;
-    }): Promise<void>;
-    uiResponse(params: {
-        vendor: VendorType;
-        response: UiResponseEvent;
-    }): void;
-    reset(params: {
-        vendor: VendorType;
-    }): void;
-    /** Register an event handler for connector events forwarded across the bridge. */
-    onEvent(params: {
-        vendor: VendorType;
-    }, handler: (event: {
-        type: ConnectorEventType;
-        data: unknown;
-    }) => void): void;
-    /** Unregister a previously registered event handler. */
-    offEvent(params: {
-        vendor: VendorType;
-    }, handler: (event: {
-        type: ConnectorEventType;
-        data: unknown;
-    }) => void): void;
-}
+};
+type ChainCapability = 'evm' | 'btc' | 'sol' | 'tron';
 /**
- * Adapt an IHardwareBridge (multi-vendor backend) into a single-vendor IConnector.
- * Every IConnector method becomes a transparent forward to bridge.<method>({ vendor, ... }).
- * Events are forwarded via bridge.onEvent / offEvent.
- *
- * Use this anywhere the actual hardware lives behind a process / context boundary
- * (Electron main, extension background, native module, worker, iframe).
+ * 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.
  */
-declare function createBridgedConnector(vendor: VendorType, connectionType: ConnectionType, bridge: IHardwareBridge): IConnector;
-
-type ChainCapability = 'evm' | 'btc' | 'sol' | 'tron';
+interface ICommonCallParams {
+    /**
+     * 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;
+}
 interface PassphraseResponse {
     passphrase: string;
     /** If true, passphrase will be entered on the device. `passphrase` field is ignored. */
@@ -761,6 +798,12 @@ type UiRequestEvent = {
          */
         message: string;
     };
+} | {
+    type: typeof UI_REQUEST.REQUEST_INSTALL_APP;
+    payload: {
+        vendor: string;
+        appName: string;
+    };
 } | {
     type: typeof UI_REQUEST.CLOSE_UI_WINDOW;
     payload: Record<string, never>;
@@ -787,7 +830,7 @@ type SdkEvent = {
         connectId: string;
     };
 };
-type HardwareEvent = DeviceEvent | UiRequestEvent | SdkEvent | ConnectorUiEvent;
+type HardwareEvent = DeviceEvent | UiRequestEvent | SdkEvent | HardwareUiEvent;
 type DeviceEventListener = (event: HardwareEvent) => void;
 /**
  * Type-safe event map for IHardwareWallet.on / .off.
@@ -796,7 +839,7 @@ type DeviceEventListener = (event: HardwareEvent) => void;
  * and the value is the narrowed event object the listener will receive.
  */
 interface HardwareEventMap {
-    'ui-event': ConnectorUiEvent;
+    'ui-event': HardwareUiEvent;
     [DEVICE.CONNECT]: {
         type: typeof DEVICE.CONNECT;
         payload: DeviceInfo;
@@ -879,6 +922,13 @@ interface HardwareEventMap {
             accountIndex: number;
         };
     };
+    [UI_REQUEST.REQUEST_INSTALL_APP]: {
+        type: typeof UI_REQUEST.REQUEST_INSTALL_APP;
+        payload: {
+            vendor: string;
+            appName: string;
+        };
+    };
     [UI_REQUEST.CLOSE_UI_WINDOW]: {
         type: typeof UI_REQUEST.CLOSE_UI_WINDOW;
         payload: Record<string, never>;
@@ -916,7 +966,7 @@ interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, I
     dispose(): Promise<void>;
     getAvailableTransports(): TransportType[];
     switchTransport(type: TransportType): Promise<void>;
-    searchDevices(): Promise<DeviceInfo[]>;
+    searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
     connectDevice(connectId: string): Promise<Response<string>>;
     disconnectDevice(connectId: string): Promise<void>;
     getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
@@ -940,6 +990,106 @@ interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, I
     off<K extends keyof HardwareEventMap>(event: K, listener: (event: HardwareEventMap[K]) => void): void;
     off(event: string, listener: DeviceEventListener): void;
 }
+interface SearchDevicesOptions {
+    /**
+     * Clear cached adapter sessions before scanning.
+     *
+     * Use this for an explicit "search/add another device" flow on transports
+     * whose connectId is not stable, such as Ledger WebHID. Normal refresh scans
+     * should leave this false so an active session can still be reused.
+     */
+    resetSession?: boolean;
+}
+
+interface EvmGetAddressParams {
+    path: string;
+    showOnDevice?: boolean;
+    chainId?: number;
+}
+interface EvmAddress {
+    address: string;
+    path: string;
+    /** Device-reported secp256k1 public key; populated when the transport exposes it. */
+    publicKey?: string;
+}
+interface EvmSignTxParams {
+    path: string;
+    /**
+     * RLP-serialized transaction hex (0x-prefixed or plain).
+     * When provided, the connector uses this directly instead of individual fields.
+     * Required for Ledger; Trezor may use individual fields instead.
+     */
+    serializedTx?: string;
+    /** Contract address or recipient. Optional for contract deployment transactions. */
+    to?: string;
+    value?: string;
+    chainId?: number;
+    nonce?: string;
+    gasLimit?: string;
+    gasPrice?: string;
+    maxFeePerGas?: string;
+    maxPriorityFeePerGas?: string;
+    accessList?: Array<{
+        address: string;
+        storageKeys: string[];
+    }>;
+    data?: string;
+}
+interface EvmSignedTx {
+    /** Recovery id as `0x`-prefixed hex string. */
+    v: string;
+    /** ECDSA `r` value as `0x`-prefixed, zero-padded 64-char hex string (32 bytes). */
+    r: string;
+    /** ECDSA `s` value as `0x`-prefixed, zero-padded 64-char hex string (32 bytes). */
+    s: string;
+    serializedTx?: string;
+}
+interface EvmSignMsgParams {
+    path: string;
+    message: string;
+    hex?: boolean;
+}
+type EvmSignTypedDataParams = EvmSignTypedDataFull | EvmSignTypedDataHash;
+interface EvmSignTypedDataFull {
+    path: string;
+    /** Defaults to `'full'` when omitted. */
+    mode?: 'full';
+    data: {
+        domain: EIP712Domain;
+        types: Record<string, Array<{
+            name: string;
+            type: string;
+        }>>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    };
+    metamaskV4Compat?: boolean;
+}
+interface EvmSignTypedDataHash {
+    path: string;
+    mode: 'hash';
+    domainSeparatorHash: string;
+    messageHash: string;
+}
+interface EIP712Domain {
+    name?: string;
+    version?: string;
+    chainId?: number;
+    verifyingContract?: string;
+    salt?: string;
+    [key: string]: unknown;
+}
+interface EvmSignature {
+    /** `0x`-prefixed hex string (r + s + v). */
+    signature: string;
+    address?: string;
+}
+interface IEvmMethods {
+    evmGetAddress(connectId: string, deviceId: string, params: EvmGetAddressParams, commonParams?: ICommonCallParams): Promise<Response<EvmAddress>>;
+    evmSignTransaction(connectId: string, deviceId: string, params: EvmSignTxParams, commonParams?: ICommonCallParams): Promise<Response<EvmSignedTx>>;
+    evmSignMessage(connectId: string, deviceId: string, params: EvmSignMsgParams, commonParams?: ICommonCallParams): Promise<Response<EvmSignature>>;
+    evmSignTypedData(connectId: string, deviceId: string, params: EvmSignTypedDataParams, commonParams?: ICommonCallParams): Promise<Response<EvmSignature>>;
+}
 
 /**
  * Low-level device descriptor from Transport layer.
@@ -952,11 +1102,13 @@ interface DeviceDescriptor {
     product?: number;
     /** USB vendor ID */
     vendor?: number;
-    /** Device type/model identifier */
+    /** Device type/model identifier (e.g. "nanoX"). */
     type?: string;
+    /** Human-readable model name (e.g. "Ledger Nano X"). */
+    modelName?: string;
     /** Human-readable display name from the transport layer. */
     name?: string;
-    /** Stable Ledger BLE identifier from the raw RN BLE `Device.name` field. */
+    /** Raw Ledger BLE advertisement name from RN BLE `Device.name`, when available. */
     bleName?: string;
     /** User-visible Ledger BLE local name from the raw RN BLE `Device.localName` field. */
     localName?: string;
@@ -964,6 +1116,14 @@ interface DeviceDescriptor {
     transport?: string;
     /** BLE RSSI when provided by the transport scanner. */
     rssi?: number | null;
+    /** BLE advertised service UUIDs, when provided by the scanner. */
+    serviceUUIDs?: string[] | null;
+    /** BLE connectable flag, when provided by the scanner. */
+    isConnectable?: boolean | null;
+    /** USB product name, when provided by the transport. */
+    productName?: string;
+    /** USB serial number, when provided by the transport. */
+    serialNumber?: string;
 }
 interface DeviceConnectEvent {
     type: 'device-connected';
@@ -1107,4 +1267,4 @@ declare function batchCall<TParam, TResult>(params: TParam[], callFn: (p: TParam
     total: number;
 }) => void): Promise<Response<TResult[]>>;
 
-export { type ActiveJobInfo, type BtcAddress, type BtcGetAddressParams, type BtcGetPublicKeyParams, 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 ConnectorDevice, type ConnectorEventMap, type ConnectorEventType, type ConnectorSession, type ConnectorUiEvent, DEVICE, DEVICE_EVENT, type DeviceCapabilities, type DeviceChangeEvent, type DeviceConnectEvent, type DeviceDescriptor, type DeviceDisconnectEvent, type DeviceEvent, type DeviceEventListener, type DeviceInfo, DeviceJobQueue, type DevicePermissionDeniedReason, type DevicePermissionResponse, type DeviceTarget, EConnectorInteraction, type EIP712Domain, type EvmAddress, type EvmGetAddressParams, type EvmSignMsgParams, type EvmSignTxParams, type EvmSignTypedDataFull, type EvmSignTypedDataHash, type EvmSignTypedDataParams, type EvmSignature, type EvmSignedTx, type Failure, HardwareErrorCode, type HardwareEvent, type HardwareEventMap, type IBtcMethods, type IConnector, type IEvmMethods, type IHardwareBridge, type IHardwareWallet, type ISolMethods, type ITronMethods, type JobOptions, ORPHAN_ELIGIBLE_ERROR_CODES, type PassphraseResponse, type QrDisplayData, type QrResponseData, type Response, SDK, type SdkEvent, type SolAddress, type SolGetAddressParams, type SolSignMsgParams, type SolSignTxParams, type SolSignature, type SolSignedTx, type Success, type TransportType, type TronAddress, type TronGetAddressParams, type TronSignMsgParams, type TronSignTxParams, type TronSignature, type TronSignedTx, TypedEventEmitter, UI_EVENT, UI_REQUEST, UI_REQUEST_CANCELLED_TAG, UI_REQUEST_DEFAULT_TIMEOUT_MS, UI_REQUEST_PREEMPTED_TAG, UI_REQUEST_TIMEOUT_TAG, UI_RESPONSE, type UiRequestEvent, UiRequestRegistry, type UiResponseEvent, type VendorType, batchCall, bytesToHex, compareSemver, createBridgedConnector, deriveDeviceFingerprint, enrichErrorMessage, ensure0x, failure, hexToBytes, padHex64, stripHex, success };
+export { type ActiveJobInfo, type BtcAddress, type BtcGetAddressParams, type BtcGetPublicKeyParams, 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 ConnectorDevice, type ConnectorErrorParams, type ConnectorEventMap, type ConnectorEventType, type ConnectorSerializedError, type ConnectorSession, type ConnectorUiEvent, DEVICE, DEVICE_EVENT, type DeviceCapabilities, type DeviceChangeEvent, type DeviceConnectEvent, type DeviceDescriptor, type DeviceDisconnectEvent, type DeviceEvent, type DeviceEventListener, type DeviceInfo, DeviceJobQueue, type DevicePermissionDeniedReason, type DevicePermissionResponse, type DeviceTarget, EConnectorInteraction, type EIP712Domain, type EvmAddress, type EvmGetAddressParams, type EvmSignMsgParams, type EvmSignTxParams, type EvmSignTypedDataFull, type EvmSignTypedDataHash, type EvmSignTypedDataParams, type EvmSignature, type EvmSignedTx, type Failure, HardwareErrorCode, type HardwareEvent, type HardwareEventMap, type HardwareUiEvent, type IBtcMethods, type ICommonCallParams, type IConnector, type IEvmMethods, type IHardwareBridge, type IHardwareWallet, type ISolMethods, type ITronMethods, type JobOptions, ORPHAN_ELIGIBLE_ERROR_CODES, type PassphraseResponse, type QrDisplayData, type QrResponseData, type Response, SDK, type SdkEvent, type SearchDevicesOptions, type SolAddress, type SolGetAddressParams, type SolSignMsgParams, type SolSignTxParams, type SolSignature, type SolSignedTx, type Success, type TransportType, type TronAddress, type TronGetAddressParams, type TronSignMsgParams, type TronSignTxParams, type TronSignature, type TronSignedTx, TypedEventEmitter, UI_EVENT, UI_REQUEST, UI_REQUEST_CANCELLED_TAG, UI_REQUEST_DEFAULT_TIMEOUT_MS, UI_REQUEST_PREEMPTED_TAG, UI_REQUEST_TIMEOUT_TAG, UI_RESPONSE, type UiRequestEvent, UiRequestRegistry, type UiResponseEvent, type VendorType, batchCall, bytesToHex, compareSemver, createBridgedConnector, deriveDeviceFingerprint, enrichErrorMessage, ensure0x, failure, hexToBytes, padHex64, rehydrateConnectorError, serializeConnectorError, stripHex, success };