513 lines
18 KiB
Kotlin
513 lines
18 KiB
Kotlin
package org.bitcoindevkit
|
||
|
||
/**
|
||
* The cryptocurrency to act on.
|
||
*/
|
||
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.
|
||
*/
|
||
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`.
|
||
*/
|
||
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.memoryDatabaseConfigExample
|
||
* @sample org.bitcoindevkit.sqliteDatabaseConfigExample
|
||
*/
|
||
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.electrumBlockchainConfigExample
|
||
*/
|
||
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.
|
||
*/
|
||
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.
|
||
*/
|
||
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 {}
|
||
}
|
||
|
||
/**
|
||
* 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.
|
||
*/
|
||
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(address: String, amount: ULong): TxBuilder {}
|
||
|
||
/** Set the list of recipients by providing a list of [AddressAmount]. */
|
||
fun setRecipients(recipients: List<AddressAmount>): 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 the BIP174 PSBT. */
|
||
fun finish(wallet: Wallet): PartiallySignedBitcoinTransaction {}
|
||
}
|
||
|
||
/**
|
||
* A object holding an address and an amount.
|
||
*
|
||
* @property address The address.
|
||
* @property amount The amount.
|
||
*/
|
||
data class AddressAmount (
|
||
var address: String,
|
||
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 the BIP174 PSBT. */
|
||
fun finish(wallet: Wallet): PartiallySignedBitcoinTransaction {}
|
||
}
|
||
|
||
/**
|
||
* 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
|
||
|
||
/**
|
||
* 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. */
|
||
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 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. */
|
||
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,
|
||
}
|