Package org.ldk.structs

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 as channel state changes. On each update, *all copies* of a [`ChannelMonitor`] must be updated and the update persisted to disk to ensure that the latest [`ChannelMonitor`] state can be reloaded if the application crashes. See method documentation and [`ChannelMonitorUpdateStatus`] for specific requirements.

    • 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 Result_ChannelMonitorUpdateStatusNoneZ 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. A return of `Err(())` indicates that the channel should immediately be force-closed without broadcasting the funding transaction. If the given `funding_txo` has previously been registered via `watch_channel`, `Err(())` must be returned. [`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 [`ChannelMonitor::update_monitor`] with the given update. This may fail (returning an `Err(())`), in which case this should return [`ChannelMonitorUpdateStatus::InProgress`] (and the update should never complete). This generally implies the channel has been closed (either by the funding outpoint being spent on-chain or the [`ChannelMonitor`] having decided to do so and broadcasted a transaction), and the [`ChannelManager`] state will be updated once it sees the funding spend on-chain. In general, persistence failures should be retried after returning [`ChannelMonitorUpdateStatus::InProgress`] and eventually complete. If a failure truly cannot be retried, the node should shut down immediately after returning [`ChannelMonitorUpdateStatus::UnrecoverableError`], see its documentation for more info. [`ChannelManager`]: crate::ln::channelmanager::ChannelManager

      • 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`].