BitcoinKernel.NET

.NET bindings for libbitcoinkernel, providing access to Bitcoin Core's consensus and validation logic.

⚠️🚧 This library is still under construction. ⚠️🚧

This library uses libbitcoinkernel which is in an experimental state, do not use for production purposes.

Packages

Package	Version	Description
BitcoinKernel	0.3.0	Managed wrappers and native bindings

dotnet add package BitcoinKernel

Architecture

The library is organized in two layers:

1. BitcoinKernel.Interop - P/Invoke bindings to libbitcoinkernel (bundled, not published separately)
2. BitcoinKernel - Managed C# wrappers with automatic memory management

┌─────────────────────────────┐
│   BitcoinKernel             │  ← Managed wrappers, IDisposable
│   (Wrapper Layer)           │
└─────────────┬───────────────┘
              │
┌─────────────▼───────────────┐
│  BitcoinKernel.Interop      │  ← P/Invoke bindings (bundled)
│  (Binding Layer)            │
└─────────────┬───────────────┘
              │
┌─────────────▼───────────────┐
│    libbitcoinkernel         │  ← Native C library
│    (Bitcoin Core)           │
└─────────────────────────────┘

Quick Start

using BitcoinKernel;
using BitcoinKernel.Chain;
using BitcoinKernel.Interop.Enums;

using var logging = new LoggingConnection((category, message, level) =>
    Console.WriteLine($"[{category}] {message}"));

using var chainParams = new ChainParameters(ChainType.MAINNET);
using var contextOptions = new KernelContextOptions().SetChainParams(chainParams);
using var context = new KernelContext(contextOptions);
using var options = new ChainstateManagerOptions(context, dataDir, blocksDir);
using var chainstate = new ChainstateManager(context, chainParams, options);

var chain = chainstate.GetActiveChain();
Console.WriteLine($"Height: {chain.Height}");
Console.WriteLine($"Genesis: {Convert.ToHexString(chain.GetGenesis().GetBlockHash())}");

Examples

Explore the examples directory for complete working samples:

• BasicUsage - Getting started with chain queries
• BlockProcessing - Block validation and processing

Tools

Kernel Bindings Test Handler

A conformance test handler for the Kernel bindings test framework, see tools/kernel-bindings-test-handler for details.

dotnet run --project tools/kernel-bindings-test-handler

Building from Source

Prerequisites

• .NET 10.0 SDK or later

Build

git clone https://github.com/janb84/BitcoinKernel.NET.git
cd BitcoinKernel.NET
dotnet build

Run Tests

dotnet test

Native Library

This package includes pre-built libbitcoinkernel binaries for:

• macOS (x64, ARM64)
• others will follow

For other platforms, you'll need to build libbitcoinkernel from the Bitcoin Core repository.

In CI, libbitcoinkernel is built from source at the Bitcoin Core commit pinned in native/BITCOIN_COMMIT and used for the test and conformance jobs. To move to a newer kernel API, update that file to the desired commit hash; the build is cached per commit, so only the first run after a bump rebuilds Bitcoin Core.

Documentation

• API Documentation (coming soon)
• libbitcoinkernel Documentation
• Bitcoin Core Developer Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built on libbitcoinkernel from Bitcoin Core

Note: This library provides access to Bitcoin Core's consensus engine. libbitcoinkernel and this package are still experimental and not ready for production use.