Add NotificationCallbacks

Author: stringintech

kernel/chainstate_manager_test.go

@@ -9,7 +9,11 @@ import (
 )
 
 func TestChainstateManager(t *testing.T) {
-	suite := SetupChainstateManagerTestSuite(t)
+	suite := ChainstateManagerTestSuite{
+		MaxBlockHeightToImport: 0,   // load all blocks from data/regtest/block.txt
+		NotificationCallbacks:  nil, // no notification callbacks
+	}
+	suite.Setup(t)
 
 	t.Run("genesis validation", suite.TestGenesis)
 	t.Run("tip validation", suite.TestTip)
@@ -107,11 +111,14 @@ func (s *ChainstateManagerTestSuite) TestBlockUndo(t *testing.T) {
 }
 
 type ChainstateManagerTestSuite struct {
+	MaxBlockHeightToImport int32 // leave zero to load all blocks
+	NotificationCallbacks  *NotificationCallbacks
+
 	Manager             *ChainstateManager
 	ImportedBlocksCount int32
 }
 
-func SetupChainstateManagerTestSuite(t *testing.T) *ChainstateManagerTestSuite {
+func (s *ChainstateManagerTestSuite) Setup(t *testing.T) {
 	tempDir, err := os.MkdirTemp("", "bitcoin_kernel_test")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
@@ -135,6 +142,13 @@ func SetupChainstateManagerTestSuite(t *testing.T) *ChainstateManagerTestSuite {
 
 	contextOpts.SetChainParams(chainParams)
 
+	if s.NotificationCallbacks != nil {
+		err = contextOpts.SetNotifications(s.NotificationCallbacks)
+		if err != nil {
+			t.Fatalf("SetNotifications() error = %v", err)
+		}
+	}
+
 	ctx, err := NewContext(contextOpts)
 	if err != nil {
 		t.Fatalf("NewContext() error = %v", err)
@@ -183,6 +197,9 @@ func SetupChainstateManagerTestSuite(t *testing.T) *ChainstateManagerTestSuite {
 		if line != "" {
 			blockLines = append(blockLines, line)
 		}
+		if s.MaxBlockHeightToImport != 0 && len(blockLines) >= int(s.MaxBlockHeightToImport) {
+			break
+		}
 	}
 	if len(blockLines) == 0 {
 		t.Fatal("No block data found in blocks.txt")
@@ -212,8 +229,6 @@ func SetupChainstateManagerTestSuite(t *testing.T) *ChainstateManagerTestSuite {
 		}
 	}
 
-	return &ChainstateManagerTestSuite{
-		Manager:             manager,
-		ImportedBlocksCount: int32(len(blockLines)),
-	}
+	s.Manager = manager
+	s.ImportedBlocksCount = int32(len(blockLines))
 }

kernel/context_options.go

@@ -2,17 +2,47 @@ package kernel
 
 /*
 #include "kernel/bitcoinkernel.h"
+#include <stdlib.h>
+#include <stdint.h>
+
+// Bridge functions: exported Go functions that C library can call
+// user_data contains the cgo.Handle ID as void* for callback identification
+extern void go_notify_block_tip_bridge(void* user_data, kernel_SynchronizationState state, kernel_BlockIndex* index, double verification_progress);
+extern void go_notify_header_tip_bridge(void* user_data, kernel_SynchronizationState state, int64_t height, int64_t timestamp, bool presync);
+extern void go_notify_progress_bridge(void* user_data, char* title, size_t title_len, int progress_percent, bool resume_possible);
+extern void go_notify_warning_set_bridge(void* user_data, kernel_Warning warning, char* message, size_t message_len);
+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);
+
+// Wrapper function: C helper to set notifications with Go callbacks
+// Converts Handle ID to void* and passes to C library
+static inline void set_notifications_wrapper(kernel_ContextOptions* opts, uintptr_t handle) {
+    kernel_NotificationInterfaceCallbacks callbacks = {
+        .user_data = (void*)handle,
+        .block_tip = (kernel_NotifyBlockTip)go_notify_block_tip_bridge,
+        .header_tip = (kernel_NotifyHeaderTip)go_notify_header_tip_bridge,
+        .progress = (kernel_NotifyProgress)go_notify_progress_bridge,
+        .warning_set = (kernel_NotifyWarningSet)go_notify_warning_set_bridge,
+        .warning_unset = (kernel_NotifyWarningUnset)go_notify_warning_unset_bridge,
+        .flush_error = (kernel_NotifyFlushError)go_notify_flush_error_bridge,
+        .fatal_error = (kernel_NotifyFatalError)go_notify_fatal_error_bridge,
+    };
+    kernel_context_options_set_notifications(opts, callbacks);
+}
 */
 import "C"
 import (
 	"runtime"
+	"runtime/cgo"
 )
 
 var _ cManagedResource = &ContextOptions{}
 
 // ContextOptions wraps the C kernel_ContextOptions
 type ContextOptions struct {
-	ptr *C.kernel_ContextOptions
+	ptr                *C.kernel_ContextOptions
+	notificationHandle cgo.Handle // Prevents notification callbacks GC until Destroy() called
 }
 
 func NewContextOptions() (*ContextOptions, error) {
@@ -37,11 +67,36 @@ func (opts *ContextOptions) SetChainParams(chainParams *ChainParameters) {
 	C.kernel_context_options_set_chainparams(opts.ptr, chainParams.ptr)
 }
 
+// SetNotifications sets the notification callbacks for these context options.
+// The context created with these options will be configured with these notifications.
+func (opts *ContextOptions) SetNotifications(callbacks *NotificationCallbacks) error {
+	checkReady(opts)
+	if callbacks == nil {
+		return ErrNilNotificationCallbacks
+	}
+
+	// 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 notification callbacks
+	C.set_notifications_wrapper(opts.ptr, C.uintptr_t(handle))
+
+	// Store the handle to prevent GC and allow cleanup
+	opts.notificationHandle = handle
+	return nil
+}
+
 func (opts *ContextOptions) destroy() {
 	if opts.ptr != nil {
 		C.kernel_context_options_destroy(opts.ptr)
 		opts.ptr = nil
 	}
+	if opts.notificationHandle != 0 {
+		// Delete exposes notification callbacks to garbage collection
+		opts.notificationHandle.Delete()
+		opts.notificationHandle = 0
+	}
 }
 
 func (opts *ContextOptions) Destroy() {

kernel/errors.go

@@ -55,6 +55,7 @@ var (
 	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")
 )
 
 // UninitializedError is returned when an operation is attempted on a

kernel/notification_callbacks.go

@@ -0,0 +1,121 @@
+package kernel
+
+/*
+#include "kernel/bitcoinkernel.h"
+*/
+import "C"
+import (
+	"runtime/cgo"
+	"unsafe"
+)
+
+// NotificationCallbacks contains all the Go callback function types for notifications.
+type NotificationCallbacks struct {
+	OnBlockTip     func(state SynchronizationState, index *BlockIndex, progress float64)
+	OnHeaderTip    func(state SynchronizationState, height int64, timestamp int64, presync bool)
+	OnProgress     func(title string, percent int, resumable bool)
+	OnWarningSet   func(warning Warning, message string)
+	OnWarningUnset func(warning Warning)
+	OnFlushError   func(message string)
+	OnFatalError   func(message string)
+}
+
+//export go_notify_block_tip_bridge
+func go_notify_block_tip_bridge(user_data unsafe.Pointer, state C.kernel_SynchronizationState, index *C.kernel_BlockIndex, verification_progress C.double) {
+	// Convert void* back to Handle - user_data contains Handle ID
+	handle := cgo.Handle(user_data)
+	// Retrieve original Go callback struct
+	callbacks := handle.Value().(*NotificationCallbacks)
+
+	if callbacks.OnBlockTip != nil {
+		goState := SynchronizationState(state)
+		// Note: BlockIndex from notification is const and owned by kernel library
+		// We create a wrapper but don't set finalizer since we don't own it
+		goIndex := &BlockIndex{ptr: (*C.kernel_BlockIndex)(unsafe.Pointer(index))}
+		callbacks.OnBlockTip(goState, goIndex, float64(verification_progress))
+	}
+}
+
+//export go_notify_header_tip_bridge
+func go_notify_header_tip_bridge(user_data unsafe.Pointer, state C.kernel_SynchronizationState, height C.int64_t, timestamp C.int64_t, presync C.bool) {
+	handle := cgo.Handle(user_data)
+	callbacks := handle.Value().(*NotificationCallbacks)
+
+	if callbacks.OnHeaderTip != nil {
+		goState := SynchronizationState(state)
+		callbacks.OnHeaderTip(goState, int64(height), int64(timestamp), bool(presync))
+	}
+}
+
+//export go_notify_progress_bridge
+func go_notify_progress_bridge(user_data unsafe.Pointer, title *C.char, title_len C.size_t, progress_percent C.int, resume_possible C.bool) {
+	handle := cgo.Handle(user_data)
+	callbacks := handle.Value().(*NotificationCallbacks)
+
+	if callbacks.OnProgress != nil {
+		goTitle := C.GoStringN(title, C.int(title_len))
+		callbacks.OnProgress(goTitle, int(progress_percent), bool(resume_possible))
+	}
+}
+
+//export go_notify_warning_set_bridge
+func go_notify_warning_set_bridge(user_data unsafe.Pointer, warning C.kernel_Warning, message *C.char, message_len C.size_t) {
+	handle := cgo.Handle(user_data)
+	callbacks := handle.Value().(*NotificationCallbacks)
+
+	if callbacks.OnWarningSet != nil {
+		goWarning := Warning(warning)
+		goMessage := C.GoStringN(message, C.int(message_len))
+		callbacks.OnWarningSet(goWarning, goMessage)
+	}
+}
+
+//export go_notify_warning_unset_bridge
+func go_notify_warning_unset_bridge(user_data unsafe.Pointer, warning C.kernel_Warning) {
+	handle := cgo.Handle(user_data)
+	callbacks := handle.Value().(*NotificationCallbacks)
+
+	if callbacks.OnWarningUnset != nil {
+		goWarning := Warning(warning)
+		callbacks.OnWarningUnset(goWarning)
+	}
+}
+
+//export go_notify_flush_error_bridge
+func go_notify_flush_error_bridge(user_data unsafe.Pointer, message *C.char, message_len C.size_t) {
+	handle := cgo.Handle(user_data)
+	callbacks := handle.Value().(*NotificationCallbacks)
+
+	if callbacks.OnFlushError != nil {
+		goMessage := C.GoStringN(message, C.int(message_len))
+		callbacks.OnFlushError(goMessage)
+	}
+}
+
+//export go_notify_fatal_error_bridge
+func go_notify_fatal_error_bridge(user_data unsafe.Pointer, message *C.char, message_len C.size_t) {
+	handle := cgo.Handle(user_data)
+	callbacks := handle.Value().(*NotificationCallbacks)
+
+	if callbacks.OnFatalError != nil {
+		goMessage := C.GoStringN(message, C.int(message_len))
+		callbacks.OnFatalError(goMessage)
+	}
+}
+
+// SynchronizationState represents the current sync state passed to tip changed callbacks
+type SynchronizationState int
+
+const (
+	SyncStateInitReindex SynchronizationState = iota
+	SyncStateInitDownload
+	SyncStatePostInit
+)
+
+// Warning represents possible warning types issued by validation
+type Warning int
+
+const (
+	WarningUnknownNewRulesActivated Warning = iota
+	WarningLargeWorkInvalidChain
+)

kernel/notification_callbacks_test.go

@@ -0,0 +1,42 @@
+package kernel
+
+import (
+	"testing"
+)
+
+func TestNotificationCallbacks(t *testing.T) {
+	var blockTipCalled bool
+	var headerTipCalled bool
+	var lastBlockHeight int64
+	var lastHeaderHeight int64
+
+	callbacks := &NotificationCallbacks{
+		OnBlockTip: func(state SynchronizationState, index *BlockIndex, _ float64) {
+			blockTipCalled = true
+			lastBlockHeight = int64(index.Height())
+		},
+		OnHeaderTip: func(state SynchronizationState, height int64, timestamp int64, presync bool) {
+			headerTipCalled = true
+			lastHeaderHeight = height
+		},
+	}
+	suite := ChainstateManagerTestSuite{
+		MaxBlockHeightToImport: 5,
+		NotificationCallbacks:  callbacks,
+	}
+	suite.Setup(t)
+
+	if !blockTipCalled {
+		t.Error("OnBlockTip callback was not called")
+	}
+	if lastBlockHeight != 5 {
+		t.Errorf("Expected last block height 5, got %d", lastBlockHeight)
+	}
+
+	if !headerTipCalled {
+		t.Error("OnHeaderTip callback was not called")
+	}
+	if lastHeaderHeight != 5 {
+		t.Errorf("Expected last header height 5, got %d", lastHeaderHeight)
+	}
+}