@onekeyfe/hwk-adapter-core 1.2.3-alpha.1 → 1.2.3-alpha.3

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.
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- import { H as HardwareErrorCode, a as HwkErrorOrigin, b as HwkRecoveryHint } from './errors-ChA_YEZY.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-ChA_YEZY.js';
3
- import { U as UiResponseEvent, a as UI_REQUEST, Q as QrDisplayData, b as UiRequestRegistry } from './ui-events-BXI9BBpx.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-BXI9BBpx.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;
@@ -499,10 +499,6 @@ declare const DEVICE: {
499
499
  readonly DISCONNECT: "device-disconnect";
500
500
  readonly CHANGED: "device-changed";
501
501
  readonly FEATURES: "features";
502
- /** Trezor transport binding, emitted only after matching the expected firmware device_id. */
503
- readonly TREZOR_CONNECTION_VERIFIED: "device-trezor-connection-verified";
504
- /** Ledger BLE address repair, emitted only after matching the stored chain fingerprint. */
505
- readonly LEDGER_CONNECTION_VERIFIED: "device-ledger-connection-verified";
506
502
  /**
507
503
  * Trezor-only. Emitted after a successful THP handshake that minted or
508
504
  * refreshed pairing credentials. The host should persist `credentials`
@@ -865,54 +861,53 @@ declare const SDK: {
865
861
  readonly DEVICE_UNRESPONSIVE: "device-unresponsive";
866
862
  readonly DEVICE_RECOVERED: "device-recovered";
867
863
  readonly DEVICE_INTERACTION: "device-interaction";
868
- readonly INTERACTION_ENDED: "interaction-ended";
864
+ readonly OPERATION_ENDED: "operation-ended";
869
865
  };
870
866
 
871
- declare const INTERACTION_DEFAULT_TTL_MS = 600000;
872
- type InteractionEndReason = 'explicit' | 'disconnect' | 'timeout' | 'runtime-reset';
873
- type HardwareInteraction = {
874
- interactionId: string;
875
- searchTargetId: string;
867
+ declare const OPERATION_DEFAULT_TTL_MS = 600000;
868
+ type OperationEndReason = 'explicit' | 'disconnect' | 'timeout' | 'runtime-reset';
869
+ type HardwareOperation = {
870
+ operationId: string;
876
871
  connectId: string;
877
872
  device: DeviceInfo;
878
873
  connectionKeys: string[];
879
874
  createdAt: number;
880
875
  lastActiveAt: number;
881
876
  };
882
- type InteractionRegistryOptions = {
877
+ type OperationRegistryOptions = {
883
878
  vendor: VendorType;
884
879
  ttlMs?: number;
885
- onEnded?: (interaction: HardwareInteraction, reason: InteractionEndReason) => void;
880
+ onEnded?: (operation: HardwareOperation, reason: OperationEndReason) => void;
886
881
  };
887
- /** Runtime-only association between a public interaction id and one live target. */
888
- declare class InteractionRegistry {
882
+ /** Runtime-only association between a public operation id and one live target. */
883
+ declare class OperationRegistry {
889
884
  private readonly _vendor;
890
885
  private readonly _ttlMs;
891
886
  private readonly _onEnded?;
892
887
  private readonly _active;
893
888
  private readonly _ended;
894
- constructor(options: InteractionRegistryOptions);
889
+ constructor(options: OperationRegistryOptions);
895
890
  create(params: {
896
891
  searchTargetId: string;
897
892
  connectId: string;
898
893
  device: DeviceInfo;
899
894
  connectionKeys?: string[];
900
- }): HardwareInteraction;
901
- resolve(interactionId: string): HardwareInteraction;
902
- /** Keep an interaction alive while one device job is actively using it. */
903
- retain(interactionId: string): () => void;
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;
904
899
  /** Return active or tombstoned binding data without refreshing its TTL. */
905
- find(interactionId: string): HardwareInteraction | undefined;
906
- findActiveByConnectionKey(connectionKey: string): HardwareInteraction | undefined;
900
+ find(operationId: string): HardwareOperation | undefined;
901
+ findActiveByConnectionKey(connectionKey: string): HardwareOperation | undefined;
907
902
  /** Replace the live transport binding after the same target was reconnected. */
908
- rebind(interactionId: string, params: {
903
+ rebind(operationId: string, params: {
909
904
  connectId: string;
910
905
  device: DeviceInfo;
911
906
  connectionKeys?: string[];
912
- }): HardwareInteraction;
913
- end(interactionId: string, reason: InteractionEndReason): HardwareInteraction | undefined;
914
- endByConnectionKey(connectionKey: string, reason: InteractionEndReason, exceptInteractionId?: string): void;
915
- endAll(reason: InteractionEndReason, exceptInteractionId?: string): void;
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;
916
911
  private _createTimer;
917
912
  private _rememberEnded;
918
913
  }
@@ -1143,7 +1138,7 @@ type DeviceSelectionContext = {
1143
1138
  } | {
1144
1139
  kind: 'bind-connection';
1145
1140
  transport: 'ble';
1146
- reason: 'missing-binding' | 'known-connection-unavailable';
1141
+ reason: 'missing-binding' | 'known-connection-unavailable' | 'manual-rebind';
1147
1142
  };
1148
1143
  interface DeviceSelectionRequest {
1149
1144
  devices: DeviceInfo[];
@@ -1169,6 +1164,7 @@ interface SaveDeviceBindingRequest {
1169
1164
  }>;
1170
1165
  extra?: HardwareCallExtra;
1171
1166
  }
1167
+ type BindBleDeviceParams = Pick<SaveDeviceBindingRequest, 'identity' | 'extra'>;
1172
1168
  interface DeviceBindingStatus {
1173
1169
  selectionRequestId: string;
1174
1170
  status: 'verifying' | 'saved' | 'failed' | 'cancelled';
@@ -1181,7 +1177,7 @@ interface ICommonCallParams extends IHardwareConnectionContext {
1181
1177
  */
1182
1178
  autoInstallApp?: boolean;
1183
1179
  /** Runtime-only id returned by connectDevice(). When present, discovery and fallback are disabled. */
1184
- interactionId?: string;
1180
+ operationId?: string;
1185
1181
  }
1186
1182
  type NullableCallArg<T> = T | null | undefined;
1187
1183
  interface IPassphraseCallParams {
@@ -1196,7 +1192,7 @@ type IHardwareCallParams<T> = T & IHardwareCommonCallParams;
1196
1192
  * reconnect. It must never be forwarded to vendor firmware.
1197
1193
  */
1198
1194
  interface IDeviceManagerOperationContext extends IHardwareConnectionContext {
1199
- interactionId?: string;
1195
+ operationId?: string;
1200
1196
  expectedDeviceIdentity?: WalletIdentity;
1201
1197
  }
1202
1198
  interface AllNetworkAddressParams {
@@ -1242,25 +1238,6 @@ type DeviceEvent = {
1242
1238
  } | {
1243
1239
  type: typeof DEVICE.CHANGED;
1244
1240
  payload: DeviceInfo;
1245
- } | {
1246
- type: typeof DEVICE.LEDGER_CONNECTION_VERIFIED;
1247
- payload: {
1248
- previousConnectId: string;
1249
- connectId: string;
1250
- chain: ChainForFingerprint;
1251
- fingerprint: string;
1252
- extra?: HardwareCallExtra;
1253
- selectionRequestId?: string;
1254
- };
1255
- } | {
1256
- type: typeof DEVICE.TREZOR_CONNECTION_VERIFIED;
1257
- payload: {
1258
- deviceId: string;
1259
- connectId: string;
1260
- connectionType: TransportType;
1261
- extra?: HardwareCallExtra;
1262
- selectionRequestId?: string;
1263
- };
1264
1241
  } | {
1265
1242
  type: typeof DEVICE.FEATURES;
1266
1243
  device: DeviceInfo & {
@@ -1389,10 +1366,10 @@ type SdkEvent = {
1389
1366
  connectId: string;
1390
1367
  };
1391
1368
  } | {
1392
- type: typeof SDK.INTERACTION_ENDED;
1369
+ type: typeof SDK.OPERATION_ENDED;
1393
1370
  payload: {
1394
- interactionId: string;
1395
- reason: InteractionEndReason;
1371
+ operationId: string;
1372
+ reason: OperationEndReason;
1396
1373
  };
1397
1374
  };
1398
1375
  type HardwareEvent = DeviceEvent | UiRequestEvent | SdkEvent | HardwareUiEvent;
@@ -1427,27 +1404,6 @@ interface HardwareEventMap {
1427
1404
  type: typeof DEVICE.CHANGED;
1428
1405
  payload: DeviceInfo;
1429
1406
  };
1430
- [DEVICE.LEDGER_CONNECTION_VERIFIED]: {
1431
- type: typeof DEVICE.LEDGER_CONNECTION_VERIFIED;
1432
- payload: {
1433
- previousConnectId: string;
1434
- connectId: string;
1435
- chain: ChainForFingerprint;
1436
- fingerprint: string;
1437
- extra?: HardwareCallExtra;
1438
- selectionRequestId?: string;
1439
- };
1440
- };
1441
- [DEVICE.TREZOR_CONNECTION_VERIFIED]: {
1442
- type: typeof DEVICE.TREZOR_CONNECTION_VERIFIED;
1443
- payload: {
1444
- deviceId: string;
1445
- connectId: string;
1446
- connectionType: TransportType;
1447
- extra?: HardwareCallExtra;
1448
- selectionRequestId?: string;
1449
- };
1450
- };
1451
1407
  [DEVICE.FEATURES]: {
1452
1408
  type: typeof DEVICE.FEATURES;
1453
1409
  device: DeviceInfo & {
@@ -1583,11 +1539,11 @@ interface HardwareEventMap {
1583
1539
  connectId: string;
1584
1540
  };
1585
1541
  };
1586
- [SDK.INTERACTION_ENDED]: {
1587
- type: typeof SDK.INTERACTION_ENDED;
1542
+ [SDK.OPERATION_ENDED]: {
1543
+ type: typeof SDK.OPERATION_ENDED;
1588
1544
  payload: {
1589
- interactionId: string;
1590
- reason: InteractionEndReason;
1545
+ operationId: string;
1546
+ reason: OperationEndReason;
1591
1547
  };
1592
1548
  };
1593
1549
  }
@@ -1640,14 +1596,15 @@ interface IHardwareWallet<TConfig = unknown> extends IEvmMethods, IBtcMethods, I
1640
1596
  searchDeviceTargets(options?: SearchDevicesOptions): Promise<DeviceSearchTarget[]>;
1641
1597
  /** @deprecated Use searchDeviceTargets(). */
1642
1598
  listConnectionTargets(options?: SearchDevicesOptions): Promise<ConnectionTarget[]>;
1643
- /** Connect or logically bind a selected search result and return a runtime-only interaction id. */
1599
+ /** Connect or logically bind a selected search result and return a runtime-only operation id. */
1644
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>>;
1645
1603
  /** Resolve operation-first routing/selection and pin it. The caller must verify wallet identity before business calls. */
1646
- acquireInteraction?(connectId: string, context: IHardwareConnectionContext): Promise<Response<string>>;
1647
- /** Release an interaction owned by the caller. Disconnect events end matching interactions automatically. */
1648
- releaseInteraction(interactionId: string): Promise<void>;
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>;
1649
1607
  getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
1650
- getSupportedChains(): ChainCapability[];
1651
1608
  /** Abort the in-flight call. Omit connectId to cancel whatever is active. */
1652
1609
  cancel(connectId?: string): void;
1653
1610
  allNetworkGetAddress(connectId: string, deviceId: string, params: AllNetworkGetAddressParams): Promise<Response<AllNetworkAddressResponse[]>>;
@@ -1815,6 +1772,14 @@ interface EvmSignTypedDataFull extends PassphraseStateAware {
1815
1772
  primaryType: string;
1816
1773
  message: Record<string, unknown>;
1817
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;
1818
1783
  metamaskV4Compat?: boolean;
1819
1784
  showMessageHash?: boolean;
1820
1785
  /**
@@ -1925,14 +1890,18 @@ interface DeviceDisconnectEvent {
1925
1890
  type DeviceChangeEvent = DeviceConnectEvent | DeviceDisconnectEvent;
1926
1891
 
1927
1892
  /**
1928
- * Pure FIFO job queue. Every enqueue chains onto the tail; jobs run one at
1929
- * a time across all devices. The queue is intentionally passive — it does
1930
- * NOT decide whether to interrupt or ask the user. Those are application-
1931
- * layer concerns owned by the caller (e.g. a UI button handler that wants
1932
- * to ask "device is busy, interrupt current?" before submitting). The
1933
- * queue exposes inspection (`getActiveJob`) and explicit cancellation
1934
- * (`cancelActive` / `cancelAll`) so callers can implement those policies
1935
- * 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.
1936
1905
  */
1937
1906
  interface JobOptions {
1938
1907
  label?: string;
@@ -1956,64 +1925,52 @@ declare class DeviceJobQueue {
1956
1925
  * `deviceId` is a label only — used by inspection / cancellation routing.
1957
1926
  */
1958
1927
  enqueue<T>(deviceId: string, job: (signal: AbortSignal) => Promise<T>, options?: JobOptions): Promise<T>;
1959
- /** Cancel the active job. If `deviceId` is given, only cancels when it matches. */
1960
- cancelActive(deviceId?: string): boolean;
1961
- /** Force cancel the active job. `reason` becomes signal.reason. */
1962
- forceCancelActive(deviceId?: string, reason?: Error): boolean;
1963
- /** Cancel the active job (alias for callers that previously needed multi-device cancel). */
1964
- cancelAllActive(reason?: Error): void;
1928
+ /** Cancel the running job. `reason` becomes signal.reason. */
1929
+ cancelActive(deviceId?: string, reason?: Error): boolean;
1965
1930
  /** Cancel the active job and invalidate queued jobs that have not started. */
1966
1931
  cancelActiveAndPending(deviceId?: string, reason?: Error): boolean;
1967
1932
  /** Get info about the currently active job, or null if idle. */
1968
1933
  getActiveJob(deviceId?: string): ActiveJobInfo | null;
1969
- /** True if any job is currently running. */
1970
- isBusy(): boolean;
1971
1934
  clear(reason?: Error): void;
1972
1935
  }
1973
1936
 
1974
- declare const HARDWARE_RUNTIME_ID_PREFIX = "hwk:runtime:v1";
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';
1975
1950
  type HardwareRuntimeId = {
1976
- kind: 'interaction';
1977
- vendor: VendorType;
1978
- nonce: string;
1979
- } | {
1980
- kind: 'search-target';
1981
- vendor: VendorType;
1982
- connectionType: ConnectionType;
1983
- nonce: string;
1984
- } | {
1985
- kind: 'connector-session';
1951
+ kind: HardwareRuntimeIdKind;
1986
1952
  vendor: VendorType;
1987
- connectionType: ConnectionType;
1988
- nonce: string;
1989
1953
  };
1990
1954
  /** Runtime ids are opaque and must never be persisted as device identity. */
1991
- declare function createHardwareInteractionId(vendor: VendorType): string;
1955
+ declare function createHardwareOperationId(vendor: VendorType): string;
1992
1956
  /** Search targets are valid only for the adapter's current discovery snapshot. */
1993
- declare function createHardwareSearchTargetId(params: {
1994
- vendor: VendorType;
1995
- connectionType: ConnectionType;
1996
- }): string;
1997
- declare function createHardwareConnectorSessionId(params: {
1998
- vendor: VendorType;
1999
- connectionType: ConnectionType;
2000
- }): string;
1957
+ declare function createHardwareSearchTargetId(vendor: VendorType): string;
1958
+ declare function createHardwareLinkId(vendor: VendorType): string;
2001
1959
  declare function hasHardwareRuntimeIdPrefix(value: unknown): value is string;
2002
1960
  declare function parseHardwareRuntimeId(value: unknown): HardwareRuntimeId | undefined;
2003
- declare function isHardwareInteractionId(value: unknown): value is string;
2004
- declare function isHardwareSearchTargetId(value: unknown): value is string;
1961
+ declare function isHardwareOperationId(value: unknown): value is string;
2005
1962
 
2006
1963
  interface HardwareOperationTarget {
2007
1964
  /** Effective target accepted by existing adapter/connector call paths. */
2008
1965
  targetId: string | undefined;
2009
- /** Present when this operation is pinned to a live interaction. */
2010
- interactionId: string | undefined;
1966
+ /** Present when this operation is pinned to a live operation. */
1967
+ operationId: string | undefined;
2011
1968
  }
2012
1969
  /**
2013
- * Normalizes the transitional positional interaction id and the canonical
1970
+ * Normalizes the transitional positional operation id and the canonical
2014
1971
  * common-params field. All vendors must reject conflicting bindings.
2015
1972
  */
2016
- declare function resolveHardwareOperationTarget(positionalTargetId: string | null | undefined, commonInteractionId: string | null | undefined, expectedVendor?: VendorType): Response<HardwareOperationTarget>;
1973
+ declare function resolveHardwareOperationTarget(positionalTargetId: string | null | undefined, commonOperationId: string | null | undefined, expectedVendor?: VendorType): Response<HardwareOperationTarget>;
2017
1974
 
2018
1975
  /**
2019
1976
  * Minimal typed event emitter using Map<string, Set<listener>>.
@@ -2048,16 +2005,43 @@ interface ElectronBleDeviceInfo {
2048
2005
  rssi?: number;
2049
2006
  advertisedServiceUuids?: string[];
2050
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
+ }
2051
2020
  interface ElectronBleScanOptions {
2052
- vendor?: 'trezor' | 'ledger';
2021
+ /** Opaque partition key: results and connected devices never mix across it. */
2022
+ vendor?: string;
2023
+ match?: ElectronBleMatch;
2024
+ /** @deprecated Superseded by `match.serviceUuids`. */
2053
2025
  serviceUuids?: string[];
2054
2026
  durationMs?: number;
2055
2027
  }
2028
+ /** GATT profile plus the write framing this vendor's firmware expects. */
2056
2029
  interface ElectronBleConnectOptions {
2057
- vendor: 'ledger';
2030
+ vendor: string;
2058
2031
  serviceUuid: string;
2059
2032
  writeUuid: string;
2060
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
+ };
2061
2045
  }
2062
2046
  /** Native code handles GATT only; framing, identity checks and wallet operations stay in the SDK. */
2063
2047
  interface ElectronBleApi {
@@ -2081,16 +2065,31 @@ interface ElectronBleApi {
2081
2065
  onDeviceDisconnected(handler: (id: string) => void): () => void;
2082
2066
  }
2083
2067
 
2084
- /** Legacy hosts keep their notification path until they subscribe to the acknowledged contract. */
2085
- declare function requestSaveDeviceBinding(emitter: TypedEventEmitter<HardwareEventMap>, registry: UiRequestRegistry, binding: Omit<SaveDeviceBindingRequest, 'requestId'>, signal?: AbortSignal): Promise<boolean>;
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>;
2086
2083
 
2087
2084
  /** Discovery and selection share one owner; never connect until the last scan has drained. */
2088
- declare function requestBleDeviceSelection({ emitter, registry, request, scan, signal, pollIntervalMs, }: {
2085
+ declare function requestBleDeviceSelection({ emitter, registry, request, scan, signal, allowUsbFallback, pollIntervalMs, }: {
2089
2086
  emitter: TypedEventEmitter<HardwareEventMap>;
2090
2087
  registry: UiRequestRegistry;
2091
2088
  request: Omit<DeviceSelectionRequest, 'requestId' | 'scanning'>;
2092
2089
  scan: () => Promise<DeviceInfo[]>;
2093
2090
  signal: AbortSignal;
2091
+ /** The adapter must verify a returned USB candidate before dispatching any business call. */
2092
+ allowUsbFallback?: boolean;
2094
2093
  pollIntervalMs?: number;
2095
2094
  }): Promise<{
2096
2095
  device: DeviceInfo;
@@ -2195,4 +2194,4 @@ declare function buildUnsupportedMethodResponse(item: AllNetworkAddressParams):
2195
2194
 
2196
2195
  declare const DEVICE_CONNECT_RETRY_DELAY_MS = 1000;
2197
2196
 
2198
- 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 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 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 HardwareInteraction, type HardwareMethodMetadata, type HardwareMethodName, type HardwareOperationTarget, type HardwareRuntimeId, 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, INTERACTION_DEFAULT_TTL_MS, type IPassphraseCallParams, type ISolMethods, type ITronMethods, type IWalletStateMethods, type InteractionEndReason, InteractionRegistry, type JobOptions, type KnownDeviceConnection, type NullableCallArg, type PassphraseResponse, type PassphraseStateAware, type PrepareSolanaOffchainMessageV1Params, type PreparedSolanaOffchainMessageV1, QrDisplayData, type Response, type RunAllNetworkGetAddressOptions, SDK, 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, createHardwareConnectorSessionId, createHardwareInteractionId, createHardwareSearchTargetId, deriveDeviceFingerprint, deriveWalletId, detectHardwareVendorFromDescriptor, ensure0x, failure, getAllNetworkMethodChain, getHardwareMethodMetadata, hasHardwareRuntimeIdPrefix, hexToBytes, isAllNetworkMethodName, isHardwareInteractionId, isHardwareSearchTargetId, isKnownNonTargetHardwareVendor, padHex64, parseBip32MasterFingerprint, parseHardwareRuntimeId, prepareSolanaOffchainMessageV1, rehydrateConnectorError, requestBleDeviceSelection, requestSaveDeviceBinding, resolveHardwareOperationTarget, resolveSearchTargetReusePolicy, 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 };