kernel: add btck_block_tree_entry_equals
What changed, and why it matters
This commit adds a new public helper function that lets outside code compare two block tree entries to see if they point to the same block. It is a pure API convenience addition with no bug fix, behavior change, or security-sensitive logic.
No security action needed; routine API addition.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch exposes btck_block_tree_entry_equals() in the bitcoinkernel C API and wraps it as operator== in the C++ wrapper. The implementation compares the underlying C++ object addresses (identity equality). It also adds unit tests covering inequality, equality, and GetPrevious(). No existing behavior is modified.
Changed components
src/kernel/bitcoinkernel.cppsrc/kernel/bitcoinkernel.hsrc/kernel/bitcoinkernel_wrapper.hsrc/test/kernel/test_kernel.cppInspect captured patch +63 / −0
diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 240255bb..f59744bc 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -1104,6 +1104,11 @@ const btck_BlockHash* btck_block_tree_entry_get_block_hash(const btck_BlockTreeE
return btck_BlockHash::ref(btck_BlockTreeEntry::get(entry).phashBlock);
}
+int btck_block_tree_entry_equals(const btck_BlockTreeEntry* entry1, const btck_BlockTreeEntry* entry2)
+{
+ return &btck_BlockTreeEntry::get(entry1) == &btck_BlockTreeEntry::get(entry2);
+}
+
btck_BlockHash* btck_block_hash_create(const unsigned char block_hash[32])
{
return btck_BlockHash::create(std::span<const unsigned char>{block_hash, 32});
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 4c94b59f..7ff9dcc0 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -922,6 +922,17 @@ BITCOINKERNEL_API int32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry
BITCOINKERNEL_API const btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_block_hash(
const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
+/**
+ * @brief Check if two block tree entries are equal. Two block tree entries are equal when they
+ * point to the same block.
+ *
+ * @param[in] entry1 Non-null.
+ * @param[in] entry2 Non-null.
+ * @return 1 if the block tree entries are equal, 0 otherwise.
+ */
+BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_equals(
+ const btck_BlockTreeEntry* entry1, const btck_BlockTreeEntry* entry2) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
///@}
/** @name ChainstateManagerOptions
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index b847dde5..764c8a3d 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -786,6 +786,11 @@ public:
{
}
+ bool operator==(const BlockTreeEntry& other) const
+ {
+ return btck_block_tree_entry_equals(get(), other.get()) != 0;
+ }
+
std::optional<BlockTreeEntry> GetPrevious() const
{
auto entry{btck_block_tree_entry_get_previous(get())};
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index e1c9376d..e98a9c50 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -797,6 +797,48 @@ BOOST_AUTO_TEST_CASE(btck_block_hash_tests)
CheckHandle(block_hash, block_hash_2);
}
+BOOST_AUTO_TEST_CASE(btck_block_tree_entry_tests)
+{
+ auto test_directory{TestDirectory{"block_tree_entry_test_bitcoin_kernel"}};
+ auto notifications{std::make_shared<TestKernelNotifications>()};
+ auto context{create_context(notifications, ChainType::REGTEST)};
+ auto chainman{create_chainman(
+ test_directory,
+ /*reindex=*/false,
+ /*wipe_chainstate=*/false,
+ /*block_tree_db_in_memory=*/true,
+ /*chainstate_db_in_memory=*/true,
+ context)};
+
+ // Process a couple of blocks
+ for (size_t i{0}; i < 3; i++) {
+ Block block{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[i])};
+ bool new_block{false};
+ chainman->ProcessBlock(block, &new_block);
+ BOOST_CHECK(new_block);
+ }
+
+ auto chain{chainman->GetChain()};
+ auto entry_0{chain.GetByHeight(0)};
+ auto entry_1{chain.GetByHeight(1)};
+ auto entry_2{chain.GetByHeight(2)};
+
+ // Test inequality
+ BOOST_CHECK(entry_0 != entry_1);
+ BOOST_CHECK(entry_1 != entry_2);
+ BOOST_CHECK(entry_0 != entry_2);
+
+ // Test equality with same entry
+ BOOST_CHECK(entry_0 == chain.GetByHeight(0));
+ BOOST_CHECK(entry_0 == BlockTreeEntry{entry_0});
+ BOOST_CHECK(entry_1 == entry_1);
+
+ // Test GetPrevious
+ auto prev{entry_1.GetPrevious()};
+ BOOST_CHECK(prev.has_value());
+ BOOST_CHECK(prev.value() == entry_0);
+}
+
BOOST_AUTO_TEST_CASE(btck_chainman_in_memory_tests)
{
auto in_memory_test_directory{TestDirectory{"in-memory_test_bitcoin_kernel"}};
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.