Class Watch


  • public class Watch
    extends Object
    The `Watch` trait defines behavior for watching on-chain activity pertaining to channels as blocks are connected and disconnected. Each channel is associated with a [`ChannelMonitor`]. Implementations of this trait are responsible for maintaining a set of monitors such that they can be updated accordingly as channel state changes and HTLCs are resolved. See method documentation for specific requirements. Implementations **must** ensure that updates are successfully applied and persisted upon method completion. If an update fails with a [`PermanentFailure`], then it must immediately shut down without taking any further action such as persisting the current state. If an implementation maintains multiple instances of a channel's monitor (e.g., by storing backup copies), then it must ensure that updates are applied across all instances. Otherwise, it could result in a revoked transaction being broadcast, allowing the counterparty to claim all funds in the channel. See [`ChannelMonitorUpdateStatus`] for more details about how to handle multiple instances. [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure
    • Method Detail

      • destroy

        public void destroy()
        Destroys the object, freeing associated resources. After this call, any access to this object may result in a SEGFAULT or worse. You should generally NEVER call this method. You should let the garbage collector do this for you when it finalizes objects. However, it may be useful for types which represent locks and should be closed immediately to avoid holding locks until the GC runs.
      • watch_channel

        public ChannelMonitorUpdateStatus watch_channel​(OutPoint funding_txo,
                                                        ChannelMonitor monitor)
        Watches a channel identified by `funding_txo` using `monitor`. Implementations are responsible for watching the chain for the funding transaction along with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means calling [`block_connected`] and [`block_disconnected`] on the monitor. Note: this interface MUST error with [`ChannelMonitorUpdateStatus::PermanentFailure`] if the given `funding_txo` has previously been registered via `watch_channel`. [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch [`block_connected`]: channelmonitor::ChannelMonitor::block_connected [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected
      • update_channel

        public ChannelMonitorUpdateStatus update_channel​(OutPoint funding_txo,
                                                         ChannelMonitorUpdate update)
        Updates a channel identified by `funding_txo` by applying `update` to its monitor. Implementations must call [`update_monitor`] with the given update. See [`ChannelMonitorUpdateStatus`] for invariants around returning an error. [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor
      • release_pending_monitor_events

        public ThreeTuple_OutPointCVec_MonitorEventZPublicKeyZ[] release_pending_monitor_events()
        Returns any monitor events since the last call. Subsequent calls must only return new events. Note that after any block- or transaction-connection calls to a [`ChannelMonitor`], no further events may be returned here until the [`ChannelMonitor`] has been fully persisted to disk. For details on asynchronous [`ChannelMonitor`] updating and returning [`MonitorEvent::Completed`] here, see [`ChannelMonitorUpdateStatus::InProgress`].