f Address Antoine's feedback

Author: tnull

lightning/src/chain/keysinterface.rs

@@ -8,6 +8,9 @@
 // licenses.
 
 //! Provides keys to LDK and defines some useful objects describing spendable on-chain outputs.
+//!
+//! The provided output descriptors follow a custom LDK data format and are currently not fully
+//! compatible with Bitcoin Core output descriptors.
 
 use bitcoin::blockdata::transaction::{Transaction, TxOut, TxIn, EcdsaSighashType};
 use bitcoin::blockdata::script::{Script, Builder};
@@ -105,7 +108,7 @@ pub struct StaticPaymentOutputDescriptor {
 	/// Arbitrary identification information returned by a call to [`BaseSign::channel_keys_id`].
 	/// This may be useful in re-deriving keys used in the channel to spend the output.
 	pub channel_keys_id: [u8; 32],
-	/// The value of the channel which this transaction spends.
+	/// The value of the funding channel output which this transaction spends.
 	pub channel_value_satoshis: u64,
 }
 impl StaticPaymentOutputDescriptor {
@@ -156,7 +159,8 @@ pub enum SpendableOutputDescriptor {
 	///
 	/// Note that the `nSequence` field in the spending input must be set to `to_self_delay` (which
 	/// means the transaction is not broadcastable until at least `to_self_delay` blocks after the
-	/// outpoint confirms).
+	/// outpoint confirms, see [BIP
+	/// 68](https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki)).
 	///
 	/// These are generally the result of a "revocable" output to us, spendable only by us unless
 	/// it is an output from an old state which we broadcast (which should never happen).
@@ -281,8 +285,9 @@ pub trait BaseSign {
 	/// This will only ever be called with a non-revoked `commitment_tx`. This will be called with the
 	/// latest `commitment_tx` when we initiate a force-close.
 	/// This will be called with the previous latest `commitment_tx`, just to get claiming HTLC
-	/// signatures, if we are reacting to a [`ChannelMonitor`] replica that decided to broadcast before
-	/// it had been updated to the latest `commitment_tx`.
+	/// signatures, if we are reacting to a [`ChannelMonitor`]
+	/// [replica](https://github.com/lightningdevkit/rust-lightning/blob/main/GLOSSARY.md#monitor-replicas)
+	/// that decided to broadcast before it had been updated to the latest `commitment_tx`.
 	/// This may be called multiple times for the same transaction.
 	///
 	/// An external signer implementation should check that the commitment has not been revoked.
@@ -342,7 +347,7 @@ pub trait BaseSign {
 	/// signed for here. It may be called multiple times for same output(s) if a fee-bump is
 	/// needed with regards to an upcoming timelock expiration.
 	///
-	/// `witness_script` is either a offered or received script as defined in BOLT3 for HTLC
+	/// `witness_script` is either an offered or received script as defined in BOLT3 for HTLC
 	/// outputs.
 	///
 	/// `amount` is value of the output spent by this input, committed to in the BIP 143 signature.
@@ -511,13 +516,13 @@ pub trait KeysInterface {
 /// This implementation performs no policy checks and is insufficient by itself as
 /// a secure external signer.
 pub struct InMemorySigner {
-	/// Private key of anchor tx.
+	/// Private key of an anchor transaction.
 	pub funding_key: SecretKey,
 	/// Holder secret key for blinded revocation pubkey.
 	pub revocation_base_key: SecretKey,
 	/// Holder secret key used for our balance in counterparty-broadcasted commitment transactions.
 	pub payment_key: SecretKey,
-	/// Holder secret key used in HTLC tx.
+	/// Holder secret key used in an HTLC transaction.
 	pub delayed_payment_base_key: SecretKey,
 	/// Holder HTLC secret key used in commitment transaction HTLC outputs.
 	pub htlc_base_key: SecretKey,