<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "BitcoinKernel",
  "identifier" : "/documentation/BitcoinKernel",
  "metadataVersion" : "0.1.0",
  "role" : "Framework",
  "symbol" : {
    "kind" : "Framework",
    "modules" : [
      "BitcoinKernel"
    ],
    "preciseIdentifier" : "BitcoinKernel"
  },
  "title" : "BitcoinKernel"
}
-->

# BitcoinKernel

BitcoinKernel is a Swift library wrapping Bitcoin Core’s [`libbitcoinkernel`](https://github.com/bitcoin/bitcoin/tree/master/src/kernel) C API for block validation, chainstate management, chain sync, and script verification on iOS, iPadOS, macOS, and Linux.

## Overview

The BitcoinKernel module wraps Bitcoin Core’s [`libbitcoinkernel`](https://github.com/bitcoin/bitcoin/tree/master/src/kernel) behind a type-safe Swift API modeled on Apple’s [`swift-crypto`](https://github.com/apple/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`](/documentation/BitcoinKernel/BlockchainSync) engine drives a [`ChainstateManager`](/documentation/BitcoinKernel/ChainstateManager) from any [`BlockSource`](/documentation/BitcoinKernel/BlockSource) and emits typed [`AsyncSequence`](https://developer.apple.com/documentation/swift/asyncsequence) progress per [SE-0298](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0298-asyncsequence.md).

The package is part of the [21.dev](https://github.com/21-DOT-DEV) Swift Bitcoin ecosystem alongside [swift-tor](https://github.com/21-DOT-DEV/swift-tor) for privacy-routed sync, [swift-event](https://github.com/21-DOT-DEV/swift-event) for async TCP sockets and a future P2P block-source substrate, and [swift-openssl](https://github.com/21-DOT-DEV/swift-openssl) for TLS and crypto.

```swift
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](/documentation/BitcoinKernel/EmbeddingOnIOS). 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](/documentation/BitcoinKernel/EmbeddingOnIOS)

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`](https://github.com/bitcoin/bitcoin/tree/master/src/kernel) and its C++ dependencies from source for each platform and architecture, so no hand-built xcframework or `lipo` step is required.

### Essentials

[`Context`](/documentation/BitcoinKernel/Context)

A kernel context — the root runtime object for every validation operation.

[`ContextOptions`](/documentation/BitcoinKernel/ContextOptions)

Builder for constructing a [`Context`](/documentation/BitcoinKernel/Context) — configure, then pass to
[`init(options:)`](/documentation/BitcoinKernel/Context/init(options:)).

### Context and Configuration

[`ChainParameters`](/documentation/BitcoinKernel/ChainParameters)

Chain parameters describing the consensus rules, genesis block, subsidy
schedule, and soft-fork activation heights of a specific Bitcoin network.

[`ChainType`](/documentation/BitcoinKernel/ChainType)

The Bitcoin network to configure a [`Context`](/documentation/BitcoinKernel/Context) / [`ChainParameters`](/documentation/BitcoinKernel/ChainParameters)
for.

[`KernelError`](/documentation/BitcoinKernel/KernelError)

Errors from the Bitcoin kernel C API.

[`NotificationCallbacks`](/documentation/BitcoinKernel/NotificationCallbacks)

Swift-friendly wrapper for kernel notification callbacks.

[`ValidationInterfaceCallbacks`](/documentation/BitcoinKernel/ValidationInterfaceCallbacks)

Swift-friendly wrapper for validation interface callbacks.

### Chainstate Management

[`ChainstateManager`](/documentation/BitcoinKernel/ChainstateManager)

The chainstate manager — validates blocks, maintains the block index
and UTXO set, and exposes the active chain.

[`ChainstateManagerOptions`](/documentation/BitcoinKernel/ChainstateManagerOptions)

Builder for constructing a [`ChainstateManager`](/documentation/BitcoinKernel/ChainstateManager) — configures data paths,
worker-thread count, reindex behavior, and in-memory-database flags.

[`Chain`](/documentation/BitcoinKernel/Chain)

A view of the active blockchain — the unbroken sequence of blocks from
genesis to the chainstate’s current tip.

[`Coin`](/documentation/BitcoinKernel/Coin)

A UTXO — an unspent transaction output enriched with the metadata the
kernel needs to validate a spending transaction.

### Chain Sync

[`BlockchainSync`](/documentation/BitcoinKernel/BlockchainSync)

Drives a [`ChainstateManager`](/documentation/BitcoinKernel/ChainstateManager) from a [`BlockSource`](/documentation/BitcoinKernel/BlockSource) toward the source’s
tip, emitting typed progress updates as blocks are validated.

[`BlockSource`](/documentation/BitcoinKernel/BlockSource)

A source of Bitcoin blockchain data for driving a [`ChainstateManager`](/documentation/BitcoinKernel/ChainstateManager).

[`EsploraBlockSource`](/documentation/BitcoinKernel/EsploraBlockSource)

A [`BlockSource`](/documentation/BitcoinKernel/BlockSource) backed by any Esplora-compatible HTTP endpoint —
mempool.space, blockstream.info, or a self-hosted Esplora instance.

[`BlockTip`](/documentation/BitcoinKernel/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`](/documentation/BitcoinKernel/BlockSource) conformer and throughout the
[`BlockchainSync`](/documentation/BitcoinKernel/BlockchainSync) engine.

[`BlockSourceError`](/documentation/BitcoinKernel/BlockSourceError)

Errors thrown by [`BlockSource`](/documentation/BitcoinKernel/BlockSource) conformers.

### Blocks

[`Block`](/documentation/BitcoinKernel/Block)

A Bitcoin block — an 80-byte [`BlockHeader`](/documentation/BitcoinKernel/BlockHeader) plus its list of
[`Transaction`](/documentation/BitcoinKernel/Transaction) values, structurally validated by the kernel on
construction.

[`BlockHeader`](/documentation/BitcoinKernel/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)`.

[`BlockHash`](/documentation/BitcoinKernel/BlockHash)

A 32-byte block hash (double-SHA256 of the block header).

[`BlockTreeEntry`](/documentation/BitcoinKernel/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.

[`BlockTreeEntrySnapshot`](/documentation/BitcoinKernel/BlockTreeEntrySnapshot)

An owned snapshot of a [`BlockTreeEntry`](/documentation/BitcoinKernel/BlockTreeEntry)’s data — three fields
(height, block hash, block header) captured as Swift-owned values.

[`BlockSpentOutputs`](/documentation/BitcoinKernel/BlockSpentOutputs)

The spent-output (undo) data for every transaction in a block — the
collection of UTXOs that this block’s transactions consumed.

### Transactions

[`Transaction`](/documentation/BitcoinKernel/Transaction)

A Bitcoin transaction — the consensus-layer value type that moves
coins from one set of scriptPubKeys to another.

[`TransactionInput`](/documentation/BitcoinKernel/TransactionInput)

A transaction input — a reference to a previous output
([`TransactionOutPoint`](/documentation/BitcoinKernel/TransactionOutPoint)) plus the scriptSig and witness data that
unlock it.

[`TransactionOutput`](/documentation/BitcoinKernel/TransactionOutput)

A transaction output — the paid amount ([`amount`](/documentation/BitcoinKernel/TransactionOutput/amount) in satoshis) plus
the [`ScriptPubkey`](/documentation/BitcoinKernel/ScriptPubkey) that locks it.

[`TransactionOutPoint`](/documentation/BitcoinKernel/TransactionOutPoint)

A reference to a specific output of a previous transaction — a
`(txid, output-index)` pair used by [`TransactionInput`](/documentation/BitcoinKernel/TransactionInput) to identify
the UTXO being spent.

[`Txid`](/documentation/BitcoinKernel/Txid)

A 32-byte transaction identifier — double-SHA256 of a transaction’s
non-witness serialization.

[`TransactionSpentOutputs`](/documentation/BitcoinKernel/TransactionSpentOutputs)

The spent outputs ([`Coin`](/documentation/BitcoinKernel/Coin) values) for a single transaction — the
UTXOs that transaction’s inputs consumed.

[`PrecomputedTransactionData`](/documentation/BitcoinKernel/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

[`ScriptPubkey`](/documentation/BitcoinKernel/ScriptPubkey)

A script pubkey — the locking script attached to a transaction
output, defining the conditions under which that output can be spent.

[`ScriptVerificationFlags`](/documentation/BitcoinKernel/ScriptVerificationFlags)

Flags controlling which BIP-governed consensus rules apply during
script verification.

[`ScriptVerifyStatus`](/documentation/BitcoinKernel/ScriptVerifyStatus)

Status codes returned alongside the `valid` boolean from
[`verify(amount:transaction:precomputedData:inputIndex:flags:)`](/documentation/BitcoinKernel/ScriptPubkey/verify(amount:transaction:precomputedData:inputIndex:flags:)).

### Validation

[`BlockValidationState`](/documentation/BitcoinKernel/BlockValidationState)

The validation state of a block after processing — a (mode, result)
pair describing whether the kernel accepted the block and, if not, why.

[`BlockValidationResult`](/documentation/BitcoinKernel/BlockValidationResult)

A granular reason why a block failed validation. Paired with
[`ValidationMode.invalid`](/documentation/BitcoinKernel/ValidationMode/invalid) inside [`BlockValidationState`](/documentation/BitcoinKernel/BlockValidationState) to explain a
rejection from [`processBlockHeader(_:state:)`](/documentation/BitcoinKernel/ChainstateManager/processBlockHeader(_:state:)) or
[`processBlock(_:)`](/documentation/BitcoinKernel/ChainstateManager/processBlock(_:)).

[`ValidationMode`](/documentation/BitcoinKernel/ValidationMode)

Whether a validated block is valid, invalid, or the kernel hit an
internal error during validation.

[`SynchronizationState`](/documentation/BitcoinKernel/SynchronizationState)

Kernel-internal synchronization phase, passed to
[`blockTip`](/documentation/BitcoinKernel/NotificationCallbacks/blockTip) and
[`headerTip`](/documentation/BitcoinKernel/NotificationCallbacks/headerTip) on every tip update.

[`Warning`](/documentation/BitcoinKernel/Warning)

Warnings surfaced by validation via
[`warningSet`](/documentation/BitcoinKernel/NotificationCallbacks/warningSet) and cleared via
[`warningUnset`](/documentation/BitcoinKernel/NotificationCallbacks/warningUnset).

### Logging

[`LoggingConnection`](/documentation/BitcoinKernel/LoggingConnection)

A connection to the kernel’s internal logging system.

[`LogCategory`](/documentation/BitcoinKernel/LogCategory)

Categories for filtering kernel log messages — pass to
[`enableLogCategory(_:)`](/documentation/BitcoinKernel/enableLogCategory(_:)) / [`disableLogCategory(_:)`](/documentation/BitcoinKernel/disableLogCategory(_:)) /
[`setLogLevel(category:level:)`](/documentation/BitcoinKernel/setLogLevel(category:level:)) to control the noise level.

[`LogLevel`](/documentation/BitcoinKernel/LogLevel)

The minimum severity at which a [`LogCategory`](/documentation/BitcoinKernel/LogCategory) emits messages. Set
per-category via [`setLogLevel(category:level:)`](/documentation/BitcoinKernel/setLogLevel(category:level:)).