Getting Started with BitcoinKernel

Install BitcoinKernel via Swift Package Manager and boot Bitcoin Core’s consensus-validation engine inside your own Swift process, ending with a running ChainstateManager pinned to the regtest genesis in a throwaway temporary directory.

Overview

BitcoinKernel wraps Bitcoin Core’s [libbitcoinkernel][bitcoin-kernel] behind a type-safe Swift API. libbitcoinkernel is the consensus-validation engine extracted from [src/kernel][bitcoin-kernel] with the network, wallet, and GUI subsystems excluded by design.

This article walks from an empty SwiftPM project to a live engine. Install the dependency, build three objects (Context, ChainstateManagerOptions, ChainstateManager), and confirm the engine has located its tip.

Prerequisites

Swift 6.3 toolchain (Xcode 26.4 or later on Apple platforms, matching swift-tools-version on Linux).
A deployment target on macOS 15.0+, iOS 18.0+, iPadOS 18.0+, or a Linux distribution with a current Swift toolchain.
Under 50 MB of free disk space for the regtest data directory this article creates.

Add BitcoinKernel with Swift Package Manager

Add the package, then depend on the BitcoinKernel product from your target:

Important

This package is currently pre-1.0. Track main until a stable tag ships, then pin with .upToNextMajor(from:) so a swift package update cannot break your build at an unmarked boundary.

// Package.swift
dependencies: [
    .package(
        url: "https://github.com/21-DOT-DEV/swift-bitcoinkernel.git",
        branch: "main"
    ),
],
targets: [
    .target(
        name: "MyBitcoinApp",
        dependencies: [
            .product(name: "BitcoinKernel", package: "swift-bitcoinkernel"),
        ]
    ),
]

The first build compiles libbitcoinkernel and its C/C++ dependencies from source for your destination’s triple. Expect several minutes on a cold cache and seconds for incremental rebuilds. The Xcode equivalent is File → Add Package Dependencies… and resolves to the same Package.resolved.

Boot the validating engine

Three objects, constructed in fixed order, get a regtest consensus engine running in a throwaway temporary directory. The example below is Snippets/BootValidatingEngine.swift in the package and is compile-checked on every swift build.

A Context carries the chain parameters and the interrupt handle every validation operation reads from. A ChainstateManagerOptions binds that context to a writable data directory. A ChainstateManager opens the block-index and chainstate LevelDB stores under that directory, replays any existing state, and exposes the chain tip via bestEntry.

On a fresh regtest data directory the kernel writes the embedded regtest genesis block and nothing else, so bestEntry.height returning 0 proves the engine opened both LevelDB stores, loaded the chain parameters, and now knows where its tip is. Anything other than 0 against a fresh regtest directory indicates a partial boot.

Where to go next

The snippet above uses a disposable temp directory and stops at the regtest genesis on purpose. What to read next depends on what you’re adding.

To ship inside an iPhone, iPad, or Apple Silicon Mac app, see Embedding BitcoinKernel on iOS without an xcframework for production data-directory layout, the SwiftUI App init pattern, background-task budgets for chain sync, and App Store encryption-export self-classification.
To drive a real chain sync, pair BlockchainSync with any BlockSource conformer; the shipped EsploraBlockSource covers HTTP-served Esplora endpoints and emits progress as a typed AsyncSequence.
To talk to a running Bitcoin Core daemon over RPC instead, use the sibling Bitcoin product, which embeds the full bitcoind and exposes a typed RPC client.