Clean up root readme and add individual libraries' readmes
This commit is contained in:
thunderbiscuit
parent
063f69222a
commit
3edda27ef2
198
README.md
198
README.md
@ -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>
|
||||
</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
|
||||
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
|
||||
1. update mapping `bdk.udl` file with new `dictionary`
|
||||
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`
|
||||
1. update mapping `bdk.udl` file with new `interface`
|
||||
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:<version>'
|
||||
// OR for android
|
||||
implementation 'org.bitcoindevkit:bdk-android:<version>'
|
||||
|
||||
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
|
||||
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:<version>")
|
||||
}
|
||||
```
|
||||
|
||||
### 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.<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
|
||||
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=<YOUR_GNUPG_ID>
|
||||
signing.gnupg.passphrase=<YOUR_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/
|
||||
|
||||
87
bdk-android/README.md
Normal file
87
bdk-android/README.md
Normal 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
73
bdk-jvm/README.md
Normal 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
|
||||
```
|
||||
@ -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/).
|
||||
<br/>
|
||||
|
||||
## Install from PyPI
|
||||
Install the latest release using
|
||||
```shell
|
||||
pip install bdkpython
|
||||
```
|
||||
<br/>
|
||||
|
||||
## Run the tests
|
||||
```shell
|
||||
@ -19,7 +17,6 @@ python3 setup.py --verbose bdist_wheel
|
||||
pip3 install ./dist/bdkpython-<yourversion>-py3-none-any.whl
|
||||
python -m unittest --verbose tests/test_bdk.py
|
||||
```
|
||||
<br/>
|
||||
|
||||
## Build the package
|
||||
```shell
|
||||
@ -32,20 +29,18 @@ bash generate.sh
|
||||
# Build the wheel
|
||||
python3 setup.py --verbose bdist_wheel
|
||||
```
|
||||
<br/>
|
||||
|
||||
## 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
|
||||
```
|
||||
<br/>
|
||||
|
||||
## Install locally
|
||||
```shell
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user