ethereum / ethereum/execution-apis

Proposal: standardize eth_getHeaderByHash and eth_getHeaderByNumber

Open
#874 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Io
Stars
1.1k
Forks
530
Avg merge
5d 8h
Merged PRs (30d)
9

Description

## Motivation

`eth_getHeaderByHash` and `eth_getHeaderByNumber` provide header-only alternatives to `eth_getBlockByHash` and `eth_getBlockByNumber`. They avoid loading and transferring block body data when callers only need the execution header.

The methods are currently implemented in:

- [Geth](https://github.com/ethereum/go-ethereum/blob/bbb9119caaefbbf619363493e54cc8362d65188d/internal/ethapi/api.go#L489-L516)
- [Reth](https://github.com/paradigmxyz/reth/blob/3bc71d43f7101f772bbb4f9e15d3cdd58f60e958/crates/rpc/rpc-eth-api/src/core.rs#L738-L751)
- [Nethermind](https://github.com/NethermindEth/nethermind/blob/f0a29b888b34aa19d1ef12213a3fba3e76d18cdb/src/Nethermind/Nethermind.JsonRpc/Modules/Eth/EthRpcModule.cs#L659-L682)

I could not find JSON-RPC implementations in Besu, and neither method is currently included in execution-apis.

There is some prior repository history: #265 added test-generator coverage for both methods, but the methods were never added to the specification. The old generator entries were disabled with a comment that header requests were not in the spec and were later removed as unused.

## Proposed signatures

```text
eth_getHeaderByHash(DATA, 32 bytes) -> Header | null
eth_getHeaderByNumber(QUANTITY | TAG) -> Header | null
```

The proposed `Header` object would contain the execution header fields used by the existing `Block` schema, but omit body-level fields:

- omit `transactions`, `uncles`, and `withdrawals`
- use `miner` as the beneficiary field name
- include fork-conditional header fields such as `baseFeePerGas`, `withdrawalsRoot`,
`blobGasUsed`, `excessBlobGas`, `parentBeaconBlockRoot`, `requestsHash`,
`blockAccessListHash`, and `slotNumber`
- omit `totalDifficulty`, which is deprecated and is not returned by the three implementations

My initial preference is not to specify `size`: Geth and Nethermind omit it, while Reth includes the full block RLP length through its Alloy RPC header wrapper. It is not a consensus header field. Reth could continue returning it as an additional implementation field if the schema remains open to additional properties.

## Existing behavior differences

| Case | Geth | Reth | Nethermind |
|---|---|---|---|
| unknown hash/number | `null` | `null` | `null` |
| missing `safe` / `finalized` | error | `null` | `null` |
| available `pending` | nulls `hash`, `nonce`, `miner` | leaves them populated and includes `size` | nulls `hash`, `nonce`, `miner` |
| unavailable `pending` | error | `null` | `null` |
| `size` | omitted | included | omitted |
| `totalDifficulty` | omitted | omitted | omitted |
| beneficiary name | `miner` | `miner` | `miner` (`author` only as an AuRa extension) |

The existing `BlockTag` description requires `-39001: Unknown block` for `safe` and `finalized` before the Merge transition is finalized. We should decide whether these header methods follow that rule for an unavailable tag, or standardize the `null` behavior currently used by Reth and Nethermind.

## Questions for client teams

1. Do client teams support standardizing both methods in the `eth` namespace?
2. Should `size` be omitted from the standard `Header` schema, or included as an optional field?
3. Should an unavailable `safe`, `finalized`, or `pending` tag return `null` or an Unknown Block
error?
4. Should pending responses require `hash`, `nonce`, and `miner` to be `null`, matching Geth and
Nethermind, or permit populated values as returned by Reth?
5. Would Besu be willing to implement these methods if standardized?

## Proposed implementation in execution-apis

- add a standalone common `Header` schema
- add the two method definitions
- add Geth-backed rpctestgen cases for by-hash, by-number, not-found, tags, pending, and fork fields
- generate golden `.io` fixtures and validate them with `make test`

If there is rough consensus on the behavior above, I would be happy to open a focused specification PR.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing Block schema and the linked Geth, Reth, and Nethermind implementations, then inspect execution-apis rpctestgen coverage and the proposed behavior questions. A complete contribution would establish consensus, add the Header schema and both method definitions, generate the mentioned .io fixtures, and pass make test.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.