@onekeyfe/hwk-adapter-core 1.2.2-alpha.9 → 1.2.3-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/chunk-3M3GMF64.mjs +68 -0
  2. package/dist/chunk-3M3GMF64.mjs.map +1 -0
  3. package/dist/chunk-7SFFS2NL.js +68 -0
  4. package/dist/chunk-7SFFS2NL.js.map +1 -0
  5. package/dist/{chunk-67BP77GT.mjs → chunk-E3UPXUN5.mjs} +149 -56
  6. package/dist/chunk-E3UPXUN5.mjs.map +1 -0
  7. package/dist/{chunk-U63HTLGJ.mjs → chunk-ELC6PLKH.mjs} +31 -2
  8. package/dist/chunk-ELC6PLKH.mjs.map +1 -0
  9. package/dist/{chunk-BAGEFFFY.js → chunk-S7X2HM7P.js} +32 -3
  10. package/dist/chunk-S7X2HM7P.js.map +1 -0
  11. package/dist/{chunk-SK7ZF33J.js → chunk-Z3IH25KV.js} +149 -56
  12. package/dist/chunk-Z3IH25KV.js.map +1 -0
  13. package/dist/errors-C5GWtyVN.d.mts +304 -0
  14. package/dist/errors-C5GWtyVN.d.ts +304 -0
  15. package/dist/errors.d.mts +1 -205
  16. package/dist/errors.d.ts +1 -205
  17. package/dist/errors.js +8 -2
  18. package/dist/errors.js.map +1 -1
  19. package/dist/errors.mjs +9 -3
  20. package/dist/index.d.mts +546 -74
  21. package/dist/index.d.ts +546 -74
  22. package/dist/index.js +616 -81
  23. package/dist/index.js.map +1 -1
  24. package/dist/index.mjs +607 -72
  25. package/dist/index.mjs.map +1 -1
  26. package/dist/{ui-events-Cb7haAeE.d.mts → ui-events-CbZdnS8a.d.mts} +28 -3
  27. package/dist/{ui-events-Cb7haAeE.d.ts → ui-events-CbZdnS8a.d.ts} +28 -3
  28. package/dist/ui-events.d.mts +1 -1
  29. package/dist/ui-events.d.ts +1 -1
  30. package/dist/ui-events.js +3 -2
  31. package/dist/ui-events.js.map +1 -1
  32. package/dist/ui-events.mjs +2 -1
  33. package/package.json +2 -2
  34. package/dist/chunk-67BP77GT.mjs.map +0 -1
  35. package/dist/chunk-BAGEFFFY.js.map +0 -1
  36. package/dist/chunk-SK7ZF33J.js.map +0 -1
  37. package/dist/chunk-U63HTLGJ.mjs.map +0 -1
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- import { HardwareErrorCode } from './errors.js';
2
- export { HwkError, IHwkErrorPayload, ORPHAN_ELIGIBLE_ERROR_CODES, createHwkError, enrichErrorMessage } from './errors.js';
3
- import { U as UiResponseEvent, a as UI_REQUEST, Q as QrDisplayData } from './ui-events-Cb7haAeE.js';
4
- export { D as DevicePermissionDeniedReason, b as DevicePermissionResponse, c as QrResponseData, d as UI_EVENT, e as UI_REQUEST_CANCELLED_TAG, f as UI_REQUEST_DEFAULT_TIMEOUT_MS, g as UI_REQUEST_PREEMPTED_TAG, h as UI_REQUEST_TIMEOUT_TAG, i as UI_RESPONSE, j as UiRequestRegistry } from './ui-events-Cb7haAeE.js';
1
+ import { H as HardwareErrorCode, a as HwkErrorOrigin, b as HwkRecoveryHint } from './errors-C5GWtyVN.js';
2
+ export { c as HwkError, d as HwkRecoveryScope, I as IHwkErrorPayload, e as IOperationMayHaveCompletedParams, O as ORPHAN_ELIGIBLE_ERROR_CODES, f as createHwkError, g as defaultOriginForCode, h as defaultRecoveryForCode, i as enrichErrorMessage, j as isHwkRecoveryHint, o as operationMayHaveCompletedParams } from './errors-C5GWtyVN.js';
3
+ import { U as UiResponseEvent, a as UI_REQUEST, Q as QrDisplayData, b as UiRequestRegistry, S as SaveDeviceBindingDeclineReason } from './ui-events-CbZdnS8a.js';
4
+ export { D as DevicePermissionDeniedReason, c as DevicePermissionResponse, d as QrResponseData, e as UI_EVENT, f as UI_REQUEST_CANCELLED_TAG, g as UI_REQUEST_DEFAULT_TIMEOUT_MS, h as UI_REQUEST_PREEMPTED_TAG, i as UI_REQUEST_TIMEOUT_TAG, j as UI_RESPONSE } from './ui-events-CbZdnS8a.js';
5
5
 
6
6
  interface Success<T> {
7
7
  success: true;
@@ -12,16 +12,57 @@ interface Failure {
12
12
  payload: {
13
13
  error: string;
14
14
  code: HardwareErrorCode;
15
+ /** See HwkErrorOrigin — who the failure came from. Optional so an
16
+ * unclassified failure degrades to code-based handling, never a guess. */
17
+ origin?: HwkErrorOrigin;
18
+ /** Connection-lifecycle recovery semantics. Optional for wire compatibility
19
+ * with SDK versions that predate this field. SDK failure helpers populate it. */
20
+ recovery?: HwkRecoveryHint;
15
21
  params?: Record<string, unknown>;
16
22
  };
17
23
  }
18
24
  type Response<T> = Success<T> | Failure;
19
25
  declare function success<T>(payload: T): Success<T>;
20
- declare function failure(code: HardwareErrorCode, error: string, params?: Record<string, unknown>): Failure;
26
+ declare function failure(code: HardwareErrorCode, error: string, params?: Record<string, unknown>, origin?: HwkErrorOrigin, recovery?: HwkRecoveryHint): Failure;
21
27
 
22
- type VendorType = 'trezor' | 'ledger';
23
- type ConnectionType = 'usb' | 'ble';
24
- type TransportType = 'usb' | 'ble' | 'hid' | 'bridge';
28
+ /**
29
+ * Fixed derivation paths used to generate chain fingerprints.
30
+ * Uses standard index 0 — Ledger firmware shows device confirmation for
31
+ * non-standard paths (e.g., index=100), which would interrupt wallet creation.
32
+ * The address is hashed into a 16-char fingerprint, not exposed directly.
33
+ * - EVM: cointype 60 (Ledger ETH App only supports 60)
34
+ * - BTC: cointype 1 (testnet)
35
+ * - SOL: cointype 501, standard 3-level hardened
36
+ */
37
+ declare const CHAIN_FINGERPRINT_PATHS: Record<ChainForFingerprint, string>;
38
+ type ChainForFingerprint = 'evm' | 'btc' | 'sol' | 'tron' | 'zcash';
39
+ /**
40
+ * Parses the complete BIP32 master fingerprint wire value: 4 bytes encoded
41
+ * as exactly 8 hexadecimal characters. This is protocol metadata, not a
42
+ * collision-resistant wallet identity.
43
+ */
44
+ declare function parseBip32MasterFingerprint(value: unknown): string | undefined;
45
+ /**
46
+ * 16-char SHA-256 fingerprint for device-identity verification.
47
+ * Callers must canonicalize input (e.g. EVM address → lowercase) —
48
+ * encoding variations otherwise cause false DeviceMismatch.
49
+ */
50
+ declare function deriveDeviceFingerprint(value: string): string;
51
+ /**
52
+ * Stable 256-bit wallet identity derived from canonical public wallet
53
+ * material. The domain separator prevents the same input from being confused
54
+ * with hashes used by other SDK features.
55
+ *
56
+ * Callers must provide one fixed, vendor-defined identity source. Do not hash
57
+ * a variable subset of exported accounts: the same wallet would then receive
58
+ * different ids depending on which accounts happened to be returned.
59
+ */
60
+ declare function deriveWalletId(canonicalPublicMaterial: string): string;
61
+
62
+ type VendorType = 'trezor' | 'ledger' | 'keystone';
63
+ /** 'qr' is a virtual channel: UR payloads travel via app-rendered/scanned QR codes. */
64
+ type ConnectionType = 'usb' | 'ble' | 'qr';
65
+ type TransportType = 'usb' | 'ble' | 'hid' | 'bridge' | 'qr';
25
66
  /**
26
67
  * Device capabilities — describes what a specific device/connection
27
68
  * combination can or cannot do. Varies by vendor, model, and connection type.
@@ -73,6 +114,56 @@ interface DeviceTarget {
73
114
  connectId: string;
74
115
  deviceId: string;
75
116
  }
117
+ /**
118
+ * How long a discovery handle remains safe to use for a new connection.
119
+ * This is deliberately separate from post-connect device identity.
120
+ */
121
+ type SearchTargetReusePolicy = 'current-discovery' | 'reconnectable' | 'rediscover';
122
+ declare function resolveSearchTargetReusePolicy(device: Pick<DeviceInfo, 'connectionType' | 'capabilities'>): SearchTargetReusePolicy;
123
+ /**
124
+ * A selectable result from hardware discovery. It may represent a physical
125
+ * transport endpoint or an interactive entry such as Keystone QR; it is not a
126
+ * physical-device or wallet identity.
127
+ */
128
+ interface DeviceSearchTarget {
129
+ /** Opaque handle scoped to the adapter's current discovery state. */
130
+ searchTargetId: string;
131
+ /**
132
+ * Whether the handle itself may be retried. This says nothing about the
133
+ * identity learned after connect and must not be inferred from a stored
134
+ * connectId.
135
+ */
136
+ searchTargetReusePolicy?: SearchTargetReusePolicy;
137
+ vendor: VendorType;
138
+ connectionType: ConnectionType;
139
+ kind: 'physical' | 'interactive';
140
+ label?: string;
141
+ model?: string;
142
+ modelName?: string;
143
+ serialNumber?: string;
144
+ }
145
+ /**
146
+ * @deprecated Use DeviceSearchTarget. Kept for consumers of the pre-release
147
+ * connection-target API.
148
+ */
149
+ type ConnectionTarget = Omit<DeviceSearchTarget, 'searchTargetId'> & {
150
+ targetId: string;
151
+ searchTargetId?: string;
152
+ };
153
+ type WalletIdentity = {
154
+ vendor: 'ledger';
155
+ type: 'chainFingerprint';
156
+ chain: ChainForFingerprint;
157
+ value: string;
158
+ } | {
159
+ vendor: 'trezor';
160
+ type: 'deviceId';
161
+ value: string;
162
+ } | {
163
+ vendor: 'keystone';
164
+ type: 'walletId';
165
+ value: string;
166
+ };
76
167
 
77
168
  /**
78
169
  * Mixin for chain-operation params that can be pinned to a specific passphrase
@@ -133,6 +224,15 @@ interface ConnectorSession {
133
224
  sessionId: string;
134
225
  deviceInfo: DeviceInfo;
135
226
  }
227
+ type ConnectorConnectTarget = {
228
+ type: 'default';
229
+ } | {
230
+ type: 'search-target';
231
+ searchTargetId: string;
232
+ } | {
233
+ type: 'expected-device-identity';
234
+ deviceIdentity: string;
235
+ };
136
236
  /**
137
237
  * Vendor-agnostic bag of extra error fields. Known keys are documented for
138
238
  * discoverability; the index signature keeps it open so any connector can
@@ -253,12 +353,16 @@ interface ConnectorEventMap {
253
353
  'ui-event': ConnectorUiEvent;
254
354
  }
255
355
  interface ConnectorSearchDevicesOptions {
356
+ /** Select a child transport without waking/scanning the others. */
357
+ transportType?: ConnectionType;
256
358
  /**
257
359
  * Wait for every child transport in a fused connector. Default discovery can
258
360
  * return shortly after USB appears so BLE does not slow down USB flows;
259
361
  * binding pickers can opt in when they need BLE candidates too.
260
362
  */
261
363
  waitForAll?: boolean;
364
+ /** Availability probes must not invalidate user-selectable discovery targets. */
365
+ purpose?: 'selection' | 'availability';
262
366
  }
263
367
  interface ConnectorConfig {
264
368
  /**
@@ -273,8 +377,17 @@ interface ConnectorConfig {
273
377
  interface IConnector {
274
378
  /** Physical connection type this connector uses. Fixed at construction. */
275
379
  readonly connectionType: ConnectionType;
380
+ readonly availableTransports?: readonly ConnectionType[];
276
381
  searchDevices(options?: ConnectorSearchDevicesOptions): Promise<ConnectorDevice[]>;
277
- connect(deviceId?: string): Promise<ConnectorSession>;
382
+ connect(deviceId?: string, options?: {
383
+ transportType: ConnectionType;
384
+ }): Promise<ConnectorSession>;
385
+ /**
386
+ * Structured form for connectors where a discovery handle and a stable
387
+ * device identity are different concepts. The string form remains for
388
+ * bridge and legacy compatibility.
389
+ */
390
+ connectTarget?(target: ConnectorConnectTarget): Promise<ConnectorSession>;
278
391
  disconnect(sessionId: string): Promise<void>;
279
392
  call(sessionId: string, method: string, params: unknown): Promise<ConnectorCallResult>;
280
393
  cancel(sessionId: string): Promise<void>;
@@ -299,6 +412,9 @@ interface IHardwareBridge {
299
412
  connect(params: {
300
413
  vendor: VendorType;
301
414
  deviceId?: string;
415
+ options?: {
416
+ transportType: ConnectionType;
417
+ };
302
418
  }): Promise<ConnectorSession>;
303
419
  disconnect(params: {
304
420
  vendor: VendorType;
@@ -581,11 +697,21 @@ interface SolSignedTx {
581
697
  /** Hex-encoded Ed25519 signature (no 0x prefix) */
582
698
  signature: string;
583
699
  }
584
- interface SolSignMsgParams extends PassphraseStateAware {
700
+ interface SolSignMessageBaseParams extends PassphraseStateAware {
585
701
  path: string;
586
702
  /** Message bytes as hex string (no 0x prefix) */
587
703
  message: string;
588
704
  }
705
+ interface SolOffchainMessageV1Params {
706
+ /** Finalized Solana off-chain message format. */
707
+ messageVersion: 1;
708
+ /** Complete signer set as 32-byte hex public keys. */
709
+ requiredSigners: string[];
710
+ }
711
+ type SolSignMsgParams = SolSignMessageBaseParams & ({
712
+ messageVersion?: undefined;
713
+ requiredSigners?: undefined;
714
+ } | SolOffchainMessageV1Params);
589
715
  interface SolSignature {
590
716
  /** Hex-encoded Ed25519 signature (no 0x prefix) */
591
717
  signature: string;
@@ -712,6 +838,12 @@ interface TronSignMsgParams extends PassphraseStateAware {
712
838
  path: string;
713
839
  /** Message hex (no 0x prefix) */
714
840
  messageHex: string;
841
+ /**
842
+ * TRON message scheme: 'V1' = legacy signMessage (prefix + 32-byte hash),
843
+ * 'V2' = TIP-191 signMessageV2 (prefix + byte length + message). Adapters
844
+ * that only implement one scheme reject the other with MethodNotSupported.
845
+ */
846
+ messageType?: 'V1' | 'V2';
715
847
  }
716
848
  interface TronSignature {
717
849
  /** 65-byte hex-encoded signature (no 0x prefix) */
@@ -723,100 +855,159 @@ interface ITronMethods {
723
855
  tronSignMessage(connectId?: NullableCallArg<string>, deviceId?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<TronSignMsgParams>>): Promise<Response<TronSignature>>;
724
856
  }
725
857
 
726
- /**
727
- * Fixed derivation paths used to generate chain fingerprints.
728
- * Uses standard index 0 — Ledger firmware shows device confirmation for
729
- * non-standard paths (e.g., index=100), which would interrupt wallet creation.
730
- * The address is hashed into a 16-char fingerprint, not exposed directly.
731
- * - EVM: cointype 60 (Ledger ETH App only supports 60)
732
- * - BTC: cointype 1 (testnet)
733
- * - SOL: cointype 501, standard 3-level hardened
734
- */
735
- declare const CHAIN_FINGERPRINT_PATHS: Record<ChainForFingerprint, string>;
736
- type ChainForFingerprint = 'evm' | 'btc' | 'sol' | 'tron';
737
- /**
738
- * 16-char SHA-256 fingerprint for device-identity verification.
739
- * Callers must canonicalize input (e.g. EVM address → lowercase) —
740
- * encoding variations otherwise cause false DeviceMismatch.
741
- */
742
- declare function deriveDeviceFingerprint(value: string): string;
743
-
744
858
  /** Events generated by SDK internal detection (not from hardware directly). */
745
859
  declare const SDK: {
746
860
  readonly DEVICE_STUCK: "device-stuck";
747
861
  readonly DEVICE_UNRESPONSIVE: "device-unresponsive";
748
862
  readonly DEVICE_RECOVERED: "device-recovered";
749
863
  readonly DEVICE_INTERACTION: "device-interaction";
864
+ readonly OPERATION_ENDED: "operation-ended";
750
865
  };
751
866
 
867
+ declare const OPERATION_DEFAULT_TTL_MS = 600000;
868
+ type OperationEndReason = 'explicit' | 'disconnect' | 'timeout' | 'runtime-reset';
869
+ type HardwareOperation = {
870
+ operationId: string;
871
+ connectId: string;
872
+ device: DeviceInfo;
873
+ connectionKeys: string[];
874
+ createdAt: number;
875
+ lastActiveAt: number;
876
+ };
877
+ type OperationRegistryOptions = {
878
+ vendor: VendorType;
879
+ ttlMs?: number;
880
+ onEnded?: (operation: HardwareOperation, reason: OperationEndReason) => void;
881
+ };
882
+ /** Runtime-only association between a public operation id and one live target. */
883
+ declare class OperationRegistry {
884
+ private readonly _vendor;
885
+ private readonly _ttlMs;
886
+ private readonly _onEnded?;
887
+ private readonly _active;
888
+ private readonly _ended;
889
+ constructor(options: OperationRegistryOptions);
890
+ create(params: {
891
+ searchTargetId: string;
892
+ connectId: string;
893
+ device: DeviceInfo;
894
+ connectionKeys?: string[];
895
+ }): HardwareOperation;
896
+ resolve(operationId: string): HardwareOperation;
897
+ /** Keep an operation alive while one device job is actively using it. */
898
+ retain(operationId: string): () => void;
899
+ /** Return active or tombstoned binding data without refreshing its TTL. */
900
+ find(operationId: string): HardwareOperation | undefined;
901
+ findActiveByConnectionKey(connectionKey: string): HardwareOperation | undefined;
902
+ /** Replace the live transport binding after the same target was reconnected. */
903
+ rebind(operationId: string, params: {
904
+ connectId: string;
905
+ device: DeviceInfo;
906
+ connectionKeys?: string[];
907
+ }): HardwareOperation;
908
+ end(operationId: string, reason: OperationEndReason): HardwareOperation | undefined;
909
+ endByConnectionKey(connectionKey: string, reason: OperationEndReason, exceptOperationId?: string): void;
910
+ endAll(reason: OperationEndReason, exceptOperationId?: string): void;
911
+ private _createTimer;
912
+ private _rememberEnded;
913
+ }
914
+
752
915
  type HardwareMethodMetadata = {
753
916
  chain: ChainForFingerprint;
754
917
  allNetwork: boolean;
918
+ /** Whether repeating the method after an ambiguous transport failure is safe. */
919
+ replayAfterTransportFailure: 'safe' | 'unsafe';
755
920
  };
756
921
  declare const HARDWARE_METHOD_CATALOG: {
757
922
  readonly evmGetAddress: {
758
923
  readonly chain: "evm";
759
924
  readonly allNetwork: true;
925
+ readonly replayAfterTransportFailure: "safe";
760
926
  };
761
927
  readonly evmSignTransaction: {
762
928
  readonly chain: "evm";
763
929
  readonly allNetwork: false;
930
+ readonly replayAfterTransportFailure: "unsafe";
764
931
  };
765
932
  readonly evmSignMessage: {
766
933
  readonly chain: "evm";
767
934
  readonly allNetwork: false;
935
+ readonly replayAfterTransportFailure: "unsafe";
768
936
  };
769
937
  readonly evmSignTypedData: {
770
938
  readonly chain: "evm";
771
939
  readonly allNetwork: false;
940
+ readonly replayAfterTransportFailure: "unsafe";
772
941
  };
773
942
  readonly btcGetAddress: {
774
943
  readonly chain: "btc";
775
944
  readonly allNetwork: true;
945
+ readonly replayAfterTransportFailure: "safe";
776
946
  };
777
947
  readonly btcGetPublicKey: {
778
948
  readonly chain: "btc";
779
949
  readonly allNetwork: true;
950
+ readonly replayAfterTransportFailure: "safe";
780
951
  };
781
952
  readonly btcSignTransaction: {
782
953
  readonly chain: "btc";
783
954
  readonly allNetwork: false;
955
+ readonly replayAfterTransportFailure: "unsafe";
784
956
  };
785
957
  readonly btcSignPsbt: {
786
958
  readonly chain: "btc";
787
959
  readonly allNetwork: false;
960
+ readonly replayAfterTransportFailure: "unsafe";
788
961
  };
789
962
  readonly btcSignMessage: {
790
963
  readonly chain: "btc";
791
964
  readonly allNetwork: false;
965
+ readonly replayAfterTransportFailure: "unsafe";
792
966
  };
793
967
  readonly btcGetMasterFingerprint: {
794
968
  readonly chain: "btc";
795
969
  readonly allNetwork: false;
970
+ readonly replayAfterTransportFailure: "safe";
796
971
  };
797
972
  readonly solGetAddress: {
798
973
  readonly chain: "sol";
799
974
  readonly allNetwork: true;
975
+ readonly replayAfterTransportFailure: "safe";
800
976
  };
801
977
  readonly solSignTransaction: {
802
978
  readonly chain: "sol";
803
979
  readonly allNetwork: false;
980
+ readonly replayAfterTransportFailure: "unsafe";
804
981
  };
805
982
  readonly solSignMessage: {
806
983
  readonly chain: "sol";
807
984
  readonly allNetwork: false;
985
+ readonly replayAfterTransportFailure: "unsafe";
808
986
  };
809
987
  readonly tronGetAddress: {
810
988
  readonly chain: "tron";
811
989
  readonly allNetwork: true;
990
+ readonly replayAfterTransportFailure: "safe";
812
991
  };
813
992
  readonly tronSignTransaction: {
814
993
  readonly chain: "tron";
815
994
  readonly allNetwork: false;
995
+ readonly replayAfterTransportFailure: "unsafe";
816
996
  };
817
997
  readonly tronSignMessage: {
818
998
  readonly chain: "tron";
819
999
  readonly allNetwork: false;
1000
+ readonly replayAfterTransportFailure: "unsafe";
1001
+ };
1002
+ readonly zcashGetFullViewingKey: {
1003
+ readonly chain: "zcash";
1004
+ readonly allNetwork: false;
1005
+ readonly replayAfterTransportFailure: "safe";
1006
+ };
1007
+ readonly zcashGetShieldedAddress: {
1008
+ readonly chain: "zcash";
1009
+ readonly allNetwork: false;
1010
+ readonly replayAfterTransportFailure: "safe";
820
1011
  };
821
1012
  };
822
1013
  type HardwareMethodName = keyof typeof HARDWARE_METHOD_CATALOG;
@@ -825,6 +1016,11 @@ type AllNetworkMethodName = {
825
1016
  }[HardwareMethodName];
826
1017
  declare const ALL_NETWORK_METHOD_NAMES: AllNetworkMethodName[];
827
1018
  declare function getHardwareMethodMetadata(method: string): HardwareMethodMetadata | undefined;
1019
+ /**
1020
+ * Conservative replay gate used only after a call may have reached hardware.
1021
+ * Unknown methods and device mutations are unsafe by default.
1022
+ */
1023
+ declare function canReplayHardwareMethodAfterTransportFailure(method: string): boolean;
828
1024
  declare function isAllNetworkMethodName(method: string): method is AllNetworkMethodName;
829
1025
  declare function getAllNetworkMethodChain(method: AllNetworkMethodName): ChainForFingerprint;
830
1026
 
@@ -843,7 +1039,7 @@ type HardwareUiEvent = Exclude<ConnectorUiEvent, {
843
1039
  progress: number;
844
1040
  };
845
1041
  };
846
- type ChainCapability = 'evm' | 'btc' | 'sol' | 'tron';
1042
+ type ChainCapability = 'evm' | 'btc' | 'sol' | 'tron' | 'zcash';
847
1043
  type TrezorDisplayRotation = 'North' | 'East' | 'South' | 'West';
848
1044
  type TrezorSafetyCheckLevel = 'Strict' | 'PromptAlways' | 'PromptTemporarily';
849
1045
  type TrezorDeviceSettingsParams = {
@@ -920,13 +1116,68 @@ type DeviceAuthenticityResult = {
920
1116
  * that aren't specific to one chain. Vendor-specific options can be added
921
1117
  * as typed sub-fields here when a vendor actually needs them.
922
1118
  */
923
- interface ICommonCallParams {
1119
+ /** Persisted connection hints, never proof of device or wallet identity. */
1120
+ type KnownDeviceConnection = {
1121
+ transport: 'usb' | 'ble';
1122
+ connectId: string;
1123
+ } | {
1124
+ transport: 'qr';
1125
+ };
1126
+ /** Opaque host lookup identifiers. Never forward these to firmware or logs. */
1127
+ type HardwareCallExtra = Readonly<Record<string, string>>;
1128
+ interface IHardwareConnectionContext {
1129
+ knownConnections?: readonly KnownDeviceConnection[];
1130
+ extra?: HardwareCallExtra;
1131
+ /** False makes discovery fail instead of asking the user to select a new endpoint. */
1132
+ allowDeviceSelection?: boolean;
1133
+ }
1134
+ type DeviceSelectionContext = {
1135
+ kind: 'select-device';
1136
+ transport: 'usb';
1137
+ reason: 'multiple-candidates';
1138
+ } | {
1139
+ kind: 'bind-connection';
1140
+ transport: 'ble';
1141
+ reason: 'missing-binding' | 'known-connection-unavailable' | 'manual-rebind';
1142
+ };
1143
+ interface DeviceSelectionRequest {
1144
+ devices: DeviceInfo[];
1145
+ requestId: string;
1146
+ context: DeviceSelectionContext;
1147
+ extra?: HardwareCallExtra;
1148
+ /** Repeated snapshots with this requestId update one SDK-owned binding scan. */
1149
+ scanning?: boolean;
1150
+ bindingSessionId?: string;
1151
+ /** A candidate rejected by SDK identity verification in this binding session. */
1152
+ rejectedConnectId?: string;
1153
+ }
1154
+ /** The SDK has verified this endpoint; the host must persist it before acknowledging. */
1155
+ interface SaveDeviceBindingRequest {
1156
+ requestId: string;
1157
+ selectionRequestId: string;
1158
+ connection: {
1159
+ transport: 'ble';
1160
+ connectId: string;
1161
+ };
1162
+ identity: Extract<WalletIdentity, {
1163
+ vendor: 'ledger' | 'trezor';
1164
+ }>;
1165
+ extra?: HardwareCallExtra;
1166
+ }
1167
+ type BindBleDeviceParams = Pick<SaveDeviceBindingRequest, 'identity' | 'extra'>;
1168
+ interface DeviceBindingStatus {
1169
+ selectionRequestId: string;
1170
+ status: 'verifying' | 'saved' | 'failed' | 'cancelled';
1171
+ }
1172
+ interface ICommonCallParams extends IHardwareConnectionContext {
924
1173
  /**
925
1174
  * When the required device app is missing, prompt the user (UI request)
926
1175
  * to install it, stream install progress, then retry the operation once.
927
1176
  * Off by default — preserves the plain "app not installed" failure.
928
1177
  */
929
1178
  autoInstallApp?: boolean;
1179
+ /** Runtime-only id returned by connectDevice(). When present, discovery and fallback are disabled. */
1180
+ operationId?: string;
930
1181
  }
931
1182
  type NullableCallArg<T> = T | null | undefined;
932
1183
  interface IPassphraseCallParams {
@@ -935,6 +1186,15 @@ interface IPassphraseCallParams {
935
1186
  }
936
1187
  type IHardwareCommonCallParams = ICommonCallParams & IPassphraseCallParams;
937
1188
  type IHardwareCallParams<T> = T & IHardwareCommonCallParams;
1189
+ /**
1190
+ * Runtime-only context for device-manager operations. The expected identity
1191
+ * lets an adapter fail closed before a read or mutation is replayed after a
1192
+ * reconnect. It must never be forwarded to vendor firmware.
1193
+ */
1194
+ interface IDeviceManagerOperationContext extends IHardwareConnectionContext {
1195
+ operationId?: string;
1196
+ expectedDeviceIdentity?: WalletIdentity;
1197
+ }
938
1198
  interface AllNetworkAddressParams {
939
1199
  network: string;
940
1200
  path: string;
@@ -945,16 +1205,7 @@ interface AllNetworkAddressParams {
945
1205
  interface AllNetworkGetAddressParams extends IHardwareCommonCallParams {
946
1206
  bundle: AllNetworkAddressParams[];
947
1207
  }
948
- type AllNetworkDeviceIdentity = {
949
- vendor: 'ledger';
950
- type: 'chainFingerprint';
951
- chain: ChainForFingerprint;
952
- value: string;
953
- } | {
954
- vendor: 'trezor';
955
- type: 'deviceId';
956
- value: string;
957
- };
1208
+ type AllNetworkDeviceIdentity = WalletIdentity;
958
1209
  type AllNetworkAddressResponsePayload = Record<string, unknown> & {
959
1210
  error?: string;
960
1211
  code?: HardwareErrorCode | number;
@@ -962,6 +1213,7 @@ type AllNetworkAddressResponsePayload = Record<string, unknown> & {
962
1213
  connectId?: string;
963
1214
  deviceId?: string;
964
1215
  deviceIdentity?: AllNetworkDeviceIdentity;
1216
+ rootFingerprint?: number;
965
1217
  chainFingerprint?: string;
966
1218
  chainFingerprintChain?: ChainForFingerprint;
967
1219
  params?: Record<string, unknown>;
@@ -1047,9 +1299,13 @@ type UiRequestEvent = {
1047
1299
  };
1048
1300
  } | {
1049
1301
  type: typeof UI_REQUEST.REQUEST_SELECT_DEVICE;
1050
- payload: {
1051
- devices: DeviceInfo[];
1052
- };
1302
+ payload: DeviceSelectionRequest;
1303
+ } | {
1304
+ type: typeof UI_REQUEST.REQUEST_SAVE_DEVICE_BINDING;
1305
+ payload: SaveDeviceBindingRequest;
1306
+ } | {
1307
+ type: typeof UI_REQUEST.DEVICE_BINDING_STATUS;
1308
+ payload: DeviceBindingStatus;
1053
1309
  } | {
1054
1310
  type: typeof UI_REQUEST.REQUEST_DEVICE_CONNECT;
1055
1311
  payload: {
@@ -1109,6 +1365,12 @@ type SdkEvent = {
1109
1365
  payload: {
1110
1366
  connectId: string;
1111
1367
  };
1368
+ } | {
1369
+ type: typeof SDK.OPERATION_ENDED;
1370
+ payload: {
1371
+ operationId: string;
1372
+ reason: OperationEndReason;
1373
+ };
1112
1374
  };
1113
1375
  type HardwareEvent = DeviceEvent | UiRequestEvent | SdkEvent | HardwareUiEvent;
1114
1376
  type DeviceEventListener = (event: HardwareEvent) => void;
@@ -1119,6 +1381,14 @@ type DeviceEventListener = (event: HardwareEvent) => void;
1119
1381
  * and the value is the narrowed event object the listener will receive.
1120
1382
  */
1121
1383
  interface HardwareEventMap {
1384
+ [UI_REQUEST.DEVICE_BINDING_STATUS]: {
1385
+ type: typeof UI_REQUEST.DEVICE_BINDING_STATUS;
1386
+ payload: DeviceBindingStatus;
1387
+ };
1388
+ [UI_REQUEST.REQUEST_SAVE_DEVICE_BINDING]: {
1389
+ type: typeof UI_REQUEST.REQUEST_SAVE_DEVICE_BINDING;
1390
+ payload: SaveDeviceBindingRequest;
1391
+ };
1122
1392
  'ui-event': HardwareUiEvent;
1123
1393
  [DEVICE.CONNECT]: {
1124
1394
  type: typeof DEVICE.CONNECT;
@@ -1206,9 +1476,7 @@ interface HardwareEventMap {
1206
1476
  };
1207
1477
  [UI_REQUEST.REQUEST_SELECT_DEVICE]: {
1208
1478
  type: typeof UI_REQUEST.REQUEST_SELECT_DEVICE;
1209
- payload: {
1210
- devices: DeviceInfo[];
1211
- };
1479
+ payload: DeviceSelectionRequest;
1212
1480
  };
1213
1481
  [UI_REQUEST.REQUEST_DEVICE_CONNECT]: {
1214
1482
  type: typeof UI_REQUEST.REQUEST_DEVICE_CONNECT;
@@ -1271,16 +1539,23 @@ interface HardwareEventMap {
1271
1539
  connectId: string;
1272
1540
  };
1273
1541
  };
1542
+ [SDK.OPERATION_ENDED]: {
1543
+ type: typeof SDK.OPERATION_ENDED;
1544
+ payload: {
1545
+ operationId: string;
1546
+ reason: OperationEndReason;
1547
+ };
1548
+ };
1274
1549
  }
1275
1550
  interface IDeviceManagerMethods {
1276
- getFeatures?(connectId: string): Promise<Response<Record<string, unknown>>>;
1277
- deviceSettings?(connectId: string, params: TrezorDeviceSettingsParams): Promise<Response<Record<string, unknown>>>;
1278
- setBrightness?(connectId: string, params?: TrezorBrightnessParams): Promise<Response<Record<string, unknown>>>;
1279
- changePin?(connectId: string, params?: TrezorChangePinParams): Promise<Response<Record<string, unknown>>>;
1280
- wipeDevice?(connectId: string): Promise<Response<Record<string, unknown>>>;
1551
+ getFeatures?(connectId: string, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
1552
+ deviceSettings?(connectId: string, params: TrezorDeviceSettingsParams, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
1553
+ setBrightness?(connectId: string, params?: TrezorBrightnessParams, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
1554
+ changePin?(connectId: string, params?: TrezorChangePinParams, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
1555
+ wipeDevice?(connectId: string, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
1281
1556
  authenticateDevice?(connectId: string, params: {
1282
1557
  challenge: string;
1283
- }): Promise<Response<Record<string, unknown>>>;
1558
+ }, operationContext?: IDeviceManagerOperationContext): Promise<Response<Record<string, unknown>>>;
1284
1559
  }
1285
1560
  interface IWalletStateMethods {
1286
1561
  /**
@@ -1307,7 +1582,7 @@ interface IWalletStateMethods {
1307
1582
  * Optional: vendors without host-managed passphrase sessions (Ledger) omit
1308
1583
  * it. Implemented by `TrezorAdapter`.
1309
1584
  */
1310
- getPassphraseState?(connectId: string, passphraseState?: string): Promise<Response<string | null>>;
1585
+ getPassphraseState?(connectId: string, passphraseState?: string, operationContext?: IDeviceManagerOperationContext): Promise<Response<string | null>>;
1311
1586
  }
1312
1587
  interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, ISolMethods, ITronMethods, IDeviceManagerMethods, IWalletStateMethods {
1313
1588
  readonly vendor: string;
@@ -1317,10 +1592,19 @@ interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, I
1317
1592
  getAvailableTransports(): TransportType[];
1318
1593
  switchTransport(type: TransportType): Promise<void>;
1319
1594
  searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
1320
- connectDevice(connectId: string): Promise<Response<string>>;
1321
- disconnectDevice(connectId: string): Promise<void>;
1595
+ /** Discover selectable hardware entries without claiming identified devices or wallets. */
1596
+ searchDeviceTargets(options?: SearchDevicesOptions): Promise<DeviceSearchTarget[]>;
1597
+ /** @deprecated Use searchDeviceTargets(). */
1598
+ listConnectionTargets(options?: SearchDevicesOptions): Promise<ConnectionTarget[]>;
1599
+ /** Connect or logically bind a selected search result and return a runtime-only operation id. */
1600
+ connectDevice(searchTargetId: string): Promise<Response<string>>;
1601
+ /** Explicit Device Manager binding: verify the existing identity before replacing its BLE locator. */
1602
+ bindBleDevice?(params: BindBleDeviceParams): Promise<Response<string>>;
1603
+ /** Resolve operation-first routing/selection and pin it. The caller must verify wallet identity before business calls. */
1604
+ acquireOperation?(connectId: string, context: IHardwareConnectionContext): Promise<Response<string>>;
1605
+ /** Release an operation owned by the caller. Disconnect events end matching operations automatically. */
1606
+ releaseOperation(operationId: string): Promise<void>;
1322
1607
  getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
1323
- getSupportedChains(): ChainCapability[];
1324
1608
  /** Abort the in-flight call. Omit connectId to cancel whatever is active. */
1325
1609
  cancel(connectId?: string): void;
1326
1610
  allNetworkGetAddress(connectId: string, deviceId: string, params: AllNetworkGetAddressParams): Promise<Response<AllNetworkAddressResponse[]>>;
@@ -1357,6 +1641,14 @@ interface SearchDevicesOptions {
1357
1641
  * was discovered first.
1358
1642
  */
1359
1643
  waitForAllTransports?: boolean;
1644
+ /**
1645
+ * Restrict discovery to one transport. A non-enumerable channel may return
1646
+ * a virtual connection target (for example Keystone QR), but discovery must
1647
+ * not start a wallet protocol or account-export interaction. The target is
1648
+ * resolved by the following `connectDevice()` call. Omit to scan everything
1649
+ * available.
1650
+ */
1651
+ transportType?: ConnectionType;
1360
1652
  }
1361
1653
 
1362
1654
  interface EvmGetAddressParams extends PassphraseStateAware {
@@ -1480,6 +1772,14 @@ interface EvmSignTypedDataFull extends PassphraseStateAware {
1480
1772
  primaryType: string;
1481
1773
  message: Record<string, unknown>;
1482
1774
  };
1775
+ /**
1776
+ * The dApp's original EIP-712 JSON, byte for byte. Vendors that hand the
1777
+ * device a serialized payload (Keystone) must prefer this over
1778
+ * re-stringifying `data`: a JSON round trip rewrites integer literals wider
1779
+ * than 2^53 and exponent forms, so the device would display and sign
1780
+ * something the dApp never sent.
1781
+ */
1782
+ dataJson?: string;
1483
1783
  metamaskV4Compat?: boolean;
1484
1784
  showMessageHash?: boolean;
1485
1785
  /**
@@ -1518,6 +1818,33 @@ interface IEvmMethods {
1518
1818
  evmSignTypedData(connectId?: NullableCallArg<string>, deviceId?: NullableCallArg<string>, params?: NullableCallArg<IHardwareCallParams<EvmSignTypedDataParams>>): Promise<Response<EvmSignature>>;
1519
1819
  }
1520
1820
 
1821
+ /** Which `GET_VK` encoding the Ledger Zcash app should return. */
1822
+ type ZcashFullViewingKeyMode = 'ufvk' | 'orchardFvk';
1823
+ interface ZcashGetFullViewingKeyParams extends PassphraseStateAware {
1824
+ /** BIP44 account path `m/44'/133'/a'` (any deeper transparent path is accepted; only the account level is used). */
1825
+ path: string;
1826
+ /** Default `ufvk`. */
1827
+ mode?: ZcashFullViewingKeyMode;
1828
+ }
1829
+ interface ZcashFullViewingKey {
1830
+ path: string;
1831
+ mode: ZcashFullViewingKeyMode;
1832
+ /** ZIP-316 bech32m UFVK string (mode `ufvk`). */
1833
+ ufvk?: string;
1834
+ /** 96-byte raw Orchard FVK as hex (mode `orchardFvk`). */
1835
+ orchardFvk?: string;
1836
+ }
1837
+ interface ZcashGetShieldedAddressParams extends PassphraseStateAware {
1838
+ /** Full 5-level transparent path `m/44'/133'/a'/0/i`; the Orchard path is derived from it. */
1839
+ path: string;
1840
+ showOnDevice?: boolean;
1841
+ }
1842
+ interface ZcashShieldedAddress {
1843
+ /** Unified address with a single Orchard receiver. */
1844
+ address: string;
1845
+ path: string;
1846
+ }
1847
+
1521
1848
  /**
1522
1849
  * Low-level device descriptor from Transport layer.
1523
1850
  * Represents a physical device detected by USB/BLE scanning.
@@ -1563,14 +1890,18 @@ interface DeviceDisconnectEvent {
1563
1890
  type DeviceChangeEvent = DeviceConnectEvent | DeviceDisconnectEvent;
1564
1891
 
1565
1892
  /**
1566
- * Pure FIFO job queue. Every enqueue chains onto the tail; jobs run one at
1567
- * a time across all devices. The queue is intentionally passive — it does
1568
- * NOT decide whether to interrupt or ask the user. Those are application-
1569
- * layer concerns owned by the caller (e.g. a UI button handler that wants
1570
- * to ask "device is busy, interrupt current?" before submitting). The
1571
- * queue exposes inspection (`getActiveJob`) and explicit cancellation
1572
- * (`cancelActive` / `cancelAll`) so callers can implement those policies
1573
- * synchronously, without racing against in-flight enqueues.
1893
+ * Serializes every device call and gives callers one handle to cancel them.
1894
+ *
1895
+ * Ordering is the lesser half of the job: calls already await each other, and
1896
+ * nothing in the app issues two device operations at once. What this buys is
1897
+ * the rest — an AbortController per job so a cancel has something to pull, a
1898
+ * busy check so a double-submit is refused rather than queued, and generation
1899
+ * tracking so a job that was queued before a teardown does not start after it.
1900
+ * Those races exist in a perfectly sequential caller, because cleanup is async.
1901
+ *
1902
+ * The queue never decides whether to interrupt or ask the user; the caller owns
1903
+ * that. `getActiveJob()` reads synchronously so a UI handler can look, decide,
1904
+ * and submit in one turn without racing an in-flight enqueue.
1574
1905
  */
1575
1906
  interface JobOptions {
1576
1907
  label?: string;
@@ -1594,21 +1925,53 @@ declare class DeviceJobQueue {
1594
1925
  * `deviceId` is a label only — used by inspection / cancellation routing.
1595
1926
  */
1596
1927
  enqueue<T>(deviceId: string, job: (signal: AbortSignal) => Promise<T>, options?: JobOptions): Promise<T>;
1597
- /** Cancel the active job. If `deviceId` is given, only cancels when it matches. */
1598
- cancelActive(deviceId?: string): boolean;
1599
- /** Force cancel the active job. `reason` becomes signal.reason. */
1600
- forceCancelActive(deviceId?: string, reason?: Error): boolean;
1601
- /** Cancel the active job (alias for callers that previously needed multi-device cancel). */
1602
- cancelAllActive(reason?: Error): void;
1928
+ /** Cancel the running job. `reason` becomes signal.reason. */
1929
+ cancelActive(deviceId?: string, reason?: Error): boolean;
1603
1930
  /** Cancel the active job and invalidate queued jobs that have not started. */
1604
1931
  cancelActiveAndPending(deviceId?: string, reason?: Error): boolean;
1605
1932
  /** Get info about the currently active job, or null if idle. */
1606
1933
  getActiveJob(deviceId?: string): ActiveJobInfo | null;
1607
- /** True if any job is currently running. */
1608
- isBusy(): boolean;
1609
1934
  clear(reason?: Error): void;
1610
1935
  }
1611
1936
 
1937
+ declare const HARDWARE_RUNTIME_ID_PREFIX = "hwk:runtime";
1938
+ /**
1939
+ * Scopes a runtime id can name. Each is a different lifetime, and none of them
1940
+ * nests cleanly inside another:
1941
+ *
1942
+ * - `search-target` — one device in one discovery snapshot. Dies on the next
1943
+ * search of the same kind, so a stale pick is refused rather than silently
1944
+ * resolved against a different unit.
1945
+ * - `link` — one open transport. Outlives the snapshot that produced it.
1946
+ * - `operation` — one business operation. Outlives the link: `rebind()` swaps
1947
+ * the transport underneath while the id stays the same.
1948
+ */
1949
+ type HardwareRuntimeIdKind = 'operation' | 'search-target' | 'link';
1950
+ type HardwareRuntimeId = {
1951
+ kind: HardwareRuntimeIdKind;
1952
+ vendor: VendorType;
1953
+ };
1954
+ /** Runtime ids are opaque and must never be persisted as device identity. */
1955
+ declare function createHardwareOperationId(vendor: VendorType): string;
1956
+ /** Search targets are valid only for the adapter's current discovery snapshot. */
1957
+ declare function createHardwareSearchTargetId(vendor: VendorType): string;
1958
+ declare function createHardwareLinkId(vendor: VendorType): string;
1959
+ declare function hasHardwareRuntimeIdPrefix(value: unknown): value is string;
1960
+ declare function parseHardwareRuntimeId(value: unknown): HardwareRuntimeId | undefined;
1961
+ declare function isHardwareOperationId(value: unknown): value is string;
1962
+
1963
+ interface HardwareOperationTarget {
1964
+ /** Effective target accepted by existing adapter/connector call paths. */
1965
+ targetId: string | undefined;
1966
+ /** Present when this operation is pinned to a live operation. */
1967
+ operationId: string | undefined;
1968
+ }
1969
+ /**
1970
+ * Normalizes the transitional positional operation id and the canonical
1971
+ * common-params field. All vendors must reject conflicting bindings.
1972
+ */
1973
+ declare function resolveHardwareOperationTarget(positionalTargetId: string | null | undefined, commonOperationId: string | null | undefined, expectedVendor?: VendorType): Response<HardwareOperationTarget>;
1974
+
1612
1975
  /**
1613
1976
  * Minimal typed event emitter using Map<string, Set<listener>>.
1614
1977
  * Each adapter uses this for device events (connect, disconnect, pin, etc.).
@@ -1635,6 +1998,104 @@ declare class TypedEventEmitter<TMap extends Record<string, any> = Record<string
1635
1998
  listenerCount(event: string): number;
1636
1999
  }
1637
2000
 
2001
+ /** Serializable BLE transport data shared by Electron main and renderer runtimes. */
2002
+ interface ElectronBleDeviceInfo {
2003
+ id: string;
2004
+ name?: string;
2005
+ rssi?: number;
2006
+ advertisedServiceUuids?: string[];
2007
+ }
2008
+ /**
2009
+ * How the main process recognizes one vendor's peripherals. Everything here
2010
+ * crosses IPC, so it is data rather than predicates: the handler owns no
2011
+ * vendor knowledge of its own. A peripheral matches when it advertises one of
2012
+ * `serviceUuids`, or when its local name matches every entry in
2013
+ * `namePatterns` (each is a case-insensitive regular expression source, so a
2014
+ * single entry can carry alternations).
2015
+ */
2016
+ interface ElectronBleMatch {
2017
+ serviceUuids?: string[];
2018
+ namePatterns?: string[];
2019
+ }
2020
+ interface ElectronBleScanOptions {
2021
+ /** Opaque partition key: results and connected devices never mix across it. */
2022
+ vendor?: string;
2023
+ match?: ElectronBleMatch;
2024
+ /** @deprecated Superseded by `match.serviceUuids`. */
2025
+ serviceUuids?: string[];
2026
+ durationMs?: number;
2027
+ }
2028
+ /** GATT profile plus the write framing this vendor's firmware expects. */
2029
+ interface ElectronBleConnectOptions {
2030
+ vendor: string;
2031
+ serviceUuid: string;
2032
+ writeUuid: string;
2033
+ notifyUuid: string;
2034
+ /**
2035
+ * `padded` splits into fixed `chunkSize` packets, zero-filling the last one
2036
+ * — Trezor firmware silently drops a short packet. `raw` writes the buffer
2037
+ * as given, for framing that carries its own length (Ledger).
2038
+ */
2039
+ write?: {
2040
+ mode: 'padded' | 'raw';
2041
+ chunkSize?: number;
2042
+ chunkDelayMs?: number;
2043
+ maxLength?: number;
2044
+ };
2045
+ }
2046
+ /** Native code handles GATT only; framing, identity checks and wallet operations stay in the SDK. */
2047
+ interface ElectronBleApi {
2048
+ scan(options?: ElectronBleScanOptions): Promise<ElectronBleDeviceInfo[]>;
2049
+ stopScan(): Promise<void>;
2050
+ connect(id: string, options?: ElectronBleConnectOptions): Promise<{
2051
+ id: string;
2052
+ name?: string;
2053
+ }>;
2054
+ disconnect(id: string): Promise<void>;
2055
+ subscribe(id: string): Promise<void>;
2056
+ unsubscribe(id: string): Promise<void>;
2057
+ write(id: string, hexData: string): Promise<void>;
2058
+ checkAvailability(): Promise<{
2059
+ available: boolean;
2060
+ state: string;
2061
+ initialized: boolean;
2062
+ }>;
2063
+ getDevice(id: string): Promise<ElectronBleDeviceInfo | null>;
2064
+ onNotification(handler: (id: string, hexData: string) => void): () => void;
2065
+ onDeviceDisconnected(handler: (id: string) => void): () => void;
2066
+ }
2067
+
2068
+ /**
2069
+ * The outcome of asking the host to persist a verified binding. A refusal is
2070
+ * reported, never thrown: by this point the SDK has already verified that the
2071
+ * connected wallet is the one the operation expects, so anything the host says
2072
+ * back is about the host's own records. Losing the binding is worth a warning
2073
+ * and a retry next time; it is not a reason to fail work the user asked for.
2074
+ */
2075
+ type SaveDeviceBindingOutcome = {
2076
+ saved: true;
2077
+ } | {
2078
+ saved: false;
2079
+ reason: SaveDeviceBindingDeclineReason;
2080
+ };
2081
+ /** Persist a verified binding through the host. Only a user abort throws. */
2082
+ declare function requestSaveDeviceBinding(emitter: TypedEventEmitter<HardwareEventMap>, registry: UiRequestRegistry, binding: Omit<SaveDeviceBindingRequest, 'requestId'>, signal?: AbortSignal): Promise<SaveDeviceBindingOutcome>;
2083
+
2084
+ /** Discovery and selection share one owner; never connect until the last scan has drained. */
2085
+ declare function requestBleDeviceSelection({ emitter, registry, request, scan, signal, allowUsbFallback, pollIntervalMs, }: {
2086
+ emitter: TypedEventEmitter<HardwareEventMap>;
2087
+ registry: UiRequestRegistry;
2088
+ request: Omit<DeviceSelectionRequest, 'requestId' | 'scanning'>;
2089
+ scan: () => Promise<DeviceInfo[]>;
2090
+ signal: AbortSignal;
2091
+ /** The adapter must verify a returned USB candidate before dispatching any business call. */
2092
+ allowUsbFallback?: boolean;
2093
+ pollIntervalMs?: number;
2094
+ }): Promise<{
2095
+ device: DeviceInfo;
2096
+ requestId: string;
2097
+ }>;
2098
+
1638
2099
  /**
1639
2100
  * Compare two semver strings (e.g. "2.1.0" vs "2.3.1").
1640
2101
  * Returns -1 if a < b, 0 if equal, 1 if a > b.
@@ -1655,7 +2116,18 @@ declare function hexToBytes(hex: string): Uint8Array;
1655
2116
  /** Convert a Uint8Array to a hex string (no 0x prefix). */
1656
2117
  declare function bytesToHex(bytes: Uint8Array): string;
1657
2118
 
1658
- type DetectableHardwareVendor = 'onekey' | 'trezor' | 'ledger';
2119
+ interface PrepareSolanaOffchainMessageV1Params {
2120
+ message: Uint8Array;
2121
+ requiredSigners: readonly string[];
2122
+ }
2123
+ interface PreparedSolanaOffchainMessageV1 {
2124
+ messageText: string;
2125
+ requiredSigners: string[];
2126
+ serializedMessage: Uint8Array;
2127
+ }
2128
+ declare function prepareSolanaOffchainMessageV1({ message, requiredSigners, }: PrepareSolanaOffchainMessageV1Params): PreparedSolanaOffchainMessageV1;
2129
+
2130
+ type DetectableHardwareVendor = 'onekey' | 'trezor' | 'ledger' | 'keystone';
1659
2131
  type HardwareDeviceIdentityInput = {
1660
2132
  name?: string | null;
1661
2133
  localName?: string | null;
@@ -1722,4 +2194,4 @@ declare function buildUnsupportedMethodResponse(item: AllNetworkAddressParams):
1722
2194
 
1723
2195
  declare const DEVICE_CONNECT_RETRY_DELAY_MS = 1000;
1724
2196
 
1725
- export { ALL_NETWORK_METHOD_NAMES, type ActiveJobInfo, type AllNetworkAddressParams, type AllNetworkAddressResponse, type AllNetworkAddressResponsePayload, type AllNetworkAttachIdentityContext, type AllNetworkCallItemContext, type AllNetworkGetAddressParams, type AllNetworkMethodName, type AllNetworkResponseContext, type BtcAddress, type BtcGetAddressParams, type BtcGetPublicKeyParams, type BtcPaymentRequest, type BtcPaymentRequestMemo, type BtcPublicKey, type BtcRefTransaction, type BtcSignMsgParams, type BtcSignPsbtParams, type BtcSignTxParams, type BtcSignature, type BtcSignedPsbt, type BtcSignedTx, type BtcTxInput, type BtcTxOutput, CHAIN_FINGERPRINT_PATHS, type ChainCapability, type ChainForFingerprint, type ConnectionType, type ConnectorCallResult, type ConnectorConfig, type ConnectorDevice, type ConnectorErrorParams, type ConnectorEventMap, type ConnectorEventType, type ConnectorSerializedError, type ConnectorSession, type ConnectorUiEvent, DEVICE, DEVICE_CONNECT_RETRY_DELAY_MS, DEVICE_EVENT, type DetectableHardwareVendor, type DeviceAuthenticityParams, type DeviceAuthenticityResult, type DeviceCapabilities, type DeviceChangeEvent, type DeviceConnectEvent, type DeviceDescriptor, type DeviceDisconnectEvent, type DeviceEvent, type DeviceEventListener, type DeviceInfo, DeviceJobQueue, type DeviceTarget, EConnectorInteraction, type EIP712Domain, type EvmAddress, type EvmEthereumDefinitions, type EvmGetAddressParams, type EvmPaymentRequest, type EvmPaymentRequestMemo, type EvmSignMsgParams, type EvmSignTxLedgerParams, type EvmSignTxParams, type EvmSignTxTrezorParams, type EvmSignTypedDataFull, type EvmSignTypedDataHash, type EvmSignTypedDataParams, type EvmSignature, type EvmSignedTx, type Failure, HARDWARE_METHOD_CATALOG, type HardwareDeviceIdentityInput, HardwareErrorCode, type HardwareEvent, type HardwareEventMap, type HardwareMethodMetadata, type HardwareMethodName, type HardwareUiEvent, type IBtcMethods, type ICommonCallParams, type IConnector, type IDeviceManagerMethods, type IEvmMethods, type IHardwareBridge, type IHardwareCallParams, type IHardwareCommonCallParams, type IHardwareWallet, type IPassphraseCallParams, type ISolMethods, type ITronMethods, type IWalletStateMethods, type JobOptions, type NullableCallArg, type PassphraseResponse, type PassphraseStateAware, QrDisplayData, type Response, type RunAllNetworkGetAddressOptions, SDK, type SdkEvent, type SearchDevicesOptions, type SolAddress, type SolGetAddressParams, type SolSignMsgParams, type SolSignTxParams, type SolSignature, type SolSignedTx, type Success, type TransportType, type TrezorBrightnessParams, type TrezorChangePinParams, type TrezorDeviceSettingsParams, type TrezorDisplayRotation, type TrezorSafetyCheckLevel, type TronAddress, type TronContract, type TronFreezeBalanceV2Contract, type TronGetAddressParams, type TronResource, type TronSignMsgParams, type TronSignTxParams, type TronSignature, type TronSignedTx, type TronTransferContract, type TronTriggerSmartContract, type TronUnfreezeBalanceV2Contract, type TronVote, type TronVoteWitnessContract, type TronWithdrawExpireUnfreezeContract, TypedEventEmitter, UI_REQUEST, type UiRequestEvent, UiResponseEvent, type VendorType, batchCall, buildUnsupportedMethodResponse, bytesToHex, compareSemver, createBridgedConnector, createCombinedConnector, deriveDeviceFingerprint, detectHardwareVendorFromDescriptor, ensure0x, failure, getAllNetworkMethodChain, getHardwareMethodMetadata, hexToBytes, isAllNetworkMethodName, isKnownNonTargetHardwareVendor, padHex64, rehydrateConnectorError, runAllNetworkGetAddress, serializeConnectorError, stripHex, success };
2197
+ export { ALL_NETWORK_METHOD_NAMES, type ActiveJobInfo, type AllNetworkAddressParams, type AllNetworkAddressResponse, type AllNetworkAddressResponsePayload, type AllNetworkAttachIdentityContext, type AllNetworkCallItemContext, type AllNetworkDeviceIdentity, type AllNetworkGetAddressParams, type AllNetworkMethodName, type AllNetworkResponseContext, type BindBleDeviceParams, type BtcAddress, type BtcGetAddressParams, type BtcGetPublicKeyParams, type BtcPaymentRequest, type BtcPaymentRequestMemo, type BtcPublicKey, type BtcRefTransaction, type BtcSignMsgParams, type BtcSignPsbtParams, type BtcSignTxParams, type BtcSignature, type BtcSignedPsbt, type BtcSignedTx, type BtcTxInput, type BtcTxOutput, CHAIN_FINGERPRINT_PATHS, type ChainCapability, type ChainForFingerprint, type ConnectionTarget, type ConnectionType, type ConnectorCallResult, type ConnectorConfig, type ConnectorConnectTarget, type ConnectorDevice, type ConnectorErrorParams, type ConnectorEventMap, type ConnectorEventType, type ConnectorSearchDevicesOptions, type ConnectorSerializedError, type ConnectorSession, type ConnectorUiEvent, DEVICE, DEVICE_CONNECT_RETRY_DELAY_MS, DEVICE_EVENT, type DetectableHardwareVendor, type DeviceAuthenticityParams, type DeviceAuthenticityResult, type DeviceBindingStatus, type DeviceCapabilities, type DeviceChangeEvent, type DeviceConnectEvent, type DeviceDescriptor, type DeviceDisconnectEvent, type DeviceEvent, type DeviceEventListener, type DeviceInfo, DeviceJobQueue, type DeviceSearchTarget, type DeviceSelectionContext, type DeviceSelectionRequest, type DeviceTarget, EConnectorInteraction, type EIP712Domain, type ElectronBleApi, type ElectronBleConnectOptions, type ElectronBleDeviceInfo, type ElectronBleMatch, type ElectronBleScanOptions, type EvmAddress, type EvmEthereumDefinitions, type EvmGetAddressParams, type EvmPaymentRequest, type EvmPaymentRequestMemo, type EvmSignMsgParams, type EvmSignTxLedgerParams, type EvmSignTxParams, type EvmSignTxTrezorParams, type EvmSignTypedDataFull, type EvmSignTypedDataHash, type EvmSignTypedDataParams, type EvmSignature, type EvmSignedTx, type Failure, HARDWARE_METHOD_CATALOG, HARDWARE_RUNTIME_ID_PREFIX, type HardwareCallExtra, type HardwareDeviceIdentityInput, HardwareErrorCode, type HardwareEvent, type HardwareEventMap, type HardwareMethodMetadata, type HardwareMethodName, type HardwareOperation, type HardwareOperationTarget, type HardwareRuntimeId, type HardwareRuntimeIdKind, type HardwareUiEvent, HwkErrorOrigin, HwkRecoveryHint, type IBtcMethods, type ICommonCallParams, type IConnector, type IDeviceManagerMethods, type IDeviceManagerOperationContext, type IEvmMethods, type IHardwareBridge, type IHardwareCallParams, type IHardwareCommonCallParams, type IHardwareConnectionContext, type IHardwareWallet, type IPassphraseCallParams, type ISolMethods, type ITronMethods, type IWalletStateMethods, type JobOptions, type KnownDeviceConnection, type NullableCallArg, OPERATION_DEFAULT_TTL_MS, type OperationEndReason, OperationRegistry, type PassphraseResponse, type PassphraseStateAware, type PrepareSolanaOffchainMessageV1Params, type PreparedSolanaOffchainMessageV1, QrDisplayData, type Response, type RunAllNetworkGetAddressOptions, SDK, SaveDeviceBindingDeclineReason, type SaveDeviceBindingRequest, type SdkEvent, type SearchDevicesOptions, type SearchTargetReusePolicy, type SolAddress, type SolGetAddressParams, type SolOffchainMessageV1Params, type SolSignMsgParams, type SolSignTxParams, type SolSignature, type SolSignedTx, type Success, type TransportType, type TrezorBrightnessParams, type TrezorChangePinParams, type TrezorDeviceSettingsParams, type TrezorDisplayRotation, type TrezorSafetyCheckLevel, type TronAddress, type TronContract, type TronFreezeBalanceV2Contract, type TronGetAddressParams, type TronResource, type TronSignMsgParams, type TronSignTxParams, type TronSignature, type TronSignedTx, type TronTransferContract, type TronTriggerSmartContract, type TronUnfreezeBalanceV2Contract, type TronVote, type TronVoteWitnessContract, type TronWithdrawExpireUnfreezeContract, TypedEventEmitter, UI_REQUEST, type UiRequestEvent, UiRequestRegistry, UiResponseEvent, type VendorType, type WalletIdentity, type ZcashFullViewingKey, type ZcashFullViewingKeyMode, type ZcashGetFullViewingKeyParams, type ZcashGetShieldedAddressParams, type ZcashShieldedAddress, batchCall, buildUnsupportedMethodResponse, bytesToHex, canReplayHardwareMethodAfterTransportFailure, compareSemver, createBridgedConnector, createCombinedConnector, createHardwareLinkId, createHardwareOperationId, createHardwareSearchTargetId, deriveDeviceFingerprint, deriveWalletId, detectHardwareVendorFromDescriptor, ensure0x, failure, getAllNetworkMethodChain, getHardwareMethodMetadata, hasHardwareRuntimeIdPrefix, hexToBytes, isAllNetworkMethodName, isHardwareOperationId, isKnownNonTargetHardwareVendor, padHex64, parseBip32MasterFingerprint, parseHardwareRuntimeId, prepareSolanaOffchainMessageV1, rehydrateConnectorError, requestBleDeviceSelection, requestSaveDeviceBinding, resolveHardwareOperationTarget, resolveSearchTargetReusePolicy, runAllNetworkGetAddress, serializeConnectorError, stripHex, success };