@onekeyfe/hwk-keystone-adapter 1.2.2-alpha.100

package/dist/index.mjs

@@ -0,0 +1,1565 @@
+// src/urEngine/KeystoneUrEngine.ts
+import { generateAddressFromXpub } from "@keystonehq/bc-ur-registry-eth";
+import { Curve, KeystoneSDK, QRHardwareCallVersion, UR } from "@keystonehq/keystone-sdk";
+import bs58check from "bs58check";
+import * as bitcoin from "bitcoinjs-lib";
+import HDKey from "hdkey";
+import { parse as uuidParse, stringify as uuidStringify } from "uuid";
+
+// src/urEngine/TronSignRequest.ts
+import {
+  CryptoKeypath,
+  DataItem,
+  PathComponent,
+  RegistryItem,
+  RegistryType,
+  RegistryTypes,
+  extend
+} from "@keystonehq/bc-ur-registry";
+var { decodeToDataItem } = extend;
+var TRON_SIGN_REQUEST_TYPE = new RegistryType("tron-sign-request", 5201);
+var TronSignRequest = class _TronSignRequest extends RegistryItem {
+  constructor(args) {
+    super();
+    this.getRegistryType = () => TRON_SIGN_REQUEST_TYPE;
+    this.getRequestId = () => this.requestId;
+    this.getSignData = () => this.signData;
+    this.getSignType = () => this.signType;
+    this.getDerivationPath = () => this.derivationPath.getPath();
+    this.toDataItem = () => {
+      const map = {};
+      if (this.requestId) {
+        map[1 /* requestId */] = new DataItem(this.requestId, RegistryTypes.UUID.getTag());
+      }
+      if (this.address) map[4 /* address */] = this.address;
+      if (this.origin) map[5 /* origin */] = this.origin;
+      map[2 /* signData */] = this.signData;
+      map[6 /* signType */] = this.signType;
+      const keyPath = this.derivationPath.toDataItem();
+      keyPath.setTag(this.derivationPath.getRegistryType().getTag());
+      map[3 /* derivationPath */] = keyPath;
+      return new DataItem(map);
+    };
+    this.requestId = args.requestId;
+    this.signData = args.signData;
+    this.derivationPath = args.derivationPath;
+    this.address = args.address;
+    this.origin = args.origin;
+    this.signType = args.signType;
+  }
+  static fromDataItem(dataItem) {
+    const map = dataItem.getData();
+    const signData = map[2 /* signData */];
+    const derivationPath = CryptoKeypath.fromDataItem(map[3 /* derivationPath */]);
+    const address = map[4 /* address */];
+    const requestIdItem = map[1 /* requestId */];
+    const requestId = requestIdItem?.getData();
+    const origin = map[5 /* origin */];
+    const signType = map[6 /* signType */];
+    return new _TronSignRequest({ requestId, signData, derivationPath, address, origin, signType });
+  }
+  static fromCBOR(cborPayload) {
+    return _TronSignRequest.fromDataItem(decodeToDataItem(cborPayload));
+  }
+  static parsePath(path, xfp) {
+    const segments = path.replace(/^[mM]\//, "").split("/");
+    const components = segments.map((segment) => {
+      const hardened = segment.endsWith("'");
+      return new PathComponent({
+        index: parseInt(hardened ? segment.slice(0, -1) : segment, 10),
+        hardened
+      });
+    });
+    return new CryptoKeypath(components, Buffer.from(xfp, "hex"));
+  }
+};
+
+// src/urEngine/TronSignature.ts
+import {
+  DataItem as DataItem2,
+  RegistryItem as RegistryItem2,
+  RegistryType as RegistryType2,
+  RegistryTypes as RegistryTypes2,
+  extend as extend2
+} from "@keystonehq/bc-ur-registry";
+var { decodeToDataItem: decodeToDataItem2 } = extend2;
+var TRON_SIGNATURE_TYPE = new RegistryType2("tron-signature", 5202);
+var TronSignature = class _TronSignature extends RegistryItem2 {
+  constructor(signature, requestId) {
+    super();
+    this.getRegistryType = () => TRON_SIGNATURE_TYPE;
+    this.getRequestId = () => this.requestId;
+    this.getSignature = () => this.signatureBytes;
+    this.toDataItem = () => {
+      const map = {};
+      if (this.requestId) {
+        map[1 /* requestId */] = new DataItem2(this.requestId, RegistryTypes2.UUID.getTag());
+      }
+      map[2 /* signature */] = this.signatureBytes;
+      return new DataItem2(map);
+    };
+    this.signatureBytes = signature;
+    this.requestId = requestId;
+  }
+  static fromDataItem(dataItem) {
+    const map = dataItem.getData();
+    const signature = map[2 /* signature */];
+    const requestIdItem = map[1 /* requestId */];
+    const requestId = requestIdItem?.getData();
+    return new _TronSignature(signature, requestId);
+  }
+  static fromCBOR(cborPayload) {
+    return _TronSignature.fromDataItem(decodeToDataItem2(cborPayload));
+  }
+};
+
+// src/urEngine/KeystoneUrEngine.ts
+var TRON_ADDRESS_PREFIX = 65;
+function stripHexPrefix(hex) {
+  return hex.replace(/^0x/i, "");
+}
+var ETH_DATA_TYPE = {
+  transaction: 1,
+  typedData: 2,
+  personalMessage: 3,
+  typedTransaction: 4
+};
+var DERIVATION_CURVE = {
+  secp256k1: Curve.secp256k1,
+  ed25519: Curve.ed25519
+};
+function toSdkUr(ur) {
+  return new UR(Buffer.from(ur.urData, "hex"), ur.urType);
+}
+function fromSdkUr(ur) {
+  return { urType: ur.type, urData: ur.cbor.toString("hex") };
+}
+function splitSignature65(hex) {
+  return { r: hex.slice(0, 64), s: hex.slice(64, 128), v: hex.slice(128) };
+}
+var KeystoneUrEngine = class {
+  constructor(origin = "OneKey") {
+    this.sdk = new KeystoneSDK({ origin });
+  }
+  // --- Account sync (works for both a device-initiated QR export and a
+  // wallet-initiated KeyDerivation request/response over either channel) ---
+  parseMultiAccounts(ur) {
+    const parsed = this.sdk.parseMultiAccounts(toSdkUr(ur));
+    return {
+      masterFingerprint: parsed.masterFingerprint.toLowerCase(),
+      device: parsed.device,
+      deviceId: parsed.deviceId,
+      deviceVersion: parsed.deviceVersion,
+      accounts: parsed.keys.map(
+        (key) => ({
+          chain: key.chain,
+          path: key.path,
+          publicKey: key.publicKey,
+          extendedPublicKey: key.extendedPublicKey,
+          xfp: key.xfp,
+          name: key.name
+        })
+      )
+    };
+  }
+  parseHDKey(ur) {
+    const key = this.sdk.parseHDKey(toSdkUr(ur));
+    return {
+      chain: key.chain,
+      path: key.path,
+      publicKey: key.publicKey,
+      extendedPublicKey: key.extendedPublicKey,
+      xfp: key.xfp,
+      name: key.name
+    };
+  }
+  /**
+   * 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.
+   */
+  buildKeyDerivationRequest(input) {
+    const ur = this.sdk.generateKeyDerivationCall({
+      schemas: input.schemas.map((schema) => ({
+        path: schema.path,
+        curve: DERIVATION_CURVE[schema.curve ?? "secp256k1"]
+      })),
+      origin: input.origin,
+      version: QRHardwareCallVersion.V1
+    });
+    return fromSdkUr(ur);
+  }
+  /**
+   * 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).
+   */
+  parseAccountResponse(ur) {
+    if (ur.urType === "crypto-hdkey") {
+      const account = this.parseHDKey(ur);
+      if (!account.xfp) {
+        throw new Error("Keystone crypto-hdkey response is missing its source fingerprint");
+      }
+      return { masterFingerprint: account.xfp.toLowerCase(), accounts: [account] };
+    }
+    return this.parseMultiAccounts(ur);
+  }
+  // --- EVM ---
+  buildEthSignRequest(input) {
+    const ur = this.sdk.eth.generateSignRequest({
+      requestId: input.requestId,
+      signData: input.unsignedTxHex,
+      dataType: ETH_DATA_TYPE[input.dataType],
+      path: input.path,
+      xfp: input.xfp,
+      chainId: input.chainId,
+      address: input.address,
+      origin: input.origin
+    });
+    return fromSdkUr(ur);
+  }
+  parseEthSignature(ur) {
+    const signature = this.sdk.eth.parseSignature(toSdkUr(ur));
+    return { requestId: signature.requestId, ...splitSignature65(signature.signature) };
+  }
+  /**
+   * 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.
+   */
+  deriveEvmAddressFromXpub(xpub, relativeDerivePath) {
+    return generateAddressFromXpub(xpub, `m/${relativeDerivePath.replace(/^m\//i, "")}`);
+  }
+  // --- BTC (PSBT transaction signing + plain message signing) ---
+  /**
+   * 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.
+   */
+  deriveBtcAddressFromXpub(xpub, relativeDerivePath, scriptType) {
+    const node = HDKey.fromExtendedKey(xpub).derive(`m/${relativeDerivePath.replace(/^m\//i, "")}`);
+    if (!node.publicKey) throw new Error("HDKey derivation did not produce a public key");
+    const pubkey = Buffer.from(node.publicKey);
+    const network = bitcoin.networks.bitcoin;
+    switch (scriptType) {
+      case "p2pkh": {
+        const { address } = bitcoin.payments.p2pkh({ pubkey, network });
+        if (!address) throw new Error("Failed to derive a P2PKH address from this xpub");
+        return address;
+      }
+      case "p2sh-p2wpkh": {
+        const { address } = bitcoin.payments.p2sh({
+          redeem: bitcoin.payments.p2wpkh({ pubkey, network }),
+          network
+        });
+        if (!address) throw new Error("Failed to derive a P2SH-P2WPKH address from this xpub");
+        return address;
+      }
+      case "p2wpkh": {
+        const { address } = bitcoin.payments.p2wpkh({ pubkey, network });
+        if (!address) throw new Error("Failed to derive a P2WPKH address from this xpub");
+        return address;
+      }
+      case "p2tr":
+        throw new Error(
+          "BTC P2TR (taproot) address derivation is not supported yet \u2014 needs an elliptic-curve library for BIP-341 tweaking"
+        );
+      default: {
+        const exhaustive = scriptType;
+        throw new Error(`Unsupported BTC script type: ${String(exhaustive)}`);
+      }
+    }
+  }
+  buildBtcPsbtRequest(unsignedPsbtHex) {
+    const ur = this.sdk.btc.generatePSBT(Buffer.from(unsignedPsbtHex, "hex"));
+    return fromSdkUr(ur);
+  }
+  /** Returns the hex-encoded (possibly still-unsigned-in-part) PSBT the device replied with. */
+  parseBtcPsbt(ur) {
+    return this.sdk.btc.parsePSBT(toSdkUr(ur));
+  }
+  buildBtcMessageSignRequest(params) {
+    const ur = this.sdk.btc.generateSignRequest({
+      requestId: params.requestId,
+      signData: params.messageHex,
+      dataType: 1,
+      // BtcSignRequest.DataType.message — PSBT signing never goes through this path.
+      accounts: params.accounts,
+      origin: params.origin
+    });
+    return fromSdkUr(ur);
+  }
+  parseBtcSignature(ur) {
+    const signature = this.sdk.btc.parseSignature(toSdkUr(ur));
+    return {
+      requestId: signature.requestId,
+      publicKey: signature.publicKey,
+      signature: signature.signature
+    };
+  }
+  // --- SOL ---
+  buildSolSignRequest(input) {
+    const ur = this.sdk.sol.generateSignRequest({
+      requestId: input.requestId,
+      signData: input.unsignedPayloadHex,
+      dataType: input.dataType === "transaction" ? 1 : 2,
+      path: input.path,
+      xfp: input.xfp,
+      address: input.address,
+      origin: input.origin
+    });
+    return fromSdkUr(ur);
+  }
+  parseSolSignature(ur) {
+    const signature = this.sdk.sol.parseSignature(toSdkUr(ur));
+    return { requestId: signature.requestId, signature: signature.signature };
+  }
+  // --- TRON ---
+  /**
+   * `@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.
+   */
+  buildTronSignRequest(input) {
+    const request = new TronSignRequest({
+      requestId: Buffer.from(uuidParse(input.requestId)),
+      signData: Buffer.from(stripHexPrefix(input.rawTxHex), "hex"),
+      signType: 0 /* Transaction */,
+      derivationPath: TronSignRequest.parsePath(input.path, input.xfp),
+      origin: input.origin
+    });
+    return fromSdkUr(request.toUR());
+  }
+  parseTronSignature(ur) {
+    if (ur.urType !== "tron-signature") {
+      throw new Error(`Expected a tron-signature UR, got ${ur.urType}`);
+    }
+    const signature = TronSignature.fromCBOR(Buffer.from(ur.urData, "hex"));
+    const requestId = signature.getRequestId();
+    return {
+      requestId: requestId ? uuidStringify(requestId) : void 0,
+      signature: signature.getSignature().toString("hex")
+    };
+  }
+  /**
+   * 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.
+   */
+  deriveTronAddressFromXpub(xpub, relativeDerivePath) {
+    const evmStyleHex = generateAddressFromXpub(
+      xpub,
+      `m/${relativeDerivePath.replace(/^m\//i, "")}`
+    );
+    const addressBytes = Buffer.concat([
+      Buffer.from([TRON_ADDRESS_PREFIX]),
+      Buffer.from(evmStyleHex.replace(/^0x/i, ""), "hex")
+    ]);
+    return bs58check.encode(addressBytes);
+  }
+};
+
+// src/adapter/KeystoneAdapter.ts
+import bs58 from "bs58";
+import { v4 as uuidv4 } from "uuid";
+import {
+  CHAIN_FINGERPRINT_PATHS,
+  DEVICE,
+  DeviceJobQueue,
+  HardwareErrorCode,
+  TypedEventEmitter,
+  UI_REQUEST,
+  UI_REQUEST_CANCELLED_TAG,
+  UI_REQUEST_PREEMPTED_TAG,
+  UI_REQUEST_TIMEOUT_TAG,
+  UI_RESPONSE,
+  UiRequestRegistry,
+  createHwkError,
+  deriveDeviceFingerprint,
+  ensure0x,
+  failure,
+  rehydrateConnectorError,
+  runAllNetworkGetAddress,
+  stripHex,
+  success
+} from "@onekeyfe/hwk-adapter-core";
+
+// src/adapter/pathUtils.ts
+function normalizePath(path) {
+  const trimmed = path.trim();
+  return /^m\//i.test(trimmed) ? `m/${trimmed.slice(2)}` : `m/${trimmed}`;
+}
+function splitAccountPath(path) {
+  const normalized = normalizePath(path);
+  const segments = normalized.slice(2).split("/");
+  if (segments.length <= 3) {
+    return { accountPath: normalized, relativeDerivePath: "" };
+  }
+  const accountSegments = segments.slice(0, segments.length - 2);
+  const relativeSegments = segments.slice(segments.length - 2);
+  return {
+    accountPath: `m/${accountSegments.join("/")}`,
+    relativeDerivePath: relativeSegments.join("/")
+  };
+}
+function btcScriptTypeFromPath(path) {
+  const match = normalizePath(path).match(/^m\/(\d+)'/);
+  if (!match) return void 0;
+  switch (Number(match[1])) {
+    case 44:
+      return "p2pkh";
+    case 49:
+      return "p2sh-p2wpkh";
+    case 84:
+      return "p2wpkh";
+    case 86:
+      return "p2tr";
+    default:
+      return void 0;
+  }
+}
+
+// src/adapter/deviceTable.ts
+var QR_CONNECT_ID_PREFIX = "keystone-qr:";
+function qrConnectId(masterFingerprint) {
+  return `${QR_CONNECT_ID_PREFIX}${masterFingerprint}`;
+}
+function accountKey(hwkChain, path) {
+  return `${hwkChain}:${normalizePath(path)}`;
+}
+function createDeviceRecord(masterFingerprint) {
+  return {
+    masterFingerprint,
+    connectId: qrConnectId(masterFingerprint),
+    accounts: /* @__PURE__ */ new Map(),
+    importedAt: Date.now()
+  };
+}
+var CAPABILITIES = { persistentDeviceIdentity: true };
+function toDeviceInfo(record) {
+  let availableChannels = ["qr"];
+  if (record.usbSessionId) {
+    availableChannels = record.qrSynced ? ["qr", "usb"] : ["usb"];
+  }
+  return {
+    vendor: "keystone",
+    model: record.model ?? "unknown",
+    modelName: record.model,
+    firmwareVersion: record.deviceVersion ?? "0.0.0",
+    deviceId: record.masterFingerprint,
+    connectId: record.connectId,
+    connectionType: record.usbSessionId ? "usb" : "qr",
+    capabilities: CAPABILITIES,
+    raw: { availableChannels }
+  };
+}
+function placeholderDeviceInfo() {
+  return {
+    vendor: "keystone",
+    model: "unknown",
+    firmwareVersion: "0.0.0",
+    deviceId: "",
+    connectId: "",
+    connectionType: "qr",
+    capabilities: CAPABILITIES
+  };
+}
+
+// src/adapter/KeystoneAdapter.ts
+var COLD_START_JOB_LABEL = "keystone-cold-start";
+var BIP44_COIN_TYPE_TO_CHAIN = {
+  60: "evm",
+  0: "btc",
+  501: "sol",
+  195: "tron"
+};
+function inferHwkChainFromPath(path) {
+  const match = normalizePath(path).match(/^m\/\d+'\/(\d+)'/);
+  return match ? BIP44_COIN_TYPE_TO_CHAIN[Number(match[1])] : void 0;
+}
+var DEFAULT_IMPORT_SCHEMAS = [
+  { hwkChain: "evm", path: CHAIN_FINGERPRINT_PATHS.evm.replace(/\/0\/0$/, "") },
+  // The 3 BTC purposes this package can actually derive addresses for
+  // (btcScriptTypeFromPath: 44'→P2PKH, 49'→P2SH-P2WPKH, 84'→P2WPKH) —
+  // explicitly requested, not left to chance on whether the device
+  // volunteers the others unprompted. Still one combined round trip: these
+  // are 3 more entries in the same qr-hardware-call, not 3 more scans.
+  // 86' (P2TR/taproot) deliberately excluded — `deriveBtcAddressFromXpub`
+  // can't use it yet (needs an elliptic-curve library not wired in), and
+  // unlike app-monorepo's own sync-all bundle (which also requests 86', but
+  // to compute a "full xfp" — a need this adapter doesn't have, since its
+  // mfp already comes for free from the response envelope), there's no
+  // other use for that xpub here — so it stays out until P2TR is real.
+  { hwkChain: "btc", path: CHAIN_FINGERPRINT_PATHS.btc },
+  { hwkChain: "btc", path: "m/49'/0'/0'" },
+  { hwkChain: "btc", path: "m/84'/0'/0'" },
+  { hwkChain: "sol", path: CHAIN_FINGERPRINT_PATHS.sol },
+  { hwkChain: "tron", path: CHAIN_FINGERPRINT_PATHS.tron.replace(/\/0\/0$/, "") }
+];
+var KeystoneAdapter = class _KeystoneAdapter {
+  constructor(options) {
+    this.vendor = "keystone";
+    this.emitter = new TypedEventEmitter();
+    this._uiRegistry = new UiRequestRegistry();
+    this._devices = /* @__PURE__ */ new Map();
+    // ---------------------------------------------------------------------------
+    // All-network bundle — dispatches to the same per-chain methods below, so
+    // there's exactly one implementation of each chain's address logic.
+    // ---------------------------------------------------------------------------
+    this.allNetworkGetAddress = async (connectId, deviceId, params) => {
+      try {
+        return await runAllNetworkGetAddress({
+          connectId,
+          deviceId,
+          params,
+          callItem: async ({ chain, item }) => {
+            const commonArgs = { path: item.path, showOnDevice: item.showOnDevice };
+            switch (chain) {
+              case "evm":
+                return this.evmGetAddress(connectId, deviceId, commonArgs);
+              case "btc":
+                return this.btcGetAddress(connectId, deviceId, commonArgs);
+              case "sol":
+                return this.solGetAddress(connectId, deviceId, commonArgs);
+              case "tron":
+                return this.tronGetAddress(connectId, deviceId, commonArgs);
+              default:
+                return failure(HardwareErrorCode.MethodNotSupported, `Unsupported chain: ${chain}`);
+            }
+          },
+          attachIdentity: (context) => {
+            const mfp = deviceId ? deviceId.toLowerCase() : void 0;
+            return Promise.resolve({
+              ...context.item,
+              success: true,
+              payload: {
+                ...context.payload,
+                deviceIdentity: mfp ? { vendor: "keystone", type: "masterFingerprint", value: mfp } : void 0
+              }
+            });
+          }
+        });
+      } catch (err) {
+        return this._errorToFailure(err);
+      }
+    };
+    this._origin = options?.origin ?? "OneKey";
+    this._qrTimeoutMs = options?.qrTimeoutMs;
+    this.urEngine = new KeystoneUrEngine(this._origin);
+    this._jobQueue = new DeviceJobQueue();
+    this._usbConnector = options?.usbConnector;
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle / transport
+  // ---------------------------------------------------------------------------
+  get activeTransport() {
+    if (this._devices.size === 0) return null;
+    const hasUsbSession = Array.from(this._devices.values()).some((r) => r.usbSessionId);
+    return hasUsbSession ? "usb" : "qr";
+  }
+  getAvailableTransports() {
+    return this._usbConnector ? ["qr", "usb"] : ["qr"];
+  }
+  /** 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. */
+  switchTransport(type) {
+    this._forcedTransport = type === "qr" || type === "usb" ? type : void 0;
+    return Promise.resolve();
+  }
+  init(_config) {
+    return Promise.resolve();
+  }
+  dispose() {
+    this._uiRegistry.cancel();
+    this._jobQueue.clear();
+    this.emitter.removeAllListeners();
+    this._devices.clear();
+    this._usbConnector?.reset();
+    return Promise.resolve();
+  }
+  // ---------------------------------------------------------------------------
+  // Device table
+  // ---------------------------------------------------------------------------
+  /**
+   * 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
+   * `KeystoneUsbConnectorBase.searchDevices`), so these entries carry an
+   * empty `deviceId` and exist purely so a host can list "plugged in, click
+   * to connect" candidates.
+   */
+  async searchDevices(_options) {
+    const known = Array.from(this._devices.values()).map(toDeviceInfo);
+    if (!this._usbConnector) return known;
+    let usbDevices;
+    try {
+      usbDevices = await this._usbConnector.searchDevices();
+    } catch {
+      return known;
+    }
+    const placeholders = usbDevices.map((d) => ({
+      vendor: "keystone",
+      model: d.model ?? "unknown",
+      modelName: d.modelName,
+      firmwareVersion: "0.0.0",
+      deviceId: d.deviceId,
+      connectId: d.connectId,
+      connectionType: "usb",
+      capabilities: d.capabilities ?? { persistentDeviceIdentity: true }
+    }));
+    return [...known, ...placeholders];
+  }
+  async connectDevice(connectId) {
+    const existing = this._findByConnectId(connectId);
+    if (existing) return success(existing.connectId);
+    if (!this._usbConnector) {
+      return failure(HardwareErrorCode.DeviceNotFound, `Unknown Keystone connectId: ${connectId}`);
+    }
+    const result = await this._connectUsb();
+    if (!result.success) return result;
+    return success(result.payload.connectId);
+  }
+  /**
+   * 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.
+   */
+  async disconnectDevice(connectId) {
+    const record = this._findByConnectId(connectId);
+    if (!record?.usbSessionId) return;
+    if (this._usbConnector) {
+      try {
+        await this._usbConnector.disconnect(record.usbSessionId);
+      } catch {
+      }
+    }
+    record.usbSessionId = void 0;
+    if (record.qrSynced) {
+      const info = toDeviceInfo(record);
+      this.emitter.emit(DEVICE.CHANGED, { type: DEVICE.CHANGED, payload: info });
+    } else {
+      this._devices.delete(record.masterFingerprint);
+      const info = toDeviceInfo(record);
+      this.emitter.emit(DEVICE.DISCONNECT, { type: DEVICE.DISCONNECT, payload: info });
+    }
+  }
+  getDeviceInfo(connectId, deviceId) {
+    const record = this._findByConnectId(connectId) ?? this._devices.get(deviceId.toLowerCase());
+    if (!record) {
+      return Promise.resolve(
+        failure(
+          HardwareErrorCode.DeviceNotFound,
+          `Unknown Keystone device: ${connectId || deviceId}`
+        )
+      );
+    }
+    return Promise.resolve(success(toDeviceInfo(record)));
+  }
+  getSupportedChains() {
+    return ["evm", "btc", "sol", "tron"];
+  }
+  cancel(connectId) {
+    const reason = createHwkError({
+      code: HardwareErrorCode.UserAborted,
+      message: "User aborted operation"
+    });
+    this._uiRegistry.cancel();
+    this._jobQueue.cancelActiveAndPending(connectId, reason);
+  }
+  getChainFingerprint(connectId, deviceId, chain) {
+    const mfp = deviceId ? deviceId.toLowerCase() : this._mfpFromConnectId(connectId);
+    if (!mfp) {
+      return Promise.resolve(failure(HardwareErrorCode.DeviceNotFound, "Unknown Keystone device"));
+    }
+    return Promise.resolve(success(deriveDeviceFingerprint(`keystone:${chain}:${mfp}`)));
+  }
+  uiResponse(response) {
+    if (response.type === UI_RESPONSE.CANCEL) {
+      this.cancel();
+      return;
+    }
+    this._uiRegistry.resolve(response.type, response.payload);
+  }
+  on(event, listener) {
+    this.emitter.on(event, listener);
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+  }
+  // ---------------------------------------------------------------------------
+  // Explicit account import — the recommended entry point before signing, so
+  // signing calls don't each pay for their own cold-sync round trip.
+  // ---------------------------------------------------------------------------
+  async importFromQr(options = {}) {
+    try {
+      return await this._jobQueue.enqueue(COLD_START_JOB_LABEL, async (signal) => {
+        const displayDevice = placeholderDeviceInfo();
+        let responseUr;
+        let requestedChains;
+        if (options.mode === "scan") {
+          responseUr = await this._requestQrScanAndAwaitResponse(displayDevice);
+        } else {
+          const schemas = options.paths?.length ? options.paths : DEFAULT_IMPORT_SCHEMAS;
+          requestedChains = schemas.map((s) => s.hwkChain);
+          const requestUr = this.urEngine.buildKeyDerivationRequest({
+            schemas: schemas.map((s) => ({
+              path: s.path,
+              curve: s.hwkChain === "sol" ? "ed25519" : "secp256k1"
+            })),
+            origin: this._origin
+          });
+          responseUr = await this._requestQrDisplayAndAwaitResponse(displayDevice, {
+            ...requestUr,
+            animated: false
+          });
+        }
+        _KeystoneAdapter._throwIfAborted(signal);
+        const parsed = this.urEngine.parseAccountResponse(responseUr);
+        const record = this._upsertDeviceRecord(parsed);
+        for (const account of parsed.accounts) {
+          const hwkChain = requestedChains?.length === 1 ? requestedChains[0] : inferHwkChainFromPath(account.path);
+          if (hwkChain) {
+            const entry = { ...account, hwkChain };
+            record.accounts.set(accountKey(hwkChain, account.path), entry);
+          }
+        }
+        return success(toDeviceInfo(record));
+      });
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // EVM
+  // ---------------------------------------------------------------------------
+  async evmGetAddress(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params) return failure(HardwareErrorCode.InvalidParams, "evmGetAddress requires params");
+    if (!params.path)
+      return failure(HardwareErrorCode.InvalidParams, "evmGetAddress requires params.path");
+    const { accountPath, relativeDerivePath } = splitAccountPath(params.path);
+    if (!relativeDerivePath) {
+      return failure(
+        HardwareErrorCode.InvalidParams,
+        "evmGetAddress requires a full leaf path, e.g. m/44'/60'/0'/0/0"
+      );
+    }
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { account } = await this._ensureAccountSynced(
+            connectId,
+            deviceId,
+            "evm",
+            accountPath,
+            signal
+          );
+          _KeystoneAdapter._throwIfAborted(signal);
+          if (!account.extendedPublicKey) {
+            throw createHwkError({
+              code: HardwareErrorCode.MethodNotSupported,
+              message: "Keystone did not return an extended public key for this account path"
+            });
+          }
+          const address = this.urEngine.deriveEvmAddressFromXpub(
+            account.extendedPublicKey,
+            relativeDerivePath
+          );
+          return success({ address, path: normalizePath(params.path) });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  async evmSignTransaction(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params)
+      return failure(HardwareErrorCode.InvalidParams, "evmSignTransaction requires params");
+    if (!params.path) {
+      return failure(HardwareErrorCode.InvalidParams, "evmSignTransaction requires params.path");
+    }
+    if (!("serializedTx" in params) || typeof params.serializedTx !== "string" || !params.serializedTx) {
+      return failure(
+        HardwareErrorCode.MethodNotSupported,
+        "Keystone only signs a fully RLP-serialized transaction (params.serializedTx) \u2014 structured-field signing is not supported"
+      );
+    }
+    const rawTxHex = stripHex(params.serializedTx);
+    const path = normalizePath(params.path);
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { record } = await this._ensureMfpKnown(connectId, deviceId, "evm", signal);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const requestId = uuidv4();
+          const dataType = parseInt(rawTxHex.slice(0, 2), 16) < 192 ? "typedTransaction" : "transaction";
+          const requestUr = this.urEngine.buildEthSignRequest({
+            requestId,
+            unsignedTxHex: rawTxHex,
+            dataType,
+            path,
+            xfp: record.masterFingerprint,
+            chainId: params.chainId
+          });
+          const responseUr = await this._resolveUr(record, requestUr, true);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const sig = this.urEngine.parseEthSignature(responseUr);
+          _KeystoneAdapter._assertRequestIdMatches(requestId, sig.requestId);
+          return success({
+            v: ensure0x(sig.v),
+            r: ensure0x(sig.r),
+            s: ensure0x(sig.s)
+          });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  async evmSignMessage(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params) return failure(HardwareErrorCode.InvalidParams, "evmSignMessage requires params");
+    if (!params.path || params.message === void 0) {
+      return failure(
+        HardwareErrorCode.InvalidParams,
+        "evmSignMessage requires params.path and params.message"
+      );
+    }
+    const messageHex = params.hex ? stripHex(params.message) : Buffer.from(params.message, "utf8").toString("hex");
+    const path = normalizePath(params.path);
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { record } = await this._ensureMfpKnown(connectId, deviceId, "evm", signal);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const requestId = uuidv4();
+          const requestUr = this.urEngine.buildEthSignRequest({
+            requestId,
+            unsignedTxHex: messageHex,
+            dataType: "personalMessage",
+            path,
+            xfp: record.masterFingerprint,
+            chainId: params.chainId
+          });
+          const responseUr = await this._resolveUr(record, requestUr, true);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const sig = this.urEngine.parseEthSignature(responseUr);
+          _KeystoneAdapter._assertRequestIdMatches(requestId, sig.requestId);
+          return success({ signature: ensure0x(sig.r + sig.s + sig.v) });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  async evmSignTypedData(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params)
+      return failure(HardwareErrorCode.InvalidParams, "evmSignTypedData requires params");
+    if (!params.path) {
+      return failure(HardwareErrorCode.InvalidParams, "evmSignTypedData requires params.path");
+    }
+    if (params.mode === "hash") {
+      return failure(
+        HardwareErrorCode.MethodNotSupported,
+        "Keystone always displays the full EIP-712 payload for on-device review \u2014 pre-hashed signing is not supported"
+      );
+    }
+    const signDataHex = Buffer.from(JSON.stringify(params.data), "utf8").toString("hex");
+    const path = normalizePath(params.path);
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { record } = await this._ensureMfpKnown(connectId, deviceId, "evm", signal);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const requestId = uuidv4();
+          const requestUr = this.urEngine.buildEthSignRequest({
+            requestId,
+            unsignedTxHex: signDataHex,
+            dataType: "typedData",
+            path,
+            xfp: record.masterFingerprint,
+            chainId: params.chainId
+          });
+          const responseUr = await this._resolveUr(record, requestUr, true);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const sig = this.urEngine.parseEthSignature(responseUr);
+          _KeystoneAdapter._assertRequestIdMatches(requestId, sig.requestId);
+          return success({ signature: ensure0x(sig.r + sig.s + sig.v) });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // BTC — PSBT signing and message signing only for now. Address/pubkey
+  // derivation needs script-type-aware xpub decoding (P2WPKH/P2TR/…) this
+  // phase doesn't wire in yet; structured-field tx signing needs host-side
+  // PSBT construction. Both are real, bounded follow-ups, not silent gaps.
+  // ---------------------------------------------------------------------------
+  async btcGetAddress(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params) return failure(HardwareErrorCode.InvalidParams, "btcGetAddress requires params");
+    if (!params.path)
+      return failure(HardwareErrorCode.InvalidParams, "btcGetAddress requires params.path");
+    const scriptType = btcScriptTypeFromPath(params.path);
+    if (!scriptType) {
+      return failure(
+        HardwareErrorCode.InvalidParams,
+        "btcGetAddress requires a path whose purpose is 44'/49'/84'/86' (P2PKH/P2SH-P2WPKH/P2WPKH/P2TR)"
+      );
+    }
+    if (scriptType === "p2tr") {
+      return this._unsupported(
+        "btcGetAddress",
+        "P2TR (purpose 86') needs an elliptic-curve library for BIP-341 tweaking, not yet wired in \u2014 44'/49'/84' work"
+      );
+    }
+    const { accountPath, relativeDerivePath } = splitAccountPath(params.path);
+    if (!relativeDerivePath) {
+      return failure(
+        HardwareErrorCode.InvalidParams,
+        "btcGetAddress requires a full leaf path, e.g. m/84'/0'/0'/0/0"
+      );
+    }
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { account } = await this._ensureAccountSynced(
+            connectId,
+            deviceId,
+            "btc",
+            accountPath,
+            signal
+          );
+          _KeystoneAdapter._throwIfAborted(signal);
+          if (!account.extendedPublicKey) {
+            throw createHwkError({
+              code: HardwareErrorCode.MethodNotSupported,
+              message: "Keystone did not return an extended public key for this account path"
+            });
+          }
+          const address = this.urEngine.deriveBtcAddressFromXpub(
+            account.extendedPublicKey,
+            relativeDerivePath,
+            scriptType
+          );
+          return success({ address, path: normalizePath(params.path) });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  async btcGetPublicKey(_connectId, _deviceId, _params) {
+    return this._unsupported(
+      "btcGetPublicKey",
+      "not yet wired \u2014 the underlying synced xpub/chainCode data already exists in the device table"
+    );
+  }
+  async btcSignTransaction(_connectId, _deviceId, _params) {
+    return this._unsupported(
+      "btcSignTransaction",
+      "use btcSignPsbt \u2014 structured input/output signing needs host-side PSBT construction, not yet wired in"
+    );
+  }
+  async btcSignPsbt(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params) return failure(HardwareErrorCode.InvalidParams, "btcSignPsbt requires params");
+    if (!params.psbt)
+      return failure(HardwareErrorCode.InvalidParams, "btcSignPsbt requires params.psbt");
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { record } = await this._ensureMfpKnown(connectId, deviceId, "btc", signal);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const requestUr = this.urEngine.buildBtcPsbtRequest(stripHex(params.psbt));
+          const responseUr = await this._resolveUr(record, requestUr, true);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const signedPsbt = this.urEngine.parseBtcPsbt(responseUr);
+          return success({ signedPsbt });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  async btcSignMessage(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params) return failure(HardwareErrorCode.InvalidParams, "btcSignMessage requires params");
+    if (!params.path || params.message === void 0) {
+      return failure(
+        HardwareErrorCode.InvalidParams,
+        "btcSignMessage requires params.path and params.message"
+      );
+    }
+    const messageHex = params.hex ? stripHex(params.message) : Buffer.from(params.message, "utf8").toString("hex");
+    const path = normalizePath(params.path);
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { record } = await this._ensureMfpKnown(connectId, deviceId, "btc", signal);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const requestId = uuidv4();
+          const requestUr = this.urEngine.buildBtcMessageSignRequest({
+            requestId,
+            messageHex,
+            accounts: [{ path, xfp: record.masterFingerprint }]
+          });
+          const responseUr = await this._resolveUr(record, requestUr, true);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const sig = this.urEngine.parseBtcSignature(responseUr);
+          _KeystoneAdapter._assertRequestIdMatches(requestId, sig.requestId);
+          return success({ signature: sig.signature });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  async btcGetMasterFingerprint(connectIdArg, deviceIdArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { record } = await this._ensureMfpKnown(connectId, deviceId, "btc", signal);
+          return success({ masterFingerprint: record.masterFingerprint });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // SOL
+  // ---------------------------------------------------------------------------
+  async solGetAddress(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params) return failure(HardwareErrorCode.InvalidParams, "solGetAddress requires params");
+    if (!params.path)
+      return failure(HardwareErrorCode.InvalidParams, "solGetAddress requires params.path");
+    const path = normalizePath(params.path);
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { account } = await this._ensureAccountSynced(
+            connectId,
+            deviceId,
+            "sol",
+            path,
+            signal
+          );
+          _KeystoneAdapter._throwIfAborted(signal);
+          const address = bs58.encode(Buffer.from(account.publicKey, "hex"));
+          return success({ address, path });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  async solSignTransaction(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params)
+      return failure(HardwareErrorCode.InvalidParams, "solSignTransaction requires params");
+    if (!params.path || !params.serializedTx) {
+      return failure(
+        HardwareErrorCode.InvalidParams,
+        "solSignTransaction requires params.path and params.serializedTx"
+      );
+    }
+    const path = normalizePath(params.path);
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { record } = await this._ensureMfpKnown(connectId, deviceId, "sol", signal);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const requestId = uuidv4();
+          const requestUr = this.urEngine.buildSolSignRequest({
+            requestId,
+            unsignedPayloadHex: stripHex(params.serializedTx),
+            dataType: "transaction",
+            path,
+            xfp: record.masterFingerprint
+          });
+          const responseUr = await this._resolveUr(record, requestUr, true);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const sig = this.urEngine.parseSolSignature(responseUr);
+          _KeystoneAdapter._assertRequestIdMatches(requestId, sig.requestId);
+          return success({ signature: sig.signature });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  async solSignMessage(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params) return failure(HardwareErrorCode.InvalidParams, "solSignMessage requires params");
+    if (!params.path || !params.message) {
+      return failure(
+        HardwareErrorCode.InvalidParams,
+        "solSignMessage requires params.path and params.message"
+      );
+    }
+    const path = normalizePath(params.path);
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { record } = await this._ensureMfpKnown(connectId, deviceId, "sol", signal);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const requestId = uuidv4();
+          const requestUr = this.urEngine.buildSolSignRequest({
+            requestId,
+            unsignedPayloadHex: stripHex(params.message),
+            dataType: "message",
+            path,
+            xfp: record.masterFingerprint
+          });
+          const responseUr = await this._resolveUr(record, requestUr, true);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const sig = this.urEngine.parseSolSignature(responseUr);
+          _KeystoneAdapter._assertRequestIdMatches(requestId, sig.requestId);
+          return success({ signature: sig.signature });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // TRON — routed through `TronSignRequest`/`TronSignature` (see
+  // urEngine/TronSignRequest.ts), a port of OneKey's own already-proven
+  // production TRON QR-wallet implementation — NOT keystone-sdk's own
+  // bundled `sdk.tron` module (different, protobuf-based protocol with
+  // unverified response semantics).
+  // ---------------------------------------------------------------------------
+  async tronGetAddress(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params) return failure(HardwareErrorCode.InvalidParams, "tronGetAddress requires params");
+    if (!params.path)
+      return failure(HardwareErrorCode.InvalidParams, "tronGetAddress requires params.path");
+    const { accountPath, relativeDerivePath } = splitAccountPath(params.path);
+    if (!relativeDerivePath) {
+      return failure(
+        HardwareErrorCode.InvalidParams,
+        "tronGetAddress requires a full leaf path, e.g. m/44'/195'/0'/0/0"
+      );
+    }
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { account } = await this._ensureAccountSynced(
+            connectId,
+            deviceId,
+            "tron",
+            accountPath,
+            signal
+          );
+          _KeystoneAdapter._throwIfAborted(signal);
+          if (!account.extendedPublicKey) {
+            throw createHwkError({
+              code: HardwareErrorCode.MethodNotSupported,
+              message: "Keystone did not return an extended public key for this account path"
+            });
+          }
+          const address = this.urEngine.deriveTronAddressFromXpub(
+            account.extendedPublicKey,
+            relativeDerivePath
+          );
+          return success({ address, path: normalizePath(params.path) });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  async tronSignTransaction(connectIdArg, deviceIdArg, paramsArg) {
+    const connectId = connectIdArg ?? void 0;
+    const deviceId = deviceIdArg ?? void 0;
+    const params = paramsArg;
+    if (!params)
+      return failure(HardwareErrorCode.InvalidParams, "tronSignTransaction requires params");
+    if (!params.path) {
+      return failure(HardwareErrorCode.InvalidParams, "tronSignTransaction requires params.path");
+    }
+    if (!params.rawTxHex) {
+      return failure(
+        HardwareErrorCode.InvalidParams,
+        "Keystone only signs a fully protobuf-serialized TRON transaction (params.rawTxHex) \u2014 the Trezor-style structured contract fields have no equivalent here"
+      );
+    }
+    const rawTxHex = stripHex(params.rawTxHex);
+    const path = normalizePath(params.path);
+    try {
+      return await this._jobQueue.enqueue(
+        deviceId ?? connectId ?? COLD_START_JOB_LABEL,
+        async (signal) => {
+          const { record } = await this._ensureMfpKnown(connectId, deviceId, "tron", signal);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const requestId = uuidv4();
+          const requestUr = this.urEngine.buildTronSignRequest({
+            requestId,
+            rawTxHex,
+            path,
+            xfp: record.masterFingerprint
+          });
+          const responseUr = await this._resolveUr(record, requestUr, true);
+          _KeystoneAdapter._throwIfAborted(signal);
+          const sig = this.urEngine.parseTronSignature(responseUr);
+          _KeystoneAdapter._assertRequestIdMatches(requestId, sig.requestId);
+          return success({ signature: sig.signature });
+        }
+      );
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  async tronSignMessage(_connectId, _deviceId, _params) {
+    return this._unsupported(
+      "tronSignMessage",
+      "Keystone TRON message signing needs signType V1-vs-V2 verified against real hardware first \u2014 not wired in"
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Internals
+  // ---------------------------------------------------------------------------
+  _mfpFromConnectId(connectId) {
+    return connectId?.startsWith(QR_CONNECT_ID_PREFIX) ? connectId.slice(QR_CONNECT_ID_PREFIX.length) : void 0;
+  }
+  /**
+   * 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`).
+   */
+  _findByConnectId(connectId) {
+    const mfp = this._mfpFromConnectId(connectId) ?? connectId?.toLowerCase();
+    return mfp ? this._devices.get(mfp) : void 0;
+  }
+  /**
+   * 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 `disconnectDevice`).
+   */
+  _upsertDeviceRecord(parsed, options) {
+    const mfp = parsed.masterFingerprint;
+    let record = this._devices.get(mfp);
+    const isNew = !record;
+    if (!record) {
+      record = createDeviceRecord(mfp);
+      this._devices.set(mfp, record);
+    }
+    record.model = parsed.device ?? record.model;
+    record.deviceVersion = parsed.deviceVersion ?? record.deviceVersion;
+    if (!options?.viaUsb) record.qrSynced = true;
+    const info = toDeviceInfo(record);
+    const eventType = isNew ? DEVICE.CONNECT : DEVICE.CHANGED;
+    this.emitter.emit(eventType, { type: eventType, payload: info });
+    return record;
+  }
+  /**
+   * 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
+   * `{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.
+   */
+  async _connectUsb() {
+    if (!this._usbConnector) {
+      return failure(
+        HardwareErrorCode.TransportNotAvailable,
+        "No USB connector configured for this Keystone adapter"
+      );
+    }
+    try {
+      const session = await this._usbConnector.connect();
+      const mfp = session.deviceInfo.deviceId.toLowerCase();
+      let record = this._devices.get(mfp);
+      const isNew = !record;
+      if (!record) {
+        record = createDeviceRecord(mfp);
+        this._devices.set(mfp, record);
+      }
+      record.model = session.deviceInfo.modelName ?? session.deviceInfo.model ?? record.model;
+      record.deviceVersion = session.deviceInfo.firmwareVersion ?? record.deviceVersion;
+      record.usbSessionId = session.sessionId;
+      const info = toDeviceInfo(record);
+      const eventType = isNew ? DEVICE.CONNECT : DEVICE.CHANGED;
+      this.emitter.emit(eventType, { type: eventType, payload: info });
+      return success(info);
+    } catch (err) {
+      return this._errorToFailure(err);
+    }
+  }
+  /**
+   * 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
+   * `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.
+   */
+  async _resolveUr(record, requestUr, animated) {
+    const wantUsb = this._forcedTransport === "usb" || this._forcedTransport !== "qr" && Boolean(record?.usbSessionId);
+    if (wantUsb) {
+      if (!record?.usbSessionId || !this._usbConnector) {
+        throw createHwkError({
+          code: HardwareErrorCode.TransportNotAvailable,
+          message: "USB channel is not connected for this Keystone wallet"
+        });
+      }
+      const result = await this._usbConnector.call(record.usbSessionId, "resolveUr", requestUr);
+      if (!result.success) throw rehydrateConnectorError(result.error);
+      return result.payload;
+    }
+    const displayDevice = record ? toDeviceInfo(record) : placeholderDeviceInfo();
+    return this._requestQrDisplayAndAwaitResponse(displayDevice, { ...requestUr, animated });
+  }
+  /**
+   * 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.
+   */
+  async _ensureAccountSynced(connectId, deviceId, hwkChain, syncPath, signal) {
+    const wantMfp = deviceId ? deviceId.toLowerCase() : this._mfpFromConnectId(connectId ?? "");
+    const key = accountKey(hwkChain, syncPath);
+    const existingRecord = wantMfp ? this._devices.get(wantMfp) : void 0;
+    const cached = existingRecord?.accounts.get(key);
+    if (existingRecord && cached) {
+      return { record: existingRecord, account: cached };
+    }
+    const requestUr = this.urEngine.buildKeyDerivationRequest({
+      schemas: [{ path: syncPath, curve: hwkChain === "sol" ? "ed25519" : "secp256k1" }],
+      origin: this._origin
+    });
+    const responseUr = await this._resolveUr(existingRecord, requestUr, false);
+    _KeystoneAdapter._throwIfAborted(signal);
+    const parsed = this.urEngine.parseAccountResponse(responseUr);
+    if (wantMfp && parsed.masterFingerprint !== wantMfp) {
+      throw createHwkError({
+        code: HardwareErrorCode.DeviceMismatch,
+        message: `Scanned Keystone wallet (mfp ${parsed.masterFingerprint}) does not match the requested device (${wantMfp})`
+      });
+    }
+    const record = this._upsertDeviceRecord(parsed, {
+      viaUsb: Boolean(existingRecord?.usbSessionId)
+    });
+    const account = parsed.accounts.find((a) => normalizePath(a.path) === syncPath);
+    if (!account) {
+      throw createHwkError({
+        code: HardwareErrorCode.DeviceMismatch,
+        message: `Keystone did not return the requested derivation path (${syncPath})`
+      });
+    }
+    const entry = { ...account, hwkChain };
+    record.accounts.set(key, entry);
+    return { record, account: entry };
+  }
+  /**
+   * Like `_ensureAccountSynced`, 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.
+   *
+   * `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
+   * 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.
+   */
+  async _ensureMfpKnown(connectId, deviceId, chain, signal) {
+    const wantMfp = deviceId ? deviceId.toLowerCase() : this._mfpFromConnectId(connectId ?? "");
+    const existing = wantMfp ? this._devices.get(wantMfp) : void 0;
+    if (existing) return { record: existing };
+    const { accountPath } = splitAccountPath(CHAIN_FINGERPRINT_PATHS[chain]);
+    const requestUr = this.urEngine.buildKeyDerivationRequest({
+      schemas: [{ path: accountPath, curve: chain === "sol" ? "ed25519" : "secp256k1" }],
+      origin: this._origin
+    });
+    const responseUr = await this._resolveUr(void 0, requestUr, false);
+    _KeystoneAdapter._throwIfAborted(signal);
+    const parsed = this.urEngine.parseAccountResponse(responseUr);
+    if (wantMfp && parsed.masterFingerprint !== wantMfp) {
+      throw createHwkError({
+        code: HardwareErrorCode.DeviceMismatch,
+        message: `Scanned Keystone wallet (mfp ${parsed.masterFingerprint}) does not match the requested device (${wantMfp})`
+      });
+    }
+    return { record: this._upsertDeviceRecord(parsed) };
+  }
+  async _requestQrDisplayAndAwaitResponse(device, data) {
+    const waitPromise = this._uiRegistry.wait(
+      UI_REQUEST.REQUEST_QR_DISPLAY,
+      { timeoutMs: this._qrTimeoutMs }
+    );
+    this.emitter.emit(UI_REQUEST.REQUEST_QR_DISPLAY, {
+      type: UI_REQUEST.REQUEST_QR_DISPLAY,
+      payload: { device, data }
+    });
+    const response = await waitPromise;
+    return { urType: response.urType, urData: response.urData };
+  }
+  async _requestQrScanAndAwaitResponse(device) {
+    const waitPromise = this._uiRegistry.wait(
+      UI_REQUEST.REQUEST_QR_SCAN,
+      { timeoutMs: this._qrTimeoutMs }
+    );
+    this.emitter.emit(UI_REQUEST.REQUEST_QR_SCAN, {
+      type: UI_REQUEST.REQUEST_QR_SCAN,
+      payload: { device }
+    });
+    const response = await waitPromise;
+    return { urType: response.urType, urData: response.urData };
+  }
+  static _throwIfAborted(signal) {
+    if (signal.aborted) {
+      throw signal.reason instanceof Error ? signal.reason : new Error("Operation aborted");
+    }
+  }
+  static _assertRequestIdMatches(expected, actual) {
+    if (actual && actual.toLowerCase() !== expected.toLowerCase()) {
+      throw createHwkError({
+        code: HardwareErrorCode.DeviceMismatch,
+        message: "Keystone response requestId does not match the pending request \u2014 discarding a stale or unrelated scan"
+      });
+    }
+  }
+  _unsupported(method, reason) {
+    return Promise.resolve(
+      failure(
+        HardwareErrorCode.MethodNotSupported,
+        `KeystoneAdapter.${method} is not implemented yet: ${reason}`
+      )
+    );
+  }
+  _errorToFailure(err) {
+    if (err && typeof err === "object") {
+      const e = err;
+      if (typeof e.code === "number") {
+        return failure(e.code, e.message ?? "Unknown error", e.params);
+      }
+      if (e._tag === UI_REQUEST_CANCELLED_TAG || e._tag === UI_REQUEST_PREEMPTED_TAG) {
+        return failure(
+          HardwareErrorCode.UserAborted,
+          e.message ?? "Keystone QR interaction was cancelled"
+        );
+      }
+      if (e._tag === UI_REQUEST_TIMEOUT_TAG) {
+        return failure(
+          HardwareErrorCode.OperationTimeout,
+          e.message ?? "Keystone QR interaction timed out"
+        );
+      }
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    const params = err instanceof Error && err.stack ? { stack: err.stack } : void 0;
+    return failure(HardwareErrorCode.UnknownError, message, params);
+  }
+};
+export {
+  KeystoneAdapter,
+  KeystoneUrEngine,
+  QR_CONNECT_ID_PREFIX,
+  accountKey,
+  btcScriptTypeFromPath,
+  createDeviceRecord,
+  normalizePath,
+  placeholderDeviceInfo,
+  qrConnectId,
+  splitAccountPath,
+  toDeviceInfo
+};
+//# sourceMappingURL=index.mjs.map