Adapt to kernelApi_65 and refactor resource management and error handling

Author: stringintech

.gitignore

@@ -87,24 +87,12 @@ replace github.com/stringintech/go-bitcoinkernel => /path/to/go-bitcoinkernel
 
 ### Memory Management
 
-The library handles memory management automatically through Go's finalizers, but it's highly recommended to explicitly
-call `Destroy()` methods when you're done with objects to free resources immediately.
+The library handles memory management automatically through Go's finalizers (see [common.go](./kernel/common.go)), but it's highly recommended to explicitly
+call `Destroy()` methods when you're done with owned objects to free resources immediately.
 
-### Error Handling and Resource Initialization
+### Error Handling
 
-The library uses structured error types for better error handling (see [errors.go](./kernel/errors.go)):
-
-- **`UninitializedError`**: Returned when attempting operations on uninitialized resources
-- **`KernelError`**: Returned when underlying C library operations fail
-
-**Important**: Method calls on uninitialized objects (where the internal C pointer is nil) will **panic** rather than return errors. This is by design to catch programming bugs early:
-
-```go
-m := kernel.ChainstateManager{}
-chain, _ := m.GetActiveChain() // panic: chainstateManager is not initialized
-```
-
-Always ensure objects are properly initialized (and not destroyed) before calling methods on them. Constructor functions like `NewChainstateManager()` return errors for validation, but method calls on receivers expect valid objects.
+The library uses structured error types for better error handling (see [errors.go](./kernel/errors.go)).
 
 ### Runtime Dependencies
 

README.md

@@ -5,108 +5,64 @@ package kernel
 */
 import "C"
 import (
-	"runtime"
 	"unsafe"
 )
 
-var _ cManagedResource = &Block{}
+type blockCFuncs struct{}
 
-// Block wraps the C btck_Block
-type Block struct {
-	ptr *C.btck_Block
+func (blockCFuncs) destroy(ptr unsafe.Pointer) {
+	C.btck_block_destroy((*C.btck_Block)(ptr))
 }
 
-// NewBlockFromRaw creates a new block from raw serialized data
-func NewBlockFromRaw(rawBlock []byte) (*Block, error) {
-	if len(rawBlock) == 0 {
-		return nil, ErrEmptyBlockData
-	}
-	ptr := C.btck_block_create(unsafe.Pointer(&rawBlock[0]), C.size_t(len(rawBlock)))
-	if ptr == nil {
-		return nil, ErrKernelBlockCreate
-	}
-	return newBlockFromPtr(ptr), nil
+func (blockCFuncs) copy(ptr unsafe.Pointer) unsafe.Pointer {
+	return unsafe.Pointer(C.btck_block_copy((*C.btck_Block)(ptr)))
 }
 
-func newBlockFromPtr(ptr *C.btck_Block) *Block {
-	block := &Block{ptr: ptr}
-	runtime.SetFinalizer(block, (*Block).destroy)
-	return block
+type Block struct {
+	*handle
 }
 
-func (b *Block) Hash() (*BlockHash, error) {
-	checkReady(b)
+func newBlock(ptr *C.btck_Block, fromOwned bool) *Block {
+	h := newHandle(unsafe.Pointer(ptr), blockCFuncs{}, fromOwned)
+	return &Block{handle: h}
+}
 
-	ptr := C.btck_block_get_hash(b.ptr)
+// NewBlock creates a new block from raw serialized data
+func NewBlock(rawBlock []byte) (*Block, error) {
+	ptr := C.btck_block_create(unsafe.Pointer(&rawBlock[0]), C.size_t(len(rawBlock)))
 	if ptr == nil {
-		return nil, ErrKernelBlockGetHash
+		return nil, &InternalError{"Failed to create block from bytes"}
 	}
+	return newBlock(ptr, true), nil
+}
 
-	hash := &BlockHash{ptr: ptr}
-	runtime.SetFinalizer(hash, (*BlockHash).destroy)
-	return hash, nil
+func (b *Block) Hash() *BlockHash {
+	return newBlockHash(C.btck_block_get_hash((*C.btck_Block)(b.ptr)))
 }
 
-// Bytes returns the serialized block
+// Bytes returns the consensus serialized block
 func (b *Block) Bytes() ([]byte, error) {
-	checkReady(b)
-
-	// Use the callback helper to collect bytes from btck_block_to_bytes
-	return writeToBytes(func(writer C.btck_WriteBytes, userData unsafe.Pointer) C.int {
-		return C.btck_block_to_bytes(b.ptr, writer, userData)
+	bytes, ok := writeToBytes(func(writer C.btck_WriteBytes, userData unsafe.Pointer) C.int {
+		return C.btck_block_to_bytes((*C.btck_Block)(b.ptr), writer, userData)
 	})
-}
-
-// Copy creates a copy of the block
-func (b *Block) Copy() (*Block, error) {
-	checkReady(b)
-
-	ptr := C.btck_block_copy(b.ptr)
-	if ptr == nil {
-		return nil, ErrKernelBlockCopy
+	if !ok {
+		return nil, &SerializationError{"Failed to serialize block"}
 	}
-
-	return newBlockFromPtr(ptr), nil
+	return bytes, nil
 }
 
-// CountTransactions returns the number of transactions in the block
-func (b *Block) CountTransactions() (uint64, error) {
-	checkReady(b)
-
-	count := C.btck_block_count_transactions(b.ptr)
-	return uint64(count), nil
+func (b *Block) Copy() *Block {
+	return newBlock((*C.btck_Block)(b.ptr), false)
 }
 
-// GetTransactionAt returns the transaction at the specified index.
-func (b *Block) GetTransactionAt(index uint64) (*Transaction, error) {
-	checkReady(b)
-
-	ptr := C.btck_block_get_transaction_at(b.ptr, C.size_t(index))
-	if ptr == nil {
-		return nil, ErrKernelBlockGetTransaction
-	}
-
-	transaction := &Transaction{ptr: ptr}
-	runtime.SetFinalizer(transaction, (*Transaction).destroy)
-	return transaction, nil
+func (b *Block) CountTransactions() uint64 {
+	return uint64(C.btck_block_count_transactions((*C.btck_Block)(b.ptr)))
 }
 
-func (b *Block) destroy() {
-	if b.ptr != nil {
-		C.btck_block_destroy(b.ptr)
-		b.ptr = nil
+func (b *Block) GetTransactionAt(index uint64) (*TransactionView, error) {
+	if index >= b.CountTransactions() {
+		return nil, ErrKernelIndexOutOfBounds
 	}
-}
-
-func (b *Block) Destroy() {
-	runtime.SetFinalizer(b, nil)
-	b.destroy()
-}
-
-func (b *Block) isReady() bool {
-	return b != nil && b.ptr != nil
-}
-
-func (b *Block) uninitializedError() error {
-	return ErrBlockUninitialized
+	ptr := C.btck_block_get_transaction_at((*C.btck_Block)(b.ptr), C.size_t(index))
+	return newTransactionView(check(ptr)), nil
 }

kernel/block.go

@@ -5,40 +5,26 @@ package kernel
 */
 import "C"
 import (
-	"runtime"
 	"unsafe"
 )
 
-var _ cManagedResource = &BlockHash{}
+type blockHashCFuncs struct{}
 
-// BlockHash wraps the C btck_BlockHash
-type BlockHash struct {
-	ptr *C.btck_BlockHash
-}
-
-// Bytes returns the raw hash bytes
-func (bh *BlockHash) Bytes() []byte {
-	checkReady(bh)
-	// BlockHash is a 32-byte array in the C struct
-	return C.GoBytes(unsafe.Pointer(&bh.ptr.hash[0]), 32)
+func (blockHashCFuncs) destroy(ptr unsafe.Pointer) {
+	C.btck_block_hash_destroy((*C.btck_BlockHash)(ptr))
 }
 
-func (bh *BlockHash) destroy() {
-	if bh.ptr != nil {
-		C.btck_block_hash_destroy(bh.ptr)
-		bh.ptr = nil
-	}
-}
-
-func (bh *BlockHash) Destroy() {
-	runtime.SetFinalizer(bh, nil)
-	bh.destroy()
+type BlockHash struct {
+	*uniqueHandle
 }
 
-func (bh *BlockHash) isReady() bool {
-	return bh != nil && bh.ptr != nil
+func newBlockHash(ptr *C.btck_BlockHash) *BlockHash {
+	h := newUniqueHandle(unsafe.Pointer(ptr), blockHashCFuncs{})
+	return &BlockHash{uniqueHandle: h}
 }
 
-func (bh *BlockHash) uninitializedError() error {
-	return ErrBlockHashUninitialized
+// Bytes returns the raw hash bytes
+func (bh *BlockHash) Bytes() []byte {
+	// BlockHash is a 32-byte array in the C struct
+	return C.GoBytes(unsafe.Pointer(&(*C.btck_BlockHash)(bh.ptr).hash[0]), 32)
 }

kernel/block_hash.go

@@ -5,65 +5,41 @@ package kernel
 */
 import "C"
 import (
-	"runtime"
+	"unsafe"
 )
 
-var _ cManagedResource = &BlockSpentOutputs{}
+type blockSpentOutputsCFuncs struct{}
 
-// BlockSpentOutputs wraps the C btck_BlockSpentOutputs
-type BlockSpentOutputs struct {
-	ptr *C.btck_BlockSpentOutputs
-}
-
-// Count returns the number of transaction spent outputs contained in block spent outputs
-func (bso *BlockSpentOutputs) Count() uint64 {
-	checkReady(bso)
-	return uint64(C.btck_block_spent_outputs_count(bso.ptr))
+func (blockSpentOutputsCFuncs) destroy(ptr unsafe.Pointer) {
+	C.btck_block_spent_outputs_destroy((*C.btck_BlockSpentOutputs)(ptr))
 }
 
-// GetTransactionSpentOutputsAt returns the transaction spent outputs at the specified index
-func (bso *BlockSpentOutputs) GetTransactionSpentOutputsAt(index uint64) (*TransactionSpentOutputs, error) {
-	checkReady(bso)
-	ptr := C.btck_block_spent_outputs_get_transaction_spent_outputs_at(bso.ptr, C.size_t(index))
-	if ptr == nil {
-		return nil, ErrKernelBlockSpentOutputsGetTransactionSpentOutputsAt
-	}
-
-	txSpentOutputs := &TransactionSpentOutputs{ptr: ptr}
-	runtime.SetFinalizer(txSpentOutputs, (*TransactionSpentOutputs).destroy)
-	return txSpentOutputs, nil
+func (blockSpentOutputsCFuncs) copy(ptr unsafe.Pointer) unsafe.Pointer {
+	return unsafe.Pointer(C.btck_block_spent_outputs_copy((*C.btck_BlockSpentOutputs)(ptr)))
 }
 
-// Copy creates a copy of the block spent outputs
-func (bso *BlockSpentOutputs) Copy() (*BlockSpentOutputs, error) {
-	checkReady(bso)
-
-	ptr := C.btck_block_spent_outputs_copy(bso.ptr)
-	if ptr == nil {
-		return nil, ErrKernelBlockSpentOutputsCopy
-	}
-
-	outputs := &BlockSpentOutputs{ptr: ptr}
-	runtime.SetFinalizer(outputs, (*BlockSpentOutputs).destroy)
-	return outputs, nil
+type BlockSpentOutputs struct {
+	*handle
 }
 
-func (bso *BlockSpentOutputs) destroy() {
-	if bso.ptr != nil {
-		C.btck_block_spent_outputs_destroy(bso.ptr)
-		bso.ptr = nil
-	}
+func newBlockSpentOutputs(ptr *C.btck_BlockSpentOutputs, fromOwned bool) *BlockSpentOutputs {
+	h := newHandle(unsafe.Pointer(ptr), blockSpentOutputsCFuncs{}, fromOwned)
+	return &BlockSpentOutputs{handle: h}
 }
 
-func (bso *BlockSpentOutputs) Destroy() {
-	runtime.SetFinalizer(bso, nil)
-	bso.destroy()
+func (bso *BlockSpentOutputs) Count() uint64 {
+	return uint64(C.btck_block_spent_outputs_count((*C.btck_BlockSpentOutputs)(bso.ptr)))
 }
 
-func (bso *BlockSpentOutputs) isReady() bool {
-	return bso != nil && bso.ptr != nil
+// GetTransactionSpentOutputsAt returns the transaction spent outputs at the specified index
+func (bso *BlockSpentOutputs) GetTransactionSpentOutputsAt(index uint64) (*TransactionSpentOutputsView, error) {
+	if index >= bso.Count() {
+		return nil, ErrKernelIndexOutOfBounds
+	}
+	ptr := C.btck_block_spent_outputs_get_transaction_spent_outputs_at((*C.btck_BlockSpentOutputs)(bso.ptr), C.size_t(index))
+	return newTransactionSpentOutputsView(check(ptr)), nil
 }
 
-func (bso *BlockSpentOutputs) uninitializedError() error {
-	return ErrBlockSpentOutputsUninitialized
+func (bso *BlockSpentOutputs) Copy() *BlockSpentOutputs {
+	return newBlockSpentOutputs((*C.btck_BlockSpentOutputs)(bso.ptr), false)
 }