Monad JSON-RPC 方法：以太坊兼容接口

Monad 的以太坊兼容 JSON-RPC 接口

Monad 被设计为 EVM 兼容区块链，这意味着它提供的 JSON-RPC 接口与 以太坊 JSON-RPC 规范 中定义的方法命名空间一致。对开发者而言，这是起点：你从以太坊工具链中已经熟悉的方法词汇——eth_、net_、web3_，以及在启用时的 debug_/trace_*——就是你在 Monad 端点上使用的同一套词汇。请求信封是标准的 JSON-RPC 2.0 对象，包含 jsonrpc、method、params 和 id，如 JSON-RPC 2.0 规范 所定义。

这种兼容性降低了入门门槛：现有的以太坊库、钱包集成和索引器通常只需极少改动即可指向 Monad RPC 端点。OnFinality 提供遵循这一兼容接口的 Monad RPC 端点，而 Monad RPC 端点与指南 涵盖了端点发现和连接基础。然而，兼容性只是起点，并不保证每个方法和每个提供商的行为完全一致。

• 标准命名空间：eth_、net_、web3_* 是 EVM 兼容链的基线。
• 可选命名空间：debug_* 和 trace_* 由于资源消耗大，通常在共享或公共端点上被禁用。
• 请求信封：{ "jsonrpc": "2.0", "method": "...", "params": [...], "id": 1 }。
• 响应信封：{ "jsonrpc": "2.0", "result": ..., "id": 1 } 或 { "jsonrpc": "2.0", "error": { "code": ..., "message": ... }, "id": 1 }。

枚举 Monad 端点支持的方法

不要假设每个以太坊方法在给定的 Monad 端点上都已启用。不同提供商和节点版本暴露的命名空间各不相同，某些方法可能因性能、安全或运维原因被禁用。了解特定端点支持哪些方法的唯一可靠方式，是用一小组安全的方法进行探测并记录响应。不支持的方法通常会返回 JSON-RPC 错误，代码为 -32601（方法未找到）或提供商特定的“不支持”消息。

探测时，先从无副作用的只读方法开始：eth_chainId、eth_blockNumber、web3_clientVersion，以及小范围的 eth_getLogs 调用。在初始能力发现阶段，避免发送交易或调用 debug/trace 方法。记录每个方法的结果和原始错误，以便区分方法不存在、方法存在但暂时失败，以及方法需要你未正确提供的参数这三种情况。

• 先用只读方法探测：eth_chainId、eth_blockNumber、web3_clientVersion。
• 记录不支持方法的精确错误代码和消息。
• 区分 -32601（方法未找到）、-32602（参数无效）和 -32603（内部错误）。
• 在提供商或节点升级后重新探测；能力集合可能发生变化。

Monad 开发者的核心方法组

你在 Monad 上最常使用的方法可分为五个功能组。链和节点身份方法——eth_chainId、net_version、web3_clientVersion——告诉你连接的是哪个网络以及哪个客户端软件在服务该端点。区块和交易读取方法——eth_blockNumber、eth_getBlockByNumber、eth_getTransactionByHash、eth_getTransactionReceipt——让你检查链状态和交易结果。状态和模拟方法——eth_call、eth_estimateGas、eth_getBalance、eth_getCode、eth_getStorageAt——支持合约交互和预检。

日志方法，主要是 eth_getLogs，对事件索引至关重要，但存在因提供商而异的区块范围限制；关于处理无效范围错误，请参阅专门的 Monad eth_getLogs 区块范围限制 指南。费用和优先费数据方法——eth_gasPrice、eth_feeHistory、eth_maxPriorityFeePerGas——帮助你构建交易，但在 Monad 上必须考虑双重 Gas 定价，这在 Monad 双重 Gas 定价估算 一文中有详细说明。

• 链/节点身份：eth_chainId、net_version、web3_clientVersion。
• 区块和交易读取：eth_blockNumber、eth_getBlockByNumber、eth_getTransactionByHash、eth_getTransactionReceipt。
• 状态和模拟：eth_call、eth_estimateGas、eth_getBalance、eth_getCode、eth_getStorageAt。
• 日志：eth_getLogs（注意区块范围上限）。
• 费用和优先费：eth_gasPrice、eth_feeHistory、eth_maxPriorityFeePerGas。

Monad 特有的行为差异

在梳理 JSON-RPC 接口时，有两个 Monad 特有的行为值得注意。首先，Monad 使用异步执行，这意味着已提交的交易可能不会像以太坊同步直觉所暗示的那样立即有收据可用。交易哈希可能在收据状态最终确定之前就已知道；开发者应轮询 eth_getTransactionReceipt 并优雅处理 null 结果。Monad 交易生命周期与收据状态 一文对此有详细说明。

其次，Monad 采用双重 Gas 定价，这意味着仅凭 eth_gasPrice 可能会误导你对交易实际成本的判断。如果你的应用仅依赖 eth_gasPrice 进行费用估算，可能会低估或高估费用。在可用的情况下使用 eth_feeHistory 和 eth_maxPriorityFeePerGas，并查阅双重 Gas 定价指南以获得更准确的方法。这些差异不是方法可用性问题——方法确实存在——但它们会影响你如何解读结果。

• 异步执行：提交后收据可能立即为 null；使用退避轮询。
• 双重 Gas 定价：eth_gasPrice 只是单一数据点；结合 eth_feeHistory 和 eth_maxPriorityFeePerGas 使用。
• 收据状态语义可能与同步 EVM 链不同；请对照 Monad 文档验证。
• 始终将观察到的行为与当前 Monad 文档 进行核对。

可运行的 Node.js 能力探测脚本

以下 Node.js 脚本探测 Monad 端点的一小组方法，并为每个方法打印 OK 或 NOT-SUPPORTED，以及适用时的原始错误。它仅使用内置的 fetch API（Node.js 18+），无需外部依赖。将 RPC_URL 常量替换为你的 Monad 端点 URL。脚本调用 eth_chainId、eth_blockNumber、eth_getBlockByNumber、eth_getBalance、小范围区块的 eth_getLogs，以及 web3_clientVersion。

针对你自己的端点运行此脚本以构建能力矩阵。输出将显示哪些方法返回结果、哪些返回错误。对于 eth_getLogs，使用最近几个区块的小范围，以避免触及范围限制；如果端点拒绝该范围，这本身就是关于提供商限制的有用信息。

const RPC_URL = 'https://your-monad-endpoint.example';

async function call(method, params = []) {
  const body = { jsonrpc: '2.0', method, params, id: 1 };
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (json.error) {
    return { ok: false, error: json.error };
  }
  return { ok: true, result: json.result };
}

async function probe() {
  const latestHex = (await call('eth_blockNumber')).result;
  const latest = parseInt(latestHex, 16);
  const fromBlock = '0x' + Math.max(0, latest - 5).toString(16);
  const toBlock = '0x' + latest.toString(16);

  const probes = [
    ['eth_chainId', []],
    ['eth_blockNumber', []],
    ['eth_getBlockByNumber', [latestHex, false]],
    ['eth_getBalance', ['0x0000000000000000000000000000000000000000', 'latest']],
    ['eth_getLogs', [{ fromBlock, toBlock }]],
    ['web3_clientVersion', []],
  ];

  for (const [method, params] of probes) {
    const out = await call(method, params);
    if (out.ok) {
      console.log(`OK  ${method} ->`, JSON.stringify(out.result).slice(0, 120));
    } else {
      console.log(`NOT-SUPPORTED  ${method} ->`, JSON.stringify(out.error));
    }
  }
}

probe().catch(console.error);

针对你的端点的可复现结果表

使用下表记录你的探测结果。针对你在 Monad 端点上测试的每个方法填写一行。“Supported?”列应填写 Yes、No 或 Error。“Sample response field”列应捕获结果中的代表性字段（例如 chainId 值或区块号）。“Notes”列用于记录提供商特定的观察结果，例如速率限制或必需参数。

此表有意留空，以便你针对自己的端点进行测量，而不是依赖第三方声明。在更换提供商或节点升级后重新运行探测，并将该表与你的集成测试一起保存。如果某个方法不受支持，请记录确切的错误代码和消息，以便在应用中优雅处理。

• Method：JSON-RPC 方法名，例如 eth_chainId。
• Namespace：eth、net、web3、debug、trace。
• Supported?：Yes / No / Error。
• Sample response field：结果中的关键字段，例如 result.chainId。
• Notes：提供商特定行为、速率限制、必需参数。

解读方法未找到和不支持错误

当 Monad 端点不支持某个方法时，JSON-RPC 响应将包含错误对象。方法不存在的标准错误代码是 -32601（方法未找到），如 JSON-RPC 2.0 规范 所定义。某些提供商可能返回不同的代码或自定义消息，例如“unsupported method”或“method disabled”。你应将任何错误响应视为该方法在该端点上不可用的信号，但要区分方法确实不存在与因速率限制或内部错误而暂时不可用。

如果收到 -32601，不要反复重试同一方法；而应回退到替代方法或端点。如果收到 -32602（参数无效），检查参数格式——例如，区块号必须是十六进制字符串或标签 'latest'、'earliest'、'pending'。如果收到 -32603（内部错误），方法可能存在但节点遇到问题；使用退避重试并考虑切换端点。

• -32601：方法未找到或被禁用；不要重试，使用回退方案。
• -32602：参数无效；验证十六进制编码和参数数量。
• -32603：内部错误；使用退避重试，考虑切换端点。
• 提供商特定代码：查阅提供商文档了解自定义错误代码。

Debug 和 Trace 命名空间的可用性

debug_* 和 trace_* 命名空间提供强大的内省方法，例如 debug_traceTransaction 和 trace_block。在共享或公共 Monad 端点上，这些命名空间通常被禁用，因为它们资源消耗大，可能降低其他用户的性能。如果你的应用需要追踪，可能需要专用节点或明确提供这些命名空间的提供商。不要因为某个方法存在于以太坊 JSON-RPC 规范中，就假设它在你的 Monad 端点上已启用。

要检查可用性，可用已知交易哈希探测一个安全的 debug 方法，例如 debug_traceTransaction，或者直接尝试 trace_ 调用并检查错误。如果端点返回 -32601，则该命名空间未暴露。对于生产环境的追踪需求，考虑运行自己的 Monad 节点或使用记录支持 trace 的提供商。OnFinality 的 API 服务 和 RPC 定价 页面描述了可用的服务层级，但始终应通过直接探测验证命名空间支持。

• debug_* 和 trace_* 通常在共享端点上被禁用。
• 使用已知交易哈希探测 debug_traceTransaction 以测试。
• 对于追踪，考虑专用节点或记录支持 trace 的提供商。
• 直接验证命名空间支持；不要依赖假设。

EVM 兼容性的局限与权衡

EVM 兼容并不保证方法可用性或语义完全一致。Monad 可能实现相同的方法名，但具有不同的性能特征、区块范围限制或错误行为。例如，Monad 上的 eth_getLogs 可能具有比以太坊主网更低的区块范围上限，而 eth_gasPrice 可能无法准确反映双重 Gas 定价。这些差异不是缺陷；它们是网络及其提供商的属性。

另一个权衡是，某些以太坊方法在 Monad 上可能被弃用或替换，或者可能引入不属于标准以太坊接口的新方法。始终将你的假设与当前 Monad 文档 和提供商的文档进行核对。如果你正在迁移现有的以太坊应用，请针对你的 Monad 端点运行能力探测脚本，并将结果与你的以太坊端点进行比较，以便尽早发现差距。

• 方法可用性因提供商和节点版本而异。
• eth_getLogs 的区块范围限制可能与以太坊不同。
• 双重 Gas 定价影响费用相关方法。
• 可能存在标准以太坊接口之外的新方法或已弃用方法。
• 始终对照当前 Monad 文档进行验证。

排查常见的 Monad JSON-RPC 问题

如果你的应用无法连接或收到意外错误，首先验证端点 URL 和网络。使用 eth_chainId 确认你在预期的 Monad 网络上。如果 eth_chainId 返回你不认识的值，你可能指向了测试网或其他链。接下来，检查请求信封是否为有效的 JSON-RPC 2.0：jsonrpc 字段必须恰好为 '2.0'，id 应为数字或字符串。格式错误的信封可能产生解析错误（-32700）或无效请求（-32600）。

如果特定方法失败，用最小化的 curl 命令隔离它。例如，curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' YOUR_RPC_URL。如果这能工作但你的应用失败，问题很可能在客户端库或参数格式。如果这也失败，该方法可能不受支持或端点暂时不可用。对于日志相关错误，请参阅 Monad eth_getLogs 区块范围限制 指南。

• 使用 eth_chainId 验证端点 URL 和网络。
• 验证 JSON-RPC 2.0 信封：jsonrpc、method、params、id。
• 用最小化的 curl 命令隔离失败的方法。
• 检查 eth_getLogs 的区块范围限制。
• 查阅提供商文档了解自定义错误代码。

Monad JSON-RPC 集成的后续步骤

在探测端点并填写结果表后，你就拥有了可用于设计集成的能力矩阵。关于端点发现和提供商选择，请参阅 Monad RPC 端点（RPC Assistant） 页面。关于 Monad RPC 使用的更广泛概述，Monad RPC 端点与指南 涵盖了连接设置和常见模式。如果你需要准确估算费用，请查看 Monad 双重 Gas 定价估算 一文。

对于生产部署，考虑使用提供你所需命名空间并记录其区块范围限制的提供商。OnFinality 的 Monad RPC 端点 专为 EVM 兼容工作负载设计，而 OnFinality Learn 中心 包含关于 Monad 特定行为的更多指南。在提供商变更或节点升级后始终重新运行能力探测，并将结果表作为集成测试套件的一部分保持更新。

• 使用能力矩阵选择回退方法和端点。
• 记录 eth_getLogs 的区块范围限制和错误处理。
• 在提供商或节点升级后重新探测。
• 查看关于 Gas、收据和日志的 Monad 特定指南。
• 对于 debug/trace 命名空间，考虑使用专用节点。