Bump version to 0.9.0

3c6075ad96 Add Balance struct and conversion from BdkBalance (thunderbiscuit)
4e15badb14 Update BDK to version 0.22 (thunderbiscuit)

Pull request description:

  The bindings do not build when attempting this upgrade because `get_balance()` now returns a `Balance` struct (this was merged in bitcoindevkit/bdk#640)

  ```sh
  error[E0308]: mismatched types
     --> src/lib.rs:433:9
      |
  432 |     fn get_balance(&self) -> Result<u64, Error> {
      |                              ------------------ expected `Result<u64, bdk::Error>` because of return type
  433 |         self.get_wallet().get_balance()
      |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected `u64`, found struct `Balance`
      |
      = note: expected enum `Result<u64, _>`
                 found enum `Result<Balance, _>`

  For more information about this error, try `rustc --explain E0308`.
  error: could not compile `bdk-ffi` due to previous error
  ```

  When we upgrade to `0.22.0` we could decide to add the `Balance` struct to the bindings, or simply return the total by calling `get_total()`, which returns a `u64` (same as we have now).

ACKs for top commit:
  notmandatory:
    ACK 3c6075ad96

Tree-SHA512: 13d2f83f992735f4f9619ae339d7834df08385129edf06bac830c298b433571af3f211e92a6da1f4f9646dec27dbd2c6133a035f26eac8757b7a1c94b54b463d

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: 'bug'
+assignees: ''
+
+---
+
+**Describe the bug**  
+<!-- A clear and concise description of what the bug is. -->
+
+**To Reproduce**  
+<!-- Steps or code to reproduce the behavior. -->
+
+**Expected behavior**  
+<!-- A clear and concise description of what you expected to happen. -->
+
+**Build environment**  
+ - BDK tag/commit: <!-- e.g. v0.13.0, 3a07614 --> 
+ - OS+version: <!-- e.g. ubuntu 20.04.01, macOS 12.0.1, windows -->  
+ - Rust/Cargo version: <!-- e.g. 1.56.0 --> 
+ - Rust/Cargo target: <!-- e.g. x86_64-apple-darwin, x86_64-unknown-linux-gnu, etc. -->  
+
+**Additional context**  
+<!-- Add any other context about the problem here. --> 

.github/ISSUE_TEMPLATE/summer_project.md

@@ -0,0 +1,77 @@
+---
+name: Summer of Bitcoin Project
+about: Template to suggest a new https://www.summerofbitcoin.org/ project.
+title: ''
+labels: 'summer-of-bitcoin'
+assignees: ''
+
+---
+
+<!--
+## Overview  
+
+Project ideas are scoped for a university-level student with a basic background in CS and bitcoin 
+fundamentals - achievable over 12-weeks. Below are just a few types of ideas: 
+
+ - Low-hanging fruit: Relatively short projects with clear goals; requires basic technical knowledge 
+   and minimal familiarity with the codebase.
+ - Core development: These projects derive from the ongoing work from the core of your development 
+   team. The list of features and bugs is never-ending, and help is always welcome.
+ - Risky/Exploratory: These projects push the scope boundaries of your development effort. They 
+   might require expertise in an area not covered by your current development team. They might take 
+   advantage of a new technology. There is a reasonable chance that the project might be less 
+   successful, but the potential rewards make it worth the attempt.
+ - Infrastructure/Automation: These projects are the code that your organization uses to get its 
+   development work done; for example, projects that improve the automation of releases, regression 
+   tests and automated builds. This is a category where a Summer of Bitcoin student can be really 
+   helpful, doing work that the development team has been putting off while they focus on core 
+   development.
+ - Quality Assurance/Testing: Projects that work on and test your project's software development 
+   process. Additionally, projects that involve a thorough test and review of individual PRs.
+ - Fun/Peripheral: These projects might not be related to the current core development focus, but 
+   create new innovations and new perspectives for your project.
+-->
+
+**Description**
+<!-- Description: 3-7 sentences describing the project background and tasks to be done. -->  
+
+**Expected Outcomes**  
+<!-- Short bullet list describing what is to be accomplished -->   
+
+**Resources**  
+<!-- 2-3 reading materials for candidate to learn about the repo, project, scope etc -->  
+<!-- Recommended reading such as a developer/contributor guide -->  
+<!-- [Another example a paper citation](https://arxiv.org/pdf/1802.08091.pdf) -->  
+<!-- [Another example an existing issue](https://github.com/opencv/opencv/issues/11013) -->  
+<!-- [An existing related module](https://github.com/opencv/opencv_contrib/tree/master/modules/optflow) -->  
+
+**Skills Required**  
+<!-- 3-4 technical skills that the candidate should know -->  
+<!-- hands on experience with git -->  
+<!-- mastery plus experience coding in C++ -->  
+<!-- basic knowledge in matrix and tensor computations, college course work in cryptography -->  
+<!-- strong mathematical background -->
+<!-- Bonus - has experience with React Native. Best if you have also worked with OSSFuzz -->
+
+**Mentor(s)**  
+<!-- names of mentor(s) for this project go here -->
+
+**Difficulty**  
+<!-- Easy, Medium, Hard -->
+
+**Competency Test (optional)**  
+<!-- 2-3 technical tasks related to the project idea or repository you’d like a candidate to 
+    perform in order to demonstrate competency, good first bugs, warm-up exercises -->
+<!-- ex. Read the instructions here to get Bitcoin core running on your machine -->
+<!-- ex. pick an issue labeled as “newcomer” in the repository, and send a merge request to the 
+    repository. You can also suggest some other improvement that we did not think of yet, or 
+    something that you find interesting or useful -->
+<!-- ex. fixes for coding style are usually easy to do, and are good issues for first time 
+    contributions for those learning how to interact with the project. After you are done with the 
+    coding style issue, try making a different contribution. -->
+<!-- ex. setup a full Debian packaging development environment and learn the basics of Debian 
+    packaging. Then identify and package the missing dependencies to package Specter Desktop -->
+<!-- ex. write a pull parser for CSV files. You'll be judged by the decisions to store the parser 
+    state and how flexible it is to wrap this parser in other scenarios. -->
+<!-- ex. Stretch Goal: Implement some basic metaprogram/app to prove you're very familiar with BDK. 
+    Be prepared to make adjustments as we judge your solution. -->

.github/pull_request_template.md

@@ -0,0 +1,30 @@
+<!-- You can erase any parts of this template not applicable to your Pull Request. -->
+
+### Description
+
+<!-- Describe the purpose of this PR, what's being adding and/or fixed -->
+
+### Notes to the reviewers
+
+<!-- In this section you can include notes directed to the reviewers, like explaining why some parts
+of the PR were done in a specific way -->
+
+### Checklists
+
+#### All Submissions:
+
+* [ ] I've signed all my commits
+* [ ] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
+* [ ] I ran `cargo fmt` and `cargo clippy` before committing
+
+#### New Features:
+
+* [ ] I've added tests for the new feature
+* [ ] I've added docs for the new feature
+* [ ] I've updated `CHANGELOG.md`
+
+#### Bugfixes:
+
+* [ ] This pull request breaks the existing API
+* [ ] I've added tests to reproduce the issue which are now passing
+* [ ] I'm linking the issue being fixed by this PR

.github/workflows/audit.yml

@@ -0,0 +1,19 @@
+name: Audit
+
+on:
+  push:
+    paths:
+      - '**/Cargo.toml'
+      - '**/Cargo.lock'
+  schedule:
+    - cron: '0 0 * * 0' # Once per week
+
+jobs:
+
+  security_audit:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/audit-check@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/cont_integration.yml

@@ -0,0 +1,61 @@
+on: [push, pull_request]
+
+name: CI
+
+jobs:
+
+  build-test:
+    name: Build and test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        rust:
+          - version: 1.63.0 # STABLE
+            clippy: true
+          - version: 1.61.0 # MSRV
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+      - name: Generate cache key
+        run: echo "${{ matrix.rust.version }} ${{ matrix.features }}" | tee .cache_key
+      - name: cache
+        uses: actions/cache@v2
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('.cache_key') }}-${{ hashFiles('**/Cargo.toml','**/Cargo.lock') }}
+      - name: Set default toolchain
+        run: rustup default ${{ matrix.rust.version }}
+      - name: Set profile
+        run: rustup set profile minimal
+      - name: Add clippy
+        if: ${{ matrix.rust.clippy }}
+        run: rustup component add clippy
+      - name: Update toolchain
+        run: rustup update
+      - name: Build
+        run: cargo build
+      - name: Clippy
+        if: ${{ matrix.rust.clippy }}
+        run: cargo clippy --all-targets -- -D warnings
+      - name: Test
+        run: cargo test
+
+  fmt:
+    name: Rust fmt
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Set default toolchain
+        run: rustup default nightly
+      - name: Set profile
+        run: rustup set profile minimal
+      - name: Add rustfmt
+        run: rustup component add rustfmt
+      - name: Update toolchain
+        run: rustup update
+      - name: Check fmt
+        run: cargo fmt --all -- --config format_code_in_doc_comments=true --check

CHANGELOG.md

@@ -6,8 +6,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [v0.7.0]
+## [v0.9.0]
+- Breaking Changes
+  - Rename `get_network()` method on `Wallet` interface to `network()` [#185]
+  - Rename `get_transactions()` method on `Wallet` interface to `list_transactions()` [#185]
+  - Remove `generate_extended_key`, returned ExtendedKeyInfo [#154]
+  - Remove `restore_extended_key`, returned ExtendedKeyInfo [#154]
+  - Remove dictionary `ExtendedKeyInfo {mnenonic, xprv, fingerprint}` [#154]
+  - Remove interface `Transaction` [#190]
+  - Changed `Wallet` interface `list_transaction()` to return array of `TransactionDetails` [#190]
+  - Update `bdk` dependency version to 0.22 [#193]
+- APIs Added [#154]
+  - `generate_mnemonic()`, returns string mnemonic
+  - `interface DescriptorSecretKey`
+    - `new(Network, string_mnenoinc, password)`, contructs DescriptorSecretKey
+    - `derive(DerivationPath)`, derives and returns child DescriptorSecretKey
+    - `extend(DerivationPath)`, extends and returns DescriptorSecretKey
+    - `as_public()`, returns DescriptorSecretKey as DescriptorPublicKey
+    - `as_string()`, returns DescriptorSecretKey as String
+  - `interface DescriptorPublicKey`
+    - `derive(DerivationPath)` derives and returns child DescriptorPublicKey
+    - `extend(DerivationPath)` extends and returns DescriptorPublicKey
+    - `as_string()` returns DescriptorPublicKey as String
+  - Add to `interface Blockchain` the `get_height()` and `get_block_hash()` methods [#184]
+  - Add to `interface TxBuilder`  the `set_recipients(recipient: Vec<AddressAmount>)` method [#186]
+  - Add to `dictionary TransactionDetails` the `confirmation_time` field [#190]
+- Interfaces Added [#154]
+  - `DescriptorSecretKey`
+  - `DescriptorPublicKey`
+  - `DerivationPath`
 
+[#154]: https://github.com/bitcoindevkit/bdk-ffi/pull/154
+[#184]: https://github.com/bitcoindevkit/bdk-ffi/pull/184
+[#185]: https://github.com/bitcoindevkit/bdk-ffi/pull/185
+[#193]: https://github.com/bitcoindevkit/bdk-ffi/pull/193
+
+## [v0.8.0]
+- Update BDK to version 0.20.0 [#169]
+- APIs Added
+  - `TxBuilder.add_data(data: Vec<u8>)` [#163]
+  - `Wallet.list_unspent()` returns `Vec<LocalUtxo>` [#158]
+  - Add coin control methods on TxBuilder [#164]
+
+[#163]: https://github.com/bitcoindevkit/bdk-ffi/pull/163
+[#158]: https://github.com/bitcoindevkit/bdk-ffi/pull/158
+[#164]: https://github.com/bitcoindevkit/bdk-ffi/pull/164
+[#169]: https://github.com/bitcoindevkit/bdk-ffi/pull/169
+[#190]: https://github.com/bitcoindevkit/bdk-ffi/pull/190
+
+## [v0.7.0]
 - Update BDK to version 0.19.0
   - fixes sqlite-db issue causing wrong balance
   - adds experimental taproot descriptor and PSBT support
@@ -23,13 +70,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#161]: https://github.com/bitcoindevkit/bdk-ffi/pull/161
 
 ## [v0.6.0]
-
 - Update BDK to version 0.18.0
 - Add BumpFeeTxBuilder to bump the fee on an unconfirmed tx created by the Wallet
 - Change TxBuilder.build() to TxBuilder.finish() to align with bdk function name 
 
 ## [v0.5.0]
-
 - Fix Wallet.broadcast function, now returns a tx id as a hex string
 - Remove creating a new spending Transaction via the PartiallySignedBitcoinTransaction constructor
 - Add TxBuilder for creating new spending PartiallySignedBitcoinTransaction
@@ -38,17 +83,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update generate cli tool to generate all binding languages and rename to bdk-ffi-bindgen
 
 ## [v0.4.0]
-
 - Add dual license MIT and Apache 2.0
 - Add sqlite database support
 - Fix memory database configuration enum, remove junk field
 
 ## [v0.3.1]
-
 - Remove hard coded sync progress value (was always returning 21.0)
 
 ## [v0.3.0]
-
 - Move bdk-kotlin bindings and ios example to separate repos
 - Add bin to generate Python bindings
 - Add `PartiallySignedBitcoinTransaction::deserialize` function as named constructor to decode from a string per [BIP 0174]
@@ -59,7 +101,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [v0.2.0]
 
-[unreleased]: https://github.com/bitcoindevkit/bdk-ffi/compare/v0.7.0...HEAD
+[unreleased]: https://github.com/bitcoindevkit/bdk-ffi/compare/v0.9.0...HEAD
+[v0.9.0]: https://github.com/bitcoindevkit/bdk-ffi/compare/v0.8.0...v0.9.0
+[v0.8.0]: https://github.com/bitcoindevkit/bdk-ffi/compare/v0.7.0...v0.8.0
 [v0.7.0]: https://github.com/bitcoindevkit/bdk-ffi/compare/v0.6.0...v0.7.0
 [v0.6.0]: https://github.com/bitcoindevkit/bdk-ffi/compare/v0.5.0...v0.6.0
 [v0.5.0]: https://github.com/bitcoindevkit/bdk-ffi/compare/v0.4.0...v0.5.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bdk-ffi"
-version = "0.7.0"
+version = "0.9.0"
 authors = ["Steve Myers <steve@notmandatory.org>", "Sudarsan Balaji <sudarsan.balaji@artfuldev.com>"]
 edition = "2018"
 
@@ -14,10 +14,10 @@ crate-type = ["staticlib", "cdylib"]
 name = "bdkffi"
 
 [dependencies]
-bdk = { version = "0.19", features = ["all-keys", "use-esplora-ureq", "sqlite-bundled"] }
+bdk = { version = "0.22", features = ["all-keys", "use-esplora-ureq", "sqlite-bundled"] }
 
-uniffi_macros = { version = "0.16.0", features = ["builtin-bindgen"] }
-uniffi = { version = "0.16.0", features = ["builtin-bindgen"] }
+uniffi_macros = { version = "0.19.3", features = ["builtin-bindgen"] }
+uniffi = { version = "0.19.3", features = ["builtin-bindgen"] }
 
 [build-dependencies]
-uniffi_build = { version = "0.16.0", features = ["builtin-bindgen"] }
+uniffi_build = { version = "0.19.3", features = ["builtin-bindgen"] }

README.md

@@ -1,5 +1,12 @@
 # Native language bindings for BDK
 
+<p>
+    <a href="https://github.com/bitcoindevkit/bdk-ffi/blob/master/LICENSE"><img alt="MIT or Apache-2.0 Licensed" src="https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg"/></a>
+    <a href="https://github.com/bitcoindevkit/bdk-ffi/actions?query=workflow%3ACI"><img alt="CI Status" src="https://github.com/bitcoindevkit/bdk-ffi/workflows/CI/badge.svg"></a>
+    <a href="https://blog.rust-lang.org/2022/05/19/Rust-1.61.0.html"><img alt="Rustc Version 1.61.0+" src="https://img.shields.io/badge/rustc-1.61.0%2B-lightgrey.svg"/></a>
+    <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 
 [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.
@@ -35,7 +42,7 @@ cargo run -p bdk-ffi-bindgen -- --help
 
 [bdk-kotlin]: https://github.com/bitcoindevkit/bdk-kotlin
 [bdk-swift]: https://github.com/bitcoindevkit/bdk-swift
-[bdk-python]: https://github.com/thunderbiscuit/bdk-python
+[bdk-python]: https://github.com/bitcoindevkit/bdk-python
 
 ## Contributing
 

bdk-ffi-bindgen/Cargo.toml

@@ -3,9 +3,8 @@ name = "bdk-ffi-bindgen"
 version = "0.2.0"
 edition = "2021"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
 anyhow = "=1.0.45" # remove after upgrading to next version of uniffi
 structopt = "0.3"
-uniffi_bindgen = "0.16.0"
+uniffi_bindgen = "0.19.5"
+camino = "1.0.9"

bdk-ffi-bindgen/src/main.rs

@@ -1,9 +1,10 @@
+use camino::Utf8Path;
 use std::fmt;
 use std::path::{Path, PathBuf};
 use std::str::FromStr;
 use structopt::StructOpt;
 
-#[derive(Debug, PartialEq)]
+#[derive(Debug, Eq, PartialEq)]
 pub enum Language {
     Kotlin,
     Python,
@@ -44,11 +45,14 @@ impl FromStr for Language {
 }
 
 fn generate_bindings(opt: &Opt) -> anyhow::Result<(), anyhow::Error> {
+    let path: &Utf8Path = Utf8Path::from_path(&opt.udl_file).unwrap();
+    let out_dir: &Utf8Path = Utf8Path::from_path(&opt.out_dir).unwrap();
     uniffi_bindgen::generate_bindings(
-        &opt.udl_file,
+        path,
         None,
         vec![opt.language.to_string().as_str()],
-        Some(&opt.out_dir),
+        Some(out_dir),
+        None,
         false,
     )?;
 

src/bdk.udl

@@ -1,15 +1,13 @@
 namespace bdk {
   [Throws=BdkError]
-  ExtendedKeyInfo generate_extended_key(Network network, WordCount word_count, string? password);
-
-  [Throws=BdkError]
-  ExtendedKeyInfo restore_extended_key(Network network, string mnemonic, string? password);
+  string generate_mnemonic(WordCount word_count);
 };
 
 [Error]
 enum BdkError {
   "InvalidU32Bytes",
   "Generic",
+  "MissingCachedScripts",
   "ScriptDoesntHaveAddressForm",
   "NoRecipients",
   "NoUtxosSelected",
@@ -76,6 +74,15 @@ dictionary SqliteDbConfiguration {
   string path;
 };
 
+dictionary Balance {
+  u64 immature;
+  u64 trusted_pending;
+  u64 untrusted_pending;
+  u64 confirmed;
+  u64 spendable;
+  u64 total;
+};
+
 [Enum]
 interface DatabaseConfig {
   Memory();
@@ -88,6 +95,7 @@ dictionary TransactionDetails {
   u64 received;
   u64 sent;
   string txid;
+  BlockTime? confirmation_time;
 };
 
 dictionary BlockTime {
@@ -95,18 +103,6 @@ dictionary BlockTime {
   u64 timestamp;
 };
 
-[Enum]
-interface Transaction {
-  Unconfirmed(TransactionDetails details);
-  Confirmed(TransactionDetails details, BlockTime confirmation);
-};
-
-dictionary ExtendedKeyInfo {
-  string mnemonic;
-  string xprv;
-  string fingerprint;
-};
-
 enum WordCount {
   "Words12",
   "Words15",
@@ -143,12 +139,45 @@ interface Blockchain {
 
   [Throws=BdkError]
   void broadcast([ByRef] PartiallySignedBitcoinTransaction psbt);
+
+  [Throws=BdkError]
+  u32 get_height();
+
+  [Throws=BdkError]
+  string get_block_hash(u32 height);
 };
 
 callback interface Progress {
   void update(f32 progress, string? message);
 };
 
+dictionary OutPoint {
+  string txid;
+  u32 vout;
+};
+
+dictionary TxOut {
+  u64 value;
+  string address;
+};
+
+enum KeychainKind {
+  "External",
+  "Internal",
+};
+
+dictionary LocalUtxo {
+  OutPoint outpoint;
+  TxOut txout;
+  KeychainKind keychain;
+  boolean is_spent;
+};
+
+dictionary AddressAmount {
+  string address;
+  u64 amount;
+};
+
 interface Wallet {
   [Throws=BdkError]
   constructor(string descriptor, string? change_descriptor, Network network, DatabaseConfig database_config);
@@ -157,18 +186,21 @@ interface Wallet {
   AddressInfo get_address(AddressIndex address_index);
 
   [Throws=BdkError]
-  u64 get_balance();
+  Balance get_balance();
 
   [Throws=BdkError]
   boolean sign([ByRef] PartiallySignedBitcoinTransaction psbt);
 
   [Throws=BdkError]
-  sequence<Transaction> get_transactions();
+  sequence<TransactionDetails> list_transactions();
 
-  Network get_network();
+  Network network();
 
   [Throws=BdkError]
   void sync([ByRef] Blockchain blockchain, Progress? progress);
+
+  [Throws=BdkError]
+  sequence<LocalUtxo> list_unspent();
 };
 
 interface PartiallySignedBitcoinTransaction {
@@ -185,8 +217,24 @@ interface TxBuilder {
 
   TxBuilder add_recipient(string address, u64 amount);
 
+  TxBuilder add_unspendable(OutPoint unspendable);
+
+  TxBuilder add_utxo(OutPoint outpoint);
+
+  TxBuilder add_utxos(sequence<OutPoint> outpoints);
+
+  TxBuilder do_not_spend_change();
+
+  TxBuilder manually_selected_only();
+
+  TxBuilder only_spend_change();
+
+  TxBuilder unspendable(sequence<OutPoint> unspendable);
+
   TxBuilder fee_rate(float sat_per_vbyte);
 
+  TxBuilder fee_absolute(u64 fee_amount);
+
   TxBuilder drain_wallet();
 
   TxBuilder drain_to(string address);
@@ -195,6 +243,10 @@ interface TxBuilder {
 
   TxBuilder enable_rbf_with_sequence(u32 nsequence);
 
+  TxBuilder add_data(sequence<u8> data);
+
+  TxBuilder set_recipients(sequence<AddressAmount> recipients);
+
   [Throws=BdkError]
   PartiallySignedBitcoinTransaction finish([ByRef] Wallet wallet);
 };
@@ -211,3 +263,31 @@ interface BumpFeeTxBuilder {
   [Throws=BdkError]
   PartiallySignedBitcoinTransaction finish([ByRef] Wallet wallet);
 };
+
+interface DerivationPath {
+  [Throws=BdkError]
+  constructor(string path);
+};
+
+interface DescriptorSecretKey {
+  [Throws=BdkError]
+  constructor(Network network, string mnemonic, string? password);
+
+  [Throws=BdkError]
+  DescriptorSecretKey derive(DerivationPath path);
+
+  DescriptorSecretKey extend(DerivationPath path);
+
+  DescriptorPublicKey as_public();
+
+  string as_string();
+};
+
+interface DescriptorPublicKey {
+  [Throws=BdkError]
+  DescriptorPublicKey derive(DerivationPath path);
+
+  DescriptorPublicKey extend(DerivationPath path);
+
+  string as_string();
+};

src/lib.rs

@@ -1,22 +1,32 @@
 use bdk::bitcoin::hashes::hex::ToHex;
 use bdk::bitcoin::secp256k1::Secp256k1;
+use bdk::bitcoin::util::bip32::DerivationPath as BdkDerivationPath;
 use bdk::bitcoin::util::psbt::PartiallySignedTransaction;
-use bdk::bitcoin::{Address, Network, Script, Txid};
+use bdk::bitcoin::{Address, Network, OutPoint as BdkOutPoint, Script, Txid};
 use bdk::blockchain::any::{AnyBlockchain, AnyBlockchainConfig};
+use bdk::blockchain::GetBlockHash;
+use bdk::blockchain::GetHeight;
 use bdk::blockchain::{
     electrum::ElectrumBlockchainConfig, esplora::EsploraBlockchainConfig, ConfigurableBlockchain,
 };
 use bdk::blockchain::{Blockchain as BdkBlockchain, Progress as BdkProgress};
 use bdk::database::any::{AnyDatabase, SledDbConfiguration, SqliteDbConfiguration};
 use bdk::database::{AnyDatabaseConfig, ConfigurableDatabase};
+use bdk::descriptor::DescriptorXKey;
 use bdk::keys::bip39::{Language, Mnemonic, WordCount};
-use bdk::keys::{DerivableKey, ExtendedKey, GeneratableKey, GeneratedKey};
+use bdk::keys::{
+    DerivableKey, DescriptorPublicKey as BdkDescriptorPublicKey,
+    DescriptorSecretKey as BdkDescriptorSecretKey, ExtendedKey, GeneratableKey, GeneratedKey,
+};
 use bdk::miniscript::BareCtx;
+use bdk::wallet::tx_builder::ChangeSpendPolicy;
 use bdk::wallet::AddressIndex as BdkAddressIndex;
 use bdk::wallet::AddressInfo as BdkAddressInfo;
 use bdk::{
-    BlockTime, Error, FeeRate, SignOptions, SyncOptions as BdkSyncOptions, Wallet as BdkWallet,
+    Balance as BdkBalance, BlockTime, Error, FeeRate, KeychainKind, SignOptions,
+    SyncOptions as BdkSyncOptions, Wallet as BdkWallet,
 };
+use std::collections::HashSet;
 use std::convert::{From, TryFrom};
 use std::fmt;
 use std::ops::Deref;
@@ -27,8 +37,16 @@ uniffi_macros::include_scaffolding!("bdk");
 
 type BdkError = Error;
 
+pub struct AddressAmount {
+    pub address: String,
+    pub amount: u64,
+}
+
+/// A derived address and the index it was found at.
 pub struct AddressInfo {
+    /// Child index of this address
     pub index: u32,
+    /// Address
     pub address: String,
 }
 
@@ -41,8 +59,17 @@ impl From<BdkAddressInfo> for AddressInfo {
     }
 }
 
+/// The address index selection strategy to use to derived an address from the wallet's external
+/// descriptor.
 pub enum AddressIndex {
+    /// Return a new address after incrementing the current descriptor index.
     New,
+    /// Return the address for the current descriptor index if it has not been used in a received
+    /// transaction. Otherwise return a new address as with AddressIndex::New.
+    /// Use with caution, if the wallet has not yet detected an address has been used it could
+    /// return an already used address. This function is primarily meant for situations where the
+    /// caller is untrusted; for example when deriving donation addresses on-demand for a public
+    /// web page.
     LastUnused,
 }
 
@@ -55,50 +82,82 @@ impl From<AddressIndex> for BdkAddressIndex {
     }
 }
 
+/// Type that can contain any of the database configurations defined by the library
+/// This allows storing a single configuration that can be loaded into an AnyDatabaseConfig
+/// instance. Wallets that plan to offer users the ability to switch blockchain backend at runtime
+/// will find this particularly useful.
 pub enum DatabaseConfig {
+    /// Memory database has no config
     Memory,
+    /// Simple key-value embedded database based on sled
     Sled { config: SledDbConfiguration },
+    /// Sqlite embedded database using rusqlite
     Sqlite { config: SqliteDbConfiguration },
 }
 
+/// Configuration for an ElectrumBlockchain
 pub struct ElectrumConfig {
+    /// URL of the Electrum server (such as ElectrumX, Esplora, BWT) may start with ssl:// or tcp:// and include a port
+    /// e.g. ssl://electrum.blockstream.info:60002
     pub url: String,
+    /// URL of the socks5 proxy server or a Tor service
     pub socks5: Option<String>,
+    /// Request retry count
     pub retry: u8,
+    /// Request timeout (seconds)
     pub timeout: Option<u8>,
+    /// Stop searching addresses for transactions after finding an unused gap of this length
     pub stop_gap: u64,
 }
 
+/// Configuration for an EsploraBlockchain
 pub struct EsploraConfig {
+    /// Base URL of the esplora service
+    /// e.g. https://blockstream.info/api/
     pub base_url: String,
+    /// Optional URL of the proxy to use to make requests to the Esplora server
+    /// The string should be formatted as: <protocol>://<user>:<password>@host:<port>.
+    /// Note that the format of this value and the supported protocols change slightly between the
+    /// sync version of esplora (using ureq) and the async version (using reqwest). For more
+    /// details check with the documentation of the two crates. Both of them are compiled with
+    /// the socks feature enabled.
+    /// The proxy is ignored when targeting wasm32.
     pub proxy: Option<String>,
+    /// Number of parallel requests sent to the esplora service (default: 4)
     pub concurrency: Option<u8>,
+    /// Stop searching addresses for transactions after finding an unused gap of this length.
     pub stop_gap: u64,
+    /// Socket timeout.
     pub timeout: Option<u64>,
 }
 
+/// Type that can contain any of the blockchain configurations defined by the library.
 pub enum BlockchainConfig {
+    /// Electrum client
     Electrum { config: ElectrumConfig },
+    /// Esplora client
     Esplora { config: EsploraConfig },
 }
 
+/// A wallet transaction
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct TransactionDetails {
-    pub fee: Option<u64>,
-    pub received: u64,
-    pub sent: u64,
+    /// Transaction id.
     pub txid: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum Transaction {
-    Unconfirmed {
-        details: TransactionDetails,
-    },
-    Confirmed {
-        details: TransactionDetails,
-        confirmation: BlockTime,
-    },
+    /// Received value (sats)
+    /// Sum of owned outputs of this transaction.
+    pub received: u64,
+    /// Sent value (sats)
+    /// Sum of owned inputs of this transaction.
+    pub sent: u64,
+    /// Fee value (sats) if confirmed.
+    /// The availability of the fee depends on the backend. It's never None with an Electrum
+    /// Server backend, but it could be None with a Bitcoin RPC node without txindex that receive
+    /// funds while offline.
+    pub fee: Option<u64>,
+    /// If the transaction is confirmed, contains height and timestamp of the block containing the
+    /// transaction, unconfirmed transaction contains `None`.
+    pub confirmation_time: Option<BlockTime>,
 }
 
 impl From<&bdk::TransactionDetails> for TransactionDetails {
@@ -108,20 +167,7 @@ impl From<&bdk::TransactionDetails> for TransactionDetails {
             txid: x.txid.to_string(),
             received: x.received,
             sent: x.sent,
-        }
-    }
-}
-
-impl From<&bdk::TransactionDetails> for Transaction {
-    fn from(x: &bdk::TransactionDetails) -> Transaction {
-        match x.confirmation_time.clone() {
-            Some(block_time) => Transaction::Confirmed {
-                details: TransactionDetails::from(x),
-                confirmation: block_time,
-            },
-            None => Transaction::Unconfirmed {
-                details: TransactionDetails::from(x),
-            },
+            confirmation_time: x.confirmation_time.clone(),
         }
     }
 }
@@ -166,13 +212,115 @@ impl Blockchain {
         let tx = psbt.internal.lock().unwrap().clone().extract_tx();
         self.get_blockchain().broadcast(&tx)
     }
+
+    fn get_height(&self) -> Result<u32, Error> {
+        self.get_blockchain().get_height()
+    }
+
+    fn get_block_hash(&self, height: u32) -> Result<String, Error> {
+        self.get_blockchain()
+            .get_block_hash(u64::from(height))
+            .map(|hash| hash.to_string())
+    }
 }
 
 struct Wallet {
     wallet_mutex: Mutex<BdkWallet<AnyDatabase>>,
 }
 
+/// A reference to a transaction output.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct OutPoint {
+    /// The referenced transaction's txid.
+    txid: String,
+    /// The index of the referenced output in its transaction's vout.
+    vout: u32,
+}
+
+impl From<&OutPoint> for BdkOutPoint {
+    fn from(x: &OutPoint) -> BdkOutPoint {
+        BdkOutPoint {
+            txid: Txid::from_str(&x.txid).unwrap(),
+            vout: x.vout,
+        }
+    }
+}
+
+pub struct Balance {
+    // All coinbase outputs not yet matured
+    pub immature: u64,
+    /// Unconfirmed UTXOs generated by a wallet tx
+    pub trusted_pending: u64,
+    /// Unconfirmed UTXOs received from an external wallet
+    pub untrusted_pending: u64,
+    /// Confirmed and immediately spendable balance
+    pub confirmed: u64,
+    /// Get sum of trusted_pending and confirmed coins
+    pub spendable: u64,
+    /// Get the whole balance visible to the wallet
+    pub total: u64,
+}
+
+impl From<BdkBalance> for Balance {
+    fn from(bdk_balance: BdkBalance) -> Self {
+        Balance {
+            immature: bdk_balance.immature,
+            trusted_pending: bdk_balance.trusted_pending,
+            untrusted_pending: bdk_balance.untrusted_pending,
+            confirmed: bdk_balance.confirmed,
+            spendable: bdk_balance.get_spendable(),
+            total: bdk_balance.get_total(),
+        }
+    }
+}
+
+/// A transaction output, which defines new coins to be created from old ones.
+pub struct TxOut {
+    /// The value of the output, in satoshis.
+    value: u64,
+    /// The address of the output.
+    address: String,
+}
+
+pub struct LocalUtxo {
+    outpoint: OutPoint,
+    txout: TxOut,
+    keychain: KeychainKind,
+    is_spent: bool,
+}
+
+// This trait is used to convert the bdk TxOut type with field `script_pubkey: Script`
+// into the bdk-ffi TxOut type which has a field `address: String` instead
+trait NetworkLocalUtxo {
+    fn from_utxo(x: &bdk::LocalUtxo, network: Network) -> LocalUtxo;
+}
+
+impl NetworkLocalUtxo for LocalUtxo {
+    fn from_utxo(x: &bdk::LocalUtxo, network: Network) -> LocalUtxo {
+        LocalUtxo {
+            outpoint: OutPoint {
+                txid: x.outpoint.txid.to_string(),
+                vout: x.outpoint.vout,
+            },
+            txout: TxOut {
+                value: x.txout.value,
+                address: bdk::bitcoin::util::address::Address::from_script(
+                    &x.txout.script_pubkey,
+                    network,
+                )
+                .unwrap()
+                .to_string(),
+            },
+            keychain: x.keychain,
+            is_spent: x.is_spent,
+        }
+    }
+}
+
+/// Trait that logs at level INFO every update received (if any).
 pub trait Progress: Send + Sync + 'static {
+    /// Send a new progress update. The progress value should be in the range 0.0 - 100.0, and the message value is an
+    /// optional text message that can be displayed to the user.
     fn update(&self, progress: f32, message: Option<String>);
 }
 
@@ -218,6 +366,11 @@ impl PartiallySignedBitcoinTransaction {
     }
 }
 
+/// A Bitcoin wallet.
+/// The Wallet acts as a way of coherently interfacing with output descriptors and related transactions. Its main components are:
+///     1. Output descriptors from which it can derive addresses.
+///     2. A Database where it tracks transactions and utxos related to the descriptors.
+///     3. Signers that can contribute signatures to addresses instantiated from the descriptors.
 impl Wallet {
     fn new(
         descriptor: String,
@@ -244,10 +397,12 @@ impl Wallet {
         self.wallet_mutex.lock().expect("wallet")
     }
 
-    fn get_network(&self) -> Network {
+    /// Get the Bitcoin network the wallet is using.
+    fn network(&self) -> Network {
         self.get_wallet().network()
     }
 
+    /// Sync the internal database with the blockchain.
     fn sync(
         &self,
         blockchain: &Blockchain,
@@ -264,65 +419,45 @@ impl Wallet {
         self.get_wallet().sync(blockchain.deref(), bdk_sync_opts)
     }
 
+    /// Return a derived address using the external descriptor, see AddressIndex for available address index selection
+    /// strategies. If none of the keys in the descriptor are derivable (i.e. the descriptor does not end with a * character)
+    /// then the same address will always be returned for any AddressIndex.
     fn get_address(&self, address_index: AddressIndex) -> Result<AddressInfo, BdkError> {
         self.get_wallet()
             .get_address(address_index.into())
             .map(AddressInfo::from)
     }
 
-    fn get_balance(&self) -> Result<u64, Error> {
-        self.get_wallet().get_balance()
+    /// Return the balance, meaning the sum of this wallet’s unspent outputs’ values. Note that this method only operates
+    /// on the internal database, which first needs to be Wallet.sync manually.
+    fn get_balance(&self) -> Result<Balance, Error> {
+        self.get_wallet().get_balance().map(|b| b.into())
     }
 
+    /// Sign a transaction with all the wallet’s signers.
     fn sign(&self, psbt: &PartiallySignedBitcoinTransaction) -> Result<bool, Error> {
         let mut psbt = psbt.internal.lock().unwrap();
         self.get_wallet().sign(&mut psbt, SignOptions::default())
     }
 
-    fn get_transactions(&self) -> Result<Vec<Transaction>, Error> {
-        let transactions = self.get_wallet().list_transactions(true)?;
-        Ok(transactions.iter().map(Transaction::from).collect())
+    /// Return the list of transactions made and received by the wallet. Note that this method only operate on the internal database, which first needs to be [Wallet.sync] manually.
+    fn list_transactions(&self) -> Result<Vec<TransactionDetails>, Error> {
+        let transaction_details = self.get_wallet().list_transactions(true)?;
+        Ok(transaction_details
+            .iter()
+            .map(TransactionDetails::from)
+            .collect())
     }
-}
 
-pub struct ExtendedKeyInfo {
-    mnemonic: String,
-    xprv: String,
-    fingerprint: String,
-}
-
-fn generate_extended_key(
-    network: Network,
-    word_count: WordCount,
-    password: Option<String>,
-) -> Result<ExtendedKeyInfo, Error> {
-    let mnemonic: GeneratedKey<_, BareCtx> =
-        Mnemonic::generate((word_count, Language::English)).unwrap();
-    let mnemonic = mnemonic.into_key();
-    let xkey: ExtendedKey = (mnemonic.clone(), password).into_extended_key()?;
-    let xprv = xkey.into_xprv(network).unwrap();
-    let fingerprint = xprv.fingerprint(&Secp256k1::new());
-    Ok(ExtendedKeyInfo {
-        mnemonic: mnemonic.to_string(),
-        xprv: xprv.to_string(),
-        fingerprint: fingerprint.to_string(),
-    })
-}
-
-fn restore_extended_key(
-    network: Network,
-    mnemonic: String,
-    password: Option<String>,
-) -> Result<ExtendedKeyInfo, Error> {
-    let mnemonic = Mnemonic::parse_in(Language::English, mnemonic).unwrap();
-    let xkey: ExtendedKey = (mnemonic.clone(), password).into_extended_key()?;
-    let xprv = xkey.into_xprv(network).unwrap();
-    let fingerprint = xprv.fingerprint(&Secp256k1::new());
-    Ok(ExtendedKeyInfo {
-        mnemonic: mnemonic.to_string(),
-        xprv: xprv.to_string(),
-        fingerprint: fingerprint.to_string(),
-    })
+    /// Return the list of unspent outputs of this wallet. Note that this method only operates on the internal database,
+    /// which first needs to be Wallet.sync manually.
+    fn list_unspent(&self) -> Result<Vec<LocalUtxo>, Error> {
+        let unspents = self.get_wallet().list_unspent()?;
+        Ok(unspents
+            .iter()
+            .map(|u| LocalUtxo::from_utxo(u, self.network()))
+            .collect())
+    }
 }
 
 fn to_script_pubkey(address: &str) -> Result<Script, BdkError> {
@@ -337,26 +472,42 @@ enum RbfValue {
     Value(u32),
 }
 
+/// A transaction builder.
+/// After creating the TxBuilder, you set options on it until finally calling finish to consume the builder and generate the transaction.
+/// Each method on the TxBuilder returns an instance of a new TxBuilder with the option set/added.
 #[derive(Clone, Debug)]
 struct TxBuilder {
     recipients: Vec<(String, u64)>,
+    utxos: Vec<OutPoint>,
+    unspendable: HashSet<OutPoint>,
+    change_policy: ChangeSpendPolicy,
+    manually_selected_only: bool,
     fee_rate: Option<f32>,
+    fee_absolute: Option<u64>,
     drain_wallet: bool,
     drain_to: Option<String>,
     rbf: Option<RbfValue>,
+    data: Vec<u8>,
 }
 
 impl TxBuilder {
     fn new() -> Self {
         TxBuilder {
             recipients: Vec::new(),
+            utxos: Vec::new(),
+            unspendable: HashSet::new(),
+            change_policy: ChangeSpendPolicy::ChangeAllowed,
+            manually_selected_only: false,
             fee_rate: None,
+            fee_absolute: None,
             drain_wallet: false,
             drain_to: None,
             rbf: None,
+            data: Vec::new(),
         }
     }
 
+    /// Add a recipient to the internal list.
     fn add_recipient(&self, recipient: String, amount: u64) -> Arc<Self> {
         let mut recipients = self.recipients.to_vec();
         recipients.append(&mut vec![(recipient, amount)]);
@@ -366,6 +517,81 @@ impl TxBuilder {
         })
     }
 
+    fn set_recipients(&self, recipients: Vec<AddressAmount>) -> Arc<Self> {
+        let recipients = recipients
+            .iter()
+            .map(|address_amount| (address_amount.address.clone(), address_amount.amount))
+            .collect();
+        Arc::new(TxBuilder {
+            recipients,
+            ..self.clone()
+        })
+    }
+
+    /// Add a utxo to the internal list of unspendable utxos. It’s important to note that the "must-be-spent"
+    /// utxos added with [TxBuilder.addUtxo] have priority over this. See the Rust docs of the two linked methods for more details.
+    fn add_unspendable(&self, unspendable: OutPoint) -> Arc<Self> {
+        let mut unspendable_hash_set = self.unspendable.clone();
+        unspendable_hash_set.insert(unspendable);
+        Arc::new(TxBuilder {
+            unspendable: unspendable_hash_set,
+            ..self.clone()
+        })
+    }
+
+    /// Add an outpoint to the internal list of UTXOs that must be spent. These have priority over the "unspendable"
+    /// utxos, meaning that if a utxo is present both in the "utxos" and the "unspendable" list, it will be spent.
+    fn add_utxo(&self, outpoint: OutPoint) -> Arc<Self> {
+        self.add_utxos(vec![outpoint])
+    }
+
+    /// Add the list of outpoints to the internal list of UTXOs that must be spent. If an error occurs while adding
+    /// any of the UTXOs then none of them are added and the error is returned. These have priority over the "unspendable"
+    /// utxos, meaning that if a utxo is present both in the "utxos" and the "unspendable" list, it will be spent.
+    fn add_utxos(&self, mut outpoints: Vec<OutPoint>) -> Arc<Self> {
+        let mut utxos = self.utxos.to_vec();
+        utxos.append(&mut outpoints);
+        Arc::new(TxBuilder {
+            utxos,
+            ..self.clone()
+        })
+    }
+
+    /// Do not spend change outputs. This effectively adds all the change outputs to the "unspendable" list. See TxBuilder.unspendable.
+    fn do_not_spend_change(&self) -> Arc<Self> {
+        Arc::new(TxBuilder {
+            change_policy: ChangeSpendPolicy::ChangeForbidden,
+            ..self.clone()
+        })
+    }
+
+    /// Only spend utxos added by [add_utxo]. The wallet will not add additional utxos to the transaction even if they are
+    /// needed to make the transaction valid.
+    fn manually_selected_only(&self) -> Arc<Self> {
+        Arc::new(TxBuilder {
+            manually_selected_only: true,
+            ..self.clone()
+        })
+    }
+
+    /// Only spend change outputs. This effectively adds all the non-change outputs to the "unspendable" list. See TxBuilder.unspendable.
+    fn only_spend_change(&self) -> Arc<Self> {
+        Arc::new(TxBuilder {
+            change_policy: ChangeSpendPolicy::OnlyChange,
+            ..self.clone()
+        })
+    }
+
+    /// Replace the internal list of unspendable utxos with a new list. It’s important to note that the "must-be-spent" utxos added with
+    /// TxBuilder.addUtxo have priority over these. See the Rust docs of the two linked methods for more details.
+    fn unspendable(&self, unspendable: Vec<OutPoint>) -> Arc<Self> {
+        Arc::new(TxBuilder {
+            unspendable: unspendable.into_iter().collect(),
+            ..self.clone()
+        })
+    }
+
+    /// Set a custom fee rate.
     fn fee_rate(&self, sat_per_vb: f32) -> Arc<Self> {
         Arc::new(TxBuilder {
             fee_rate: Some(sat_per_vb),
@@ -373,6 +599,15 @@ impl TxBuilder {
         })
     }
 
+    /// Set an absolute fee.
+    fn fee_absolute(&self, fee_amount: u64) -> Arc<Self> {
+        Arc::new(TxBuilder {
+            fee_absolute: Some(fee_amount),
+            ..self.clone()
+        })
+    }
+
+    /// Spend all the available inputs. This respects filters like TxBuilder.unspendable and the change policy.
     fn drain_wallet(&self) -> Arc<Self> {
         Arc::new(TxBuilder {
             drain_wallet: true,
@@ -380,6 +615,14 @@ impl TxBuilder {
         })
     }
 
+    /// Sets the address to drain excess coins to. Usually, when there are excess coins they are sent to a change address
+    /// generated by the wallet. This option replaces the usual change address with an arbitrary ScriptPubKey of your choosing.
+    /// Just as with a change output, if the drain output is not needed (the excess coins are too small) it will not be included
+    /// in the resulting transaction. The only difference is that it is valid to use drain_to without setting any ordinary recipients
+    /// with add_recipient (but it is perfectly fine to add recipients as well). If you choose not to set any recipients, you should
+    /// either provide the utxos that the transaction should spend via add_utxos, or set drain_wallet to spend all of them.
+    /// When bumping the fees of a transaction made with this option, you probably want to use BumpFeeTxBuilder.allow_shrinking
+    /// to allow this output to be reduced to pay for the extra fees.
     fn drain_to(&self, address: String) -> Arc<Self> {
         Arc::new(TxBuilder {
             drain_to: Some(address),
@@ -387,6 +630,7 @@ impl TxBuilder {
         })
     }
 
+    /// Enable signaling RBF. This will use the default `nsequence` value of `0xFFFFFFFD`.
     fn enable_rbf(&self) -> Arc<Self> {
         Arc::new(TxBuilder {
             rbf: Some(RbfValue::Default),
@@ -394,6 +638,9 @@ impl TxBuilder {
         })
     }
 
+    /// Enable signaling RBF with a specific nSequence value. This can cause conflicts if the wallet's descriptors contain an
+    /// "older" (OP_CSV) operator and the given `nsequence` is lower than the CSV value. If the `nsequence` is higher than `0xFFFFFFFD`
+    /// an error will be thrown, since it would not be a valid nSequence to signal RBF.
     fn enable_rbf_with_sequence(&self, nsequence: u32) -> Arc<Self> {
         Arc::new(TxBuilder {
             rbf: Some(RbfValue::Value(nsequence)),
@@ -401,15 +648,41 @@ impl TxBuilder {
         })
     }
 
+    /// Add data as an output using OP_RETURN.
+    fn add_data(&self, data: Vec<u8>) -> Arc<Self> {
+        Arc::new(TxBuilder {
+            data,
+            ..self.clone()
+        })
+    }
+
+    /// Finish building the transaction. Returns the BIP174 PSBT.
     fn finish(&self, wallet: &Wallet) -> Result<Arc<PartiallySignedBitcoinTransaction>, Error> {
         let wallet = wallet.get_wallet();
         let mut tx_builder = wallet.build_tx();
         for (address, amount) in &self.recipients {
             tx_builder.add_recipient(to_script_pubkey(address)?, *amount);
         }
+        tx_builder.change_policy(self.change_policy);
+        if !self.utxos.is_empty() {
+            let bdk_utxos: Vec<BdkOutPoint> = self.utxos.iter().map(BdkOutPoint::from).collect();
+            let utxos: &[BdkOutPoint] = &bdk_utxos;
+            tx_builder.add_utxos(utxos)?;
+        }
+        if !self.unspendable.is_empty() {
+            let bdk_unspendable: Vec<BdkOutPoint> =
+                self.unspendable.iter().map(BdkOutPoint::from).collect();
+            tx_builder.unspendable(bdk_unspendable);
+        }
+        if self.manually_selected_only {
+            tx_builder.manually_selected_only();
+        }
         if let Some(sat_per_vb) = self.fee_rate {
             tx_builder.fee_rate(FeeRate::from_sat_per_vb(sat_per_vb));
         }
+        if let Some(fee_amount) = self.fee_absolute {
+            tx_builder.fee_absolute(fee_amount);
+        }
         if self.drain_wallet {
             tx_builder.drain_wallet();
         }
@@ -426,6 +699,10 @@ impl TxBuilder {
                 }
             }
         }
+        if !&self.data.is_empty() {
+            tx_builder.add_data(self.data.as_slice());
+        }
+
         tx_builder
             .finish()
             .map(|(psbt, _)| PartiallySignedBitcoinTransaction {
@@ -435,6 +712,7 @@ impl TxBuilder {
     }
 }
 
+/// The BumpFeeTxBuilder is used to bump the fee on a transaction that has been broadcast and has its RBF flag set to true.
 #[derive(Clone)]
 struct BumpFeeTxBuilder {
     txid: String,
@@ -453,6 +731,11 @@ impl BumpFeeTxBuilder {
         }
     }
 
+    /// Explicitly tells the wallet that it is allowed to reduce the amount of the output matching this script_pubkey
+    /// in order to bump the transaction fee. Without specifying this the wallet will attempt to find a change output to
+    /// shrink instead. Note that the output may shrink to below the dust limit and therefore be removed. If it is preserved
+    /// then it is currently not guaranteed to be in the same position as it was originally. Returns an error if script_pubkey
+    /// can’t be found among the recipients of the transaction we are bumping.
     fn allow_shrinking(&self, address: String) -> Arc<Self> {
         Arc::new(Self {
             allow_shrinking: Some(address),
@@ -460,6 +743,7 @@ impl BumpFeeTxBuilder {
         })
     }
 
+    /// Enable signaling RBF. This will use the default `nsequence` value of `0xFFFFFFFD`.
     fn enable_rbf(&self) -> Arc<Self> {
         Arc::new(Self {
             rbf: Some(RbfValue::Default),
@@ -467,6 +751,9 @@ impl BumpFeeTxBuilder {
         })
     }
 
+    /// Enable signaling RBF with a specific nSequence value. This can cause conflicts if the wallet's descriptors contain an
+    /// "older" (OP_CSV) operator and the given `nsequence` is lower than the CSV value. If the `nsequence` is higher than `0xFFFFFFFD`
+    /// an error will be thrown, since it would not be a valid nSequence to signal RBF.
     fn enable_rbf_with_sequence(&self, nsequence: u32) -> Arc<Self> {
         Arc::new(Self {
             rbf: Some(RbfValue::Value(nsequence)),
@@ -474,6 +761,7 @@ impl BumpFeeTxBuilder {
         })
     }
 
+    /// Finish building the transaction. Returns the BIP174 PSBT.
     fn finish(&self, wallet: &Wallet) -> Result<Arc<PartiallySignedBitcoinTransaction>, Error> {
         let wallet = wallet.get_wallet();
         let txid = Txid::from_str(self.txid.as_str())?;
@@ -504,6 +792,173 @@ impl BumpFeeTxBuilder {
     }
 }
 
+fn generate_mnemonic(word_count: WordCount) -> Result<String, BdkError> {
+    let mnemonic: GeneratedKey<_, BareCtx> =
+        Mnemonic::generate((word_count, Language::English)).unwrap();
+    Ok(mnemonic.to_string())
+}
+
+struct DerivationPath {
+    derivation_path_mutex: Mutex<BdkDerivationPath>,
+}
+
+impl DerivationPath {
+    fn new(path: String) -> Result<Self, BdkError> {
+        BdkDerivationPath::from_str(&path)
+            .map(|x| DerivationPath {
+                derivation_path_mutex: Mutex::new(x),
+            })
+            .map_err(|e| BdkError::Generic(e.to_string()))
+    }
+}
+
+struct DescriptorSecretKey {
+    descriptor_secret_key_mutex: Mutex<BdkDescriptorSecretKey>,
+}
+
+impl DescriptorSecretKey {
+    fn new(network: Network, mnemonic: String, password: Option<String>) -> Result<Self, BdkError> {
+        let mnemonic = Mnemonic::parse_in(Language::English, mnemonic)
+            .map_err(|e| BdkError::Generic(e.to_string()))?;
+        let xkey: ExtendedKey = (mnemonic, password).into_extended_key()?;
+        let descriptor_secret_key = BdkDescriptorSecretKey::XPrv(DescriptorXKey {
+            origin: None,
+            xkey: xkey.into_xprv(network).unwrap(),
+            derivation_path: BdkDerivationPath::master(),
+            wildcard: bdk::descriptor::Wildcard::Unhardened,
+        });
+        Ok(Self {
+            descriptor_secret_key_mutex: Mutex::new(descriptor_secret_key),
+        })
+    }
+
+    fn derive(&self, path: Arc<DerivationPath>) -> Result<Arc<Self>, BdkError> {
+        let secp = Secp256k1::new();
+        let descriptor_secret_key = self.descriptor_secret_key_mutex.lock().unwrap();
+        let path = path.derivation_path_mutex.lock().unwrap().deref().clone();
+        match descriptor_secret_key.deref() {
+            BdkDescriptorSecretKey::XPrv(descriptor_x_key) => {
+                let derived_xprv = descriptor_x_key.xkey.derive_priv(&secp, &path)?;
+                let key_source = match descriptor_x_key.origin.clone() {
+                    Some((fingerprint, origin_path)) => (fingerprint, origin_path.extend(path)),
+                    None => (descriptor_x_key.xkey.fingerprint(&secp), path),
+                };
+                let derived_descriptor_secret_key = BdkDescriptorSecretKey::XPrv(DescriptorXKey {
+                    origin: Some(key_source),
+                    xkey: derived_xprv,
+                    derivation_path: BdkDerivationPath::default(),
+                    wildcard: descriptor_x_key.wildcard,
+                });
+                Ok(Arc::new(Self {
+                    descriptor_secret_key_mutex: Mutex::new(derived_descriptor_secret_key),
+                }))
+            }
+            BdkDescriptorSecretKey::SinglePriv(_) => {
+                unreachable!()
+            }
+        }
+    }
+
+    fn extend(&self, path: Arc<DerivationPath>) -> Arc<Self> {
+        let descriptor_secret_key = self.descriptor_secret_key_mutex.lock().unwrap();
+        let path = path.derivation_path_mutex.lock().unwrap().deref().clone();
+        match descriptor_secret_key.deref() {
+            BdkDescriptorSecretKey::XPrv(descriptor_x_key) => {
+                let extended_path = descriptor_x_key.derivation_path.extend(path);
+                let extended_descriptor_secret_key = BdkDescriptorSecretKey::XPrv(DescriptorXKey {
+                    origin: descriptor_x_key.origin.clone(),
+                    xkey: descriptor_x_key.xkey,
+                    derivation_path: extended_path,
+                    wildcard: descriptor_x_key.wildcard,
+                });
+                Arc::new(Self {
+                    descriptor_secret_key_mutex: Mutex::new(extended_descriptor_secret_key),
+                })
+            }
+            BdkDescriptorSecretKey::SinglePriv(_) => {
+                unreachable!()
+            }
+        }
+    }
+
+    fn as_public(&self) -> Arc<DescriptorPublicKey> {
+        let secp = Secp256k1::new();
+        let descriptor_public_key = self
+            .descriptor_secret_key_mutex
+            .lock()
+            .unwrap()
+            .as_public(&secp)
+            .unwrap();
+        Arc::new(DescriptorPublicKey {
+            descriptor_public_key_mutex: Mutex::new(descriptor_public_key),
+        })
+    }
+
+    fn as_string(&self) -> String {
+        self.descriptor_secret_key_mutex.lock().unwrap().to_string()
+    }
+}
+
+struct DescriptorPublicKey {
+    descriptor_public_key_mutex: Mutex<BdkDescriptorPublicKey>,
+}
+
+impl DescriptorPublicKey {
+    fn derive(&self, path: Arc<DerivationPath>) -> Result<Arc<Self>, BdkError> {
+        let secp = Secp256k1::new();
+        let descriptor_public_key = self.descriptor_public_key_mutex.lock().unwrap();
+        let path = path.derivation_path_mutex.lock().unwrap().deref().clone();
+
+        match descriptor_public_key.deref() {
+            BdkDescriptorPublicKey::XPub(descriptor_x_key) => {
+                let derived_xpub = descriptor_x_key.xkey.derive_pub(&secp, &path)?;
+                let key_source = match descriptor_x_key.origin.clone() {
+                    Some((fingerprint, origin_path)) => (fingerprint, origin_path.extend(path)),
+                    None => (descriptor_x_key.xkey.fingerprint(), path),
+                };
+                let derived_descriptor_public_key = BdkDescriptorPublicKey::XPub(DescriptorXKey {
+                    origin: Some(key_source),
+                    xkey: derived_xpub,
+                    derivation_path: BdkDerivationPath::default(),
+                    wildcard: descriptor_x_key.wildcard,
+                });
+                Ok(Arc::new(Self {
+                    descriptor_public_key_mutex: Mutex::new(derived_descriptor_public_key),
+                }))
+            }
+            BdkDescriptorPublicKey::SinglePub(_) => {
+                unreachable!()
+            }
+        }
+    }
+
+    fn extend(&self, path: Arc<DerivationPath>) -> Arc<Self> {
+        let descriptor_public_key = self.descriptor_public_key_mutex.lock().unwrap();
+        let path = path.derivation_path_mutex.lock().unwrap().deref().clone();
+        match descriptor_public_key.deref() {
+            BdkDescriptorPublicKey::XPub(descriptor_x_key) => {
+                let extended_path = descriptor_x_key.derivation_path.extend(path);
+                let extended_descriptor_public_key = BdkDescriptorPublicKey::XPub(DescriptorXKey {
+                    origin: descriptor_x_key.origin.clone(),
+                    xkey: descriptor_x_key.xkey,
+                    derivation_path: extended_path,
+                    wildcard: descriptor_x_key.wildcard,
+                });
+                Arc::new(Self {
+                    descriptor_public_key_mutex: Mutex::new(extended_descriptor_public_key),
+                })
+            }
+            BdkDescriptorPublicKey::SinglePub(_) => {
+                unreachable!()
+            }
+        }
+    }
+
+    fn as_string(&self) -> String {
+        self.descriptor_public_key_mutex.lock().unwrap().to_string()
+    }
+}
+
 uniffi::deps::static_assertions::assert_impl_all!(Wallet: Sync, Send);
 
 // The goal of these tests to to ensure `bdk-ffi` intermediate code correctly calls `bdk` APIs.
@@ -511,7 +966,7 @@ uniffi::deps::static_assertions::assert_impl_all!(Wallet: Sync, Send);
 // crate.
 #[cfg(test)]
 mod test {
-    use crate::{TxBuilder, Wallet};
+    use crate::*;
     use bdk::bitcoin::Address;
     use bdk::bitcoin::Network::Testnet;
     use bdk::wallet::get_funded_wallet;
@@ -530,7 +985,7 @@ mod test {
             .drain_wallet()
             .drain_to(drain_to_address.clone());
         //dbg!(&tx_builder);
-        assert_eq!(tx_builder.drain_wallet, true);
+        assert!(tx_builder.drain_wallet);
         assert_eq!(tx_builder.drain_to, Some(drain_to_address));
 
         let psbt = tx_builder.finish(&test_wallet).unwrap();
@@ -549,7 +1004,7 @@ mod test {
             .get(0)
             .unwrap()
             .value;
-        assert_eq!(input_value, 50_000 as u64);
+        assert_eq!(input_value, 50_000_u64);
 
         // confirm one output to correct address with all sats - fee
         assert_eq!(psbt.outputs.len(), 1);
@@ -569,6 +1024,98 @@ mod test {
             Address::from_str("tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt").unwrap()
         );
         let output_value = psbt.unsigned_tx.output.get(0).cloned().unwrap().value;
-        assert_eq!(output_value, 49_890 as u64); // input - fee
+        assert_eq!(output_value, 49_890_u64); // input - fee
+    }
+
+    fn get_descriptor_secret_key() -> DescriptorSecretKey {
+        let mnemonic =
+        "chaos fabric time speed sponsor all flat solution wisdom trophy crack object robot pave observe combine where aware bench orient secret primary cable detect".to_string();
+        DescriptorSecretKey::new(Network::Testnet, mnemonic, None).unwrap()
+    }
+
+    fn derive_dsk(
+        key: &DescriptorSecretKey,
+        path: &str,
+    ) -> Result<Arc<DescriptorSecretKey>, BdkError> {
+        let path = Arc::new(DerivationPath::new(path.to_string()).unwrap());
+        key.derive(path)
+    }
+
+    fn extend_dsk(key: &DescriptorSecretKey, path: &str) -> Arc<DescriptorSecretKey> {
+        let path = Arc::new(DerivationPath::new(path.to_string()).unwrap());
+        key.extend(path)
+    }
+
+    fn derive_dpk(
+        key: &DescriptorPublicKey,
+        path: &str,
+    ) -> Result<Arc<DescriptorPublicKey>, BdkError> {
+        let path = Arc::new(DerivationPath::new(path.to_string()).unwrap());
+        key.derive(path)
+    }
+
+    fn extend_dpk(key: &DescriptorPublicKey, path: &str) -> Arc<DescriptorPublicKey> {
+        let path = Arc::new(DerivationPath::new(path.to_string()).unwrap());
+        key.extend(path)
+    }
+
+    #[test]
+    fn test_generate_descriptor_secret_key() {
+        let master_dsk = get_descriptor_secret_key();
+        assert_eq!(master_dsk.as_string(), "tprv8ZgxMBicQKsPdWuqM1t1CDRvQtQuBPyfL6GbhQwtxDKgUAVPbxmj71pRA8raTqLrec5LyTs5TqCxdABcZr77bt2KyWA5bizJHnC4g4ysm4h/*");
+        assert_eq!(master_dsk.as_public().as_string(), "tpubD6NzVbkrYhZ4WywdEfYbbd62yuvqLjAZuPsNyvzCNV85JekAEMbKHWSHLF9h3j45SxewXDcLv328B1SEZrxg4iwGfmdt1pDFjZiTkGiFqGa/*");
+    }
+
+    #[test]
+    fn test_derive_self() {
+        let master_dsk = get_descriptor_secret_key();
+        let derived_dsk: &DescriptorSecretKey = &derive_dsk(&master_dsk, "m").unwrap();
+        assert_eq!(derived_dsk.as_string(), "[d1d04177]tprv8ZgxMBicQKsPdWuqM1t1CDRvQtQuBPyfL6GbhQwtxDKgUAVPbxmj71pRA8raTqLrec5LyTs5TqCxdABcZr77bt2KyWA5bizJHnC4g4ysm4h/*");
+
+        let master_dpk: &DescriptorPublicKey = &master_dsk.as_public();
+        let derived_dpk: &DescriptorPublicKey = &derive_dpk(master_dpk, "m").unwrap();
+        assert_eq!(derived_dpk.as_string(), "[d1d04177]tpubD6NzVbkrYhZ4WywdEfYbbd62yuvqLjAZuPsNyvzCNV85JekAEMbKHWSHLF9h3j45SxewXDcLv328B1SEZrxg4iwGfmdt1pDFjZiTkGiFqGa/*");
+    }
+
+    #[test]
+    fn test_derive_descriptors_keys() {
+        let master_dsk = get_descriptor_secret_key();
+        let derived_dsk: &DescriptorSecretKey = &derive_dsk(&master_dsk, "m/0").unwrap();
+        assert_eq!(derived_dsk.as_string(), "[d1d04177/0]tprv8d7Y4JLmD25jkKbyDZXcdoPHu1YtMHuH21qeN7mFpjfumtSU7eZimFYUCSa3MYzkEYfSNRBV34GEr2QXwZCMYRZ7M1g6PUtiLhbJhBZEGYJ/*");
+
+        let master_dpk: &DescriptorPublicKey = &master_dsk.as_public();
+        let derived_dpk: &DescriptorPublicKey = &derive_dpk(master_dpk, "m/0").unwrap();
+        assert_eq!(derived_dpk.as_string(), "[d1d04177/0]tpubD9oaCiP1MPmQdndm7DCD3D3QU34pWd6BbKSRedoZF1UJcNhEk3PJwkALNYkhxeTKL29oGNR7psqvT1KZydCGqUDEKXN6dVQJY2R8ooLPy8m/*");
+    }
+
+    #[test]
+    fn test_extend_descriptor_keys() {
+        let master_dsk = get_descriptor_secret_key();
+        let extended_dsk: &DescriptorSecretKey = &extend_dsk(&master_dsk, "m/0");
+        assert_eq!(extended_dsk.as_string(), "tprv8ZgxMBicQKsPdWuqM1t1CDRvQtQuBPyfL6GbhQwtxDKgUAVPbxmj71pRA8raTqLrec5LyTs5TqCxdABcZr77bt2KyWA5bizJHnC4g4ysm4h/0/*");
+
+        let master_dpk: &DescriptorPublicKey = &master_dsk.as_public();
+        let extended_dpk: &DescriptorPublicKey = &extend_dpk(master_dpk, "m/0");
+        assert_eq!(extended_dpk.as_string(), "tpubD6NzVbkrYhZ4WywdEfYbbd62yuvqLjAZuPsNyvzCNV85JekAEMbKHWSHLF9h3j45SxewXDcLv328B1SEZrxg4iwGfmdt1pDFjZiTkGiFqGa/0/*");
+    }
+
+    #[test]
+    fn test_derive_and_extend_descriptor_secret_key() {
+        let master_dsk = get_descriptor_secret_key();
+
+        // derive DescriptorSecretKey with path "m/0" from master
+        let derived_dsk: &DescriptorSecretKey = &derive_dsk(&master_dsk, "m/0").unwrap();
+        assert_eq!(derived_dsk.as_string(), "[d1d04177/0]tprv8d7Y4JLmD25jkKbyDZXcdoPHu1YtMHuH21qeN7mFpjfumtSU7eZimFYUCSa3MYzkEYfSNRBV34GEr2QXwZCMYRZ7M1g6PUtiLhbJhBZEGYJ/*");
+
+        // extend derived_dsk with path "m/0"
+        let extended_dsk: &DescriptorSecretKey = &extend_dsk(derived_dsk, "m/0");
+        assert_eq!(extended_dsk.as_string(), "[d1d04177/0]tprv8d7Y4JLmD25jkKbyDZXcdoPHu1YtMHuH21qeN7mFpjfumtSU7eZimFYUCSa3MYzkEYfSNRBV34GEr2QXwZCMYRZ7M1g6PUtiLhbJhBZEGYJ/0/*");
+    }
+
+    #[test]
+    fn test_derive_hardened_path_using_public() {
+        let master_dpk = get_descriptor_secret_key().as_public();
+        let derived_dpk = &derive_dpk(&master_dpk, "m/84h/1h/0h");
+        assert!(derived_dpk.is_err());
     }
 }