Native language bindings for BDK

The workspace in this repository creates the libbdkffi multi-language library for the Rust-based bdk library from the Bitcoin Dev Kit project. The bdk-ffi-bindgen package builds a tool for generating the actual language binding code used to access the libbdkffi library.

Each supported language and the platform(s) it's packaged for has its own directory. The Rust code in this project is in the bdk-ffi directory and is a wrapper around the bdk library to expose its APIs in a uniform way using the mozilla/uniffi-rs bindings generator for each supported target language.

Supported target languages and platforms

The below directories (a separate repository in the case of bdk-swift) include instructions for using, building, and publishing the native language binding for bdk supported by this project.

Language	Platform	Published Package	Building Documentation	API Docs
Kotlin	JVM	bdk-jvm (Maven Central)	Readme bdk-jvm	Kotlin JVM API Docs
Kotlin	Android	bdk-android (Maven Central)	Readme bdk-android	Android API Docs
Swift	iOS, macOS	bdk-swift (GitHub)	Readme bdk-swift
Python	linux, macOS, Windows	bdk-python (PyPI)	Readme bdk-python

Language bindings generator tool

Use the bdk-ffi-bindgen tool to generate language binding code for the above supported languages. To run bdk-ffi-bindgen and see the available options use the command:

cargo run -p bdk-ffi-bindgen -- --help

Contributing

Adding new structs and functions

See the UniFFI User Guide

For pass by value objects

1. Create new rust struct with only fields that are supported UniFFI types
2. Update mapping bdk.udl file with new dictionary

For pass by reference values

1. Create wrapper rust struct/impl with only fields that are Sync + Send
2. Update mapping bdk.udl file with new interface

Goals

1. Language bindings should feel idiomatic in target languages/platforms
2. Adding new targets should be easy
3. Getting up and running should be easy
4. Contributing should be easy
5. Get it right, then automate

Using the libraries

bdk-android

// build.gradle.kts
repositories {
    mavenCentral()
}
dependencies {
  implementation("org.bitcoindevkit:bdk-android:<version>")
}

bdk-jvm

// build.gradle.kts
repositories {
    mavenCentral()
}
dependencies {
  implementation("org.bitcoindevkit:bdk-jvm:<version>")
}

Note: We also publish snapshot versions of bdk-jvm and bdk-android. See the specific readmes for instructions on how to use those.

bdk-python

pip3 install bdkpython

bdk-swift

Add bdk-swift to your dependencies in XCode.

Developing language bindings using uniffi-rs

If you are interested in better understanding the base structure we use here in order to build your own Rust-to-Kotlin/Swift/Python language bindings, check out the uniffi-bindings-template repository. We maintain it as an example and starting point for other projects that wish to leverage the tech stack used in producing the BDK language bindings.

Verifying Signatures

Both libraries and all their corresponding artifacts are signed with a PGP key you can find in the root of this repository. To verify the signatures follow the below steps:

1. Import the PGP key in your keyring.

# Navigate to the root of the repository and import the ./PGP-BDK-BINDINGS.asc public key
gpg --import ./PGP-BDK-BINDINGS.asc
    
# Alternatively, you can import the key directly from a public key server
gpg --keyserver keyserver.ubuntu.com --receive-key 2768C43E8803C6A3
    
# Verify that the correct key was imported
gpg --list-keys
# You should see the below output
pub   ed25519 2022-08-31 [SC]
    88AD93AC4589FD090FF3B8D12768C43E8803C6A3
uid           [ unknown] bitcoindevkit-bindings <bindings@bitcoindevkit.org>
sub   cv25519 2022-08-31 [E]

2. Download the binary artifacts and corresponding signature files.

• from bdk-jvm
  • bdk-jvm-<version>.jar
  • bdk-jvm-<version>.jar.asc
• from bdk-android
  • bdk-android-<version>.aar
  • bdk-android-<version>.aar.asc

3. Verify the signatures.

gpg --verify bdk-jvm-<version>.jar.asc 
gpg --verify bdk-android-<version>.aar.asc

# you should see a "Good signature" result
gpg: Good signature from "bitcoindevkit-bindings <bindings@bitcoindevkit.org>" [unknown]

PGP Metadata

Full key ID: 88AD 93AC 4589 FD09 0FF3 B8D1 2768 C43E 8803 C6A3
Fingerprint: 2768C43E8803C6A3
Name: bitcoindevkit-bindings
Email: bindings@bitcoindevkit.org

Thanks

This project is made possible thanks to the wonderful work by the mozilla/uniffi-rs team.