✅Ethereum JSON‑RPC Schema Changes & Execution Client Compatibility

Following Ethereum’s transition to Proof of Stake, the Execution Layer JSON-RPC schema was updated to reflect changes in block metadata. The totalDifficulty field was officially removed from the eth_getBlockByNumber response. Additionally, the difficulty field—previously used in Proof of Work—was retained as optional but is now considered obsolete and typically returned as "0x0" by spec-compliant clients like Erigon v3. While some clients (e.g., Geth and BSC-Erigon) continue to include these fields for backward compatibility, developers relying on them should update their subgraphs and tooling to accommodate these schema changes.

Full schema details are available in the Ethereum Execution APIs documentation. We've added a chart with the current client compatibility with these updates as of July 17, 2025. Please check for specific client updates as needed.

Ethereum JSON‑RPC Schema Changes Post-Merge

Field	JSON‑RPC Schema Status (Post-Merge)
totalDifficulty	❌ Removed from eth_getBlockByNumber response
difficulty	⚠️ Optional / deprecated, expected to be 0x0 post-Merge
size	⚠️ Optional; may be omitted depending on client

Execution Client Compatibility

Client	totalDifficulty	difficulty	size	Notes
Erigon v3	Not returned	"0x0"	Usually present	Strict spec compliance, noted here
Geth	Returned	Non-zero	Returned	Maintains legacy behavior, noted here
Nethermind	Returned	Non-zero	Returned	Maintains legacy behavior, noted here
Besu	Returns 0 for an uncle block	Non-zero	Returned	Returns deprecated fields with valid values, noted here
Reth	Not returned	"0x0"	Returned	Highly spec-compliant, aligns with post-Merge schema