Merge pull request #1903 from TheBlueMatt/2022-12-1867-followups

Clarify docs on `provide_channel_parameters`

Author: TheBlueMatt

lightning/src/chain/keysinterface.rs

@@ -395,9 +395,12 @@ pub trait BaseSign {
 	fn sign_channel_announcement(&self, msg: &UnsignedChannelAnnouncement, secp_ctx: &Secp256k1<secp256k1::All>)
 		-> Result<(Signature, Signature), ()>;
 	/// Set the counterparty static channel data, including basepoints,
-	/// `counterparty_selected`/`holder_selected_contest_delay` and funding outpoint. Since these
-	/// are static channel data, they MUST NOT be allowed to change to different values once set,
-	/// as LDK may call this method more than once.
+	/// `counterparty_selected`/`holder_selected_contest_delay` and funding outpoint.
+	///
+	/// This data is static, and will never change for a channel once set. For a given [`BaseSign`]
+	/// instance, LDK will call this method exactly once - either immediately after construction
+	/// (not including if done via [`KeysInterface::read_chan_signer`]) or when the funding
+	/// information has been generated.
 	///
 	/// channel_parameters.is_populated() MUST be true.
 	fn provide_channel_parameters(&mut self, channel_parameters: &ChannelTransactionParameters);
@@ -470,8 +473,10 @@ pub trait KeysInterface {
 	/// This method should return a different value each time it is called, to avoid linking
 	/// on-chain funds across channels as controlled to the same user.
 	fn get_shutdown_scriptpubkey(&self) -> ShutdownScript;
-	/// Get a new set of [`Sign`] for per-channel secrets. These MUST be unique even if you
-	/// restarted with some stale data!
+	/// Generates a unique `channel_keys_id` that can be used to obtain a [`Self::Signer`] through
+	/// [`KeysInterface::derive_channel_signer`]. The `user_channel_id` is provided to allow
+	/// implementations of [`KeysInterface`] to maintain a mapping between it and the generated
+	/// `channel_keys_id`.
 	///
 	/// This method must return a different value each time it is called.
 	fn generate_channel_keys_id(&self, inbound: bool, channel_value_satoshis: u64, user_channel_id: u128) -> [u8; 32];