区块链原理 / 系统课时

从 txid 查询交易的输入输出

从 txid 查询交易的输入输出

拿到一笔 Bitcoin 交易的 txid 后,需要先确认本地节点能否找到交易,再将原始十六进制数据解码为输入与输出。本课使用 Bitcoin Core 在 regtest 网络创建一笔 0.01 BTC 交易,检查 vin、vout、金额和锁定脚本,并掌握交易确认后的查询方法。

学习目标

  • 区分 getrawtransaction 的原始字节模式、详细信息模式与 decoderawtransaction 的解码用途。
  • 正确读取 vin、vout、输出金额及 scriptPubKey,理解输入对历史 UTXO 的引用。
  • 在交易进入区块后继续通过 blockhash 查询,并定位常见的交易未找到问题。

构造一笔可查询的交易

以下实验适用于 Bitcoin Core 30.0 和 31.0,使用 Linux 或 macOS 的 Bash 终端,并要求已安装 bitcoin-cli、bitcoind 和 jq。实验使用全新的本地 regtest 数据目录,不涉及真实 BTC。如果已经启动 regtest 节点,可跳过启动命令。

regtest 是由本地开发者控制出块的独立测试网络。我们先创建钱包,生成 101 个区块使最早的 Coinbase 奖励达到可花费成熟度,再发送 0.01 BTC 给同一钱包生成的新地址。这是一笔真实构造、签名并提交到本地节点内存池的测试交易。

bash
set -euo pipefail

# 首次运行:启动独立的 regtest 节点并创建钱包
bitcoind -regtest -daemon >/dev/null
bitcoin-cli -regtest -rpcwait createwallet "tx-trace-lab" >/dev/null

mine_addr=$(bitcoin-cli -regtest -rpcwallet=tx-trace-lab getnewaddress)
# 挖出 101 个区块,使最早的 Coinbase 输出可以花费
bitcoin-cli -regtest generatetoaddress 101 "$mine_addr" >/dev/null

receive_addr=$(bitcoin-cli -regtest -rpcwallet=tx-trace-lab getnewaddress)
txid=$(bitcoin-cli -regtest -rpcwallet=tx-trace-lab -named sendtoaddress address="$receive_addr" amount=0.01 fee_rate=2)

# 先取得原始十六进制,再调用独立的解码 RPC
raw=$(bitcoin-cli -regtest getrawtransaction "$txid" 0)
bitcoin-cli -regtest decoderawtransaction "$raw" |
  jq --arg addr "$receive_addr" '{input_count: (.vin | length), output_count: (.vout | length), payment: ([.vout[] | select(.scriptPubKey.address == $addr) | .value] | add)}'

# verbosity=1 直接返回包含 vin、vout 的 JSON
bitcoin-cli -regtest getrawtransaction "$txid" 1 |
  jq '{txid_length: (.txid | length), confirmations: (.confirmations // 0)}'

预期输出(首次运行、钱包中只有这笔可花费 Coinbase 奖励时):

json
{
  "input_count": 1,
  "output_count": 2,
  "payment": 0.01
}
{
  "txid_length": 64,
  "confirmations": 0
}

sendtoaddress 中的 fee_rate=2 表示 2 sat/vB,而不是 2 BTC。这里有两个输出,通常分别是 0.01 BTC 的收款输出和扣除手续费后的找零输出;Bitcoin Core 可能调整两者在 vout 数组中的顺序,不应假设收款输出永远位于索引 0。

txid 是 64 个十六进制字符组成的交易标识符。实际标识符、地址和找零金额每次运行都可能不同,可以统一记为 <ID> 等动态值。再次执行整段脚本前需要处理已经存在的 tx-trace-lab 钱包,或者使用新的隔离数据目录。

读取原始交易和解码字段

两个 RPC 的职责不同:getrawtransaction 负责从节点可访问的交易数据中取得交易,decoderawtransaction 则负责解析已经拿到的交易十六进制内容。

调用形式 返回内容 适用场景
getrawtransaction <ID> 0 完整交易的十六进制序列化数据 保存、传输或进一步解码
getrawtransaction <ID> 1 含 vin、vout 的 JSON 对象 直接查看输入输出
getrawtransaction <ID> 2 JSON,额外尝试提供手续费及历史输出信息 追踪输入金额与手续费
decoderawtransaction <HEX> 从原始十六进制数据解析的 JSON 检查编码、结构和脚本

其中 <ID> 代表实际 txid,<HEX> 代表真实交易十六进制字符串。getrawtransaction 的第三个可选参数是包含该交易的 blockhash。verbosity=2 提供的 fee、prevout 等字段受历史数据可用性限制,不能假设在所有节点和场景下都存在。

查看解码结果时,优先认识以下字段:

字段 含义 读取要点
txid 不包含见证数据的交易标识符 匹配查询时提供的 ID
hash 包含见证数据的交易哈希 对于包含见证数据的交易,可能与 txid 不同
vin[].txid 被花费输出所属的历史交易 指向前一笔交易,不是当前 txid
vin[].vout 被花费输出在历史交易中的索引 从 0 开始计数
vin[].sequence 输入序列号 与锁定时间及交易替换等规则相关
vout[].n 当前交易输出索引 与当前 txid 一起定位新的输出
vout[].value 当前输出金额 单位为 BTC,不是 sat
vout[].scriptPubKey 当前输出的锁定脚本信息 包含脚本字节、汇编表示及类型

对于原生 SegWit 输入,scriptSig 通常为空,签名相关见证数据位于 txinwitness。对于 Coinbase 交易,输入使用 coinbase 字段而不是普通交易的历史 txid 引用。

读取输出脚本时,scriptPubKey.hex 表示原始脚本字节,asm 表示便于阅读的脚本汇编形式,type 表示节点识别的脚本类型。例如 witness_v0_keyhash 对应 P2WPKH,witness_v1_taproot 对应 Taproot 输出。address 仅在脚本可以映射到明确地址时提供,不能把它当成必有字段,也不要依赖旧版本的 addresses 数组。

从输入引用追踪历史 UTXO

Bitcoin 交易采用 UTXO 模型。普通输入并不直接存放所花费的金额,而是通过历史交易的 txid 和输出索引定位一个已有的交易输出;当前交易的 vout 则定义本次新创建的输出。

通过 txid、vin 与 vout 还原 UTXO 消费和创建关系

例如,一笔普通交易的某个输入引用了历史交易 A 的第 0 个输出,该输出价值 1.00000000 BTC。新交易创建 0.01000000 BTC 的收款输出及 0.98999000 BTC 的找零输出,则手续费为:

1.00000000−0.01000000−0.98999000=0.00001000 BTC1.00000000-0.01000000-0.98999000=0.00001000\ \mathrm{BTC}

这个数值案例独立于前面生成的 regtest 交易。真实交易的手续费由全部输入金额减去全部输出金额计算,不能仅凭某一个 vin 的引用直接得到。

追踪时可以按以下顺序操作:

  1. 从当前交易的 vin[0].txid 获取历史交易 ID,记录 vin[0].vout 的数值。
  2. 查询该历史交易并解码,找到 vout 中 n 等于记录索引的输出。
  3. 读取该输出的 value 和 scriptPubKey,确认被花费的金额与锁定条件。
  4. 对所有普通输入重复上述过程,合计输入金额,再减去当前交易全部 vout[].value。

金额计算时建议使用 sat 作为整数单位,1 BTC 等于 100000000 sat。这样可以避免在程序中反复使用二进制浮点数进行精确余额计算。

已确认交易如何查询与排错

刚发送的交易通常存在于节点内存池,因此即使没有启用交易索引,也能通过 getrawtransaction 查询。交易被打包进区块后,如果节点没有启用 -txindex=1,仅提供 txid 就可能无法查到历史交易。

对于已知归属区块的交易,可以把区块哈希作为第三个参数传给 getrawtransaction。接着前面的实验执行以下命令:

bash
# 将刚创建的交易打包进下一个 regtest 区块
bitcoin-cli -regtest generatetoaddress 1 "$mine_addr" >/dev/null

# 钱包 RPC 能提供该钱包交易所属的区块哈希
blockhash=$(bitcoin-cli -regtest -rpcwallet=tx-trace-lab gettransaction "$txid" | jq -r '.blockhash')

# 明确指定区块,无需依赖全局 txindex
bitcoin-cli -regtest getrawtransaction "$txid" 1 "$blockhash" |
  jq '{confirmations, in_active_chain}'

预期输出:

json
{
  "confirmations": 1,
  "in_active_chain": true
}

这里的 confirmations=1 表示包含该交易的区块已位于当前活动链中,并且该区块就是链尖。in_active_chain 只有显式提供 blockhash 时才会出现在此 RPC 的详细结果中。以后继续挖块,确认数会随链高度增加;如果发生链重组,确认状态也可能变化。

如果查询失败,应按下列顺序区分原因:

现象 首先检查 处理方式
报告找不到交易 节点是否连接正确网络,txid 是否完整 用 getblockchaininfo 核对 chain,检查 64 位十六进制 txid
未确认交易不可见 是否仍在本地 mempool 使用 getmempoolentry 检查;交易可能未广播成功或已被移除
已确认交易不可见 是否缺少 txindex 和 blockhash 已知区块时传第三参数,或在非裁剪节点配置交易索引
指定 blockhash 仍失败 区块是否存在且数据可读取 核对区块哈希、交易归属及节点裁剪状态
钱包里有记录但原始查询失败 钱包记录与节点交易索引的查询范围不同 对本钱包交易使用 gettransaction 查看记录

在需要持续按 txid 查询历史交易的专用节点上,可以配置 txindex=1,重启节点并等待索引构建完成。对于启用区块裁剪的节点,完整交易索引与裁剪配置存在限制,应先确认部署方式是否适合保留所需历史区块。

实际排查时,先确认 txid、网络与交易所在位置,再选择 mempool 查询、带 blockhash 的历史区块查询或完整索引查询。读懂 vin 指向的历史输出和当前 vout 创建的新输出,就能够从一笔交易继续追踪整条 UTXO 资金流。

RPC 参数及版本差异可对照 Bitcoin Core 31.0 官方文档:getrawtransaction 与 decoderawtransaction。

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

目录与阅读设置

阅读设置

17

记录一个想法

从 txid 查询交易的输入输出

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

登录哪都通