以太坊 RPC 方法命名空间：eth、net、web3、debug、trace

为什么以太坊 JSON-RPC 按命名空间组织

以太坊 JSON-RPC 接口并不是一个扁平的方法列表。它按前缀分组，每个前缀都是一个具有不同用途和不同可用性特征的命名空间。以太坊 JSON-RPC 规范以这种方式分组呈现完整方法列表，而 JSON-RPC 2.0 规范定义了所有命名空间共享的请求和错误信封。

命名空间的存在是因为这些方法具有不同的信任和成本特征。读取余额成本低且可以安全地在共享端点上暴露。追踪交易的每个内部调用成本高昂，可能泄露节点内部信息，并且通常默认禁用。按前缀分组让节点运营商可以用一个标志启用或禁用整个能力族，并让客户端在发送请求之前推断端点能做什么。

要更广泛地了解网络本身，请参阅以太坊网络页面。下面的命名空间映射是建立在其之上的实用层：它告诉你一个方法属于哪个族以及它的用途。

• eth_ — 链状态、区块、交易、调用、日志、费用：主力。
• net_ — 网络和节点信息。
• web3_ — 客户端版本和哈希工具。
• debug_ — 节点/客户端调试，包括一些交易追踪。
• trace_ — Parity/OpenEthereum 风格的调用和区块追踪。
• txpool_ — 待处理交易检查。

eth_ 命名空间：链状态、区块、交易和费用

eth_ 命名空间是你几乎每个应用级任务都会用到的。它涵盖账户余额、区块检索、交易提交和查询、合约调用、日志和费用估算。如果你在构建钱包、仪表板或合约交互流程，你会经常使用它。

在 eth_ 内部选择方法主要取决于你要问的问题。余额读取是 eth_getBalance。不发送交易的合约调用只读模拟是 eth_call。待处理交易查询使用 eth_getTransactionByHash 并传入 null 区块标签。区块检索有自己的系列，在以太坊区块检索方法文章中介绍。

eth_ 命名空间在托管端点上几乎总是启用的，因为它是基线能力。这并不意味着每个方法都是免费或无限制的；费用历史和日志查询可能比简单的余额读取更重，提供商可能以不同方式计量它们。RPC 定价页面描述了计量通常如何构建。

• 读取余额 → eth_getBalance。
• 不发送交易模拟调用 → eth_call。
• 检查待处理交易 → eth_getTransactionByHash 并传入 null 区块标签。
• 估算费用 → eth_feeHistory 或 eth_gasPrice。
• 查询日志 → eth_getLogs（注意区块范围）。

net_ 和 web3_ 命名空间：网络和客户端元数据

net_ 和 web3_ 是小命名空间，但它们对诊断和确认你实际在与哪个端点通信很有用。net_version 返回网络 ID 字符串，net_peerCount 返回连接的节点数量。web3_clientVersion 返回客户端名称和版本字符串。

这些方法几乎总是启用的，因为它们成本低且不暴露敏感状态。当你调试连接时，它们是首先要调用的：如果 net_version 返回错误的网络，说明你指向了错误的端点。以太坊节点身份方法文章更深入地介绍了 eth_chainId、web3_clientVersion 及相关身份调用。

一个微妙之处：net_version 返回网络 ID，它并不总是与 eth_chainId 返回的链 ID 相同。在大多数网络上它们匹配，但它们是不同的字段，在代码中不应视为可互换。

• net_version — 网络 ID 字符串。
• net_peerCount — 连接的节点数量。
• net_listening — 节点是否接受连接。
• web3_clientVersion — 客户端名称和版本。
• web3_sha3 — 输入数据的 Keccak-256 哈希。

debug_ 命名空间：节点调试和交易追踪

debug_ 命名空间是节点和客户端调试所在之处。它包括检查节点内部状态的方法，在某些客户端上还包括追踪交易执行。debug_traceTransaction 返回单个交易的追踪，debug_traceCall 追踪调用而不发送它。这些对于调试失败交易和理解内部价值流动非常强大。

问题在于可用性。debug_ 方法在共享和托管端点上通常被禁用，因为它们成本高昂且可能泄露内部信息。Geth JSON-RPC 文档描述了如何启用命名空间，并指出 debug、trace 和 admin 组通常受到限制。如果你依赖 debug_，必须先探测它。

以太坊交易追踪：trace 和 debug文章更深入地介绍了追踪方法本身。本参考侧重于它们在命名空间映射中的位置以及如何检查它们是否可用。

• debug_traceTransaction — 追踪单个交易。
• debug_traceCall — 追踪调用而不发送它。
• debug_traceBlockByNumber — 追踪区块中的所有交易。
• 可用性：在共享端点上通常被禁用；使用前先探测。
• 成本：昂贵；可能以不同方式计量或限速。

trace_ 命名空间：Parity/OpenEthereum 风格追踪

trace_ 命名空间起源于 Parity/OpenEthereum，提供调用和区块追踪。trace_block 返回区块中所有交易的追踪，trace_transaction 返回单个交易的追踪，trace_call 追踪调用。这些方法被分析和内部转账工具广泛使用，因为它们暴露了 eth_getLogs 不提供的内部价值转移。

重要的警告是标准化。trace_ 方法不像 eth_ 方法那样在客户端之间标准化。它们的精确参数和返回形状在执行客户端之间可能略有不同，有些客户端只实现子集。这是因提供商和客户端而异的有文档记录的行为，因此你应该针对特定端点验证形状，而不是假设可移植性。

由于 trace_ 成本高昂，它在共享端点上经常被禁用。检查 debug_ 的同一能力探测也应检查 trace_。

• trace_block — 区块中所有交易的追踪。
• trace_transaction — 单个交易的追踪。
• trace_call — 追踪调用。
• trace_replayTransaction — 重放交易并返回追踪。
• 在客户端之间未标准化；按端点验证返回形状。

txpool_ 命名空间：待处理交易检查

txpool_ 命名空间暴露节点的待处理交易池。txpool_status 返回待处理和排队交易的数量，txpool_content 返回完整池内容，txpool_inspect 返回摘要。这对于内存池监控、gas 估算以及理解交易为何卡住很有用。

与 debug_ 和 trace_ 一样，txpool_ 并非普遍启用。它可以在共享端点上被禁用，因为它暴露待处理交易数据，并且在繁忙节点上序列化可能成本高昂。能力探测是正确的第一步。

对于待处理交易，你有两个选择：txpool_content 获取完整池视图，或 eth_getTransactionByHash 并传入 null 区块标签获取特定交易。后者属于 eth_ 命名空间，更可能可用。

• txpool_status — 待处理和排队交易的数量。
• txpool_content — 完整池内容。
• txpool_inspect — 池内容摘要。
• 可用性：在共享端点上通常被禁用。
• 替代方案：eth_getTransactionByHash 并传入 null 区块标签。

为任务选择正确的方法

一旦你了解了命名空间映射，方法选择就更容易了。下表将常见任务映射到解决它们的方法族。如果存在 eth_ 选项，请从它开始，因为它最可能被启用且在客户端之间最具可移植性。

当任务需要追踪内部价值转移时，你会进入 trace_ 或 debug_。当需要待处理交易检查时，你会进入 txpool_ 或使用 eth_ 回退。OnFinality Learn 中心有你最常使用的方法的逐方法深入介绍。

如果你不确定端点是否支持某个命名空间，不要猜测。运行下一节中的能力探测并记录结果。

• 读取余额 → eth_getBalance。
• 不发送交易模拟调用 → eth_call。
• 检查待处理交易 → txpool_content 或 eth_getTransactionByHash 并传入 null 区块标签。
• 追踪内部价值转移 → trace_block 或 debug_traceTransaction。
• 检查网络身份 → net_version 或 eth_chainId。
• 检查客户端版本 → web3_clientVersion。

使用 Node.js 脚本探测命名空间可用性

由于 debug_、trace_ 和 txpool_ 通常被禁用，在你依赖它们之前必须进行能力探测。下面的脚本向端点发送每个命名空间的一个代表性方法，并打印能力矩阵及原始错误。它只使用现代 Node.js 中内置的 fetch，因此无需安装依赖。

在运行之前，将 RPC_URL 环境变量设置为你的端点。脚本故意不解释错误，只打印它们，因为原始错误代码和消息是你需要记录在结果表中的内容。

探测使用 eth_chainId、net_version、web3_clientVersion、txpool_status、debug_traceTransaction 和 trace_block。debug 和 trace 探测使用存根交易哈希和区块号；方法未找到错误意味着命名空间被禁用，而不同的错误可能意味着命名空间已启用但输入无效。

// probe-namespaces.mjs
// Run: RPC_URL=https://your-endpoint node probe-namespaces.mjs

const RPC_URL = process.env.RPC_URL;
if (!RPC_URL) {
  console.error('Set RPC_URL environment variable');
  process.exit(1);
}

const probes = [
  { namespace: 'eth',    method: 'eth_chainId',            params: [] },
  { namespace: 'net',    method: 'net_version',            params: [] },
  { namespace: 'web3',   method: 'web3_clientVersion',     params: [] },
  { namespace: 'txpool', method: 'txpool_status',          params: [] },
  { namespace: 'debug',  method: 'debug_traceTransaction', params: ['0x0000000000000000000000000000000000000000000000000000000000000000', {}] },
  { namespace: 'trace',  method: 'trace_block',            params: ['latest'] }
];

async function call(method, params) {
  const body = { jsonrpc: '2.0', id: 1, method, params };
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(body)
  });
  const json = await res.json();
  return json;
}

const rows = [];
for (const p of probes) {
  try {
    const json = await call(p.method, p.params);
    const enabled = json.error ? 'no' : 'yes';
    const code = json.error ? json.error.code : '';
    const message = json.error ? json.error.message : 'ok';
    rows.push({ namespace: p.namespace, method: p.method, enabled, code, message });
  } catch (err) {
    rows.push({ namespace: p.namespace, method: p.method, enabled: 'error', code: '', message: String(err) });
  }
}

console.table(rows);

记录你自己的命名空间能力矩阵

探测输出只有在你记录它时才有用。为你的端点填写下表，并将其与集成笔记一起保存。错误代码列最重要：-32601 方法未找到通常意味着该端点上命名空间被禁用，而不是方法在规范中不存在。

对你使用的每个端点运行探测，包括故障转移端点。即使在同一提供商内，它们之间的可用性也可能不同，而缺少 trace_ 的故障转移会破坏在你主端点上工作的追踪功能。

不要记录你未测量的基准数字。该表用于能力，而非性能。如果你想要延迟数据，请单独测量并标记为你自己的测量。

• 命名空间 — eth、net、web3、debug、trace、txpool。
• 探测的方法 — 你发送的代表性方法。
• 已启用？ — 是、否或错误。
• 错误代码 — JSON-RPC 错误代码，例如 -32601。
• 备注 — 提供商、客户端、日期和任何注意事项。

错误代码如何因命名空间而异

JSON-RPC 2.0 规范定义了一小组标准错误代码，包括 -32601 表示方法未找到。在实践中，对 debug_ 或 trace_ 方法的 -32601 响应通常意味着该端点上命名空间被禁用，而不是方法在规范中不存在。解码 JSON-RPC 错误对象文章解释了如何一起读取代码、消息和数据字段。

其他代码有不同的含义。-32602 无效参数错误意味着命名空间已启用但你的参数错误。-32000 服务器错误可能表示节点级故障或速率限制，具体取决于提供商。消息和数据字段通常携带提供商特定的细节，因此请原样记录它们。

实用规则：将 -32601 视为能力信号，将 -32602 视为请求形状信号，将 -32000 视为运行时信号。当你调试失败的集成时，这种区分可以节省时间。

• -32601 — 方法未找到；通常意味着命名空间被禁用。
• -32602 — 无效参数；命名空间已启用，参数错误。
• -32000 — 服务器错误；节点级故障或速率限制。
• 始终记录原始错误对象，包括 data。

依赖命名空间的集成的限制和权衡

命名空间可用性因提供商和客户端而异。无法普遍保证 debug_、trace_ 或 txpool_ 会在任何给定端点上启用，同一提供商可能在一个计划上启用而在另一个计划上不启用。设计你的集成，使追踪功能在命名空间不可用时优雅降级。

trace_ 方法在客户端之间未标准化。它们的参数和返回形状在执行客户端之间可能略有不同，因此针对一个客户端工作的代码可能需要针对另一个客户端进行调整。这是因提供商和客户端而异的有文档记录的行为，不是错误。

昂贵的命名空间可能以不同于 eth_ 的方式计量或限速。trace_block 调用可能比余额读取重得多，提供商可能应用单独的限额。查看 RPC 定价和 API 服务页面了解计量通常如何构建，并且永远不要因为余额读取免费就假设追踪调用免费。

• 可用性因提供商、计划和客户端而异。
• trace_ 在客户端之间未标准化。
• 昂贵的命名空间可能以不同方式计量。
• 方法语义在执行客户端之间可能略有不同。
• 为命名空间缺失时的优雅降级而设计。

排查命名空间和方法故障

当方法失败时，第一个问题是命名空间是否启用。对端点运行能力探测并检查错误代码。如果探测对 debug_ 或 trace_ 返回 -32601，则命名空间被禁用，任何参数调整都无法修复。

如果探测返回 -32602，则命名空间已启用但你的参数错误。对照规范检查参数数量和类型。如果返回 -32000，则节点可达但运行时失败；检查消息和数据字段以获取详细信息。

如果探测成功但你的应用仍然失败，请检查你是否将请求发送到同一端点，以及你的 JSON-RPC 信封是否格式正确。以太坊 RPC 节点指南涵盖端点设置和常见连接问题。

• 先探测；不要假设命名空间已启用。
• -32601 → 命名空间禁用；切换端点或功能。
• -32602 → 修复参数形状。
• -32000 → 检查消息和数据以获取运行时细节。
• 验证端点和 JSON-RPC 信封。

命名空间感知集成的后续步骤

首先对你使用的每个端点运行能力探测，并将结果记录在你自己的矩阵中。然后按任务选择方法，在存在合适方法时优先使用 eth_，仅当任务需要且探测确认可用时才回退到 debug_、trace_ 或 txpool_。

要更深入地了解特定方法，OnFinality Learn 中心收集了逐方法文章，包括节点身份、区块检索和交易追踪。以太坊网络页面提供网络级上下文，以太坊 RPC 节点指南涵盖端点设置。

如果你在评估提供商，请检查每个提供商如何记录命名空间可用性和计量。RPC 定价和 API 服务页面描述了 OnFinality 的方法，以太坊交易追踪：trace 和 debug文章更深入地介绍了追踪命名空间。

• 探测每个端点并记录矩阵。
• 在存在 eth_ 方法时优先使用它们。
• 仅在确认可用时使用 debug_、trace_ 和 txpool_。
• 在提供商或计划变更后重新探测。
• 保留原始错误日志以供支持升级。