go-bitcoinkernel

A Go wrapper for Bitcoin Core's libbitcoinkernel library.

⚠️ Work in Progress

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

This repository consists of:

• Bitcoin Core Source: Git subtree containing Bitcoin Core source code with libbitcoinkernel C API
• Kernel Package: Safe, idiomatic Go interfaces with integrated CGO bindings that manage memory and provide error handling
• Utils Package: Helper functions and utilities built on the kernel package wrappers for common operations

Installation and Usage

Since this library includes native C++ dependencies that must be compiled from source, it cannot be installed directly via go get (at least for now). Follow these steps:

Step 1: Clone the Repository

git clone https://github.com/stringintech/go-bitcoinkernel.git
cd go-bitcoinkernel

Step 2: Build the Native Library

make build-kernel

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, macOS, Windows)

Step 3: Run Tests

make test

This ensures that both the native library and Go bindings are working correctly.

The tests also include examples demonstrating how to use different components. For example, see:

• chainstate_manager_test.go
• logger_test.go

Step 4: Use in Your Project

In your Go project directory, add a replace directive to point to your local copy:

# Initialize your Go module (if not already done)
go mod init your-project-name

# Add replace directive to use local go-bitcoinkernel
go mod edit -replace github.com/stringintech/go-bitcoinkernel=/path/to/go-bitcoinkernel

# Add the dependency
go get github.com/stringintech/go-bitcoinkernel/kernel

Your go.mod file should look like this:

module your-project-name

go 1.23.3

require github.com/stringintech/go-bitcoinkernel/kernel v0.0.0-00010101000000-000000000000

replace github.com/stringintech/go-bitcoinkernel => /path/to/go-bitcoinkernel

Important Notes

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.

Error Handling and Resource Initialization

The library uses structured error types for better error handling (see 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:

m := kernel.ChainstateManager{}
blockIndex := m.GetBlockIndexFromGenesis() // 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.

Runtime Dependencies

Your Go application will have a runtime dependency on the shared libbitcoinkernel library produced by make build-kernel in /path/to/go-bitcoinkernel/depend/bitcoin/build. Do not delete or move these built library files as your application needs them to run.