#35909 rest: Allow fetching stale header

full analysis

https://github.com/bitcoin/bitcoin/pull/35909 · davidgumberg · +134/-28 in 6 files, 3 commits · labels: RPC/REST/ZMQ

Goal

  • Allow REST clients to fetch headers for stale blocks not on the active chain
  • Enables tools like fork-observer to inspect non-active blocks during or after re-orgs

This PR adds an `activechainonly=false` query parameter to the `/rest/headers/` endpoint, allowing clients to query a single stale block header when `count=1`. It also refactors query parameter boolean parsing into a shared helper `RESTParseBoolParam`.

Problem: The REST `/rest/headers/` endpoint only returns headers that reside on the active chain, making it impossible for REST-based tools (such as fork-observer) to inspect ancestors of non-active blocks during or after a re-org.

Category: RPC / REST / ZMQ (#15 of 52)

P3 · new feature

  • P3 because it provides clear value for external REST consumers following re-orgs
  • Valuable for fork monitoring tools but deferrable without system-wide urgency

Clear use case and real value for external REST consumers following re-orgs or stale branches, but deferrable without system-wide urgency.

Membership: Modifies REST server endpoints in src/rest.cpp and src/rest.h.

Factors: security/stability 0, bug 0, performance 0, user value 2, leverage 0

Reviewability: Ready

  • Ready for review now

The patch is clean, tests pass, and it is ready for feedback on the endpoint parameter design.

Author status: active

Open concerns:

  • 0xB10C raised whether a dedicated `/rest/header/` endpoint might be cleaner than requiring `count=1&activechainonly=false` on `/rest/headers/`.

Resolved concerns:

  • jeanpablojp questioned release note naming convention; author clarified.

Agreement: Positive

  • Concept approval without stated reasons (sedited)
  • Tested and prefers query parameter approach over a new endpoint (jeanpablojp)
  • Supports use case but asks if a dedicated endpoint would be cleaner (0xB10C)

Positive: concept ACKed and tested, with minor discussion on whether a separate endpoint is cleaner.

Multiple contributors support the functionality, with concrete use cases mentioned (such as fork-observer), while discussion remains open on parameter versus dedicated endpoint semantics.

  • sedited left Concept ACK
  • jeanpablojp gave tACK and preferred the query param approach over a new endpoint
  • 0xB10C gave Concept ACK citing fork-observer use case, but suggested a separate endpoint might avoid REST API weirdness

Review verdicts (DrahtBot): 1

Dependencies

Enables:

Files

59 lines under test/bench/ci.

  • src/rest.cpp +59/-25
  • src/test/rest_tests.cpp +44/-0
  • test/functional/interface_rest.py +14/-1
  • doc/REST-interface.md +7/-2
  • doc/release-notes-reststaleheader.md +5/-0
  • src/rest.h +5/-0

Card

Adds an activechainonly query parameter to /rest/headers to allow retrieving single stale block headers not on the active chain. Solves a gap where REST users cannot inspect headers on stale branches or follow re-orgs upward, matching getblockheader RPC behavior. Concept is well supported with a tACK, though discussion remains open on whether a dedicated endpoint would be cleaner than an activechainonly parameter. No dependencies.

Data

dossier JSON · extract JSON · model openrouter/google/gemini-3.8-flash, generated 2026-09-17T16:21, confidence high, input hash e47a0ebd7e52bef6