Skip to content
AndroidPoetPublic

About

Kotlin Multiplatform bindings for the Bitcoin Dev Kit (bdk-ffi): JVM, Android, iOS, macOS

Resources

Code of conduct

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

bdk-kmp: Bitcoin Dev Kit for Kotlin Multiplatform

The Bitcoin Dev Kit for Kotlin Multiplatform.

Kotlin BDK Maven Central Build License

badge-android badge-ios badge-macos badge-jvm

Descriptor wallets, PSBTs, Esplora, Electrum and compact-block-filter sync from commonMain. The same org.bitcoindevkit API that bdk-android and bdk-jvm ship, now also on iOS and macOS, so a Kotlin Multiplatform wallet keeps all of its Bitcoin logic in shared code.

Install · Quickstart · Sync backends · Platforms · Migrating · What it is not · How it works · Status · Build


Why

BDK is the wallet library behind Bitkey, Proton Wallet and most new Bitcoin wallets. Until now its Kotlin packages stopped at Android and the JVM, so a Kotlin Multiplatform app had to write its iOS wallet layer twice, in Swift, and keep the two in step.

bdk-kmp removes that split. One Gradle dependency gives you the bdk_wallet API as Kotlin on Android, JVM desktop, iOS and macOS, with the Rust core compiled per platform and linked for you. No Swift glue, no second implementation. The status table says exactly what is verified where.

Install

Published on Maven Central. Add it to the shared module and every target picks up its native library automatically:

// build.gradle.kts (shared module)
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.androidpoet:bdk-kmp:3.1.1")
        }
    }
}

The version number follows the BDK release it wraps, so 3.1.1 is BDK 3.1.1.

Quickstart

Everything below lives in commonMain and runs unchanged on Android, iOS, macOS and the JVM.

Create a wallet

import org.bitcoindevkit.*

val mnemonic = Mnemonic(WordCount.WORDS12)
val secretKey = DescriptorSecretKey(NetworkKind.TEST, mnemonic, password = null)

val external = Descriptor.newBip86(secretKey, KeychainKind.EXTERNAL, NetworkKind.TEST)
val change = Descriptor.newBip86(secretKey, KeychainKind.INTERNAL, NetworkKind.TEST)

val persister = Persister.newInMemory()          // or Persister.newSqlite(pathToDbFile)
val wallet = Wallet(external, change, Network.SIGNET, persister)

val address = wallet.revealNextAddress(KeychainKind.EXTERNAL).address
println(address)                                 // tb1p…

Keys and descriptors take a NetworkKind (main or test); the wallet takes the exact Network (BITCOIN, TESTNET, TESTNET4, SIGNET, REGTEST).

Load an existing wallet

val persister = Persister.newSqlite(pathToDbFile)
val wallet = Wallet.load(external, change, persister)

Sync and read the balance

val esplora = EsploraClient("https://mutinynet.com/api")

// First time: scan every address the descriptor can produce, up to a stop gap.
val fullScan = wallet.startFullScan().build()
wallet.applyUpdate(esplora.fullScan(fullScan, stopGap = 20uL, parallelRequests = 4uL))

// Afterwards: only re-check the addresses you have revealed.
val sync = wallet.startSyncWithRevealedSpks().build()
wallet.applyUpdate(esplora.sync(sync, parallelRequests = 4uL))

wallet.persist(persister)
println(wallet.balance().total.toSat())

Send

val recipient = Address("tb1q…", Network.SIGNET)

val psbt = TxBuilder()
    .addRecipient(recipient.scriptPubkey(), Amount.fromSat(50_000uL))
    .feeRate(FeeRate.fromSatPerVb(2uL))
    .finish(wallet)

wallet.sign(psbt)
esplora.broadcast(psbt.extractTx())
wallet.persist(persister)

Keep it off the main thread

Every call is synchronous and does real work (network, signing, SQLite). Wrap the sync and send paths in withContext(Dispatchers.IO) on JVM and Android, and Dispatchers.Default on Apple targets, exactly as you would with any blocking client. A few rules that follow from that:

  • A blocking call cannot be cancelled from Kotlin. Give long syncs their own coroutine and a timeout on the client (ElectrumClient(url, timeout = ...)), and prefer sync over fullScan once a wallet is set up.
  • One Wallet may be shared across threads; the Rust side serialises access. Expect callers to queue behind a running sync rather than run alongside it.
  • Every handle is Disposable. Release it with use { } or close(); calling a released handle throws IllegalStateException rather than touching freed memory. Values such as addresses, amounts and transactions outlive the handle that produced them.
  • Released builds use upstream's release-smaller profile, including panic = "abort": a bug that panics inside the Rust core ends the process instead of surfacing as a Kotlin exception, the same as bdk-android and bdk-jvm. Errors BDK expects are typed exceptions, not panics.

Sync backends

BDK ships three chain sources and all of them are available from shared code.

Backend Class When
Esplora (HTTP) EsploraClient(url) Simplest. Public servers exist for every network.
Electrum (TCP/TLS) ElectrumClient("ssl://host:port") Your own server, or privacy over a SOCKS proxy.
Compact block filters (BIP 157/158) CbfBuilder().build(wallet) No trusted server. Talks to Bitcoin peers directly.

Electrum:

val electrum = ElectrumClient("ssl://electrum.blockstream.info:60002")
val update = electrum.sync(request = sync, batchSize = 10u, fetchPrevTxouts = true)
wallet.applyUpdate(update)

Compact block filters (a light client inside your app, no server at all):

val (client, node) = CbfBuilder()
    .connections(2u)
    .scanType(ScanType.Sync)
    .dataDir(pathToPeerDataDir)
    .build(wallet)

node.run()
wallet.applyUpdate(client.update())

Over Tor

BDK does not ship Tor; it takes a proxy and leaves running Tor to the app. Pairing with tor-kmp, which runs Tor in-process on the same targets, needs no extra native code, but the three backends differ in what they accept:

Backend Proxy it accepts Over Tor
Electrum SOCKS5 (socks5 = "127.0.0.1:9050") Yes. Hostnames, onion ones included, are resolved by the proxy.
Compact block filters SOCKS5 (socks5Proxy(Socks5Proxy(ip, port))) Yes. Peer connections go through the proxy.
Esplora HTTP CONNECT only (proxy = "http://127.0.0.1:8118") Only behind an HTTP proxy that forwards to Tor. The bundled Esplora client has no SOCKS support.
val electrum = ElectrumClient("ssl://host.onion:50002", socks5 = "127.0.0.1:9050")
val cbf = CbfBuilder().socks5Proxy(Socks5Proxy(IpAddress.fromIpv4(127u, 0u, 0u, 1u), 9050u))

None of this is exercised by the test suite yet; treat it as wiring, not as a verified privacy property.

Platform notes

Target Linking Notes
jvm() dynamic library inside the jar ships macOS arm64, Linux x86_64 and Windows x86_64; only the first two run in CI, Windows is untested
android jniLibs per ABI minSdk 24, compileSdk 37; arm64-v8a, armeabi-v7a, x86_64
iosArm64(), iosSimulatorArm64() static library, linked into your framework by the Kotlin compiler no manual Xcode step expected; not yet tried from a consumer app
macosArm64() static library

iOS. The Rust core is a static library that the Kotlin/Native compiler links into your shared framework. Your Swift code never sees it; it calls the Kotlin API you already expose.

Android. Native libraries are bundled for each ABI through JNA. Add the usual android.ndk split configuration if you want per-ABI APKs; App Bundles handle it automatically.

JVM. The jar carries the native library for the host it was built on and loads it on first use.

Coming from bdk-android or bdk-jvm

The generated API is the same package, the same classes and the same method names. Code that targets org.bitcoindevkit:bdk-android or bdk-jvm compiles against bdk-kmp without edits; it simply becomes available to commonMain and to your Apple targets as well. Mixing both in one build is not supported: pick one.

What it is, and what it is not

It is BDK. Descriptor-based wallets, coin selection, PSBT creation and signing, Taproot, Esplora, Electrum and compact-block-filter sync, SQLite persistence, BIP 39 mnemonics and BIP 32 derivation, on every Kotlin Multiplatform target that matters for a wallet.

It is not a wallet. There is no UI, no key backup, no price feed and no Lightning. It does not run a full node. It does not route traffic through Tor by itself; point ElectrumClient at a SOCKS proxy or pair it with tor-kmp for that.

How it works

BDK's Rust core is compiled once per target by the Gradle build. The Kotlin API is generated from the same upstream binding definitions that produce bdk-android, bdk-jvm and bdk-swift, using the UniFFI Kotlin Multiplatform generator, so there is no hand-written wrapper to drift out of date. On Apple targets the core is a static library pulled in through cinterop; on Android and the JVM it is a dynamic library loaded at runtime.

Where is the Kotlin?

There is no hand-written API layer under src/; the whole org.bitcoindevkit package is generated into build/ when the project compiles. To browse the public surface without building anything, read the committed dumps in bdk-kmp/api/: bdk-kmp.klib.api lists every declaration in Kotlin syntax for the native targets, and jvm/bdk-kmp.api lists the JVM signatures. CI runs ./gradlew apiCheck, so the dumps cannot drift from the generated code. After moving the upstream pin, run ./gradlew apiDump and commit the result.

Upstream currently pins a binding-generator version one step older than the one with Multiplatform support. patches/ holds that two-line version bump and the build applies it to the vendored upstream checkout. The bump is being proposed upstream so the patch can go away.

Status

Every row is backed by a CI job on main; nothing here is inferred.

Platform Verified
JVM, Linux x86_64 Full suite, network tests included, against a regtest node, Esplora and Electrum
JVM, macOS arm64 Offline suite
Android (API 34 emulator, x86_64) Full suite, network tests included, same regtest stack
macOS arm64 (Kotlin/Native) Offline suite
iOS simulator (arm64) Offline suite
iOS device (arm64) Compiles and links; not yet run on a device
JVM, Windows x86_64 and Linux x86_64 libraries Built on their own OS by the publish workflow and shipped in the jar; not yet exercised by tests
Maven Central io.github.androidpoet:bdk-kmp:3.1.1

The network tests cover receive, build, sign, broadcast and confirm over both Esplora and Electrum, compact-block-filter sync, and sync inspector callbacks. The offline suite covers keys, descriptors, mnemonics, wallet creation, SQLite persistence across reload, concurrent access to one wallet, and handle lifetimes.

Roadmap, in order: a run on an iPhone, Intel macOS and Linux arm64 libraries in the jar, a Compose Multiplatform sample wallet, then proposing the project to the bitcoindevkit organisation alongside bdk-jvm and bdk-swift.

Build & test

git clone --recurse-submodules https://github.com/AndroidPoet/bdk-kmp.git
cd bdk-kmp
./gradlew :bdk-kmp:jvmTest :bdk-kmp:macosArm64Test

The suite has two halves. The offline tests (keys, descriptors, wallets, persistence, threading, handle lifetimes) run everywhere. The network tests (full scan, sync, build, sign, broadcast and confirm over Esplora and Electrum, compact-block-filter sync, Rust-to-Kotlin sync callbacks) need a regtest stack and skip without one. CI runs them on Linux and on an Android emulator against the same container upstream bdk-ffi uses; to run them locally:

docker run -d -p 18443:18443 -p 18444:18444 -p 3002:3002 -p 60401:60401 \
  ghcr.io/thunderbiscuit/podman-regtest-infinity-pro:0.4.0
BDK_REGTEST_HOST=127.0.0.1 ./gradlew :bdk-kmp:jvmTest
./gradlew :bdk-kmp:connectedAndroidDeviceTest   # emulator reaches the container at 10.0.2.2

Requirements: JDK 17, Rust 1.93 with rustup target add aarch64-apple-ios aarch64-apple-ios-sim for iOS, and an Android NDK (28.x) for Android. The binding generator is installed by Gradle on the first build. Add :bdk-kmp:iosSimulatorArm64Test to run the suite on the iOS simulator.

Rust build output goes to cargo-build/ at the repo root; it is large, and safe to delete.

Contributing

Issues and pull requests are welcome. Keep the generated API untouched (it is regenerated on every build) and put platform-specific fixes in the Gradle build or the patch set. If a change alters the public API, run ./gradlew apiDump and commit the updated files under bdk-kmp/api/. All contributors are expected to follow the Code of Conduct.

License

MIT or Apache-2.0, at your option, matching BDK.

About

Kotlin Multiplatform bindings for the Bitcoin Dev Kit (bdk-ffi): JVM, Android, iOS, macOS

Resources

Code of conduct

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages