<!--
{
  "availability" : [
    "iOS: 18.0.0 -",
    "macOS: 15.0.0 -"
  ],
  "documentType" : "article",
  "framework" : "BitcoinKernel",
  "identifier" : "/documentation/BitcoinKernel/GettingStarted",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Getting Started with BitcoinKernel"
}
-->

# 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`](/documentation/BitcoinKernel/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`](/documentation/BitcoinKernel/Context), [`ChainstateManagerOptions`](/documentation/BitcoinKernel/ChainstateManagerOptions), [`ChainstateManager`](/documentation/BitcoinKernel/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.

```swift
// 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`.BootValidatingEngine.swift
21-DOT-DEV/swift-bitcoinkernel

Copyright (c) 2026-present Timechain Software Initiative, Inc.
Distributed under the MIT software license

See the accompanying file LICENSE for information

```swift
// Boot Bitcoin Core's consensus-validation engine into a fresh regtest data
// directory and confirm the chainstate has loaded by reading the tip height.

import BitcoinKernel
import Foundation

// Pick a network. Regtest is the empty, no-internet chain — instant boot at genesis.
let params = ChainParameters(.regtest)
let options = ContextOptions()
options.setChainParams(params)
let context = try Context(options: options)

// Throwaway data directory inside the system temp dir.
let dataDirectory = FileManager.default.temporaryDirectory
    .appendingPathComponent(UUID().uuidString)
    .path(percentEncoded: false)

let managerOptions = try ChainstateManagerOptions(
    context: context,
    dataDirectory: dataDirectory
)
let manager = try ChainstateManager(options: managerOptions)

print(manager.bestEntry.height)  // 0 on a fresh regtest directory
```

A [`Context`](/documentation/BitcoinKernel/Context) carries the chain parameters and the interrupt handle every validation operation reads from. A [`ChainstateManagerOptions`](/documentation/BitcoinKernel/ChainstateManagerOptions) binds that context to a writable data directory. A [`ChainstateManager`](/documentation/BitcoinKernel/ChainstateManager) opens the block-index and chainstate LevelDB stores under that directory, replays any existing state, and exposes the chain tip via [`bestEntry`](/documentation/BitcoinKernel/ChainstateManager/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 <doc://BitcoinKernel/documentation/BitcoinKernel/EmbeddingOnIOS> 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 ``doc://BitcoinKernel/documentation/BitcoinKernel/BlockchainSync`` with any ``doc://BitcoinKernel/documentation/BitcoinKernel/BlockSource`` conformer; the shipped ``doc://BitcoinKernel/documentation/BitcoinKernel/EsploraBlockSource`` covers HTTP-served Esplora endpoints and emits progress as a typed [`AsyncSequence`](https://developer.apple.com/documentation/swift/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.

## See Also

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

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

[`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.

[`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.

[`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.

[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.

  [Bitcoin Core `src/kernel`](https://github.com/bitcoin/bitcoin/tree/master/src/kernel)

  [Wrapping a C/C++ Library in Swift — Swift.org](https://www.swift.org/documentation/articles/wrapping-c-cpp-library-in-swift.html)

  [`FileManager.temporaryDirectory` — Apple](https://developer.apple.com/documentation/foundation/filemanager/temporarydirectory)