diff --git a/README.md b/README.md index 251cf67..659c8e8 100644 --- a/README.md +++ b/README.md @@ -7,183 +7,79 @@ Chat on Discord

-The workspace in this repository creates the `libbdkffi` multi-language library for the rust based +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 has its own repository that includes this project as a [git submodule]. -The rust code in this project is a wrapper around the [bdk] library to expose it's APIs in a -uniform way using the [mozilla/uniffi-rs] bindings generator for each supported target language. +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. -The below repositories include instructions for using, building, and publishing the native -language binding for [bdk] supported by this project. - -| Language | Platform | Repository | -| -------- | ------------ | ------------ | -| Kotlin | jvm | [bdk-kotlin] | -| Kotlin | android | [bdk-kotlin] | -| Swift | iOS, macOS | [bdk-swift] | -| Python | linux, macOS | [bdk-python] | +| 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: ```shell cargo run -p bdk-ffi-bindgen -- --help ``` -[bdk]: https://github.com/bitcoindevkit/bdk -[Bitcoin Dev Kit]: https://github.com/bitcoindevkit -[git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[uniffi-rs]: https://github.com/mozilla/uniffi-rs - -[bdk-kotlin]: https://github.com/bitcoindevkit/bdk-kotlin -[bdk-swift]: https://github.com/bitcoindevkit/bdk-swift -[bdk-python]: https://github.com/bitcoindevkit/bdk-python - ## Contributing ### Adding new structs and functions - See the [UniFFI User Guide](https://mozilla.github.io/uniffi-rs/) #### 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` -1. create new rust struct with only fields that are supported UniFFI types -1. 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` -1. update mapping `bdk.udl` file with new `interface` +#### 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 -1. Adding new targets should be easy -1. Getting up and running should be easy -1. Contributing should be easy -1. Get it right, then automate +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 -# bdk-kotlin - -This project builds .jar and .aar packages for the `jvm` and `android` platforms that provide -[Kotlin] language bindings for the [`bdk`] library. The Kotlin language bindings are created by the -[`bdk-ffi`] project which is included as a git submodule of this repository. - -## How to Use - -To use the Kotlin language bindings for [`bdk`] in your `jvm` or `android` project add the -following to your gradle dependencies: -```groovy +## Using the libraries +### bdk-android +```kotlin +// build.gradle.kts repositories { mavenCentral() } - dependencies { - - // for jvm - implementation 'org.bitcoindevkit:bdk-jvm:' - // OR for android - implementation 'org.bitcoindevkit:bdk-android:' - + implementation("org.bitcoindevkit:bdk-android:") } ``` -You may then import and use the `org.bitcoindevkit` library in your Kotlin code. For example: - +### bdk-jvm ```kotlin -import org.bitcoindevkit.* - -// ... - -val externalDescriptor = "wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/0/*)" -val internalDescriptor = "wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/1/*)" - -val databaseConfig = DatabaseConfig.Memory - -val blockchainConfig = - BlockchainConfig.Electrum( - ElectrumConfig("ssl://electrum.blockstream.info:60002", null, 5u, null, 10u) - ) -val wallet = Wallet(externalDescriptor, internalDescriptor, Network.TESTNET, databaseConfig, blockchainConfig) -val newAddress = wallet.getNewAddress() +// build.gradle.kts +repositories { + mavenCentral() +} +dependencies { + implementation("org.bitcoindevkit:bdk-jvm:") +} ``` -### Example Projects - -#### `bdk-android` -* [Devkit Wallet](https://github.com/thunderbiscuit/devkit-wallet) -* [Padawan Wallet](https://github.com/thunderbiscuit/padawan-wallet) - -#### `bdk-jvm` -* [Tatooine Faucet](https://github.com/thunderbiscuit/tatooine) - -### How to build -_Note that Kotlin version `1.6.10` or later is required to build the library._ - -1. Clone this repository and initialize and update its [`bdk-ffi`] submodule. +### bdk-python ```shell -git clone https://github.com/bitcoindevkit/bdk-kotlin -git submodule update --init -``` -2. Follow the "General" bdk-ffi ["Getting Started (Developer)"] instructions. -3. If building on MacOS install required intel and m1 jvm targets -```sh -rustup target add x86_64-apple-darwin aarch64-apple-darwin -``` -4. Install required targets - ```sh - rustup target add x86_64-linux-android aarch64-linux-android armv7-linux-androideabi - ``` -5. Install Android SDK and Build-Tools for API level 30+ -6. Setup `$ANDROID_SDK_ROOT` and `$ANDROID_NDK_ROOT` path variables (which are required by the - build tool), for example (NDK major version 21 is required): - ```shell - export ANDROID_SDK_ROOT=~/Android/Sdk - export ANDROID_NDK_ROOT=$ANDROID_SDK_ROOT/ndk/21. - ``` -7. Build kotlin bindings - ```sh - # build JVM library - cd bdk-jvm - ./gradlew buildJvmLib - - # build Android library - cd bdk-android - ./gradlew buildAndroidLib - ``` -8. Start android emulator (must be x86_64) and run tests -```sh -./gradlew connectedAndroidTest +pip3 install bdkpython ``` -## How to publish - -### Publish to your local maven repo -```shell -# bdk-jvm -cd bdk-jvm -./gradlew publishToMavenLocal --exclude-task signMavenPublication - -# bdk-android -cd bdk-android -./gradlew publishToMavenLocal --exclude-task signMavenPublication -``` - -Note that the commands assume you don't need the local libraries to be signed. If you do wish to sign them, simply set your `~/.gradle/gradle.properties` signing key values like so: -```properties -signing.gnupg.keyName= -signing.gnupg.passphrase= -``` - -and use the `publishToMavenLocal` task without excluding the signing task: -```shell -./gradlew publishToMavenLocal -``` +### bdk-swift +Add bdk-swift to your dependencies in XCode. ## Verifying Signatures Both libraries and all their corresponding artifacts are signed with a PGP key you can find in the @@ -229,17 +125,27 @@ 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. + [Kotlin]: https://kotlinlang.org/ [Android Studio]: https://developer.android.com/studio/ [`bdk`]: https://github.com/bitcoindevkit/bdk [`bdk-ffi`]: https://github.com/bitcoindevkit/bdk-ffi ["Getting Started (Developer)"]: https://github.com/bitcoindevkit/bdk-ffi#getting-started-developer -[Gradle Nexus Publish Plugin]: https://github.com/gradle-nexus/publish-plugin -[bdk-jvm]: https://search.maven.org/artifact/org.bitcoindevkit/bdk-jvm/0.9.0/jar -[bdk-android]: https://search.maven.org/artifact/org.bitcoindevkit/bdk-android/0.9.0/aar - -## Thanks - -This project is made possible thanks to the wonderful work by the [mozilla/uniffi-rs] team. - +[bdk-jvm]: https://search.maven.org/artifact/org.bitcoindevkit/bdk-jvm/0.11.0/jar +[bdk-android]: https://search.maven.org/artifact/org.bitcoindevkit/bdk-android/0.11.0/aar +[bdk-jvm (Maven Central)]: https://central.sonatype.dev/artifact/org.bitcoindevkit/bdk-jvm/0.11.0 +[bdk-android (Maven Central)]: https://central.sonatype.dev/artifact/org.bitcoindevkit/bdk-android/0.11.0 +[bdk-swift (GitHub)]: https://github.com/bitcoindevkit/bdk-swift +[bdk-python (PyPI)]: https://pypi.org/project/bdkpython/ [mozilla/uniffi-rs]: https://github.com/mozilla/uniffi-rs +[bdk]: https://github.com/bitcoindevkit/bdk +[Bitcoin Dev Kit]: https://github.com/bitcoindevkit +[uniffi-rs]: https://github.com/mozilla/uniffi-rs +[Readme bdk-jvm]: https://github.com/bitcoindevkit/bdk-ffi/tree/master/bdk-jvm +[Readme bdk-android]: https://github.com/bitcoindevkit/bdk-ffi/tree/master/bdk-android +[Readme bdk-swift]: https://github.com/bitcoindevkit/bdk-swift +[Readme bdk-python]: https://github.com/bitcoindevkit/bdk-ffi/tree/master/bdk-python +[Kotlin JVM API Docs]: https://bitcoindevkit.org/jvm/ +[Android API Docs]: https://bitcoindevkit.org/android/ diff --git a/bdk-android/README.md b/bdk-android/README.md new file mode 100644 index 0000000..d75c75b --- /dev/null +++ b/bdk-android/README.md @@ -0,0 +1,87 @@ +# bdk-android +This project builds an .aar package for the `android` platform that provide [Kotlin] language bindings for the [`bdk`] library. The Kotlin language bindings are created by the [`bdk-ffi`] project which is included in the root of this repository. + +## How to Use +To use the Kotlin language bindings for [`bdk`] in your `android` project add the following to your gradle dependencies: +```groovy +repositories { + mavenCentral() +} + +dependencies { + implementation("org.bitcoindevkit:bdk-android:") +} +``` + +You may then import and use the `org.bitcoindevkit` library in your Kotlin code. For example: +```kotlin +import org.bitcoindevkit.* + +// ... + +val externalDescriptor = "wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/0/*)" +val internalDescriptor = "wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/1/*)" + +val databaseConfig = DatabaseConfig.Memory + +val blockchainConfig = + BlockchainConfig.Electrum( + ElectrumConfig("ssl://electrum.blockstream.info:60002", null, 5u, null, 10u) + ) +val wallet = Wallet(externalDescriptor, internalDescriptor, Network.TESTNET, databaseConfig, blockchainConfig) +val newAddress = wallet.getNewAddress() +``` + +### Example Projects +* [Devkit Wallet](https://github.com/thunderbiscuit/devkit-wallet) +* [Padawan Wallet](https://github.com/thunderbiscuit/padawan-wallet) + +### How to build +_Note that Kotlin version `1.6.10` or later is required to build the library._ + +1. Clone this repository. +```shell +git clone https://github.com/bitcoindevkit/bdk-ffi +``` +2. Follow the "General" bdk-ffi ["Getting Started (Developer)"] instructions. +3. If building on macOS install required intel and m1 jvm targets +4. Install required targets + ```sh + rustup target add x86_64-linux-android aarch64-linux-android armv7-linux-androideabi + ``` +5. Install Android SDK and Build-Tools for API level 30+ +6. Setup `$ANDROID_SDK_ROOT` and `$ANDROID_NDK_ROOT` path variables (which are required by the + build tool), for example (NDK major version 21 is required): + ```shell + export ANDROID_SDK_ROOT=~/Android/Sdk + export ANDROID_NDK_ROOT=$ANDROID_SDK_ROOT/ndk/21. + ``` +7. Build kotlin bindings + ```sh + # build Android library + cd bdk-android + ./gradlew buildAndroidLib + ``` +8. Start android emulator (must be x86_64) and run tests +```sh +./gradlew connectedAndroidTest +``` + +## How to publish +### Publish to your local maven repo +```shell +# bdk-android +cd bdk-android +./gradlew publishToMavenLocal --exclude-task signMavenPublication +``` + +Note that the commands assume you don't need the local libraries to be signed. If you do wish to sign them, simply set your `~/.gradle/gradle.properties` signing key values like so: +```properties +signing.gnupg.keyName= +signing.gnupg.passphrase= +``` + +and use the `publishToMavenLocal` task without excluding the signing task: +```shell +./gradlew publishToMavenLocal +``` diff --git a/bdk-jvm/README.md b/bdk-jvm/README.md new file mode 100644 index 0000000..a6bf20e --- /dev/null +++ b/bdk-jvm/README.md @@ -0,0 +1,73 @@ +# bdk-android +This project builds a .jar package for the `jvm` platform that provide [Kotlin] language bindings for the [`bdk`] library. The Kotlin language bindings are created by the [`bdk-ffi`] project which is included in the root of this repository. + +## How to Use +To use the Kotlin language bindings for [`bdk`] in your `jvm` project add the following to your gradle dependencies: +```kotlin +repositories { + mavenCentral() +} + +dependencies { + implementation("org.bitcoindevkit:bdk-jvm:") +} +``` + +You may then import and use the `org.bitcoindevkit` library in your Kotlin code. For example: +```kotlin +import org.bitcoindevkit.* + +// ... + +val externalDescriptor = "wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/0/*)" +val internalDescriptor = "wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/1/*)" + +val databaseConfig = DatabaseConfig.Memory + +val blockchainConfig = + BlockchainConfig.Electrum( + ElectrumConfig("ssl://electrum.blockstream.info:60002", null, 5u, null, 10u) + ) +val wallet = Wallet(externalDescriptor, internalDescriptor, Network.TESTNET, databaseConfig, blockchainConfig) +val newAddress = wallet.getNewAddress() +``` + +### Example Projects +* [Tatooine Faucet](https://github.com/thunderbiscuit/tatooine) + +### How to build +_Note that Kotlin version `1.6.10` or later is required to build the library._ + +1. Clone this repository. +```shell +git clone https://github.com/bitcoindevkit/bdk-ffi +``` +2. Follow the "General" bdk-ffi ["Getting Started (Developer)"] instructions. +3. If building on macOS install required intel and m1 jvm targets +```sh +rustup target add x86_64-apple-darwin aarch64-apple-darwin +``` +4. Build kotlin bindings + ```sh + # build JVM library + ./gradlew buildJvmLib + ``` + +## How to publish +### Publish to your local maven repo +```shell +# bdk-jvm +cd bdk-jvm +./gradlew publishToMavenLocal --exclude-task signMavenPublication +``` + +Note that the commands assume you don't need the local libraries to be signed. If you do wish to sign them, simply set your `~/.gradle/gradle.properties` signing key values like so: +```properties +signing.gnupg.keyName= +signing.gnupg.passphrase= +``` + +and use the `publishToMavenLocal` task without excluding the signing task: +```shell +./gradlew publishToMavenLocal +``` diff --git a/bdk-python/README.md b/bdk-python/README.md index c89f245..4cc8ed9 100644 --- a/bdk-python/README.md +++ b/bdk-python/README.md @@ -2,14 +2,12 @@ The Python language bindings for the [bitcoindevkit](https://github.com/bitcoindevkit). See the [package on PyPI](https://pypi.org/project/bdkpython/). -
## Install from PyPI Install the latest release using ```shell pip install bdkpython ``` -
## Run the tests ```shell @@ -19,7 +17,6 @@ python3 setup.py --verbose bdist_wheel pip3 install ./dist/bdkpython--py3-none-any.whl python -m unittest --verbose tests/test_bdk.py ``` -
## Build the package ```shell @@ -32,20 +29,18 @@ bash generate.sh # Build the wheel python3 setup.py --verbose bdist_wheel ``` -
## Run tox to build and test locally ```shell # install dev requirements pip install --requirement requirements-dev.txt -# build bindings glue code (located at ./src/bdkpython/bdk.py) +# build bindings glue code (located at .bdk-python/src/bdkpython/bdk.py) source ./generate.sh # build and test tox -vv ``` -
## Install locally ```shell