区块链原理 / 系统课时

列出钱包中的可用 UTXO

列出钱包中的可用 UTXO

构造 Bitcoin 交易前,需要先确定钱包里哪些未花费交易输出可以作为输入。本课使用 Bitcoin Core 的 listunspent 查询 UTXO,按确认数和可用状态筛选,记录 txid、vout 与金额,并通过钱包锁定机制降低重复选择同一输出的风险。

学习目标

  • 使用 Bitcoin Core RPC 查询指定钱包的 UTXO,并理解主要返回字段。
  • 根据确认数、安全状态和可花费条件筛选交易输入。
  • 使用 txid 与 vout 唯一定位输出,并在构造交易期间管理 UTXO 锁定状态。

在 regtest 钱包中查询 UTXO

UTXO 是尚未被其他有效交易消费的交易输出。Bitcoin 使用 txid 和 vout 共同定位一个输出:txid 标识创建该输出的交易,vout 是从零开始的输出索引。同一笔交易可以产生多个 UTXO,因此不能只记录 txid。

以下操作适用于 Bitcoin Core 31.0、Linux 或 macOS Bash 环境。需要安装 bitcoind、bitcoin-cli 和 jq,并提前启动一个独立的 regtest 节点。示例假定 regtest 区块链为空,钱包 utxo_lab 尚不存在;不要在已有测试钱包中重复执行创建命令。

首先创建钱包、生成接收地址,再挖掘 101 个测试区块,最后查询可用输出。

bash
# 创建独立测试钱包并生成接收地址
bitcoin-cli -regtest createwallet "utxo_lab" >/dev/null
addr=$(bitcoin-cli -regtest -rpcwallet=utxo_lab getnewaddress)

# 生成 101 个区块,使第一个区块的 coinbase 奖励成熟
bitcoin-cli -regtest generatetoaddress 101 "$addr" >/dev/null

# 查询已确认、安全且可求解的输出,并保留构造交易所需字段
bitcoin-cli -regtest -rpcwallet=utxo_lab listunspent 1 9999999 '[]' false \
  | jq '[.[] | select(.safe == true and .solvable == true and (.reused != true)) | {txid, vout, amount, confirmations}]'

预期输出(全新 regtest 链的典型结果):

json
[
  {
    "txid": "<ID>",
    "vout": 0,
    "amount": 50,
    "confirmations": 101
  }
]

<ID> 代表实际生成的 64 位十六进制交易 ID,每次创建区块的实际值不同。amount 的 JSON 数值显示格式也可能不同。在全新 regtest 链上,第一个区块的奖励为 50 BTC;挖掘 101 个区块后,该奖励满足 coinbase 成熟条件。其余较新的 coinbase 输出尚未成熟,因此不会出现在默认的可用列表中。

这里的 listunspent 只读取指定钱包所管理的输出,而不是遍历全网 UTXO。没有对应钱包密钥、描述符或监控信息的链上输出,不会因为存在于区块链中就自动进入该钱包的查询结果。

理解查询参数和筛选规则

listunspent 的完整调用形式为 listunspent minconf maxconf addresses include_unsafe query_options,其中各参数按位置传入。

参数 本例取值 实际作用
minconf 1 至少获得一次区块确认,排除零确认输出
maxconf 9999999 设置确认数上限,通常足以覆盖已有 UTXO
addresses [] 不限制接收地址,查询整个指定钱包
include_unsafe false 不返回钱包判定为不安全的输出
query_options 省略 不再施加额外金额和数量限制

还可以通过第五个参数传入 {"minimumAmount":0.001},只保留单个金额不小于 0.001 BTC 的输出。这个阈值是逐个 UTXO 比较,不是对钱包余额求和。

返回结果里需要特别检查以下字段:

字段 示例 选择时的含义
txid <ID> 创建该输出的交易标识
vout 0 创建交易中的输出索引
amount 50 金额,单位 BTC,而不是 sat
confirmations 101 当前确认数,可能随新区块改变
safe true 钱包认为该输出可以安全用于自动选币
solvable true 钱包知道该输出的花费脚本结构
spendable true Bitcoin Core 31.0 中已弃用,返回值始终为 true
reused false 或缺失 启用钱包 avoid_reuse 标志时才可能返回,用于识别地址重复使用相关输出

本课采用至少一次确认的保守选择策略。涉及大额资金时可以根据业务风险要求六次或更多确认,但这属于业务规则,并不是 Bitcoin 共识层规定的统一安全阈值。

金额在 RPC 中以 BTC 表示。例如 0.01500000 BTC 等于 1,500,000 sat。进行手续费和找零计算时,应转换为整数 sat,避免在程序内部直接累加二进制浮点数产生精度问题。

锁定已选输出,避免重复挑选

查询结果只是某个时间点的快照。两个交易构造流程如果读取同一批 UTXO,都可能挑选相同的 txid:vout。Bitcoin Core 提供 lockunspent 将指定输出排除出钱包的自动选币范围,并用 listlockunspent 查询锁定记录。

继续使用前面生成的 utxo_lab 钱包,选择一个输出并设置持久锁定:

bash
# 读取当前候选输出,只提取其唯一标识
chosen=$(bitcoin-cli -regtest -rpcwallet=utxo_lab listunspent 1 9999999 '[]' false \
  | jq -ec 'first(.[] | select(.safe == true and .solvable == true) | {txid, vout})')

# false 表示锁定;最后的 true 表示将锁定状态写入钱包数据库
bitcoin-cli -regtest -rpcwallet=utxo_lab lockunspent false "[$chosen]" true

# 检查指定输出是否出现在锁定列表中
bitcoin-cli -regtest -rpcwallet=utxo_lab listlockunspent \
  | jq --argjson target "$chosen" 'any(.[]; .txid == $target.txid and .vout == $target.vout)'

预期输出:

text
true
true

第一行表示锁定操作成功,第二行表示锁定列表确实包含所选输出。重新调用该钱包的 listunspent 时,已锁定输出不会被正常候选列表选中。

lockunspent 的第三个参数 persistent=true 表示锁定可跨节点重启保留;省略该参数时,默认只在内存中保存。需要释放输出时,可使用 lockunspent true 并传入相同的 txid、vout 数组。

实际交易构造系统至少应保存 txid、vout、整数 sat 金额、确认数和本地预留状态。业务侧可使用 txid:vout 作为唯一键,禁止两个未完成的交易任务同时占用同一输出。广播失败后也不要立即假定该输出可重新使用,应先检查交易是否进入内存池或已经被其他交易消费。

查询为空或余额不一致时怎样排查

listunspent 返回 [] 不一定意味着钱包没有收到资金。应按以下顺序缩小范围:

  1. 执行 bitcoin-cli -regtest getblockcount,确认实际链高度。如果刚挖出 coinbase 奖励但未满足成熟条件,需要继续等待或生成足够的区块。
  2. 执行 bitcoin-cli -regtest listwallets,确认目标钱包已加载,再检查每条命令是否都指定 -rpcwallet=utxo_lab。多钱包环境中漏掉钱包选择参数容易导致查询失败或读错钱包。
  3. 检查 minconf 是否设置过高,以及 addresses、minimumAmount 是否错误地排除了本应使用的输出。排查时可临时取消金额过滤,但不能因此忽略真实的安全条件。
  4. 执行 bitcoin-cli -regtest -rpcwallet=utxo_lab listlockunspent,确认候选输出是否被此前的任务锁定。只有确认不再被交易任务占用,才能解除锁定。
  5. 如果钱包已经发生转账,重新查询 listunspent,不要继续使用此前缓存的输入列表;必要时结合 gettxout 检查节点当前看到的输出状态。

例如,一个钱包拥有两笔已确认 UTXO,分别为 0.020 BTC 和 0.015 BTC,总额 0.035 BTC。若设置 minimumAmount=0.018,查询只会返回 0.020 BTC 那一笔;若这笔输出又被锁定,最终候选列表可能为空,即使钱包仍有未花费资金。

准备签名时,以最新的 txid、vout 和金额记录为依据,并将所选输出及其预留状态交给交易构造流程。钱包余额表示资金汇总,而真正能够放进交易输入列表的是逐笔确认可用的 UTXO。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

列出钱包中的可用 UTXO

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通