智能合约与以太坊 / 系统课时
判断交易回执与确认状态
判断交易回执与确认状态
拿到 Ethereum 交易哈希后,不能仅凭钱包显示“已发送”就判定链上执行成功。本课使用 JSON-RPC 查询交易与回执,核对执行状态、Gas 消耗、区块归属和确认进度,并识别待处理、回滚及链重组带来的状态变化。
学习目标
- 根据交易对象和回执区分待处理、未查到、执行成功与执行回滚。
- 从回执计算实际执行 Gas 费用,并核验交易所在区块。
- 计算确认数,区分最新区块确认与
safe、finalized最终性。
先确认交易是否获得回执
交易哈希是 32 字节标识,JSON-RPC 中通常写成以 0x 开头的 66 字符十六进制字符串。用同一个 RPC 节点依次检查 eth_getTransactionReceipt 和 eth_getTransactionByHash,不要把“没有回执”直接判断为失败。
| 查询结果 | 合理判断 | 后续动作 |
|---|---|---|
回执为 null,交易对象的 blockNumber 为 null |
当前节点已看到待处理交易 | 等待打包并重复查询 |
回执为 null,交易对象也为 null |
节点尚未查到;也可能未传播、被丢弃或连错网络 | 核对链、节点及交易哈希 |
回执存在且 status=0x1 |
已被纳入区块,执行成功 | 核验区块及确认数 |
回执存在且 status=0x0 |
已被纳入区块,但执行失败并回滚 | 查询失败原因及费用 |
交易对象已有区块号、回执却暂时查不到时,可能是节点索引或查询时机不同步,先短暂等待并重查。历史上早于 Byzantium 升级的交易回执可能没有 status,不能按现代交易规则强行判断。

读取 Gas、区块和执行字段
transactionHash 标识交易,blockNumber 与 blockHash 指向打包它的区块。gasUsed 是本笔交易实际使用的执行 Gas,不是交易设置的 gas 上限;cumulativeGasUsed 是区块内截至本笔交易的累计值,不能用来计算单笔费用。
普通交易的执行 Gas 费用为 gasUsed × effectiveGasPrice,单位是 wei。例如使用 21,000 Gas、有效价格为 20 gwei,费用为 420,000,000,000,000 wei,即 0.00042 ETH(1 gwei = 10⁹ wei)。Blob 交易还有单独的 blob Gas 费用,不能把上述乘积当作全部手续费。
status=0x0 说明链上执行未成功,但交易已经被纳入区块,执行 Gas 费用仍可能被扣除。回执不直接提供 Solidity 的回滚原因;需要结合合约调用参数、模拟执行或节点调试接口调查。
用 Node.js 查询并核验当前链
准备 Node.js 18 或更新版本及可访问的 Ethereum HTTP JSON-RPC 节点。将以下内容保存为 receipt.mjs,把环境变量 ETH_RPC_URL 设为实际节点地址、TX_HASH 设为真实交易哈希,然后执行 node receipt.mjs。脚本不需要第三方依赖。
const url = process.env.ETH_RPC_URL;
const hash = process.env.TX_HASH;
if (!url || !/^0x[0-9a-fA-F]{64}$/.test(hash ?? "")) {
console.error("请设置 ETH_RPC_URL 和 66 字符的 TX_HASH");
process.exit(1);
}
let id = 0;
async function rpc(method, params = []) {
const response = await fetch(url, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method, params })
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
if (data.error) throw new Error(`${method}: ${data.error.message}`);
return data.result;
}
async function main() {
const [tx, receipt] = await Promise.all([
rpc("eth_getTransactionByHash", [hash]),
rpc("eth_getTransactionReceipt", [hash])
]);
console.log(`交易哈希: ${hash}`);
if (receipt === null) {
const state = !tx ? "当前节点未查到" :
tx.blockNumber === null ? "待处理" : "回执暂不可用,稍后重试";
console.log(`状态: ${state}`);
return;
}
// 回执存在不代表交易仍位于当前规范链。
const [headHex, block] = await Promise.all([
rpc("eth_blockNumber"),
rpc("eth_getBlockByNumber", [receipt.blockNumber, false])
]);
if (!block || block.hash.toLowerCase() !== receipt.blockHash.toLowerCase()) {
console.log("状态: 区块哈希不匹配,可能发生重组,请重新查询");
return;
}
const height = BigInt(receipt.blockNumber);
const head = BigInt(headHex);
const confirmations = head >= height ? head - height + 1n : 0n;
const outcome = receipt.status === "0x1" ? "成功" :
receipt.status === "0x0" ? "回滚" : "未知";
console.log(`区块: ${height},区块哈希: ${receipt.blockHash}`);
console.log(`执行: ${outcome}`);
console.log(`已确认: ${confirmations} 次`);
console.log(`Gas 消耗: ${BigInt(receipt.gasUsed)}`);
// 有效 Gas 价存在时才计算实际执行 Gas 费用。
if (receipt.effectiveGasPrice != null) {
const price = BigInt(receipt.effectiveGasPrice);
console.log(`有效 Gas 价: ${price} wei`);
console.log(`执行 Gas 费: ${BigInt(receipt.gasUsed) * price} wei`);
}
for (const tag of ["safe", "finalized"]) {
try {
const boundary = await rpc("eth_getBlockByNumber", [tag, false]);
const state = !boundary ? "节点未返回" :
height <= BigInt(boundary.number) ? "已达到" : "未达到";
console.log(`${tag}: ${state}`);
} catch {
console.log(`${tag}: 节点不支持或暂不可用`);
}
}
}
main().catch(error => {
console.error(`RPC 查询失败: ${error.message}`);
process.exitCode = 1;
});预期输出(以刚入块、执行成功且节点支持最终性标签的交易为例;<ID>、<HEIGHT> 等代表实际会变化的值):
交易哈希: <ID>
区块: <HEIGHT>,区块哈希: <ID>
执行: 成功
已确认: <CONFIRMATIONS> 次
Gas 消耗: <GAS_USED>
有效 Gas 价: <PRICE_WEI> wei
执行 Gas 费: <FEE_WEI> wei
safe: 未达到
finalized: 未达到如果交易尚未入块,脚本只输出哈希与“待处理”或“当前节点未查到”,不会编造区块号。执行回滚时则显示“执行: 回滚”;Gas 消耗和区块确认仍可正常读取。
用确认数与最终性决定业务状态
若当前最新规范链区块高度为 205,交易位于高度 203,则确认数为 205 - 203 + 1 = 3。交易所在区块本身算第 1 次确认;确认数增长只是后续区块继续建立在其上的计数,不等于共识最终确定。
latest 是节点当前规范链头;safe 表示在相应共识假设下较难重组的安全链头;finalized 表示已经达到共识最终性的链头。查询 eth_getBlockByNumber 的 safe 与 finalized 标签后,若交易位于当前规范链中且区块高度不超过对应链头高度,即可分别标记为安全或最终确定。部分 RPC 服务可能不支持这些标签,不能把查询失败解释成“尚未最终确定”。
生产系统可分别保存“已入块且执行成功”“达到所需确认数”“已最终确定”三个标志。轮询期间重新校验交易的 blockHash:若同一高度的规范链区块哈希不同,先撤回先前的临时确认结论,再重新查询回执。付款、入账或解锁权限应根据业务风险选择等待条件,而不是仅依赖 status=0x1。
官方字段说明可查阅 Ethereum JSON-RPC 文档。