Expand documentation and fields in SpendableOutputDescriptors

This adds a channel_value_satoshis field to
SpendableOutputDescriptors as it is required to recreate our
InMemoryChannelKeys. It also slightly expands documentation.

Author: TheBlueMatt

lightning/src/chain/channelmonitor.rs

@@ -2206,8 +2206,9 @@ impl<ChanSigner: ChannelKeys> ChannelMonitor<ChanSigner> {
 						per_commitment_point: broadcasted_holder_revokable_script.1,
 						to_self_delay: self.on_holder_tx_csv,
 						output: outp.clone(),
-						key_derivation_params: self.key_derivation_params,
 						revocation_pubkey: broadcasted_holder_revokable_script.2.clone(),
+						key_derivation_params: self.key_derivation_params,
+						channel_value_satoshis: self.channel_value_satoshis,
 					});
 					break;
 				}
@@ -2216,6 +2217,7 @@ impl<ChanSigner: ChannelKeys> ChannelMonitor<ChanSigner> {
 					outpoint: OutPoint { txid: tx.txid(), index: i as u16 },
 					output: outp.clone(),
 					key_derivation_params: self.key_derivation_params,
+					channel_value_satoshis: self.channel_value_satoshis,
 				});
 				break;
 			} else if outp.script_pubkey == self.shutdown_script {

lightning/src/chain/keysinterface.rs

@@ -47,9 +47,9 @@ use ln::msgs::DecodeError;
 /// that txid/index, and any keys or other information required to sign.
 #[derive(Clone, Debug, PartialEq)]
 pub enum SpendableOutputDescriptor {
-	/// An output to a script which was provided via KeysInterface, thus you should already know
-	/// how to spend it. No keys are provided as rust-lightning was never given any keys - only the
-	/// script_pubkey as it appears in the output.
+	/// An output to a script which was provided via KeysInterface directly, either from
+	/// `get_destination_script()` or `get_shutdown_pubkey()`, thus you should already know how to
+	/// spend it. No keys are provided as rust-lightning was never given any key.
 	/// These may include outputs from a transaction punishing our counterparty or claiming an HTLC
 	/// on-chain using the payment preimage or after it has timed out.
 	StaticOutput {
@@ -98,11 +98,14 @@ pub enum SpendableOutputDescriptor {
 		to_self_delay: u16,
 		/// The output which is referenced by the given outpoint
 		output: TxOut,
-		/// The channel keys state used to proceed to derivation of signing key. Must
-		/// be pass to KeysInterface::derive_channel_keys.
-		key_derivation_params: (u64, u64),
 		/// The revocation_pubkey used to derive witnessScript
-		revocation_pubkey: PublicKey
+		revocation_pubkey: PublicKey,
+		/// Arbitrary identification information returned by a call to
+		/// `ChannelKeys::key_derivation_params()`. This may be useful in re-deriving keys used in
+		/// the channel to spend the output.
+		key_derivation_params: (u64, u64),
+		/// The value of the channel which this transactions spends.
+		channel_value_satoshis: u64,
 	},
 	/// An output to a P2WPKH, spendable exclusively by our payment key (ie the private key which
 	/// corresponds to the public key in ChannelKeys::pubkeys().payment_point).
@@ -116,9 +119,12 @@ pub enum SpendableOutputDescriptor {
 		outpoint: OutPoint,
 		/// The output which is reference by the given outpoint
 		output: TxOut,
-		/// The channel keys state used to proceed to derivation of signing key. Must
-		/// be pass to KeysInterface::derive_channel_keys.
+		/// Arbitrary identification information returned by a call to
+		/// `ChannelKeys::key_derivation_params()`. This may be useful in re-deriving keys used in
+		/// the channel to spend the output.
 		key_derivation_params: (u64, u64),
+		/// The value of the channel which this transactions spends.
+		channel_value_satoshis: u64,
 	}
 }
 
@@ -130,22 +136,24 @@ impl Writeable for SpendableOutputDescriptor {
 				outpoint.write(writer)?;
 				output.write(writer)?;
 			},
-			&SpendableOutputDescriptor::DynamicOutputP2WSH { ref outpoint, ref per_commitment_point, ref to_self_delay, ref output, ref key_derivation_params, ref revocation_pubkey } => {
+			&SpendableOutputDescriptor::DynamicOutputP2WSH { ref outpoint, ref per_commitment_point, ref to_self_delay, ref output, ref revocation_pubkey, ref key_derivation_params, channel_value_satoshis } => {
 				1u8.write(writer)?;
 				outpoint.write(writer)?;
 				per_commitment_point.write(writer)?;
 				to_self_delay.write(writer)?;
 				output.write(writer)?;
+				revocation_pubkey.write(writer)?;
 				key_derivation_params.0.write(writer)?;
 				key_derivation_params.1.write(writer)?;
-				revocation_pubkey.write(writer)?;
+				channel_value_satoshis.write(writer)?;
 			},
-			&SpendableOutputDescriptor::StaticOutputCounterpartyPayment { ref outpoint, ref output, ref key_derivation_params } => {
+			&SpendableOutputDescriptor::StaticOutputCounterpartyPayment { ref outpoint, ref output, ref key_derivation_params, channel_value_satoshis } => {
 				2u8.write(writer)?;
 				outpoint.write(writer)?;
 				output.write(writer)?;
 				key_derivation_params.0.write(writer)?;
 				key_derivation_params.1.write(writer)?;
+				channel_value_satoshis.write(writer)?;
 			},
 		}
 		Ok(())
@@ -164,13 +172,15 @@ impl Readable for SpendableOutputDescriptor {
 				per_commitment_point: Readable::read(reader)?,
 				to_self_delay: Readable::read(reader)?,
 				output: Readable::read(reader)?,
-				key_derivation_params: (Readable::read(reader)?, Readable::read(reader)?),
 				revocation_pubkey: Readable::read(reader)?,
+				key_derivation_params: (Readable::read(reader)?, Readable::read(reader)?),
+				channel_value_satoshis: Readable::read(reader)?,
 			}),
 			2u8 => Ok(SpendableOutputDescriptor::StaticOutputCounterpartyPayment {
 				outpoint: Readable::read(reader)?,
 				output: Readable::read(reader)?,
 				key_derivation_params: (Readable::read(reader)?, Readable::read(reader)?),
+				channel_value_satoshis: Readable::read(reader)?,
 			}),
 			_ => Err(DecodeError::InvalidValue),
 		}

lightning/src/ln/functional_tests.rs

@@ -4662,7 +4662,8 @@ macro_rules! check_spendable_outputs {
 					Event::SpendableOutputs { ref outputs } => {
 						for outp in outputs {
 							match *outp {
-								SpendableOutputDescriptor::StaticOutputCounterpartyPayment { ref outpoint, ref output, ref key_derivation_params } => {
+								SpendableOutputDescriptor::StaticOutputCounterpartyPayment { ref outpoint, ref output, ref key_derivation_params, channel_value_satoshis } => {
+									assert_eq!(channel_value_satoshis, $chan_value);
 									let input = TxIn {
 										previous_output: outpoint.into_bitcoin_outpoint(),
 										script_sig: Script::new(),
@@ -4691,7 +4692,8 @@ macro_rules! check_spendable_outputs {
 									spend_tx.input[0].witness.push(remotepubkey.serialize().to_vec());
 									txn.push(spend_tx);
 								},
-								SpendableOutputDescriptor::DynamicOutputP2WSH { ref outpoint, ref per_commitment_point, ref to_self_delay, ref output, ref key_derivation_params, ref revocation_pubkey } => {
+								SpendableOutputDescriptor::DynamicOutputP2WSH { ref outpoint, ref per_commitment_point, ref to_self_delay, ref output, ref revocation_pubkey, ref key_derivation_params, channel_value_satoshis  } => {
+									assert_eq!(channel_value_satoshis, $chan_value);
 									let input = TxIn {
 										previous_output: outpoint.into_bitcoin_outpoint(),
 										script_sig: Script::new(),