#35909 rest: Allow fetching stale header
https://github.com/bitcoin/bitcoin/pull/35909 · · +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
- ACK: jeanpablojp
- Concept ACK: sedited, 0xB10C
Dependencies
Enables:
- Resolves #35897
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.