Struct lightning::chain::channelmonitor::ChannelMonitor

pub struct ChannelMonitor<Signer: WriteableEcdsaChannelSigner> { /* private fields */ }

A ChannelMonitor handles chain events (blocks connected and disconnected) and generates on-chain transactions to ensure no loss of funds occurs.

You MUST ensure that no ChannelMonitors for a given channel anywhere contain out-of-date information and are actively monitoring the chain.

Note that the deserializer is only implemented for (BlockHash, ChannelMonitor), which tells you the last block hash which was block_connect()ed. You MUST rescan any blocks along the “reorg path” (ie disconnecting blocks until you find a common ancestor from both the returned block hash and the the current chain and then reconnecting blocks to get to the best chain) upon deserializing the object!

Implementations

impl<Signer: WriteableEcdsaChannelSigner> ChannelMonitor<Signer>

pub fn update_monitor<B: Deref, F: Deref, L: Deref>( &self, updates: &ChannelMonitorUpdate, broadcaster: &B, fee_estimator: &F, logger: &L ) -> Result<(), ()>

where B::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger,

Updates a ChannelMonitor on the basis of some new information provided by the Channel itself.

panics if the given update is not the next update by update_id.

pub fn get_latest_update_id(&self) -> u64

Gets the update_id from the latest ChannelMonitorUpdate which was applied to this ChannelMonitor.

pub fn get_funding_txo(&self) -> (OutPoint, ScriptBuf)

Gets the funding transaction outpoint of the channel this ChannelMonitor is monitoring for.

pub fn get_outputs_to_watch(&self) -> Vec<(Txid, Vec<(u32, ScriptBuf)>)>

Gets a list of txids, with their output scripts (in the order they appear in the transaction), which we must learn about spends of via block_connected().

pub fn load_outputs_to_watch<F: Deref, L: Deref>(&self, filter: &F, logger: &L)

where F::Target: Filter, L::Target: Logger,

Loads the funding txo and outputs to watch into the given chain::Filter by repeatedly calling chain::Filter::register_output and chain::Filter::register_tx until all outputs have been registered.

pub fn get_and_clear_pending_monitor_events(&self) -> Vec<MonitorEvent>

Get the list of HTLCs who’s status has been updated on chain. This should be called by ChannelManager via chain::Watch::release_pending_monitor_events.

pub fn process_pending_events<H: Deref>(&self, handler: &H)

where H::Target: EventHandler,

Processes SpendableOutputs events produced from each ChannelMonitor upon maturity.

For channels featuring anchor outputs, this method will also process BumpTransaction events produced from each ChannelMonitor while there is a balance to claim onchain within each channel. As the confirmation of a commitment transaction may be critical to the safety of funds, we recommend invoking this every 30 seconds, or lower if running in an environment with spotty connections, like on mobile.

An EventHandler may safely call back to the provider, though this shouldn’t be needed in order to handle these events.

pub async fn process_pending_events_async<Future: Future, H: Fn(Event) -> Future>( &self, handler: &H )

Processes any events asynchronously.

See Self::process_pending_events for more information.

pub fn initial_counterparty_commitment_tx( &self ) -> Option<CommitmentTransaction>

Gets the counterparty’s initial commitment transaction. The returned commitment transaction is unsigned. This is intended to be called during the initial persistence of the monitor (inside an implementation of Persist::persist_new_channel), to allow for watchtowers in the persistence pipeline to have enough data to form justice transactions.

This is similar to Self::counterparty_commitment_txs_from_update, except that for the initial commitment transaction, we don’t have a corresponding update.

This will only return Some for channel monitors that have been created after upgrading to LDK 0.0.117+.

pub fn counterparty_commitment_txs_from_update( &self, update: &ChannelMonitorUpdate ) -> Vec<CommitmentTransaction>

Gets all of the counterparty commitment transactions provided by the given update. This may be empty if the update doesn’t include any new counterparty commitments. Returned commitment transactions are unsigned.

This is provided so that watchtower clients in the persistence pipeline are able to build justice transactions for each counterparty commitment upon each update. It’s intended to be used within an implementation of Persist::update_persisted_channel, which is provided with a monitor and an update. Once revoked, signing a justice transaction can be done using Self::sign_to_local_justice_tx.

It is expected that a watchtower client may use this method to retrieve the latest counterparty commitment transaction(s), and then hold the necessary data until a later update in which the monitor has been updated with the corresponding revocation data, at which point the monitor can sign the justice transaction.

This will only return a non-empty list for monitor updates that have been created after upgrading to LDK 0.0.117+. Note that no restriction lies on the monitors themselves, which may have been created prior to upgrading.

pub fn sign_to_local_justice_tx( &self, justice_tx: Transaction, input_idx: usize, value: u64, commitment_number: u64 ) -> Result<Transaction, ()>

Wrapper around EcdsaChannelSigner::sign_justice_revoked_output to make signing the justice transaction easier for implementors of chain::chainmonitor::Persist. On success this method returns the provided transaction signing the input at input_idx. This method will only produce a valid signature for a transaction spending the to_local output of a commitment transaction, i.e. this cannot be used for revoked HTLC outputs.

Value is the value of the output being spent by the input at input_idx, committed in the BIP 143 signature.

This method will only succeed if this monitor has received the revocation secret for the provided commitment_number. If a commitment number is provided that does not correspond to the commitment transaction being revoked, this will return a signed transaction, but the signature will not be valid.

pub fn get_counterparty_node_id(&self) -> Option<PublicKey>

Gets the node_id of the counterparty for this channel.

Will be None for channels constructed on LDK versions prior to 0.0.110 and always Some otherwise.

pub fn get_latest_holder_commitment_txn<L: Deref>( &self, logger: &L ) -> Vec<Transaction>

where L::Target: Logger,

Used by ChannelManager deserialization to broadcast the latest holder state if its copy of the channel state was out-of-date.

You may also use this to broadcast the latest local commitment transaction, either because a monitor update failed or because we’ve fallen behind (i.e. we’ve received proof that our counterparty side knows a revocation secret we gave them that they shouldn’t know).

Broadcasting these transactions in the second case is UNSAFE, as they allow counterparty side to punish you. Nevertheless you may want to broadcast them if counterparty doesn’t close channel with their commitment transaction after a substantial amount of time. Best may be to contact the other node operator out-of-band to coordinate other options available to you.

pub fn block_connected<B: Deref, F: Deref, L: Deref>( &self, header: &Header, txdata: &TransactionData<'_>, height: u32, broadcaster: B, fee_estimator: F, logger: &L ) -> Vec<TransactionOutputs>

where B::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: 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.

pub fn block_disconnected<B: Deref, F: Deref, L: Deref>( &self, header: &Header, height: u32, broadcaster: B, fee_estimator: F, logger: &L )

where B::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger,

Determines if the disconnected block contained any transactions of interest and updates appropriately.

pub fn transactions_confirmed<B: Deref, F: Deref, L: Deref>( &self, header: &Header, txdata: &TransactionData<'_>, height: u32, broadcaster: B, fee_estimator: F, logger: &L ) -> Vec<TransactionOutputs>

where B::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: 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.

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,

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.

pub fn best_block_updated<B: Deref, F: Deref, L: Deref>( &self, header: &Header, height: u32, broadcaster: B, fee_estimator: F, logger: &L ) -> Vec<TransactionOutputs>

where B::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: 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.

pub fn get_relevant_txids(&self) -> Vec<(Txid, u32, Option<BlockHash>)>

Returns the set of txids that should be monitored for re-organization out of the chain.

pub fn current_best_block(&self) -> BestBlock

Gets the latest best block which was connected either via the chain::Listen or chain::Confirm interfaces.

pub fn rebroadcast_pending_claims<B: Deref, F: Deref, L: Deref>( &self, broadcaster: B, fee_estimator: F, logger: &L )

where B::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger,

Triggers rebroadcasts/fee-bumps of pending claims from a force-closed channel. This is crucial in preventing certain classes of pinning attacks, detecting substantial mempool feerate changes between blocks, and ensuring reliability if broadcasting fails. We recommend invoking this every 30 seconds, or lower if running in an environment with spotty connections, like on mobile.

pub fn get_spendable_outputs( &self, tx: &Transaction, confirmation_height: u32 ) -> Vec<SpendableOutputDescriptor>

Returns the descriptors for relevant outputs (i.e., those that we can spend) within the transaction if they exist and the transaction has at least ANTI_REORG_DELAY confirmations. For SpendableOutputDescriptor::DelayedPaymentOutput descriptors to be returned, the transaction must have at least max(ANTI_REORG_DELAY, to_self_delay) confirmations.

Descriptors returned by this method are primarily exposed via Event::SpendableOutputs once they are no longer under reorg risk. This method serves as a way to retrieve these descriptors at a later time, either for historical purposes, or to replay any missed/unhandled descriptors. For the purpose of gathering historical records, if the channel close has fully resolved (i.e., ChannelMonitor::get_claimable_balances returns an empty set), you can retrieve all spendable outputs by providing all descendant spending transactions starting from the channel’s funding transaction and going down three levels.

tx is a transaction we’ll scan the outputs of. Any transaction can be provided. If any outputs which can be spent by us are found, at least one descriptor is returned.

confirmation_height must be the height of the block in which tx was included in.

impl<Signer: WriteableEcdsaChannelSigner> ChannelMonitor<Signer>

pub fn get_claimable_balances(&self) -> Vec<Balance>

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 for ChannelMonitors which track a channel which went on-chain with versions of LDK prior to 0.0.111, not all or excess balances may be included.

See Balance for additional details on the types of claimable balances which may be returned here and their meanings.

Trait Implementations

impl<Signer> Clone for ChannelMonitor<Signer>

where Signer: Clone + WriteableEcdsaChannelSigner,

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Signer> PartialEq for ChannelMonitor<Signer>

where Signer: PartialEq + WriteableEcdsaChannelSigner,

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Signer: WriteableEcdsaChannelSigner> Writeable for ChannelMonitor<Signer>

fn write<W: Writer>(&self, writer: &mut W) -> Result<(), Error>

Writes self out to the given Writer.

fn encode(&self) -> Vec<u8>

Writes self out to a Vec<u8>.

fn serialized_length(&self) -> usize

Gets the length of this object after it has been serialized. This can be overridden to optimize cases where we prepend an object with its length.