Add BlockUndo

Author: stringintech

TODO.md

@@ -4,9 +4,7 @@ This document lists the remaining C API functions and data structures from [`bit
 
 ## Missing Data Structures
 
-### Core Transaction Types
 - **`kernel_BlockPointer`** - Non-owned block pointers (from callbacks)
-- **`kernel_BlockUndo`** - Block undo data operations
 
 ## Missing Functions by Category
 
@@ -15,15 +13,7 @@ This document lists the remaining C API functions and data structures from [`bit
 
 ### Block Operations (Additional)
 - [ ] `kernel_block_pointer_get_hash()` - Get hash from block pointer
-- [ ] `kernel_copy_block_pointer_data()` - Copy data from block pointer  
-
-### Block Undo Operations
-- [ ] `kernel_read_block_undo_from_disk()` - Read undo data from disk
-- [ ] `kernel_block_undo_size()` - Get number of transactions in undo data
-- [ ] `kernel_get_transaction_undo_size()` - Get output count per transaction
-- [ ] `kernel_get_undo_output_height_by_index()` - Get output block height
-- [ ] `kernel_get_undo_output_by_index()` - Get specific undo output
-- [ ] `kernel_block_undo_destroy()` - Cleanup undo data
+- [ ] `kernel_copy_block_pointer_data()` - Copy data from block pointer
 
 ### Callback Support
 - [ ] **Notification callbacks** - Full integration of kernel notification system

kernel/block_undo.go

@@ -0,0 +1,69 @@
+package kernel
+
+/*
+#include "kernel/bitcoinkernel.h"
+*/
+import "C"
+import (
+	"runtime"
+)
+
+// BlockUndo wraps the C kernel_BlockUndo
+type BlockUndo struct {
+	ptr *C.kernel_BlockUndo
+}
+
+// Size returns the number of transactions whose undo data is contained in block undo
+func (bu *BlockUndo) Size() uint64 {
+	if bu.ptr == nil {
+		return 0
+	}
+	return uint64(C.kernel_block_undo_size(bu.ptr))
+}
+
+// GetTransactionUndoSize returns the number of previous transaction outputs
+// contained in the transaction undo data at the specified index
+func (bu *BlockUndo) GetTransactionUndoSize(transactionUndoIndex uint64) uint64 {
+	if bu.ptr == nil {
+		return 0
+	}
+	return uint64(C.kernel_get_transaction_undo_size(bu.ptr, C.uint64_t(transactionUndoIndex)))
+}
+
+// GetUndoOutputHeightByIndex returns the block height of the block that contains
+// the output at output_index within the transaction undo data at the provided index
+func (bu *BlockUndo) GetUndoOutputHeightByIndex(transactionUndoIndex, outputIndex uint64) uint32 {
+	if bu.ptr == nil {
+		return 0
+	}
+	return uint32(C.kernel_get_undo_output_height_by_index(bu.ptr, C.uint64_t(transactionUndoIndex), C.uint64_t(outputIndex)))
+}
+
+// GetUndoOutputByIndex returns a transaction output contained in the transaction
+// undo data at the specified indices
+func (bu *BlockUndo) GetUndoOutputByIndex(transactionUndoIndex, outputIndex uint64) (*TransactionOutput, error) {
+	if bu.ptr == nil {
+		return nil, ErrInvalidBlockUndo
+	}
+
+	ptr := C.kernel_get_undo_output_by_index(bu.ptr, C.uint64_t(transactionUndoIndex), C.uint64_t(outputIndex))
+	if ptr == nil {
+		return nil, ErrUndoOutputRetrieval
+	}
+
+	output := &TransactionOutput{ptr: ptr}
+	runtime.SetFinalizer(output, (*TransactionOutput).destroy)
+	return output, nil
+}
+
+func (bu *BlockUndo) destroy() {
+	if bu.ptr != nil {
+		C.kernel_block_undo_destroy(bu.ptr)
+		bu.ptr = nil
+	}
+}
+
+func (bu *BlockUndo) Destroy() {
+	runtime.SetFinalizer(bu, nil)
+	bu.destroy()
+}

kernel/chainstate_manager.go

@@ -60,6 +60,25 @@ func (cm *ChainstateManager) ReadBlockFromDisk(blockIndex *BlockIndex) (*Block,
 	return block, nil
 }
 
+// ReadBlockUndoFromDisk reads block undo data from disk for a given block index
+func (cm *ChainstateManager) ReadBlockUndoFromDisk(blockIndex *BlockIndex) (*BlockUndo, error) {
+	if cm.ptr == nil || cm.context == nil || cm.context.ptr == nil {
+		return nil, ErrChainstateManagerCreation
+	}
+	if blockIndex == nil || blockIndex.ptr == nil {
+		return nil, ErrInvalidBlockIndex
+	}
+
+	ptr := C.kernel_read_block_undo_from_disk(cm.context.ptr, cm.ptr, blockIndex.ptr)
+	if ptr == nil {
+		return nil, ErrBlockUndoRead
+	}
+
+	blockUndo := &BlockUndo{ptr: ptr}
+	runtime.SetFinalizer(blockUndo, (*BlockUndo).destroy)
+	return blockUndo, nil
+}
+
 // ProcessBlock processes and validates a block
 func (cm *ChainstateManager) ProcessBlock(block *Block) (bool, bool, error) {
 	if cm.ptr == nil || cm.context == nil || cm.context.ptr == nil {

kernel/chainstate_manager_test.go

@@ -13,6 +13,7 @@ func TestChainstateManager(t *testing.T) {
 
 	t.Run("genesis validation", suite.TestGenesis)
 	t.Run("tip validation", suite.TestTip)
+	t.Run("block undo", suite.TestBlockUndo)
 }
 
 func (s *ChainstateManagerTestSuite) TestGenesis(t *testing.T) {
@@ -67,6 +68,44 @@ func (s *ChainstateManagerTestSuite) TestTip(t *testing.T) {
 	}
 }
 
+func (s *ChainstateManagerTestSuite) TestBlockUndo(t *testing.T) {
+	blockIndex, err := s.Manager.GetBlockIndexFromHeight(202)
+	if err != nil {
+		t.Fatalf("GetBlockIndexFromHeight(202) error = %v", err)
+	}
+	defer blockIndex.Destroy()
+
+	blockUndo, err := s.Manager.ReadBlockUndoFromDisk(blockIndex)
+	if err != nil {
+		t.Fatalf("ReadBlockUndoFromDisk() error = %v", err)
+	}
+	defer blockUndo.Destroy()
+
+	// Test transaction count
+	txCount := blockUndo.Size()
+	if txCount != 20 {
+		t.Errorf("Expected 20 transactions, got %d", txCount)
+	}
+
+	// Verify each transaction is a valid TransactionUndo
+	for i := uint64(0); i < txCount; i++ {
+		undoSize := blockUndo.GetTransactionUndoSize(i)
+		if undoSize != 1 {
+			t.Errorf("Expected transaction undo size 1, got %d", undoSize)
+		}
+
+		_, err := blockUndo.GetUndoOutputByIndex(i, 0)
+		if err != nil {
+			t.Fatalf("GetUndoOutputByIndex() error = %v", err)
+		}
+
+		height := blockUndo.GetUndoOutputHeightByIndex(i, 0)
+		if height <= 0 {
+			t.Fatalf("GetUndoOutputHeightByIndex() height %d, want > 0", height)
+		}
+	}
+}
+
 type ChainstateManagerTestSuite struct {
 	Manager             *ChainstateManager
 	ImportedBlocksCount int32

kernel/errors.go

@@ -28,4 +28,7 @@ var (
 	ErrTransactionOutputCreation        = errors.New("failed to create transaction output")
 	ErrInvalidTransactionOutput         = errors.New("invalid transaction output")
 	ErrScriptPubkeyCopyFromOutput       = errors.New("failed to copy script pubkey from output")
+	ErrBlockUndoRead                    = errors.New("failed to read block undo from disk")
+	ErrInvalidBlockUndo                 = errors.New("invalid block undo")
+	ErrUndoOutputRetrieval              = errors.New("failed to retrieve undo output")
 )