+ /// Used by ChannelManager deserialization to broadcast the latest holder state if its copy of
+ /// the Channel was out-of-date. You may use it to get a broadcastable holder toxic tx in case of
+ /// fallen-behind, i.e when receiving a channel_reestablish with a proof that our counterparty side knows
+ /// a higher revocation secret than the holder commitment number we are aware of. Broadcasting these
+ /// transactions are UNSAFE, as they allow counterparty side to punish you. Nevertheless you may want to
+ /// broadcast them if counterparty don't close channel with his higher commitment transaction after a
+ /// substantial amount of time (a month or even a year) to get back funds. Best may be to contact
+ /// out-of-band the other node operator to coordinate with him if option is available to you.
+ /// In any-case, choice is up to the user.
+ pub fn get_latest_holder_commitment_txn<L: Deref>(&self, logger: &L) -> Vec<Transaction>
+ where L::Target: Logger {
+ self.inner.lock().unwrap().get_latest_holder_commitment_txn(logger)
+ }
+
+ /// Unsafe test-only version of get_latest_holder_commitment_txn used by our test framework
+ /// to bypass HolderCommitmentTransaction state update lockdown after signature and generate
+ /// revoked commitment transaction.
+ #[cfg(any(test, feature = "unsafe_revoked_tx_signing"))]
+ pub fn unsafe_get_latest_holder_commitment_txn<L: Deref>(&self, logger: &L) -> Vec<Transaction>
+ where L::Target: Logger {
+ self.inner.lock().unwrap().unsafe_get_latest_holder_commitment_txn(logger)
+ }
+
+ /// Processes transactions in a newly connected block, which may result in any of the following:
+ /// - update the monitor's state against resolved HTLCs
+ /// - punish the counterparty in the case of seeing a revoked commitment transaction
+ /// - force close the channel and claim/timeout incoming/outgoing HTLCs if near expiration
+ /// - detect settled outputs for later spending
+ /// - schedule and bump any in-flight claims
+ ///
+ /// Returns any new outputs to watch from `txdata`; after called, these are also included in
+ /// [`get_outputs_to_watch`].
+ ///
+ /// [`get_outputs_to_watch`]: #method.get_outputs_to_watch
+ pub fn block_connected<B: Deref, F: Deref, L: Deref>(
+ &self,
+ header: &BlockHeader,
+ txdata: &TransactionData,
+ height: u32,
+ broadcaster: B,
+ fee_estimator: F,
+ logger: L,
+ ) -> Vec<TransactionOutputs>
+ where
+ B::Target: BroadcasterInterface,
+ F::Target: FeeEstimator,
+ L::Target: Logger,
+ {
+ self.inner.lock().unwrap().block_connected(
+ header, txdata, height, broadcaster, fee_estimator, logger)
+ }
+
+ /// Determines if the disconnected block contained any transactions of interest and updates
+ /// appropriately.
+ pub fn block_disconnected<B: Deref, F: Deref, L: Deref>(
+ &self,
+ header: &BlockHeader,
+ height: u32,
+ broadcaster: B,
+ fee_estimator: F,
+ logger: L,
+ ) where
+ B::Target: BroadcasterInterface,
+ F::Target: FeeEstimator,
+ L::Target: Logger,
+ {
+ self.inner.lock().unwrap().block_disconnected(
+ header, height, broadcaster, fee_estimator, logger)
+ }
+
+ /// Processes transactions confirmed in a block with the given header and height, returning new
+ /// outputs to watch. See [`block_connected`] for details.
+ ///
+ /// Used instead of [`block_connected`] by clients that are notified of transactions rather than
+ /// blocks. See [`chain::Confirm`] for calling expectations.
+ ///
+ /// [`block_connected`]: Self::block_connected
+ pub fn transactions_confirmed<B: Deref, F: Deref, L: Deref>(
+ &self,
+ header: &BlockHeader,
+ txdata: &TransactionData,
+ height: u32,
+ broadcaster: B,
+ fee_estimator: F,
+ logger: L,
+ ) -> Vec<TransactionOutputs>
+ where
+ B::Target: BroadcasterInterface,
+ F::Target: FeeEstimator,
+ L::Target: Logger,
+ {
+ self.inner.lock().unwrap().transactions_confirmed(
+ header, txdata, height, broadcaster, fee_estimator, logger)
+ }
+
+ /// Processes a transaction that was reorganized out of the chain.
+ ///
+ /// Used instead of [`block_disconnected`] by clients that are notified of transactions rather
+ /// than blocks. See [`chain::Confirm`] for calling expectations.
+ ///
+ /// [`block_disconnected`]: Self::block_disconnected
+ pub fn transaction_unconfirmed<B: Deref, F: Deref, L: Deref>(
+ &self,
+ txid: &Txid,
+ broadcaster: B,
+ fee_estimator: F,
+ logger: L,
+ ) where
+ B::Target: BroadcasterInterface,
+ F::Target: FeeEstimator,
+ L::Target: Logger,
+ {
+ self.inner.lock().unwrap().transaction_unconfirmed(
+ txid, broadcaster, fee_estimator, logger);
+ }
+
+ /// Updates the monitor with the current best chain tip, returning new outputs to watch. See
+ /// [`block_connected`] for details.
+ ///
+ /// Used instead of [`block_connected`] by clients that are notified of transactions rather than
+ /// blocks. See [`chain::Confirm`] for calling expectations.
+ ///
+ /// [`block_connected`]: Self::block_connected
+ pub fn best_block_updated<B: Deref, F: Deref, L: Deref>(
+ &self,
+ header: &BlockHeader,
+ height: u32,
+ broadcaster: B,
+ fee_estimator: F,
+ logger: L,
+ ) -> Vec<TransactionOutputs>
+ where
+ B::Target: BroadcasterInterface,
+ F::Target: FeeEstimator,
+ L::Target: Logger,
+ {
+ self.inner.lock().unwrap().best_block_updated(
+ header, height, broadcaster, fee_estimator, logger)
+ }
+
+ /// Returns the set of txids that should be monitored for re-organization out of the chain.
+ pub fn get_relevant_txids(&self) -> Vec<Txid> {
+ let inner = self.inner.lock().unwrap();
+ let mut txids: Vec<Txid> = inner.onchain_events_awaiting_threshold_conf
+ .iter()
+ .map(|entry| entry.txid)
+ .chain(inner.onchain_tx_handler.get_relevant_txids().into_iter())
+ .collect();
+ txids.sort_unstable();
+ txids.dedup();
+ txids
+ }
+
+ /// Gets the latest best block which was connected either via the [`chain::Listen`] or
+ /// [`chain::Confirm`] interfaces.
+ 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 (possibly awaiting
+ /// confirmation).
+ ///
+ /// Any balances in the channel which are available on-chain (excluding 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.
+ ///
+ /// Note that the balances available when you or your counterparty have broadcasted revoked
+ /// state(s) may not be fully captured here.
+ // TODO, fix that ^
+ ///
+ /// See [`Balance`] for additional details on the types of claimable balances which
+ /// may be returned here and their meanings.
+ pub fn get_claimable_balances(&self) -> Vec<Balance> {
+ let mut res = Vec::new();
+ let us = self.inner.lock().unwrap();
+
+ let mut confirmed_txid = us.funding_spend_confirmed;
+ let mut pending_commitment_tx_conf_thresh = None;
+ let funding_spend_pending = us.onchain_events_awaiting_threshold_conf.iter().find_map(|event| {
+ if let OnchainEvent::FundingSpendConfirmation { .. } = event.event {
+ Some((event.txid, event.confirmation_threshold()))
+ } else { None }
+ });
+ if let Some((txid, conf_thresh)) = funding_spend_pending {
+ debug_assert!(us.funding_spend_confirmed.is_none(),
+ "We have a pending funding spend awaiting anti-reorg confirmation, we can't have confirmed it already!");
+ confirmed_txid = Some(txid);
+ pending_commitment_tx_conf_thresh = Some(conf_thresh);
+ }
+
+ macro_rules! walk_htlcs {
+ ($holder_commitment: expr, $htlc_iter: expr) => {
+ for htlc in $htlc_iter {
+ if let Some(htlc_commitment_tx_output_idx) = htlc.transaction_output_index {
+ if let Some(conf_thresh) = us.onchain_events_awaiting_threshold_conf.iter().find_map(|event| {
+ if let OnchainEvent::MaturingOutput { descriptor: SpendableOutputDescriptor::DelayedPaymentOutput(descriptor) } = &event.event {
+ if descriptor.outpoint.index as u32 == htlc_commitment_tx_output_idx { Some(event.confirmation_threshold()) } else { None }
+ } else { None }
+ }) {
+ debug_assert!($holder_commitment);
+ res.push(Balance::ClaimableAwaitingConfirmations {
+ claimable_amount_satoshis: htlc.amount_msat / 1000,
+ confirmation_height: conf_thresh,
+ });
+ } else if us.htlcs_resolved_on_chain.iter().any(|v| v.commitment_tx_output_idx == htlc_commitment_tx_output_idx) {
+ // Funding transaction spends should be fully confirmed by the time any
+ // HTLC transactions are resolved, unless we're talking about a holder
+ // commitment tx, whose resolution is delayed until the CSV timeout is
+ // reached, even though HTLCs may be resolved after only
+ // ANTI_REORG_DELAY confirmations.
+ debug_assert!($holder_commitment || us.funding_spend_confirmed.is_some());
+ } else if htlc.offered == $holder_commitment {
+ // If the payment was outbound, check if there's an HTLCUpdate
+ // indicating we have spent this HTLC with a timeout, claiming it back
+ // and awaiting confirmations on it.
+ let htlc_update_pending = us.onchain_events_awaiting_threshold_conf.iter().find_map(|event| {
+ if let OnchainEvent::HTLCUpdate { commitment_tx_output_idx: Some(commitment_tx_output_idx), .. } = event.event {
+ if commitment_tx_output_idx == htlc_commitment_tx_output_idx {
+ Some(event.confirmation_threshold()) } else { None }
+ } else { None }
+ });
+ if let Some(conf_thresh) = htlc_update_pending {
+ res.push(Balance::ClaimableAwaitingConfirmations {
+ claimable_amount_satoshis: htlc.amount_msat / 1000,
+ confirmation_height: conf_thresh,
+ });
+ } else {
+ res.push(Balance::MaybeClaimableHTLCAwaitingTimeout {
+ claimable_amount_satoshis: htlc.amount_msat / 1000,
+ claimable_height: htlc.cltv_expiry,
+ });
+ }
+ } else if us.payment_preimages.get(&htlc.payment_hash).is_some() {
+ // Otherwise (the payment was inbound), only expose it as claimable if
+ // we know the preimage.
+ // Note that if there is a pending claim, but it did not use the
+ // preimage, we lost funds to our counterparty! We will then continue
+ // to show it as ContentiousClaimable until ANTI_REORG_DELAY.
+ let htlc_spend_pending = us.onchain_events_awaiting_threshold_conf.iter().find_map(|event| {
+ if let OnchainEvent::HTLCSpendConfirmation { commitment_tx_output_idx, preimage, .. } = event.event {
+ if commitment_tx_output_idx == htlc_commitment_tx_output_idx {
+ Some((event.confirmation_threshold(), preimage.is_some()))
+ } else { None }
+ } else { None }
+ });
+ if let Some((conf_thresh, true)) = htlc_spend_pending {
+ res.push(Balance::ClaimableAwaitingConfirmations {
+ claimable_amount_satoshis: htlc.amount_msat / 1000,
+ confirmation_height: conf_thresh,
+ });
+ } else {
+ res.push(Balance::ContentiousClaimable {
+ claimable_amount_satoshis: htlc.amount_msat / 1000,
+ timeout_height: htlc.cltv_expiry,
+ });
+ }
+ }
+ }
+ }
+ }
+ }
+
+ if let Some(txid) = confirmed_txid {
+ let mut found_commitment_tx = false;
+ 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));
+ if let Some(conf_thresh) = pending_commitment_tx_conf_thresh {
+ if let Some(value) = us.onchain_events_awaiting_threshold_conf.iter().find_map(|event| {
+ if let OnchainEvent::MaturingOutput {
+ descriptor: SpendableOutputDescriptor::StaticPaymentOutput(descriptor)
+ } = &event.event {
+ Some(descriptor.output.value)
+ } else { None }
+ }) {
+ res.push(Balance::ClaimableAwaitingConfirmations {
+ claimable_amount_satoshis: value,
+ confirmation_height: conf_thresh,
+ });
+ } else {
+ // If a counterparty commitment transaction is awaiting confirmation, we
+ // should either have a StaticPaymentOutput MaturingOutput event awaiting
+ // confirmation with the same height or have never met our dust amount.
+ }
+ }
+ found_commitment_tx = true;
+ } else if txid == us.current_holder_commitment_tx.txid {
+ walk_htlcs!(true, us.current_holder_commitment_tx.htlc_outputs.iter().map(|(a, _, _)| a));
+ if let Some(conf_thresh) = pending_commitment_tx_conf_thresh {
+ res.push(Balance::ClaimableAwaitingConfirmations {
+ claimable_amount_satoshis: us.current_holder_commitment_tx.to_self_value_sat,
+ confirmation_height: conf_thresh,
+ });
+ }
+ found_commitment_tx = true;
+ } 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));
+ if let Some(conf_thresh) = pending_commitment_tx_conf_thresh {
+ res.push(Balance::ClaimableAwaitingConfirmations {
+ claimable_amount_satoshis: prev_commitment.to_self_value_sat,
+ confirmation_height: conf_thresh,
+ });
+ }
+ found_commitment_tx = true;
+ }
+ }
+ if !found_commitment_tx {
+ if let Some(conf_thresh) = pending_commitment_tx_conf_thresh {
+ // We blindly assume this is a cooperative close transaction here, and that
+ // neither us nor our counterparty misbehaved. At worst we've under-estimated
+ // the amount we can claim as we'll punish a misbehaving counterparty.
+ res.push(Balance::ClaimableAwaitingConfirmations {
+ claimable_amount_satoshis: us.current_holder_commitment_tx.to_self_value_sat,
+ confirmation_height: conf_thresh,
+ });
+ }
+ }
+ // TODO: Add logic to provide claimable balances for counterparty broadcasting revoked
+ // outputs.
+ } 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(Balance::MaybeClaimableHTLCAwaitingTimeout {
+ 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(Balance::ClaimableOnChannelClose {
+ claimable_amount_satoshis: us.current_holder_commitment_tx.to_self_value_sat + claimable_inbound_htlc_value_sat,
+ });
+ }
+
+ res
+ }
+
+ /// Gets the set of outbound HTLCs which are pending resolution in this channel.
+ /// This is used to reconstruct pending outbound payments on restart in the ChannelManager.
+ pub(crate) fn get_pending_outbound_htlcs(&self) -> HashMap<HTLCSource, HTLCOutputInCommitment> {
+ let mut res = HashMap::new();
+ let us = self.inner.lock().unwrap();
+
+ macro_rules! walk_htlcs {
+ ($holder_commitment: expr, $htlc_iter: expr) => {
+ for (htlc, source) in $htlc_iter {
+ if us.htlcs_resolved_on_chain.iter().any(|v| Some(v.commitment_tx_output_idx) == htlc.transaction_output_index) {
+ // We should assert that funding_spend_confirmed is_some() here, but we
+ // have some unit tests which violate HTLC transaction CSVs entirely and
+ // would fail.
+ // TODO: Once tests all connect transactions at consensus-valid times, we
+ // should assert here like we do in `get_claimable_balances`.
+ } else if htlc.offered == $holder_commitment {
+ // If the payment was outbound, check if there's an HTLCUpdate
+ // indicating we have spent this HTLC with a timeout, claiming it back
+ // and awaiting confirmations on it.
+ let htlc_update_confd = us.onchain_events_awaiting_threshold_conf.iter().any(|event| {
+ if let OnchainEvent::HTLCUpdate { commitment_tx_output_idx: Some(commitment_tx_output_idx), .. } = event.event {
+ // If the HTLC was timed out, we wait for ANTI_REORG_DELAY blocks
+ // before considering it "no longer pending" - this matches when we
+ // provide the ChannelManager an HTLC failure event.
+ Some(commitment_tx_output_idx) == htlc.transaction_output_index &&
+ us.best_block.height() >= event.height + ANTI_REORG_DELAY - 1
+ } else if let OnchainEvent::HTLCSpendConfirmation { commitment_tx_output_idx, .. } = event.event {
+ // If the HTLC was fulfilled with a preimage, we consider the HTLC
+ // immediately non-pending, matching when we provide ChannelManager
+ // the preimage.
+ Some(commitment_tx_output_idx) == htlc.transaction_output_index
+ } else { false }
+ });
+ if !htlc_update_confd {
+ res.insert(source.clone(), htlc.clone());
+ }
+ }
+ }
+ }
+ }
+
+ // We're only concerned with the confirmation count of HTLC transactions, and don't
+ // actually care how many confirmations a commitment transaction may or may not have. Thus,
+ // we look for either a FundingSpendConfirmation event or a funding_spend_confirmed.
+ let confirmed_txid = us.funding_spend_confirmed.or_else(|| {
+ us.onchain_events_awaiting_threshold_conf.iter().find_map(|event| {
+ if let OnchainEvent::FundingSpendConfirmation { .. } = event.event {
+ Some(event.txid)
+ } else { None }
+ })
+ });
+ 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().filter_map(|(a, b)| {
+ if let &Some(ref source) = b {
+ Some((a, &**source))
+ } else { None }
+ }));
+ } else if txid == us.current_holder_commitment_tx.txid {
+ walk_htlcs!(true, us.current_holder_commitment_tx.htlc_outputs.iter().filter_map(|(a, _, c)| {
+ if let Some(source) = c { Some((a, source)) } else { None }
+ }));
+ } 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().filter_map(|(a, _, c)| {
+ if let Some(source) = c { Some((a, source)) } else { None }
+ }));
+ }
+ }
+ } else {
+ // If we have not seen a commitment transaction on-chain (ie the channel is not yet
+ // closed), just examine the available counterparty commitment transactions. See docs
+ // on `fail_unbroadcast_htlcs`, below, for justification.
+ macro_rules! walk_counterparty_commitment {
+ ($txid: expr) => {
+ if let Some(ref latest_outpoints) = us.counterparty_claimable_outpoints.get($txid) {
+ for &(ref htlc, ref source_option) in latest_outpoints.iter() {
+ if let &Some(ref source) = source_option {
+ res.insert((**source).clone(), htlc.clone());
+ }
+ }
+ }
+ }
+ }
+ if let Some(ref txid) = us.current_counterparty_commitment_txid {
+ walk_counterparty_commitment!(txid);
+ }
+ if let Some(ref txid) = us.prev_counterparty_commitment_txid {
+ walk_counterparty_commitment!(txid);
+ }