@onekeyfe/hwk-adapter-core 1.2.3-alpha.7 → 1.2.3-alpha.8

package/dist/errors-Cm8XpjmX.d.mts

@@ -0,0 +1,321 @@
+/**
+ * HWK HardwareErrorCode — independent namespace from the legacy
+ * `@onekeyfe/shared` HardwareErrorCode (which occupies 0-902).
+ *
+ * All HWK codes are 5-digit (>= 10000) so the two tables never collide
+ * even if either side grows. Each sub-category gets a 100-slot block.
+ *
+ *   10000-10099  Generic / cross-cutting primitives
+ *   10100-10199  Device state
+ *   10200-10299  Firmware
+ *   10300-10399  Transport + OS-level permission
+ *   10400-10499  PIN / Passphrase
+ *   10500-10599  App lifecycle (wrong app, not open, too old)
+ *   10600-10699  Payload / framing limits (adapter-level)
+ *   10700-10999  RESERVED — future adapter-level categories
+ *
+ *   11000-11099  EVM APDU (reactive mapping)
+ *   11100-11199  Solana APDU
+ *   11200-11299  Tron APDU
+ *   11300-11399  BTC APDU
+ *   11400-11999  RESERVED — future chain APDU blocks (100 per chain)
+ *
+ *   12000-99999  RESERVED — future major categories
+ */
+declare enum HardwareErrorCode {
+    UnknownError = 10000,
+    UserRejected = 10001,
+    InvalidParams = 10002,
+    OperationTimeout = 10003,
+    MethodNotSupported = 10004,
+    /** User dismissed in-app cancel UI. Distinct from UserRejected (on-device). */
+    UserAborted = 10005,
+    DeviceNotFound = 10100,
+    DeviceDisconnected = 10101,
+    DeviceBusy = 10102,
+    DeviceLocked = 10103,
+    DeviceNotInitialized = 10104,
+    DeviceInBootloader = 10105,
+    DeviceMismatch = 10106,
+    /** Chain app wedged (e.g. Ledger BTC 0x6901). User must exit app on device. */
+    DeviceAppStuck = 10107,
+    /** Vendor (Ledger / Trezor) doesn't support the chain at all. */
+    ChainNotSupported = 10108,
+    /** Current operation supports only one connected device. */
+    DeviceOneDeviceOnly = 10109,
+    /**
+     * The device rejected the requested derivation path (Trezor Failure_DataError
+     * "Forbidden key path") — the path is non-standard or its index is outside the
+     * range the device's safety checks allow. Distinct from ChainNotSupported
+     * (whole chain) and MethodNotSupported (the operation/method itself).
+     */
+    DevicePathForbidden = 10110,
+    /** Busy with our own in-flight request (queue guard / firmware Failure_Busy), not another app — wait and retry, don't close other apps. */
+    DeviceBusyInternal = 10111,
+    /** The supplied runtime-only operation id is unknown to this adapter instance. */
+    OperationNotFound = 10112,
+    /** The supplied operation ended and can never be resumed. */
+    OperationEnded = 10113,
+    /**
+     * Discovery found devices but none of them is the wallet being looked for.
+     * Milder than DeviceMismatch: nothing about the known wallet has changed, the
+     * user simply has the wrong unit connected. DeviceMismatch stays reserved for
+     * reaching the expected device and finding a different identity on it, which
+     * can mean it was wiped, reseeded, or swapped.
+     */
+    DeviceSearchMismatch = 10114,
+    FirmwareTooOld = 10200,
+    FirmwareUpdateRequired = 10201,
+    TransportError = 10300,
+    BridgeNotFound = 10301,
+    TransportNotAvailable = 10302,
+    /**
+     * OS-level permission (Bluetooth / USB / etc.) — denied, blocked,
+     * unavailable, or dismissed. Consumers surface a single "please grant
+     * permission" toast and let the user retry manually.
+     */
+    DevicePermissionDenied = 10303,
+    /**
+     * BLE SMP pairing did not complete within the GATT bonding window.
+     * GATT connected but the device didn't acknowledge SMP — typically
+     * because the user didn't confirm the passkey on the device, or the
+     * device went out of range mid-pairing. Distinct from OperationTimeout
+     * (generic) and from DeviceLocked (Secure Element actually locked).
+     */
+    BlePairingTimeout = 10304,
+    /** Remote network failure reaching a vendor's servers (HTTP/WS). Distinct from TransportError (local USB/BLE link). */
+    NetworkError = 10305,
+    /**
+     * Host-managed pairing handshake failed (Trezor THP). The device rejected the
+     * pairing exchange — e.g. CodeEntry: the user mistyped the code shown on the
+     * device, so the CPace tag didn't match ("Unexpected Code Entry Tag").
+     * Recoverable: the user re-pairs and re-enters the code. Distinct from
+     * BlePairingTimeout (BLE SMP bonding window) and UserRejected (on-device
+     * reject button).
+     */
+    ThpPairingFailed = 10306,
+    /**
+     * The OS-level BLE bond is stale/invalid, so the device rejected link
+     * encryption: Android GATT_INSUF_AUTHENTICATION (status 5) or iOS "Peer
+     * removed pairing information". Happens after the device is wiped/re-flashed
+     * or unpaired elsewhere while the host still holds an old bond. The SDK cannot
+     * remove an OS bond — the user must forget the device in system Bluetooth
+     * settings and re-pair. Distinct from BlePairingTimeout (SMP window) and
+     * ThpPairingFailed (THP code mismatch).
+     */
+    BleBondInvalid = 10307,
+    /**
+     * A stored THP pairing credential was rejected by the device during the
+     * handshake (device returned completion `state=0`), so the autoconnect session
+     * could not be established. The SDK discards the stale credential; recovery is
+     * a fresh pairing. Distinct from ThpPairingFailed (user mistyped the code
+     * during an *active* pairing) and BleBondInvalid (OS-level BLE bond).
+     */
+    ThpPairingRequired = 10308,
+    /**
+     * Generic BLE connect failure where the OS dropped the specific reason. On
+     * macOS the noble native binding hardcodes "connection failed" (and a connect
+     * timeout) and discards the CoreBluetooth NSError, so the SDK cannot tell a
+     * stale bond from an out-of-range / unresponsive device. Surfaced as a
+     * generic "couldn't connect — check the device, re-pair if paired before".
+     * Distinct from BleBondInvalid (a *known* stale-bond signal, iOS/Android only)
+     * and BlePairingTimeout (the SMP bonding window).
+     */
+    BleConnectFailed = 10309,
+    /**
+     * The user cancelled BLE pairing from the app while the connect was still
+     * waiting on the OS pairing window. Not a failure to report — the flow ends
+     * because they asked it to. Distinct from UserAborted (generic in-app cancel)
+     * so the pairing UI can close quietly instead of surfacing a connect error,
+     * and from BlePairingTimeout (the SMP window elapsed on its own).
+     */
+    BlePairingCancelled = 10310,
+    /**
+     * The vendor's remote secure channel broke while it was relaying APDUs to the
+     * device (Ledger: the manager-api script-runner WebSocket behind app install,
+     * uninstall and genuine check). The device link itself is still usable, so
+     * this is not a disconnect: retry the same call. Distinct from NetworkError,
+     * which is a plain HTTP/WS request that never carried device traffic.
+     */
+    LedgerSecureChannelError = 10311,
+    /**
+     * The vendor's metadata service answered with a payload the SDK cannot use
+     * (Ledger: firmware metadata or the application catalog). Not a connectivity
+     * failure — the request succeeded and the response was unusable — so callers
+     * must not treat it as a dropped link.
+     */
+    LedgerFirmwareMetadataError = 10312,
+    PinInvalid = 10400,
+    PinCancelled = 10401,
+    PassphraseRejected = 10402,
+    /**
+     * The passphrase entered produced a different wallet (`passphraseState`) than
+     * the one the caller asked to operate on. Trezor-only: the host pins a wallet
+     * by its derived state and the SDK refuses to sign with a mismatched
+     * passphrase session. Surfaced by TrezorAdapter.getPassphraseState.
+     */
+    PassphraseStateMismatch = 10403,
+    /**
+     * The two new-PIN entries did not match during set/change PIN. Only host-input
+     * models (Trezor Model One matrix) surface this; on-device-input models show
+     * the mismatch on the device and never return it.
+     */
+    PinMismatch = 10404,
+    /** Standard wallet is unavailable while Trezor enforces on-device passphrase entry. */
+    PassphraseAlwaysOnDevice = 10405,
+    /** Chain app NOT INSTALLED on device. User must install via Ledger Live. */
+    AppNotInstalled = 10500,
+    WrongApp = 10501,
+    /** 0x911c Command code not supported — app predates current SDK. */
+    AppTooOld = 10502,
+    /** Not enough free storage for install/update; user must uninstall apps first. */
+    DeviceOutOfMemory = 10503,
+    /** Install refused because the app is already on the device. Benign for callers that only need it present. */
+    AppAlreadyInstalled = 10504,
+    /**
+     * The call payload exceeds a transport's fixed framing capacity (e.g.
+     * Keystone USB's ~12.5KB per-request cap — 200 frames of 64 bytes). Distinct
+     * from a generic TransportError: the request never reached the device, and
+     * retrying with the same payload over the same transport will fail the same
+     * way. Callers should route the call over a different channel (e.g. Keystone
+     * QR) or reduce the payload (e.g. a smaller PSBT) instead of retrying as-is.
+     */
+    PayloadTooLarge = 10600,
+    /** 0x6a80 Invalid data — observed on blindSignTransactionFallback when the
+     *  user has not enabled Blind signing on the device. */
+    EvmBlindSigningRequired = 11000,
+    /** 0x6984 Plugin not installed */
+    EvmClearSignPluginMissing = 11001,
+    /** 0x6a84 Insufficient memory (typical on Nano S with large calldata) */
+    EvmDataTooLarge = 11002,
+    /** 0x6501 TransactionType not supported (app too old for EIP-1559 / blob / 7702) */
+    EvmTxTypeNotSupported = 11003,
+    /** 0x6808 Blind signing disabled for this instruction. */
+    SolanaBlindSigningRequired = 11100,
+    /** 0x6a8d Custom Contracts setting disabled (blocks TRC-20 etc.). */
+    TronCustomContractRequired = 11200,
+    /** 0x6a8b Transactions Data setting disabled. */
+    TronDataSigningRequired = 11201,
+    /** 0x6a8c Sign by Hash setting disabled (hash-signing fallback). */
+    TronSignByHashRequired = 11202,
+    /** 0xb008 Wallet policy HMAC mismatch or not registered. */
+    BtcWalletPolicyHmacMismatch = 11300,
+    /** 0xb007 Aborted due to unexpected state (malformed PSBT / missing UTXO). */
+    BtcUnexpectedState = 11301
+}
+/**
+ * Device-level failures the SDK cannot self-recover from — affect the entire
+ * batch (vs per-chain failures like AppNotInstalled / WrongApp which soft-
+ * skip in onboarding). Combined with `accounts.length === 0`, signals
+ * genuine orphan. Also reused as the batch-abort whitelist for HWK.
+ * Single source of truth.
+ *
+ * UserRejected (device-side reject) is included: pressing reject is an
+ * explicit "I don't consent" — continuing the batch to ask again on the
+ * next chain is harassment, not helpful.
+ */
+declare const ORPHAN_ELIGIBLE_ERROR_CODES: number[];
+/**
+ * Where a failure came from. The distinction the numeric code ranges cannot
+ * make reliably (UserRejected=10001 sits in the general range but is the
+ * device speaking; DevicePermissionDenied=10303 sits in the transport range
+ * but is the browser speaking), and the one recovery logic actually needs:
+ *
+ * - `device`    the firmware ANSWERED: rejection, locked screen, wrong
+ *               wallet, bad PIN. It is a result, not a malfunction — surface
+ *               it to the user verbatim; never auto-reconnect, never switch
+ *               channels, never drop a healthy session over it.
+ * - `transport` the pipe failed: cable pulled, bus reset, bridge gone.
+ *               Reconnecting or falling back to another channel is fair game.
+ * - `host`      the host environment refused: browser permission, picker
+ *               dismissed, bad parameters. Fix the environment, not the link.
+ *
+ * Optional on purpose: a mapper that cannot tell MUST leave it unset rather
+ * than guess — consumers fall back to their existing code-based tables, so an
+ * unset origin degrades to today's behavior instead of mislabeling.
+ */
+type HwkErrorOrigin = 'device' | 'transport' | 'host';
+/**
+ * Smallest runtime resource a consumer must replace before retrying a failed
+ * operation. This is connection-lifecycle metadata, not UI navigation and not
+ * permission to replay a signing command automatically.
+ *
+ * - `call`: nothing needs replacing; re-issuing the same call is eligible,
+ *   usually after the user fixes device state.
+ * - `operation`: the operation binding is no longer usable; the selected target
+ *   may be used to establish a new one when its identity is persistent.
+ * - `search-target`: the selected discovery result is stale or untrusted;
+ *   rediscover on the same transport and let the user select again.
+ * - `transport`: the selected transport is unavailable or unsuitable; repair
+ *   it or choose another transport.
+ * - `not-recoverable`: retrying the same operation/context cannot succeed.
+ * - `unknown`: the SDK cannot make a safe recovery claim.
+ */
+type HwkRecoveryScope = 'call' | 'operation' | 'search-target' | 'transport' | 'not-recoverable' | 'unknown';
+interface HwkRecoveryHint {
+    scope: HwkRecoveryScope;
+}
+declare function isHwkRecoveryHint(value: unknown): value is HwkRecoveryHint;
+/**
+ * Vendor-neutral fallback used when an adapter has no more precise runtime
+ * knowledge. Adapters may stamp a narrower hint when transport/session state
+ * makes the correct scope unambiguous.
+ */
+declare function defaultRecoveryForCode(code: HardwareErrorCode): HwkRecoveryHint;
+/**
+ * The authoritative code→origin table. Most codes imply their origin by
+ * definition (UserRejected IS the device speaking; BridgeNotFound IS the
+ * pipe). Vendors use this as the default and override only where their
+ * mapping context knows better. Codes whose origin genuinely depends on
+ * context (UnknownError, OperationTimeout — the device may be waiting for a
+ * human, or the pipe may be dead — and DeviceBusy) return undefined: an
+ * honest "can't tell" beats a plausible mislabel, because consumers fall
+ * back to their existing behavior instead of taking the wrong recovery.
+ */
+declare function defaultOriginForCode(code: HardwareErrorCode): HwkErrorOrigin | undefined;
+interface IHwkErrorPayload {
+    code: HardwareErrorCode;
+    message: string;
+    origin?: HwkErrorOrigin;
+    recovery?: HwkRecoveryHint;
+    appName?: string;
+    _tag?: string;
+    params?: Record<string, unknown>;
+}
+interface IOperationMayHaveCompletedParams extends Record<string, unknown> {
+    operationMayHaveCompleted: true;
+    method: string;
+}
+/**
+ * Marks an unsafe hardware request whose response was lost after dispatch.
+ * Callers must not interpret the resulting transport error as proof that the
+ * device rejected or did not execute the operation.
+ */
+declare function operationMayHaveCompletedParams(method: string, params?: Record<string, unknown>): IOperationMayHaveCompletedParams;
+type HwkError = Error & {
+    code: HardwareErrorCode;
+    /** See {@link HwkErrorOrigin}. Survives serializeConnectorError/rehydrate
+     *  automatically (own fields outside the top-level whitelist travel via
+     *  `params` and are lifted back). */
+    origin?: HwkErrorOrigin;
+    recovery?: HwkRecoveryHint;
+    appName?: string;
+    _tag?: string;
+    params?: Record<string, unknown>;
+};
+/**
+ * Canonical throwable for HWK adapters. Plain Error + canonical extra fields,
+ * shape-compatible with `rehydrateConnectorError` so locally-thrown and
+ * cross-boundary errors are indistinguishable to downstream classifiers
+ * (`err.code` / `err._tag` / `err.appName`). Do NOT mutate caught errors
+ * with `Object.assign` — construct a fresh one via this factory.
+ */
+declare function createHwkError(payload: IHwkErrorPayload): HwkError;
+
+/**
+ * Enrich a hardware error message with actionable recovery hints.
+ * Shared across adapters (Ledger, Trezor, etc.).
+ */
+declare function enrichErrorMessage(code: HardwareErrorCode, originalMessage: string): string;
+
+export { HardwareErrorCode as H, type IHwkErrorPayload as I, ORPHAN_ELIGIBLE_ERROR_CODES as O, type HwkErrorOrigin as a, type HwkRecoveryHint as b, type HwkError as c, type HwkRecoveryScope as d, type IOperationMayHaveCompletedParams as e, createHwkError as f, defaultOriginForCode as g, defaultRecoveryForCode as h, enrichErrorMessage as i, isHwkRecoveryHint as j, operationMayHaveCompletedParams as o };

package/dist/errors-Cm8XpjmX.d.ts

@@ -0,0 +1,321 @@
+/**
+ * HWK HardwareErrorCode — independent namespace from the legacy
+ * `@onekeyfe/shared` HardwareErrorCode (which occupies 0-902).
+ *
+ * All HWK codes are 5-digit (>= 10000) so the two tables never collide
+ * even if either side grows. Each sub-category gets a 100-slot block.
+ *
+ *   10000-10099  Generic / cross-cutting primitives
+ *   10100-10199  Device state
+ *   10200-10299  Firmware
+ *   10300-10399  Transport + OS-level permission
+ *   10400-10499  PIN / Passphrase
+ *   10500-10599  App lifecycle (wrong app, not open, too old)
+ *   10600-10699  Payload / framing limits (adapter-level)
+ *   10700-10999  RESERVED — future adapter-level categories
+ *
+ *   11000-11099  EVM APDU (reactive mapping)
+ *   11100-11199  Solana APDU
+ *   11200-11299  Tron APDU
+ *   11300-11399  BTC APDU
+ *   11400-11999  RESERVED — future chain APDU blocks (100 per chain)
+ *
+ *   12000-99999  RESERVED — future major categories
+ */
+declare enum HardwareErrorCode {
+    UnknownError = 10000,
+    UserRejected = 10001,
+    InvalidParams = 10002,
+    OperationTimeout = 10003,
+    MethodNotSupported = 10004,
+    /** User dismissed in-app cancel UI. Distinct from UserRejected (on-device). */
+    UserAborted = 10005,
+    DeviceNotFound = 10100,
+    DeviceDisconnected = 10101,
+    DeviceBusy = 10102,
+    DeviceLocked = 10103,
+    DeviceNotInitialized = 10104,
+    DeviceInBootloader = 10105,
+    DeviceMismatch = 10106,
+    /** Chain app wedged (e.g. Ledger BTC 0x6901). User must exit app on device. */
+    DeviceAppStuck = 10107,
+    /** Vendor (Ledger / Trezor) doesn't support the chain at all. */
+    ChainNotSupported = 10108,
+    /** Current operation supports only one connected device. */
+    DeviceOneDeviceOnly = 10109,
+    /**
+     * The device rejected the requested derivation path (Trezor Failure_DataError
+     * "Forbidden key path") — the path is non-standard or its index is outside the
+     * range the device's safety checks allow. Distinct from ChainNotSupported
+     * (whole chain) and MethodNotSupported (the operation/method itself).
+     */
+    DevicePathForbidden = 10110,
+    /** Busy with our own in-flight request (queue guard / firmware Failure_Busy), not another app — wait and retry, don't close other apps. */
+    DeviceBusyInternal = 10111,
+    /** The supplied runtime-only operation id is unknown to this adapter instance. */
+    OperationNotFound = 10112,
+    /** The supplied operation ended and can never be resumed. */
+    OperationEnded = 10113,
+    /**
+     * Discovery found devices but none of them is the wallet being looked for.
+     * Milder than DeviceMismatch: nothing about the known wallet has changed, the
+     * user simply has the wrong unit connected. DeviceMismatch stays reserved for
+     * reaching the expected device and finding a different identity on it, which
+     * can mean it was wiped, reseeded, or swapped.
+     */
+    DeviceSearchMismatch = 10114,
+    FirmwareTooOld = 10200,
+    FirmwareUpdateRequired = 10201,
+    TransportError = 10300,
+    BridgeNotFound = 10301,
+    TransportNotAvailable = 10302,
+    /**
+     * OS-level permission (Bluetooth / USB / etc.) — denied, blocked,
+     * unavailable, or dismissed. Consumers surface a single "please grant
+     * permission" toast and let the user retry manually.
+     */
+    DevicePermissionDenied = 10303,
+    /**
+     * BLE SMP pairing did not complete within the GATT bonding window.
+     * GATT connected but the device didn't acknowledge SMP — typically
+     * because the user didn't confirm the passkey on the device, or the
+     * device went out of range mid-pairing. Distinct from OperationTimeout
+     * (generic) and from DeviceLocked (Secure Element actually locked).
+     */
+    BlePairingTimeout = 10304,
+    /** Remote network failure reaching a vendor's servers (HTTP/WS). Distinct from TransportError (local USB/BLE link). */
+    NetworkError = 10305,
+    /**
+     * Host-managed pairing handshake failed (Trezor THP). The device rejected the
+     * pairing exchange — e.g. CodeEntry: the user mistyped the code shown on the
+     * device, so the CPace tag didn't match ("Unexpected Code Entry Tag").
+     * Recoverable: the user re-pairs and re-enters the code. Distinct from
+     * BlePairingTimeout (BLE SMP bonding window) and UserRejected (on-device
+     * reject button).
+     */
+    ThpPairingFailed = 10306,
+    /**
+     * The OS-level BLE bond is stale/invalid, so the device rejected link
+     * encryption: Android GATT_INSUF_AUTHENTICATION (status 5) or iOS "Peer
+     * removed pairing information". Happens after the device is wiped/re-flashed
+     * or unpaired elsewhere while the host still holds an old bond. The SDK cannot
+     * remove an OS bond — the user must forget the device in system Bluetooth
+     * settings and re-pair. Distinct from BlePairingTimeout (SMP window) and
+     * ThpPairingFailed (THP code mismatch).
+     */
+    BleBondInvalid = 10307,
+    /**
+     * A stored THP pairing credential was rejected by the device during the
+     * handshake (device returned completion `state=0`), so the autoconnect session
+     * could not be established. The SDK discards the stale credential; recovery is
+     * a fresh pairing. Distinct from ThpPairingFailed (user mistyped the code
+     * during an *active* pairing) and BleBondInvalid (OS-level BLE bond).
+     */
+    ThpPairingRequired = 10308,
+    /**
+     * Generic BLE connect failure where the OS dropped the specific reason. On
+     * macOS the noble native binding hardcodes "connection failed" (and a connect
+     * timeout) and discards the CoreBluetooth NSError, so the SDK cannot tell a
+     * stale bond from an out-of-range / unresponsive device. Surfaced as a
+     * generic "couldn't connect — check the device, re-pair if paired before".
+     * Distinct from BleBondInvalid (a *known* stale-bond signal, iOS/Android only)
+     * and BlePairingTimeout (the SMP bonding window).
+     */
+    BleConnectFailed = 10309,
+    /**
+     * The user cancelled BLE pairing from the app while the connect was still
+     * waiting on the OS pairing window. Not a failure to report — the flow ends
+     * because they asked it to. Distinct from UserAborted (generic in-app cancel)
+     * so the pairing UI can close quietly instead of surfacing a connect error,
+     * and from BlePairingTimeout (the SMP window elapsed on its own).
+     */
+    BlePairingCancelled = 10310,
+    /**
+     * The vendor's remote secure channel broke while it was relaying APDUs to the
+     * device (Ledger: the manager-api script-runner WebSocket behind app install,
+     * uninstall and genuine check). The device link itself is still usable, so
+     * this is not a disconnect: retry the same call. Distinct from NetworkError,
+     * which is a plain HTTP/WS request that never carried device traffic.
+     */
+    LedgerSecureChannelError = 10311,
+    /**
+     * The vendor's metadata service answered with a payload the SDK cannot use
+     * (Ledger: firmware metadata or the application catalog). Not a connectivity
+     * failure — the request succeeded and the response was unusable — so callers
+     * must not treat it as a dropped link.
+     */
+    LedgerFirmwareMetadataError = 10312,
+    PinInvalid = 10400,
+    PinCancelled = 10401,
+    PassphraseRejected = 10402,
+    /**
+     * The passphrase entered produced a different wallet (`passphraseState`) than
+     * the one the caller asked to operate on. Trezor-only: the host pins a wallet
+     * by its derived state and the SDK refuses to sign with a mismatched
+     * passphrase session. Surfaced by TrezorAdapter.getPassphraseState.
+     */
+    PassphraseStateMismatch = 10403,
+    /**
+     * The two new-PIN entries did not match during set/change PIN. Only host-input
+     * models (Trezor Model One matrix) surface this; on-device-input models show
+     * the mismatch on the device and never return it.
+     */
+    PinMismatch = 10404,
+    /** Standard wallet is unavailable while Trezor enforces on-device passphrase entry. */
+    PassphraseAlwaysOnDevice = 10405,
+    /** Chain app NOT INSTALLED on device. User must install via Ledger Live. */
+    AppNotInstalled = 10500,
+    WrongApp = 10501,
+    /** 0x911c Command code not supported — app predates current SDK. */
+    AppTooOld = 10502,
+    /** Not enough free storage for install/update; user must uninstall apps first. */
+    DeviceOutOfMemory = 10503,
+    /** Install refused because the app is already on the device. Benign for callers that only need it present. */
+    AppAlreadyInstalled = 10504,
+    /**
+     * The call payload exceeds a transport's fixed framing capacity (e.g.
+     * Keystone USB's ~12.5KB per-request cap — 200 frames of 64 bytes). Distinct
+     * from a generic TransportError: the request never reached the device, and
+     * retrying with the same payload over the same transport will fail the same
+     * way. Callers should route the call over a different channel (e.g. Keystone
+     * QR) or reduce the payload (e.g. a smaller PSBT) instead of retrying as-is.
+     */
+    PayloadTooLarge = 10600,
+    /** 0x6a80 Invalid data — observed on blindSignTransactionFallback when the
+     *  user has not enabled Blind signing on the device. */
+    EvmBlindSigningRequired = 11000,
+    /** 0x6984 Plugin not installed */
+    EvmClearSignPluginMissing = 11001,
+    /** 0x6a84 Insufficient memory (typical on Nano S with large calldata) */
+    EvmDataTooLarge = 11002,
+    /** 0x6501 TransactionType not supported (app too old for EIP-1559 / blob / 7702) */
+    EvmTxTypeNotSupported = 11003,
+    /** 0x6808 Blind signing disabled for this instruction. */
+    SolanaBlindSigningRequired = 11100,
+    /** 0x6a8d Custom Contracts setting disabled (blocks TRC-20 etc.). */
+    TronCustomContractRequired = 11200,
+    /** 0x6a8b Transactions Data setting disabled. */
+    TronDataSigningRequired = 11201,
+    /** 0x6a8c Sign by Hash setting disabled (hash-signing fallback). */
+    TronSignByHashRequired = 11202,
+    /** 0xb008 Wallet policy HMAC mismatch or not registered. */
+    BtcWalletPolicyHmacMismatch = 11300,
+    /** 0xb007 Aborted due to unexpected state (malformed PSBT / missing UTXO). */
+    BtcUnexpectedState = 11301
+}
+/**
+ * Device-level failures the SDK cannot self-recover from — affect the entire
+ * batch (vs per-chain failures like AppNotInstalled / WrongApp which soft-
+ * skip in onboarding). Combined with `accounts.length === 0`, signals
+ * genuine orphan. Also reused as the batch-abort whitelist for HWK.
+ * Single source of truth.
+ *
+ * UserRejected (device-side reject) is included: pressing reject is an
+ * explicit "I don't consent" — continuing the batch to ask again on the
+ * next chain is harassment, not helpful.
+ */
+declare const ORPHAN_ELIGIBLE_ERROR_CODES: number[];
+/**
+ * Where a failure came from. The distinction the numeric code ranges cannot
+ * make reliably (UserRejected=10001 sits in the general range but is the
+ * device speaking; DevicePermissionDenied=10303 sits in the transport range
+ * but is the browser speaking), and the one recovery logic actually needs:
+ *
+ * - `device`    the firmware ANSWERED: rejection, locked screen, wrong
+ *               wallet, bad PIN. It is a result, not a malfunction — surface
+ *               it to the user verbatim; never auto-reconnect, never switch
+ *               channels, never drop a healthy session over it.
+ * - `transport` the pipe failed: cable pulled, bus reset, bridge gone.
+ *               Reconnecting or falling back to another channel is fair game.
+ * - `host`      the host environment refused: browser permission, picker
+ *               dismissed, bad parameters. Fix the environment, not the link.
+ *
+ * Optional on purpose: a mapper that cannot tell MUST leave it unset rather
+ * than guess — consumers fall back to their existing code-based tables, so an
+ * unset origin degrades to today's behavior instead of mislabeling.
+ */
+type HwkErrorOrigin = 'device' | 'transport' | 'host';
+/**
+ * Smallest runtime resource a consumer must replace before retrying a failed
+ * operation. This is connection-lifecycle metadata, not UI navigation and not
+ * permission to replay a signing command automatically.
+ *
+ * - `call`: nothing needs replacing; re-issuing the same call is eligible,
+ *   usually after the user fixes device state.
+ * - `operation`: the operation binding is no longer usable; the selected target
+ *   may be used to establish a new one when its identity is persistent.
+ * - `search-target`: the selected discovery result is stale or untrusted;
+ *   rediscover on the same transport and let the user select again.
+ * - `transport`: the selected transport is unavailable or unsuitable; repair
+ *   it or choose another transport.
+ * - `not-recoverable`: retrying the same operation/context cannot succeed.
+ * - `unknown`: the SDK cannot make a safe recovery claim.
+ */
+type HwkRecoveryScope = 'call' | 'operation' | 'search-target' | 'transport' | 'not-recoverable' | 'unknown';
+interface HwkRecoveryHint {
+    scope: HwkRecoveryScope;
+}
+declare function isHwkRecoveryHint(value: unknown): value is HwkRecoveryHint;
+/**
+ * Vendor-neutral fallback used when an adapter has no more precise runtime
+ * knowledge. Adapters may stamp a narrower hint when transport/session state
+ * makes the correct scope unambiguous.
+ */
+declare function defaultRecoveryForCode(code: HardwareErrorCode): HwkRecoveryHint;
+/**
+ * The authoritative code→origin table. Most codes imply their origin by
+ * definition (UserRejected IS the device speaking; BridgeNotFound IS the
+ * pipe). Vendors use this as the default and override only where their
+ * mapping context knows better. Codes whose origin genuinely depends on
+ * context (UnknownError, OperationTimeout — the device may be waiting for a
+ * human, or the pipe may be dead — and DeviceBusy) return undefined: an
+ * honest "can't tell" beats a plausible mislabel, because consumers fall
+ * back to their existing behavior instead of taking the wrong recovery.
+ */
+declare function defaultOriginForCode(code: HardwareErrorCode): HwkErrorOrigin | undefined;
+interface IHwkErrorPayload {
+    code: HardwareErrorCode;
+    message: string;
+    origin?: HwkErrorOrigin;
+    recovery?: HwkRecoveryHint;
+    appName?: string;
+    _tag?: string;
+    params?: Record<string, unknown>;
+}
+interface IOperationMayHaveCompletedParams extends Record<string, unknown> {
+    operationMayHaveCompleted: true;
+    method: string;
+}
+/**
+ * Marks an unsafe hardware request whose response was lost after dispatch.
+ * Callers must not interpret the resulting transport error as proof that the
+ * device rejected or did not execute the operation.
+ */
+declare function operationMayHaveCompletedParams(method: string, params?: Record<string, unknown>): IOperationMayHaveCompletedParams;
+type HwkError = Error & {
+    code: HardwareErrorCode;
+    /** See {@link HwkErrorOrigin}. Survives serializeConnectorError/rehydrate
+     *  automatically (own fields outside the top-level whitelist travel via
+     *  `params` and are lifted back). */
+    origin?: HwkErrorOrigin;
+    recovery?: HwkRecoveryHint;
+    appName?: string;
+    _tag?: string;
+    params?: Record<string, unknown>;
+};
+/**
+ * Canonical throwable for HWK adapters. Plain Error + canonical extra fields,
+ * shape-compatible with `rehydrateConnectorError` so locally-thrown and
+ * cross-boundary errors are indistinguishable to downstream classifiers
+ * (`err.code` / `err._tag` / `err.appName`). Do NOT mutate caught errors
+ * with `Object.assign` — construct a fresh one via this factory.
+ */
+declare function createHwkError(payload: IHwkErrorPayload): HwkError;
+
+/**
+ * Enrich a hardware error message with actionable recovery hints.
+ * Shared across adapters (Ledger, Trezor, etc.).
+ */
+declare function enrichErrorMessage(code: HardwareErrorCode, originalMessage: string): string;
+
+export { HardwareErrorCode as H, type IHwkErrorPayload as I, ORPHAN_ELIGIBLE_ERROR_CODES as O, type HwkErrorOrigin as a, type HwkRecoveryHint as b, type HwkError as c, type HwkRecoveryScope as d, type IOperationMayHaveCompletedParams as e, createHwkError as f, defaultOriginForCode as g, defaultRecoveryForCode as h, enrichErrorMessage as i, isHwkRecoveryHint as j, operationMayHaveCompletedParams as o };