@bytezhang/hardware-wallet-core 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,822 @@
+declare enum HardwareErrorCode {
+    UnknownError = 0,
+    DeviceNotFound = 1,
+    DeviceDisconnected = 2,
+    UserRejected = 3,
+    DeviceBusy = 4,
+    FirmwareUpdateRequired = 5,
+    AppNotOpen = 6,
+    InvalidParams = 7,
+    TransportError = 8,
+    OperationTimeout = 9,
+    MethodNotSupported = 10,
+    PinInvalid = 5520,
+    PinCancelled = 5521,
+    PassphraseRejected = 5522,
+    DeviceLocked = 5530,
+    DeviceNotInitialized = 5531,
+    DeviceInBootloader = 5532,
+    FirmwareTooOld = 5533,
+    WrongApp = 5540,
+    BridgeNotFound = 5550,
+    TransportNotAvailable = 5551
+}
+
+interface Success<T> {
+    success: true;
+    payload: T;
+}
+interface Failure {
+    success: false;
+    payload: {
+        error: string;
+        code: HardwareErrorCode;
+    };
+}
+type Response<T> = Success<T> | Failure;
+declare function success<T>(payload: T): Success<T>;
+declare function failure(code: HardwareErrorCode, error: string): Failure;
+
+type VendorType = 'trezor' | 'ledger' | 'keystone' | 'keystoneqr';
+type ConnectionType = 'usb' | 'ble' | 'qr';
+type TransportType = 'usb' | 'ble' | 'hid' | 'bridge' | 'qr';
+interface DeviceInfo {
+    vendor: VendorType;
+    model: string;
+    firmwareVersion: string;
+    deviceId: string;
+    connectId: string;
+    label?: string;
+    connectionType: ConnectionType;
+    battery?: number;
+}
+interface DeviceTarget {
+    connectId: string;
+    deviceId: string;
+}
+
+interface EvmGetAddressParams {
+    path: string;
+    showOnDevice?: boolean;
+    chainId?: number;
+}
+interface EvmAddress {
+    address: string;
+    path: string;
+}
+interface EvmGetPublicKeyParams {
+    path: string;
+    showOnDevice?: boolean;
+}
+interface EvmPublicKey {
+    publicKey: string;
+    path: string;
+}
+interface EvmSignTxParams {
+    path: 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;
+}
+type ProgressCallback = (progress: {
+    index: number;
+    total: number;
+}) => void;
+interface IEvmMethods {
+    evmGetAddress(connectId: string, deviceId: string, params: EvmGetAddressParams): Promise<Response<EvmAddress>>;
+    evmGetAddresses(connectId: string, deviceId: string, params: EvmGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<EvmAddress[]>>;
+    evmGetPublicKey(connectId: string, deviceId: string, params: EvmGetPublicKeyParams): Promise<Response<EvmPublicKey>>;
+    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 BtcGetAddressParams {
+    path: string;
+    coin?: string;
+    showOnDevice?: boolean;
+    scriptType?: 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr';
+    addressIndex?: number;
+    change?: boolean;
+}
+interface BtcAddress {
+    address: string;
+    path: string;
+}
+interface BtcGetPublicKeyParams {
+    path: string;
+    coin?: string;
+    showOnDevice?: boolean;
+}
+interface BtcPublicKey {
+    xpub: string;
+    publicKey: string;
+    /** Parent key fingerprint (BIP-32), not the master fingerprint. */
+    fingerprint: number;
+    chainCode: string;
+    path: string;
+    depth: number;
+}
+interface BtcSignTxParams {
+    psbt?: string;
+    inputs?: BtcTxInput[];
+    outputs?: BtcTxOutput[];
+    refTxs?: BtcRefTransaction[];
+    coin: string;
+    locktime?: number;
+    version?: number;
+}
+interface BtcTxInput {
+    path: string;
+    prevHash: string;
+    prevIndex: number;
+    amount: string;
+    scriptType?: 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr';
+    sequence?: number;
+}
+interface BtcTxOutput {
+    address?: string;
+    path?: string;
+    amount: string;
+    scriptType?: 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr';
+}
+interface BtcRefTransaction {
+    hash: string;
+    version: number;
+    inputs: Array<{
+        prevHash: string;
+        prevIndex: number;
+        script: string;
+        sequence: number;
+    }>;
+    outputs: Array<{
+        amount: string;
+        scriptPubKey: string;
+    }>;
+    locktime: number;
+}
+interface BtcSignedTx {
+    signatures: string[];
+    serializedTx: string;
+    txid?: string;
+    signedPsbt?: string;
+}
+interface BtcSignMsgParams {
+    path: string;
+    message: string;
+    coin?: string;
+}
+interface BtcSignature {
+    signature: string;
+    address: string;
+}
+interface IBtcMethods {
+    btcGetAddress(connectId: string, deviceId: string, params: BtcGetAddressParams): Promise<Response<BtcAddress>>;
+    btcGetAddresses(connectId: string, deviceId: string, params: BtcGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<BtcAddress[]>>;
+    btcGetPublicKey(connectId: string, deviceId: string, params: BtcGetPublicKeyParams): Promise<Response<BtcPublicKey>>;
+    btcSignTransaction(connectId: string, deviceId: string, params: BtcSignTxParams): Promise<Response<BtcSignedTx>>;
+    btcSignMessage(connectId: string, deviceId: string, params: BtcSignMsgParams): Promise<Response<BtcSignature>>;
+    btcGetMasterFingerprint(connectId: string, deviceId: string): Promise<Response<{
+        masterFingerprint: string;
+    }>>;
+}
+
+interface SolGetAddressParams {
+    path: string;
+    showOnDevice?: boolean;
+}
+interface SolAddress {
+    /** Base58-encoded Solana address */
+    address: string;
+    path: string;
+}
+interface SolGetPublicKeyParams {
+    path: string;
+    showOnDevice?: boolean;
+}
+interface SolPublicKey {
+    /** Base58-encoded Ed25519 public key (same as the Solana address) */
+    publicKey: string;
+    path: string;
+}
+interface SolSignTxParams {
+    path: string;
+    /** Hex-encoded serialized transaction bytes (no 0x prefix) */
+    serializedTx: string;
+    additionalInfo?: {
+        tokenAccountsInfos?: Array<{
+            baseAddress: string;
+            tokenProgram: string;
+            tokenMint: string;
+            tokenAccount: string;
+        }>;
+    };
+}
+interface SolSignedTx {
+    /** Hex-encoded Ed25519 signature (no 0x prefix) */
+    signature: string;
+}
+interface SolSignMsgParams {
+    path: string;
+    /** Message bytes as hex string (no 0x prefix) */
+    message: string;
+}
+interface SolSignature {
+    /** Hex-encoded Ed25519 signature (no 0x prefix) */
+    signature: string;
+}
+interface ISolMethods {
+    solGetAddress(connectId: string, deviceId: string, params: SolGetAddressParams): Promise<Response<SolAddress>>;
+    solGetAddresses(connectId: string, deviceId: string, params: SolGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<SolAddress[]>>;
+    solGetPublicKey(connectId: string, deviceId: string, params: SolGetPublicKeyParams): Promise<Response<SolPublicKey>>;
+    solSignTransaction(connectId: string, deviceId: string, params: SolSignTxParams): Promise<Response<SolSignedTx>>;
+    solSignMessage(connectId: string, deviceId: string, params: SolSignMsgParams): Promise<Response<SolSignature>>;
+}
+
+interface QrDisplayData {
+    urType: string;
+    urData: string;
+    animated: boolean;
+}
+interface QrResponseData {
+    urType: string;
+    urData: 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";
+    readonly ACQUIRE: "device-acquire";
+    readonly RELEASE: "device-release";
+    readonly FEATURES: "features";
+    readonly SUPPORT_FEATURES: "support_features";
+};
+
+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 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 CANCEL: "cancel";
+};
+
+/** 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";
+};
+
+type ChainCapability = 'evm' | 'btc' | 'sol';
+interface PassphraseResponse {
+    passphrase: string;
+    /** If true, passphrase will be entered on the device. `passphrase` field is ignored. */
+    onDevice?: boolean;
+}
+type DeviceEvent = {
+    type: typeof DEVICE.CONNECT;
+    payload: DeviceInfo;
+} | {
+    type: typeof DEVICE.DISCONNECT;
+    payload: {
+        connectId: string;
+    };
+} | {
+    type: typeof DEVICE.CHANGED;
+    payload: DeviceInfo;
+};
+type UiRequestEvent = {
+    type: typeof UI_REQUEST.REQUEST_PIN;
+    payload: {
+        device: DeviceInfo;
+    };
+} | {
+    type: typeof UI_REQUEST.REQUEST_PASSPHRASE;
+    payload: {
+        device: DeviceInfo;
+    };
+} | {
+    type: typeof UI_REQUEST.REQUEST_PASSPHRASE_ON_DEVICE;
+    payload: {
+        device: DeviceInfo;
+    };
+} | {
+    type: typeof UI_REQUEST.REQUEST_BUTTON;
+    payload: {
+        device: DeviceInfo;
+        code?: string;
+    };
+} | {
+    type: typeof UI_REQUEST.REQUEST_QR_DISPLAY;
+    payload: {
+        device: DeviceInfo;
+        data: QrDisplayData;
+    };
+} | {
+    type: typeof UI_REQUEST.REQUEST_QR_SCAN;
+    payload: {
+        device: DeviceInfo;
+    };
+} | {
+    type: typeof UI_REQUEST.REQUEST_DEVICE_PERMISSION;
+    payload: Record<string, never>;
+} | {
+    type: typeof UI_REQUEST.REQUEST_SELECT_DEVICE;
+    payload: {
+        devices: DeviceInfo[];
+    };
+} | {
+    type: typeof UI_REQUEST.CLOSE_UI_WINDOW;
+    payload: Record<string, never>;
+};
+type SdkEvent = {
+    type: typeof SDK.DEVICE_INTERACTION;
+    payload: {
+        connectId: string;
+        action: string;
+    };
+} | {
+    type: typeof SDK.DEVICE_STUCK;
+    payload: {
+        connectId: string;
+    };
+} | {
+    type: typeof SDK.DEVICE_UNRESPONSIVE;
+    payload: {
+        connectId: string;
+    };
+} | {
+    type: typeof SDK.DEVICE_RECOVERED;
+    payload: {
+        connectId: string;
+    };
+};
+type HardwareEvent = DeviceEvent | UiRequestEvent | SdkEvent;
+type DeviceEventListener = (event: HardwareEvent) => void;
+/**
+ * Type-safe event map for IHardwareWallet.on / .off.
+ *
+ * Each key is a concrete event string (e.g. DEVICE.CONNECT = 'device-connect'),
+ * and the value is the narrowed event object the listener will receive.
+ */
+interface HardwareEventMap {
+    [DEVICE.CONNECT]: {
+        type: typeof DEVICE.CONNECT;
+        payload: DeviceInfo;
+    };
+    [DEVICE.DISCONNECT]: {
+        type: typeof DEVICE.DISCONNECT;
+        payload: {
+            connectId: string;
+        };
+    };
+    [DEVICE.CHANGED]: {
+        type: typeof DEVICE.CHANGED;
+        payload: DeviceInfo;
+    };
+    [UI_REQUEST.REQUEST_PIN]: {
+        type: typeof UI_REQUEST.REQUEST_PIN;
+        payload: {
+            device: DeviceInfo;
+        };
+    };
+    [UI_REQUEST.REQUEST_PASSPHRASE]: {
+        type: typeof UI_REQUEST.REQUEST_PASSPHRASE;
+        payload: {
+            device: DeviceInfo;
+        };
+    };
+    [UI_REQUEST.REQUEST_PASSPHRASE_ON_DEVICE]: {
+        type: typeof UI_REQUEST.REQUEST_PASSPHRASE_ON_DEVICE;
+        payload: {
+            device: DeviceInfo;
+        };
+    };
+    [UI_REQUEST.REQUEST_BUTTON]: {
+        type: typeof UI_REQUEST.REQUEST_BUTTON;
+        payload: {
+            device: DeviceInfo;
+            code?: string;
+        };
+    };
+    [UI_REQUEST.REQUEST_QR_DISPLAY]: {
+        type: typeof UI_REQUEST.REQUEST_QR_DISPLAY;
+        payload: {
+            device: DeviceInfo;
+            data: QrDisplayData;
+        };
+    };
+    [UI_REQUEST.REQUEST_QR_SCAN]: {
+        type: typeof UI_REQUEST.REQUEST_QR_SCAN;
+        payload: {
+            device: DeviceInfo;
+        };
+    };
+    [UI_REQUEST.REQUEST_DEVICE_PERMISSION]: {
+        type: typeof UI_REQUEST.REQUEST_DEVICE_PERMISSION;
+        payload: Record<string, never>;
+    };
+    [UI_REQUEST.REQUEST_SELECT_DEVICE]: {
+        type: typeof UI_REQUEST.REQUEST_SELECT_DEVICE;
+        payload: {
+            devices: DeviceInfo[];
+        };
+    };
+    [UI_REQUEST.CLOSE_UI_WINDOW]: {
+        type: typeof UI_REQUEST.CLOSE_UI_WINDOW;
+        payload: Record<string, never>;
+    };
+    [SDK.DEVICE_INTERACTION]: {
+        type: typeof SDK.DEVICE_INTERACTION;
+        payload: {
+            connectId: string;
+            action: string;
+        };
+    };
+    [SDK.DEVICE_STUCK]: {
+        type: typeof SDK.DEVICE_STUCK;
+        payload: {
+            connectId: string;
+        };
+    };
+    [SDK.DEVICE_UNRESPONSIVE]: {
+        type: typeof SDK.DEVICE_UNRESPONSIVE;
+        payload: {
+            connectId: string;
+        };
+    };
+    [SDK.DEVICE_RECOVERED]: {
+        type: typeof SDK.DEVICE_RECOVERED;
+        payload: {
+            connectId: string;
+        };
+    };
+}
+/**
+ * UI handler for interactive request-response flows.
+ * Adapters call these when they need user input (PIN, passphrase, QR scan).
+ * Pure notifications (button confirm, progress) go through events instead.
+ */
+interface IUiHandler {
+    onPinRequest(device: DeviceInfo): Promise<string>;
+    onPassphraseRequest(device: DeviceInfo): Promise<string | PassphraseResponse>;
+    onQrDisplay(device: DeviceInfo, data: QrDisplayData): Promise<QrResponseData>;
+    onSelectDevice(devices: DeviceInfo[]): Promise<string>;
+    /**
+     * Check if device access permission is already granted.
+     * Returns { granted, context? }.
+     * - granted: true → skip onDevicePermission
+     * - granted: false → adapter calls onDevicePermission with the context
+     * - context: consumer-defined data passed through to onDevicePermission
+     *
+     * When connectId/deviceId are undefined (searchDevices), check environment-level
+     * permissions (USB: any paired device exists; BLE: bluetooth on + location permission).
+     * When connectId/deviceId are provided (business methods), check device-level
+     * permissions (USB: target device authorized; BLE: bluetooth on + device connected).
+     */
+    checkDevicePermission?(params: {
+        transportType: TransportType;
+        connectId?: string;
+        deviceId?: string;
+    }): Promise<{
+        granted: boolean;
+        context?: Record<string, unknown>;
+    }>;
+    /**
+     * Request device access permission from the user.
+     * Only called when checkDevicePermission returns granted: false (or is not set).
+     *
+     * The handler decides what to do based on transportType + context:
+     * - usb/hid: open pairing page or call requestWebUSBDevice
+     * - ble: enable bluetooth, request location permission, start scanning
+     */
+    onDevicePermission(params: {
+        transportType: TransportType;
+        context?: Record<string, unknown>;
+    }): Promise<void>;
+}
+interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, ISolMethods {
+    readonly vendor: string;
+    readonly activeTransport: TransportType | null;
+    init(config: TConfig): Promise<void>;
+    dispose(): Promise<void>;
+    getAvailableTransports(): TransportType[];
+    switchTransport(type: TransportType): Promise<void>;
+    searchDevices(): Promise<DeviceInfo[]>;
+    connectDevice(connectId: string): Promise<Response<string>>;
+    disconnectDevice(connectId: string): Promise<void>;
+    getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
+    getSupportedChains(): ChainCapability[];
+    cancel(connectId: string): void;
+    setUiHandler(handler: Partial<IUiHandler>): void;
+    on<K extends keyof HardwareEventMap>(event: K, listener: (event: HardwareEventMap[K]) => void): void;
+    on(event: string, listener: DeviceEventListener): void;
+    off<K extends keyof HardwareEventMap>(event: K, listener: (event: HardwareEventMap[K]) => void): void;
+    off(event: string, listener: DeviceEventListener): void;
+}
+
+/**
+ * Low-level device descriptor from Transport layer.
+ * Represents a physical device detected by USB/BLE scanning.
+ */
+interface DeviceDescriptor {
+    /** Unique device path (USB serial number, BLE address, etc.) */
+    path: string;
+    /** USB product ID */
+    product?: number;
+    /** USB vendor ID */
+    vendor?: number;
+    /** Device type/model identifier */
+    type?: string;
+}
+interface DeviceConnectEvent {
+    type: 'device-connected';
+    descriptor: DeviceDescriptor;
+}
+interface DeviceDisconnectEvent {
+    type: 'device-disconnected';
+    descriptor: DeviceDescriptor;
+}
+type DeviceChangeEvent = DeviceConnectEvent | DeviceDisconnectEvent;
+
+/**
+ * Per-device serial job queue with preemption support and stuck recovery.
+ * Ensures that only one operation runs at a time per device, with intelligent
+ * handling of conflicting operations.
+ */
+type Interruptibility = 'none' | 'safe' | 'confirm';
+type PreemptionDecision = 'cancel-current' | 'wait' | 'reject-new';
+interface JobOptions {
+    interruptibility?: Interruptibility;
+    label?: string;
+}
+interface ActiveJobInfo {
+    label?: string;
+    interruptibility: Interruptibility;
+    startedAt: number;
+}
+interface PreemptionEvent {
+    deviceId: string;
+    currentJob: ActiveJobInfo;
+    newJob: {
+        label?: string;
+        interruptibility: Interruptibility;
+    };
+}
+declare class DeviceJobQueue {
+    private readonly _queues;
+    private readonly _active;
+    /**
+     * Called when a new job conflicts with an active 'confirm'-level job.
+     * UI should show a dialog and return the user's decision.
+     * If not set, defaults to 'wait' (queue behind current job).
+     */
+    onPreemptionRequest?: (event: PreemptionEvent) => Promise<PreemptionDecision>;
+    /**
+     * Enqueue a job for a specific device.
+     * If a job is already running for this device, behavior depends on interruptibility:
+     * - 'none': new job queues silently (no preemption possible)
+     * - 'safe': current job is auto-cancelled, new job runs immediately after
+     * - 'confirm': onPreemptionRequest is called to ask user
+     */
+    enqueue<T>(deviceId: string, job: (signal: AbortSignal) => Promise<T>, options?: JobOptions): Promise<T>;
+    /** Manually cancel the active job on a device. Returns false if job is non-interruptible. */
+    cancelActive(deviceId: string): boolean;
+    /** Force cancel regardless of interruptibility. Use for device stuck recovery. */
+    forceCancelActive(deviceId: string): boolean;
+    /** Get info about the currently active job for a device, or null if idle. */
+    getActiveJob(deviceId: string): ActiveJobInfo | null;
+    clear(): void;
+}
+
+/**
+ * Abstraction for UI communication during device interactions.
+ * Implementations handle different execution contexts:
+ * - DirectUiBridge: same-process event emitter (default)
+ * - IframeUiBridge: postMessage-based (future)
+ * - ExtensionUiBridge: chrome.runtime.sendMessage (future)
+ */
+interface IUiBridge {
+    /** Ask the user for PIN entry. Returns the PIN string. */
+    requestPin(device: DeviceInfo, signal?: AbortSignal): Promise<string>;
+    /** Ask the user for passphrase entry. Returns the passphrase string. */
+    requestPassphrase(device: DeviceInfo, signal?: AbortSignal): Promise<string>;
+    /** Notify the UI about a button press request on the device. */
+    notifyButton(device: DeviceInfo, code?: string): void;
+    /**
+     * Ask the user whether to preempt the current device operation.
+     * Only called for 'confirm'-level operations.
+     */
+    requestPreemption(device: DeviceInfo, activeLabel: string, newLabel: string): Promise<PreemptionDecision>;
+}
+
+/**
+ * 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;
+}
+interface ConnectorSession {
+    sessionId: string;
+    deviceInfo: DeviceInfo;
+}
+type ConnectorEventType = 'device-connect' | 'device-disconnect' | 'ui-request' | 'ui-event';
+interface ConnectorEventMap {
+    'device-connect': {
+        device: ConnectorDevice;
+    };
+    'device-disconnect': {
+        connectId: string;
+    };
+    'ui-request': {
+        type: string;
+        payload?: unknown;
+    };
+    'ui-event': {
+        type: string;
+        payload?: unknown;
+    };
+}
+interface IConnector {
+    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: {
+        type: string;
+        payload: unknown;
+    }): 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 IDesktopHardwareBridge {
+    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: {
+            type: string;
+            payload: unknown;
+        };
+    }): void;
+    reset(params: {
+        vendor: VendorType;
+    }): void;
+    /** Register an event handler for connector events forwarded from the main process. */
+    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;
+}
+/**
+ * Create an IConnector from a desktop IPC bridge + vendor name.
+ * Events are forwarded via bridge.onEvent/offEvent.
+ */
+declare function createDesktopBridgeConnector(vendor: VendorType, bridge: IDesktopHardwareBridge): IConnector;
+
+/**
+ * Minimal typed event emitter using Map<string, Set<listener>>.
+ * Each adapter uses this for device events (connect, disconnect, pin, etc.).
+ *
+ * TMap is a record mapping event name strings to their payload types.
+ * Example:
+ *   type MyEvents = { 'connect': { id: string }; 'disconnect': { id: string } };
+ *   const emitter = new TypedEventEmitter<MyEvents>();
+ *   emitter.on('connect', (data) => { data.id }); // data is { id: string }
+ *
+ * For backward compatibility, TMap defaults to Record<string, any> so that
+ * existing code using `new TypedEventEmitter<SomeUnionType>()` still compiles.
+ */
+declare class TypedEventEmitter<TMap extends Record<string, any> = Record<string, any>> {
+    private readonly _listeners;
+    on<K extends keyof TMap & string>(event: K, listener: (event: TMap[K]) => void): void;
+    on(event: string, listener: (event: any) => void): void;
+    off<K extends keyof TMap & string>(event: K, listener: (event: TMap[K]) => void): void;
+    off(event: string, listener: (event: any) => void): void;
+    emit<K extends keyof TMap & string>(event: K, data: TMap[K]): void;
+    emit(event: string, data: unknown): void;
+    removeAllListeners(): void;
+}
+
+/**
+ * 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.
+ */
+declare function compareSemver(a: string, b: string): number;
+
+export { type ActiveJobInfo, type BtcAddress, type BtcGetAddressParams, type BtcGetPublicKeyParams, type BtcPublicKey, type BtcRefTransaction, type BtcSignMsgParams, type BtcSignTxParams, type BtcSignature, type BtcSignedTx, type BtcTxInput, type BtcTxOutput, type ChainCapability, type ConnectionType, type ConnectorDevice, type ConnectorEventMap, type ConnectorEventType, type ConnectorSession, DEVICE, DEVICE_EVENT, type DeviceChangeEvent, type DeviceConnectEvent, type DeviceDescriptor, type DeviceDisconnectEvent, type DeviceEvent, type DeviceEventListener, type DeviceInfo, DeviceJobQueue, type DeviceTarget, type EIP712Domain, type EvmAddress, type EvmGetAddressParams, type EvmGetPublicKeyParams, type EvmPublicKey, 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 IDesktopHardwareBridge, type IEvmMethods, type IHardwareWallet, type ISolMethods, type IUiBridge, type IUiHandler, type Interruptibility, type JobOptions, type PassphraseResponse, type PreemptionDecision, type PreemptionEvent, type ProgressCallback, type QrDisplayData, type QrResponseData, type Response, SDK, type SdkEvent, type SolAddress, type SolGetAddressParams, type SolGetPublicKeyParams, type SolPublicKey, type SolSignMsgParams, type SolSignTxParams, type SolSignature, type SolSignedTx, type Success, type TransportType, TypedEventEmitter, UI_EVENT, UI_REQUEST, UI_RESPONSE, type UiRequestEvent, type VendorType, compareSemver, createDesktopBridgeConnector, failure, success };