kernel: add btck_Chain API alongside btck_BlockTreeEntry

Introduce a chain-oriented view of the block index that consumers can
use instead of btck_BlockTreeEntry. A btck_Chain represents the linear
sequence of blocks from tip back to genesis; because a
block uniquely determines its path to genesis, a chain is fully
determined by its tip and shares the same underlying CBlockIndex as the
corresponding block tree entry.

New chain functions:
  - btck_chainstate_manager_get_best_chain / _find return chains
  - btck_chain_get_block_header / _get_block_hash / _get_ancestor
  - btck_chain_get_parent (O(1) step towards genesis)
  - btck_chain_starts_with / _mismatch / _equals

A new equivalence test to test the chain-based and entry-based queries return
identical results (height, hash, header, lookup-by-hash, membership,
block and spent-output reads, and previous-block stepping).

Author: janb84

src/kernel/bitcoinkernel.cpp

@@ -150,6 +150,9 @@ struct btck_BlockTreeEntry: Handle<btck_BlockTreeEntry, CBlockIndex> {};
 struct btck_Block : Handle<btck_Block, std::shared_ptr<const CBlock>> {};
 struct btck_BlockValidationState : Handle<btck_BlockValidationState, BlockValidationState> {};
 struct btck_TxValidationState : Handle<btck_TxValidationState, TxValidationState> {};
+// A chain is fully determined by its tip block, so it is represented by the
+// CBlockIndex of that tip - the same underlying type as a btck_BlockTreeEntry.
+struct btck_Chain : Handle<btck_Chain, CBlockIndex> {};
 
 namespace {
 
@@ -494,7 +497,6 @@ struct btck_Context : Handle<btck_Context, std::shared_ptr<const Context>> {};
 struct btck_ChainParameters : Handle<btck_ChainParameters, CChainParams> {};
 struct btck_ChainstateManagerOptions : Handle<btck_ChainstateManagerOptions, ChainstateManagerOptions> {};
 struct btck_ChainstateManager : Handle<btck_ChainstateManager, ChainMan> {};
-struct btck_Chain : Handle<btck_Chain, CChain> {};
 struct btck_BlockSpentOutputs : Handle<btck_BlockSpentOutputs, std::shared_ptr<CBlockUndo>> {};
 struct btck_TransactionSpentOutputs : Handle<btck_TransactionSpentOutputs, CTxUndo> {};
 struct btck_Coin : Handle<btck_Coin, Coin> {};
@@ -912,6 +914,32 @@ const btck_BlockTreeEntry* btck_block_tree_entry_get_ancestor(const btck_BlockTr
     return btck_BlockTreeEntry::ref(ancestor);
 }
 
+btck_BlockHeader* btck_block_tree_entry_get_block_header(const btck_BlockTreeEntry* entry)
+{
+    return btck_BlockHeader::create(btck_BlockTreeEntry::get(entry).GetBlockHeader());
+}
+
+int32_t btck_block_tree_entry_get_height(const btck_BlockTreeEntry* entry)
+{
+    return btck_BlockTreeEntry::get(entry).nHeight;
+}
+
+const btck_BlockHash* btck_block_tree_entry_get_block_hash(const btck_BlockTreeEntry* entry)
+{
+    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);
+}
+
+const btck_Chain* btck_block_tree_entry_get_chain(const btck_BlockTreeEntry* entry)
+{
+    // A chain and a block tree entry share the same underlying CBlockIndex.
+    return btck_Chain::ref(&btck_BlockTreeEntry::get(entry));
+}
+
 btck_BlockValidationState* btck_block_validation_state_create()
 {
     return btck_BlockValidationState::create();
@@ -1062,6 +1090,17 @@ btck_ChainstateManager* btck_chainstate_manager_create(
     return btck_ChainstateManager::create(std::move(chainman), opts.m_context);
 }
 
+const btck_Chain* btck_chainstate_manager_find(const btck_ChainstateManager* chainman, const btck_BlockHash* block_hash)
+{
+    auto block_index = WITH_LOCK(btck_ChainstateManager::get(chainman).m_chainman->GetMutex(),
+                                 return btck_ChainstateManager::get(chainman).m_chainman->m_blockman.LookupBlockIndex(btck_BlockHash::get(block_hash)));
+    if (!block_index) {
+        LogDebug(BCLog::KERNEL, "A block with the given hash is not indexed.");
+        return nullptr;
+    }
+    return btck_Chain::ref(block_index);
+}
+
 const btck_BlockTreeEntry* btck_chainstate_manager_get_block_tree_entry_by_hash(const btck_ChainstateManager* chainman, const btck_BlockHash* block_hash)
 {
     auto block_index = WITH_LOCK(btck_ChainstateManager::get(chainman).m_chainman->GetMutex(),
@@ -1073,6 +1112,12 @@ const btck_BlockTreeEntry* btck_chainstate_manager_get_block_tree_entry_by_hash(
     return btck_BlockTreeEntry::ref(block_index);
 }
 
+const btck_Chain* btck_chainstate_manager_get_best_chain(const btck_ChainstateManager* chainstate_manager)
+{
+    auto& chainman = *btck_ChainstateManager::get(chainstate_manager).m_chainman;
+    return btck_Chain::ref(WITH_LOCK(chainman.GetMutex(), return chainman.m_best_header));
+}
+
 const btck_BlockTreeEntry* btck_chainstate_manager_get_best_entry(const btck_ChainstateManager* chainstate_manager)
 {
     auto& chainman = *btck_ChainstateManager::get(chainstate_manager).m_chainman;
@@ -1196,26 +1241,6 @@ btck_Block* btck_block_read(const btck_ChainstateManager* chainman, const btck_B
     return btck_Block::create(block);
 }
 
-btck_BlockHeader* btck_block_tree_entry_get_block_header(const btck_BlockTreeEntry* entry)
-{
-    return btck_BlockHeader::create(btck_BlockTreeEntry::get(entry).GetBlockHeader());
-}
-
-int32_t btck_block_tree_entry_get_height(const btck_BlockTreeEntry* entry)
-{
-    return btck_BlockTreeEntry::get(entry).nHeight;
-}
-
-const btck_BlockHash* btck_block_tree_entry_get_block_hash(const btck_BlockTreeEntry* entry)
-{
-    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});
@@ -1355,25 +1380,93 @@ btck_BlockValidationState* btck_chainstate_manager_process_block_header(
 
 const btck_Chain* btck_chainstate_manager_get_active_chain(const btck_ChainstateManager* chainman)
 {
-    return btck_Chain::ref(&WITH_LOCK(btck_ChainstateManager::get(chainman).m_chainman->GetMutex(), return btck_ChainstateManager::get(chainman).m_chainman->ActiveChain()));
+    return btck_Chain::ref(WITH_LOCK(btck_ChainstateManager::get(chainman).m_chainman->GetMutex(), return btck_ChainstateManager::get(chainman).m_chainman->ActiveChain().Tip()));
 }
 
 int32_t btck_chain_get_height(const btck_Chain* chain)
 {
     LOCK(::cs_main);
-    return btck_Chain::get(chain).Height();
+    return btck_Chain::get(chain).nHeight;
+}
+
+const btck_BlockTreeEntry* btck_chain_get_tip(const btck_Chain* chain)
+{
+    // A chain and a block tree entry share the same underlying CBlockIndex.
+    return btck_BlockTreeEntry::ref(&btck_Chain::get(chain));
 }
 
 const btck_BlockTreeEntry* btck_chain_get_by_height(const btck_Chain* chain, int32_t height)
 {
     LOCK(::cs_main);
-    return btck_BlockTreeEntry::ref(btck_Chain::get(chain)[height]);
+    return btck_BlockTreeEntry::ref(btck_Chain::get(chain).GetAncestor(height));
 }
 
 int btck_chain_contains(const btck_Chain* chain, const btck_BlockTreeEntry* entry)
 {
     LOCK(::cs_main);
-    return btck_Chain::get(chain).Contains(btck_BlockTreeEntry::get(entry)) ? 1 : 0;
+    const auto& tip{btck_Chain::get(chain)};
+    const auto& block{btck_BlockTreeEntry::get(entry)};
+    return tip.GetAncestor(block.nHeight) == &block ? 1 : 0;
+}
+
+btck_BlockHeader* btck_chain_get_block_header(const btck_Chain* chain, int32_t height)
+{
+    const auto* index{btck_Chain::get(chain).GetAncestor(height)};
+    if (!index) {
+        LogDebug(BCLog::KERNEL, "The requested height is not in the chain.");
+        return nullptr;
+    }
+    return btck_BlockHeader::create(index->GetBlockHeader());
+}
+
+const btck_BlockHash* btck_chain_get_block_hash(const btck_Chain* chain, int32_t height)
+{
+    const auto* index{btck_Chain::get(chain).GetAncestor(height)};
+    if (!index) {
+        LogDebug(BCLog::KERNEL, "The requested height is not in the chain.");
+        return nullptr;
+    }
+    return btck_BlockHash::ref(index->phashBlock);
+}
+
+const btck_Chain* btck_chain_get_ancestor(const btck_Chain* chain, int32_t height)
+{
+    const auto* ancestor{btck_Chain::get(chain).GetAncestor(height)};
+    if (!ancestor) {
+        LogDebug(BCLog::KERNEL, "The requested height is not in the chain.");
+        return nullptr;
+    }
+    return btck_Chain::ref(ancestor);
+}
+
+const btck_Chain* btck_chain_get_parent(const btck_Chain* chain)
+{
+    const auto* pprev{btck_Chain::get(chain).pprev};
+    if (!pprev) {
+        return nullptr;
+    }
+    return btck_Chain::ref(pprev);
+}
+
+int btck_chain_starts_with(const btck_Chain* chain, const btck_Chain* prefix)
+{
+    const auto& tip{btck_Chain::get(chain)};
+    const auto& prefix_tip{btck_Chain::get(prefix)};
+    return tip.GetAncestor(prefix_tip.nHeight) == &prefix_tip ? 1 : 0;
+}
+
+const btck_Chain* btck_chain_mismatch(const btck_Chain* chain1, const btck_Chain* chain2)
+{
+    const auto* common{LastCommonAncestor(&btck_Chain::get(chain1), &btck_Chain::get(chain2))};
+    if (!common) {
+        return nullptr;
+    }
+    return btck_Chain::ref(common);
+}
+
+int btck_chain_equals(const btck_Chain* chain1, const btck_Chain* chain2)
+{
+    return &btck_Chain::get(chain1) == &btck_Chain::get(chain2) ? 1 : 0;
 }
 
 btck_BlockHeader* btck_block_header_create(const void* raw_block_header, size_t raw_block_header_len)