#33820 kernel: trim Chain interface

ReviewabilityReviewsAgreementSize
#33820 stickies-v kernel: trim Chain interfaceAuthor silent 356d1Strong+2/-33
  • Trim redundant accessor functions from the public libbitcoinkernel C API
  • Reduce the public surface area before API stabilization without losing functionality
  • Author inactive for 318 days; reviews may wait a long time for a response
  • Concept support noting redundant accessors provide marginal benefit over chain iterators (TheCharlatan)
  • General approval without detailed technical justification (yuvicc)
  • Resolved concern: rare reorg lowering chain height could throw an uncaught exception (maflcko)
  • 3 files
  • 2 commits
Kernel (libbitcoinkernel)#18 of 18
P4 · cleanup
  • P4 after comparing with the other PRs here (assessed alone as P3): Lowered to P4: removing two redundant accessors is cosmetic API polish with no consumer asking for it, which the category explicitly places at P3 or below; it is the weakest claim on review time here.
  • P3 because it is a routine cleanup removing redundant accessors from the public C API
  • Minimizes the surface area of the public kernel interface ahead of stabilization
Ranking notes
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.

Goal

Removes btck_chain_get_genesis and btck_chain_get_tip from the libbitcoinkernel C API. Both operations can be performed by calling btck_chain_get_by_height with height 0 or the current chain height.

Problem: Redundant accessor methods expand the public kernel surface without providing extra guarantees or thread safety over existing height-based lookups.

Reviewability

Stale · Author silent 356d

No author activity for 356 days; a review may wait a long time for a response.

Agreement

Strong

substantive support, no open objection (TheCharlatan)

Thread notes: Added ACK from yuvicc and Concept ACK from TheCharlatan. Recorded maflcko's edge-case reorg exception concern as a resolved nonblocking objection addressed by the author's rationale.

Objections, suggestions, and questions:

ReviewerTypeHarm, request, or questionStatusMust beAuthor repliedQuote
maflcko (member)objection, correctnessa rare reorg that lowers the chain height can cause a query for the tip to throw an uncaught std::runtime_erroranswered · v1, not yet re-checkedansweredyes2025-11-10: 'there could be a rare and theoretical race where the function does not return any tip, but rather throws `std::runtime_error("No entry in the chain at the provided height");` when the height is re-orged out to a lower more-work height'
Status from: 2025-11-10: stickies-v: 'Reorg-safety in general is still an unsolved problem for the public interface, and this is another case of that. Note: the problem you report already exists for objects based on the `Range` class'

Support:

  • yuvicc (contributor) (ACK, 2025-11-08): This makes sense to me. [not substantive]
  • TheCharlatan (contributor) (Concept ACK, 2025-11-08): These were introduced before we had a dedicated iterator for traversing the chain. At this point, their benefit (thread safety) is kind of marginal.

Participants:

  • TheCharlatan (contributor, support, 3 statements 2025-11-08 to 2025-11-10): Concept ACKed removing the calls; noted synchronization should be handled by external callers
  • yuvicc (contributor, support, 1 statements 2025-11-08 to 2025-11-08): ACKed the commit
  • maflcko (member, objection, 1 statements 2025-11-10 to 2025-11-10): noted an edge case race during height-reducing reorgs that could throw an exception

Files

0 lines under test/bench/ci.

File list not available for this run.

Card

The short text the ranking pass compares across PRs.

This PR removes btck_chain_get_genesis and btck_chain_get_tip from the libbitcoinkernel C API, trimming redundant methods that can be achieved via btck_chain_get_by_height. It is a minor API cleanup that does not affect validation logic or unlock external consumers. Reviewers TheCharlatan and yuvicc agreed the methods are redundant and safe to remove, but the PR has been inactive for over ten months.

Data

dossier JSON · extract JSON · model ledger, generated 2026-09-18T03:56, confidence high, input hash a4d93076e1420ce3
thread read through 2025-11-10 (7 statements), head f4b3ba18d9
Discussion read under schema 1 rules: suggestions and questions may be missing, and an objection may combine several harms (schema history).
labels: Validation

Categories

Kernel (libbitcoinkernel)

P4 · cleanup (assessed alone as P3; Lowered to P4: removing two redundant accessors is cosmetic API polish with no consumer asking for it, which the category explicitly places at P3 or below; it is the weakest claim on review time here.)

Trims redundant accessor functions from the public C API to minimize surface area prior to stabilization. As noted by TheCharlatan, these redundant methods provide marginal benefit now that dedicated chain iteration exists.

Membership: Removes btck_chain_get_genesis and btck_chain_get_tip from the libbitcoinkernel C API wrapper.

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