区块链原理 / 系统课时
用 RPC 组装原始交易输入输出
用 RPC 组装原始交易输入输出
本课使用 Bitcoin Core 的 RPC 接口,在 regtest 私有测试网络中构造一笔未签名交易:选择已有 UTXO,指定收款和找零金额,生成原始交易十六进制数据,再解码检查输入引用、输出脚本、序列号及手续费。完成后可以得到结构正确、尚未签名和广播的交易数据。
学习目标
- 使用
createrawtransaction指定交易输入、收款输出和找零输出。 - 使用
decoderawtransaction检查交易字段和序列化结果。 - 根据输入输出金额计算手续费,并识别未签名交易的验证边界。
原始交易需要哪些输入数据
Bitcoin 交易不直接从账户余额中扣除金额,而是引用此前交易产生的未花费交易输出,即 UTXO。构造交易时,必须明确指出准备花费哪个旧输出,并创建金额和锁定条件确定的新输出。
假设钱包已有一笔价值 1.00000000 BTC 的 UTXO,目标是向接收者支付 0.40000000 BTC,同时保留 0.59990000 BTC 作为找零。
| 项目 | 示例值 | 作用 |
|---|---|---|
| 输入引用 | 旧交易 txid 与 vout |
指定待花费的 UTXO |
| 输入金额 | 1.00000000 BTC | 来自被引用的旧输出 |
| 收款输出 | 0.40000000 BTC | 锁定到接收地址 |
| 找零输出 | 0.59990000 BTC | 锁定到钱包控制的找零地址 |
| 隐含手续费 | 0.00010000 BTC | 输入金额减去输出金额总和 |
手续费不是交易中的独立输出字段,而是节点根据被引用的 UTXO 金额与新输出金额计算得到:
本例中,手续费为 0.00010000 BTC,即 10000 sat。这里只采用固定金额演示字段关系,实际交易应根据签名后的虚拟大小和目标费率确定手续费。

createrawtransaction 接收两项核心参数:inputs 数组和 outputs 数组。每个输入至少包含旧交易的 txid 与输出索引 vout;每个普通收款输出以地址为键、BTC 金额为值。它不会自动查找 UTXO、计算找零或为交易签名。
在 regtest 中准备可花费的 UTXO
以下示例适用于 Bitcoin Core 30.0 的 RPC 接口,使用 Linux 或 macOS 的 Bash 环境,并要求系统已安装 bitcoin-cli、bitcoind 和 jq。请在全新的 regtest 数据目录中首次运行;如果已有测试节点和钱包,应跳过重复创建操作并使用现有钱包。
为了让实验结果可重复,先生成 101 个区块,使最早的挖矿奖励达到可以花费的成熟条件。随后向测试钱包自身发送 1 BTC,再挖出一个区块确认该交易,取得金额精确的 UTXO。
下面将准备环境、构造交易和解码验证放进同一个 Bash 示例中,避免跨终端执行时丢失变量。整个过程只使用 regtest 地址,不涉及真实比特币。
调用 RPC 构造并解码交易
createrawtransaction 的第三个参数设置 locktime=0,第四个参数设置 replaceable=true。输入的 sequence 显式指定为 4294967293(十六进制 0xfffffffd),使结果不依赖不同版本的默认序列号行为。
set -euo pipefail
# 首次启动私有测试节点并创建实验钱包
bitcoind -regtest -daemon >/dev/null
bitcoin-cli -regtest -rpcwait createwallet rawlab >/dev/null
miner=$(bitcoin-cli -regtest -rpcwallet=rawlab getnewaddress)
bitcoin-cli -regtest -rpcwallet=rawlab generatetoaddress 101 "$miner" >/dev/null
# 制造并确认一笔精确为1 BTC的可花费输出
fund_addr=$(bitcoin-cli -regtest -rpcwallet=rawlab getnewaddress)
fund_txid=$(bitcoin-cli -regtest -rpcwallet=rawlab sendtoaddress "$fund_addr" 1.0)
bitcoin-cli -regtest -rpcwallet=rawlab generatetoaddress 1 "$miner" >/dev/null
utxo=$(bitcoin-cli -regtest -rpcwallet=rawlab listunspent 1 9999999 | jq -c --arg id "$fund_txid" 'map(select(.txid == $id and .amount == 1))[0]')
vout=$(jq -r '.vout' <<< "$utxo")
test "$vout" != null
# 分别生成收款地址与找零地址
receiver=$(bitcoin-cli -regtest -rpcwallet=rawlab getnewaddress "" bech32)
change=$(bitcoin-cli -regtest -rpcwallet=rawlab getrawchangeaddress bech32)
inputs=$(jq -nc --arg id "$fund_txid" --argjson n "$vout" '[{txid:$id,vout:$n,sequence:4294967293}]')
outputs=$(jq -nc --arg to "$receiver" --arg change "$change" '[{($to):"0.40000000"},{($change):"0.59990000"}]')
# 只创建未签名交易,不签名、不广播
rawhex=$(bitcoin-cli -regtest createrawtransaction "$inputs" "$outputs" 0 true)
decoded=$(bitcoin-cli -regtest decoderawtransaction "$rawhex")
# 检查结构、序列号与以sat为单位的输出金额
jq -r '"version=\(.version) locktime=\(.locktime)","vin=\(.vin|length) vout=\(.vout|length)","sequence=\(.vin[0].sequence)",(.vout[]|"output[\(.n)]=\(.value) BTC"),"output_sats=\(.vout|map(.value*100000000|round)|add)"' <<< "$decoded"
jq -e '(.vin|length)==1 and (.vout|length)==2 and (.vout|map(.value*100000000|round)|add)==99990000' <<< "$decoded" >/dev/null
echo '校验通过'预期输出:
version=2 locktime=0
vin=1 vout=2
sequence=4294967293
output[0]=0.4 BTC
output[1]=0.5999 BTC
output_sats=99990000
校验通过这段脚本通过 listunspent 找出刚刚确认的 1 BTC 输出,并读取它的实际 vout 索引,因此不假定收款输出一定排在索引 0。jq 根据真实地址生成 JSON 参数,避免人工拼接地址时产生引号和转义错误。
outputs 使用数组指定顺序,因此接收者得到 vout[0],找零地址得到 vout[1]。金额以 BTC 为单位传入 RPC,验证时转换为整数 sat,能够避免直接使用浮点数比较造成的精度问题。
在同一终端中,还可以直接查看完整解码对象:
bitcoin-cli -regtest decoderawtransaction "$rawhex"预期结果是返回包含 txid、hash、version、size、vsize、weight、locktime、vin 和 vout 等字段的 JSON 对象。实际交易 ID、地址和字节数随运行环境变化,不应与固定示例值比较。
核对序列化字段与锁定脚本
decoderawtransaction 将原始十六进制字节还原为结构化字段。检查时,先确认交易头部及输入引用,再核对两个输出的金额和锁定脚本。
| 字段 | 本例应满足的条件 |
|---|---|
version |
等于 2 |
locktime |
等于 0,不施加绝对锁定时间 |
vin[0].txid |
等于准备阶段得到的 fund_txid |
vin[0].vout |
等于从 listunspent 读取的输出索引 |
vin[0].sequence |
等于 4294967293 |
vout[0].value |
等于 0.40000000 BTC |
vout[1].value |
等于 0.59990000 BTC |
vout[].scriptPubKey |
包含对应地址的锁定脚本信息 |
本例显式要求 Bech32 v0 地址,因此两个输出的 scriptPubKey.type 应为 witness_v0_keyhash。其锁定脚本通常由见证版本 0、20 字节公钥哈希构成;在十六进制表达中,前缀为 0014,后接 40 个十六进制字符的公钥哈希。
对于这笔尚未签名的交易,输入中的 scriptSig.hex 为空,也没有提供用于授权花费的见证签名数据。由于还没有见证部分,当前解码结果通常满足 size=vsize 且 weight=4×size。完成签名后,见证数据会影响交易权重和虚拟大小,因此不能用这里的字节数直接推算最终费率。
处理常见构造错误
在实际调用 RPC 时,最容易出现的问题不是十六进制序列化,而是输入引用、网络地址和金额组合不符合预期。
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 交易输入找不到 | 使用了错误的 txid 或 vout |
重新查询 listunspent,确认 UTXO 存在且尚未消费 |
| 地址被拒绝 | 主网、测试网与 regtest 地址混用 | 使用 getnewaddress 在当前网络生成地址 |
| 输出金额不正确 | BTC 与 sat 单位混淆 | 以 100000000 sat = 1 BTC 换算并核对 |
| 输出构造失败 | 重复使用相同地址作为多个输出键 | 合并金额,或使用不同收款与找零地址 |
| 解码成功但无法花费 | 输入尚未签名,或旧输出锁定条件不满足 | 后续使用钱包签名并执行交易验证 |
手续费也应单独检查:本例输入 100000000 sat,输出合计 99990000 sat,差额 10000 sat,不能出现输入总额小于输出总额的情况。对于多输入交易,必须逐个查询旧输出金额再求和,因为普通原始交易输入并不直接携带被花费 UTXO 的金额。
实际开发中,若需要自动选择 UTXO、补充找零并估算手续费,可使用 fundrawtransaction 辅助构造;如果需要严格指定交易的输入和输出,则应保留当前手动构造方式,并明确控制 sequence、手续费以及输出顺序。
本课得到的 rawhex 是可解码的未签名交易。后续可交给 signrawtransactionwithwallet 添加授权签名,再通过 testmempoolaccept 检查交易能否进入内存池,确认有效后才使用 sendrawtransaction 广播。