Errors and compatibility

Handle errors

Transport and provider errors can follow different paths. Do not assume every rejection is a TransportError; Auth validation can throw a plain Error('INVALID_PARAMETER').

import { TransportError, normalizeErrorCode } from 'stash-wallet-sdk'
import type { TransportErrorCode } from 'stash-wallet-sdk'

function errorCode(error: unknown): TransportErrorCode {
  if (error instanceof TransportError) return error.code
  if (typeof error === 'object' && error !== null && 'code' in error) {
    const code = error.code
    if (typeof code === 'string') return normalizeErrorCode(code)
  }
  if (error instanceof Error && error.message === 'INVALID_PARAMETER') {
    return 'INVALID_PARAMETER'
  }
  return 'UNKNOWN'
}

normalizeErrorCode() maps unrecognized values to UNKNOWN. isKnownErrorCode() checks whether a code is known. Unknown errors must not be treated as success.

All error codes

Installation and connection

• PROVIDER_NOT_FOUND: injection not detected; check installation, enablement, and site permissions, then reload.
• EXTENSION_NOT_FOUND: legacy Chrome transport cannot find or communicate with the extension.
• ORIGIN_NOT_ALLOWED: origin is outside the allowed scope.
• ORIGIN_NOT_AUTHORIZED: site access has not been approved; let the user initiate connection rather than looping approval prompts.

Session and approval

• WALLET_LOCKED: ask the user to unlock the wallet.
• SESSION_EXPIRED: recheck wallet and application sessions.
• NODE_NOT_CONFIGURED: the operation requires node configuration.
• USER_REJECTED: stop; do not automatically retry approval or fund operations.
• APPROVAL_BUSY: another approval is active; allow the user to complete it before initiating another operation.

Parameters and compatibility

• NETWORK_SWITCH_TIMEOUT: refresh the network rather than assuming success or failure.
• INVALID_PARAMETER: check fields, formats, units, network, and challenge.
• NOT_SUPPORTED: disable or hide the unsupported action.
• UNKNOWN_MESSAGE_TYPE: check SDK/extension method and protocol compatibility.

Timeout and unknown errors

• TIMEOUT: for fund operations, check authoritative status before retrying.
• UNKNOWN: retain necessary diagnostics without logging credentials or sensitive signature data.

Support limits

• SDK Network includes mainnet, testnet, testnet4, and regtest. The current wallet reports mainnet, testnet4, and regtest; use runtime supportedNetworks.
• Identity signing currently supports regtest only. Check canAuthSign and authNetworks.
• The public requestNodeGrantSignature() challenge type is restricted to regtest.
• requestLspRevoke() is currently marked NOT_SUPPORTED and does not revoke Cloud idle protection.
• Unlock state affects issuance, claim, swap, and signing capabilities. Node state and mode affect LSP capabilities.
• Capability names do not imply matching client methods. There is currently no public client.claim() or hold-invoice client method.

Capabilities signal current availability but do not replace approvals, validation, or server permissions. Use getVersion(), providerVersion, and protocolVersion for diagnostics rather than assuming version-specific behavior.

Security boundaries

• Private keys, signing, and sensitive credentials remain in protected wallet workflows. The SDK holds no private keys.
• Page dialogs are not wallet authorization. Fund operations must follow the extension's required approval process.
• Browser sender metadata determines the real origin, not page-supplied payloads.
• Send encrypted credentials only to trusted recipients, never logs or third-party analytics.
• Identity signatures do not prove BTC address or node ownership.
• Backends must obtain authoritative prices, calculate amounts, validate trade conditions, and perform required slippage checks independently; do not trust page quotes.
• Timeout does not cancel transactions. Check chain/payment status before allowing another attempt.