Update README.md
This commit is contained in:
Steve Myers
parent
d0be3bd6da
commit
e409856d62
156
README.md
156
README.md
@ -1,112 +1,98 @@
|
|||||||
# Foreign language bindings for BDK (bdk-ffi)
|
# bdk-kotlin
|
||||||
|
|
||||||
This repository contains source code for generating foreign language bindings
|
This project builds .jar and .aar packages for the `jvm` and `android` platforms that provide
|
||||||
for the rust library bdk for the Bitcoin Dev Kit (BDK) project.
|
[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.
|
||||||
|
|
||||||
## Supported target languages and platforms
|
## How to Use
|
||||||
|
|
||||||
| Language | Platform | Status |
|
To use the Kotlin language bindings for [`bdk`] in your `jvm` or `android` project add the
|
||||||
| --- | --- | --- |
|
following to your gradle dependencies:
|
||||||
| Kotlin | JVM | WIP |
|
```groovy
|
||||||
| Kotlin | Android | WIP |
|
repositories {
|
||||||
| Swift | iOS | WIP |
|
mavenCentral()
|
||||||
|
}
|
||||||
|
|
||||||
|
dependencies {
|
||||||
|
|
||||||
## Getting Started (User)
|
// for jvm
|
||||||
|
implementation 'org.bitcoindevkit:bdk-jvm:0.2.0'
|
||||||
|
// OR for android
|
||||||
|
implementation 'org.bitcoindevkit:bdk-android:0.2.0'
|
||||||
|
|
||||||
If you just want to consume the language bindings:
|
}
|
||||||
|
|
||||||
### Kotlin (JVM)
|
```
|
||||||
|
|
||||||
Just add the dependency `org.bitcoindevkit:bdk-jvm:0.1.1`. The package is `org.bitcoindevkit.bdk`.
|
You may then import and use the `org.bitcoindevkit` library in your Kotlin code. For example:
|
||||||
|
|
||||||
### Kotlin (Android)
|
```kotlin
|
||||||
|
import org.bitcoindevkit.*
|
||||||
|
|
||||||
Just add the dependency `org.bitcoindevkit:bdk-android:0.1.1`. The package is `org.bitcoindevkit.bdk`.
|
// ...
|
||||||
|
|
||||||
## Getting Started (Developer)
|
val descriptor = "wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/0/*)"
|
||||||
|
val db = DatabaseConfig.Memory("")
|
||||||
|
|
||||||
This project uses rust. A basic knowledge of the rust ecosystem is helpful.
|
val client =
|
||||||
|
BlockchainConfig.Electrum(
|
||||||
|
ElectrumConfig("ssl://electrum.blockstream.info:60002", null, 5u, null, 10u)
|
||||||
|
)
|
||||||
|
val wallet = OnlineWallet(descriptor, null, Network.TESTNET, db, client)
|
||||||
|
val newAddress = wallet.getNewAddress()
|
||||||
|
```
|
||||||
|
|
||||||
### General
|
### How to build
|
||||||
1. Install `uniffi-bindgen`
|
|
||||||
```sh
|
|
||||||
cargo install uniffi_bindgen
|
|
||||||
```
|
|
||||||
1. See the [UniFFI User Guide](https://mozilla.github.io/uniffi-rs/) for more info
|
|
||||||
|
|
||||||
### Kotlin Bindings for JVM (OSX / Linux)
|
|
||||||
|
|
||||||
1. Install required targets
|
1. Install required targets
|
||||||
```sh
|
```sh
|
||||||
rustup target add x86_64-apple-darwin x86_64-unknown-linux-gnu
|
rustup target add x86_64-linux-android aarch64-linux-android armv7-linux-androideabi i686-linux-android
|
||||||
```
|
|
||||||
1. Build kotlin (JVM) bindings
|
|
||||||
```sh
|
|
||||||
./build.sh -k
|
|
||||||
```
|
|
||||||
1. Generated kotlin bindings are available at `/bindings/bdk-kotlin/`
|
|
||||||
1. A demo app is available at `/bindings/bdk-kotlin/demo/`. It uses stdin for
|
|
||||||
inputs and can be run from gradle.
|
|
||||||
```sh
|
|
||||||
cd bindings/bdk-kotlin
|
|
||||||
./gradlew :demo:run
|
|
||||||
```
|
|
||||||
|
|
||||||
### Kotlin bindings for Android
|
|
||||||
|
|
||||||
1. Install required targets
|
|
||||||
```sh
|
|
||||||
rustup target add x86_64-linux-android aarch64-linux-android
|
|
||||||
armv7-linux-androideabi i686-linux-android
|
|
||||||
```
|
```
|
||||||
1. Install Android SDK and Build-Tools for API level 30+
|
1. Install Android SDK and Build-Tools for API level 30+
|
||||||
1. Setup `$ANDROID_NDK_HOME` and `$ANDROID_SDK_ROOT` path variables (which are
|
1. Setup `$ANDROID_SDK_ROOT` and `$ANDROID_NDK_HOME` path variables (which are required by the
|
||||||
required by the build scripts)
|
build scripts), for example:
|
||||||
1. Build kotlin (Android) bindings
|
```shell
|
||||||
```sh
|
export ANDROID_SDK_ROOT=~/Android/Sdk
|
||||||
./build.sh -a
|
export ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/21.3.6528147
|
||||||
```
|
```
|
||||||
2. A demo android app is available at [notmandatory/bdk-sample-app](https://github.com/notmandatory/bitcoindevkit-android-sample-app/tree/upgrade-to-bdk-ffi/)
|
1. Build kotlin bindings
|
||||||
|
|
||||||
### Swift bindings for iOS
|
|
||||||
|
|
||||||
1. Install the latest version of xcode, download and install the advanced tools.
|
|
||||||
1. Ensure Swift is installed
|
|
||||||
1. Install required targets
|
|
||||||
```sh
|
```sh
|
||||||
rustup target add aarch64-apple-ios x86_64-apple-ios
|
./build.sh
|
||||||
```
|
```
|
||||||
1. Build swift (iOS) bindings
|
|
||||||
```sh
|
### How to publish to your local maven repo
|
||||||
./build.sh -s
|
|
||||||
|
1. Set your `~/.gradle/gradle.properties` signing key values
|
||||||
|
```properties
|
||||||
|
signing.gnupg.keyName=<YOUR_GNUPG_ID>
|
||||||
|
signing.gnupg.passphrase=<YOUR_GNUPG_PASSPHRASE>
|
||||||
|
```
|
||||||
|
1. Publish
|
||||||
|
```shell
|
||||||
|
./gradlew :jvm:publishReleasePublicationToMavenLocal
|
||||||
|
./gradlew :android:publishReleasePublicationToMavenLocal
|
||||||
```
|
```
|
||||||
1. Example iOS app can be found in `/examples/iOS` which can be run by xcode.
|
|
||||||
|
|
||||||
## Notes
|
### How to publish to maven central (project maintainers only)
|
||||||
|
|
||||||
### Adding new structs and functions
|
1. Set your `~/.gradle/gradle.properties` signing key values and SONATYPE login
|
||||||
|
```properties
|
||||||
|
signing.gnupg.keyName=<YOUR_GNUPG_ID>
|
||||||
|
signing.gnupg.passphrase=<YOUR_GNUPG_PASSPHRASE>
|
||||||
|
|
||||||
See the [UniFFI User Guide](https://mozilla.github.io/uniffi-rs/)
|
ossrhUserName=<YOUR_SONATYPE_USERNAME>
|
||||||
|
ossrhPassword=<YOUR_SONATYPE_PASSWORD>
|
||||||
|
```
|
||||||
|
1. Publish
|
||||||
|
```shell
|
||||||
|
./gradlew :jvm:publishToSonatype closeAndReleaseSonatypeStagingRepository
|
||||||
|
./gradlew :android:publishToSonatype closeAndReleaseSonatypeStagingRepository
|
||||||
|
```
|
||||||
|
|
||||||
#### For pass by value objects
|
<!-- TODO A demo android app is available at [notmandatory/bdk-sample-app](https://github.com/notmandatory/bitcoindevkit-android-sample-app/tree/upgrade-to-bdk-ffi/) -->
|
||||||
|
|
||||||
1. create new rust struct with only fields that are supported UniFFI types
|
[Kotlin]: https://kotlinlang.org/
|
||||||
1. update mapping `bdk.udl` file with new `dictionary`
|
[Android Studio]: https://developer.android.com/studio/
|
||||||
|
[`bdk`]: https://github.com/bitcoindevkit/bdk
|
||||||
#### For pass by reference values
|
[`bdk-ffi`]: https://github.com/bitcoindevkit/bdk-ffi
|
||||||
|
["Getting Started (Developer)"]: https://github.com/bitcoindevkit/bdk-ffi#getting-started-developer
|
||||||
1. create wrapper rust struct/impl with only fields that are `Sync + Send`
|
|
||||||
1. 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
|
|
||||||
|
|
||||||
## Thanks
|
|
||||||
|
|
||||||
This project is made possible thanks to the wonderful work on [mozilla/uniffi-rs](https://github.com/mozilla/uniffi-rs)
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user