Rename KeysInterface ready_channel to provide_channel_parameters

Now that ready_channel is also called on startup upon deserializing
channels, we opt to rename it to a more indicative name.

We also derive `PartialEq` on ChannelTransactionParameters to allow
implementations to determine whether `provide_channel_parameters` calls
are idempotent after the channel parameters have already been provided.

Author: wpaulino

lightning/src/chain/keysinterface.rs

@@ -161,7 +161,7 @@ pub enum SpendableOutputDescriptor {
 	///
 	/// To derive the revocation_pubkey provided here (which is used in the witness
 	/// script generation), you must pass the counterparty revocation_basepoint (which appears in the
-	/// call to Sign::ready_channel) and the provided per_commitment point
+	/// call to Sign::provide_channel_parameters) and the provided per_commitment point
 	/// to chan_utils::derive_public_revocation_key.
 	///
 	/// The witness script which is hashed and included in the output script_pubkey may be
@@ -368,16 +368,14 @@ pub trait BaseSign {
 		-> Result<(Signature, Signature), ()>;
 
 	/// Set the counterparty static channel data, including basepoints,
-	/// counterparty_selected/holder_selected_contest_delay and funding outpoint.
-	/// This is done as soon as the funding outpoint is known.  Since these are static channel data,
-	/// they MUST NOT be allowed to change to different values once set.
+	/// 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.
 	///
-	/// channel_parameters.is_populated() MUST be true.
-	///
-	/// We bind holder_selected_contest_delay late here for API convenience.
+	/// LDK will call this method once per signer derivation, either immediately after, or if the
+	/// channel has yet to be funded, as soon as the funding outpoint is known.
 	///
-	/// Will be called before any signatures are applied.
-	fn ready_channel(&mut self, channel_parameters: &ChannelTransactionParameters);
+	/// channel_parameters.is_populated() MUST be true.
+	fn provide_channel_parameters(&mut self, channel_parameters: &ChannelTransactionParameters);
 }
 
 /// A cloneable signer.
@@ -583,39 +581,39 @@ impl InMemorySigner {
 	}
 
 	/// Counterparty pubkeys.
-	/// Will panic if ready_channel wasn't called.
+	/// Will panic if provide_channel_parameters wasn't called.
 	pub fn counterparty_pubkeys(&self) -> &ChannelPublicKeys { &self.get_channel_parameters().counterparty_parameters.as_ref().unwrap().pubkeys }
 
 	/// The contest_delay value specified by our counterparty and applied on holder-broadcastable
 	/// transactions, ie the amount of time that we have to wait to recover our funds if we
 	/// broadcast a transaction.
-	/// Will panic if ready_channel wasn't called.
+	/// Will panic if provide_channel_parameters wasn't called.
 	pub fn counterparty_selected_contest_delay(&self) -> u16 { self.get_channel_parameters().counterparty_parameters.as_ref().unwrap().selected_contest_delay }
 
 	/// The contest_delay value specified by us and applied on transactions broadcastable
 	/// by our counterparty, ie the amount of time that they have to wait to recover their funds
 	/// if they broadcast a transaction.
-	/// Will panic if ready_channel wasn't called.
+	/// Will panic if provide_channel_parameters wasn't called.
 	pub fn holder_selected_contest_delay(&self) -> u16 { self.get_channel_parameters().holder_selected_contest_delay }
 
 	/// Whether the holder is the initiator
-	/// Will panic if ready_channel wasn't called.
+	/// Will panic if provide_channel_parameters wasn't called.
 	pub fn is_outbound(&self) -> bool { self.get_channel_parameters().is_outbound_from_holder }
 
 	/// Funding outpoint
-	/// Will panic if ready_channel wasn't called.
+	/// Will panic if provide_channel_parameters wasn't called.
 	pub fn funding_outpoint(&self) -> &OutPoint { self.get_channel_parameters().funding_outpoint.as_ref().unwrap() }
 
 	/// Obtain a ChannelTransactionParameters for this channel, to be used when verifying or
 	/// building transactions.
 	///
-	/// Will panic if ready_channel wasn't called.
+	/// Will panic if provide_channel_parameters wasn't called.
 	pub fn get_channel_parameters(&self) -> &ChannelTransactionParameters {
 		self.channel_parameters.as_ref().unwrap()
 	}
 
 	/// Whether anchors should be used.
-	/// Will panic if ready_channel wasn't called.
+	/// Will panic if provide_channel_parameters wasn't called.
 	pub fn opt_anchors(&self) -> bool {
 		self.get_channel_parameters().opt_anchors.is_some()
 	}
@@ -819,7 +817,7 @@ impl BaseSign for InMemorySigner {
 		Ok((sign(secp_ctx, &msghash, &self.node_secret), sign(secp_ctx, &msghash, &self.funding_key)))
 	}
 
-	fn ready_channel(&mut self, channel_parameters: &ChannelTransactionParameters) {
+	fn provide_channel_parameters(&mut self, channel_parameters: &ChannelTransactionParameters) {
 		assert!(self.channel_parameters.is_none(), "Acceptance already noted");
 		assert!(channel_parameters.is_populated(), "Channel parameters must be fully populated");
 		self.channel_parameters = Some(channel_parameters.clone());

lightning/src/ln/chan_utils.rs

@@ -763,7 +763,7 @@ pub fn build_anchor_input_witness(funding_key: &PublicKey, funding_sig: &Signatu
 ///
 /// Normally, this is converted to the broadcaster/countersignatory-organized DirectedChannelTransactionParameters
 /// before use, via the as_holder_broadcastable and as_counterparty_broadcastable functions.
-#[derive(Clone)]
+#[derive(Clone, PartialEq)]
 pub struct ChannelTransactionParameters {
 	/// Holder public keys
 	pub holder_pubkeys: ChannelPublicKeys,
@@ -787,7 +787,7 @@ pub struct ChannelTransactionParameters {
 }
 
 /// Late-bound per-channel counterparty data used to build transactions.
-#[derive(Clone)]
+#[derive(Clone, PartialEq)]
 pub struct CounterpartyChannelTransactionParameters {
 	/// Counter-party public keys
 	pub pubkeys: ChannelPublicKeys,

lightning/src/ln/channel.rs

@@ -2215,7 +2215,7 @@ impl<Signer: Sign> Channel<Signer> {
 		self.channel_transaction_parameters.funding_outpoint = Some(funding_txo);
 		// This is an externally observable change before we finish all our checks.  In particular
 		// funding_created_signature may fail.
-		self.holder_signer.ready_channel(&self.channel_transaction_parameters);
+		self.holder_signer.provide_channel_parameters(&self.channel_transaction_parameters);
 
 		let (counterparty_initial_commitment_txid, initial_commitment_tx, signature) = match self.funding_created_signature(&msg.signature, logger) {
 			Ok(res) => res,
@@ -5250,7 +5250,7 @@ impl<Signer: Sign> Channel<Signer> {
 		}
 
 		self.channel_transaction_parameters.funding_outpoint = Some(funding_txo);
-		self.holder_signer.ready_channel(&self.channel_transaction_parameters);
+		self.holder_signer.provide_channel_parameters(&self.channel_transaction_parameters);
 
 		let signature = match self.get_outbound_funding_created_signature(logger) {
 			Ok(res) => res,
@@ -7296,7 +7296,7 @@ mod tests {
 				selected_contest_delay: 144
 			});
 		chan.channel_transaction_parameters.funding_outpoint = Some(funding_info);
-		signer.ready_channel(&chan.channel_transaction_parameters);
+		signer.provide_channel_parameters(&chan.channel_transaction_parameters);
 
 		assert_eq!(counterparty_pubkeys.payment_point.serialize()[..],
 		           hex::decode("032c0b7cf95324a07d05398b240174dc0c2be444d96b159aa6c7f7b1e668680991").unwrap()[..]);

lightning/src/util/enforcing_trait_impls.rs

@@ -215,8 +215,8 @@ impl BaseSign for EnforcingSigner {
 		self.inner.sign_channel_announcement(msg, secp_ctx)
 	}
 
-	fn ready_channel(&mut self, channel_parameters: &ChannelTransactionParameters) {
-		self.inner.ready_channel(channel_parameters)
+	fn provide_channel_parameters(&mut self, channel_parameters: &ChannelTransactionParameters) {
+		self.inner.provide_channel_parameters(channel_parameters)
 	}
 }