Stash Wallet SDK

面向第三方网站的官方 JavaScript / TypeScript SDK。网站通过扩展注入的 window.stashwallet 与钱包通信；SDK 不持有私钥，不负责业务后端的登录会话、定价或权限管理。

从 Git 仓库下载并构建

从 [email protected]:rgbstashlabs/stash-wallet-sdk.git 获取 SDK 源码。请先安装 Git、Node.js 和 npm，并确保已配置可访问 GitHub 的 SSH 密钥。

在业务项目的同级目录执行：

git clone [email protected]:rgbstashlabs/stash-wallet-sdk.git
cd stash-wallet-sdk
npm ci --include=dev
npm run build

npm ci 用于安装源码构建所需的依赖。构建成功后，dist/ 中会生成 ESM、CommonJS、TypeScript 类型定义和浏览器 UMD 产物；源码仓库不包含 dist/，必须先构建再使用。

在 JavaScript / TypeScript 项目中使用

回到业务项目根目录执行（假设业务项目与 stash-wallet-sdk/ 位于同一父目录，否则请调整相对路径）：

npm install ../stash-wallet-sdk

此命令将本地 SDK 目录添加为项目依赖。代码中仍使用 import { StashWalletClient } from 'stash-wallet-sdk'，参见下方快速接入示例。CI 或其他开发环境也需要先检出并构建 SDK，再按相同的相对路径安装本地依赖；建议固定使用经过验证的 Git tag 或 commit。

在普通 HTML 页面中使用

将构建生成的 dist/stash-wallet-sdk.umd.js 复制到网站的静态资源目录并自行托管。下面假设文件已部署到 /assets/stash-wallet-sdk.umd.js；该路径不是在线 CDN：

<script src="/assets/stash-wallet-sdk.umd.js"></script>
<script>
  const { StashWalletClient } = window.StashWalletSDK;
</script>

快速接入

在浏览器客户端执行，不要在 SSR 初始化过程中访问钱包：

import { StashWalletClient } from 'stash-wallet-sdk'

const client = await StashWalletClient.connect()
const { address } = await client.connect()
const { network } = await client.getNetwork()
const capabilities = await client.getCapabilities()
const accounts = await client.getAccounts()

这里两个 connect() 含义不同：

• 静态方法 StashWalletClient.connect()：等待 Provider 注入并创建客户端，不代表用户已授权。
• 实例方法 client.connect()：请求站点连接，由用户在扩展内批准，返回 { address }。

查询会话可使用 getWalletSessionStatus()；撤销当前站点授权可使用 disconnect()。断开站点连接不会锁定整个钱包。

检查运行时能力

const caps = await client.getCapabilities()
const { network } = await client.getNetwork()
if (!caps.canAuthSign || !caps.authNetworks.includes(network)) {
  throw new Error('Identity signing is unavailable on this wallet/network')
}

文档目录

• API 参考：所有客户端请求方法、参数、返回值与单位。
• Auth 登录：V2 challenge、签名上下文、后端验证与 V1 兼容。
• Provider 与事件：发现 Provider、事件订阅、Transport 与超时。
• 错误与兼容性：错误处理、支持范围与安全边界。