frost/bdk-ffi
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clean up root readme and add individual libraries' readmes

Browse Source
This commit is contained in:
thunderbiscuit 2022-11-15 20:29:58 -05:00
parent 063f69222a
commit 3edda27ef2
No known key found for this signature in database
GPG Key ID: 88253696EB836462
4 changed files with 214 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
README.md
View File

@ -7,183 +7,79 @@
<a href="https://discord.gg/d7NkDKm"><img alt="Chat on Discord" src="https://img.shields.io/discord/753336465005608961?logo=discord"></a> <a href="https://discord.gg/d7NkDKm"><img alt="Chat on Discord" src="https://img.shields.io/discord/753336465005608961?logo=discord"></a>
</p> </p>
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 [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. 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]. 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.
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.
## Supported target languages and platforms ## 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 | Platform | Published Package | Building Documentation | API Docs |
language binding for [bdk] supported by this project. | -------- |-----------------------|-------------------------------|------------------------|-----------------------|
| Kotlin | JVM | [bdk-jvm (Maven Central)] | [Readme bdk-jvm] | [Kotlin JVM API Docs] |
| Language | Platform | Repository | | Kotlin | Android | [bdk-android (Maven Central)] | [Readme bdk-android] | [Android API Docs] |
| -------- | ------------ | ------------ | | Swift | iOS, macOS | [bdk-swift (GitHub)] | [Readme bdk-swift] | |
| Kotlin | jvm | [bdk-kotlin] | | Python | linux, macOS, Windows | [bdk-python (PyPI)] | [Readme bdk-python] | |
| Kotlin | android | [bdk-kotlin] |
| Swift | iOS, macOS | [bdk-swift] |
| Python | linux, macOS | [bdk-python] |
## Language bindings generator tool ## Language bindings generator tool
Use the `bdk-ffi-bindgen` tool to generate language binding code for the above supported languages. 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: To run `bdk-ffi-bindgen` and see the available options use the command:
```shell ```shell
cargo run -p bdk-ffi-bindgen -- --help 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 ## Contributing
### Adding new structs and functions ### Adding new structs and functions
See the [UniFFI User Guide](https://mozilla.github.io/uniffi-rs/) See the [UniFFI User Guide](https://mozilla.github.io/uniffi-rs/)
#### For pass by value objects #### 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 #### For pass by reference values
1. update mapping `bdk.udl` file with new `dictionary` 1. Create wrapper rust struct/impl with only fields that are `Sync + Send`
2. 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`
1. update mapping `bdk.udl` file with new `interface`
## Goals ## Goals
1. Language bindings should feel idiomatic in target languages/platforms 1. Language bindings should feel idiomatic in target languages/platforms
1. Adding new targets should be easy 2. Adding new targets should be easy
1. Getting up and running should be easy 3. Getting up and running should be easy
1. Contributing should be easy 4. Contributing should be easy
1. Get it right, then automate 5. Get it right, then automate
# bdk-kotlin ## Using the libraries
### bdk-android
This project builds .jar and .aar packages for the `jvm` and `android` platforms that provide ```kotlin
[Kotlin] language bindings for the [`bdk`] library. The Kotlin language bindings are created by the // build.gradle.kts
[`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
repositories { repositories {
mavenCentral() mavenCentral()
} }
dependencies { dependencies {
implementation("org.bitcoindevkit:bdk-android:<version>")
// for jvm
implementation 'org.bitcoindevkit:bdk-jvm:<version>'
// OR for android
implementation 'org.bitcoindevkit:bdk-android:<version>'
} }
``` ```
You may then import and use the `org.bitcoindevkit` library in your Kotlin code. For example: ### bdk-jvm
```kotlin ```kotlin
import org.bitcoindevkit.* // build.gradle.kts
repositories {
// ... mavenCentral()
}
val externalDescriptor = "wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/0/*)" dependencies {
val internalDescriptor = "wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/1/*)" implementation("org.bitcoindevkit:bdk-jvm:<version>")
}
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 ### bdk-python
#### `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.
```shell ```shell
git clone https://github.com/bitcoindevkit/bdk-kotlin pip3 install bdkpython
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.<NDK_VERSION>
```
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
``` ```
## How to publish ### bdk-swift
Add bdk-swift to your dependencies in XCode.
### 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=<YOUR_GNUPG_ID>
signing.gnupg.passphrase=<YOUR_GNUPG_PASSPHRASE>
```
and use the `publishToMavenLocal` task without excluding the signing task:
```shell
./gradlew publishToMavenLocal
```
## Verifying Signatures ## Verifying Signatures
Both libraries and all their corresponding artifacts are signed with a PGP key you can find in the 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` Name: `bitcoindevkit-bindings`
Email: `bindings@bitcoindevkit.org` 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/ [Kotlin]: https://kotlinlang.org/
[Android Studio]: https://developer.android.com/studio/ [Android Studio]: https://developer.android.com/studio/
[`bdk`]: https://github.com/bitcoindevkit/bdk [`bdk`]: https://github.com/bitcoindevkit/bdk
[`bdk-ffi`]: https://github.com/bitcoindevkit/bdk-ffi [`bdk-ffi`]: https://github.com/bitcoindevkit/bdk-ffi
["Getting Started (Developer)"]: https://github.com/bitcoindevkit/bdk-ffi#getting-started-developer ["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.11.0/jar
[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.11.0/aar
[bdk-android]: https://search.maven.org/artifact/org.bitcoindevkit/bdk-android/0.9.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
## Thanks [bdk-swift (GitHub)]: https://github.com/bitcoindevkit/bdk-swift
[bdk-python (PyPI)]: https://pypi.org/project/bdkpython/
This project is made possible thanks to the wonderful work by the [mozilla/uniffi-rs] team.
[mozilla/uniffi-rs]: https://github.com/mozilla/uniffi-rs [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/

87
bdk-android/README.md Normal file
View File

@ -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:<version>")
}
```
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.<NDK_VERSION>
```
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=<YOUR_GNUPG_ID>
signing.gnupg.passphrase=<YOUR_GNUPG_PASSPHRASE>
```
and use the `publishToMavenLocal` task without excluding the signing task:
```shell
./gradlew publishToMavenLocal
```

73
bdk-jvm/README.md Normal file
View File

@ -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:<version>")
}
```
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=<YOUR_GNUPG_ID>
signing.gnupg.passphrase=<YOUR_GNUPG_PASSPHRASE>
```
and use the `publishToMavenLocal` task without excluding the signing task:
```shell
./gradlew publishToMavenLocal
```

7
bdk-python/README.md
View File

@ -2,14 +2,12 @@
The Python language bindings for the [bitcoindevkit](https://github.com/bitcoindevkit). The Python language bindings for the [bitcoindevkit](https://github.com/bitcoindevkit).
See the [package on PyPI](https://pypi.org/project/bdkpython/). See the [package on PyPI](https://pypi.org/project/bdkpython/).
<br/>
## Install from PyPI ## Install from PyPI
Install the latest release using Install the latest release using
```shell ```shell
pip install bdkpython pip install bdkpython
``` ```
<br/>
## Run the tests ## Run the tests
```shell ```shell
@ -19,7 +17,6 @@ python3 setup.py --verbose bdist_wheel
pip3 install ./dist/bdkpython-<yourversion>-py3-none-any.whl pip3 install ./dist/bdkpython-<yourversion>-py3-none-any.whl
python -m unittest --verbose tests/test_bdk.py python -m unittest --verbose tests/test_bdk.py
``` ```
<br/>
## Build the package ## Build the package
```shell ```shell
@ -32,20 +29,18 @@ bash generate.sh
# Build the wheel # Build the wheel
python3 setup.py --verbose bdist_wheel python3 setup.py --verbose bdist_wheel
``` ```
<br/>
## Run tox to build and test locally ## Run tox to build and test locally
```shell ```shell
# install dev requirements # install dev requirements
pip install --requirement requirements-dev.txt 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 source ./generate.sh
# build and test # build and test
tox -vv tox -vv
``` ```
<br/>
## Install locally ## Install locally
```shell ```shell