-f Add documentation in onchain_utils

Author: Antoine Riard

lightning/src/chain/onchain_utils.rs

@@ -1,4 +1,15 @@
-//! Utilities for computing witnesses weight and feerate computation for onchain operation
+// This file is Copyright its original authors, visible in version control
+// history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
+// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
+// You may not use this file except in accordance with one or both of these
+// licenses.
+
+//! Various utilities to assemble claimable outpoints in package of one or more transactions. Those
+//! packages are attached metadatas, guiding their aggregation or fee-bumping re-schedule. This file
+//! also includes witness weight computation and fee computation methods.
 
 use bitcoin::blockdata::transaction::{TxOut,TxIn, Transaction, SigHashType};
 use bitcoin::blockdata::transaction::OutPoint as BitcoinOutPoint;
@@ -24,6 +35,8 @@ use std::ops::Deref;
 
 const MAX_ALLOC_SIZE: usize = 64*1024;
 
+
+/// witnessScript markers used to compute the expected witness weight.
 #[derive(PartialEq, Clone, Copy)]
 pub(crate) enum InputDescriptors {
 	RevokedOfferedHTLC,
@@ -80,6 +93,8 @@ impl Readable for InputDescriptors {
 	}
 }
 
+/// Sum up witnesses weight of a set of given inputs. Inputs might belong to differing descriptors.
+/// Weights should be compliant with BOLT 3 Appendix A.
 pub(crate) fn get_witnesses_weight(inputs: &[InputDescriptors]) -> usize {
 	let mut tx_weight = 2; // count segwit flags
 	for inp in inputs {
@@ -110,9 +125,16 @@ pub(crate) fn get_witnesses_weight(inputs: &[InputDescriptors]) -> usize {
 	tx_weight
 }
 
-/// A struct to describe a revoked output, the templated witnessScript variables to claim it
-/// (hash, timelock, pubkeys) and per_commitment_key to generate a solving witness. It is used by
-/// OnchainTxHandler to generate a valid transaction claiming this output.
+/// A struct to describe a revoked output and corresponding informations to generate a solving
+/// witness.
+///
+/// If the revoked output is a HTLC output on a committment transaction, HTLCOuputInCommitment (hash
+/// timelock, direction), pubkeys are used to generate the suiting witnessScript.
+///
+/// Otherwise, CSV is used to generate a witnessScript redeeming a balance output on a commitment
+/// transaction or second-stage HTLC transaction.
+///
+/// Amount and revocation secret are used in both cases.
 #[derive(Clone, PartialEq)]
 pub(crate) struct RevokedOutput {
 	per_commitment_point: PublicKey,
@@ -177,9 +199,12 @@ impl Readable for RevokedOutput {
 	}
 }
 
-/// A struct to describe a counterparty htlc output, the templated witnessScript variables to claim it (hash,
-/// timelock, pubkeys) and preimage to generate a solving witness. It is used by OnchainTxHandler
-/// to generate a valid transaction claiming this output.
+/// A struct to describe a HTLC output on a counterparty commitment transaction.
+///
+/// HTLCOutputInCommitment (hash, timelock, directon) and pubkeys are used to generate the suiting
+/// witnessScript.
+///
+/// If the HTLC is offered to holder, the preimae is used as part of the witness.
 #[derive(Clone, PartialEq)]
 pub(crate) struct CounterpartyHTLCOutput {
 	per_commitment_point: PublicKey,
@@ -229,9 +254,10 @@ impl Readable for CounterpartyHTLCOutput {
 	}
 }
 
-/// A struct to describe a holder htlc output, amount and preimage to generate a signature and
-/// solving witness. It is used by OnchainTxHandler to finalize a HTLC transaction claiming this
-/// output.
+/// A struct to describe a HTLC output on holder commitment transaction.
+///
+/// Either offered or received, the amount is always used as part of the bip143 sighash.
+/// Preimage is only included as part of the witness in former case.
 #[derive(Clone, PartialEq)]
 pub(crate) struct HolderHTLCOutput {
 	preimage: Option<PaymentPreimage>,
@@ -266,8 +292,9 @@ impl Readable for HolderHTLCOutput {
 	}
 }
 
-/// A struct to describe a holder funding output with the static witnessScript to claim it. It is
-/// used by OnchainTxHandler to finalize a holder commitment transaction claiming this output.
+/// A struct to describe the channel output on the funding transaction.
+///
+/// witnessScript is used as part of the witness redeeming the funding utxo.
 #[derive(Clone, PartialEq)]
 pub(crate) struct HolderFundingOutput {
 	funding_redeemscript: Script,
@@ -296,6 +323,10 @@ impl Readable for HolderFundingOutput {
 	}
 }
 
+/// A wrapper encapsulating all in-protocol differing outputs categories.
+///
+/// The generic API offers access to outputs attributes (amount, weight, category) or allow
+/// transformation such as finalizing an input claiming the output.
 #[derive(Clone, PartialEq)]
 pub(crate) enum PackageSolvingData {
 	RevokedOutput(RevokedOutput),
@@ -431,6 +462,9 @@ impl Readable for PackageSolvingData {
 	}
 }
 
+/// A malleable package might be aggregated with other packages to save on fees.
+/// A untractable package has been counter-signed and aggregation will break cached counterparty
+/// signatures.
 #[derive(Clone, PartialEq)]
 pub(crate) enum PackageMalleability {
 	Malleable,
@@ -467,48 +501,47 @@ impl Readable for PackageMalleability {
 	}
 }
 
-/// An enum to describe a claim content which is generated by ChannelMonitor and
-/// used by OnchainTxHandler to regenerate feerate-bump transactions to settle claims.
+/// A structure to describe a package content which is generated by ChannelMonitor and
+/// used by OnchainTxHandler to generate and broadcast transactions settling onchain claims.
 ///
-/// Template may be either malleable (a justice tx, a counterparty HTLC tx) or lockdown (a holder htlc
-/// tx, a holder commitment tx, a pre-signed justice tx). Bumping can be a Replace-by-Fee, that way
-/// the claim-settlement tx in itself has its feerate increased or Child-Pay-For-Parent, a child
-/// of the claim tx has its feerate increased. For the latter case, access to the whole package
-/// sizea and pre-committed fee is required to compute an efficient bump.
+/// A package is defined as one or more transactions claiming onchain outputs in reaction
+/// to confirmation of a channel transaction. Those packages might be aggregated to save on
+/// fees, if satisfaction of outputs's witnessScript let's us do so.
 ///
-/// Metadata are related to multiple fields playing a role in package lifetime.
-/// Once issued, it may be aggregated with other package if it's judged safe
-/// and feerate opportunistic.
-/// Current LN fees model, pre-committed fees with update_fee adjustement, means
-/// that counter-signed transactions must be CPFP to be dynamically confirmed as a
-/// bumping strategy. If transactions aren't lockdown (i.e justice transactions) we
-/// may RBF them.
-/// Feerate previous will serve as a feerate floor between different bumping attempts.
-/// Height timer clocks these different bumping attempts.
-/// Absolute timelock defines the block barrier at which claiming isn't exclusive
-/// to us anymore and thus we MUST have get it solved before.
-/// Height original serves as a packet timestamps to prune out claim in case of reorg.
-/// Content embeds transactions elements to generate transaction. See PackageTemplate.
+/// As packages are time-sensitive, we fee-bump and rebroadcast them at scheduled intervals.
+/// Failing to confirm a package translate as a loss of funds for the user.
 #[derive(Clone, PartialEq)]
 pub(crate) struct PackageTemplate {
+	// List of onchain outputs and solving data to generate satisfying witnesses.
 	inputs: Vec<(BitcoinOutPoint, PackageSolvingData)>,
+	// Packages are deemed as malleable if we have local knwoledge of at least one set of
+	// private keys yelling a satisfying witnesses. Malleability implies that we can aggregate
+	// packages among them to save on fees or rely on RBF to bump their feerates.
+	// Untractable packages have been counter-signed and thus imply that we can't aggregate
+	// them without breaking signatures. Fee-bumping strategy will also rely on CPFP.
 	malleability: PackageMalleability,
-	// Block height before which claiming is exclusive to one party,
-	// after reaching it, claiming may be contentious.
+	// Block height after which the soonest-output belonging to this package is mature for a
+	// competing claim by the counterparty. As our chain tip becomes nearer from the timelock,
+	// the fee-bumping frequency will increase. See `OnchainTxHandler::get_height_timer`.
 	absolute_timelock: u32,
-	// Timeout tx must have nLocktime set which means aggregating multiple
-	// ones must take the higher nLocktime among them to satisfy all of them.
-	// Sadly it has few pitfalls, a) it takes longuer to get fund back b) CLTV_DELTA
-	// of a sooner-HTLC could be swallowed by the highest nLocktime of the HTLC set.
-	// To simplify we mark them as non-aggregable.
+	// Timelocked outputs belonging to the same transaction might have differing
+	// satisfying heights. Picking up the highest height among the output set would be a valid
+	// aggregation strategy but it comes with at least 2 trade-offs :
+	// * soonest-output fund are going to take longer to come back
+	// * CLTV delta backing up a corresponding HTLC on an upstream channel could be swallowed
+	// by the requirement of the highest-output part of the set
+	// For now, we mark such timelocked outputs as non-aggregable, though we might introduce
+	// smarter aggregation strategy in the future.
 	aggregation: bool,
-	// Based feerate of previous broadcast. If resources available (either
-	// output value or utxo bumping).
+	// Cache of package feerate committed at previous (re)broadcast. If bumping resources
+	// (either claimed output value or external utxo), it will keep increasing until holder
+	// or counterparty successful claim.
 	feerate_previous: u64,
-	// At every block tick, used to check if pending claiming tx is taking too
-	// much time for confirmation and we need to bump it.
+	// Cache of next height at which fee-bumping and rebroadcast will be attempted. In
+	// the future, we might abstract it to an observed mempool fluctuation.
 	height_timer: Option<u32>,
-	// Tracked in case of reorg to wipe out now-superflous request.
+	// Confirmation height of the claimed outputs set transaction. In case of reorg reaching
+	// it, we wipe out and forget the package.
 	height_original: u32,
 }
 
@@ -735,6 +768,10 @@ impl Readable for PackageTemplate {
 	}
 }
 
+/// Attempt to propose a fee based on consumed outpoints's values and predicted weight of the claiming
+/// transaction. We start with the highest priority feerate returned by the node's fee estimator
+/// then fall-back to lower priorities until we have enough value available to suck from.
+/// If the proposed fee is more than the claimable balance, we return None
 fn subtract_high_prio_fee<F: Deref, L: Deref>(input_amounts: u64, predicted_weight: usize, fee_estimator: &F, logger: &L) -> Option<(u64, u64)>
 	where F::Target: FeeEstimator,
 	      L::Target: Logger,
@@ -766,6 +803,12 @@ fn subtract_high_prio_fee<F: Deref, L: Deref>(input_amounts: u64, predicted_weig
 	}
 }
 
+/// Attempt to propose a bumping fee based on consumed outpoint's value and predicted weight of the
+/// claiming transaction. If feerates proposed by the fee-estimator have been increasing since last
+/// fee-bumping attempt, use them. Otherwise, blindly bump the feerate by 25% of the previous
+/// feerate.
+/// We also verify that those bumping heuristics respect BIP125 rules 3) and 4) and if required
+/// adjust the new fee to meet the RBF policy requirement.
 fn feerate_bump<F: Deref, L: Deref>(predicted_weight: usize, input_amounts: u64, previous_feerate: u64, fee_estimator: &F, logger: &L) -> Option<(u64, u64)>
 	where F::Target: FeeEstimator,
 	      L::Target: Logger,
@@ -801,6 +844,9 @@ fn feerate_bump<F: Deref, L: Deref>(predicted_weight: usize, input_amounts: u64,
 	Some((new_fee, new_fee * 1000 / (predicted_weight as u64)))
 }
 
+/// Deduce a new proposed fee from the claiming transaction output value.
+/// If the new proposed fee is superior to the consumed outpoint's value, burn everything in miner's
+/// fee to deter counterparties attacker.
 pub(crate) fn compute_output_value<F: Deref, L: Deref>(predicted_weight: usize, input_amounts: u64, previous_feerate: u64, fee_estimator: &F, logger: &L) -> Option<(u64, u64)>
 	where F::Target: FeeEstimator,
 	      L::Target: Logger,