BitcoinKernel

Framework

BitcoinKernel

BitcoinKernel is a Swift library wrapping Bitcoin Core’s libbitcoinkernel C API for block validation, chainstate management, chain sync, and script verification on iOS, iPadOS, macOS, and Linux.

Mentioned In

Embedding BitcoinKernel on iOS without an xcframework

Overview

The BitcoinKernel module wraps Bitcoin Core’s libbitcoinkernel behind a type-safe Swift API modeled on Apple’s swift-crypto framework. The wrapped surface covers block validation, chainstate management, chain sync, and script verification. Network, wallet, and GUI subsystems are excluded by design.

Every opaque C handle is owned by a Swift class whose deinit calls the matching btck_*_destroy. Memory management is invisible to callers and OpaquePointer does not appear in public signatures. The BlockchainSync engine drives a ChainstateManager from any BlockSource and emits typed AsyncSequence progress per SE-0298.

The package is part of the 21.dev Swift Bitcoin ecosystem alongside swift-tor for privacy-routed sync, swift-event for async TCP sockets and a future P2P block-source substrate, and swift-openssl for TLS and crypto.

import BitcoinKernel

let params = ChainParameters(.regtest)
let options = ContextOptions()
options.setChainParams(params)
let context = try Context(options: options)

Where to start

To ship BitcoinKernel inside an iPhone, iPad, or Apple Silicon Mac app, read Embedding BitcoinKernel on iOS without an xcframework. It covers the SwiftPM target topology, data-directory placement, the cross-compile invocation, and the iOS-specific caveats for App Store review.

Topics

Guides

Embedding BitcoinKernel on iOS without an xcframework
Ship Bitcoin Core’s consensus-validation engine inside an iPhone, iPad, or Apple Silicon Mac app by adding BitcoinKernel as a Swift Package Manager dependency. SwiftPM compiles libbitcoinkernel and its C++ dependencies from source for each platform and architecture, so no hand-built xcframework or lipo step is required.

Essentials

class Context
A kernel context — the root runtime object for every validation operation.
class ContextOptions
Builder for constructing a Context — configure, then pass to init(options:).

Context and Configuration

Chainstate Management

class ChainstateManager
The chainstate manager — validates blocks, maintains the block index and UTXO set, and exposes the active chain.
class ChainstateManagerOptions
Builder for constructing a ChainstateManager — configures data paths, worker-thread count, reindex behavior, and in-memory-database flags.
class Chain
A view of the active blockchain — the unbroken sequence of blocks from genesis to the chainstate’s current tip.
class Coin
A UTXO — an unspent transaction output enriched with the metadata the kernel needs to validate a spending transaction.

Chain Sync

struct BlockchainSync
Drives a ChainstateManager from a BlockSource toward the source’s tip, emitting typed progress updates as blocks are validated.
protocol BlockSource
A source of Bitcoin blockchain data for driving a ChainstateManager.
struct EsploraBlockSource
A BlockSource backed by any Esplora-compatible HTTP endpoint — mempool.space, blockstream.info, or a self-hosted Esplora instance.
struct BlockTip
A snapshot identifying a specific block on a chain — paired 32-byte hash, height, and an optional header timestamp. The canonical “where am I?” value used by every BlockSource conformer and throughout the BlockchainSync engine.
enum BlockSourceError
Errors thrown by BlockSource conformers.

Blocks

class Block
A Bitcoin block — an 80-byte BlockHeader plus its list of Transaction values, structurally validated by the kernel on construction.
class BlockHeader
A Bitcoin block header — exactly 80 bytes holding the six fields that make up the proof-of-work commitment: version (4) | prev hash (32) | merkle root (32) | time (4) | nBits (4) | nonce (4).
class BlockHash
A 32-byte block hash (double-SHA256 of the block header).
class BlockTreeEntry
An entry in the block tree (block index) — a block the kernel has validated, whether on the active chain or on a side chain.
struct BlockTreeEntrySnapshot
An owned snapshot of a BlockTreeEntry’s data — three fields (height, block hash, block header) captured as Swift-owned values.
class BlockSpentOutputs
The spent-output (undo) data for every transaction in a block — the collection of UTXOs that this block’s transactions consumed.

Transactions

class Transaction
A Bitcoin transaction — the consensus-layer value type that moves coins from one set of scriptPubKeys to another.
class TransactionInput
A transaction input — a reference to a previous output (TransactionOutPoint) plus the scriptSig and witness data that unlock it.
class TransactionOutput
A transaction output — the paid amount (amount in satoshis) plus the ScriptPubkey that locks it.
class TransactionOutPoint
A reference to a specific output of a previous transaction — a (txid, output-index) pair used by TransactionInput to identify the UTXO being spent.
class Txid
A 32-byte transaction identifier — double-SHA256 of a transaction’s non-witness serialization.
class TransactionSpentOutputs
The spent outputs (Coin values) for a single transaction — the UTXOs that transaction’s inputs consumed.
class PrecomputedTransactionData
Cached per-transaction data that speeds up repeated script verification — most importantly, the BIP-341 sighash components a taproot spend uses (hashPrevouts, hashAmounts, hashScriptPubkeys, hashSequences, hashOutputs) that would otherwise be recomputed for every input.

Script Verification

Validation

Logging

class LoggingConnection
A connection to the kernel’s internal logging system.
enum LogCategory
Categories for filtering kernel log messages — pass to enableLogCategory(_:) / disableLogCategory(_:) / setLogLevel(category:level:) to control the noise level.
enum LogLevel
The minimum severity at which a LogCategory emits messages. Set per-category via setLogLevel(category:level:).

Functions

Extended Modules