智能合约与以太坊 / 系统课时
用 JSON-RPC 查询交易详情
用 JSON-RPC 查询交易详情
拿到一笔 Ethereum 交易的哈希后,可以直接向执行客户端查询交易内容和执行收据,确认它发送了什么、是否进入区块、执行是否成功以及实际消耗了多少 Gas。本课使用 Python 标准库完成两次 JSON-RPC 调用,并解释返回字段及常见的空结果。
学习目标
- 使用
eth_getTransactionByHash和eth_getTransactionReceipt查询同一笔交易。 - 区分 JSON-RPC 的十六进制数量、交易字段和执行收据字段。
- 根据收据计算实际 Gas 费用,并识别待打包、执行失败和查询不到记录的情况。
准备 RPC 端点与交易哈希
Ethereum 执行层的 JSON-RPC 通常通过 HTTP POST 接收请求。开始前需要准备一个可访问的执行客户端 RPC 地址,以及该网络上的真实交易哈希。以下示例使用 Python 3.10 或更高版本,无需安装第三方依赖。
- 确认本地执行客户端已启用 HTTP JSON-RPC。如果使用已配置好的本地开发节点,RPC 地址可能是
http://127.0.0.1:8545;实际地址和端口以节点配置为准。 - 从钱包、交易浏览器或交易发送接口的返回值中取得完整交易哈希。
- 确认 RPC 连接的网络与交易所属网络一致。例如,主网交易不能直接在独立的本地开发链中查询。
- 将交易哈希保存备用。标准 Ethereum 交易哈希为 32 字节,文本形式是
0x加 64 个十六进制字符。
每条 JSON-RPC 请求主要包含四个字段:jsonrpc 固定为 2.0,method 指定接口,params 按接口定义提供参数,id 用于关联请求和响应。两个查询接口都只接收一个交易哈希参数,不需要额外传入区块高度。
发送请求并读取交易和收据
eth_getTransactionByHash 返回交易对象,描述发送方、接收方、转账金额、Gas 限额、输入数据及区块归属等信息。eth_getTransactionReceipt 返回已经进入区块的交易执行收据,包含执行状态、实际 Gas 用量和事件日志。
下面的程序将两次调用组合在一起。保存为 rpc_tx.py,再执行 python3 rpc_tx.py <RPC_URL> <TX_HASH>,将两个占位符替换为真实 RPC 地址和交易哈希。程序使用不同的请求 ID 区分调用,并检查 JSON-RPC 错误和空结果。
import json
import sys
from decimal import Decimal
from urllib.request import Request, urlopen
def rpc(url, method, tx_hash, request_id):
# 按 JSON-RPC 2.0 协议构造 POST 请求
payload = {
'jsonrpc': '2.0',
'id': request_id,
'method': method,
'params': [tx_hash],
}
request = Request(
url,
data=json.dumps(payload).encode('utf-8'),
headers={'Content-Type': 'application/json'},
method='POST',
)
with urlopen(request, timeout=15) as response:
body = json.load(response)
if 'error' in body:
raise RuntimeError(f'{method}: {body["error"]}')
return body['result']
def main():
if len(sys.argv) != 3:
raise SystemExit('用法:python3 rpc_tx.py <RPC_URL> <TX_HASH>')
url, tx_hash = sys.argv[1:]
if len(tx_hash) != 66 or not tx_hash.startswith('0x'):
raise SystemExit('交易哈希应为 0x 加 64 个十六进制字符')
try:
int(tx_hash[2:], 16)
except ValueError:
raise SystemExit('交易哈希包含非十六进制字符')
tx = rpc(url, 'eth_getTransactionByHash', tx_hash, 1)
if tx is None:
print('交易:未找到')
return
print('发起方:', tx['from'])
print('接收方:', tx['to'])
print('nonce:', int(tx['nonce'], 16))
print('转账 Wei:', int(tx['value'], 16))
print('所在区块:', tx['blockNumber'] or '待打包')
receipt = rpc(url, 'eth_getTransactionReceipt', tx_hash, 2)
if receipt is None:
print('收据:暂不可用,可能尚未打包')
return
# 以收据中的实际用量和实际单价计算执行层 Gas 费用
gas_used = int(receipt['gasUsed'], 16)
gas_price = int(receipt['effectiveGasPrice'], 16)
fee_eth = Decimal(gas_used * gas_price) / Decimal(10**18)
print('执行状态:', '成功' if int(receipt['status'], 16) == 1 else '失败')
print('实际 Gas:', gas_used)
print('实际 Gas 单价(Wei):', gas_price)
print('执行层 Gas 费用(ETH):', fee_eth)
print('日志条数:', len(receipt['logs']))
if __name__ == '__main__':
main()预期输出示例:假设查询的是一笔已经进入区块、发送 1 ETH、实际使用 21000 Gas、单价为 20 Gwei 的成功普通转账,则输出形式如下。地址、Nonce、区块编号及其他数值随实际交易变化。
发起方: <ADDRESS>
接收方: <ADDRESS>
nonce: <NONCE>
转账 Wei: 1000000000000000000
所在区块: <BLOCK_HEX>
执行状态: 成功
实际 Gas: 21000
实际 Gas 单价(Wei): 20000000000
执行层 Gas 费用(ETH): 0.00042
日志条数: 0这里的 <ADDRESS>、<NONCE>、<BLOCK_HEX> 都代表实际返回的动态值。如果交易尚未打包,程序会显示待打包和收据暂不可用;如果当前节点没有找到交易,则只会显示交易未找到。HTTP 连接失败、超时及 JSON-RPC 错误不会被当作正常交易状态。
区分交易字段与执行收据字段
同一个交易哈希可以查询出两种不同对象。交易对象记录发送者提交的交易内容,收据记录该交易实际执行后的结果。判断手续费和执行状态时,必须以收据为依据。
| 查询来源与字段 | 含义 | 阅读重点 |
|---|---|---|
交易 from、to |
发送方和目标地址 | 创建合约时 to 为 null |
交易 nonce |
发送账户的交易序号 | 是十六进制数量,不是交易哈希 |
交易 value |
转移的 ETH 数量,以 Wei 表示 | 合约调用也可能为 0x0 |
交易 input |
调用数据或合约部署字节码 | 普通无数据转账通常是 0x |
交易 gas |
交易设置的 Gas 上限 | 不等于实际消耗 |
交易 blockNumber |
所属区块编号 | 待打包时为 null |
收据 status |
执行状态 | 0x1 成功,0x0 失败 |
收据 gasUsed |
本笔交易实际使用的 Gas | 计算执行层 Gas 费用 |
收据 effectiveGasPrice |
实际每单位 Gas 的支付价格 | 单位 Wei |
收据 logs |
执行产生的事件日志 | 为空不一定表示失败 |
收据里的 cumulativeGasUsed 是截至本笔交易为止,该区块内交易累计消耗的 Gas,不能拿来计算这笔交易自己的手续费。合约创建交易还可以通过收据的 contractAddress 查询创建的合约地址;普通转账或普通合约调用时该字段为 null。
对于 EIP-1559 动态费用交易,交易对象中的 maxFeePerGas 和 maxPriorityFeePerGas 表示发送者设置的费用上限,而收据的 effectiveGasPrice 才是实际计算执行层费用时应采用的单价。不同交易类型还可能包含额外字段,例如 Blob 交易的相关费用字段。
解析十六进制数量并计算 Gas 费用
JSON-RPC 返回的整数采用 QUANTITY 编码,使用 0x 前缀、最短十六进制表示法,零写为 0x0。地址、哈希和 input 则属于字节数据,虽然也使用十六进制形式,但不能全部当作整数处理。
例如,收据返回 gasUsed = 0x5208,转换后是 21000;effectiveGasPrice = 0x4a817c800,转换后是 20000000000 Wei,即 20 Gwei。
| 数量 | 数值 | 单位 |
|---|---|---|
| 实际 Gas 用量 | 21000 | Gas |
| 实际 Gas 单价 | 20 | Gwei/Gas |
| 执行层 Gas 费用 | 420000000000000 | Wei |
| 换算后费用 | 0.00042 | ETH |
换算关系为:1 Gwei = 1000000000 Wei,1 ETH = 1000000000000000000 Wei。因此,这笔交易的执行层 Gas 费用等于 21000 乘以 20000000000,再除以 1000000000000000000,最终得到 0.00042 ETH。
程序中使用 int(hex_string, 16) 解析十六进制数量,使用 Python 整数完成乘法,最后使用 Decimal 换算 ETH,避免大整数经过浮点数后发生精度损失。
识别空结果、失败状态与查询异常
result: null 并不等于交易执行失败。查询时要把交易存在性、是否进入区块和执行结果分开判断。
| 查询现象 | 可能含义 | 下一步检查 |
|---|---|---|
交易对象为 null |
当前节点未找到交易 | 检查网络、哈希和节点可用历史数据 |
交易存在且 blockNumber 为 null |
节点已知交易,但尚未进入区块 | 稍后重新查询,检查交易池状态 |
交易存在但收据为 null |
尚未获得入块执行结果 | 重新查询收据,确认是否被打包 |
收据 status = 0x0 |
交易已执行但失败 | 检查合约调用、Gas 限额和回退条件 |
收据 status = 0x1 |
顶层交易执行成功 | 按业务需要检查日志及合约状态 |
如果 HTTP 请求返回连接拒绝或超时,应先检查 RPC 地址、端口及节点服务。JSON-RPC 返回 error 时,应读取错误对象中的错误码和信息,而不是将其解释成链上交易失败。
还需要注意三个边界:首先,执行失败的已入块交易仍可能消耗 Gas;其次,收据通常不直接提供完整的 Solidity 回退原因,进一步定位可能需要调用追踪接口或重现执行;最后,查到区块编号和成功收据只说明交易已进入当前节点认可的链,不等于区块已经最终确定,链重组仍可能改变其归属和确认情况。
实际排查时,先使用 eth_getTransactionByHash 确认交易内容和入块状态,再使用 eth_getTransactionReceipt 检查执行结果、Gas 和日志。按照这一顺序能够避免把交易未找到、尚未打包和执行失败混为一谈。