Add ValidationInterfaceCallbacks

Author: stringintech

.gitignore

@@ -1 +1,2 @@
-.idea
+.idea
+.cache

README.md

@@ -4,7 +4,7 @@ A Go wrapper for Bitcoin Core's [`libbitcoinkernel`](https://github.com/bitcoin/
 
 ## ⚠️ Work in Progress
 
-This library is currently under active development. Check [TODO.md](./TODO.md) for missing wrappers.
+This library is experimental and not production-ready. The underlying C API is subject to change, which may cause breaking changes in this wrapper. The wrapper itself may also change based on user feedback, which is welcome and appreciated. Feel free to open issues to help make this wrapper more useful for everyone.
 
 ## Overview
 
@@ -33,13 +33,7 @@ cd go-bitcoinkernel
 make build-kernel
 ```
 
-This command will:
-
-- Configure Bitcoin Core's CMake build system
-- Build only the `libbitcoinkernel` library
-- Use parallel compilation for faster builds
-
-Refer to Bitcoin Core's build documentation to for the minimum requirements to compile `libbitcoinkernel` from source:
+This command will configure Bitcoin Core's CMake build system and build only the `libbitcoinkernel` shared library. Refer to Bitcoin Core's build documentation to for the minimum requirements to compile `libbitcoinkernel` from source:
 ([Unix](./depend/bitcoin/doc/build-unix.md),
 [macOS](./depend/bitcoin/doc/build-osx.md),
 [Windows](./depend/bitcoin/doc/build-windows.md))

TODO.md

@@ -12,6 +12,7 @@ func TestChainstateManager(t *testing.T) {
 	suite := ChainstateManagerTestSuite{
 		MaxBlockHeightToImport: 0,   // load all blocks from data/regtest/block.txt
 		NotificationCallbacks:  nil, // no notification callbacks
+		ValidationCallbacks:    nil, // no validation callbacks
 	}
 	suite.Setup(t)
 
@@ -113,6 +114,7 @@ func (s *ChainstateManagerTestSuite) TestBlockUndo(t *testing.T) {
 type ChainstateManagerTestSuite struct {
 	MaxBlockHeightToImport int32 // leave zero to load all blocks
 	NotificationCallbacks  *NotificationCallbacks
+	ValidationCallbacks    *ValidationInterfaceCallbacks
 
 	Manager             *ChainstateManager
 	ImportedBlocksCount int32
@@ -149,6 +151,13 @@ func (s *ChainstateManagerTestSuite) Setup(t *testing.T) {
 		}
 	}
 
+	if s.ValidationCallbacks != nil {
+		err = contextOpts.SetValidationInterface(s.ValidationCallbacks)
+		if err != nil {
+			t.Fatalf("SetValidationInterface() error = %v", err)
+		}
+	}
+
 	ctx, err := NewContext(contextOpts)
 	if err != nil {
 		t.Fatalf("NewContext() error = %v", err)
@@ -204,7 +213,6 @@ func (s *ChainstateManagerTestSuite) Setup(t *testing.T) {
 	if len(blockLines) == 0 {
 		t.Fatal("No block data found in blocks.txt")
 	}
-	t.Logf("Found %d blocks in regtest data", len(blockLines))
 
 	for i := 0; i < len(blockLines); i++ {
 		blockHex := blockLines[i]

kernel/chainstate_manager_test.go

@@ -14,6 +14,7 @@ extern void go_notify_warning_set_bridge(void* user_data, kernel_Warning warning
 extern void go_notify_warning_unset_bridge(void* user_data, kernel_Warning warning);
 extern void go_notify_flush_error_bridge(void* user_data, char* message, size_t message_len);
 extern void go_notify_fatal_error_bridge(void* user_data, char* message, size_t message_len);
+extern void go_validation_interface_block_checked_bridge(void* user_data, const kernel_BlockPointer* block, const kernel_BlockValidationState* state);
 
 // Wrapper function: C helper to set notifications with Go callbacks
 // Converts Handle ID to void* and passes to C library
@@ -30,6 +31,16 @@ static inline void set_notifications_wrapper(kernel_ContextOptions* opts, uintpt
     };
     kernel_context_options_set_notifications(opts, callbacks);
 }
+
+// Wrapper function: C helper to set validation interface with Go callbacks
+// Converts Handle ID to void* and passes to C library
+static inline void set_validation_interface_wrapper(kernel_ContextOptions* opts, uintptr_t handle) {
+    kernel_ValidationInterfaceCallbacks callbacks = {
+        .user_data = (void*)handle,
+        .block_checked = (kernel_ValidationInterfaceBlockChecked)go_validation_interface_block_checked_bridge,
+    };
+    kernel_context_options_set_validation_interface(opts, callbacks);
+}
 */
 import "C"
 import (
@@ -43,6 +54,7 @@ var _ cManagedResource = &ContextOptions{}
 type ContextOptions struct {
 	ptr                *C.kernel_ContextOptions
 	notificationHandle cgo.Handle // Prevents notification callbacks GC until Destroy() called
+	validationHandle   cgo.Handle // Prevents validation callbacks GC until Destroy() called
 }
 
 func NewContextOptions() (*ContextOptions, error) {
@@ -87,6 +99,26 @@ func (opts *ContextOptions) SetNotifications(callbacks *NotificationCallbacks) e
 	return nil
 }
 
+// SetValidationInterface sets the validation interface callbacks for these context options.
+// The context created with these options will be configured with these validation callbacks.
+func (opts *ContextOptions) SetValidationInterface(callbacks *ValidationInterfaceCallbacks) error {
+	checkReady(opts)
+	if callbacks == nil {
+		return ErrNilValidationInterfaceCallbacks
+	}
+
+	// Create a handle for the callbacks - this prevents garbage collection
+	// and provides a stable ID that can be passed through C code safely
+	handle := cgo.NewHandle(callbacks)
+
+	// Call the C wrapper function to set all validation interface callbacks
+	C.set_validation_interface_wrapper(opts.ptr, C.uintptr_t(handle))
+
+	// Store the handle to prevent GC and allow cleanup
+	opts.validationHandle = handle
+	return nil
+}
+
 func (opts *ContextOptions) destroy() {
 	if opts.ptr != nil {
 		C.kernel_context_options_destroy(opts.ptr)
@@ -97,6 +129,11 @@ func (opts *ContextOptions) destroy() {
 		opts.notificationHandle.Delete()
 		opts.notificationHandle = 0
 	}
+	if opts.validationHandle != 0 {
+		// Delete exposes validation callbacks to garbage collection
+		opts.validationHandle.Delete()
+		opts.validationHandle = 0
+	}
 }
 
 func (opts *ContextOptions) Destroy() {

kernel/context_options.go

@@ -48,14 +48,15 @@ var (
 	ErrScriptVerifySpentOutputsRequired    = &KernelError{Operation: "kernel_verify_script", Detail: "the taproot flag was set, so valid spent_outputs have to be provided"}
 	ErrScriptVerifySpentOutputsMismatch    = &KernelError{Operation: "kernel_verify_script", Detail: "the number of spent outputs does not match the number of inputs of the transaction"}
 
-	ErrInvalidChainType          = errors.New("invalid chain type")
-	ErrInvalidLogLevel           = errors.New("invalid log level")
-	ErrInvalidLogCategory        = errors.New("invalid log category")
-	ErrInvalidScriptVerifyStatus = errors.New("invalid script verify status")
-	ErrEmptyBlockData            = errors.New("empty block data")
-	ErrEmptyScriptPubkeyData     = errors.New("empty script pubkey data")
-	ErrEmptyTransactionData      = errors.New("empty transaction data")
-	ErrNilNotificationCallbacks  = errors.New("nil notification callbacks")
+	ErrInvalidChainType                = errors.New("invalid chain type")
+	ErrInvalidLogLevel                 = errors.New("invalid log level")
+	ErrInvalidLogCategory              = errors.New("invalid log category")
+	ErrInvalidScriptVerifyStatus       = errors.New("invalid script verify status")
+	ErrEmptyBlockData                  = errors.New("empty block data")
+	ErrEmptyScriptPubkeyData           = errors.New("empty script pubkey data")
+	ErrEmptyTransactionData            = errors.New("empty transaction data")
+	ErrNilNotificationCallbacks        = errors.New("nil notification callbacks")
+	ErrNilValidationInterfaceCallbacks = errors.New("nil validation interface callbacks")
 )
 
 // UninitializedError is returned when an operation is attempted on a

kernel/errors.go

@@ -0,0 +1,72 @@
+package kernel
+
+/*
+#include "kernel/bitcoinkernel.h"
+*/
+import "C"
+import (
+	"runtime/cgo"
+	"unsafe"
+)
+
+// ValidationInterfaceCallbacks contains all the Go callback function types for validation interface.
+type ValidationInterfaceCallbacks struct {
+	OnBlockChecked func(block *BlockPointer, state *BlockValidationState)
+}
+
+//export go_validation_interface_block_checked_bridge
+func go_validation_interface_block_checked_bridge(user_data unsafe.Pointer, block *C.kernel_BlockPointer, state *C.kernel_BlockValidationState) {
+	// Convert void* back to Handle - user_data contains Handle ID
+	handle := cgo.Handle(user_data)
+	// Retrieve original Go callback struct
+	callbacks := handle.Value().(*ValidationInterfaceCallbacks)
+
+	if callbacks.OnBlockChecked != nil {
+		// Note: BlockPointer and BlockValidationState from validation interface are const and owned by kernel library
+		// We create wrappers but don't set finalizer since we don't own them
+		goBlock := &BlockPointer{ptr: (*C.kernel_BlockPointer)(unsafe.Pointer(block))}
+		goState := &BlockValidationState{ptr: (*C.kernel_BlockValidationState)(unsafe.Pointer(state))}
+		callbacks.OnBlockChecked(goBlock, goState)
+	}
+}
+
+// BlockPointer wraps the C kernel_BlockPointer for validation interface callbacks
+type BlockPointer struct {
+	ptr *C.kernel_BlockPointer
+}
+
+// GetHash returns the block hash
+func (bp *BlockPointer) GetHash() (*BlockHash, error) {
+	if bp.ptr == nil {
+		return nil, ErrBlockUninitialized
+	}
+
+	hashPtr := C.kernel_block_pointer_get_hash(bp.ptr)
+	if hashPtr == nil {
+		return nil, ErrKernelBlockGetHash
+	}
+
+	return &BlockHash{ptr: hashPtr}, nil
+}
+
+// CopyData copies the block data into a byte array
+func (bp *BlockPointer) CopyData() ([]byte, error) {
+	if bp.ptr == nil {
+		return nil, ErrBlockUninitialized
+	}
+
+	byteArray := C.kernel_copy_block_pointer_data(bp.ptr)
+	if byteArray == nil {
+		return nil, ErrKernelCopyBlockData
+	}
+	defer C.kernel_byte_array_destroy(byteArray)
+
+	size := int(byteArray.size)
+	if size == 0 {
+		return nil, nil
+	}
+
+	// Copy the data to Go slice
+	data := C.GoBytes(unsafe.Pointer(byteArray.data), C.int(size))
+	return data, nil
+}

kernel/validation_interface_callbacks.go

@@ -0,0 +1,43 @@
+package kernel
+
+import (
+	"encoding/hex"
+	"testing"
+)
+
+func TestValidationInterfaceCallbacks(t *testing.T) {
+	var blockCheckedCalled bool
+	var lastValidationMode ValidationMode
+	var lastBlockData []byte
+
+	callbacks := &ValidationInterfaceCallbacks{
+		OnBlockChecked: func(block *BlockPointer, state *BlockValidationState) {
+			blockCheckedCalled = true
+			lastValidationMode = state.ValidationMode()
+			var err error
+			lastBlockData, err = block.CopyData()
+			if err != nil {
+				t.Fatal(err)
+			}
+		},
+	}
+
+	suite := ChainstateManagerTestSuite{
+		MaxBlockHeightToImport: 2,
+		ValidationCallbacks:    callbacks,
+	}
+	suite.Setup(t)
+
+	if !blockCheckedCalled {
+		t.Error("OnBlockChecked callback was not called")
+	}
+
+	if lastValidationMode != ValidationStateValid {
+		t.Errorf("Expected validation mode %d, got %d", ValidationStateValid, lastValidationMode)
+	}
+
+	lastBlockDataHex := hex.EncodeToString(lastBlockData)
+	if lastBlockDataHex != "00000020a629da61ccd6c9de14dd22d4dcf06ac4b98828801fb58275af1ed2c89e361b79677daedb5fc7781c5907a88133cd461b4865e9a4881fecfb362304ad1806acf3a7242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025200ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000" {
+		t.Errorf("Unexpected block data for last block")
+	}
+}