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

package/dist/index.d.mts

@@ -0,0 +1,1079 @@
+/**
+ * HWK HardwareErrorCode — independent namespace from the legacy
+ * `@onekeyfe/shared` HardwareErrorCode (which occupies 0-902).
+ *
+ * All HWK codes are 5-digit (>= 10000) so the two tables never collide
+ * even if either side grows. Each sub-category gets a 100-slot block.
+ *
+ *   10000-10099  Generic / cross-cutting primitives
+ *   10100-10199  Device state
+ *   10200-10299  Firmware
+ *   10300-10399  Transport + OS-level permission
+ *   10400-10499  PIN / Passphrase
+ *   10500-10599  App lifecycle (wrong app, not open, too old)
+ *   10600-10999  RESERVED — future adapter-level categories
+ *
+ *   11000-11099  EVM APDU (reactive mapping)
+ *   11100-11199  Solana APDU
+ *   11200-11299  Tron APDU
+ *   11300-11399  BTC APDU
+ *   11400-11999  RESERVED — future chain APDU blocks (100 per chain)
+ *
+ *   12000-99999  RESERVED — future major categories
+ */
+declare enum HardwareErrorCode {
+    UnknownError = 10000,
+    UserRejected = 10001,
+    InvalidParams = 10002,
+    OperationTimeout = 10003,
+    MethodNotSupported = 10004,
+    DeviceNotFound = 10100,
+    DeviceDisconnected = 10101,
+    DeviceBusy = 10102,
+    DeviceLocked = 10103,
+    DeviceNotInitialized = 10104,
+    DeviceInBootloader = 10105,
+    DeviceMismatch = 10106,
+    FirmwareTooOld = 10200,
+    FirmwareUpdateRequired = 10201,
+    TransportError = 10300,
+    BridgeNotFound = 10301,
+    TransportNotAvailable = 10302,
+    /**
+     * OS-level permission (Bluetooth / USB / etc.) — denied, blocked,
+     * unavailable, or dismissed. Consumers surface a single "please grant
+     * permission" toast and let the user retry manually.
+     */
+    DevicePermissionDenied = 10303,
+    PinInvalid = 10400,
+    PinCancelled = 10401,
+    PassphraseRejected = 10402,
+    AppNotOpen = 10500,
+    WrongApp = 10501,
+    /** 0x911c Command code not supported — app predates current SDK. */
+    AppTooOld = 10502,
+    /** 0x6a80 Invalid data — observed on blindSignTransactionFallback when the
+     *  user has not enabled Blind signing on the device. */
+    EvmBlindSigningRequired = 11000,
+    /** 0x6984 Plugin not installed */
+    EvmClearSignPluginMissing = 11001,
+    /** 0x6a84 Insufficient memory (typical on Nano S with large calldata) */
+    EvmDataTooLarge = 11002,
+    /** 0x6501 TransactionType not supported (app too old for EIP-1559 / blob / 7702) */
+    EvmTxTypeNotSupported = 11003,
+    /** 0x6808 Blind signing disabled for this instruction. */
+    SolanaBlindSigningRequired = 11100,
+    /** 0x6a8d Custom Contracts setting disabled (blocks TRC-20 etc.). */
+    TronCustomContractRequired = 11200,
+    /** 0x6a8b Transactions Data setting disabled. */
+    TronDataSigningRequired = 11201,
+    /** 0x6a8c Sign by Hash setting disabled (hash-signing fallback). */
+    TronSignByHashRequired = 11202,
+    /** 0xb008 Wallet policy HMAC mismatch or not registered. */
+    BtcWalletPolicyHmacMismatch = 11300,
+    /** 0xb007 Aborted due to unexpected state (malformed PSBT / missing UTXO). */
+    BtcUnexpectedState = 11301
+}
+
+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';
+type ConnectionType = 'usb' | 'ble';
+type TransportType = 'usb' | 'ble' | 'hid' | 'bridge';
+/**
+ * Device capabilities — describes what a specific device/connection
+ * combination can or cannot do. Varies by vendor, model, and connection type.
+ *
+ * This enables business logic to check capabilities instead of hard-coding
+ * vendor-specific conditions (e.g., `if (vendor === 'ledger')`).
+ */
+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.
+     */
+    persistentDeviceIdentity: boolean;
+}
+interface DeviceInfo {
+    vendor: VendorType;
+    model: string;
+    firmwareVersion: string;
+    deviceId: string;
+    connectId: string;
+    label?: string;
+    connectionType: ConnectionType;
+    battery?: number;
+    /** Device capabilities — varies by vendor, model, and connection type */
+    capabilities?: DeviceCapabilities;
+}
+interface DeviceTarget {
+    connectId: string;
+    deviceId: string;
+}
+
+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;
+}
+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[]>>;
+    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;
+    /** Account-level derivation path (e.g. "84'/0'/0'") for wallet template. */
+    path?: string;
+}
+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 {
+    serializedTx: string;
+    /** Present when the wallet returns per-input sigs separately (e.g. Trezor). */
+    signatures?: string[];
+    txid?: string;
+}
+interface BtcSignPsbtParams {
+    psbt: string;
+    coin?: string;
+    /** Account-level derivation path (e.g. "84'/0'/0'") for wallet template. */
+    path?: string;
+}
+interface BtcSignedPsbt {
+    signedPsbt: string;
+}
+interface BtcSignMsgParams {
+    path: string;
+    message: string;
+    coin?: string;
+}
+interface BtcSignature {
+    signature: string;
+    /** Optional — not all adapters return it (e.g. Ledger DMK). Derive via btcGetAddress if needed. */
+    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>>;
+    btcSignPsbt(connectId: string, deviceId: string, params: BtcSignPsbtParams): Promise<Response<BtcSignedPsbt>>;
+    btcSignMessage(connectId: string, deviceId: string, params: BtcSignMsgParams): Promise<Response<BtcSignature>>;
+    btcGetMasterFingerprint(connectId: string, deviceId: string): Promise<Response<{
+        masterFingerprint: string;
+    }>>;
+}
+
+interface SolGetAddressParams {
+    path: string;
+    showOnDevice?: boolean;
+}
+interface SolAddress {
+    /** Base58-encoded Solana address — this is also the Ed25519 public key. */
+    address: 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[]>>;
+    solSignTransaction(connectId: string, deviceId: string, params: SolSignTxParams): Promise<Response<SolSignedTx>>;
+    solSignMessage(connectId: string, deviceId: string, params: SolSignMsgParams): Promise<Response<SolSignature>>;
+}
+
+interface TronGetAddressParams {
+    path: string;
+    showOnDevice?: boolean;
+}
+interface TronAddress {
+    /** Base58check-encoded TRON address (starts with 'T') */
+    address: string;
+    path: string;
+}
+interface TronSignTxParams {
+    path: string;
+    /** Protobuf-encoded raw transaction hex (no 0x prefix) */
+    rawTxHex: string;
+}
+interface TronSignedTx {
+    /** 65-byte hex-encoded signature (no 0x prefix) */
+    signature: string;
+}
+interface TronSignMsgParams {
+    path: string;
+    /** Message hex (no 0x prefix) */
+    messageHex: string;
+}
+interface TronSignature {
+    /** 65-byte hex-encoded signature (no 0x prefix) */
+    signature: string;
+}
+interface ITronMethods {
+    tronGetAddress(connectId: string, deviceId: string, params: TronGetAddressParams): Promise<Response<TronAddress>>;
+    tronGetAddresses(connectId: string, deviceId: string, params: TronGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<TronAddress[]>>;
+    tronSignTransaction(connectId: string, deviceId: string, params: TronSignTxParams): Promise<Response<TronSignedTx>>;
+    tronSignMessage(connectId: string, deviceId: string, params: TronSignMsgParams): Promise<Response<TronSignature>>;
+}
+
+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";
+};
+
+/** 10 min — every UI request is human-in-the-loop; bias toward "wait long". */
+declare const UI_REQUEST_DEFAULT_TIMEOUT_MS = 600000;
+declare const UI_REQUEST_PREEMPTED_TAG = "UiRequestPreempted";
+declare const UI_REQUEST_CANCELLED_TAG = "UiRequestCancelled";
+declare const UI_REQUEST_TIMEOUT_TAG = "UiRequestTimeout";
+/**
+ * Per-type single-slot registry for adapter-level UI requests. A new `wait`
+ * of the same type preempts (rejects) the prior one. Unknown response types
+ * are dropped silently so the public `uiResponse` entry never throws.
+ */
+declare class UiRequestRegistry {
+    private pending;
+    wait<T = unknown>(requestType: string, options?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    resolve(responseType: string, payload: unknown): void;
+    cancel(requestType?: string): void;
+    reset(): void;
+    hasPending(requestType: string): boolean;
+}
+
+/**
+ * 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.
+ *
+ * The 'confirm' level uses the standard UI request/response flow:
+ * emits REQUEST_PREEMPTION → waits for RECEIVE_PREEMPTION via UiRequestRegistry.
+ */
+
+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;
+    };
+}
+interface DeviceJobQueueDeps {
+    /** Emit a UI request event to the frontend. */
+    emit: (event: string, data: unknown) => void;
+    /** Registry for waiting on UI responses. */
+    uiRegistry: UiRequestRegistry;
+}
+declare class DeviceJobQueue {
+    private readonly _queues;
+    private readonly _active;
+    private readonly _deps;
+    /** Incremented on clear() so stale queued jobs can detect invalidation. */
+    private _generation;
+    constructor(deps?: DeviceJobQueueDeps);
+    /**
+     * 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': emits REQUEST_PREEMPTION and waits for UI response
+     */
+    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;
+    /**
+     * Request preemption decision via UI request/response flow.
+     * Falls back to 'wait' if deps are not provided.
+     */
+    private _requestPreemptionDecision;
+}
+
+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_PREEMPTION: "ui-request-preemption";
+    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_PREEMPTION: "receive-preemption";
+    readonly CANCEL: "cancel";
+};
+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: {
+        granted: boolean;
+    };
+} | {
+    type: typeof UI_RESPONSE.RECEIVE_PREEMPTION;
+    payload: {
+        decision: PreemptionDecision;
+    };
+} | {
+    type: typeof UI_RESPONSE.CANCEL;
+    payload?: undefined;
+};
+
+/** 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";
+};
+
+/**
+ * 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.).
+ */
+declare enum EConnectorInteraction {
+    /** 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.ConfirmOpenApp;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.UnlockDevice;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.ConfirmOnDevice;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    type: EConnectorInteraction.InteractionComplete;
+    payload: {
+        sessionId: string;
+    };
+};
+interface ConnectorEventMap {
+    'device-connect': {
+        device: ConnectorDevice;
+    };
+    'device-disconnect': {
+        connectId: string;
+    };
+    '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;
+}
+/**
+ * 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;
+
+type ChainCapability = 'evm' | 'btc' | 'sol' | 'tron';
+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: {
+        transportType: TransportType;
+        connectId?: string;
+        deviceId?: string;
+    };
+} | {
+    type: typeof UI_REQUEST.REQUEST_SELECT_DEVICE;
+    payload: {
+        devices: DeviceInfo[];
+    };
+} | {
+    type: typeof UI_REQUEST.REQUEST_DEVICE_CONNECT;
+    payload: {
+        message: string;
+    };
+} | {
+    type: typeof UI_REQUEST.REQUEST_PREEMPTION;
+    payload: {
+        deviceId: string;
+        currentJob: ActiveJobInfo;
+        newJob: {
+            label?: string;
+            interruptibility: Interruptibility;
+        };
+    };
+} | {
+    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 | ConnectorUiEvent;
+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 {
+    'ui-event': ConnectorUiEvent;
+    [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: {
+            transportType: TransportType;
+            connectId?: string;
+            deviceId?: string;
+        };
+    };
+    [UI_REQUEST.REQUEST_SELECT_DEVICE]: {
+        type: typeof UI_REQUEST.REQUEST_SELECT_DEVICE;
+        payload: {
+            devices: DeviceInfo[];
+        };
+    };
+    [UI_REQUEST.REQUEST_DEVICE_CONNECT]: {
+        type: typeof UI_REQUEST.REQUEST_DEVICE_CONNECT;
+        payload: {
+            message: string;
+        };
+    };
+    [UI_REQUEST.REQUEST_PREEMPTION]: {
+        type: typeof UI_REQUEST.REQUEST_PREEMPTION;
+        payload: {
+            deviceId: string;
+            currentJob: ActiveJobInfo;
+            newJob: {
+                label?: string;
+                interruptibility: Interruptibility;
+            };
+        };
+    };
+    [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;
+        };
+    };
+}
+interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, ISolMethods, ITronMethods {
+    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;
+    /** Respond to any pending `ui-request-*`. */
+    uiResponse(response: UiResponseEvent): void;
+    /**
+     * Derive a chain-specific fingerprint for the connected device.
+     *
+     * For Ledger: derives an address at a fixed testnet path and hashes it.
+     * For Trezor: returns the hardware device_id from firmware features.
+     *
+     * Used to verify that the same seed/device is connected across sessions,
+     * especially for vendors with ephemeral connectId/deviceId.
+     */
+    getChainFingerprint(connectId: string, deviceId: string, chain: ChainForFingerprint): Promise<Response<string>>;
+    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;
+    /** BLE device name (e.g., "Nano X 123A") — contains stable 4-digit HEX suffix */
+    name?: string;
+    /** Transport identifier (e.g., 'WEB-HID', 'BLE') */
+    transport?: string;
+}
+interface DeviceConnectEvent {
+    type: 'device-connected';
+    descriptor: DeviceDescriptor;
+}
+interface DeviceDisconnectEvent {
+    type: 'device-disconnected';
+    descriptor: DeviceDescriptor;
+}
+type DeviceChangeEvent = DeviceConnectEvent | DeviceDisconnectEvent;
+
+/**
+ * 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;
+
+/** Ensure hex string has 0x prefix */
+declare function ensure0x(hex: string): string;
+/** Strip 0x prefix from hex string */
+declare function stripHex(hex: string): string;
+/** Pad hex to 64 chars (32 bytes) with 0x prefix */
+declare function padHex64(hex: string): string;
+/**
+ * Convert a hex string (with or without 0x prefix) to a Uint8Array.
+ * Throws on invalid hex (non-hex characters, odd length).
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/** Convert a Uint8Array to a hex string (no 0x prefix). */
+declare function bytesToHex(bytes: Uint8Array): string;
+
+/**
+ * Enrich a hardware error message with actionable recovery hints.
+ * Shared across adapters (Ledger, Trezor, etc.).
+ */
+declare function enrichErrorMessage(code: HardwareErrorCode, originalMessage: string): string;
+
+/**
+ * Generic batch call with progress reporting.
+ * If any single call fails, returns the failure immediately.
+ */
+declare function batchCall<TParam, TResult>(params: TParam[], callFn: (p: TParam) => Promise<Response<TResult>>, onProgress?: (progress: {
+    index: number;
+    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 DeviceJobQueueDeps, 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 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 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 };