Class ChainMonitor


  • public class ChainMonitor
    extends Object
    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. [`ChannelManager`]: crate::ln::channelmanager::ChannelManager [module-level documentation]: crate::chain::chainmonitor [`rebroadcast_pending_claims`]: Self::rebroadcast_pending_claims
    • Method Detail

      • of

        public static ChainMonitor of​(Option_FilterZ chain_source,
                                      BroadcasterInterface broadcaster,
                                      Logger logger,
                                      FeeEstimator feeest,
                                      Persist persister)
        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.
      • get_claimable_balances

        public Balance[] get_claimable_balances​(ChannelDetails[] ignored_channels)
        Gets the balances in the contained [`ChannelMonitor`]s which are claimable on-chain or claims which are awaiting confirmation. Includes the balances from each [`ChannelMonitor`] *except* those included in `ignored_channels`, allowing you to filter out balances from channels which are still open (and whose balance should likely be pulled from the [`ChannelDetails`]). See [`ChannelMonitor::get_claimable_balances`] for more details on the exact criteria for inclusion in the return value.
      • get_monitor

        public Result_LockedChannelMonitorNoneZ get_monitor​(OutPoint funding_txo)
        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.
      • list_monitors

        public OutPoint[] list_monitors()
        Lists the funding outpoint of each [`ChannelMonitor`] being monitored. Note that [`ChannelMonitor`]s are not removed when a channel is closed as they are always monitoring for on-chain state resolutions.
      • list_pending_monitor_updates

        public TwoTuple_OutPointCVec_MonitorUpdateIdZZ[] list_pending_monitor_updates()
        Lists the pending updates for each [`ChannelMonitor`] (by `OutPoint` being monitored).
      • channel_monitor_updated

        public Result_NoneAPIErrorZ channel_monitor_updated​(OutPoint funding_txo,
                                                            MonitorUpdateId completed_update_id)
        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 the `completed_update_id` that completed, and once all pending updates have completed the channel will be re-enabled. Returns an [`APIError::APIMisuseError`] if `funding_txo` does not match any currently registered [`ChannelMonitor`]s.
      • get_update_future

        public Future get_update_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. [`EventsProvider::process_pending_events`]: crate::events::EventsProvider::process_pending_events
      • rebroadcast_pending_claims

        public void rebroadcast_pending_claims()
        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.
      • as_Listen

        public Listen as_Listen()
        Constructs a new Listen which calls the relevant methods on this_arg. This copies the `inner` pointer in this_arg and thus the returned Listen must be freed before this_arg is
      • as_Confirm

        public Confirm as_Confirm()
        Constructs a new Confirm which calls the relevant methods on this_arg. This copies the `inner` pointer in this_arg and thus the returned Confirm must be freed before this_arg is
      • as_Watch

        public Watch as_Watch()
        Constructs a new Watch which calls the relevant methods on this_arg. This copies the `inner` pointer in this_arg and thus the returned Watch must be freed before this_arg is
      • as_EventsProvider

        public EventsProvider as_EventsProvider()
        Constructs a new EventsProvider which calls the relevant methods on this_arg. This copies the `inner` pointer in this_arg and thus the returned EventsProvider must be freed before this_arg is