Move kotlin API docs to more specific subdirectory

api-docs/kotlin/Module1.md

@@ -0,0 +1,4 @@
+# Module bdk-android
+The [bitcoindevkit](https://bitcoindevkit.org/) language bindings library for Android.
+
+# Package org.bitcoindevkit

api-docs/kotlin/Module2.md

@@ -0,0 +1,4 @@
+# Module bdk-jvm
+The [bitcoindevkit](https://bitcoindevkit.org/) language bindings library for Kotlin and Java on the JVM.
+
+# Package org.bitcoindevkit

api-docs/kotlin/build.gradle.kts

@@ -0,0 +1,46 @@
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+plugins {
+    kotlin("jvm") version "1.7.10"
+
+    // API docs
+    id("org.jetbrains.dokka") version "1.7.10"
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    testImplementation(kotlin("test"))
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+
+tasks.withType<KotlinCompile> {
+    kotlinOptions.jvmTarget = "1.8"
+}
+
+// tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>().configureEach {
+//     dokkaSourceSets {
+//         named("main") {
+//             moduleName.set("bdk-android")
+//             moduleVersion.set("0.11.0")
+//             includes.from("Module1.md")
+//             samples.from("src/test/kotlin/org/bitcoindevkit/Samples.kt")
+//         }
+//     }
+// }
+
+tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>().configureEach {
+    dokkaSourceSets {
+        named("main") {
+            moduleName.set("bdk-jvm")
+            moduleVersion.set("0.11.0")
+            includes.from("Module2.md")
+            samples.from("src/test/kotlin/org/bitcoindevkit/Samples.kt")
+        }
+    }
+}

api-docs/kotlin/deploy.sh

@@ -0,0 +1,8 @@
+./gradlew dokkaHtml
+cd build/dokka/html
+git init .
+git add .
+git switch --create gh-pages
+git commit -m "Deploy"
+git remote add origin git@github.com:bitcoindevkit/bdk-kotlin.git
+git push --set-upstream origin gh-pages --force

api-docs/kotlin/gradle.properties

@@ -0,0 +1 @@
+kotlin.code.style=official

api-docs/kotlin/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

api-docs/kotlin/gradlew

@@ -0,0 +1,234 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/master/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
+
+APP_NAME="Gradle"
+APP_BASE_NAME=${0##*/}
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+# Collect all arguments for the java command;
+#   * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of
+#     shell script including quotes and variable substitutions, so put them in
+#     double quotes to make sure that they get re-expanded; and
+#   * put everything else in single quotes, so that it's not re-expanded.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        org.gradle.wrapper.GradleWrapperMain \
+        "$@"
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"

api-docs/kotlin/gradlew.bat

@@ -0,0 +1,89 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+
+@if "%DEBUG%" == "" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%" == "" set DIRNAME=.
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if "%ERRORLEVEL%" == "0" goto execute
+
+echo.
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo.
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if "%ERRORLEVEL%"=="0" goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+if  not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
+exit /b 1
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega

api-docs/kotlin/settings.gradle.kts

@@ -0,0 +1 @@
+rootProject.name = "BDK Android and BDK JVM API Docs"

api-docs/kotlin/src/main/kotlin/org/bitcoindevkit/bdk.kt

@@ -0,0 +1,582 @@
+package org.bitcoindevkit
+
+/**
+ * The cryptocurrency to act on.
+ *
+ * @sample org.bitcoindevkit.networkSample
+ */
+enum class Network {
+    /** Bitcoin's mainnet. */
+    BITCOIN,
+
+    /** Bitcoin’s testnet. */
+    TESTNET,
+
+    /** Bitcoin’s signet. */
+    SIGNET,
+
+    /** Bitcoin’s regtest. */
+    REGTEST,
+}
+
+/**
+ * A derived address and the index it was found at.
+ *
+ * @property index Child index of this address.
+ * @property address Address.
+ *
+ * @sample org.bitcoindevkit.addressInfoSample
+ */
+data class AddressInfo (
+    var index: UInt,
+    var address: String
+)
+
+/**
+ * The address index selection strategy to use to derive an address from the wallet’s external descriptor.
+ *
+ * If you’re unsure which one to use, use `AddressIndex.NEW`.
+ *
+ * @sample org.bitcoindevkit.addressIndexSample
+ */
+enum class 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.
+     */
+    LAST_UNUSED,
+}
+
+/**
+ * Balance differentiated in various categories.
+ *
+ * @property immature All coinbase outputs not yet matured.
+ * @property trustedPending Unconfirmed UTXOs generated by a wallet tx.
+ * @property untrustedPending Unconfirmed UTXOs received from an external wallet.
+ * @property confirmed Confirmed and immediately spendable balance.
+ * @property spendable The sum of trustedPending and confirmed coins.
+ * @property total The whole balance visible to the wallet.
+ *
+ * @sample org.bitcoindevkit.balanceSample
+ */
+data class Balance (
+    var immature: ULong,
+    var trustedPending: ULong,
+    var untrustedPending: ULong,
+    var confirmed: ULong,
+    var spendable: ULong,
+    var total: ULong
+)
+
+/**
+ * Type that can contain any of the database configurations defined by the library.
+ *
+ * @sample org.bitcoindevkit.memoryDatabaseConfigSample
+ * @sample org.bitcoindevkit.sqliteDatabaseConfigSample
+ */
+sealed class DatabaseConfig {
+    /** Configuration for an in-memory database. */
+    object Memory : DatabaseConfig()
+
+    /** Configuration for a Sled database. */
+    data class Sled(val config: SledDbConfiguration) : DatabaseConfig()
+
+    /** Configuration for a SQLite database. */
+    data class Sqlite(val config: SqliteDbConfiguration) : DatabaseConfig()
+}
+
+/**
+ * Configuration type for a SQLite database.
+ *
+ * @property path Main directory of the DB.
+ */
+data class SqliteDbConfiguration(
+    var path: String,
+)
+
+/**
+ * Configuration type for a SledDB database.
+ *
+ * @property path Main directory of the DB.
+ * @property treeName Name of the database tree, a separated namespace for the data.
+ */
+data class SledDbConfiguration(
+    var path: String,
+    var treeName: String,
+)
+
+/**
+ * Configuration for an Electrum blockchain.
+ *
+ * @property url 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`.
+ * @property socks5 URL of the socks5 proxy server or a Tor service.
+ * @property retry Request retry count.
+ * @property timeout Request timeout (seconds).
+ * @property stopGap Stop searching addresses for transactions after finding an unused gap of this length.
+ *
+ * @sample org.bitcoindevkit.electrumBlockchainConfigSample
+ */
+data class ElectrumConfig (
+    var url: String,
+    var socks5: String?,
+    var retry: UByte,
+    var timeout: UByte?,
+    var stopGap: ULong
+)
+
+/**
+ * Configuration for an Esplora blockchain.
+ *
+ * @property baseUrl Base URL of the esplora service, e.g. `https://blockstream.info/api/`.
+ * @property proxy Optional URL of the proxy to use to make requests to the Esplora server.
+ * @property concurrency Number of parallel requests sent to the esplora service (default: 4).
+ * @property stopGap Stop searching addresses for transactions after finding an unused gap of this length.
+ * @property timeout Socket timeout.
+ */
+data class EsploraConfig (
+    var baseUrl: String,
+    var proxy: String?,
+    var concurrency: UByte?,
+    var stopGap: ULong,
+    var timeout: ULong?
+)
+
+/**
+ * Type that can contain any of the blockchain configurations defined by the library.
+ *
+ * @sample org.bitcoindevkit.electrumBlockchainConfigSample
+ */
+sealed class BlockchainConfig {
+    /** Electrum client. */
+    data class Electrum(val config: ElectrumConfig) : BlockchainConfig()
+
+    /** Esplora client. */
+    data class Esplora(val config: EsploraConfig) : BlockchainConfig()
+}
+
+/**
+ * A wallet transaction.
+ *
+ * @property fee Fee value (sats) if available. 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.
+ * @property received Received value (sats) Sum of owned outputs of this transaction.
+ * @property sent Sent value (sats) Sum of owned inputs of this transaction.
+ * @property txid Transaction id.
+ * @property confirmationTime If the transaction is confirmed, [BlockTime] contains height and timestamp of the block containing the transaction. This property is null for unconfirmed transactions.
+ */
+data class TransactionDetails (
+    var fee: ULong?,
+    var received: ULong,
+    var sent: ULong,
+    var txid: String,
+    var confirmationTime: BlockTime?
+)
+
+/**
+ * A blockchain backend.
+ *
+ * @constructor Create the new blockchain client.
+ *
+ * @param config The blockchain configuration required.
+ *
+ * @sample org.bitcoindevkit.blockchainSample
+ */
+class Blockchain(
+    config: BlockchainConfig
+) {
+    /** Broadcast a transaction. */
+    fun broadcast(psbt: PartiallySignedBitcoinTransaction): String {}
+
+    /** Get the current height of the blockchain. */
+    fun getHeight(): UInt {}
+
+    /** Get the block hash of a given block. */
+    fun getBlockHash(height: UInt): String {}
+}
+
+/**
+ * A partially signed bitcoin transaction.
+ *
+ * @constructor Build a new Partially Signed Bitcoin Transaction.
+ *
+ * @param psbtBase64 The PSBT in base64 format.
+ */
+class PartiallySignedBitcoinTransaction(psbtBase64: String) {
+    /** Return the PSBT in string format, using a base64 encoding. */
+    fun serialize(): String {}
+
+    /** Get the txid of the PSBT. */
+    fun txid(): String {}
+
+    /** Return the transaction as bytes. */
+    fun `extractTx`(): List<UByte>
+
+    /**
+     * Combines this PartiallySignedTransaction with another PSBT as described by BIP 174.
+     * In accordance with BIP 174 this function is commutative i.e., `A.combine(B) == B.combine(A)`
+     */
+    fun combine(other: PartiallySignedBitcoinTransaction): PartiallySignedBitcoinTransaction
+}
+
+/**
+ * A reference to a transaction output.
+ *
+ * @property txid The referenced transaction’s txid.
+ * @property vout The index of the referenced output in its transaction’s vout.
+ */
+data class OutPoint (
+    var txid: String,
+    var vout: UInt
+)
+
+/**
+ * A transaction output, which defines new coins to be created from old ones.
+ *
+ * @property value The value of the output, in satoshis.
+ * @property address The address of the output.
+ */
+data class TxOut (
+    var value: ULong,
+    var address: String
+)
+
+/**
+ * An unspent output owned by a [Wallet].
+ *
+ * @property outpoint Reference to a transaction output.
+ * @property txout Transaction output.
+ * @property keychain Type of keychain.
+ * @property isSpent Whether this UTXO is spent or not.
+ */
+data class LocalUtxo (
+    var outpoint: OutPoint,
+    var txout: TxOut,
+    var keychain: KeychainKind,
+    var isSpent: Boolean
+)
+
+/**
+ * Types of keychains.
+ */
+enum class KeychainKind {
+    /** External. */
+    EXTERNAL,
+
+    /** Internal, usually used for change outputs. */
+    INTERNAL,
+}
+
+/**
+ * Block height and timestamp of a block.
+ *
+ * @property height Confirmation block height.
+ * @property timestamp Confirmation block timestamp.
+ */
+data class BlockTime (
+    var height: UInt,
+    var timestamp: ULong,
+)
+
+/**
+ * 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.
+ *
+ * @constructor Create a BDK wallet.
+ *
+ * @param descriptor The main (or "external") descriptor.
+ * @param changeDescriptor The change (or "internal") descriptor.
+ * @param network The network to act on.
+ * @param databaseConfig The database configuration.
+ *
+ * @sample org.bitcoindevkit.walletSample
+ */
+class Wallet(
+    descriptor: String,
+    changeDescriptor: String,
+    network: Network,
+    databaseConfig: DatabaseConfig,
+) {
+    /**
+     * 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].
+     */
+    fun getAddress(addressIndex: AddressIndex): AddressInfo {}
+
+    /** 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. */
+    fun getBalance(): ULong {}
+
+    /** Sign a transaction with all the wallet’s signers. */
+    fun sign(psbt: PartiallySignedBitcoinTransaction): Boolean {}
+
+    /** 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. */
+    fun listTransactions(): List<TransactionDetails> {}
+
+    /** Get the Bitcoin network the wallet is using. */
+    fun network(): Network {}
+
+    /** Sync the internal database with the blockchain. */
+    fun sync(blockchain: Blockchain, progress: Progress?) {}
+
+    /** 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. */
+    fun listUnspent(): List<LocalUtxo> {}
+}
+
+/**
+ * Class that logs at level INFO every update received (if any).
+ */
+class Progress {
+    /** 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. */
+    fun update(progress: Float, message: String?) {}
+}
+
+/**
+ * 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.
+ */
+class TxBuilder() {
+    /** Add data as an output using OP_RETURN. */
+    fun addData(data: List<UByte>): TxBuilder {}
+
+    /** Add a recipient to the internal list. */
+    fun addRecipient(script: Script, amount: ULong): TxBuilder {}
+
+    /** Set the list of recipients by providing a list of [AddressAmount]. */
+    fun setRecipients(recipients: List<ScriptAmount>): TxBuilder {}
+
+    /** 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. */
+    fun addUnspendable(unspendable: OutPoint): TxBuilder {}
+
+    /** 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. */
+    fun addUtxo(outpoint: OutPoint): TxBuilder {}
+
+    /**
+     * 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.
+     */
+    fun addUtxos(outpoints: List<OutPoint>): TxBuilder {}
+
+    /** Do not spend change outputs. This effectively adds all the change outputs to the "unspendable" list. See [TxBuilder.unspendable]. */
+    fun doNotSpendChange(): TxBuilder {}
+
+    /** 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. */
+    fun manuallySelectedOnly(): TxBuilder {}
+
+    /** Only spend change outputs. This effectively adds all the non-change outputs to the "unspendable" list. See [TxBuilder.unspendable]. */
+    fun onlySpendChange(): TxBuilder {}
+
+    /**
+     * 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.
+     */
+    fun unspendable(unspendable: List<OutPoint>): TxBuilder {}
+
+    /** Set a custom fee rate. */
+    fun feeRate(satPerVbyte: Float): TxBuilder {}
+
+    /** Set an absolute fee. */
+    fun feeAbsolute(feeAmount: ULong): TxBuilder {}
+
+    /** Spend all the available inputs. This respects filters like [TxBuilder.unspendable] and the change policy. */
+    fun drainWallet(): 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 [drainTo] without setting any ordinary recipients
+     * with [addRecipient] (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 [addUtxos], or set
+     * [drainWallet] to spend all of them. When bumping the fees of a transaction made with this option,
+     * you probably want to use [BumpFeeTxBuilder.allowShrinking] to allow this output to be reduced to pay for the extra fees.
+     */
+    fun drainTo(address: String): TxBuilder {}
+
+    /** Enable signaling RBF. This will use the default `nsequence` value of `0xFFFFFFFD`. */
+    fun enableRbf(): 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.
+     */
+    fun enableRbfWithSequence(nsequence: UInt): TxBuilder {}
+
+    /** Finish building the transaction. Returns a [TxBuilderResult]. */
+    fun finish(wallet: Wallet): TxBuilderResult {}
+}
+
+/**
+ * A object holding an ScriptPubKey and an amount.
+ *
+ * @property script The ScriptPubKey.
+ * @property amount The amount.
+ */
+data class AddressAmount (
+    var script: Script,
+    var amount: ULong
+)
+
+/**
+ * The BumpFeeTxBuilder is used to bump the fee on a transaction that has been broadcast and has its RBF flag set to true.
+ */
+class BumpFeeTxBuilder() {
+    /**
+     * Explicitly tells the wallet that it is allowed to reduce the amount of the output matching this scriptPubKey
+     * 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 scriptPubkey can’t be found among the recipients of the transaction we are bumping.
+     */
+    fun allowShrinking(address: String): BumpFeeTxBuilder {}
+
+    /** Enable signaling RBF. This will use the default `nsequence` value of `0xFFFFFFFD`. */
+    fun enableRbf(): 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.
+     */
+    fun enableRbfWithSequence(nsequence: UInt): BumpFeeTxBuilder {}
+
+    /** Finish building the transaction. Returns a [TxBuilderResult]. */
+    fun finish(wallet: Wallet): TxBuilderResult {}
+}
+
+/**
+ * A BIP-32 derivation path.
+ *
+ * @param path The derivation path. Must start with `m`. Use this type to derive or extend a [DescriptorSecretKey]
+ * or [DescriptorPublicKey].
+ */
+class DerivationPath(path: String) {}
+
+/**
+ * An extended secret key.
+ *
+ * @param network The network this DescriptorSecretKey is to be used on.
+ * @param mnemonic The mnemonic.
+ * @param password The optional passphrase that can be provided as per BIP-39.
+ *
+ * @sample org.bitcoindevkit.descriptorSecretKeyDeriveSample
+ * @sample org.bitcoindevkit.descriptorSecretKeyExtendSample
+ */
+class DescriptorSecretKey(network: Network, mnemonic: Mnemonic, password: String?) {
+    /** Derive a private descriptor at a given path. */
+    fun derive(path: DerivationPath): DescriptorSecretKey {}
+
+    /** Extend the private descriptor with a custom path. */
+    fun extend(path: DerivationPath): DescriptorSecretKey {}
+
+    /** Return the public version of the descriptor. */
+    fun asPublic(): DescriptorPublicKey {}
+
+    /* Return the raw private key as bytes. */
+    fun secretBytes(): List<UByte>
+
+    /** Return the private descriptor as a string. */
+    fun asString(): String {}
+}
+
+/**
+ * An extended public key.
+ *
+ * @param network The network this DescriptorPublicKey is to be used on.
+ * @param mnemonic The mnemonic.
+ * @param password The optional passphrase that can be provided as per BIP-39.
+ */
+class DescriptorPublicKey(network: Network, mnemonic: String, password: String?) {
+    /** Derive a public descriptor at a given path. */
+    fun derive(path: DerivationPath): DescriptorSecretKey
+
+    /** Extend the public descriptor with a custom path. */
+    fun extend(path: DerivationPath): DescriptorSecretKey
+
+    /** Return the public descriptor as a string. */
+    fun asString(): String
+}
+
+/**
+ * An enum describing entropy length (aka word count) in the mnemonic.
+ */
+enum class WordCount {
+    /** 12 words mnemonic (128 bits entropy). */
+    WORDS12,
+
+    /** 15 words mnemonic (160 bits entropy). */
+    WORDS15,
+
+    /** 18 words mnemonic (192 bits entropy). */
+    WORDS18,
+
+    /** 21 words mnemonic (224 bits entropy). */
+    WORDS21,
+
+    /** 24 words mnemonic (256 bits entropy). */
+    WORDS24,
+}
+
+/**
+ * The value returned from calling the `.finish()` method on the [TxBuilder] or [BumpFeeTxBuilder].
+ *
+ * @property psbt The PSBT
+ * @property transactionDetails The transaction details.
+ *
+ * @sample org.bitcoindevkit.txBuilderResultSample1
+ * @sample org.bitcoindevkit.txBuilderResultSample2
+ */
+data class TxBuilderResult (
+    var psbt: PartiallySignedBitcoinTransaction,
+    var transactionDetails: TransactionDetails
+)
+
+/**
+ * A bitcoin script.
+ */
+class Script(rawOutputScript: List<UByte>)
+
+/**
+ * A bitcoin address.
+ *
+ * @param address The address in string format.
+ */
+class Address(address: String) {
+    /* Return the ScriptPubKey. */
+    fun scriptPubkey(): Script
+}
+
+/**
+ * Mnemonic phrases are a human-readable version of the private keys. Supported number of words are 12, 15, 18, 21 and 24.
+ *
+ * @constructor Generates Mnemonic with a random entropy.
+ * @param mnemonic The mnemonic as a string of space-separated words.
+ *
+ * @sample org.bitcoindevkit.mnemonicSample
+ */
+class Mnemonic(mnemonic: String) {
+    /* Returns Mnemonic as string */
+    fun asString(): String
+
+    /* Parse a Mnemonic from a given string. */
+    fun fromString(): Mnemonic
+
+    /*
+     * Create a new Mnemonic in the specified language from the given entropy. Entropy must be a
+     * multiple of 32 bits (4 bytes) and 128-256 bits in length.
+     */
+    fun fromEntropy(): Mnemonic
+}

api-docs/kotlin/src/test/kotlin/org/bitcoindevkit/Samples.kt

@@ -0,0 +1,233 @@
+package org.bitcoindevkit
+
+fun networkSample() {
+    val wallet = Wallet(
+        descriptor = descriptor,
+        changeDescriptor = changeDescriptor,
+        network = Network.TESTNET,
+        databaseConfig = DatabaseConfig.Memory
+    )
+}
+
+fun balanceSample() {
+    object LogProgress : Progress {
+        override fun update(progress: Float, message: String?) {}
+    }
+
+    val memoryDatabaseConfig = DatabaseConfig.Memory
+    private val blockchainConfig = BlockchainConfig.Electrum(
+        ElectrumConfig(
+            "ssl://electrum.blockstream.info:60002",
+            null,
+            5u,
+            null,
+            200u
+        )
+    )
+    val wallet = Wallet(descriptor, null, Network.TESTNET, memoryDatabaseConfig)
+    val blockchain = Blockchain(blockchainConfig)
+    wallet.sync(blockchain, LogProgress)
+
+    val balance: Balance = wallet.getBalance()
+    println("Total wallet balance is ${balance.total}")
+}
+
+fun electrumBlockchainConfigSample() {
+    val blockchainConfig = BlockchainConfig.Electrum(
+        ElectrumConfig(
+            url = "ssl://electrum.blockstream.info:60002",
+            socks5 = null,
+            retry = 5u,
+            timeout = null,
+            stopGap = 200u
+        )
+    )
+}
+
+fun memoryDatabaseConfigSample() {
+    val memoryDatabaseConfig = DatabaseConfig.Memory
+}
+
+fun sqliteDatabaseConfigSample() {
+    val databaseConfig = DatabaseConfig.Sqlite(SqliteDbConfiguration("bdk-sqlite"))
+}
+
+fun addressIndexSample() {
+    val wallet: Wallet = Wallet(
+        descriptor = descriptor,
+        changeDescriptor = changeDescriptor,
+        network = Network.TESTNET,
+        databaseConfig = DatabaseConfig.Memory
+    )
+
+    fun getLastUnusedAddress(): AddressInfo {
+        return wallet.getAddress(AddressIndex.LAST_UNUSED)
+    }
+}
+
+fun addressInfoSample() {
+    val wallet: Wallet = Wallet(
+        descriptor = descriptor,
+        changeDescriptor = changeDescriptor,
+        network = Network.TESTNET,
+        databaseConfig = DatabaseConfig.Memory
+    )
+
+    fun getLastUnusedAddress(): AddressInfo {
+        return wallet.getAddress(AddressIndex.NEW)
+    }
+
+    val newAddress: AddressInfo = getLastUnusedAddress()
+
+    println("New address at index ${newAddress.index} is ${newAddress.address}")
+}
+
+fun blockchainSample() {
+    val blockchainConfig: BlockchainConfig = BlockchainConfig.Electrum(
+        ElectrumConfig(
+            electrumURL,
+            null,
+            5u,
+            null,
+            10u
+        )
+    )
+
+    val blockchain: Blockchain = Blockchain(blockchainConfig)
+
+    blockchain.broadcast(signedPsbt)
+}
+
+
+fun txBuilderResultSample1() {
+    val faucetAddress = Address("tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt")
+    // TxBuilderResult is a data class, which means you can use destructuring declarations on it to
+    // open it up in its component parts
+    val (psbt, txDetails) = TxBuilder()
+        .addRecipient(faucetAddress.scriptPubkey(), 1000u)
+        .feeRate(1.2f)
+        .finish(wallet)
+
+    println("Txid is ${txDetails.txid}")
+    wallet.sign(psbt)
+}
+
+fun txBuilderResultSample2() {
+    val faucetAddress = Address("tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt")
+    val txBuilderResult: TxBuilderResult = TxBuilder()
+        .addRecipient(faucetAddress.scriptPubkey(), 1000u)
+        .feeRate(1.2f)
+        .finish(wallet)
+
+    val psbt = txBuilderResult.psbt
+    val txDetails = txBuilderResult.transactionDetails
+
+    println("Txid is ${txDetails.txid}")
+    wallet.sign(psbt)
+}
+
+fun descriptorSecretKeyExtendSample() {
+    // The `DescriptorSecretKey.extend()` method allows you to extend a key to any given path.
+
+    // val mnemonic: String = generateMnemonic(WordCount.WORDS12)
+    val mnemonic: Mnemonic = Mnemonic("scene change clap smart together mind wheel knee clip normal trial unusual")
+
+    // the initial DescriptorSecretKey will always be at the "master" node,
+    // i.e. the derivation path is empty
+    val bip32RootKey: DescriptorSecretKey = DescriptorSecretKey(
+        network = Network.TESTNET,
+        mnemonic = mnemonic,
+        password = ""
+    )
+    println(bip32RootKey.asString())
+    // tprv8ZgxMBicQKsPfM8Trx2apvdEkmxbJkYY3ZsmcgKb2bfnLNcBhtCstqQTeFesMRLEJXpjGDinAUJUHprXMwph8dQBdS1HAoxEis8Knimxovf/*
+
+    // the derive method will also automatically apply the wildcard (*) to your path,
+    // i.e the following will generate the typical testnet BIP84 external wallet path
+    // m/84h/1h/0h/0/*
+    val bip84ExternalPath: DerivationPath = DerivationPath("m/84h/1h/0h/0")
+    val externalExtendedKey: DescriptorSecretKey = bip32RootKey.extend(bip84ExternalPath).asString()
+    println(externalExtendedKey)
+    // tprv8ZgxMBicQKsPfM8Trx2apvdEkmxbJkYY3ZsmcgKb2bfnLNcBhtCstqQTeFesMRLEJXpjGDinAUJUHprXMwph8dQBdS1HAoxEis8Knimxovf/84'/1'/0'/0/*
+
+    // to create the descriptor you'll need to use this extended key in a descriptor function,
+    // i.e. wpkh(), tr(), etc.
+    val externalDescriptor = "wpkh($externalExtendedKey)"
+}
+
+fun descriptorSecretKeyDeriveSample() {
+    // The DescriptorSecretKey.derive() method allows you to derive an extended key for a given
+    // node in the derivation tree (for example to create an xpub for a particular account)
+
+    val mnemonic: Mnemonic = Mnemonic("scene change clap smart together mind wheel knee clip normal trial unusual")
+    val bip32RootKey: DescriptorSecretKey = DescriptorSecretKey(
+        network = Network.TESTNET,
+        mnemonic = mnemonic,
+        password = ""
+    )
+
+    val bip84Account0: DerivationPath = DerivationPath("m/84h/1h/0h")
+    val xpubAccount0: DescriptorSecretKey = bip32RootKey.derive(bip84Account0)
+    println(xpubAccount0.asString())
+    // [5512949b/84'/1'/0']tprv8ghw3FWfWTeLCEXcr8f8Q8Lz4QPCELYv3jhBXjAm7XagA6R5hreeWLTJeLBfMj7Ni6Q3PdV1o8NbvNBHE59W97EkRJSU4JkvTQjaNUmQubE/*
+
+    val internalPath: DerivationPath = DerivationPath("m/0")
+    val externalExtendedKey = xpubAccount0.extend(internalPath).asString()
+    println(externalExtendedKey)
+    // [5512949b/84'/1'/0']tprv8ghw3FWfWTeLCEXcr8f8Q8Lz4QPCELYv3jhBXjAm7XagA6R5hreeWLTJeLBfMj7Ni6Q3PdV1o8NbvNBHE59W97EkRJSU4JkvTQjaNUmQubE/0/*
+
+    // to create the descriptor you'll need to use this extended key in a descriptor function,
+    // i.e. wpkh(), tr(), etc.
+    val externalDescriptor = "wpkh($externalExtendedKey)"
+}
+
+fun createTransaction() {
+    val wallet = BdkWallet(
+        descriptor = externalDescriptor,
+        changeDescriptor = internalDescriptor,
+        network = Network.TESTNET,
+        databaseConfig = memoryDatabaseConfig,
+    )
+    val blockchainConfig = BlockchainConfig.Electrum(
+        ElectrumConfig(
+            "ssl://electrum.blockstream.info:60002",
+            null,
+            5u,
+            null,
+            200u
+        )
+    )
+
+    val paymentAddress: Address = Address("tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt")
+    val (psbt, txDetails) = TxBuilder()
+        .addRecipient(faucetAddress.scriptPubkey(), 1000u)
+        .feeRate(1.2f)
+        .finish(wallet)
+
+    wallet.sign(psbt)
+    blockchain.broadcast(psbt)
+}
+
+fun walletSample() {
+    val externalDescriptor = "wpkh(tprv8hwWMmPE4BVNxGdVt3HhEERZhondQvodUY7Ajyseyhudr4WabJqWKWLr4Wi2r26CDaNCQhhxEfVULesmhEfZYyBXdE/84h/1h/0h/0/*)"
+    val internalDescriptor = "wpkh(tprv8hwWMmPE4BVNxGdVt3HhEERZhondQvodUY7Ajyseyhudr4WabJqWKWLr4Wi2r26CDaNCQhhxEfVULesmhEfZYyBXdE/84h/1h/0h/1/*)"
+    val sqliteDatabaseConfig = DatabaseConfig.Sqlite(SqliteDbConfiguration("bdk-sqlite"))
+
+    val wallet = BdkWallet(
+        descriptor = externalDescriptor,
+        changeDescriptor = internalDescriptor,
+        network = Network.TESTNET,
+        databaseConfig = sqliteDatabaseConfig,
+    )
+}
+
+fun mnemonicSample() {
+    val mnemonic0: Mnemonic = Mnemonic(WordCount.WORDS12)
+
+    val mnemonic1: Mnemonic = Mnemonic.fromString("scene change clap smart together mind wheel knee clip normal trial unusual")
+
+    val entropy: List<UByte> = listOf<UByte>(0u, 0u, 0u, 0u, 0u, 0u, 0u, 0u, 0u, 0u, 0u, 0u, 0u, 0u, 0u, 0u)
+    val mnemonic2: Mnemonic = Mnemonic.fromEntropy(entropy)
+
+    println(mnemonic0.asString(), mnemonic1.asString(), mnemonic2.asString())
+}