Use idiomatic Kotlin/Java documentation and KDoc structure

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

@@ -4,27 +4,27 @@ package org.bitcoindevkit
  * The cryptocurrency to act on.
  */
 enum class Network {
-    /** Bitcoin's mainnet */
+    /** Bitcoin's mainnet. */
     BITCOIN,
 
-    /** Bitcoin’s testnet */
+    /** Bitcoin’s testnet. */
     TESTNET,
 
-    /** Bitcoin’s signet */
+    /** Bitcoin’s signet. */
     SIGNET,
 
-    /** Bitcoin’s regtest */
+    /** Bitcoin’s regtest. */
     REGTEST,
 }
 
 /**
  * A derived address and the index it was found at.
+ *
+ * @property index Child index of this address.
+ * @property address Address.
  */
 data class AddressInfo (
-    /** Child index of this address. */
     var index: UInt,
-
-    /** Address. */
     var address: String
 )
 
@@ -37,32 +37,33 @@ 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. */
+    /** 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
+ * 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 (
-    /** All coinbase outputs not yet matured. */
     var immature: ULong,
-
-    /** Unconfirmed UTXOs generated by a wallet tx. */
     var trustedPending: ULong,
-
-    /** Unconfirmed UTXOs received from an external wallet. */
     var untrustedPending: ULong,
-
-    /** Confirmed and immediately spendable balance. */
     var confirmed: ULong,
-
-    /** The sum of trustedPending and confirmed coins. */
     var spendable: ULong,
-
-    /** The whole balance visible to the wallet. */
     var total: ULong
 )
 
@@ -73,112 +74,106 @@ data class Balance (
  * @sample org.bitcoindevkit.sqliteDatabaseConfigExample
  */
 sealed class DatabaseConfig {
-    /** Configuration for an in-memory database */
+    /** Configuration for an in-memory database. */
     object Memory : DatabaseConfig()
 
-    /** Configuration for a Sled database */
+    /** Configuration for a Sled database. */
     data class Sled(val config: SledDbConfiguration) : DatabaseConfig()
 
-    /** Configuration for a SQLite database */
+    /** 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(
-    /** Main directory of the db */
     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(
-    /** Main directory of the db */
     var path: String,
-
-    /** Name of the database tree, a separated namespace for the data */
     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.electrumBlockchainConfigExample
  */
 data class 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`. */
     var url: String,
-
-    /** URL of the socks5 proxy server or a Tor service. */
     var socks5: String?,
-
-    /** Request retry count. */
     var retry: UByte,
-
-    /** Request timeout (seconds). */
     var timeout: UByte?,
-
-    /** Stop searching addresses for transactions after finding an unused gap of this length. */
     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 (
-    /** Base URL of the esplora service, e.g. `https://blockstream.info/api/`. */
     var baseUrl: String,
-
-    /** Optional URL of the proxy to use to make requests to the Esplora server. */
     var proxy: String?,
-
-    /** Number of parallel requests sent to the esplora service (default: 4). */
     var concurrency: UByte?,
-
-    /** Stop searching addresses for transactions after finding an unused gap of this length. */
     var stopGap: ULong,
-
-    /** Socket timeout. */
     var timeout: ULong?
 )
 
 /**
  * Type that can contain any of the blockchain configurations defined by the library.
- *
- *  @sample org.bitcoindevkit.Samples.blockchainConfig
  */
 sealed class BlockchainConfig {
-    /** Electrum client */
+    /** Electrum client. */
     data class Electrum(val config: ElectrumConfig) : BlockchainConfig()
 
-    /** Esplora client */
+    /** 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 (
-    /** 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. */
     var fee: ULong?,
-
-    /** Received value (sats) Sum of owned outputs of this transaction. */
     var received: ULong,
-
-    /** Sent value (sats) Sum of owned inputs of this transaction. */
     var sent: ULong,
-
-    /** Transaction id. */
     var txid: String
-
-    /** If the transaction is confirmed, [BlockTime] contains height and timestamp of the block containing the transaction. This property is null for unconfirmed transactions. */
     var confirmationTime: BlockTime?
 )
 
 /**
  * A blockchain backend.
+ *
+ * @constructor Create the new blockchain client.
+ *
+ * @param config The blockchain configuration required.
  */
 class Blockchain(
     config: BlockchainConfig
@@ -195,6 +190,10 @@ class Blockchain(
 
 /**
  * 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. */
@@ -206,40 +205,38 @@ class PartiallySignedBitcoinTransaction(psbtBase64: String) {
 
 /**
  * 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 (
-    /** The referenced transaction’s txid. */
     var txid: String,
-
-    /** The index of the referenced output in its transaction’s vout. */
     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 (
-    /** The value of the output, in satoshis. */
     var value: ULong,
-
-    /** The address of the output. */
     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 (
-    /** Reference to a transaction output. */
     var outpoint: OutPoint,
-
-    /** Transaction output. */
     var txout: TxOut,
-
-    /** Type of keychain. */
     var keychain: KeychainKind,
-
-    /** Whether this UTXO is spent or not. */
     var isSpent: Boolean
 )
 
@@ -247,7 +244,7 @@ data class LocalUtxo (
  * Types of keychains.
  */
 enum class KeychainKind {
-    /** External */
+    /** External. */
     EXTERNAL,
 
     /** Internal, usually used for change outputs. */
@@ -256,21 +253,32 @@ enum class KeychainKind {
 
 /**
  * Block height and timestamp of a block.
+ *
+ * @property height Confirmation block height.
+ * @property timestamp Confirmation block timestamp.
  */
 data class BlockTime (
-    /** confirmation block height */
     var height: UInt,
-
-    /** confirmation block timestamp */
     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.
  */
 class Wallet(
     descriptor: String,
@@ -278,7 +286,11 @@ class Wallet(
     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]. */
+    /**
+     * 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. */
@@ -331,7 +343,12 @@ class 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. */
+    /**
+     * 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]. */
@@ -343,7 +360,10 @@ class 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. */
+    /**
+     * 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. */
@@ -355,13 +375,27 @@ class 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. */
+    /**
+     * 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. */
+    /**
+     * 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 the BIP174 PSBT. */
@@ -370,26 +404,36 @@ class TxBuilder() {
 
 /**
  * A object holding an address and an amount.
+ *
+ * @property address The address.
+ * @property amount The amount.
  */
 data class AddressAmount (
-    /** The address. */
     var address: String,
-
-    /** The amount. */
     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 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. */
+    /**
+     * 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. */
+    /**
+     * 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 the BIP174 PSBT. */
@@ -398,11 +442,20 @@ class BumpFeeTxBuilder() {
 
 /**
  * Generates a new mnemonic using the English word list and the given number of words (12, 15, 18, 21, or 24).
+ *
+ * @param wordCount The number of words to use for the mnemonic (also determines the amount of entropy that is used).
+ * @return The mnemonic words separated by a space in a String
  */
-fun generateMnemonic(wordCount: WordCount): String {}
+fun generateMnemonic(wordCount: WordCount): String
 
 /**
+ * TODO
  *
+ * @constructor TODO
+ *
+ * @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.
  */
 class DescriptorSecretKey(network: Network, mnemonic: String, password: String?) {
     /** Derive a private descriptor at a given path. */
@@ -414,12 +467,18 @@ class DescriptorSecretKey(network: Network, mnemonic: String, password: String?)
     /** Return the public version of the descriptor. */
     fun asPublic(): DescriptorPublicKey {}
 
-    /** Return the private descriptor as a string.  */
+    /** Return the private descriptor as a string. */
     fun asString(): String {}
 }
 
 /**
+ * TODO
  *
+ * @constructor TODO
+ *
+ * @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. */
@@ -428,7 +487,7 @@ class DescriptorPublicKey(network: Network, mnemonic: String, password: String?)
     /** Extend the public descriptor with a custom path. */
     fun extend(path: DerivationPath): DescriptorSecretKey {}
 
-    /** Return the public descriptor as a string.  */
+    /** Return the public descriptor as a string. */
     fun asString(): String {}
 }
 
@@ -436,18 +495,18 @@ class DescriptorPublicKey(network: Network, mnemonic: String, password: String?)
  * An enum describing entropy length (aka word count) in the mnemonic.
  */
 enum class WordCount {
-    /** 12 words mnemonic (128 bits entropy) */
+    /** 12 words mnemonic (128 bits entropy). */
     WORDS12,
 
-    /** 15 words mnemonic (160 bits entropy) */
+    /** 15 words mnemonic (160 bits entropy). */
     WORDS15,
 
-    /** 18 words mnemonic (192 bits entropy) */
+    /** 18 words mnemonic (192 bits entropy). */
     WORDS18,
 
-    /** 21 words mnemonic (224 bits entropy) */
+    /** 21 words mnemonic (224 bits entropy). */
     WORDS21,
 
-    /** 24 words mnemonic (256 bits entropy) */
+    /** 24 words mnemonic (256 bits entropy). */
     WORDS24,
 }