docs: wallet docstrings

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<AddressInfo> 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<AddressInfo> 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<CanonicalTx> 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<LocalOutput> 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<LocalOutput> 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]