Clean up docs on public chan_utils methods to be more useful

[rust-lightning] / lightning / src / ln / chan_utils.rs

diff --git a/lightning/src/ln/chan_utils.rs b/lightning/src/ln/chan_utils.rs
index 81b0df09607250d2a4a6c5c634c6d9fe2094a3e8..9f98cd03b28af31ec86b58f154bf582942ccf849 100644 (file)
--- a/lightning/src/ln/chan_utils.rs
+++ b/lightning/src/ln/chan_utils.rs
@@ -22,7 +22,7 @@ use bitcoin::hash_types::{Txid, PubkeyHash};
 
 use ln::{PaymentHash, PaymentPreimage};
 use ln::msgs::DecodeError;
-use util::ser::{Readable, Writeable, Writer, MAX_BUF_SIZE};
+use util::ser::{Readable, Writeable, Writer};
 use util::byte_utils;
 
 use bitcoin::hash_types::WPubkeyHash;
@@ -36,18 +36,11 @@ use core::cmp;
 use ln::chan_utils;
 use util::transaction_utils::sort_outputs;
 use ln::channel::INITIAL_COMMITMENT_NUMBER;
-use std::io::Read;
 use core::ops::Deref;
 use chain;
 
-// Maximum size of a serialized HTLCOutputInCommitment
-pub(crate) const HTLC_OUTPUT_IN_COMMITMENT_SIZE: usize = 1 + 8 + 4 + 32 + 5;
-
 pub(crate) const MAX_HTLCS: u16 = 483;
 
-// This checks that the buffer size is greater than the maximum possible size for serialized HTLCS
-const _EXCESS_BUFFER_SIZE: usize = MAX_BUF_SIZE - MAX_HTLCS as usize * HTLC_OUTPUT_IN_COMMITMENT_SIZE;
-
 pub(super) const HTLC_SUCCESS_TX_WEIGHT: u64 = 703;
 pub(super) const HTLC_TIMEOUT_TX_WEIGHT: u64 = 663;
 
@@ -532,12 +525,18 @@ pub fn make_funding_redeemscript(broadcaster: &PublicKey, countersignatory: &Pub
        }.push_opcode(opcodes::all::OP_PUSHNUM_2).push_opcode(opcodes::all::OP_CHECKMULTISIG).into_script()
 }
 
-/// panics if htlc.transaction_output_index.is_none()!
-pub fn build_htlc_transaction(prev_hash: &Txid, feerate_per_kw: u32, contest_delay: u16, htlc: &HTLCOutputInCommitment, broadcaster_delayed_payment_key: &PublicKey, revocation_key: &PublicKey) -> Transaction {
+/// Builds an unsigned HTLC-Success or HTLC-Timeout transaction from the given channel and HTLC
+/// parameters. This is used by [`TrustedCommitmentTransaction::get_htlc_sigs`] to fetch the
+/// transaction which needs signing, and can be used to construct an HTLC transaction which is
+/// broadcastable given a counterparty HTLC signature.
+///
+/// Panics if htlc.transaction_output_index.is_none() (as such HTLCs do not appear in the
+/// commitment transaction).
+pub fn build_htlc_transaction(commitment_txid: &Txid, feerate_per_kw: u32, contest_delay: u16, htlc: &HTLCOutputInCommitment, broadcaster_delayed_payment_key: &PublicKey, revocation_key: &PublicKey) -> Transaction {
        let mut txins: Vec<TxIn> = Vec::new();
        txins.push(TxIn {
                previous_output: OutPoint {
-                       txid: prev_hash.clone(),
+                       txid: commitment_txid.clone(),
                        vout: htlc.transaction_output_index.expect("Can't build an HTLC transaction for a dust output"),
                },
                script_sig: Script::new(),
@@ -866,44 +865,16 @@ impl PartialEq for CommitmentTransaction {
        }
 }
 
-/// (C-not exported) as users never need to call this directly
-impl Writeable for Vec<HTLCOutputInCommitment> {
-       #[inline]
-       fn write<W: Writer>(&self, w: &mut W) -> Result<(), ::std::io::Error> {
-               (self.len() as u16).write(w)?;
-               for e in self.iter() {
-                       e.write(w)?;
-               }
-               Ok(())
-       }
-}
-
-/// (C-not exported) as users never need to call this directly
-impl Readable for Vec<HTLCOutputInCommitment> {
-       #[inline]
-       fn read<R: Read>(r: &mut R) -> Result<Self, DecodeError> {
-               let len: u16 = Readable::read(r)?;
-               let byte_size = (len as usize)
-                       .checked_mul(HTLC_OUTPUT_IN_COMMITMENT_SIZE)
-                       .ok_or(DecodeError::BadLengthDescriptor)?;
-               if byte_size > MAX_BUF_SIZE {
-                       return Err(DecodeError::BadLengthDescriptor);
-               }
-               let mut ret = Vec::with_capacity(len as usize);
-               for _ in 0..len { ret.push(HTLCOutputInCommitment::read(r)?); }
-               Ok(ret)
-       }
-}
-
 impl_writeable_tlv_based!(CommitmentTransaction, {
        (0, commitment_number),
        (2, to_broadcaster_value_sat),
        (4, to_countersignatory_value_sat),
        (6, feerate_per_kw),
-       (8, htlcs),
-       (10, keys),
-       (12, built),
-}, {}, {});
+       (8, keys),
+       (10, built),
+}, {}, {
+       (12, htlcs),
+});
 
 impl CommitmentTransaction {
        /// Construct an object of the class while assigning transaction output indices to HTLCs.
@@ -1212,7 +1183,12 @@ impl<'a> TrustedCommitmentTransaction<'a> {
        }
 }
 
-/// Get the transaction number obscure factor
+/// Commitment transaction numbers which appear in the transactions themselves are XOR'd with a
+/// shared secret first. This prevents on-chain observers from discovering how many commitment
+/// transactions occurred in a channel before it was closed.
+///
+/// This function gets the shared secret from relevant channel public keys and can be used to
+/// "decrypt" the commitment transaction number given a commitment transaction on-chain.
 pub fn get_commitment_transaction_number_obscure_factor(
        broadcaster_payment_basepoint: &PublicKey,
        countersignatory_payment_basepoint: &PublicKey,