rest: Query predecessor headers using negative count param #33752

1. 
   A-Manning commented at 9:11 am on October 31, 2025: contributor

   There is currently no mechanism by which to batch-query headers from tip, backwards towards genesis. This PR extends the REST Blockheaders API to support batch-querying predecessor headers, by providing a negative count parameter.
2. DrahtBot added the label RPC/REST/ZMQ on Oct 31, 2025
3. 
   DrahtBot commented at 9:11 am on October 31, 2025: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33752.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   Concept NACK	stickies-v

   If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

4. A-Manning force-pushed on Oct 31, 2025
5. A-Manning force-pushed on Oct 31, 2025
6. in src/rest.cpp:226 in b63808585d

   230+        abs_count = static_cast<size_t>(PTRDIFF_MAX);
   231+        count_is_non_negative = false;
   232+    } else {
   233+        abs_count = static_cast<size_t>(-*parsed_count);
   234+        count_is_non_negative = false;
   235+    }
   

   ---

   ---

   

   maflcko commented at 11:23 am on October 31, 2025:

   this seems a bit tedious. Why not just use i64 as a type, which can hold a sign and a value. This way, it won’t be necessary to use a bool to hold the sign.

   ---

   

   A-Manning commented at 3:00 pm on October 31, 2025:

   Updated to make this a bit more succinct. ptrdiff_t used here because it is the signed equivalent to size_t, and is suitable for casting to size_t to compare against headers.size().

   ---

   

   maflcko commented at 3:29 pm on October 31, 2025:

   MAX_REST_HEADERS_RESULTS is a small number, so I don’t think we need any architecture-specific and special PTRDIFF handling and can just use fixed size integral values.

   Also, to walk backwards, I am sure you can just use pprev and not need to create a new method.

7. A-Manning force-pushed on Oct 31, 2025
8. A-Manning force-pushed on Oct 31, 2025
9. A-Manning requested review from maflcko on Oct 31, 2025
10. 
    maflcko commented at 9:48 am on November 3, 2025: member

    Though, I wonder what the use case is. If someone knows a header, it seems likely they also know about the previous headers and a feature to support asking for them would have no users?
11. 
    A-Manning commented at 10:21 am on November 3, 2025: contributor

    Though, I wonder what the use case is. If someone knows a header, it seems likely they also know about the previous headers and a feature to support asking for them would have no users?

    Knowing a header only means that you know the previous block hash. If you want to request headers from best tip to genesis, There is no existing mechanism other than requesting headers one-at-a-time. This makes it possible to batch request headers from tip to genesis, which is much more efficient than requesting one-at-a-time.

12. 
    stickies-v commented at 12:34 pm on November 3, 2025: contributor

    There is no existing mechanism other than requesting headers one-at-a-time.

    Request the starting hash with GET /rest/blockhashbyheight/<HEIGHT>.<bin|hex|json> and then request headers upward with /rest/headers/?

    Concept NACK, unless I’m misunderstanding the limitations/use case.

13. 
    A-Manning commented at 1:11 pm on November 3, 2025: contributor

    Request the starting hash with GET /rest/blockhashbyheight/.<bin|hex|json> and then request headers upward with /rest/headers/?

    We currently use this approach at L2L. This strategy is far from ideal - any of the upward requests may return headers from a different active chain, in the event of a re-org. It is necessary to check that the final block hash is the same as the tip hash we want to sync to, and if it is not, then the only way to retrieve the headers would be requesting headers via JSON-RPC, one at a time.

14. 
    stickies-v commented at 2:25 pm on November 3, 2025: contributor

    The reorg potential does make using the interface more cumbersome in general, I’m not sure your approach solves that? You’re still limited by what’s in the active_chain, so you still need logic to deal with what if the index you’re requesting a negative count from isn’t in the active chain anymore?
15. REST: Accept negative header counts to return predecessors 200a9c980e
16. A-Manning force-pushed on Nov 6, 2025
17. 
    A-Manning commented at 5:55 pm on November 6, 2025: contributor

    @stickies-v Updated to handle the case where the requested block header is no longer in the active chain.
18. A-Manning requested review from stickies-v on Nov 17, 2025

Contributors
A-Manning DrahtBot maflcko stickies-v

Review Requested
maflcko stickies-v

Labels
RPC/REST/ZMQ