Skip to content

eth: add eth_getHeaderByHash and eth_getHeaderByNumber - #877

Open
MysticRyuujin wants to merge 4 commits into
ethereum:mainfrom
MysticRyuujin:eth-get-header
Open

MysticRyuujin wants to merge 4 commits into
ethereum:mainfrom
MysticRyuujin:eth-get-header

Conversation

@MysticRyuujin

@MysticRyuujin MysticRyuujin commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

Implements #874.

Adds eth_getHeaderByHash and eth_getHeaderByNumber. The result is a new Header schema: the consensus header fields plus the derived hash. size and totalDifficulty are excluded, because neither is a header field. The schema is closed, so a client must not add fields. Fields introduced by a fork are omitted for headers that predate it. The result is null for an unknown block and for pending. slotNumber (EIP-7843) is added to Block and Header to keep the schemas aligned.

An unresolvable safe or finalized tag is an unknown block, so the result is null there too. #879 put that rule in BlockTag itself, so this PR no longer repeats it in the method description.

Also adds the testgen generators and 13 geth-generated fixtures.

Client work, one PR per client:

Client Change PR
go-ethereum Return null instead of -32000 for unresolvable tags and pending. #35627, merged
Nethermind Return null for pending instead of a header with hash, nonce, and miner nulled. #13082
reth Drop size from header responses. The value is the whole-block RLP length. Block responses keep it. #26912, waits on reth-core#44
Besu Implement. #11220
Erigon Implement in the eth namespace. erigon_getHeaderBy* emits pre-fork fields as null and errors on unknown blocks, so it cannot be aliased directly. #23717
ethrex Implement. Pre-fork baseFeePerGas, withdrawalsRoot, and parentBeaconBlockRoot must be omitted, not null. #7247

Hive rpc-compat against client master images on 2026-09-01, before any of those PRs: geth and Nethermind pass all 13 fixtures byte-identically, reth fails 10 on the extra size field, and Besu, Erigon and ethrex do not implement the methods.

The pending and unresolvable-tag rules are not reproducible on the static test chain, so no fixture covers them.

Comment thread src/eth/block.yaml Outdated
Comment thread src/schemas/block.yaml
@magamongo

magamongo commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

Thanks for taking this forward so comprehensively, including the client-side PRs. This matches the direction I had in mind when opening #874.

I am comfortable with the choices to omit size and totalDifficulty, disallow additional properties, return null for pending, and treat unresolvable safe / finalized tags as unknown blocks, subject to #879. Returning null for pending seems cleaner than defining a partially-null header object.

MariusVanDerWijden pushed a commit to ethereum/go-ethereum that referenced this pull request Sep 9, 2026
…_getHeaderByNumber (#35627)

`eth_getHeaderByNumber` now returns `null` for the `pending` tag and for
a `safe` or `finalized` tag that cannot be resolved to a block. Before
this change it returned a pending header with `hash`, `nonce`, and
`miner` nulled, and a `-32000` error for unresolvable tags.

Implements the semantics proposed in ethereum/execution-apis#877 for
these methods (ethereum/execution-apis#874). Block methods are not
changed.
@MysticRyuujin
MysticRyuujin marked this pull request as ready for review September 9, 2026 16:01
@MysticRyuujin MysticRyuujin mentioned this pull request Sep 13, 2026
29 tasks
yperbasis pushed a commit to Sahil-4555/erigon that referenced this pull request Sep 16, 2026
…ech#23717)

Adds `eth_getHeaderByHash` and `eth_getHeaderByNumber`, implementing the
spec proposed in ethereum/execution-apis#877
(ethereum/execution-apis#874). geth, Nethermind, and reth already serve
these methods; Erigon has them only in the `erigon_` namespace.

The new methods do not reuse the `erigon_getHeaderBy*` path because its
`types.Header` JSON marshaling emits pre-fork fields as literal `null`
and returns errors for unknown blocks. They marshal through
`ethapi.RPCMarshalHeader`, which fork-gates optional fields, and return
`null` for an unknown block, for the `pending` tag, and for an
unresolvable `safe` or `finalized` tag.

`RPCMarshalHeader` no longer sets `size`. Its only caller overwrites the
value with the block size, and the header methods must not emit it: the
spec excludes `size` because no client computes a header size and the
block getters already report the block size.

---------

Co-authored-by: Alexey Sharov <askalexsharov@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants