Kernel (libbitcoinkernel)

PRPriorityReviewabilityReviewsAgreementSize
(+)#34775 stickies-v kernel: allow only one global logging connectionP1 · bug fixReady0Mild132 + 96 tests
  • Prevent logging deadlocks when consumer callbacks trigger logging during garbage collection or finalization
  • Restrict kernel logging to one connection handle to match the process-wide singleton reality
  • P1 after comparing with the other PRs here (assessed alone as P2): Raised to P1 and moved up five places: a deadlock risk when consumer callbacks log is a reliability defect exactly at the kernel boundary, and the single-connection decision also gates the per-context logging series.
  • P2 because it fixes potential deadlocks at the kernel boundary when consumer callbacks invoke logging
  • It eliminates thread serialization on user callbacks and aligns the public API with singleton behavior
  • Ready for review
  • Concept support because single connections are simpler and pragmatic for consumers (sedited)
  • Approach approval without detailed reasoning (w0xlt)
  • Answered objection: premature API restriction is hard to reverse and lacks benefit (ryanofsky)
  • 132 lines added or modified outside tests
  • 96 lines added or modified in tests
  • 112 lines removed in total
  • 5 files, 4 commits
(+)#32427 sedited kernel: Replace leveldb-based BlockTreeDB with WAL and .dat file based storeP1 · new featureWaiting on author0 (+6)Blocked988 + 769 tests
  • Allow external applications using libbitcoinkernel to inspect block and header data concurrently
  • Remove the exclusive database lock that forces users to shut down Bitcoin Core to run indexers
  • P1 after comparing with the other PRs here (assessed alone as P2): Raised to P1: LevelDB's exclusive process lock is the concrete reason external consumers (Electrs/Esplora) cannot read block/header data from a running node, which is the category's defining use case.
  • P2 because it allows external consumers to read block and header data while a node is running
  • Unblocks concurrent index building for downstream tools like Electrs and Esplora
  • Needs rebase
  • Author silent 84 days and reworking parallel reader access after converting to draft
  • Broad interest in removing the LevelDB dependency and enabling parallel indexing (josibake, theuni)
  • Verified by differential fuzzing for 5000 CPU hours without issues (marcofleon)
  • Unaddressed objection: LockDirectory succeeds without locking on re-lock and drops the lock (pzafonte)
  • Unaddressed objection: directory committing is a no-op on Windows risking corruption (stickies-v)
  • 988 lines added or modified outside tests
  • 769 lines added or modified in tests
  • 201 lines removed in total
  • 31 files, 10 commits
(+)#29700 ryanofsky kernel, refactor: return error status on all fatal errorsP2 · cleanupReview #25665 first0Blocked1,334 + 464 tests
  • Return error status directly from validation and storage routines rather than triggering node shutdowns
  • Lets libbitcoinkernel callers handle fatal errors programmatically instead of via global callbacks
  • P2 because it allows library consumers to receive structured error information directly at call sites
  • Removing node-specific abort assumptions is required to make validation usable as a standalone library
  • No review verdicts recorded
  • Unaddressed objection: Result-style error handling hurts performance and defies C++ idioms (purpleKarrot)
  • Concern about fragile nested result unwrapping and missed interruptions was answered (maflcko)
  • Inconsistency from ignored flush returns mutating validation state was resolved in #35621 (optout21)
  • Approval without stated reason from an account with no project history (Graysonbarton)
  • 1,334 lines added or modified outside tests
  • 464 lines added or modified in tests
  • 676 lines removed in total
  • 56 files, 23 commits
(+)#35187 sedited kernel: Block validation without a complete UTXO setP2 · new featureReady0 (+1)Disputed242 + 119 tests
  • Validate blocks in libbitcoinkernel without requiring a local on-disk chainstate database
  • Allow lightweight verifiers and external UTXO databases to validate block transactions directly
  • P2 because it adds a major capability to libbitcoinkernel for block validation without an on-disk UTXO set
  • P2 because it advances API completeness for external consumers and lightweight verification tools
  • Ready to review
  • Broad concept support, but contested objections remain after a rebase (ajtowns, w0xlt)
  • Contested objection: caller callback enables non-deterministic lookups and drops UTXO changes (ajtowns)
  • Contested objection: script cache poisoning could let caller-supplied coins validate invalid blocks (w0xlt)
  • Contested objection: impossible coin confirmation heights can cause assertion crashes in release builds (w0xlt)
  • Unaddressed objection: assumevalid causes ancestor blocks to skip script checks (nervana21)
  • 242 lines added or modified outside tests
  • 119 lines added or modified in tests
  • 0 lines removed in total
  • 6 files, 5 commits
(+)#33847 ryanofsky kernel: Attach logging connections to contexts, per-connection log levelsP2 · unblocks #30342Ready0 -1Disputed142 + 45 tests
  • Attach logging connections to kernel contexts and configure minimum log levels per connection
  • Enable applications running multiple chainstates or multi-context tests to separate their log output
  • Avoid future breaking API changes and caller restructuring when per-context log routing is introduced
  • P2 because it unblocks per-context log routing in #30342
  • Avoids breaking API changes and caller restructuring across all kernel consumers and bindings
  • Ready to review
  • Disputed on whether to change the public API before internal refactoring lands
  • Concept support for making the logging interface local instead of global (sedited, stickies-v)
  • Objection: per-connection handles falsely imply isolation while behavior remains global (stringintech)
  • Approach NACK: public logging API should not change until internal work in #30342 proceeds (stickies-v)
  • 142 lines added or modified outside tests
  • 45 lines added or modified in tests
  • 48 lines removed in total
  • 5 files, 1 commits
(+)#29256 ryanofsky log, refactor: Allow log macros to accept context argumentsP2 · new featureReview #34778 first0 -2Disputed217 + 207 tests
  • Let logging macros target specific logger instances, custom formatters, and categories
  • Allow kernel library users to isolate log output instead of forcing all callers into one global stream
  • Skip unnecessary formatting work when log messages are disabled
  • P2 because it removes reliance on a single global logger for libbitcoinkernel consumers
  • Enables isolated log traces and running multiple kernel instances side by side
  • Ranking pass: Moved up five places: it is the macro-level prerequisite for both #33847 and #30342, so it inherits their importance and must be reviewed before them.
  • Disputed with an active Concept NACK against instanced logging and context arguments (ajtowns)
  • Thinks multi-instance logging adds unnecessary complexity and call-site churn without benefit (ajtowns)
  • Concept support to enable separate kernel log instances like parallel chainstate managers (sedited)
  • Concept support for separating logging facility from severity (vasild, jonatack)
  • Requested changes to split commits were answered by author and await re-review (l0rinc)
  • 217 lines added or modified outside tests
  • 207 lines added or modified in tests
  • 127 lines removed in total
  • 7 files, 10 commits
(+)#30342 ryanofsky kernel, logging: Deliver each context's log output to its own logging connectionP2 · cleanupReview #29256 first0 -1Mild832 + 437 tests
  • Prevent interleaved log streams when running multiple chainstate contexts or kernel library instances
  • Allow kernel consumers and multi-context tests to cleanly separate log output by context
  • P2 because it eliminates process-wide global logging state from the kernel library
  • Enables clean concurrent execution of multiple independent chainstate contexts in one process
  • Provides architectural leverage for making the kernel usable as an isolated library
  • Concept approval without stated reasons (sedited)
  • Thinks review cost and merge conflicts outweigh current user demand, favoring simpler logging (stickies-v)
  • Earlier objection about cumbersome logger plumbing was resolved with per-file enforcement (stickies-v)
  • 832 lines added or modified outside tests
  • 437 lines added or modified in tests
  • 744 lines removed in total
  • 79 files, 18 commits
(+)#36326 arejula27 kernel: Use typed errors for fatal and flush error notificationsP2 · unblocks #27587Waiting on author0Mild358 + 96 tests
  • Remove application-level translation machinery dependencies from libbitcoinkernel
  • Replace string-based fatal and flush error notifications with typed errors across the kernel boundary
  • Move error string formatting and translation into the node layer
  • P2 because it decouples libbitcoinkernel from application-layer translation dependencies
  • Directly advances tracking issue #27587 by removing translation.h from the kernel
  • Ready for review
  • Concept approval without detailed review (sedited, yuvicc)
  • Objection that replacing C API callback messages with error codes drops details (ryanofsky, yuvicc)
  • Unaddressed suggestions on C API dynamic error details and debug assertions (Yudis-bit)
  • 358 lines added or modified outside tests
  • 96 lines added or modified in tests
  • 89 lines removed in total
  • 15 files, 6 commits
(+)#35557 ryanofsky kernel, validation: Add btck_chainstate_manager_set_clock_timeP2 · new featureReady0Mild171 + 86 tests
  • Allow kernel library callers and tests to set clock time per instance rather than through global state
  • Eliminate intermittent test flakes caused by race conditions across second boundaries
  • P2 because it lets concurrent kernel instances set mock time independently without shared global state
  • Enforces kernel boundaries by catching accidental nondeterministic clock usage at link time
  • Ready to review
  • No review verdicts recorded
  • Unaddressed objection: PR may be obsolete after #35496 and conflicts with approach in #35906 (maflcko)
  • Prefers setter on chainstate over options, but questions whether it is worth the effort (sedited)
  • Ergonomics concern about managing clocks per object was answered with an alternative prototype (stickies-v)
  • 171 lines added or modified outside tests
  • 86 lines added or modified in tests
  • 99 lines removed in total
  • 31 files, 6 commits
(+)#35646 yuvicc RFC: Separate out runtime errors from BlockValidationState using `util::Expected`P2 · cleanupWaiting on author0 -1Blocked342 + 233 tests
  • Separate system runtime errors like disk or memory failures from consensus block validity
  • Prevent operational failures from being mistaken for invalid blocks across node routines
  • P2 because it refactors error reporting across the library boundary and C API
  • Improves modularity by giving callers a dedicated representation for fatal system failures
  • Reviewing logic now is worthwhile even though the branch has merge conflicts
  • The rebase is mechanical and does not disrupt the ongoing design discussion
  • General support for separating fatal runtime errors from block validation (optout21, hodlinator, l0rinc)
  • Unaddressed objections on fallthrough bugs and changed notification behavior (optout21)
  • Concept objection against expected returns over exceptions citing chain split risks (purpleKarrot)
  • Concern that flattening results into booleans leaves safety to reviewer checks (alexanderwiederin)
  • 342 lines added or modified outside tests
  • 233 lines added or modified in tests
  • 369 lines removed in total
  • 40 files, 16 commits
(+)#28690 sedited build: Introduce internal kernel libraryP2 · cleanupWaiting on author2 (+2)Mild114 + 12 tests
  • Clarifies internal library boundaries by giving the kernel and its utilities dedicated build targets
  • Prevents node targets and the standalone kernel library from duplicating kernel source lists
  • P2 because it isolates kernel sources and trims utility dependencies away from node code
  • It completes the intended internal library architecture needed to decouple the kernel cleanly
  • Ready for review
  • Unaddressed objection: consumer-oriented targets encourage unnatural libraries (stickies-v)
  • Support for improved library boundaries and successful Guix builds (hebasto, janb84, w0xlt)
  • Verified by running bindings in an external test application (Sjors)
  • Verified shared library builds and source reuse under CMake (BrandonOdiwuor)
  • 114 lines added or modified outside tests
  • 12 lines added or modified in tests
  • 122 lines removed in total
  • 6 files, 2 commits
(+)#35662 l0rinc script: prevent partial reinitialization of sighash dataP3 · speedupNeeds rebase1Strong35 + 55 tests
  • Prevent transactions from accidentally reusing cached signature verification data across transactions
  • Eliminate unnecessary copying in kernel verification and skip unused block verification memory
  • P3 because it speeds up the experimental kernel verification API by orders of magnitude
  • The speedup comes from eliminating an unintended transaction data copy on every call
  • Its impact is limited to consumers of the experimental kernel C interface
  • Ready for review with no known blockers or invalidating changes
  • Strong support with all reviewer concerns addressed
  • Verified by differential testing across thousands of sighash key paths and kernel benchmarks (fametrano)
  • Approval after objection to enforce initialization at construction was resolved (sedited)
  • 35 lines added or modified outside tests
  • 55 lines added or modified in tests
  • 88 lines removed in total
  • 17 files, 5 commits
(+)#36318 optout21 validation: Ensure Invalid ValidationState has resultP3 · bug fixReady0Crickets18 + 9 tests
  • Ensure invalid validation states always carry a concrete failure result and non-empty reason
  • Prevent ambiguous validation outcomes in downstream callers like P2P logic and the kernel C API
  • P3 because it updates the kernel C API to report inconclusive validation rather than an unset result
  • Improves error reporting clarity at the kernel boundary for external consumers
  • Ready for review
  • Nothing known that would invalidate a review now
  • No review verdicts recorded
  • No substantive reviews or objections yet
  • Neutral context provided noting where the defaulted result originated (hodlinator)
  • 18 lines added or modified outside tests
  • 9 lines added or modified in tests
  • 11 lines removed in total
  • 10 files, 4 commits
(+)#35641 sedited kernel: Add script evaluation tracerP3 · new featureWaiting on author1 (+1)Mild549 + 111 tests
  • Expose step-by-step script execution snapshots to libbitcoinkernel consumers
  • Enables external script debuggers, execution visualizers, and deeper test inspection
  • P3 because it adds an optional debugging API rather than core validation or chainstate logic
  • Useful for downstream debuggers and tooling, but remains an opt-in extension
  • Worthwhile to review now as nothing invalidates review
  • Broad concept support and extensive test verification
  • Tested ACK across thousands of script spends compared against an external interpreter (fametrano)
  • Unaddressed objection: mutex locking causes contention during parallel verification (fametrano)
  • Answered objection without follow-up: inactive branch opcodes reported as skipped (w0xlt)
  • Concept approval highlighting debugging and testing benefits (furszy, theStack)
  • 549 lines added or modified outside tests
  • 111 lines added or modified in tests
  • 2 lines removed in total
  • 9 files, 1 commits
(+)#36584 stickies-v kernel: make btck_LogEntry opaqueP3 · cleanupReady2Strong175
  • Avoid breaking backwards compatibility for external library consumers when log fields are added or changed
  • Align logging entry types with the rest of the kernel library C interface
  • P3 because it improves ABI extensibility for kernel consumers by avoiding a fixed struct layout
  • It is an internal C API refinement and reasonably deferrable
  • Ready to review
  • Strong support with no open objections
  • Verified by testing all getters from the logging callback locally (musaHaruna)
  • Approval without stated reasons after docstring style query was answered (sedited)
  • 175 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 78 lines removed in total
  • 3 files, 1 commits
(+)#36632 fametrano kernel: document the import_blocks abortP3 · cleanupReady0Positive11
  • 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
  • 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
  • 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
(+)#36353 FlashWayne kernel: document that blocks cache their check resultsP3 · cleanupReady0 (+2) -1Mild11
  • Warn libbitcoinkernel users in API docs that block validation results are cached across shallow copies
  • Prevent API consumers from inadvertently skipping validation when reusing blocks across parameter sets
  • P3 because it is a documentation-only clarification of C API invariants for library consumers
  • Helps external callers avoid unintended validation bypasses when reusing block objects
  • Ranking pass: Moved up two bands' worth of positions relative to its score because it warns of a silent validation bypass (cached fChecked across parameter sets), a correctness hazard for consumers rather than ordinary doc polish.
  • Review is worthwhile now as the documentation changes are ready
  • Objection to copy overhead on checks led author to rework this into documentation only (sedited)
  • Documentation wording refined to detail exact conditions under which checks are cached (alexanderwiederin)
  • Concept approval without stated reasons (l0rinc)
  • 11 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 0 lines removed in total
  • 1 files, 3 commits
(+)#33820 stickies-v kernel: trim Chain interfaceP4 · cleanupAuthor 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
  • 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
  • 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
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.
Ranking pass (2026-11-01): all PRs here were compared with each other; 11 notes on review order, overlaps, and band changes.

Covers

The libbitcoinkernel project: the C and C++ kernel API, its headers and bindings, the boundary between the kernel and the rest of the node (notifications, logging callbacks, error reporting, context and options objects), the bitcoin-chainstate example, kernel tests, and refactors whose stated purpose is to make validation usable as a library. The Kernel label is a strong prior.

A kernel PR that also substantively changes validation logic is both kernel and validation, and probably needs splitting; say so.

Not kernel: changes inside validation that happen to compile into the kernel library but do not touch its API or its boundary.

What matters here

Whether external users can build on the library: API completeness for the stated use cases (validating blocks and transactions, reading chainstate, receiving notifications), API stability and versioning, correctness at the boundary (error propagation, thread safety, object lifetimes), and platform coverage. Then removing node dependencies from kernel code, which is the project's core work. Then documentation and examples that determine whether anyone outside the project can use it.

Renames and cosmetic API polish without a consumer asking for them are P3 or below.

generated 2026-11-02 01:17 UTC