Expose the amount of funds available for claim in ChannelMonitor

In general, we should always allow users to query for how much is
currently in-flight being claimed on-chain at any time.

This does so by examining the confirmed claims on-chain and
breaking down what is left to be claimed into a new
`ClaimableBalance` enum.

Fixes lightningdevkit#995.

Author: TheBlueMatt

lightning/src/chain/channelmonitor.rs

@@ -521,6 +521,56 @@ impl_writeable_tlv_based_enum_upgradable!(ChannelMonitorUpdateStep,
 	},
 );
 
+/// Details about the balance available for claim once the channel appears on chain.
+#[derive(Clone, Debug, PartialEq, Eq)]
+#[cfg_attr(test, derive(PartialOrd, Ord))]
+pub enum ClaimableBalance {
+	/// The channel is not yet closed (or the initial commitment or closing transaction has not yet
+	/// been confirmed). The given balance is claimable (less on-chain fees) if the channel is
+	/// force-closed now.
+	ClaimableOnChannelClose {
+		/// The amount available to claim, in satoshis, ignoring the on-chain fees which will be
+		/// required to do so.
+		claimable_amount_satoshis: u64,
+	},
+	/// The channel has been closed, and the given balance is ours but awaiting confirmations until
+	/// we consider it spendable.
+	ClaimableAwaitingConfirmations {
+		/// The amount available to claim, in satoshis, possibly ignoring the on-chain fees which
+		/// were spent in broadcasting the transaction.
+		claimable_amount_satoshis: u64,
+		/// The height at which an [`Event::SpendableOutputs`] event will be generated for this
+		/// amount.
+		confirmation_height: u32,
+	},
+	/// The channel has been closed, and the given balance should be ours but awaiting spending
+	/// transaction confirmation. If the spending transaction does not confirm in time, it is
+	/// possible our counterparty can take the funds by broadcasting an HTLC timeout on-chain.
+	///
+	/// Once the spending transaction confirms, before it has reached enough confirmations to be
+	/// considered safe from chain reorganizations, the balance will instead be provided via
+	/// [`ClaimableBalance::ClaimableAwaitingConfirmations`].
+	ContentiousClaimable {
+		/// The amount available to claim, in satoshis, ignoring the on-chain fees which will be
+		/// required to do so.
+		claimable_amount_satoshis: u64,
+		/// The height at which the counterparty may be able to claim the balance if we have not
+		/// done so.
+		timeout_height: u32,
+	},
+	/// HTLCs which we sent to our counterparty which are claimable after a timeout (less on-chain
+	/// fees) if the counterparty does not know the preimage for the HTLCs. These are somewhat
+	/// likely to be claimed by our counterparty before we do.
+	PossiblyClaimableHTLCAwaitingTimeout {
+		/// The amount available to claim, in satoshis, ignoring the on-chain fees which will be
+		/// required to do so.
+		claimable_amount_satoshis: u64,
+		/// The height at which we will be able to claim the balance if our counterparty has not
+		/// done so.
+		claimable_height: u32,
+	},
+}
+
 /// An HTLC which has been irrevocably resolved on-chain, and has reached ANTI_REORG_DELAY.
 #[derive(PartialEq)]
 struct HTLCIrrevocablyResolved {
@@ -1287,6 +1337,107 @@ impl<Signer: Sign> ChannelMonitor<Signer> {
 	pub fn current_best_block(&self) -> BestBlock {
 		self.inner.lock().unwrap().best_block.clone()
 	}
+
+	/// Gets the balances in this channel which are either claimable by us if we were to
+	/// force-close the channel now or which are claimable on-chain or claims which are awaiting
+	/// confirmation.
+	///
+	/// Any balances in the channel which are available on-chain (ignoring on-chain fees) are
+	/// included here until an [`Event::SpendableOutputs`] event has been generated for the
+	/// balance, or until our counterparty has claimed the balance and accrued several
+	/// confirmations on the claim transaction.
+	///
+	/// See [`ClaimableBalance`] for additional details on the types of claimable balances which
+	/// may be returned here and their meanings.
+	pub fn get_claimable_balances(&self) -> Vec<ClaimableBalance> {
+		let mut res = Vec::new();
+		let us = self.inner.lock().unwrap();
+
+		let mut confirmed_txid = us.funding_spend_confirmed;
+		if let Some((txid, conf_thresh)) = us.onchain_events_awaiting_threshold_conf.iter().find_map(|event| {
+			if let OnchainEvent::FundingSpendConfirmation { txid, .. } = event.event {
+				Some((txid, event.confirmation_threshold()))
+			} else { None }
+		}) {
+			debug_assert!(us.funding_spend_confirmed.is_none(), "We have a pending funding spend awaiting confirmation, we can't have confirmed it already!");
+			confirmed_txid = Some(txid);
+			res.push(ClaimableBalance::ClaimableAwaitingConfirmations {
+				claimable_amount_satoshis: us.current_holder_commitment_tx.to_self_value_sat,
+				confirmation_height: conf_thresh,
+			});
+		}
+
+		macro_rules! walk_htlcs {
+			($holder_commitment: expr, $htlc_iter: expr) => {
+				for htlc in $htlc_iter {
+					if let Some(htlc_input_idx) = htlc.transaction_output_index {
+						if us.htlcs_resolved_on_chain.iter().any(|v| v.input_idx == htlc_input_idx) {
+								assert!(us.funding_spend_confirmed.is_some());
+						} else if htlc.offered == $holder_commitment {
+							res.push(ClaimableBalance::PossiblyClaimableHTLCAwaitingTimeout {
+								claimable_amount_satoshis: htlc.amount_msat / 1000,
+								claimable_height: htlc.cltv_expiry,
+							});
+						} else {
+							if us.payment_preimages.get(&htlc.payment_hash).is_some() {
+								if let Some(conf_thresh) = us.onchain_events_awaiting_threshold_conf.iter().find_map(|event| {
+									if let OnchainEvent::HTLCSpendConfirmation { input_idx, .. } = event.event {
+										if input_idx == htlc_input_idx { Some(event.confirmation_threshold()) } else { None }
+									} else { None }
+								}) {
+									res.push(ClaimableBalance::ClaimableAwaitingConfirmations {
+										claimable_amount_satoshis: htlc.amount_msat / 1000,
+										confirmation_height: conf_thresh,
+									});
+								} else {
+									res.push(ClaimableBalance::ContentiousClaimable {
+										claimable_amount_satoshis: htlc.amount_msat / 1000,
+										timeout_height: htlc.cltv_expiry,
+									});
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+
+		if let Some(txid) = confirmed_txid {
+			if Some(txid) == us.current_counterparty_commitment_txid || Some(txid) == us.prev_counterparty_commitment_txid {
+				walk_htlcs!(false, us.counterparty_claimable_outpoints.get(&txid).unwrap().iter().map(|(a, _)| a));
+			} else if txid == us.current_holder_commitment_tx.txid {
+				walk_htlcs!(true, us.current_holder_commitment_tx.htlc_outputs.iter().map(|(a, _, _)| a));
+			} else if let Some(prev_commitment) = &us.prev_holder_signed_commitment_tx {
+				if txid == prev_commitment.txid {
+					walk_htlcs!(true, prev_commitment.htlc_outputs.iter().map(|(a, _, _)| a));
+				}
+			}
+			// TODO: Add logic to provide claimable balances for counterparty broadcasting revoked
+			// outputs.
+			// Otherwise assume we closed with a cooperative close which only needs the
+			// `ClaimableAwaitingConfirmations` balance pushed first.
+		} else {
+			let mut claimable_inbound_htlc_value_sat = 0;
+			for (htlc, _, _) in us.current_holder_commitment_tx.htlc_outputs.iter() {
+				if htlc.transaction_output_index.is_none() { continue; }
+				if htlc.offered {
+					res.push(ClaimableBalance::PossiblyClaimableHTLCAwaitingTimeout {
+						claimable_amount_satoshis: htlc.amount_msat / 1000,
+						claimable_height: htlc.cltv_expiry,
+					});
+				} else {
+					if us.payment_preimages.get(&htlc.payment_hash).is_some() {
+						claimable_inbound_htlc_value_sat += htlc.amount_msat / 1000;
+					}
+				}
+			}
+			res.push(ClaimableBalance::ClaimableOnChannelClose {
+				claimable_amount_satoshis: us.current_holder_commitment_tx.to_self_value_sat + claimable_inbound_htlc_value_sat,
+			});
+		}
+
+		res
+	}
 }
 
 /// Compares a broadcasted commitment transaction's HTLCs with those in the latest state,