@ckb-ccc/xverse
将 Xverse 及兼容 SATS Connect 的钱包接入 CKB，并通过统一的 Signer 接口实现 Bitcoin 签名。
@ckb-ccc/xverse 将 Xverse Wallet 及任意兼容 SATS Connect 的 Bitcoin 钱包集成至 CCC。它基于 SATS Connect RPC 协议提供 SignerBtc 实现，并通过 window.btc_providers 支持多钱包发现。
如果你使用的是 @ckb-ccc/connector-react 或 @ckb-ccc/ccc，Xverse 已内置其中，无需单独安装。
安装
npm install @ckb-ccc/xverse依赖：
| 包 | 说明 |
|---|---|
@ckb-ccc/core | 基础类型——Signer、Client、Transaction 等 |
架构
与其他只检测单一全局 Provider 的钱包包不同，@ckb-ccc/xverse 通过读取 window.btc_providers 数组同时发现多个兼容 SATS Connect 的钱包。
入口：getXverseSigners
getXverseSigners(client) 从 window.btc_providers 读取数据。Xverse 及支持 WBIP 网络方法的 Provider 会分别获得 Mainnet、Testnet4、Signet 和 Regtest 条目；旧 Provider 保留单个 BTC 条目。
每个 Provider 条目包含钱包元数据（name、icon），SignersController 据此为每个钱包显示独立条目。
Signer 类
Signer 继承自 ccc.SignerBtc，所有钱包交互均通过 SATS Connect RPC 协议完成。
核心方法
| 方法 | 说明 |
|---|---|
connect() | 请求授权，并切换至所选网络 |
disconnect() | 清除缓存的地址 |
isConnected() | 检查选定网络并静默读取支付地址，不触发授权弹窗 |
getBtcAccount() | 通过 getAddresses 返回支付地址 |
getBtcPublicKey() | 从支付地址中返回公钥 |
signMessageRaw(message) | 通过 signMessage 使用 ECDSA 协议签名 |
onReplaced(listener) | 在 accountChange 或 networkChange 事件触发时调用 |
连接与地址缓存
Signer 缓存已解析的地址以避免重复 RPC 调用，调用 disconnect() 时缓存失效：
签名流程
账户变更检测
Signer 通过 SATS Connect 事件 API 实现 onReplaced()：
- 监听
"accountChange"——用户切换了 BTC 账户 - 监听
"networkChange"——用户切换了 BTC 网络
通过 provider.addListener() 返回清理函数，确保监听器正确移除。
SATS Connect RPC 方法
| 方法 | 说明 |
|---|---|
wallet_requestPermissions | 请求钱包连接权限 |
getAddresses | 按用途（Payment、Ordinals 等）获取地址列表 |
signMessage | 使用 ECDSA 或 BIP-322 签名消息 |
集成模式
@ckb-ccc/xverse 遵循 CCC 中其他钱包包相同的集成约定：
- Factory 函数——
getXverseSigners返回支持多钱包的{ wallet, signerInfo }[]数组。 - Provider 检测——读取
window.btc_providers数组。 - 多钱包发现——为每个 Provider 创建独立的 Signer 条目，附带各自的钱包名称和图标。
- 优雅降级——无可用的 SATS Connect 钱包时返回空数组。
Last updated on