Package org.ldk.structs
Class ChainMonitor
- java.lang.Object
-
- org.ldk.structs.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 Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Confirm
as_Confirm()
Constructs a new Confirm which calls the relevant methods on this_arg.EventsProvider
as_EventsProvider()
Constructs a new EventsProvider which calls the relevant methods on this_arg.Listen
as_Listen()
Constructs a new Listen which calls the relevant methods on this_arg.Watch
as_Watch()
Constructs a new Watch which calls the relevant methods on this_arg.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.protected void
finalize()
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.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.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`].OutPoint[]
list_monitors()
Lists the funding outpoint of each [`ChannelMonitor`] being monitored.TwoTuple_OutPointCVec_MonitorUpdateIdZZ[]
list_pending_monitor_updates()
Lists the pending updates for each [`ChannelMonitor`] (by `OutPoint` being monitored).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.void
rebroadcast_pending_claims()
Triggers rebroadcasts/fee-bumps of pending claims from a force-closed channel.
-
-
-
Method Detail
-
finalize
protected void finalize() throws Throwable
-
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
-
-