From c74be6afe141ec1211d86c5e82837fe17fd1f3c6 Mon Sep 17 00:00:00 2001 From: Matthew Date: Thu, 31 Oct 2024 12:22:28 -0500 Subject: [PATCH] docs: wallet docstrings --- bdk-ffi/src/bdk.udl | 129 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) diff --git a/bdk-ffi/src/bdk.udl b/bdk-ffi/src/bdk.udl index 12b87851..cfa793dd 100644 --- a/bdk-ffi/src/bdk.udl +++ b/bdk-ffi/src/bdk.udl @@ -362,9 +362,14 @@ interface ChangeSet {}; // bdk_wallet crate - wallet module // ------------------------------------------------------------------------ +/// Policy regarding the use of change outputs when creating a transaction enum ChangeSpendPolicy { +/// Use both change and non-change outputs (default) "ChangeAllowed", + /// Only use change outputs (see [`TxBuilder::only_spend_change`]) "OnlyChange", + + /// Only use non-change outputs "ChangeForbidden" }; @@ -375,64 +380,188 @@ interface Wallet { [Name=load, Throws=LoadWithPersistError] constructor(Descriptor descriptor, Descriptor change_descriptor, Connection connection); +/// Informs the wallet that you no longer intend to broadcast a tx that was built from it. +/// +/// This frees up the change address used when creating the tx for use in future transactions. void cancel_tx([ByRef] Transaction tx); +/// The derivation index of this wallet. It will return `None` if it has not derived any addresses. +/// Otherwise, it will return the index of the highest address it has derived. u32? derivation_index(KeychainKind keychain); +/// Returns the utxo owned by this wallet corresponding to `outpoint` if it exists in the +/// wallet's database. LocalOutput? get_utxo(OutPoint op); +/// Finds how the wallet derived the script pubkey `spk`. +/// +/// Will only return `Some(_)` if the wallet has given out the spk. KeychainAndIndex? derivation_of_spk(Script spk); +/// Attempt to reveal the next address of the given `keychain`. +/// +/// This will increment the keychain's derivation index. If the keychain's descriptor doesn't +/// contain a wildcard or every address is already revealed up to the maximum derivation +/// index defined in [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), +/// then the last revealed address will be returned. AddressInfo reveal_next_address(KeychainKind keychain); +/// Peek an address of the given `keychain` at `index` without revealing it. +/// +/// For non-wildcard descriptors this returns the same address at every provided index. +/// +/// # Panics +/// +/// This panics when the caller requests for an address of derivation index greater than the +/// [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) max index. AddressInfo peek_address(KeychainKind keychain, u32 index); +/// The index of the next address that you would get if you were to ask the wallet for a new address u32 next_derivation_index(KeychainKind keychain); +/// Get the next unused address for the given `keychain`, i.e. the address with the lowest +/// derivation index that hasn't been used. +/// +/// This will attempt to derive and reveal a new address if no newly revealed addresses +/// are available. See also [`reveal_next_address`](Self::reveal_next_address). +/// +/// **WARNING**: To avoid address reuse you must persist the changes resulting from one or more +/// calls to this method before closing the wallet. See [`Wallet::reveal_next_address`]. AddressInfo next_unused_address(KeychainKind keychain); +/// Marks an address used of the given `keychain` at `index`. +/// +/// Returns whether the given index was present and then removed from the unused set. boolean mark_used(KeychainKind keychain, u32 index); +/// Reveal addresses up to and including the target `index` and return an iterator +/// of newly revealed addresses. +/// +/// If the target `index` is unreachable, we make a best effort to reveal up to the last +/// possible index. If all addresses up to the given `index` are already revealed, then +/// no new addresses are returned. +/// +/// **WARNING**: To avoid address reuse you must persist the changes resulting from one or more +/// calls to this method before closing the wallet. See [`Wallet::reveal_next_address`]. sequence reveal_addresses_to(KeychainKind keychain, u32 index); +/// List addresses that are revealed but unused. +/// +/// Note if the returned iterator is empty you can reveal more addresses +/// by using [`reveal_next_address`](Self::reveal_next_address) or +/// [`reveal_addresses_to`](Self::reveal_addresses_to). sequence list_unused_addresses(KeychainKind keychain); +/// Get the Bitcoin network the wallet is using. Network network(); +/// Return the checksum of the public descriptor associated to `keychain` +/// +/// Internally calls [`Self::public_descriptor`] to fetch the right descriptor string descriptor_checksum(KeychainKind keychain); +/// Return the balance, separated into available, trusted-pending, untrusted-pending and immature +/// values. Balance balance(); +/// Applies an update to the wallet and stages the changes (but does not persist them). +/// +/// Usually you create an `update` by interacting with some blockchain data source and inserting +/// transactions related to your wallet into it. +/// +/// After applying updates you should persist the staged wallet changes. For an example of how +/// to persist staged wallet changes see [`Wallet::reveal_next_address`]. [Throws=CannotConnectError] void apply_update(Update update); +/// Return whether or not a `script` is part of this wallet (either internal or external) boolean is_mine(Script script); +/// Sign a transaction with all the wallet's signers, in the order specified by every signer's +/// [`SignerOrdering`]. This function returns the `Result` type with an encapsulated `bool` that has the value true if the PSBT was finalized, or false otherwise. +/// +/// The [`SignOptions`] can be used to tweak the behavior of the software signers, and the way +/// the transaction is finalized at the end. Note that it can't be guaranteed that *every* +/// signers will follow the options, but the "software signers" (WIF keys and `xprv`) defined +/// in this library will. [Throws=SignerError] boolean sign(Psbt psbt); +/// Finalize a PSBT, i.e., for each input determine if sufficient data is available to pass +/// validation and construct the respective `scriptSig` or `scriptWitness`. Please refer to +/// [BIP174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#Input_Finalizer), +/// and [BIP371](https://github.com/bitcoin/bips/blob/master/bip-0371.mediawiki) +/// for further information. +/// +/// Returns `true` if the PSBT could be finalized, and `false` otherwise. +/// +/// The [`SignOptions`] can be used to tweak the behavior of the finalizer. [Throws=SignerError] boolean finalize_psbt(Psbt psbt); +/// Compute the `tx`'s sent and received [`Amount`]s. +/// +/// This method returns a tuple `(sent, received)`. Sent is the sum of the txin amounts +/// that spend from previous txouts tracked by this wallet. Received is the summation +/// of this tx's outputs that send to script pubkeys tracked by this wallet. SentAndReceivedValues sent_and_received([ByRef] Transaction tx); +/// Iterate over the transactions in the wallet. sequence transactions(); +/// Get a single transaction from the wallet as a [`WalletTx`] (if the transaction exists). +/// +/// `WalletTx` contains the full transaction alongside meta-data such as: +/// * Blocks that the transaction is [`Anchor`]ed in. These may or may not be blocks that exist +/// in the best chain. +/// * The [`ChainPosition`] of the transaction in the best chain - whether the transaction is +/// confirmed or unconfirmed. If the transaction is confirmed, the anchor which proves the +/// confirmation is provided. If the transaction is unconfirmed, the unix timestamp of when +/// the transaction was last seen in the mempool is provided. [Throws=TxidParseError] CanonicalTx? get_tx(string txid); +/// Calculates the fee of a given transaction. Returns [`Amount::ZERO`] if `tx` is a coinbase transaction. +/// +/// To calculate the fee for a [`Transaction`] with inputs not owned by this wallet you must +/// manually insert the TxOut(s) into the tx graph using the [`insert_txout`] function. +/// +/// Note `tx` does not have to be in the graph for this to work. [Throws=CalculateFeeError] Amount calculate_fee([ByRef] Transaction tx); +/// Calculate the [`FeeRate`] for a given transaction. +/// +/// To calculate the fee rate for a [`Transaction`] with inputs not owned by this wallet you must +/// manually insert the TxOut(s) into the tx graph using the [`insert_txout`] function. +/// +/// Note `tx` does not have to be in the graph for this to work. [Throws=CalculateFeeError] FeeRate calculate_fee_rate([ByRef] Transaction tx); +/// Return the list of unspent outputs of this wallet sequence list_unspent(); +/// List all relevant outputs (includes both spent and unspent, confirmed and unconfirmed). +/// +/// To list only unspent outputs (UTXOs), use [`Wallet::list_unspent`] instead. sequence list_output(); +/// Create a [`FullScanRequest] for this wallet. +/// +/// This is the first step when performing a spk-based wallet full scan, the returned +/// [`FullScanRequest] collects iterators for the wallet's keychain script pub keys needed to +/// start a blockchain full scan with a spk based blockchain client. +/// +/// This operation is generally only used when importing or restoring a previously used wallet +/// in which the list of used scripts is not known. FullScanRequestBuilder start_full_scan(); +/// Create a partial [`SyncRequest`] for this wallet for all revealed spks. +/// +/// This is the first step when performing a spk-based wallet partial sync, the returned +/// [`SyncRequest`] collects all revealed script pubkeys from the wallet keychain needed to +/// start a blockchain sync with a spk based blockchain client. SyncRequestBuilder start_sync_with_revealed_spks(); [Throws=SqliteError]