进阶 docs.nethermind.io 2026-11-13 08:27:03 · 6 阅读
第10章 与 Nethermind 交互
版本:2.2.0JSON-RPC server与 Nethermind 交互需要使用 JSON-RPC 2.0 协议。Nethermind 支持通过 HTTP、WebSocket 和 IPC socket 三种传输方式提供 JSON-RPC 服务,每种传输方式都需要通过相应的配置项启用,具体如下。更多细节请参阅 JSON-RPC configuration options。
JSON-RPC API 方法按用途分为若干类别(命名空间)。所有 API 方法名都由命名空间和方法名组成,例如 eth_call 方法属于 eth 命名空间。所有支持的命名空间和方法请见侧边栏。
note并非所有 JSON-RPC 命名空间都默认启用,需要通过 JsonRpc.EnabledModules 命令行选项显式开启,否则会返回错误码 -32600。已启用的命名空间可以在 -c, --config 命令行选项指定的配置文件中查看。
Transports
tip传输方式的选择取决于具体使用场景。
HTTP 是一种常见且幂等的传输方式,请求之间会关闭连接,因此请求数量较少时整体开销更低。
WebSocket 提供持续开放的通道,支持事件订阅和流式传输,适合处理大量请求,且每条消息的额外开销很小。
IPC 通常最安全,因为它仅限本地交互,无法暴露给外部流量,同时也可用于事件订阅。
HTTP
HTTP 是 Nethermind 使用最广泛的传输方式。要启用 HTTP 服务器,将 JsonRpc.Enabled 配置项设为 true。默认情况下,Nethermind 使用本地回环地址(127.0.0.1 或 localhost)和 8545 端口。如需更改主机或端口,分别设置 JsonRpc.Host 和 JsonRpc.Port 配置项即可。
WebSocket
WebSocket 服务器的配置方式与 HTTP 服务器相同。启用 HTTP 服务器时会自动启用 WebSocket 服务器,且共用相同的主机和端口。如需禁用 WebSocket 服务器,将 Init.WebSocketsEnabled 配置项设为 false。如需使用其他端口,设置 JsonRpc.WebSocketsPort 配置项。
IPC socket
Nethermind 使用基于 Unix domain socket 的 IPC。要启用 IPC 服务器,使用 JsonRpc.IpcUnixDomainSocketPath 配置项。例如:
--jsonrpc-ipcunixdomainsocketpath path/to/ipc
如果指定的 path/to/ipc 不存在,Nethermind 会自动创建。 Engine API Engine API 是一组 RPC 方法,用于执行客户端和共识客户端之间的通信。客户端在需要交换信息时会自动调用这些方法。Engine API 默认自动启用,并非设计给用户直接调用。 默认情况下,Engine API 使用本地回环地址(127.0.0.1 或 localhost)和 8551 端口。如需使用其他主机或端口,可分别设置 JsonRpc.EngineHost 和 JsonRpc.EnginePort 配置项。例如,当执行客户端和共识客户端不在同一台机器上时,就需要这样配置。 重要提示:指定 JsonRpc.EngineHost 时,必须同时指定 JsonRpc.EnginePort。 Engine API 使用 JWT 认证,需要提供 JWT 密钥。默认情况下,Nethermind 会在其根目录下的 keystore/jwt-secret 路径生成密钥。如需使用其他路径,请指定 JsonRpc.JwtSecretFile 配置项。 请求 info 按照 JSON-RPC 2.0 规范,Nethermind 支持批量请求。具体用法取决于所使用的 JSON-RPC 客户端。 与 JSON-RPC 交互有多种方式可选:从 curl、Postman 等通用工具直接发送原始请求,到 Cast 这类定制化工具,再到 Ethers.js、Viem 等专用库,不一而足。 下面的示例展示了如何用其中几种方式发送 JSON-RPC 请求。 CastEthers.jsViem以下示例使用 eth_getBalance 方法查询指定账户的余额:# 假设 Nethermind 在本地运行,使用默认端口 8545
cast rpc --rpc-url http://localhost:8545 eth_getBalance 0x00000000219ab540356cbb839cbe05303d7705fa latest
# 也可以使用专用的 balance 命令。
# 注意,其输出格式与上面的命令不同。
cast balance 0x00000000219ab540356cbb839cbe05303d7705fa --ether --rpc-url http://localhost:8545
类似地,我们可以使用 eth_getBlockByNumber 方法获取指定区块的数据(包括交易):# 假设 Nethermind 在本地运行,使用默认端口 8545
cast rpc --rpc-url http://localhost:8545 eth_getBlockByNumber latest true
# 也可以使用专用的 block 命令
cast block latest --rpc-url http://localhost:8545
更多信息请参考 Cast 文档。注意:示例基于 Ethers.js v6。以下示例使用 eth_getBalance 方法查询指定账户的余额: import { JsonRpcProvider, formatEther } from 'ethers';
// 假设 Nethermind 在本地运行,使用默认端口 8545
const provider = new JsonRpcProvider('http://localhost:8545');
// 使用低层 API 发送请求
let balance = await provider.send('eth_getBalance', [
'0x00000000219ab540356cbb839cbe05303d7705fa',
'latest'
]);
console.log('Balance:', formatEther(balance));
// 使用高层 API 发送请求。
// 注意返回类型可能与低层 API 不同。
balance = await provider.getBalance('0x00000000219ab540356cbb839cbe05303d7705fa', 'latest');
console.log('Balance:', formatEther(balance));
类似地,我们可以使用 eth_getBlockBy 方法获取指定的区块数据(包括交易): import { JsonRpcProvider } from 'ethers';
// 假设 Nethermind 在本地运行,使用默认端口 8545
const provider = new JsonRpcProvider('http://localhost:8545');
// 使用低层 API 发送请求
let block = await provider.send('eth_getBlockByNumber', ['latest', true]);
console.log('Block:', block);
// 使用高层 API 发送请求。
// 注意返回类型可能与低层 API 不同。
// 并非所有 JSON-RPC 方法都有对应的高层 API。
block = await provider.getBlock('latest', true);
console.log('Block:', block);
更多信息请参考 Ethers.js 文档。注意:示例基于 Viem v2。以下示例使用 eth_getBalance 方法查询指定账户的余额: import { createPublicClient, http, formatEther, hexToNumber } from 'viem';
import { localhost } from 'viem/chains';
// 假设 Nethermind 在本地运行,使用默认端口 8545
const client = createPublicClient({
chain: localhost,
transport: http('http://localhost:8545')
});
// 使用低层 API 发送请求
let balance = await client.request({
method: 'eth_getBalance',
params: ['0x00000000219ab540356cbb839cbe05303d7705fa', 'latest']
});
console.log('Balance:', formatEther(hexToNumber(balance)));
// 使用高层 API 发送请求。
// 注意返回类型可能与底层 API 不同。
// 并非所有 JSON-RPC 方法都有对应的高层 API。
balance = await client.getBalance({
address: '0x00000000219ab540356cbb839cbe05303d7705fa',
blockTag: 'latest'
});
console.log('Balance:', formatEther(balance));
同样,我们可以用 eth_getBlockByNumber 方法获取指定区块的数据,包括其中的交易:import { createPublicClient, http } from 'viem';
import { localhost } from 'viem/chains';
// 假设 Nethermind 在本地以默认端口 8545 运行
const client = createPublicClient({
chain: localhost,
transport: http('http://localhost:8545')
});
// 使用底层 API 发送请求
let block = await client.request({
method: 'eth_getBlockByNumber',
params: ['latest', true]
});
console.log('Block:', block);
// 使用高层 API 发送请求
block = await client.getBlock({
blockTag: 'latest',
includeTransactions: true
});
console.log('Block:', block);
更多信息请参阅 Viem 文档。 流式响应 有些方法的响应可能远大于发起请求本身:比如区块 trace,或者大范围的日志查询。Nethermind 在生成响应的过程中就把它们写入传输层,而不是先在内存里把整个响应构建好。这样,单个请求的内存开销取决于流本身,而不是结果的大小,而且调用方在节点完成全部工作之前就能收到最初的字节。 Traces JsonRpc.EnableTracingStreamMode 会在交易执行过程中以流式方式返回 debug_trace* 和 trace_* 的响应。该选项默认开启。debug_trace* 调用可以通过 streamMode 选项针对单个请求覆盖这一设置,例如: cast rpc --rpc-url http://localhost:8545 debug_traceBlockByNumber latest '{"tracer":"callTracer","streamMode":false}'
流式输出可以控制 trace 的内存占用,并缩短首字节的等待时间。但它本身不会缩短生成 trace 的总耗时,因为 tracing 需要重新执行区块。 在启用了逐交易 changeset 索引的 archive 节点上,对已索引区块做 trace 时不需要重放目标位置之前的交易;整块 trace 会并发执行其中的交易,并按完成顺序、以区块顺序输出结果。采用流式输出时,数据会从第一个完成的交易开始返回,而不是从区块中的第一个交易开始。而带 JavaScript tracer 的 debug_trace* 调用则保持顺序重放。 日志 JsonRpc.EnableLogsStreamMode 可以在匹配到日志时就流式返回 eth_getLogs 和 eth_getFilterLogs 的响应。该选项默认关闭,因为它会改变查询结果过大时调用方收到的内容:非流式模式下会缓冲完整结果并返回超限错误,而流式响应会在达到 JsonRpc.MaxLogsPerResponse 或 JsonRpc.MaxLogsResponseBodySize 时直接截断结束。经过身份验证的请求不受这些限制约束。 支持的 JSON-RPC 方法完整列表可在 JSON-RPC namespaces 一节中查看。
如果指定的 path/to/ipc 不存在,Nethermind 会自动创建。 Engine API Engine API 是一组 RPC 方法,用于执行客户端和共识客户端之间的通信。客户端在需要交换信息时会自动调用这些方法。Engine API 默认自动启用,并非设计给用户直接调用。 默认情况下,Engine API 使用本地回环地址(127.0.0.1 或 localhost)和 8551 端口。如需使用其他主机或端口,可分别设置 JsonRpc.EngineHost 和 JsonRpc.EnginePort 配置项。例如,当执行客户端和共识客户端不在同一台机器上时,就需要这样配置。 重要提示:指定 JsonRpc.EngineHost 时,必须同时指定 JsonRpc.EnginePort。 Engine API 使用 JWT 认证,需要提供 JWT 密钥。默认情况下,Nethermind 会在其根目录下的 keystore/jwt-secret 路径生成密钥。如需使用其他路径,请指定 JsonRpc.JwtSecretFile 配置项。 请求 info 按照 JSON-RPC 2.0 规范,Nethermind 支持批量请求。具体用法取决于所使用的 JSON-RPC 客户端。 与 JSON-RPC 交互有多种方式可选:从 curl、Postman 等通用工具直接发送原始请求,到 Cast 这类定制化工具,再到 Ethers.js、Viem 等专用库,不一而足。 下面的示例展示了如何用其中几种方式发送 JSON-RPC 请求。 CastEthers.jsViem以下示例使用 eth_getBalance 方法查询指定账户的余额:# 假设 Nethermind 在本地运行,使用默认端口 8545
cast rpc --rpc-url http://localhost:8545 eth_getBalance 0x00000000219ab540356cbb839cbe05303d7705fa latest
# 也可以使用专用的 balance 命令。
# 注意,其输出格式与上面的命令不同。
cast balance 0x00000000219ab540356cbb839cbe05303d7705fa --ether --rpc-url http://localhost:8545
类似地,我们可以使用 eth_getBlockByNumber 方法获取指定区块的数据(包括交易):# 假设 Nethermind 在本地运行,使用默认端口 8545
cast rpc --rpc-url http://localhost:8545 eth_getBlockByNumber latest true
# 也可以使用专用的 block 命令
cast block latest --rpc-url http://localhost:8545
更多信息请参考 Cast 文档。注意:示例基于 Ethers.js v6。以下示例使用 eth_getBalance 方法查询指定账户的余额: import { JsonRpcProvider, formatEther } from 'ethers';
// 假设 Nethermind 在本地运行,使用默认端口 8545
const provider = new JsonRpcProvider('http://localhost:8545');
// 使用低层 API 发送请求
let balance = await provider.send('eth_getBalance', [
'0x00000000219ab540356cbb839cbe05303d7705fa',
'latest'
]);
console.log('Balance:', formatEther(balance));
// 使用高层 API 发送请求。
// 注意返回类型可能与低层 API 不同。
balance = await provider.getBalance('0x00000000219ab540356cbb839cbe05303d7705fa', 'latest');
console.log('Balance:', formatEther(balance));
类似地,我们可以使用 eth_getBlockBy 方法获取指定的区块数据(包括交易): import { JsonRpcProvider } from 'ethers';
// 假设 Nethermind 在本地运行,使用默认端口 8545
const provider = new JsonRpcProvider('http://localhost:8545');
// 使用低层 API 发送请求
let block = await provider.send('eth_getBlockByNumber', ['latest', true]);
console.log('Block:', block);
// 使用高层 API 发送请求。
// 注意返回类型可能与低层 API 不同。
// 并非所有 JSON-RPC 方法都有对应的高层 API。
block = await provider.getBlock('latest', true);
console.log('Block:', block);
更多信息请参考 Ethers.js 文档。注意:示例基于 Viem v2。以下示例使用 eth_getBalance 方法查询指定账户的余额: import { createPublicClient, http, formatEther, hexToNumber } from 'viem';
import { localhost } from 'viem/chains';
// 假设 Nethermind 在本地运行,使用默认端口 8545
const client = createPublicClient({
chain: localhost,
transport: http('http://localhost:8545')
});
// 使用低层 API 发送请求
let balance = await client.request({
method: 'eth_getBalance',
params: ['0x00000000219ab540356cbb839cbe05303d7705fa', 'latest']
});
console.log('Balance:', formatEther(hexToNumber(balance)));
// 使用高层 API 发送请求。
// 注意返回类型可能与底层 API 不同。
// 并非所有 JSON-RPC 方法都有对应的高层 API。
balance = await client.getBalance({
address: '0x00000000219ab540356cbb839cbe05303d7705fa',
blockTag: 'latest'
});
console.log('Balance:', formatEther(balance));
同样,我们可以用 eth_getBlockByNumber 方法获取指定区块的数据,包括其中的交易:import { createPublicClient, http } from 'viem';
import { localhost } from 'viem/chains';
// 假设 Nethermind 在本地以默认端口 8545 运行
const client = createPublicClient({
chain: localhost,
transport: http('http://localhost:8545')
});
// 使用底层 API 发送请求
let block = await client.request({
method: 'eth_getBlockByNumber',
params: ['latest', true]
});
console.log('Block:', block);
// 使用高层 API 发送请求
block = await client.getBlock({
blockTag: 'latest',
includeTransactions: true
});
console.log('Block:', block);
更多信息请参阅 Viem 文档。 流式响应 有些方法的响应可能远大于发起请求本身:比如区块 trace,或者大范围的日志查询。Nethermind 在生成响应的过程中就把它们写入传输层,而不是先在内存里把整个响应构建好。这样,单个请求的内存开销取决于流本身,而不是结果的大小,而且调用方在节点完成全部工作之前就能收到最初的字节。 Traces JsonRpc.EnableTracingStreamMode 会在交易执行过程中以流式方式返回 debug_trace* 和 trace_* 的响应。该选项默认开启。debug_trace* 调用可以通过 streamMode 选项针对单个请求覆盖这一设置,例如: cast rpc --rpc-url http://localhost:8545 debug_traceBlockByNumber latest '{"tracer":"callTracer","streamMode":false}'
流式输出可以控制 trace 的内存占用,并缩短首字节的等待时间。但它本身不会缩短生成 trace 的总耗时,因为 tracing 需要重新执行区块。 在启用了逐交易 changeset 索引的 archive 节点上,对已索引区块做 trace 时不需要重放目标位置之前的交易;整块 trace 会并发执行其中的交易,并按完成顺序、以区块顺序输出结果。采用流式输出时,数据会从第一个完成的交易开始返回,而不是从区块中的第一个交易开始。而带 JavaScript tracer 的 debug_trace* 调用则保持顺序重放。 日志 JsonRpc.EnableLogsStreamMode 可以在匹配到日志时就流式返回 eth_getLogs 和 eth_getFilterLogs 的响应。该选项默认关闭,因为它会改变查询结果过大时调用方收到的内容:非流式模式下会缓冲完整结果并返回超限错误,而流式响应会在达到 JsonRpc.MaxLogsPerResponse 或 JsonRpc.MaxLogsResponseBodySize 时直接截断结束。经过身份验证的请求不受这些限制约束。 支持的 JSON-RPC 方法完整列表可在 JSON-RPC namespaces 一节中查看。