智能合约与以太坊 / 系统课时

用 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 或更高版本,无需安装第三方依赖。

  1. 确认本地执行客户端已启用 HTTP JSON-RPC。如果使用已配置好的本地开发节点,RPC 地址可能是 http://127.0.0.1:8545;实际地址和端口以节点配置为准。
  2. 从钱包、交易浏览器或交易发送接口的返回值中取得完整交易哈希。
  3. 确认 RPC 连接的网络与交易所属网络一致。例如,主网交易不能直接在独立的本地开发链中查询。
  4. 将交易哈希保存备用。标准 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 错误和空结果。

python
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、区块编号及其他数值随实际交易变化。

text
发起方: <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 和日志。按照这一顺序能够避免把交易未找到、尚未打包和执行失败混为一谈。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 JSON-RPC 查询交易详情

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

登录哪都通