@onekeyfe/hwk-keystone-adapter 1.2.3-alpha.8 → 1.2.5-alpha.1

package/dist/index.d.mts

@@ -7,15 +7,8 @@ declare enum TronSignType {
 }
 
 /**
- * A UR payload in the wire shape the reserved `QrDisplayData`/`QrResponseData`
- * (from `@onekeyfe/hwk-adapter-core`) already commit to: `urType` + `urData`.
- *
- * `urData` is the hex-encoded raw CBOR payload (equivalent to `ur.cbor.toString('hex')`),
- * NOT a `ur:type/…` bech32-style string and NOT a pre-fragmented animated-QR frame
- * list. Turning this into single- or multi-part QR frames is a rendering concern the
- * app/UI layer owns (via `@ngraveio/bc-ur`'s `UREncoder`), not something the engine
- * or the event payload should bake in — `QrDisplayData.animated` is only a hint that
- * the payload is large enough to need fragmenting.
+ * `urData` is the hex-encoded raw CBOR payload, not a `ur:` string or QR frame list; the UI layer
+ * owns fragmenting into animated QR frames.
  */
 interface KeystoneUr {
     urType: string;
@@ -36,9 +29,8 @@ interface KeystoneParsedMultiAccounts {
     /** Model string (e.g. "Keystone 3 Pro"), present on both channels but not unique per unit. */
     device?: string;
     /**
-     * Hardware-derived id (sha256(sha256(serial))). Only populated in specific
-     * wallet-branded QR sync menus — firmware omits it on the generic
-     * KeyDerivation path USB uses. Enrichment only; never key identity on it.
+     * sha256(sha256(serial)), only sent by some QR sync menus and never on the KeyDerivation path.
+     * Enrichment only; never key identity on it.
      */
     deviceId?: string;
     deviceVersion?: string;
@@ -46,7 +38,7 @@ interface KeystoneParsedMultiAccounts {
 }
 interface KeystoneEthSignRequestInput {
     requestId: string;
-    /** Hex, no 0x prefix — raw unsigned payload matching dataType. */
+    /** Hex, no 0x prefix, raw unsigned payload matching dataType. */
     unsignedTxHex: string;
     dataType: 'transaction' | 'typedTransaction' | 'personalMessage' | 'typedData';
     path: string;
@@ -67,12 +59,7 @@ interface KeystoneBtcSignRequestAccount {
     xfp: string;
     address?: string;
 }
-/**
- * Standard BIP-44/49/84/86 purpose → script-type mapping. `p2tr` is a
- * recognized value but `KeystoneUrEngine.deriveBtcAddressFromXpub` doesn't
- * support it yet — taproot output-key tweaking needs an elliptic-curve
- * library (`bitcoinjs-lib`'s `initEccLib`) this package doesn't wire in.
- */
+/** Script types for purposes 44'/49'/84'/86'; `p2tr` address derivation is not supported yet. */
 type BtcScriptType = 'p2pkh' | 'p2sh-p2wpkh' | 'p2wpkh' | 'p2tr';
 interface KeystoneSolSignRequestInput {
     requestId: string;
@@ -95,7 +82,7 @@ interface KeystoneBtcSignatureResult {
     /** Hex, no 0x prefix. */
     signature: string;
 }
-/** SLIP-10 for secp256k1 (EVM/BTC) and ed25519 (SOL); Cardano-style BIP32-Ed25519 is out of scope. */
+/** SLIP-10 secp256k1 (EVM/BTC) and ed25519 (SOL); Cardano BIP32-Ed25519 is out of scope. */
 type KeystoneDerivationCurve = 'secp256k1' | 'ed25519';
 interface KeystoneKeySchema {
     path: string;
@@ -108,9 +95,8 @@ interface KeystoneKeyDerivationRequestInput {
 interface KeystoneTronSignRequestInput {
     requestId: string;
     /**
-     * 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.
+     * Hex, no 0x prefix: protobuf `Transaction.raw` bytes, or raw message bytes (the device applies
+     * the TIP-191 prefix itself).
      */
     rawTxHex: string;
     path: string;
@@ -121,14 +107,13 @@ interface KeystoneTronSignRequestInput {
 }
 interface KeystoneTronSignatureResult {
     requestId?: string;
-    /** Hex, no 0x prefix — 65-byte secp256k1 signature. */
+    /** Hex, no 0x prefix, 65-byte secp256k1 signature. */
     signature: string;
 }
 
 /**
- * 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.
+ * Single touch point with `@keystonehq/keystone-sdk`, shared by QR and USB. Uses the bare
+ * constructor: `KeystoneSDK.create()` fetches remote config at call time.
  */
 declare class KeystoneUrEngine {
     private readonly sdk;
@@ -136,60 +121,22 @@ declare class KeystoneUrEngine {
     parseMultiAccounts(ur: KeystoneUr): KeystoneParsedMultiAccounts;
     parseHDKey(ur: KeystoneUr): KeystoneParsedAccount;
     /**
-     * Build a `qr-hardware-call` (KeyDerivation) request: the host asks for
-     * specific paths instead of waiting for whatever the device happens to be
-     * showing. The device replies with a `crypto-multi-accounts` UR — parse it
-     * with `parseMultiAccounts`. Used for the implicit "sync this wallet's xfp
-     * before the first sign" round trip as well as an explicit account import.
-     *
-     * `version: V1` is required — verified against real Keystone hardware and
-     * `keystone3-firmware`'s `CheckHardwareCallRequestIsLegal` source: an
-     * unversioned/V0 request is validated as a legacy Cardano-only request
-     * (`m/1852'/1815'/...`) and firmware rejects every other chain's path with
-     * `PRS_PARSING_ERROR` (device-shown message: "路径不受支持" / "path not
-     * supported"), regardless of the path's shape. V1 is what actually enables
-     * the general per-chain path whitelist (includes `m/44'/60'` for ETH, the
-     * standard BTC purposes, etc.). The SDK itself defaults to V0 unless a
-     * truthy `version` is passed — omitting this silently produces a request
-     * every non-Cardano device rejects.
+     * Builds a KeyDerivation request. `version: V1` is required: firmware validates V0 (the SDK
+     * default) as Cardano-only and rejects other paths with `PRS_PARSING_ERROR`.
      */
     buildKeyDerivationRequest(input: KeystoneKeyDerivationRequestInput): KeystoneUr;
     /**
-     * Parse the response to a KeyDerivation request (or a device-initiated
-     * account export): `crypto-multi-accounts` for a multi-schema request,
-     * `crypto-hdkey` for a single-key response some firmware paths use instead.
-     * Both are normalized to the same `KeystoneParsedMultiAccounts` shape — a
-     * single `crypto-hdkey` becomes a one-entry account list, with its own
-     * `origin.sourceFingerprint` promoted to `masterFingerprint` (correct for a
-     * key derived directly from the seed, which every request this engine
-     * builds asks for).
+     * Normalizes `crypto-multi-accounts` and the single-key `crypto-hdkey` some firmware returns. The
+     * hdkey source fingerprint is the mfp only because every request here derives from the seed.
      */
     parseAccountResponse(ur: KeystoneUr): KeystoneParsedMultiAccounts;
     buildEthSignRequest(input: KeystoneEthSignRequestInput): KeystoneUr;
     parseEthSignature(ur: KeystoneUr): KeystoneEthSignatureResult;
-    /**
-     * Derive one EVM address offline from an already-synced account xpub —
-     * verified against the same `@keystonehq/bc-ur-registry-eth` helper the
-     * Keystone-based OneKey air-gap demo uses in production
-     * (`generateAddressFromXpub`), so no unverified assumption about what a
-     * leaf-path KeyDerivation request would return. `relativeDerivePath` is
-     * relative to the xpub's own depth, e.g. `'0/0'` for an account xpub.
-     */
+    /** Derives an EVM address offline; `relativeDerivePath` is relative to the xpub, e.g. `'0/0'`. */
     deriveEvmAddressFromXpub(xpub: string, relativeDerivePath: string): string;
     /**
-     * Derive one BTC address offline from an already-synced account xpub, the
-     * same way `deriveEvmAddressFromXpub` does. Keystone's `CryptoHDKey`
-     * always emits standard mainnet-xpub version bytes (`0488B21E`) regardless
-     * of the account's purpose/script type (verified against
-     * `@keystonehq/bc-ur-registry`'s `CryptoHDKey.getBip32Key`, which hardcodes
-     * that version rather than switching to a SLIP-132 ypub/zpub prefix per
-     * script type) — so `hdkey.fromExtendedKey` parses it correctly for every
-     * `scriptType` without needing custom version bytes configured.
-     *
-     * `p2tr` is deliberately not handled: taproot output-key tweaking (BIP-341)
-     * needs an elliptic-curve library wired via bitcoinjs-lib's `initEccLib`,
-     * which this package doesn't set up yet — every other payment function
-     * here needs no such library.
+     * `CryptoHDKey` always emits mainnet xpub version bytes (`0488B21E`), so `hdkey` parses it as is.
+     * `p2tr` needs an ECC lib for BIP-341 tweaking, not wired here.
      */
     deriveBtcAddressFromXpub(xpub: string, relativeDerivePath: string, scriptType: BtcScriptType): string;
     deriveBtcAddressFromPublicKey(publicKeyHex: string, scriptType: BtcScriptType): string;
@@ -213,23 +160,11 @@ declare class KeystoneUrEngine {
     buildTronSignRequest(input: KeystoneTronSignRequestInput): KeystoneUr;
     parseTronSignature(ur: KeystoneUr): KeystoneTronSignatureResult;
     /**
-     * Derive one TRON address offline from an already-synced account xpub.
-     * TRON reuses EVM's exact secp256k1-pubkey → keccak256 → last-20-bytes
-     * derivation (verified against Keystone's own `formatAddress()` in
-     * `keystone-sdk`'s TRON chain source) — only the final text encoding
-     * differs (base58check with a `0x41` version byte, not checksummed hex).
-     * Reusing `generateAddressFromXpub` here means no new hashing dependency:
-     * strip its "0x" and re-encode the same 20 bytes.
+     * TRON uses the same 20 address bytes as EVM (Keystone's `formatAddress()`), re-encoded as
+     * base58check with the `0x41` version byte.
      */
     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.
-     */
+    /** Decodes an xpub's BIP-32 fields; `parentFingerprint` is the parent key's, not the mfp. */
     parseXpubMeta(xpub: string): {
         publicKey: string;
         chainCode: string;
@@ -239,17 +174,15 @@ declare class KeystoneUrEngine {
 }
 
 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;
+/** Account a QR cold start requests when the caller named no path; any path returns the mfp. */
+declare const KEYSTONE_COLD_START_PATH = "m/44'/60'/0'";
+declare function walletConnectId(masterFingerprint: 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. */
+    /** Lowercase 8-char BIP32 master fingerprint: the wallet identity and the BC-UR xfp. */
     masterFingerprint: string;
     connectId: string;
     /** Optional physical-device id exposed by some Keystone QR export menus. */
@@ -258,49 +191,33 @@ interface KeystoneDeviceRecord {
     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 `releaseOperation`. Presence of this field is
-     * what `KeystoneAdapter._resolveUr` uses to route a call over USB instead
-     * of QR.
-     */
+    /** Connector session id while a live USB session exists; its presence routes calls over USB. */
     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.
+     * Stays true after the USB session is lost, so only these wallets wait through the device's
+     * USB re-enumeration window.
      */
     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.
-     */
+    /** True after one QR round trip; on USB disconnect it decides demote-to-QR versus drop. */
     qrSynced?: boolean;
 }
-declare function deriveKeystoneWalletId(accounts: KeystoneParsedAccount[]): string;
-declare function createDeviceRecord(walletId: string, masterFingerprint: string): KeystoneDeviceRecord;
+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. */
+/** Device row for a not-yet-synced wallet during a cold-start round trip. */
 declare function placeholderDeviceInfo(): DeviceInfo;
 
 /** Key material for one operation, keyed by `accountKey()`; never retained. */
 type AccountBook = Map<string, KeystoneAccountEntry>;
 interface ImportFromQrOptions {
     /**
-     * '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.
+     * 'request' asks the device for one account; 'scan' waits for whatever export it already shows.
+     * Only the wallet's master fingerprint is learned either way.
      */
     mode?: 'request' | 'scan';
 }
 /**
- * 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.
+ * QR and USB behind one `IHardwareWallet`, keyed by the wallet's BIP32 master fingerprint.
+ * Key material is fetched per operation and never retained.
  */
 declare class KeystoneAdapter implements IHardwareWallet {
     readonly vendor: "keystone";
@@ -315,17 +232,18 @@ declare class KeystoneAdapter implements IHardwareWallet {
     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. */
+    /** Host answer timeout for QR display/scan requests; undefined uses the registry 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. */
+    /** Host-supplied USB connector; 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 _abandonedUsbConnects;
     private _usbTeardownTail;
     private _pendingUsbTeardowns;
-    /** Explicit `switchTransport` pin. `undefined` means "auto": USB when a live session exists for the target wallet, else QR. */
+    /** `switchTransport` pin; undefined means USB when the wallet has a live session, else QR. */
     private _forcedTransport;
     private readonly _handleUsbDisconnect;
     private readonly _handleUsbUiEvent;
@@ -336,31 +254,24 @@ declare class KeystoneAdapter implements IHardwareWallet {
     });
     get activeTransport(): TransportType | null;
     getAvailableTransports(): TransportType[];
-    /** Pins subsequent calls to 'qr' or 'usb' (routing otherwise defaults to "USB when the target wallet has a live session, else QR" — see `_resolveUr`). Any other value clears the pin back to auto. */
+    /** Pins calls to 'qr' or 'usb'; any other value clears the pin back to auto routing. */
     switchTransport(type: TransportType): Promise<void>;
     init(_config?: unknown): Promise<void>;
     dispose(): Promise<void>;
     /**
-     * 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.
+     * Returns known wallets plus USB scan results; USB entries have no mfp until `connectDevice()`
+     * claims them. Explicit QR discovery returns one virtual target.
      */
     searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
     private _resetUsbSessions;
+    /** Best-effort disconnect; the session is retired either way so it cannot be selected again. */
+    private _retireUsbSession;
     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,
-     * this closes the connector session and either demotes the record back to
-     * 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.
+     * QR has nothing to tear down. A USB session is closed, and the record is demoted to QR-only or
+     * removed if it was never QR-synced.
      */
     releaseOperation(operationId: string): Promise<void>;
     private _releaseOperationConnection;
@@ -374,127 +285,88 @@ 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>>, 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>>, book?: AccountBook): Promise<Response<BtcAddress>>;
+    evmGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<EvmGetAddressParams>>, book?: AccountBook): Promise<Response<EvmAddress>>;
+    evmSignTransaction(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<EvmSignTxParams>>): Promise<Response<EvmSignedTx>>;
+    evmSignMessage(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<EvmSignMsgParams>>): Promise<Response<EvmSignature>>;
+    evmSignTypedData(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<EvmSignTypedDataParams>>): Promise<Response<EvmSignature>>;
+    btcGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: 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.
+     * `params.path` must be an account path (`m/84'/0'/0'`), the level Keystone syncs. An xpub is
+     * script-type agnostic, so `86'` works here even though `btcGetAddress` rejects it.
      */
-    btcGetPublicKey(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<BtcGetPublicKeyParams>>, book?: AccountBook): Promise<Response<BtcPublicKey>>;
+    btcGetPublicKey(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: 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>>;
+    btcSignPsbt(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<BtcSignPsbtParams>>): Promise<Response<BtcSignedPsbt>>;
+    btcSignMessage(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<BtcSignMsgParams>>): Promise<Response<BtcSignature>>;
     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>>, 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>>, book?: AccountBook): Promise<Response<TronAddress>>;
-    tronSignTransaction(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<TronSignTxParams>>): Promise<Response<TronSignedTx>>;
-    tronSignMessage(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, paramsArg?: NullableCallArg<IHardwareCallParams<TronSignMsgParams>>): Promise<Response<TronSignature>>;
-    private _walletIdFromIdentifier;
-    private _allNetworkSyncSchema;
+    solGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<SolGetAddressParams>>, book?: AccountBook): Promise<Response<SolAddress>>;
+    solSignTransaction(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<SolSignTxParams>>): Promise<Response<SolSignedTx>>;
+    solSignMessage(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<SolSignMsgParams>>): Promise<Response<SolSignature>>;
+    tronGetAddress(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<TronGetAddressParams>>, book?: AccountBook): Promise<Response<TronAddress>>;
+    tronSignTransaction(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<TronSignTxParams>>): Promise<Response<TronSignedTx>>;
+    tronSignMessage(connectIdArg?: NullableCallArg<string>, deviceIdArg?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<TronSignMsgParams>>): Promise<Response<TronSignature>>;
+    private _runJob;
+    private _fetchAccountXpub;
     /**
-     * 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.
+     * Signing needs only the wallet's mfp: the device re-derives the key from path+xfp, so no
+     * per-path account lookup happens here.
      */
-    private _prefetchAllNetworkAccounts;
+    private _signWithWallet;
+    private _allNetworkSyncSchema;
     /**
-     * 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.
+     * QR answers the whole bundle with one request QR and one scan. USB exports one path per
+     * request because the device limits that channel.
      */
+    private _prefetchAllNetworkAccounts;
+    /** Resolve the wallet's master fingerprint from the connectId and/or deviceId the caller passed. */
     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 —
-     * `_resolveUr` routes a KeyDerivation sync over USB when the target record
-     * 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 `releaseOperation`).
+     * Folds a parsed account response into the device table. Only non-USB round trips mark
+     * `qrSynced`, so a USB-only wallet is dropped on disconnect.
      */
     private _upsertDeviceRecord;
     /**
-     * Opens+claims whatever Keystone the USB connector currently has
-     * 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.
+     * Opens a permitted USB Keystone and takes its mfp as the wallet identity. A known wallet gains
+     * USB in place (`device-changed`); an unseen one becomes USB-only.
      */
     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 operation.
+     * Probes already-authorized USB devices without a permission picker, then attaches and verifies
+     * the requested wallet if present.
      */
     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 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.
+     * Decides QR vs USB for one UR round trip. A pinned 'usb' with no live session fails closed;
+     * otherwise a failed USB reattach leaves the call on QR.
      */
     private _resolveUr;
     private _resolveUrWithRoute;
+    /** Ends the operation as disconnected and returns the error to throw. */
+    private _endDisconnectedOperation;
     /**
-     * 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. A failed USB export ends this operation without
-     * replaying the request or switching transports.
+     * Fetches one account's key material for this operation only; `book` reuses earlier fetches. A
+     * failed USB export ends the operation without replaying or switching transports.
      */
     private _fetchAccount;
     /**
-     * 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 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
-     * `_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.
+     * Resolves which wallet is attached, without a per-path account. `CHAIN_FINGERPRINT_PATHS.evm` is
+     * a leaf path, so it is cut to the account path Keystone expects.
      */
     private _ensureWalletKnown;
     /**
-     * The operation the running device job belongs to, so a UI request raised
-     * mid-call can name it. A call pinned to an operation queues under its id
-     * (`keystoneQueueKey`); a call without one queues under the wallet id or the
-     * wallet connectId, and the live operation routed to that connection is still
-     * the owner. Only a cold start comes back undefined.
+     * The operation owning the running job, so a mid-call UI request can name it. Unpinned jobs map
+     * through the operation route; a cold start returns undefined.
      */
     private _activeOperationId;
-    /** Routes are keyed by connectId; a job key may be the bare wallet id. */
+    /** Routes are keyed by connectId; a job key may be the bare master fingerprint. */
     private _operationRouteForIdentifier;
     /**
-     * A QR prompt has no transport to interrupt, so an aborted job would sit here
-     * until the QR timeout. Releasing the registry slot on abort is what lets a
-     * cancel reach the wait at all.
+     * A QR prompt has no transport to interrupt; releasing the registry slot on abort is what lets
+     * a cancel reach the wait before the QR timeout.
      */
     private _awaitQrResponse;
     private _requestQrDisplayAndAwaitResponse;
@@ -513,26 +385,14 @@ declare class KeystoneAdapter implements IHardwareWallet {
 /** Always returns an `m/`-prefixed path, regardless of the input's casing/prefix. */
 declare function normalizePath(path: string): string;
 /**
- * Split a full BIP-44 leaf path (`purpose'/coin'/account'/change/index`, 5
- * segments) into its 3-segment account path and the relative `change/index`
- * path from that account to the leaf. Matches the OneKey Keystone air-gap
- * demo's `removePathLastSegment({removeCount: 2})` convention, which is
- * verified against real Keystone hardware.
- *
- * A path with 3 or fewer segments IS already an account path (or shorter) —
- * BIP-44's account level is exactly 3 hardened components — so there is
- * nothing to split off: `relativeDerivePath` is empty and `accountPath` is
- * the (normalized) input unchanged.
+ * Splits a 5-segment BIP-44 leaf path into the 3-segment account path and the relative
+ * `change/index`; a path of 3 or fewer segments is already an account path.
  */
 declare function splitAccountPath(path: string): {
     accountPath: string;
     relativeDerivePath: string;
 };
-/**
- * Standard BIP-44/49/84/86 purpose → script-type mapping. Returns `undefined`
- * for a path whose purpose isn't one of these four (or isn't parseable),
- * rather than guessing.
- */
+/** BIP-44/49/84/86 purpose to script type; undefined for any other purpose. */
 declare function btcScriptTypeFromPath(path: string): BtcScriptType | undefined;
 
-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 };
+export { type BtcScriptType, type ImportFromQrOptions, KEYSTONE_COLD_START_PATH, KEYSTONE_WALLET_CONNECT_ID_PREFIX, 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, normalizePath, placeholderDeviceInfo, splitAccountPath, toDeviceInfo, walletConnectId };