WalletClient：应用与钱包之间的通信入口

一句话理解

WalletClient 是应用和钱包之间的通信入口：应用提出“我要创建什么交易”，钱包负责授权、签名、UTXO 管理和部分交易处理细节。

这件事很关键，因为真实 BSV 应用通常不应该直接拿用户私钥来签名。应用应该描述交易意图，让钱包在用户授权后完成敏感操作。

WalletClient 不是钱包本身

新手最容易误解的是：WalletClient 这个名字里有 Wallet，但它不是私钥库，也不是钱包余额数据库。

更准确地说，它是一个客户端。它通过某种通信方式连接到钱包实现。官方 SDK 文档把这种通信方式称为 substrate，可以是自动选择、本地 JSON API、浏览器环境、跨窗口通信、React Native 等不同形式。

简化理解：

应用不需要知道私钥在哪里，也不应该要求用户把助记词输入应用。钱包负责保管密钥，并在必要时让用户确认操作。

与 BRC-100 的关系

BRC-100 是 BSV 的钱包到应用接口标准。它的目标是让应用用一致的方式和不同钱包通信，而不是每个钱包都设计一套私有 API。

官方 TypeScript SDK 在 WalletClient 中实现了 BRC-100 相关接口。这意味着应用可以通过标准化方法请求钱包做事，例如：

• 创建交易。
• 签名交易。
• 管理可花费输出。
• 查询钱包信息。
• 处理身份和授权相关操作。

对新手来说，先抓住一点就够：WalletClient 让应用不用直接管理私钥，也不用手写每个钱包的接入逻辑。

最小连接示例

官方第一笔交易教程中的示例使用类似下面的方式连接钱包。

这里的 'auto' 表示让 SDK 自动选择合适的钱包通信方式。'localhost' 是本地开发时常见的 originator 标识。具体参数可能随钱包环境和 SDK 版本变化，写生产项目时要对照当前钱包和 SDK 文档。

连接之后，应用通常会调用钱包方法，例如：

真实交易不能总是空 outputs，这里只是说明调用关系。后续文章会具体解释 createAction() 的参数。

WalletClient 帮你隔离哪些复杂度

1. 隔离私钥：应用不直接接触私钥，减少密钥泄露风险。
2. 隔离 UTXO 管理：钱包知道用户有哪些可花费输出，应用不需要自己维护完整 UTXO 集。
3. 隔离签名流程：应用可以描述要花哪些输出、创建哪些新输出，钱包生成对应签名。
4. 隔离用户授权：钱包可以让用户看到交易描述，再决定是否同意。
5. 隔离不同钱包实现：只要钱包遵循相同接口，应用接入成本会下降。

在 BSV 技术栈里的位置

BSV 的应用开发不只是“拼一笔交易”。真实应用还涉及身份、授权、支付、数据发布、状态更新、token 输出、查询与索引。钱包接口是这些操作的入口之一。

• 在用户侧，钱包是资金和身份的控制点。
• 在应用侧，WalletClient 是请求这些能力的代码入口。
• 在网络侧，交易最终仍然要符合 BSV 协议规则，并被交易处理网络接受。

所以它不是“绕过协议的捷径”，而是“在应用层使用协议的接口”。

和直接使用私钥的区别

直接使用私钥的代码通常像这样：

1. 应用读取私钥
2. 应用选择 UTXO
3. 应用构造交易
4. 应用签名
5. 应用广播

这种方式适合某些后端服务、测试脚本或低层学习，但不适合普通用户应用。

使用 WalletClient 的思路是：

1. 应用描述动作
2. 钱包检查和授权
3. 钱包管理 UTXO
4. 钱包签名
5. 钱包返回结果

这更符合用户应用的安全边界。

新手常见误解

• WalletClient 不是私钥对象。它是通信客户端。
• 连接钱包不代表用户已经授权所有操作。具体交易通常仍要经过授权或策略检查。
• 钱包自动处理 UTXO，不代表应用可以不理解输出脚本。应用仍然要知道自己创建的是支付输出、数据输出还是应用协议输出。
• 不同钱包的可用能力可能不同。BRC-100 提供标准接口，但具体部署环境、权限和体验仍可能不同。
• 本地开发成功，不代表生产环境就能直接上线。生产环境还要处理权限、错误、重试、用户提示和交易状态。

参考来源

• Wallet reference
• First Transaction tutorial
• BRC-100 Wallet Interface
• Wallet Integration concept
• Wallet Toolbox docs