@onekeyfe/hwk-keystone-adapter 1.2.2-alpha.100 → 1.2.3-alpha.1

package/dist/index.d.mts

@@ -1,4 +1,10 @@
-import { ChainCapability, IHardwareWallet, IConnector, TransportType, SearchDevicesOptions, DeviceInfo, Response, ChainForFingerprint, UiResponseEvent, HardwareEventMap, DeviceEventListener, AllNetworkGetAddressParams, AllNetworkAddressResponse, NullableCallArg, IHardwareCallParams, EvmGetAddressParams, EvmAddress, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature } from '@onekeyfe/hwk-adapter-core';
+import { ChainCapability, DeviceInfo, IHardwareWallet, IConnector, TransportType, SearchDevicesOptions, DeviceSearchTarget, ConnectionTarget, Response, ChainForFingerprint, UiResponseEvent, HardwareEventMap, DeviceEventListener, AllNetworkGetAddressParams, AllNetworkAddressResponse, NullableCallArg, IHardwareCallParams, EvmGetAddressParams, EvmAddress, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, IHardwareCommonCallParams, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature } from '@onekeyfe/hwk-adapter-core';
+
+/** Keystone `DataType`: 1 = transaction, 2 = personal message. */
+declare enum TronSignType {
+    Transaction = 1,
+    PersonalMessage = 2
+}
 
 /**
  * A UR payload in the wire shape the reserved `QrDisplayData`/`QrResponseData`
@@ -25,7 +31,7 @@ interface KeystoneParsedAccount {
     name?: string;
 }
 interface KeystoneParsedMultiAccounts {
-    /** BIP32 master fingerprint of the seed (lowercase hex, 8 chars) — the cross-channel wallet identity. */
+    /** BIP32 master fingerprint of the seed (lowercase hex, 8 chars) used as BC-UR xfp metadata. */
     masterFingerprint: string;
     /** Model string (e.g. "Keystone 3 Pro"), present on both channels but not unique per unit. */
     device?: string;
@@ -102,13 +108,16 @@ interface KeystoneKeyDerivationRequestInput {
 interface KeystoneTronSignRequestInput {
     requestId: string;
     /**
-     * Hex, no 0x prefix — a standard TRON protobuf `Transaction.raw` message
-     * (the same bytes `TronSignTxParams.rawTxHex` already carries for Ledger).
+     * Hex, no 0x prefix. For a transaction: the TRON protobuf `Transaction.raw`
+     * bytes (same as `TronSignTxParams.rawTxHex`). For a personal message:
+     * the raw message bytes; the device applies the TIP-191 prefix itself.
      */
     rawTxHex: string;
     path: string;
     xfp: string;
     origin?: string;
+    /** Defaults to Transaction. */
+    signType?: TronSignType;
 }
 interface KeystoneTronSignatureResult {
     requestId?: string;
@@ -117,15 +126,9 @@ interface KeystoneTronSignatureResult {
 }
 
 /**
- * Thin wrapper around `@keystonehq/keystone-sdk`. Owns every touch point with the
- * vendor SDK so the rest of the adapter never imports it directly: same UR
- * construction/parsing serves both the QR and USB channels (USB carries the
- * identical UR payloads inside EAPDU framing — see the Keystone USB SDK's
- * `sendURRequest`), so this engine has no channel awareness at all.
- *
- * Deliberately uses the bare constructor, never `KeystoneSDK.create()` — `create()`
- * fetches remote fragment-size config from keyst.one at call time, which this SDK
- * must not depend on.
+ * Single touch point with `@keystonehq/keystone-sdk`; the same UR building
+ * and parsing serves QR and USB. Uses the bare constructor, not
+ * `KeystoneSDK.create()`, which fetches remote config at call time.
  */
 declare class KeystoneUrEngine {
     private readonly sdk;
@@ -189,6 +192,7 @@ declare class KeystoneUrEngine {
      * here needs no such library.
      */
     deriveBtcAddressFromXpub(xpub: string, relativeDerivePath: string, scriptType: BtcScriptType): string;
+    deriveBtcAddressFromPublicKey(publicKeyHex: string, scriptType: BtcScriptType): string;
     buildBtcPsbtRequest(unsignedPsbtHex: string): KeystoneUr;
     /** Returns the hex-encoded (possibly still-unsigned-in-part) PSBT the device replied with. */
     parseBtcPsbt(ur: KeystoneUr): string;
@@ -203,15 +207,8 @@ declare class KeystoneUrEngine {
     buildSolSignRequest(input: KeystoneSolSignRequestInput): KeystoneUr;
     parseSolSignature(ur: KeystoneUr): KeystoneSolSignatureResult;
     /**
-     * `@keystonehq/keystone-sdk`'s own bundled `sdk.tron` module is
-     * deliberately NOT used here — see `TronSignRequest.ts`'s doc comment for
-     * why: it's a different (gzip/protobuf) protocol with response semantics
-     * this package has no way to verify, whereas `TronSignRequest`/
-     * `TronSignature` are a direct port of OneKey's own already-proven
-     * production QR-wallet TRON implementation (a plain CBOR-native
-     * sign-request/signature pair, same shape as eth/sol). The device decodes
-     * `rawTxHex` itself — no client-side contract-type pre-parsing or
-     * `tokenInfo` needed, unlike the public SDK's module.
+     * Keystone's native tron-sign-request/tron-signature pair (bare signature).
+     * `sdk.tron` from keystone-sdk is the older protobuf envelope; not used.
      */
     buildTronSignRequest(input: KeystoneTronSignRequestInput): KeystoneUr;
     parseTronSignature(ur: KeystoneUr): KeystoneTronSignatureResult;
@@ -225,54 +222,112 @@ declare class KeystoneUrEngine {
      * strip its "0x" and re-encode the same 20 bytes.
      */
     deriveTronAddressFromXpub(xpub: string, relativeDerivePath: string): string;
+    /**
+     * Split an account-level xpub back into the BIP-32 fields a host needs to
+     * treat it as a real extended key (`BtcPublicKey`). Everything here is
+     * carried inside the xpub's own serialization — depth, the PARENT key
+     * fingerprint (not the seed's master fingerprint), the chain code and the
+     * compressed public key — so this is a pure decode with no device round
+     * trip; the xpub itself was already device-verified when it was synced.
+     */
+    parseXpubMeta(xpub: string): {
+        publicKey: string;
+        chainCode: string;
+        depth: number;
+        parentFingerprint: number;
+    };
+}
+
+declare const KEYSTONE_WALLET_CONNECT_ID_PREFIX = "keystone-wallet:";
+/** Fixed public source used to derive a collision-resistant wallet id. */
+declare const KEYSTONE_WALLET_ID_PATH = "m/44'/60'/0'";
+declare function walletConnectId(walletId: string): string;
+interface KeystoneAccountEntry extends KeystoneParsedAccount {
+    hwkChain: ChainCapability;
 }
+declare function accountKey(hwkChain: ChainCapability, path: string): string;
+interface KeystoneDeviceRecord {
+    /** SHA-256 id derived from the fixed account-level identity xpub. */
+    walletId: string;
+    /** Lowercase 8-char BIP32 fingerprint used by BC-UR as xfp, never as identity. */
+    masterFingerprint: string;
+    connectId: string;
+    /** Optional physical-device id exposed by some Keystone QR export menus. */
+    hardwareDeviceId?: string;
+    /** Model string from the device (e.g. "Keystone 3 Pro"); not unique per unit. */
+    model?: string;
+    deviceVersion?: string;
+    importedAt: number;
+    /**
+     * Set to the connector's process-local `sessionId` once a live USB session exists for
+     * this wallet. Cleared by `releaseInteraction`. Presence of this field is
+     * what `KeystoneAdapter._resolveUr` uses to route a call over USB instead
+     * of QR.
+     */
+    usbSessionId?: string;
+    /**
+     * Remains true after a live USB session is lost. It allows the adapter to
+     * wait through the device's short USB re-enumeration window without making
+     * wallets that have only ever used QR pay the same retry delay.
+     */
+    hadUsbSession?: boolean;
+    /**
+     * True once this wallet has completed at least one QR round trip.
+     * Distinguishes "USB session dropped but this wallet was also QR-synced —
+     * fall back to a QR-only entry" from "this was a USB-only wallet that
+     * never synced over QR — drop the entry entirely" on USB disconnect.
+     */
+    qrSynced?: boolean;
+}
+declare function deriveKeystoneWalletId(accounts: KeystoneParsedAccount[]): string;
+declare function createDeviceRecord(walletId: string, masterFingerprint: string): KeystoneDeviceRecord;
+declare function toDeviceInfo(record: KeystoneDeviceRecord): DeviceInfo;
+/** A device row for a wallet the adapter hasn't synced yet — used while a cold-start round trip is in flight. */
+declare function placeholderDeviceInfo(): DeviceInfo;
 
+/** Key material for one operation, keyed by `accountKey()`; never retained. */
+type AccountBook = Map<string, KeystoneAccountEntry>;
 interface ImportFromQrOptions {
     /**
-     * 'request': host asks for specific paths via a `qr-hardware-call`
-     * (KeyDerivation) UR — precise, works regardless of what screen the device
-     * is on. 'scan': just wait for whatever multi-account/HD-key export the
-     * device is already showing. Defaults to 'request' with `paths`, or the
-     * default EVM/BTC/SOL account set if `paths` is omitted.
+     * 'request': ask the device for the fixed identity xpub via a
+     * `qr-hardware-call` (KeyDerivation) UR. 'scan': just wait for whatever
+     * multi-account/HD-key export the device is already showing. Either way
+     * only the wallet identity is learned; key material is never retained.
      */
     mode?: 'request' | 'scan';
-    paths?: Array<{
-        hwkChain: ChainCapability;
-        path: string;
-    }>;
 }
 /**
- * Keystone hardware wallet adapter — QR and USB channels merged behind one
- * `IHardwareWallet` surface, keyed by the wallet's master fingerprint (mfp):
- * a caller sees the same `evmSignTransaction(...)` call regardless of which
- * channel actually carries it. Internally, a chain method's UR round trip
- * either drives one or two `REQUEST_QR_DISPLAY`/`REQUEST_QR_SCAN` UI events
- * (QR) or a direct `IConnector.call(sessionId, 'resolveUr', ur)` (USB) — see
- * `_resolveUr`.
- *
- * QR needs no physical enumeration or explicit connect step: a caller can
- * call any chain method with `connectId`/`deviceId` both null and the
- * adapter drives its own implicit cold-start sync. USB is the opposite —
- * WebUSB device pickers require a user gesture, so a USB session only comes
- * into existence via an explicit `searchDevices()` + `connectDevice()` (see
- * `_connectUsb`). Once a USB session exists for a wallet's mfp, later calls
- * for that same wallet route over USB automatically (unless pinned via
- * `switchTransport`) — matching docs/design/keystone-integration/README.md §4.3.
+ * Keystone adapter: QR and USB behind one `IHardwareWallet`, keyed by a
+ * wallet id derived from the fixed identity xpub. `_resolveUr` picks the
+ * channel per request (USB when a session exists, else QR). Key material
+ * is fetched per operation and never retained on the wallet record.
  */
 declare class KeystoneAdapter implements IHardwareWallet {
     readonly vendor: "keystone";
     private readonly urEngine;
     private readonly emitter;
+    private readonly _interactionRoutes;
+    private readonly _interactions;
     private readonly _uiRegistry;
     private readonly _jobQueue;
     private readonly _devices;
+    private readonly _searchDeviceTargets;
+    private _activeSearchGeneration;
     private readonly _origin;
     /** How long to wait for the app to answer a `REQUEST_QR_DISPLAY`/`REQUEST_QR_SCAN` before failing. Defaults to the registry's own 10-minute default. */
     private readonly _qrTimeoutMs;
     /** Optional USB `IConnector` — supplied by the host app (DI, same pattern as Trezor/Ledger), e.g. via `createKeystoneWebUsbConnector()` from `@onekeyfe/hwk-keystone-connector-usb`. Undefined means QR-only. */
     private readonly _usbConnector;
+    /** Serializes USB open/identity handshakes that run outside the job queue. */
+    private _usbConnectTail;
+    private readonly _unsettledUsbOperations;
+    private readonly _usbIdleWaiters;
+    private _usbTeardownTail;
+    private _pendingUsbTeardowns;
     /** Explicit `switchTransport` pin. `undefined` means "auto": USB when a live session exists for the target wallet, else QR. */
     private _forcedTransport;
+    private readonly _handleUsbDisconnect;
+    private readonly _handleUsbUiEvent;
     constructor(options?: {
         origin?: string;
         qrTimeoutMs?: number;
@@ -285,16 +340,20 @@ declare class KeystoneAdapter implements IHardwareWallet {
     init(_config?: unknown): Promise<void>;
     dispose(): Promise<void>;
     /**
-     * QR-synced wallets are always included (this instance's own state — no
-     * enumeration exists for QR). When a USB connector is configured, its raw
-     * scan results are appended as-is: a USB descriptor has no mfp until
-     * `connectDevice()` actually opens+claims it (see
+     * Unscoped discovery includes QR-synced wallets already known to this
+     * adapter. Explicit QR discovery returns a virtual connection target because
+     * there is no physical descriptor to enumerate. When a USB connector is
+     * configured, its raw scan results are appended as-is: a USB descriptor has
+     * no mfp until `connectDevice()` actually opens+claims it (see
      * `KeystoneUsbConnectorBase.searchDevices`), so these entries carry an
      * empty `deviceId` and exist purely so a host can list "plugged in, click
      * to connect" candidates.
      */
-    searchDevices(_options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
-    connectDevice(connectId: string): Promise<Response<string>>;
+    searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
+    private _resetUsbSessions;
+    searchDeviceTargets(options?: SearchDevicesOptions): Promise<DeviceSearchTarget[]>;
+    listConnectionTargets(options?: SearchDevicesOptions): Promise<ConnectionTarget[]>;
+    connectDevice(searchTargetId: string): Promise<Response<string>>;
     /**
      * QR has no persistent connection to tear down — the account cache
      * survives so a later call resumes without re-syncing. For a USB session,
@@ -302,8 +361,9 @@ declare class KeystoneAdapter implements IHardwareWallet {
      * QR-only (if it was ever QR-synced) or removes it entirely (pure-USB
      * wallet that was never seen over QR) — see §4.2 of the design doc.
      */
-    disconnectDevice(connectId: string): Promise<void>;
-    getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
+    releaseInteraction(interactionId: string): Promise<void>;
+    private _releaseInteractionConnection;
+    getDeviceInfo(connectIdOrInteractionId: string, deviceId: string): Promise<Response<DeviceInfo>>;
     getSupportedChains(): ChainCapability[];
     cancel(connectId?: string): void;
     getChainFingerprint(connectId: string, deviceId: string, chain: ChainForFingerprint): Promise<Response<string>>;
@@ -314,32 +374,48 @@ declare class KeystoneAdapter implements IHardwareWallet {
     off(event: string, listener: DeviceEventListener): void;
     importFromQr(options?: ImportFromQrOptions): Promise<Response<DeviceInfo>>;
     allNetworkGetAddress: (connectId: string, deviceId: string, params: AllNetworkGetAddressParams) => Promise<Response<AllNetworkAddressResponse[]>>;
-    evmGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<EvmGetAddressParams>>): Promise<Response<EvmAddress>>;
+    evmGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<EvmGetAddressParams>>, book?: AccountBook): Promise<Response<EvmAddress>>;
     evmSignTransaction(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<EvmSignTxParams>>): Promise<Response<EvmSignedTx>>;
     evmSignMessage(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<EvmSignMsgParams>>): Promise<Response<EvmSignature>>;
     evmSignTypedData(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<EvmSignTypedDataParams>>): Promise<Response<EvmSignature>>;
-    btcGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<BtcGetAddressParams>>): Promise<Response<BtcAddress>>;
-    btcGetPublicKey(_connectId?: NullableCallArg<string>, _deviceId?: NullableCallArg<string>, _params?: NullableCallArg<IHardwareCallParams<BtcGetPublicKeyParams>>): Promise<Response<BtcPublicKey>>;
+    btcGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<BtcGetAddressParams>>, book?: AccountBook): Promise<Response<BtcAddress>>;
+    /**
+     * Returns the account-level extended public key. `params.path` must be an
+     * ACCOUNT path (`m/84'/0'/0'`), not a leaf — that is the level Keystone
+     * actually syncs, and it is what a host needs to derive a whole account's
+     * addresses offline. Unlike `btcGetAddress` this has no script-type
+     * restriction: an xpub is script-type agnostic, so `86'` (taproot) works
+     * here even though deriving a taproot ADDRESS still needs an EC library
+     * this package doesn't wire in.
+     */
+    btcGetPublicKey(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<BtcGetPublicKeyParams>>, book?: AccountBook): Promise<Response<BtcPublicKey>>;
     btcSignTransaction(_connectId?: NullableCallArg<string>, _deviceId?: NullableCallArg<string>, _params?: NullableCallArg<IHardwareCallParams<BtcSignTxParams>>): Promise<Response<BtcSignedTx>>;
     btcSignPsbt(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<BtcSignPsbtParams>>): Promise<Response<BtcSignedPsbt>>;
     btcSignMessage(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<BtcSignMsgParams>>): Promise<Response<BtcSignature>>;
-    btcGetMasterFingerprint(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>): Promise<Response<{
+    btcGetMasterFingerprint(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCommonCallParams>): Promise<Response<{
         masterFingerprint: string;
     }>>;
-    solGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<SolGetAddressParams>>): Promise<Response<SolAddress>>;
+    solGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<SolGetAddressParams>>, book?: AccountBook): Promise<Response<SolAddress>>;
     solSignTransaction(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<SolSignTxParams>>): Promise<Response<SolSignedTx>>;
     solSignMessage(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<SolSignMsgParams>>): Promise<Response<SolSignature>>;
-    tronGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<TronGetAddressParams>>): Promise<Response<TronAddress>>;
+    tronGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<TronGetAddressParams>>, book?: AccountBook): Promise<Response<TronAddress>>;
     tronSignTransaction(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<TronSignTxParams>>): Promise<Response<TronSignedTx>>;
-    tronSignMessage(_connectId?: NullableCallArg<string>, _deviceId?: NullableCallArg<string>, _params?: NullableCallArg<IHardwareCallParams<TronSignMsgParams>>): Promise<Response<TronSignature>>;
-    private _mfpFromConnectId;
+    tronSignMessage(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<TronSignMsgParams>>): Promise<Response<TronSignature>>;
+    private _walletIdFromIdentifier;
+    private _allNetworkSyncSchema;
+    /**
+     * QR is an interactive batch transport: one account-creation action must
+     * produce one request QR and one response scan, regardless of how many
+     * chains or derivation paths the host bundled. USB keeps its proven
+     * one-path-at-a-time export flow because the device limits that channel.
+     */
+    private _prefetchAllNetworkAccounts;
     /**
-     * Handles both connectId shapes a caller might hand back: the QR-style
-     * `keystone-qr:<mfp>` prefix, and a bare mfp — which is exactly what a
-     * USB session's `sessionId`/`connectId` is (see `KeystoneUsbConnectorBase`
-     * and `_connectUsb`).
+     * Resolve only the stable 64-hex wallet identity. The 8-hex BIP32 master
+     * fingerprint is protocol metadata and is never accepted as a lookup key.
      */
-    private _findByConnectId;
+    private _resolveTarget;
+    private _assertParsedIdentity;
     /**
      * Folds a parsed account-response UR into the device table. `viaUsb`
      * (defaults false) says which channel actually carried this round trip —
@@ -347,99 +423,77 @@ declare class KeystoneAdapter implements IHardwareWallet {
      * already has a live session, so this must NOT unconditionally mark
      * `qrSynced`, or a USB-only wallet would wrongly survive a later USB
      * disconnect as a "QR-synced, demote to QR-only" entry instead of being
-     * dropped outright (see `disconnectDevice`).
+     * dropped outright (see `releaseInteraction`).
      */
     private _upsertDeviceRecord;
     /**
      * Opens+claims whatever Keystone the USB connector currently has
-     * permission for, learns its mfp via `getAppConfig`, and merges it into
-     * the device table by that mfp — a QR-synced entry becomes
+     * permission for, learns its protocol mfp via `getAppConfig`, then requests
+     * one fixed account-level xpub and derives the stable wallet id. A
+     * QR-synced entry becomes
      * `{qr, usb}`-capable in place (one `device-changed`, not a second
      * `device-connect`); a wallet never seen before becomes a new USB-only
      * entry. See §4.2 of the design doc.
      */
     private _connectUsb;
+    private _connectUsbExclusive;
+    /**
+     * Probe already-authorized USB devices without opening a permission picker,
+     * then attach and verify the requested wallet when one is present. This is
+     * used both after an adapter restart and after a QR-only period, so plugging
+     * USB back in affects the next business call without changing an in-flight
+     * QR interaction.
+     */
+    private _tryUsbAttach;
     /**
      * The one place that decides QR vs. USB for a UR round trip and carries it
      * out. `record` is the (possibly not-yet-existing, for a true cold start)
-     * device row for the target wallet — USB is only used when `record`
-     * already has a live `usbSessionId` (a session comes from an explicit
-     * `connectDevice()`, never conjured mid-call — see the class doc). A
+     * device row for the target wallet. USB is the preferred channel: a known
+     * wallet record with no live session gets ONE best-effort re-attach here,
+     * and anything that goes wrong just leaves the call on QR. A
      * `switchTransport('qr')` pin forces QR even for a USB-attached wallet;
      * `switchTransport('usb')` on a wallet with no live USB session fails
      * closed rather than silently falling back to QR.
      */
     private _resolveUr;
+    private _resolveUrWithRoute;
     /**
-     * Resolve (syncing over QR if needed) the account cached for `hwkChain` at
-     * `syncPath`. Drives the "implicit account sync, then the real request" two
-     * hop flow the first time a wallet/path pair is seen; a cache hit skips
-     * straight to the caller's own round trip.
+     * Fetch one account's key material from the device for this operation only.
+     * `book` lets earlier fetches of the same operation be reused; nothing is
+     * retained on the record. On a USB drop the remaining paths fall back to one
+     * QR request.
      */
-    private _ensureAccountSynced;
+    private _fetchAccount;
     /**
-     * Like `_ensureAccountSynced`, but for operations (PSBT signing, master
+     * Like `_fetchAccount`, but for operations (PSBT signing, master
      * fingerprint) that only need to know WHICH wallet is attached, not a
      * specific cached path. Syncs the account-level path for `chain` as a
-     * throwaway probe when the mfp isn't already known.
+     * throwaway probe when the wallet record isn't already known.
      *
      * `CHAIN_FINGERPRINT_PATHS[chain]` is a 5-segment LEAF path for `evm`
      * (`m/44'/60'/0'/0/0`) — sending that verbatim as a KeyDerivation request
      * asks Keystone for a non-standard path. Keystone's own docs
      * (dev.keyst.one's multichain KeyDerivation example) show the ETH
      * account-level path as `m/44'/60'/0'` (3 segments), same as what
-     * `DEFAULT_IMPORT_SCHEMAS`/`_ensureAccountSynced` already request — so
+     * `_fetchAccount` already requests — so
      * truncate through `splitAccountPath` here too instead of using the raw
      * fingerprint leaf path. `btc`/`sol` are already 3-segment account paths
      * and pass through unchanged.
      */
-    private _ensureMfpKnown;
+    private _ensureWalletKnown;
     private _requestQrDisplayAndAwaitResponse;
     private _requestQrScanAndAwaitResponse;
+    private _callUsbConnector;
+    private _runUsbTeardown;
+    private _waitForUsbOperationsToDrain;
+    private _retainUsbOperation;
+    private static _abortable;
     private static _throwIfAborted;
     private static _assertRequestIdMatches;
     private _unsupported;
     private _errorToFailure;
 }
 
-/** `keystone-qr:<mfp>` is the QR-only connectId; a merged USB session gets its own (phase 4). */
-declare const QR_CONNECT_ID_PREFIX = "keystone-qr:";
-declare function qrConnectId(masterFingerprint: string): string;
-interface KeystoneAccountEntry extends KeystoneParsedAccount {
-    hwkChain: ChainCapability;
-}
-declare function accountKey(hwkChain: ChainCapability, path: string): string;
-interface KeystoneDeviceRecord {
-    /** Lowercase hex BIP32 master fingerprint — the cross-channel wallet identity; doubles as `deviceId`. */
-    masterFingerprint: string;
-    connectId: string;
-    /** Model string from the device (e.g. "Keystone 3 Pro"); not unique per unit. */
-    model?: string;
-    deviceVersion?: string;
-    /** Keyed by `accountKey(hwkChain, path)`. Holds whatever was directly synced — usually account-level (3-segment) entries for EVM, exact leaf entries for SOL. */
-    accounts: Map<string, KeystoneAccountEntry>;
-    importedAt: number;
-    /**
-     * Set to the connector's `sessionId` (== this record's own mfp, per
-     * `KeystoneUsbConnectorBase.connect`) once a live USB session exists for
-     * this wallet. Cleared by `disconnectDevice`. Presence of this field is
-     * what `KeystoneAdapter._resolveUr` uses to route a call over USB instead
-     * of QR.
-     */
-    usbSessionId?: string;
-    /**
-     * True once this wallet has completed at least one QR round trip.
-     * Distinguishes "USB session dropped but this wallet was also QR-synced —
-     * fall back to a QR-only entry" from "this was a USB-only wallet that
-     * never synced over QR — drop the entry entirely" on USB disconnect.
-     */
-    qrSynced?: boolean;
-}
-declare function createDeviceRecord(masterFingerprint: string): KeystoneDeviceRecord;
-declare function toDeviceInfo(record: KeystoneDeviceRecord): DeviceInfo;
-/** A device row for a wallet the adapter hasn't synced yet — used while a cold-start round trip is in flight. */
-declare function placeholderDeviceInfo(): DeviceInfo;
-
 /** Always returns an `m/`-prefixed path, regardless of the input's casing/prefix. */
 declare function normalizePath(path: string): string;
 /**
@@ -465,4 +519,4 @@ declare function splitAccountPath(path: string): {
  */
 declare function btcScriptTypeFromPath(path: string): BtcScriptType | undefined;
 
-export { type BtcScriptType, type ImportFromQrOptions, type KeystoneAccountEntry, KeystoneAdapter, type KeystoneBtcSignRequestAccount, type KeystoneBtcSignatureResult, type KeystoneDerivationCurve, type KeystoneDeviceRecord, type KeystoneEthSignRequestInput, type KeystoneEthSignatureResult, type KeystoneKeyDerivationRequestInput, type KeystoneKeySchema, type KeystoneParsedAccount, type KeystoneParsedMultiAccounts, type KeystoneSolSignRequestInput, type KeystoneSolSignatureResult, type KeystoneTronSignRequestInput, type KeystoneTronSignatureResult, type KeystoneUr, KeystoneUrEngine, QR_CONNECT_ID_PREFIX, accountKey, btcScriptTypeFromPath, createDeviceRecord, normalizePath, placeholderDeviceInfo, qrConnectId, splitAccountPath, toDeviceInfo };
+export { type BtcScriptType, type ImportFromQrOptions, KEYSTONE_WALLET_CONNECT_ID_PREFIX, KEYSTONE_WALLET_ID_PATH, type KeystoneAccountEntry, KeystoneAdapter, type KeystoneBtcSignRequestAccount, type KeystoneBtcSignatureResult, type KeystoneDerivationCurve, type KeystoneDeviceRecord, type KeystoneEthSignRequestInput, type KeystoneEthSignatureResult, type KeystoneKeyDerivationRequestInput, type KeystoneKeySchema, type KeystoneParsedAccount, type KeystoneParsedMultiAccounts, type KeystoneSolSignRequestInput, type KeystoneSolSignatureResult, type KeystoneTronSignRequestInput, type KeystoneTronSignatureResult, type KeystoneUr, KeystoneUrEngine, accountKey, btcScriptTypeFromPath, createDeviceRecord, deriveKeystoneWalletId, normalizePath, placeholderDeviceInfo, splitAccountPath, toDeviceInfo, walletConnectId };