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(),
-						channel_keys_id: self.channel_keys_id,
 						revocation_pubkey: broadcasted_holder_revokable_script.2.clone(),
+						channel_keys_id: self.channel_keys_id,
+						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(),
 					channel_keys_id: self.channel_keys_id,
+					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 secret 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.
-		channel_keys_id: [u8; 32],
 		/// The revocation_pubkey used to derive witnessScript
-		revocation_pubkey: PublicKey
+		revocation_pubkey: PublicKey,
+		/// Arbitrary identification information returned by a call to
+		/// `ChannelKeys::channel_keys_id()`. This may be useful in re-deriving keys used in
+		/// the channel to spend the output.
+		channel_keys_id: [u8; 32],
+		/// The value of the channel which this output originated from, possibly indirectly.
+		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::channel_keys_id()`. This may be useful in re-deriving keys used in
+		/// the channel to spend the output.
 		channel_keys_id: [u8; 32],
+		/// The value of the channel which this transactions spends.
+		channel_value_satoshis: u64,
 	}
 }
 
@@ -130,20 +136,22 @@ 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 channel_keys_id, ref revocation_pubkey } => {
+			&SpendableOutputDescriptor::DynamicOutputP2WSH { ref outpoint, ref per_commitment_point, ref to_self_delay, ref output, ref revocation_pubkey, ref channel_keys_id, channel_value_satoshis } => {
 				1u8.write(writer)?;
 				outpoint.write(writer)?;
 				per_commitment_point.write(writer)?;
 				to_self_delay.write(writer)?;
 				output.write(writer)?;
-				channel_keys_id.write(writer)?;
 				revocation_pubkey.write(writer)?;
+				channel_keys_id.write(writer)?;
+				channel_value_satoshis.write(writer)?;
 			},
-			&SpendableOutputDescriptor::StaticOutputCounterpartyPayment { ref outpoint, ref output, ref channel_keys_id } => {
+			&SpendableOutputDescriptor::StaticOutputCounterpartyPayment { ref outpoint, ref output, ref channel_keys_id, channel_value_satoshis } => {
 				2u8.write(writer)?;
 				outpoint.write(writer)?;
 				output.write(writer)?;
 				channel_keys_id.write(writer)?;
+				channel_value_satoshis.write(writer)?;
 			},
 		}
 		Ok(())
@@ -162,13 +170,15 @@ impl Readable for SpendableOutputDescriptor {
 				per_commitment_point: Readable::read(reader)?,
 				to_self_delay: Readable::read(reader)?,
 				output: Readable::read(reader)?,
-				channel_keys_id: Readable::read(reader)?,
 				revocation_pubkey: Readable::read(reader)?,
+				channel_keys_id: Readable::read(reader)?,
+				channel_value_satoshis: Readable::read(reader)?,
 			}),
 			2u8 => Ok(SpendableOutputDescriptor::StaticOutputCounterpartyPayment {
 				outpoint: Readable::read(reader)?,
 				output: Readable::read(reader)?,
 				channel_keys_id: 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 channel_keys_id } => {
+								SpendableOutputDescriptor::StaticOutputCounterpartyPayment { ref outpoint, ref output, ref channel_keys_id, 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 channel_keys_id, ref revocation_pubkey } => {
+								SpendableOutputDescriptor::DynamicOutputP2WSH { ref outpoint, ref per_commitment_point, ref to_self_delay, ref output, ref revocation_pubkey, ref channel_keys_id, channel_value_satoshis  } => {
+									assert_eq!(channel_value_satoshis, $chan_value);
 									let input = TxIn {
 										previous_output: outpoint.into_bitcoin_outpoint(),
 										script_sig: Script::new(),
@@ -7484,7 +7486,7 @@ fn test_data_loss_protect() {
 	let header = BlockHeader { version: 0x20000000, prev_blockhash: Default::default(), merkle_root: Default::default(), time: 42, bits: 42, nonce: 42};
 	connect_block(&nodes[0], &Block { header, txdata: vec![node_txn[0].clone()]}, 0);
 	connect_blocks(&nodes[0], ANTI_REORG_DELAY - 1, 0, true, header.block_hash());
-	let spend_txn = check_spendable_outputs!(nodes[0], 1, node_cfgs[0].keys_manager, 100000);
+	let spend_txn = check_spendable_outputs!(nodes[0], 1, node_cfgs[0].keys_manager, 1000000);
 	assert_eq!(spend_txn.len(), 1);
 	check_spends!(spend_txn[0], node_txn[0]);
 }