Introduce UtxoPool

UtxoPool is an interface to require utxos aiming to
use them as bumping input for CPFPs. Implementor must provide
an outpoint, its spending witness weight and the available
amount. It should be also ready to sign the CPFP.

A UTXO may be freed but this call isn't leveraged in the rest of
this patchset to prevent mempool rejection on the ground of BIP125.

Author: Antoine Riard

lightning/src/chain/mod.rs

@@ -12,3 +12,4 @@
 pub mod chaininterface;
 pub mod transaction;
 pub mod keysinterface;
+pub mod utxointerface;

lightning/src/chain/utxointerface.rs

@@ -0,0 +1,24 @@
+//! Trait which allow others parts of rust-lightning to manage CPFP candidates
+//! utxos for increasing feerate of time-sensitive transactions.
+
+
+use bitcoin::blockdata::transaction::OutPoint as BitcoinOutPoint;
+use bitcoin::blockdata::transaction::Transaction;
+
+use ln::onchain_utils::BumpingOutput;
+
+/// A trait which sould be implemented to provide fresh CPFP utxo for onchain
+/// transactions.
+///
+/// Implementation MUST provision and bookmarked utxo correctly to ensure LN
+/// channel security in case of adversarial counterparty or unfavorable mempool
+/// congestion.
+//TODO: document better
+pub trait UtxoPool: Sync + Send {
+	/// Allocate a utxo to cover fee required to confirm a pending onchain transaction.
+	fn allocate_utxo(&self, required_fee: u64) -> Option<(BitcoinOutPoint, BumpingOutput)>;
+	/// Free a utxo. Call in case of reorg or counterparty claiming the output first.
+	fn free_utxo(&self, free_utxo: BitcoinOutPoint);
+	/// Provide a witness for the bumping utxo
+	fn provide_utxo_witness(&self, cpfp_transaction: &Transaction, utxo_index: u32) -> Result<Vec<Vec<u8>>, ()>;
+}

lightning/src/ln/mod.rs

@@ -21,6 +21,7 @@
 pub mod channelmanager;
 pub mod channelmonitor;
 pub mod msgs;
+pub mod onchain_utils;
 pub mod peer_handler;
 pub mod chan_utils;
 pub mod features;
@@ -32,7 +33,6 @@ pub mod peer_channel_encryptor;
 pub(crate) mod peer_channel_encryptor;
 
 mod channel;
-mod onchain_utils;
 mod onion_utils;
 mod wire;
 

lightning/src/ln/onchain_utils.rs

@@ -253,6 +253,40 @@ impl Readable for HolderFundingOutput {
 	}
 }
 
+/// A struct to describe a bumping output with the amount and witness weight. It is used by
+/// OnchainTxHandler to build a CPFP transaction to drag a local commitment transaction.
+#[derive(Clone, PartialEq)]
+pub struct BumpingOutput {
+	amount: u64,
+	witness_weight: u64,
+}
+
+impl BumpingOutput {
+	pub(crate) fn new(amount: u64, witness_weight: u64) -> Self {
+		BumpingOutput {
+			amount,
+			witness_weight,
+		}
+	}
+}
+
+impl Writeable for BumpingOutput {
+	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), ::std::io::Error> {
+		self.amount.write(writer)?;
+		self.witness_weight.write(writer)?;
+		Ok(())
+	}
+}
+
+impl Readable for BumpingOutput {
+	fn read<R: ::std::io::Read>(reader: &mut R) -> Result<Self, DecodeError> {
+		Ok(BumpingOutput {
+			amount: Readable::read(reader)?,
+			witness_weight: Readable::read(reader)?,
+		})
+	}
+}
+
 /// An enum to describe a claim content which is generated by ChannelMonitor and
 /// used by OnchainTxHandler to regenerate feerate-bump transactions to settle claims.
 ///