#36632 kernel: document the import_blocks abort

ReviewabilityReviewsAgreementSize
#36632 fametrano kernel: document the import_blocks abortReady0Positive11
  • Document process-abort preconditions and block storage behavior in the libbitcoinkernel C API
  • Prevent external callers from accidentally triggering process aborts or storing untrusted blocks
  • Reviewable immediately as all requested changes are pushed and no work is pending
  • No review verdicts recorded
  • General support with no open objections
  • Support for documenting the import_blocks abort behavior (sedited)
  • Author dropped an already documented commit per reviewer feedback (sedited)
  • 11 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 0 lines removed in total
  • 1 files, 1 commits
Kernel (libbitcoinkernel)#16 of 18
P3 · cleanup
  • P3 because clarifying abort preconditions offers modest safety value for external library consumers
  • Documentation only with no changes to executable code or internal kernel logic
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

Documents block storage behavior and process-abort preconditions in the libbitcoinkernel C API header. It clarifies that btck_chainstate_manager_process_block treats passed blocks as requested (storing them without unrequested-block filtering) and warns callers taking blocks from untrusted sources to perform those checks themselves. It also documents preconditions that trigger process aborts in btck_precomputed_transaction_data_create and btck_chainstate_manager_import_blocks.

Problem: Consumers of the libbitcoinkernel C API lack documentation on undocumented abort preconditions and unexpected block persistence behavior. Without this documentation, external applications could inadvertently trigger fatal aborts or persist low-work or pruned blocks received from untrusted peers.

Evidence of importance:

  • Commit dda2c1f325 notes: 'btck_precomputed_transaction_data_create aborts when spent_outputs is set and its length differs from the number of inputs. A nested btck_chainstate_manager_import_blocks call on the same chainstate manager also aborts. The header states neither.'
  • PR description notes that the author verified both aborts with a small test program against the library and that btck_chainstate_manager_process_block sets force_processing, altering what gets written to disk.

Scope: Pure documentation changes in the public C header src/kernel/bitcoinkernel.h.

Risk of a mistake: low (docs). The patch consists entirely of comment additions in a header file and alters no executable code.

Changed since the previous assessment: Added a second commit documenting process-abort preconditions for mismatched spent_outputs length in btck_precomputed_transaction_data_create and nested calls in btck_chainstate_manager_import_blocks.

Reviewability

Ready

Nothing known that would invalidate a review now.

Waiting on (from the thread read):

  • reviewer: sedited to review after author dropped the first commit 2026-11-01

Agreement

Positive

support without stated reasons, no open objection (sedited)

Thread notes: Author dropped the first commit in response to sedited's feedback, resolving the suggestion.

Objections, suggestions, and questions:

ReviewerTypeHarm, request, or questionStatusMust beAuthor repliedQuote
sedited (member)suggestion, usefulnessExplain why the first commit is needed or drop it, as it seems already documentedfixed · fix pushed · author dropped the first commit as suggestedansweredyes2026-10-26: 'The first commit seems already documented to me.'
Status from: 2026-11-01: fametrano: 'Dropped the first commit and the `spent_outputs_len` note.'

Support:

  • sedited (member) (2026-10-26) [read]: The second one's importblocks behaviour seems ok to add. [not substantive]

Participants:

  • sedited (member, support, 1 statements 2026-10-26 to 2026-10-26): suggested dropping the first commit as already documented, supported the import_blocks abort documentation

Files

0 lines under test/bench/ci.

  • src/kernel/bitcoinkernel.h +11/-1

Card

The short text the ranking pass compares across PRs.

Documents block storage behavior and process-abort preconditions in the libbitcoinkernel C API header. Callers of btck_chainstate_manager_process_block are warned that blocks are processed as requested and stored to disk without standard work or tip checks, requiring external callers using untrusted sources to filter them first. It also documents abort preconditions for mismatched spent outputs in transaction precomputation and reentrant calls in block importing. The pull request is documentation-only, adding 11 lines to bitcoinkernel.h.

Data

dossier JSON · extract JSON · model ledger, generated 2026-11-02T01:11, confidence high, input hash a07e8b5d158ac0b4
thread read through 2026-11-01 (2 statements), head 2077d1571e
labels: Validation

Categories

Kernel (libbitcoinkernel)

P3 · cleanup

Clarifies abort preconditions and block storage behavior in the public C API header. Documenting conditions that trigger process aborts or disk persistence of untrusted blocks provides clear, deferrable value to external consumers of libbitcoinkernel.

Membership: Modifies src/kernel/bitcoinkernel.h to document libbitcoinkernel C API behavior and preconditions.

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