Merge pull request #4203 from TheBlueMatt/2025-11-0.2-doc-tweaks

Bindings doc updates for 0.2

Author: TheBlueMatt

lightning-invoice/src/lib.rs

@@ -91,7 +91,10 @@ use crate::ser::Base32Iterable;
 #[allow(missing_docs)]
 #[derive(PartialEq, Eq, Debug, Clone)]
 pub enum Bolt11ParseError {
-	Bech32Error(CheckedHrpstringError),
+	Bech32Error(
+		/// This is not exported to bindings users as the details don't matter much
+		CheckedHrpstringError,
+	),
 	ParseAmountError(ParseIntError),
 	MalformedSignature(bitcoin::secp256k1::Error),
 	BadPrefix,

lightning/src/chain/chainmonitor.rs

@@ -253,6 +253,8 @@ impl<ChannelSigner: EcdsaChannelSigner> Deref for LockedChannelMonitor<'_, Chann
 
 /// An unconstructable [`Persist`]er which is used under the hood when you call
 /// [`ChainMonitor::new_async_beta`].
+///
+/// This is not exported to bindings users as async is not supported outside of Rust.
 pub struct AsyncPersister<
 	K: Deref + MaybeSend + MaybeSync + 'static,
 	S: FutureSpawner,
@@ -431,6 +433,8 @@ impl<
 	/// [`MonitorUpdatingPersisterAsync`] and thus allows persistence to be completed async.
 	///
 	/// Note that async monitor updating is considered beta, and bugs may be triggered by its use.
+	///
+	/// This is not exported to bindings users as async is not supported outside of Rust.
 	pub fn new_async_beta(
 		chain_source: Option<C>, broadcaster: T, logger: L, feeest: F,
 		persister: MonitorUpdatingPersisterAsync<K, S, L, ES, SP, T, F>, _entropy_source: ES,

lightning/src/events/bump_transaction/mod.rs

@@ -353,6 +353,9 @@ pub struct CoinSelection {
 /// which can provide a default implementation of this trait when used with [`Wallet`].
 ///
 /// For a synchronous version of this trait, see [`sync::CoinSelectionSourceSync`].
+///
+/// This is not exported to bindings users as async is only supported in Rust.
+// Note that updates to documentation on this trait should be copied to the synchronous version.
 pub trait CoinSelectionSource {
 	/// Performs coin selection of a set of UTXOs, with at least 1 confirmation each, that are
 	/// available to spend. Implementations are free to pick their coin selection algorithm of
@@ -404,6 +407,9 @@ pub trait CoinSelectionSource {
 /// provide a default implementation to [`CoinSelectionSource`].
 ///
 /// For a synchronous version of this trait, see [`sync::WalletSourceSync`].
+///
+/// This is not exported to bindings users as async is only supported in Rust.
+// Note that updates to documentation on this trait should be copied to the synchronous version.
 pub trait WalletSource {
 	/// Returns all UTXOs, with at least 1 confirmation each, that are available to spend.
 	fn list_confirmed_utxos<'a>(&'a self) -> AsyncResult<'a, Vec<Utxo>, ()>;
@@ -419,11 +425,14 @@ pub trait WalletSource {
 	fn sign_psbt<'a>(&'a self, psbt: Psbt) -> AsyncResult<'a, Transaction, ()>;
 }
 
-/// A wrapper over [`WalletSource`] that implements [`CoinSelection`] by preferring UTXOs that would
-/// avoid conflicting double spends. If not enough UTXOs are available to do so, conflicting double
-/// spends may happen.
+/// A wrapper over [`WalletSource`] that implements [`CoinSelectionSource`] by preferring UTXOs
+/// that would avoid conflicting double spends. If not enough UTXOs are available to do so,
+/// conflicting double spends may happen.
 ///
 /// For a synchronous version of this wrapper, see [`sync::WalletSync`].
+///
+/// This is not exported to bindings users as async is only supported in Rust.
+// Note that updates to documentation on this struct should be copied to the synchronous version.
 pub struct Wallet<W: Deref + MaybeSync + MaybeSend, L: Deref + MaybeSync + MaybeSend>
 where
 	W::Target: WalletSource + MaybeSend,
@@ -670,7 +679,10 @@ where
 ///
 /// For a synchronous version of this handler, see [`sync::BumpTransactionEventHandlerSync`].
 ///
+/// This is not exported to bindings users as async is only supported in Rust.
+///
 /// [`Event::BumpTransaction`]: crate::events::Event::BumpTransaction
+// Note that updates to documentation on this struct should be copied to the synchronous version.
 pub struct BumpTransactionEventHandler<B: Deref, C: Deref, SP: Deref, L: Deref>
 where
 	B::Target: BroadcasterInterface,

lightning/src/events/bump_transaction/sync.rs

@@ -28,13 +28,26 @@ use super::{
 	WalletSource,
 };
 
-/// A synchronous version of the [`WalletSource`] trait.
+/// An alternative to [`CoinSelectionSourceSync`] that can be implemented and used along
+/// [`WalletSync`] to provide a default implementation to [`CoinSelectionSourceSync`].
+///
+/// For an asynchronous version of this trait, see [`WalletSource`].
+// Note that updates to documentation on this trait should be copied to the asynchronous version.
 pub trait WalletSourceSync {
-	/// A synchronous version of [`WalletSource::list_confirmed_utxos`].
+	/// Returns all UTXOs, with at least 1 confirmation each, that are available to spend.
 	fn list_confirmed_utxos(&self) -> Result<Vec<Utxo>, ()>;
-	/// A synchronous version of [`WalletSource::get_change_script`].
+	/// Returns a script to use for change above dust resulting from a successful coin selection
+	/// attempt.
 	fn get_change_script(&self) -> Result<ScriptBuf, ()>;
-	/// A Synchronous version of [`WalletSource::sign_psbt`].
+	/// Signs and provides the full [`TxIn::script_sig`] and [`TxIn::witness`] for all inputs within
+	/// the transaction known to the wallet (i.e., any provided via
+	/// [`WalletSource::list_confirmed_utxos`]).
+	///
+	/// If your wallet does not support signing PSBTs you can call `psbt.extract_tx()` to get the
+	/// unsigned transaction and then sign it with your wallet.
+	///
+	/// [`TxIn::script_sig`]: bitcoin::TxIn::script_sig
+	/// [`TxIn::witness`]: bitcoin::TxIn::witness
 	fn sign_psbt(&self, psbt: Psbt) -> Result<Transaction, ()>;
 }
 
@@ -74,7 +87,12 @@ where
 	}
 }
 
-/// A synchronous wrapper around [`Wallet`] to be used in contexts where async is not available.
+/// A wrapper over [`WalletSourceSync`] that implements [`CoinSelectionSourceSync`] by preferring
+/// UTXOs that would avoid conflicting double spends. If not enough UTXOs are available to do so,
+/// conflicting double spends may happen.
+///
+/// For an asynchronous version of this wrapper, see [`Wallet`].
+// Note that updates to documentation on this struct should be copied to the asynchronous version.
 pub struct WalletSync<W: Deref + MaybeSync + MaybeSend, L: Deref + MaybeSync + MaybeSend>
 where
 	W::Target: WalletSourceSync + MaybeSend,
@@ -136,15 +154,59 @@ where
 	}
 }
 
-/// A synchronous version of the [`CoinSelectionSource`] trait.
+/// An abstraction over a bitcoin wallet that can perform coin selection over a set of UTXOs and can
+/// sign for them. The coin selection method aims to mimic Bitcoin Core's `fundrawtransaction` RPC,
+/// which most wallets should be able to satisfy. Otherwise, consider implementing
+/// [`WalletSourceSync`], which can provide a default implementation of this trait when used with
+/// [`WalletSync`].
+///
+/// For an asynchronous version of this trait, see [`CoinSelectionSource`].
+// Note that updates to documentation on this trait should be copied to the asynchronous version.
 pub trait CoinSelectionSourceSync {
-	/// A synchronous version of [`CoinSelectionSource::select_confirmed_utxos`].
+	/// Performs coin selection of a set of UTXOs, with at least 1 confirmation each, that are
+	/// available to spend. Implementations are free to pick their coin selection algorithm of
+	/// choice, as long as the following requirements are met:
+	///
+	/// 1. `must_spend` contains a set of [`Input`]s that must be included in the transaction
+	///    throughout coin selection, but must not be returned as part of the result.
+	/// 2. `must_pay_to` contains a set of [`TxOut`]s that must be included in the transaction
+	///    throughout coin selection. In some cases, like when funding an anchor transaction, this
+	///    set is empty. Implementations should ensure they handle this correctly on their end,
+	///    e.g., Bitcoin Core's `fundrawtransaction` RPC requires at least one output to be
+	///    provided, in which case a zero-value empty OP_RETURN output can be used instead.
+	/// 3. Enough inputs must be selected/contributed for the resulting transaction (including the
+	///    inputs and outputs noted above) to meet `target_feerate_sat_per_1000_weight`.
+	/// 4. The final transaction must have a weight smaller than `max_tx_weight`; if this
+	///    constraint can't be met, return an `Err`. In the case of counterparty-signed HTLC
+	///    transactions, we will remove a chunk of HTLCs and try your algorithm again. As for
+	///    anchor transactions, we will try your coin selection again with the same input-output
+	///    set when you call [`ChannelMonitor::rebroadcast_pending_claims`], as anchor transactions
+	///    cannot be downsized.
+	///
+	/// Implementations must take note that [`Input::satisfaction_weight`] only tracks the weight of
+	/// the input's `script_sig` and `witness`. Some wallets, like Bitcoin Core's, may require
+	/// providing the full input weight. Failing to do so may lead to underestimating fee bumps and
+	/// delaying block inclusion.
+	///
+	/// The `claim_id` must map to the set of external UTXOs assigned to the claim, such that they
+	/// can be re-used within new fee-bumped iterations of the original claiming transaction,
+	/// ensuring that claims don't double spend each other. If a specific `claim_id` has never had a
+	/// transaction associated with it, and all of the available UTXOs have already been assigned to
+	/// other claims, implementations must be willing to double spend their UTXOs. The choice of
+	/// which UTXOs to double spend is left to the implementation, but it must strive to keep the
+	/// set of other claims being double spent to a minimum.
+	///
+	/// [`ChannelMonitor::rebroadcast_pending_claims`]: crate::chain::channelmonitor::ChannelMonitor::rebroadcast_pending_claims
 	fn select_confirmed_utxos(
 		&self, claim_id: ClaimId, must_spend: Vec<Input>, must_pay_to: &[TxOut],
 		target_feerate_sat_per_1000_weight: u32, max_tx_weight: u64,
 	) -> Result<CoinSelection, ()>;
 
-	/// A synchronous version of [`CoinSelectionSource::sign_psbt`].
+	/// Signs and provides the full witness for all inputs within the transaction known to the
+	/// trait (i.e., any provided via [`CoinSelectionSourceSync::select_confirmed_utxos`]).
+	///
+	/// If your wallet does not support signing PSBTs you can call `psbt.extract_tx()` to get the
+	/// unsigned transaction and then sign it with your wallet.
 	fn sign_psbt(&self, psbt: Psbt) -> Result<Transaction, ()>;
 }
 
@@ -188,7 +250,14 @@ where
 	}
 }
 
-/// A synchronous wrapper around [`BumpTransactionEventHandler`] to be used in contexts where async is not available.
+/// A handler for [`Event::BumpTransaction`] events that sources confirmed UTXOs from a
+/// [`CoinSelectionSourceSync`] to fee bump transactions via Child-Pays-For-Parent (CPFP) or
+/// Replace-By-Fee (RBF).
+///
+/// For an asynchronous version of this handler, see [`BumpTransactionEventHandler`].
+///
+/// [`Event::BumpTransaction`]: crate::events::Event::BumpTransaction
+// Note that updates to documentation on this struct should be copied to the synchronous version.
 pub struct BumpTransactionEventHandlerSync<B: Deref, C: Deref, SP: Deref, L: Deref>
 where
 	B::Target: BroadcasterInterface,

lightning/src/ln/funding.rs

@@ -9,12 +9,13 @@
 
 //! Types pertaining to funding channels.
 
+use alloc::vec::Vec;
+
 use bitcoin::{Amount, ScriptBuf, SignedAmount, TxOut};
 use bitcoin::{Script, Sequence, Transaction, Weight};
 
 use crate::events::bump_transaction::Utxo;
 use crate::ln::chan_utils::EMPTY_SCRIPT_SIG_WEIGHT;
-use crate::prelude::Vec;
 use crate::sign::{P2TR_KEY_PATH_WITNESS_WEIGHT, P2WPKH_WITNESS_WEIGHT};
 
 /// The components of a splice's funding transaction that are contributed by one party.

lightning/src/offers/flow.rs

@@ -597,6 +597,8 @@ where
 	///
 	/// Returns an error if the parameterized [`Router`] is unable to create a blinded path for the offer.
 	///
+	/// This is not exported to bindings users as builder patterns don't map outside of move semantics.
+	///
 	/// [`DefaultMessageRouter`]: crate::onion_message::messenger::DefaultMessageRouter
 	pub fn create_offer_builder<ES: Deref>(
 		&self, entropy_source: ES, peers: Vec<MessageForwardNode>,
@@ -618,6 +620,8 @@ where
 	/// This gives users full control over how the [`BlindedMessagePath`] is constructed,
 	/// including the option to omit it entirely.
 	///
+	/// This is not exported to bindings users as builder patterns don't map outside of move semantics.
+	///
 	/// See [`Self::create_offer_builder`] for more details on usage.
 	pub fn create_offer_builder_using_router<ME: Deref, ES: Deref>(
 		&self, router: ME, entropy_source: ES, peers: Vec<MessageForwardNode>,
@@ -644,6 +648,8 @@ where
 	/// 2. Use [`Self::create_static_invoice_builder`] to create a [`StaticInvoice`] from this
 	///    [`Offer`] plus the returned [`Nonce`], and provide the static invoice to the
 	///    aforementioned always-online node.
+	///
+	/// This is not exported to bindings users as builder patterns don't map outside of move semantics.
 	pub fn create_async_receive_offer_builder<ES: Deref>(
 		&self, entropy_source: ES, message_paths_to_always_online_node: Vec<BlindedMessagePath>,
 	) -> Result<(OfferBuilder<'_, DerivedMetadata, secp256k1::All>, Nonce), Bolt12SemanticError>
@@ -726,6 +732,8 @@ where
 	/// - `amount_msats` is invalid, or
 	/// - The parameterized [`Router`] is unable to create a blinded path for the refund.
 	///
+	/// This is not exported to bindings users as builder patterns don't map outside of move semantics.
+	///
 	/// [`Event::PaymentFailed`]: crate::events::Event::PaymentFailed
 	/// [`RouteParameters::from_payment_params_and_value`]: crate::routing::router::RouteParameters::from_payment_params_and_value
 	pub fn create_refund_builder<ES: Deref>(
@@ -762,6 +770,8 @@ where
 	/// return an error if the provided [`MessageRouter`] fails to construct a valid
 	/// [`BlindedMessagePath`] for the refund.
 	///
+	/// This is not exported to bindings users as builder patterns don't map outside of move semantics.
+	///
 	/// [`Refund`]: crate::offers::refund::Refund
 	/// [`BlindedMessagePath`]: crate::blinded_path::message::BlindedMessagePath
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
@@ -797,6 +807,8 @@ where
 	/// # Nonce
 	/// The nonce is used to create a unique [`InvoiceRequest::payer_metadata`] for the invoice request.
 	/// These will be used to verify the corresponding [`Bolt12Invoice`] when it is received.
+	///
+	/// This is not exported to bindings users as builder patterns don't map outside of move semantics.
 	pub fn create_invoice_request_builder<'a>(
 		&'a self, offer: &'a Offer, nonce: Nonce, payment_id: PaymentId,
 	) -> Result<InvoiceRequestBuilder<'a, 'a, secp256k1::All>, Bolt12SemanticError> {
@@ -812,6 +824,8 @@ where
 
 	/// Creates a [`StaticInvoiceBuilder`] from the corresponding [`Offer`] and [`Nonce`] that were
 	/// created via [`Self::create_async_receive_offer_builder`].
+	///
+	/// This is not exported to bindings users as builder patterns don't map outside of move semantics.
 	pub fn create_static_invoice_builder<'a, ES: Deref, R: Deref>(
 		&self, router: &R, entropy_source: ES, offer: &'a Offer, offer_nonce: Nonce,
 		payment_secret: PaymentSecret, relative_expiry_secs: u32,
@@ -884,6 +898,8 @@ where
 	///
 	/// Returns an error if the refund targets a different chain or if no valid
 	/// blinded path can be constructed.
+	///
+	/// This is not exported to bindings users as builder patterns don't map outside of move semantics.
 	pub fn create_invoice_builder_from_refund<'a, ES: Deref, R: Deref, F>(
 		&'a self, router: &R, entropy_source: ES, refund: &'a Refund,
 		usable_channels: Vec<ChannelDetails>, get_payment_info: F,

lightning/src/offers/merkle.rs

@@ -94,6 +94,9 @@ pub enum SignError {
 }
 
 /// A function for signing a [`TaggedHash`].
+///
+/// This is not exported to bindings users as signing functions should just be used per-signed-type
+/// instead.
 pub trait SignFn<T: AsRef<TaggedHash>> {
 	/// Signs a [`TaggedHash`] computed over the merkle root of `message`'s TLV stream.
 	fn sign(&self, message: &T) -> Result<Signature, ()>;

lightning/src/offers/parse.rs

@@ -142,7 +142,10 @@ pub enum Bolt12ParseError {
 	/// being parsed.
 	InvalidBech32Hrp,
 	/// The string could not be bech32 decoded.
-	Bech32(CheckedHrpstringError),
+	Bech32(
+		/// This is not exported to bindings users as the details don't matter much
+		CheckedHrpstringError,
+	),
 	/// The bech32 decoded string could not be decoded as the expected message type.
 	Decode(DecodeError),
 	/// The parsed message has invalid semantics.

lightning/src/sign/ecdsa.rs

@@ -7,15 +7,16 @@ use bitcoin::secp256k1::ecdsa::Signature;
 use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
 
 use crate::ln::chan_utils::{
-	ClosingTransaction, CommitmentTransaction, HTLCOutputInCommitment, HolderCommitmentTransaction,
+	ChannelTransactionParameters, ClosingTransaction, CommitmentTransaction,
+	HTLCOutputInCommitment, HolderCommitmentTransaction,
 };
 use crate::ln::msgs::UnsignedChannelAnnouncement;
 use crate::types::payment::PaymentPreimage;
 
 #[allow(unused_imports)]
 use crate::prelude::*;
 
-use crate::sign::{ChannelSigner, ChannelTransactionParameters, HTLCDescriptor};
+use crate::sign::{ChannelSigner, HTLCDescriptor};
 
 /// A trait to sign Lightning channel transactions as described in
 /// [BOLT 3](https://github.com/lightning/bolts/blob/master/03-transactions.md).

lightning/src/sign/mod.rs

@@ -1058,6 +1058,8 @@ pub trait SignerProvider {
 
 /// A helper trait that describes an on-chain wallet capable of returning a (change) destination
 /// script.
+///
+/// This is not exported to bindings users as async is only supported in Rust.
 pub trait ChangeDestinationSource {
 	/// Returns a script pubkey which can be used as a change destination for
 	/// [`OutputSpender::spend_spendable_outputs`].
@@ -1069,6 +1071,9 @@ pub trait ChangeDestinationSource {
 
 /// A synchronous helper trait that describes an on-chain wallet capable of returning a (change) destination script.
 pub trait ChangeDestinationSourceSync {
+	/// Returns a script pubkey which can be used as a change destination for
+	/// [`OutputSpender::spend_spendable_outputs`].
+	///
 	/// This method should return a different value each time it is called, to avoid linking
 	/// on-chain funds controlled to the same user.
 	fn get_change_destination_script(&self) -> Result<ScriptBuf, ()>;