kernel: add context‑free block validation API (btck_check_block_context_free) with POW/Merkle flags #33908

pull w0xlt wants to merge 3 commits into bitcoin:master from w0xlt:kerne_checkblock changing 5 files +165 −28
  1. w0xlt commented at 11:37 pm on November 18, 2025: contributor

    This PR exposes Bitcoin Core’s context‑free block checks to library users via a new C API entry point, btck_check_block_context_free.

    Callers can validate a block’s structure (size/weight, coinbase rules, per‑tx context‑free checks) and optionally re‑run Proof‑of‑Work and Merkle‑root verification without touching chainstate, the block index, or the UTXO set.

    Rationale Clients embedding the kernel need a pure block sanity check without requiring node state or disk writes (candidate block validation, for example). This API offers that surface in a single call, with optional PoW/Merkle toggles to avoid redundant work when the header has already been validated or when Merkle verification is deferred.

  2. DrahtBot added the label Validation on Nov 18, 2025
  3. DrahtBot commented at 11:37 pm on November 18, 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/33908.

    Reviews

    See the guideline for information on the review process.

    Type Reviewers
    Approach ACK yuvicc

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

    Conflicts

    Reviewers, this pull request conflicts with the following ones:

    • #33891 (kernel: Expose reusable PrecomputedTransactionData in script validation by joshdoman)
    • #33856 (kernel, validation: Refactor ProcessNewBlock(Headers) to return BlockValidationState by yuvicc)
    • #33822 (kernel: Add block header support and validation by yuvicc)
    • #33796 (kernel: Expose CheckTransaction consensus validation function by w0xlt)

    If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

    LLM Linter (✨ experimental)

    Possible typos and grammar issues:

    • “The returned consensus params is not owned and depends on the lifetime of the chain parameters.” -> “The returned consensus params are not owned and depend on the lifetime of the chain parameters.” [subject “consensus params” is plural so verbs must be plural]

    drahtbot_id_5_m

  4. w0xlt force-pushed on Nov 18, 2025
  5. DrahtBot added the label CI failed on Nov 18, 2025
  6. DrahtBot removed the label CI failed on Nov 19, 2025
  7. yuvicc commented at 10:22 am on November 19, 2025: contributor

    Concept ACK, Approach NACK from my side.

    Currently, btck_check_block_context_free requires a full btck_Context*, but it only usescontext->m_chainparams->GetConsensus(). Library user will need to maintain a full context object just to perform context-free block validation checks which I think is not a good idea. Also, the function doesn’t clearly communicate that only consensus params are needed and not full context. I think a better approach could be to expose opaque struct for consensus params (btck_ConsensusParams). This makes the API lighter-weight and more clearly expresses the actual behaviour. I’ve been working on a similar implementation to expose context free checkblock and made a patch. The wrapper and test_kernel also needs to be updated.

    The use of bitflags for extensibility look good imo.

  8. purpleKarrot commented at 11:10 am on November 19, 2025: contributor
    Both @w0xlt and @yuvicc, please don’t introduce more boolean traps.
  9. kernel: Expose consensus parameters (`btck_ConsensusParams`) 
    Library users currently need to maintain a full context object to perform
context-free block validation. Exposing an opaque `btck_ConsensusParams`
struct allows callers to supply only the required consensus parameters,
resulting in a lighter-weight API and a clearer expression of the actual
validation behavior.

Co-authored-by: yuvicc <yuvichh01@gmail.com>
    1a1b7929fe
  10. w0xlt force-pushed on Nov 20, 2025
  11. kernel: Fix BlockValidationState ownership for context-free checks 
    This change exposes create and destroy functions for
`btck_BlockValidationState` in the C API and splits the C++ wrapper
into an owning `BlockValidationState` (which allocates memory) and a
non-owning `BlockValidationStateView`.

Co-authored-by: yuvicc <yuvichh01@gmail.com>
    c5071d173d
  12. kernel: Expose context-free block validation 
    This introduces a context-free validation entry point for full blocks in
the kernel C and C++ APIs.

* Add `btck_block_check`, a C function that wraps `CheckBlock` and runs
header and body checks for a `btck_Block` using `btck_ConsensusParams`.
Callers provide a `btck_BlockValidationState` to receive the result
and supply a `btck_BlockCheckFlags` bitmask to control POW and
merkle-root verification.

* Add `btck_BlockCheckFlags` in the C API, plus the corresponding
`BlockCheckFlags` scoped enum in the C++ wrapper, including a
`*_ALL` convenience value.

* Add `Block::Check()` to the C++ wrapper to mirror the new C function
and return a bool while filling a `BlockValidationState`.

* Add a test `(btck_check_block_context_free)` that verifies a known
valid mainnet block passes with `BlockCheckFlags::ALL` and that
truncated block data fails deserialization.

Co-authored-by: yuvicc <yuvichh01@gmail.com>
    824b5c4756
  13. w0xlt force-pushed on Nov 20, 2025
  14. DrahtBot added the label CI failed on Nov 20, 2025
  15. DrahtBot commented at 0:18 am on November 20, 2025: contributor

    🚧 At least one of the CI tasks failed. Task ASan + LSan + UBSan + integer: https://github.com/bitcoin/bitcoin/actions/runs/19520546781/job/55882840198 LLM reason (✨ experimental): C++ compile error: overridden BlockChecked signature mismatches base (hides virtual with BlockValidationState vs BlockValidationStateView).

    Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

    • Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.

    • A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.

    • An intermittent issue.

    Leave a comment here, if you need help tracking down a confusing failure.

  16. w0xlt commented at 0:23 am on November 20, 2025: contributor

    Thanks for the review @yuvicc and @purpleKarrot .

    Great idea exposing the chain parameter class. I’ve updated the PR to follow this approach and split it into three commits for better readability and easier reviewing (and added @yuvicc as co-author). I also had to update BlockValidationState so the reference parameter works correctly. I kept btck_BlockCheckFlags to avoid unclear boolean parameters.

  17. DrahtBot removed the label CI failed on Nov 20, 2025
  18. in src/kernel/bitcoinkernel.h:1200 in c5071d173d outdated 
    1191@@ -1192,6 +1192,17 @@ BITCOINKERNEL_API int btck_block_to_bytes(
1192  */
1193 BITCOINKERNEL_API void btck_block_destroy(btck_Block* block);
1194 
1195+/**
1196+ * @brief Create a new block validation state.
1197+ * @return The block validation state, or null on error.
1198+ */
1199+BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_validation_state_create();
1200+
    yuvicc commented at 9:24 am on November 20, 2025:

    I think we also expose _copy API here:

    0
1/**
2 * [@brief](/bitcoin-bitcoin/contributor/brief/) Copies the block validation state.
3 *
4 * [@param](/bitcoin-bitcoin/contributor/param/)[in] block_validation_state Non-null.
5 * [@return](/bitcoin-bitcoin/contributor/return/)                           The copied block validation state.
6 */
7BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_validation_state_copy(
8    const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);
  19. in src/kernel/bitcoinkernel_wrapper.h:732 in c5071d173d outdated 
    727+{
728+public:
729+    explicit BlockValidationStateView(const btck_BlockValidationState* ptr) : View{ptr} {}
730+};
731+
732+class BlockValidationState : public UniqueHandle<btck_BlockValidationState, btck_block_validation_state_destroy>, public BlockValidationStateApi<BlockValidationState>
    yuvicc commented at 9:26 am on November 20, 2025:

    And then use Handle instead of UniqueHandle here:

    0class BlockValidationState : public Handle<btck_BlockValidationState, btck_block_validation_state_copy, btck_block_validation_state_destroy>, public BlockValidationStateApi<BlockValidationState>
  20. in src/kernel/bitcoinkernel_wrapper.h:735 in c5071d173d outdated 
    730+};
731+
732+class BlockValidationState : public UniqueHandle<btck_BlockValidationState, btck_block_validation_state_destroy>, public BlockValidationStateApi<BlockValidationState>
733+{
734+public:
735+    BlockValidationState() : UniqueHandle{btck_block_validation_state_create()} {}
    yuvicc commented at 9:27 am on November 20, 2025:

    Also here:

    0explicit BlockValidationState() : Handle{btck_block_validation_state_create()} {}
  21. yuvicc commented at 9:29 am on November 20, 2025: contributor

    Approach ACK

    Thanks for taking my suggestion.


w0xlt DrahtBot yuvicc purpleKarrot

Labels
Validation

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2025-11-30 00:13 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me