The Bitcoin Dev Kit for Kotlin Multiplatform.
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
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.
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.
Everything below lives in commonMain and runs unchanged on Android, iOS, macOS and the JVM.
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).
val persister = Persister.newSqlite(pathToDbFile)
val wallet = Wallet.load(external, change, persister)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())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)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 prefersyncoverfullScanonce a wallet is set up. - One
Walletmay 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 withuse { }orclose(); calling a released handle throwsIllegalStateExceptionrather than touching freed memory. Values such as addresses, amounts and transactions outlive the handle that produced them. - Released builds use upstream's
release-smallerprofile, includingpanic = "abort": a bug that panics inside the Rust core ends the process instead of surfacing as a Kotlin exception, the same asbdk-androidandbdk-jvm. Errors BDK expects are typed exceptions, not panics.
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())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.
| 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.
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.
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.
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.
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.
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.
git clone --recurse-submodules https://github.com/AndroidPoet/bdk-kmp.git
cd bdk-kmp
./gradlew :bdk-kmp:jvmTest :bdk-kmp:macosArm64TestThe 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.2Requirements: 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.
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.
MIT or Apache-2.0, at your option, matching BDK.
