错误与兼容性

错误处理

Transport 和 Provider 错误可能来自不同路径，不能假定每次拒绝都是 TransportError。Auth 参数检查还可能抛出普通 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() 将未识别值映射为 UNKNOWN；isKnownErrorCode() 检查是否为已知错误码。未知错误不能当作成功处理。

完整错误码

安装与连接

PROVIDER_NOT_FOUND：未发现注入 Provider；检查扩展安装、启用状态和站点权限后刷新。
EXTENSION_NOT_FOUND：旧 Chrome Transport 未发现扩展或无法通信。
ORIGIN_NOT_ALLOWED：来源不在允许范围。
ORIGIN_NOT_AUTHORIZED：站点未获授权；引导用户发起连接，不要循环弹窗。

会话与审批

WALLET_LOCKED：钱包锁定；由用户解锁。
SESSION_EXPIRED：会话过期；重新检查钱包会话和业务会话。
NODE_NOT_CONFIGURED：操作需要节点配置。
USER_REJECTED：用户拒绝；停止操作，不自动重试授权或资金请求。
APPROVAL_BUSY：已有审批进行中；等待用户完成后再主动发起下一项。

参数与兼容性

NETWORK_SWITCH_TIMEOUT：切换等待超时；重新查询网络，不假设切换失败或成功。
INVALID_PARAMETER：检查字段、格式、金额单位、网络和 challenge。
NOT_SUPPORTED：当前钱包不支持；隐藏或禁用对应入口。
UNKNOWN_MESSAGE_TYPE：方法或协议不兼容；核对 SDK 和扩展版本。

超时与未知错误

TIMEOUT：等待超时；资金操作先查询权威状态，禁止盲目重试。
UNKNOWN：无法归类；保留必要诊断，不记录凭据或敏感签名数据。

支持范围

SDK Network 类型包含 mainnet、testnet、testnet4、regtest。当前钱包能力返回的支持网络为 mainnet、testnet4、regtest；以运行时 supportedNetworks 为准。
当前 Auth 身份签名只支持 regtest；检查 canAuthSign 与 authNetworks。
requestNodeGrantSignature() 的公开类型将 challenge 网络限定为 regtest。
requestLspRevoke() 当前标注 NOT_SUPPORTED，不能用于撤销 Cloud 空闲保护。
解锁状态会影响发行、领取、兑换和签名能力；节点状态与模式会影响 LSP 能力。
canClaim 等能力标记不等于客户端提供同名方法。当前没有公开 client.claim()，也没有公开 hold-invoice 客户端方法。

能力标记只是当前可用性信号，不能替代审批、参数验证或服务端权限检查。使用 getVersion()、providerVersion 和 protocolVersion 排查兼容性，不应猜测版本对应的行为。

安全边界

私钥、签名和敏感凭据处理留在钱包受保护流程中；SDK 不持有私钥。
网页弹框不是钱包授权，资金操作必须经过扩展要求的审批。
浏览器 sender 决定真实 origin；不信任网页 payload 提供的 origin。
加密凭据必须发给可信接收方，不应输出到日志或发送给第三方分析服务。
身份签名不等于 BTC 地址或节点所有权证明。
后端必须独立获取权威价格、核算金额、验证交易条件及执行必要的滑点检查，不能信任网页报价。
请求超时不取消交易；业务方应先核查链上 / 支付状态，再决定是否允许重新发起。

错误与兼容性 ​

错误处理 ​

完整错误码 ​

安装与连接 ​

会话与审批 ​

参数与兼容性 ​

超时与未知错误 ​

支持范围 ​

安全边界 ​