Struct ChainMonitor 

pub struct ChainMonitor<ChannelSigner: EcdsaChannelSigner, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref, ES: Deref>
where
    C::Target: Filter,
    T::Target: BroadcasterInterface,
    F::Target: FeeEstimator,
    L::Target: Logger,
    P::Target: Persist<ChannelSigner>,
    ES::Target: EntropySource,
{ /* private fields */ }

An implementation of chain::Watch for monitoring channels.

Connected and disconnected blocks must be provided to ChainMonitor as documented by chain::Watch. May be used in conjunction with ChannelManager to monitor channels locally or used independently to monitor channels remotely. See the module-level documentation for details.

Note that ChainMonitor should regularly trigger 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.

Implementations

impl<K: Deref + MaybeSend + MaybeSync + 'static, S: FutureSpawner, SP: Deref + MaybeSend + MaybeSync + 'static, C: Deref, T: Deref + MaybeSend + MaybeSync + 'static, F: Deref + MaybeSend + MaybeSync + 'static, L: Deref + MaybeSend + MaybeSync + 'static, ES: Deref + MaybeSend + MaybeSync + 'static> ChainMonitor<<SP::Target as SignerProvider>::EcdsaSigner, C, T, F, L, AsyncPersister<K, S, L, ES, SP, T, F>, ES>

where K::Target: KVStore + MaybeSync, SP::Target: SignerProvider + Sized, C::Target: Filter, T::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger, ES::Target: EntropySource + Sized, <SP::Target as SignerProvider>::EcdsaSigner: MaybeSend + 'static,

pub fn new_async_beta( chain_source: Option<C>, broadcaster: T, logger: L, feeest: F, persister: MonitorUpdatingPersisterAsync<K, S, L, ES, SP, T, F>, _entropy_source: ES, _our_peerstorage_encryption_key: PeerStorageKey, ) -> Self

Creates a new ChainMonitor used to watch on-chain activity pertaining to channels.

This behaves the same as ChainMonitor::new except that it relies on MonitorUpdatingPersisterAsync and thus allows persistence to be completed async.

Note that async monitor updating is considered beta, and bugs may be triggered by its use.

This is not exported to bindings users as async is not supported outside of Rust.

impl<ChannelSigner: EcdsaChannelSigner, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref, ES: Deref> ChainMonitor<ChannelSigner, C, T, F, L, P, ES>

where C::Target: Filter, T::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger, P::Target: Persist<ChannelSigner>, ES::Target: EntropySource,

pub fn new( chain_source: Option<C>, broadcaster: T, logger: L, feeest: F, persister: P, _entropy_source: ES, _our_peerstorage_encryption_key: PeerStorageKey, ) -> Self

Creates a new ChainMonitor used to watch on-chain activity pertaining to channels.

When an optional chain source implementing chain::Filter is provided, the chain monitor will call back to it indicating transactions and outputs of interest. This allows clients to pre-filter blocks or only fetch blocks matching a compact filter. Otherwise, clients may always need to fetch full blocks absent another means for determining which blocks contain transactions relevant to the watched channels.

Note

our_peerstorage_encryption_key must be obtained from NodeSigner::get_peer_storage_key. This key is used to encrypt peer storage backups.

Important: This key should not be set arbitrarily or changed after initialization. The same key is obtained by the ChannelManager through NodeSigner to decrypt peer backups. Using an inconsistent or incorrect key will result in the inability to decrypt previously encrypted backups.

pub fn get_claimable_balances( &self, ignored_channels: &[&ChannelDetails], ) -> Vec<Balance>

Gets the balances in the contained ChannelMonitors which are claimable on-chain or claims which are awaiting confirmation.

Includes the balances from each ChannelMonitor except those included in ignored_channels.

See ChannelMonitor::get_claimable_balances for more details on the exact criteria for inclusion in the return value.

pub fn get_monitor( &self, channel_id: ChannelId, ) -> Result<LockedChannelMonitor<'_, ChannelSigner>, ()>

Gets the LockedChannelMonitor for a given funding outpoint, returning an Err if no such ChannelMonitor is currently being monitored for.

Note that the result holds a mutex over our monitor set, and should not be held indefinitely.

pub fn list_monitors(&self) -> Vec<ChannelId>

Lists the funding outpoint and channel ID of each ChannelMonitor being monitored.

Note that ChannelMonitors are not removed when a channel is closed as they are always monitoring for on-chain state resolutions.

pub fn list_pending_monitor_updates(&self) -> HashMap<ChannelId, Vec<u64>>

Available on non-c_bindings only.

Lists the pending updates for each ChannelMonitor (by ChannelId being monitored). Each Vec<u64> contains update_ids from ChannelMonitor::get_latest_update_id for updates that have not yet been fully persisted. Note that if a full monitor is persisted all the pending monitor updates must be individually marked completed by calling ChainMonitor::channel_monitor_updated.

pub fn channel_monitor_updated( &self, channel_id: ChannelId, completed_update_id: u64, ) -> Result<(), APIError>

Indicates the persistence of a ChannelMonitor has completed after ChannelMonitorUpdateStatus::InProgress was returned from an update operation.

Thus, the anticipated use is, at a high level:

1. This ChainMonitor calls Persist::update_persisted_channel which stores the update to disk and begins updating any remote (e.g. watchtower/backup) copies, returning ChannelMonitorUpdateStatus::InProgress,
2. once all remote copies are updated, you call this function with ChannelMonitor::get_latest_update_id or ChannelMonitorUpdate::update_id as the completed_update_id, and once all pending updates have completed the channel will be re-enabled.

It is only necessary to call ChainMonitor::channel_monitor_updated when you return ChannelMonitorUpdateStatus::InProgress from Persist and either:

1. A new ChannelMonitor was added in Persist::persist_new_channel, or
2. A ChannelMonitorUpdate was provided as part of Persist::update_persisted_channel. Note that we don’t care about calls to Persist::update_persisted_channel where no ChannelMonitorUpdate was provided.

Returns an APIError::APIMisuseError if funding_txo does not match any currently registered ChannelMonitors.

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

Processes any events asynchronously in the order they were generated since the last call using the given event handler.

See the trait-level documentation of EventsProvider for requirements.

pub fn get_update_future(&self) -> Future

Gets a Future that completes when an event is available either via chain::Watch::release_pending_monitor_events or EventsProvider::process_pending_events.

Note that callbacks registered on the Future MUST NOT call back into this ChainMonitor and should instead register actions to be taken later.

pub fn rebroadcast_pending_claims(&self)

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 signer_unblocked(&self, monitor_opt: Option<ChannelId>)

Triggers rebroadcasts of pending claims from force-closed channels after a transaction signature generation failure.

monitor_opt can be used as a filter to only trigger them for a specific channel monitor.

pub fn archive_fully_resolved_channel_monitors(&self)

Archives fully resolved channel monitors by calling Persist::archive_persisted_channel.

This is useful for pruning fully resolved monitors from the monitor set and primary storage so they are not kept in memory and reloaded on restart.

Should be called occasionally (once every handful of blocks or on startup).

Depending on the implementation of Persist::archive_persisted_channel the monitor data could be moved to an archive location or removed entirely.

pub fn load_existing_monitor( &self, channel_id: ChannelId, monitor: ChannelMonitor<ChannelSigner>, ) -> Result<ChannelMonitorUpdateStatus, ()>

Loads a ChannelMonitor which already exists on disk after startup.

Using this over chain::Watch::watch_channel avoids re-persisting a ChannelMonitor that hasn’t changed, slowing down startup.

Note that this method can be used if additional blocks were replayed against the ChannelMonitor or if a ChannelMonitorUpdate loaded from disk was replayed such that it will replayed on startup, and in general can only not be used if you directly accessed the ChannelMonitor and changed its state in some way that will not be replayed again on a restart. Such direct access should generally never occur for most LDK-based nodes.

For ChannelMonitors which were last serialized by an LDK version prior to 0.1 this will fall back to calling chain::Watch::watch_channel and persisting the ChannelMonitor. See the release notes for LDK 0.1 for more information on this requirement.

ChannelMonitors which do not need to be persisted (i.e. were last written by LDK 0.1 or later) will be loaded without persistence and this method will return ChannelMonitorUpdateStatus::Completed.

Trait Implementations

impl<ChannelSigner: EcdsaChannelSigner, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref, ES: Deref> BaseMessageHandler for ChainMonitor<ChannelSigner, C, T, F, L, P, ES>

where C::Target: Filter, T::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger, P::Target: Persist<ChannelSigner>, ES::Target: EntropySource,

fn get_and_clear_pending_msg_events(&self) -> Vec<MessageSendEvent>

Gets the list of pending events which were generated by previous actions, clearing the list in the process.

fn peer_disconnected(&self, _their_node_id: PublicKey)

Indicates a connection to the peer failed/an existing connection was lost.

fn provided_node_features(&self) -> NodeFeatures

Gets the node feature flags which this handler itself supports. All available handlers are queried similarly and their feature flags are OR’d together to form the NodeFeatures which are broadcasted in our NodeAnnouncement message.

fn provided_init_features(&self, _their_node_id: PublicKey) -> InitFeatures

Gets the init feature flags which should be sent to the given peer. All available handlers are queried similarly and their feature flags are OR’d together to form the InitFeatures which are sent in our Init message.

fn peer_connected( &self, _their_node_id: PublicKey, _msg: &Init, _inbound: bool, ) -> Result<(), ()>

Handle a peer (re)connecting.

impl<ChannelSigner: EcdsaChannelSigner, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref, ES: Deref> Confirm for ChainMonitor<ChannelSigner, C, T, F, L, P, ES>

where C::Target: Filter, T::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger, P::Target: Persist<ChannelSigner>, ES::Target: EntropySource,

fn transactions_confirmed( &self, header: &Header, txdata: &TransactionData<'_>, height: u32, )

Notifies LDK of transactions confirmed in a block with a given header and height.

fn transaction_unconfirmed(&self, txid: &Txid)

Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.

fn best_block_updated(&self, header: &Header, height: u32)

Notifies LDK of an update to the best header connected at the given height.

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

Returns transactions that must be monitored for reorganization out of the chain along with the height and the hash of the block as part of which it had been previously confirmed.

impl<ChannelSigner: EcdsaChannelSigner, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref, ES: Deref> EventsProvider for ChainMonitor<ChannelSigner, C, T, F, L, P, ES>

where C::Target: Filter, T::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger, P::Target: Persist<ChannelSigner>, ES::Target: EntropySource,

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.

impl<ChannelSigner: EcdsaChannelSigner, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref, ES: Deref> Listen for ChainMonitor<ChannelSigner, C, T, F, L, P, ES>

where C::Target: Filter, T::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger, P::Target: Persist<ChannelSigner>, ES::Target: EntropySource,

fn filtered_block_connected( &self, header: &Header, txdata: &TransactionData<'_>, height: u32, )

Notifies the listener that a block was added at the given height, with the transaction data possibly filtered.

fn blocks_disconnected(&self, fork_point: BestBlock)

Notifies the listener that one or more blocks were removed in anticipation of a reorg.

fn block_connected(&self, block: &Block, height: u32)

Notifies the listener that a block was added at the given height.

impl<ChannelSigner: EcdsaChannelSigner, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref, ES: Deref> Watch<ChannelSigner> for ChainMonitor<ChannelSigner, C, T, F, L, P, ES>

where C::Target: Filter, T::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger, P::Target: Persist<ChannelSigner>, ES::Target: EntropySource,

fn watch_channel( &self, channel_id: ChannelId, monitor: ChannelMonitor<ChannelSigner>, ) -> Result<ChannelMonitorUpdateStatus, ()>

Watches a channel identified by channel_id using monitor.

fn update_channel( &self, channel_id: ChannelId, update: &ChannelMonitorUpdate, ) -> ChannelMonitorUpdateStatus

Updates a channel identified by channel_id by applying update to its monitor.

fn release_pending_monitor_events( &self, ) -> Vec<(OutPoint, ChannelId, Vec<MonitorEvent>, PublicKey)>

Returns any monitor events since the last call. Subsequent calls must only return new events.

impl<ChannelSigner: EcdsaChannelSigner, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref, ES: Deref> SendOnlyMessageHandler for ChainMonitor<ChannelSigner, C, T, F, L, P, ES>

where C::Target: Filter, T::Target: BroadcasterInterface, F::Target: FeeEstimator, L::Target: Logger, P::Target: Persist<ChannelSigner>, ES::Target: EntropySource,