kernel: Add block header support and validation

yuvicc commented at 5:16 pm on November 7, 2025: contributor

Adds a new btck_BlockHeader type and associated functions to create, access, and validate block headers. Block headers will have their own type (btck_BlockHeader) that can be created from raw data, copied, and queried for all the standard header fields (hash, prev hash, timestamp, bits, version, nonce). We can also extract headers from full blocks or block tree entries.

New Block Header API

btck_BlockHeader type: Opaque handle for block headers
Header methods:
- btck_block_header_create(): Create header from 80-byte serialized data
- btck_block_header_copy(): Copy block headers
- btck_block_header_destroy(): Destroy header object
- btck_block_header_get_hash(): Calculate block hash
- btck_block_header_get_prev_hash(): Get previous block hash
- btck_block_header_get_timestamp(): Get block timestamp
- btck_block_header_get_bits(): Get difficulty target (compact format)
- btck_block_header_get_version(): Get block version
- btck_block_header_get_nonce(): Get proof-of-work nonce
- btck_block_get_header(): Extract header from a full block
- btck_block_tree_entry_get_block_header(): Get header associated with a block tree entry

Testing

Added tests in test_kernel.cpp that cover creating headers from raw data, extracting all header fields, and processing headers through the chainstate manager.

CC @TheCharlatan

DrahtBot commented at 5:16 pm on November 7, 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/33822.

Reviews

See the guideline for information on the review process.

Type	Reviewers
Approach ACK	TheCharlatan

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:

#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:

passes in block header -> passed-in block header (or “passed block header”) [original phrase is unclear/incorrect English; it should indicate the header being passed into the function]
Must be destroyed btck_block_hash_destroy(). -> Must be destroyed with btck_block_hash_destroy(). [missing preposition “with” makes the sentence ungrammatical]

drahtbot_id_5_m

fanquake renamed this:
~~[kernel] Add block header support and validation~~
kernel: Add block header support and validation
on Nov 7, 2025

DrahtBot added the label Validation on Nov 7, 2025

fanquake commented at 5:27 pm on November 7, 2025: member

https://github.com/bitcoin/bitcoin/actions/runs/19175802541/job/54820162776?pr=33822#step:5:179:

0<snip>
1src/kernel/bitcoinkernel.h:1726: * 
2src/kernel/bitcoinkernel_wrapper.h:759:    
3src/kernel/bitcoinkernel_wrapper.h:762:    
4^^^
5Trailing whitespace (including Windows line endings [CR LF]) is problematic

DrahtBot added the label CI failed on Nov 7, 2025

DrahtBot commented at 5:27 pm on November 7, 2025: contributor

🚧 At least one of the CI tasks failed. Task lint: https://github.com/bitcoin/bitcoin/actions/runs/19175802541/job/54820162776 LLM reason (✨ experimental): Trailing whitespace detected by lint, causing the CI to fail.

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.

yuvicc force-pushed on Nov 8, 2025

yuvicc commented at 5:20 am on November 8, 2025: contributor

Fixed some lint errors.

Kernel: Add support for block headers

Co-authored-by: TheCharlatan <seb.kung@gmail.com>

86958ee668

yuvicc force-pushed on Nov 8, 2025

DrahtBot removed the label CI failed on Nov 8, 2025

in src/bitcoin-chainstate.cpp:47 in 86958ee668

43@@ -44,17 +44,17 @@ class TestValidationInterface : public ValidationInterface
44 
45     std::optional<std::string> m_expected_valid_block = std::nullopt;
46 
47-    void BlockChecked(const Block block, const BlockValidationState state) override
48+    void BlockChecked(Block block, const BlockValidationStateView view) override

TheCharlatan commented at 11:42 am on November 9, 2025:

I think the variable name state should just be kept.

in src/test/kernel/test_kernel.cpp:581 in 86958ee668

573@@ -574,6 +574,14 @@ BOOST_AUTO_TEST_CASE(btck_context_tests)
574     }
575 }
576 
577+BOOST_AUTO_TEST_CASE(btck_block_header_tests)
578+{
579+    BlockHeader header_0{hex_string_to_byte_vec("00e07a26beaaeee2e71d7eb19279545edbaf15de0999983626ec00000000000000000000579cf78b65229bfb93f4a11463af2eaa5ad91780f27f5d147a423bea5f7e4cdf2a47e268b4dd01173a9662ee")};
580+    BOOST_CHECK_EQUAL(byte_span_to_hex_string_reversed(header_0.Hash().ToBytes()), "00000000000000000000325c7e14a4ee3b4fcb2343089a839287308a0ddbee4f");
581+    BlockHeader header_1{hex_string_to_byte_vec("00c00020e7cb7b4de21d26d55bd384017b8bb9333ac3b2b55bed00000000000000000000d91b4484f801b99f03d36b9d26cfa83420b67f81da12d7e6c1e7f364e743c5ba9946e268b4dd011799c8533d")};

TheCharlatan commented at 1:23 pm on November 9, 2025:

Can you add BOOST_CHECK_THROW(BlockHeader{hex_string_to_byte_vec("00")}, std::runtime_error);?

in src/kernel/bitcoinkernel.cpp:1311 in 86958ee668

1306+btck_BlockHeader* btck_block_header_create(const void* raw_block_header, size_t raw_block_header_len)
1307+{
1308+    if (raw_block_header_len != 80) {
1309+        LogError("invalid header length %zu (expected 80)", raw_block_header_len);
1310+        return nullptr;
1311+    }

TheCharlatan commented at 1:36 pm on November 9, 2025:

I wouldn’t add this length check here and would instead just rely on the exception. We do the same thing in the rpc too: submitheader just calls DecodeHexBlockHeader, which doesn’t have a length check either.

in src/kernel/bitcoinkernel.cpp:1267 in 86958ee668

1262+    btck_ChainstateManager* chainstate_manager,
1263+    const btck_BlockHeader* header,
1264+    btck_BlockValidationState* state)
1265+{
1266+    auto& chainman = btck_ChainstateManager::get(chainstate_manager).m_chainman;
1267+    auto result = chainman->ProcessNewBlockHeaders({&btck_BlockHeader::get(header), 1}, true, btck_BlockValidationState::get(state), nullptr);

TheCharlatan commented at 1:42 pm on November 9, 2025:

I saw that in your own patch, you wrapped this call in a try-catch block. As far as I can tell we should not run into an exception here, but maybe it is still better to add it for defensive reasons?

yancyribbens commented at 4:42 pm on November 9, 2025:

Isn’t this something the fuzz harness can help answer?

in src/kernel/bitcoinkernel.cpp:1268 in 86958ee668

1263+    const btck_BlockHeader* header,
1264+    btck_BlockValidationState* state)
1265+{
1266+    auto& chainman = btck_ChainstateManager::get(chainstate_manager).m_chainman;
1267+    auto result = chainman->ProcessNewBlockHeaders({&btck_BlockHeader::get(header), 1}, true, btck_BlockValidationState::get(state), nullptr);
1268+    return result ? 0 : -1;

TheCharlatan commented at 1:54 pm on November 9, 2025:

One thing that could be considered here is returning the BlockValidationState directly instead of having an in/out param. To safely do that I think we’d need to refactor ProcessNewBlockHeaders though, similarly to what was done in https://github.com/bitcoin/bitcoin/commit/74690f4ed82b1584abb07c0387db0d924c4c0cab. Not sure that is worth it.

in src/kernel/bitcoinkernel.h:1244 in 86958ee668

1237@@ -1184,6 +1238,11 @@ BITCOINKERNEL_API void btck_block_destroy(btck_Block* block);
1238  */
1239 ///@{
1240 
1241+/**
1242+ * Create a new block validation state.
1243+ */
1244+BITCOINKERNEL_API btck_BlockValidationState* btck_block_validation_state_create();

TheCharlatan commented at 1:57 pm on November 9, 2025:

This (and btck_block_validation_state_copy needs BITCOINKERNEL_WARN_UNUSED_RESULT

TheCharlatan commented at 2:00 pm on November 9, 2025: contributor

Approach ACK

Aa777263100 commented at 4:52 pm on November 9, 2025: none

نعم اريد سحب

hsan saed abd alwhap

في الأحد، 9 نوفمبر 2025 7:43 م yancy @.***> كتب:

@.**** commented on this pull request.

In src/kernel/bitcoinkernel.cpp https://github.com/bitcoin/bitcoin/pull/33822#discussion_r2508162294:

@@ -1225,6 +1258,16 @@ int btck_chainstate_manager_process_block( return result ? 0 : -1; }

+int btck_chainstate_manager_process_block_header(

btck_ChainstateManager* chainstate_manager,

const btck_BlockHeader* header,

btck_BlockValidationState* state) +{

auto& chainman = btck_ChainstateManager::get(chainstate_manager).m_chainman;

auto result = chainman->ProcessNewBlockHeaders({&btck_BlockHeader::get(header), 1}, true, btck_BlockValidationState::get(state), nullptr);

Isn’t this something the fuzz harness can help answer?

— Reply to this email directly, view it on GitHub https://github.com/bitcoin/bitcoin/pull/33822#discussion_r2508162294, or unsubscribe https://github.com/notifications/unsubscribe-auth/BVZIU6M4XOH3WNDVIC2JYLD335VLNAVCNFSM6AAAAACLO3ZMFSVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTINBQGEZDOOBQGY . You are receiving this because you are subscribed to this thread.Message ID: @.***>