RPC API

相关源文件

• core/blockchain_reader.go
• core/txindexer.go
• core/txindexer_test.go
• eth/api_backend.go
• eth/downloader/api.go
• eth/filters/api.go
• eth/filters/filter.go
• eth/filters/filter_system.go
• eth/filters/filter_system_test.go
• eth/filters/filter_test.go
• eth/gasestimator/gasestimator.go
• eth/state_accessor.go
• eth/tracers/api.go
• eth/tracers/api_test.go
• ethstats/ethstats.go
• internal/debug/api.go
• internal/ethapi/api.go
• internal/ethapi/api_test.go
• internal/ethapi/backend.go
• internal/ethapi/override/override.go
• internal/ethapi/simulate.go
• internal/ethapi/simulate_test.go
• internal/ethapi/transaction_args.go
• internal/ethapi/transaction_args_test.go
• internal/web3ext/web3ext.go
• rpc/client.go
• rpc/client_test.go
• rpc/context_headers.go
• rpc/doc.go
• rpc/errors.go
• rpc/handler.go
• rpc/http.go
• rpc/http_test.go
• rpc/json.go
• rpc/server.go
• rpc/server_test.go
• rpc/service.go
• rpc/subscription.go
• rpc/subscription_test.go
• rpc/testdata/invalid-badversion.js
• rpc/testservice_test.go
• rpc/types.go
• rpc/types_test.go
• rpc/websocket.go
• rpc/websocket_test.go

RPC API 系统为外部应用程序提供 JSON-RPC 2.0 接口，以便进行交互。该系统支持多种传输机制（HTTP、WebSocket 和 IPC），并公开了用于区块链操作、交易管理、调试和实时事件订阅的各种 API 命名空间。

有关用于共识层通信的 Engine API 的信息，请参阅 Engine API。有关命令行界面详细信息，请参阅 命令行界面。

架构概述

RPC 系统建立在模块化架构之上，将传输机制与 API 服务实现分离开来。核心的 Server 处理传入的请求并将其路由到适当的 API 服务，而各种传输适配器则处理特定于协议的通信。

来源：rpc/server.go46-57 rpc/http.go40-50 internal/ethapi/api.go58-66 eth/api_backend.go47-53

传输机制

HTTP 传输

HTTP 传输通过 HTTP/HTTPS 提供无状态请求-响应通信。它支持单次请求和批量请求，并具有可配置的超时和正文大小限制。

HTTP 处理程序会验证请求，创建包含对等方信息的请求作用域上下文，并通过主 RPC 服务器管道处理单个请求。关键配置包括

• 正文限制：可配置的最大请求大小（默认为 5MB）rpc/http.go36
• 内容类型：支持 application/json、application/json-rpc 和 application/jsonrequest rpc/http.go41
• 超时：可配置的读、写和空闲超时rpc/http.go83-112

来源：rpc/http.go308-336 rpc/http.go340-363 rpc/http.go83-121

WebSocket 传输

WebSocket 传输支持持久连接和实时双向通信，这对于订阅和事件流至关重要。

WebSocket 连接支持

• 订阅：新区块、交易和日志的实时事件通知
• Ping/Pong：自动连接健康监控 rpc/websocket.go38-41
• 并发安全：线程安全的读/写操作 rpc/websocket.go114-147
• 缓冲区管理：可配置的读/写缓冲区和消息大小限制 rpc/websocket.go36-42

来源：rpc/websocket.go190-220 rpc/websocket.go46-100 rpc/websocket.go114-147

IPC 传输

IPC（进程间通信）提供基于本地套接字的通信，用于本地应用程序的安全、高性能访问。虽然 IPC 实现文件未在提供的源代码中显示，但它遵循与 HTTP 和 WebSocket 传输相同的 ServerCodec 接口模式。

来源：rpc/types.go40-49

API 服务组织

RPC 系统将功能组织到不同的 API 服务中，每个服务处理特定的操作域。这些服务使用命名空间注册，这些命名空间成为 JSON-RPC 调用中的方法前缀。

核心 API 服务

命名空间	服务	目的	关键方法
eth	EthereumAPI	核心以太坊操作	eth_getBalance、eth_call、eth_sendTransaction
eth	BlockChainAPI	区块链数据访问	eth_getBlockByNumber、eth_getTransactionReceipt
txpool	TxPoolAPI	交易池管理	txpool_status、txpool_content
eth	FilterAPI	事件过滤和订阅	eth_newFilter、eth_getLogs
debug	DebugAPI	调试和诊断	debug_traceTransaction、debug_traceBlock

来源：internal/ethapi/api.go58-66 internal/ethapi/api.go176-184 internal/ethapi/api.go296-304 eth/filters/api.go66-72

后端接口

所有 API 服务通过 Backend 接口与以太坊节点进行交互，该接口提供了对区块链数据、交易池和其他核心功能的标准化访问。

Backend 接口定义了以下方法：

• 区块链访问：HeaderByNumber、BlockByHash、StateAndHeaderByNumber internal/ethapi/backend.go59-68
• 事务管理： SendTx、GetPoolTransactions、GetTransaction internal/ethapi/backend.go76-81
• 事件订阅： SubscribeChainEvent、SubscribeNewTxsEvent internal/ethapi/backend.go72-73
• 配置： ChainConfig、RPCGasCap、RPCEVMTimeout internal/ethapi/backend.go49-55

来源： internal/ethapi/backend.go40-89 eth/api_backend.go47-53

JSON-RPC 消息处理

RPC 系统实现了 JSON-RPC 2.0 规范，支持单请求、批量请求和订阅。消息处理遵循从传输到响应的结构化管道。

请求处理流程

核心消息类型

系统处理几种类型的 JSON-RPC 消息

标准方法调用:

批量请求:

订阅请求:

来源： rpc/json.go32-50 rpc/handler.go100-150 rpc/subscription.go50-80

区块编号和哈希解析

RPC API 支持通过 BlockNumberOrHash 类型灵活地标识区块，允许客户端通过编号、哈希或特殊标签指定区块。

区块编号类型

标签	值	描述
“latest”	-2	最新区块
“pending”	-1	正在开采的待处理区块
“earliest”	-5	创世区块
“safe”	-4	安全头部区块
“finalized”	-3	已最终确定的区块

解析过程处理

• 十六进制数字： "0x1a" → 区块编号 26
• 十进制数字： 直接转换为 uint64
• 特殊标签： 映射到特定的区块链状态
• 区块哈希： 以 0x 开头的 32 字节十六进制字符串

来源： rpc/types.go63-145 rpc/types.go146-254 eth/api_backend.go69-103

订阅系统

WebSocket 和 IPC 传输支持实时订阅以进行事件流式传输。订阅系统使客户端能够接收区块链事件的通知，而无需轮询。

订阅类型

事件处理

过滤器系统处理区块链事件并将其分发给订阅者

1. 事件源： 区块链提要、交易池事件、日志事件
2. 过滤器匹配： 对日志订阅应用地址和主题过滤器
3. 通知传递： 将 JSON-RPC 通知发送给已订阅的客户端
4. 订阅管理： 处理订阅生命周期和清理

关键订阅方法

• eth_subscribe("newHeads") - 新区块头 eth/filters/api.go232-256
• eth_subscribe("newPendingTransactions") - 待处理的交易 eth/filters/api.go160-196
• eth_subscribe("logs", {...}) - 合约事件日志 eth/filters/api.go259-290

来源： eth/filters/api.go66-85 eth/filters/filter_system.go42-100 rpc/subscription.go1-50

Web3 JavaScript 扩展

RPC 系统包含 JavaScript 扩展，这些扩展用 geth 特定的功能扩展了 web3.js。这些扩展为高级功能提供了方便的客户端接口。

扩展模块

模块	目的	示例方法
admin	节点管理	admin.peers、admin.nodeInfo
debug	调试工具	debug.traceTransaction、debug.traceBlock
miner	挖矿控制	miner.setGasPrice、miner.setExtra
txpool	交易池	txpool.status、txpool.content

这些扩展在 JavaScript 中定义，并为 geth 特定的 RPC 方法提供了客户端方法定义、参数格式化和结果处理。

来源： internal/web3ext/web3ext.go20-30 internal/web3ext/web3ext.go89-177 internal/web3ext/web3ext.go179-474

错误处理与验证

RPC 系统实施了全面的错误处理和请求验证，以确保安全可靠的运行。

请求验证

• 方法存在性： 验证所请求的方法是否已注册
• 参数验证： 参数的类型检查和范围验证
• 身份验证： 对敏感方法的可选身份验证
• 速率限制： 对请求处理的可配置限制

常见错误响应

错误代码遵循 JSON-RPC 2.0 规范，并包含 geth 特定的以太坊相关错误扩展。

来源： rpc/handler.go200-250 rpc/json.go200-300 internal/ethapi/api.go700-800