Package org.ldk.structs
Class ChannelMonitor
- java.lang.Object
-
- org.ldk.structs.ChannelMonitor
-
public class ChannelMonitor extends Object
A ChannelMonitor handles chain events (blocks connected and disconnected) and generates on-chain transactions to ensure no loss of funds occurs. You MUST ensure that no ChannelMonitors for a given channel anywhere contain out-of-date information and are actively monitoring the chain. Pending Events or updated HTLCs which have not yet been read out by get_and_clear_pending_monitor_events or get_and_clear_pending_events are serialized to disk and reloaded at deserialize-time. Thus, you must ensure that, when handling events, all events gotten are fully handled before re-serializing the new state. Note that the deserializer is only implemented for (BlockHash, ChannelMonitor), which tells you the last block hash which was block_connect()ed. You MUST rescan any blocks along the \"reorg path\" (ie disconnecting blocks until you find a common ancestor from both the returned block hash and the the current chain and then reconnecting blocks to get to the best chain) upon deserializing the object!
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description TwoTuple<byte[],TwoTuple<Integer,TxOut>[]>[]
best_block_updated(byte[] header, int height, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Updates the monitor with the current best chain tip, returning new outputs to watch.TwoTuple<byte[],TwoTuple<Integer,TxOut>[]>[]
block_connected(byte[] header, TwoTuple<Long,byte[]>[] txdata, int height, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Processes transactions in a newly connected block, which may result in any of the following: - update the monitor's state against resolved HTLCs - punish the counterparty in the case of seeing a revoked commitment transaction - force close the channel and claim/timeout incoming/outgoing HTLCs if near expiration - detect settled outputs for later spending - schedule and bump any in-flight claims Returns any new outputs to watch from `txdata`; after called, these are also included in [`get_outputs_to_watch`].void
block_disconnected(byte[] header, int height, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Determines if the disconnected block contained any transactions of interest and updates appropriately.ChannelMonitor
clone()
Creates a copy of the ChannelMonitorBestBlock
current_best_block()
Gets the latest best block which was connected either via the [`chain::Listen`] or [`chain::Confirm`] interfaces.protected void
finalize()
Event[]
get_and_clear_pending_events()
Gets the list of pending events which were generated by previous actions, clearing the list in the process.MonitorEvent[]
get_and_clear_pending_monitor_events()
Get the list of HTLCs who's status has been updated on chain.Balance[]
get_claimable_balances()
Gets the balances in this channel which are either claimable by us if we were to force-close the channel now or which are claimable on-chain (possibly awaiting confirmation).TwoTuple<OutPoint,byte[]>
get_funding_txo()
Gets the funding transaction outpoint of the channel this ChannelMonitor is monitoring for.byte[][]
get_latest_holder_commitment_txn(Logger logger)
Used by ChannelManager deserialization to broadcast the latest holder state if its copy of the Channel was out-of-date.long
get_latest_update_id()
Gets the update_id from the latest ChannelMonitorUpdate which was applied to this ChannelMonitor.TwoTuple<byte[],TwoTuple<Integer,byte[]>[]>[]
get_outputs_to_watch()
Gets a list of txids, with their output scripts (in the order they appear in the transaction), which we must learn about spends of via block_connected().byte[][]
get_relevant_txids()
Returns the set of txids that should be monitored for re-organization out of the chain.void
load_outputs_to_watch(Filter filter)
Loads the funding txo and outputs to watch into the given `chain::Filter` by repeatedly calling `chain::Filter::register_output` and `chain::Filter::register_tx` until all outputs have been registered.void
transaction_unconfirmed(byte[] txid, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Processes a transaction that was reorganized out of the chain.TwoTuple<byte[],TwoTuple<Integer,TxOut>[]>[]
transactions_confirmed(byte[] header, TwoTuple<Long,byte[]>[] txdata, int height, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Processes transactions confirmed in a block with the given header and height, returning new outputs to watch.Result_NoneMonitorUpdateErrorZ
update_monitor(ChannelMonitorUpdate updates, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Updates a ChannelMonitor on the basis of some new information provided by the Channel itself.byte[]
write()
Serialize the ChannelMonitor object into a byte array which can be read by ChannelMonitor_read
-
-
-
Method Detail
-
finalize
protected void finalize() throws Throwable
-
clone
public ChannelMonitor clone()
Creates a copy of the ChannelMonitor
-
write
public byte[] write()
Serialize the ChannelMonitor object into a byte array which can be read by ChannelMonitor_read
-
update_monitor
public Result_NoneMonitorUpdateErrorZ update_monitor(ChannelMonitorUpdate updates, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Updates a ChannelMonitor on the basis of some new information provided by the Channel itself. panics if the given update is not the next update by update_id.
-
get_latest_update_id
public long get_latest_update_id()
Gets the update_id from the latest ChannelMonitorUpdate which was applied to this ChannelMonitor.
-
get_funding_txo
public TwoTuple<OutPoint,byte[]> get_funding_txo()
Gets the funding transaction outpoint of the channel this ChannelMonitor is monitoring for.
-
get_outputs_to_watch
public TwoTuple<byte[],TwoTuple<Integer,byte[]>[]>[] get_outputs_to_watch()
Gets a list of txids, with their output scripts (in the order they appear in the transaction), which we must learn about spends of via block_connected().
-
load_outputs_to_watch
public void load_outputs_to_watch(Filter filter)
Loads the funding txo and outputs to watch into the given `chain::Filter` by repeatedly calling `chain::Filter::register_output` and `chain::Filter::register_tx` until all outputs have been registered.
-
get_and_clear_pending_monitor_events
public MonitorEvent[] get_and_clear_pending_monitor_events()
Get the list of HTLCs who's status has been updated on chain. This should be called by ChannelManager via [`chain::Watch::release_pending_monitor_events`].
-
get_and_clear_pending_events
public Event[] get_and_clear_pending_events()
Gets the list of pending events which were generated by previous actions, clearing the list in the process. This is called by ChainMonitor::get_and_clear_pending_events() and is equivalent to EventsProvider::get_and_clear_pending_events() except that it requires &mut self as we do no internal locking in ChannelMonitors.
-
get_latest_holder_commitment_txn
public byte[][] get_latest_holder_commitment_txn(Logger logger)
Used by ChannelManager deserialization to broadcast the latest holder state if its copy of the Channel was out-of-date. You may use it to get a broadcastable holder toxic tx in case of fallen-behind, i.e when receiving a channel_reestablish with a proof that our counterparty side knows a higher revocation secret than the holder commitment number we are aware of. Broadcasting these transactions are UNSAFE, as they allow counterparty side to punish you. Nevertheless you may want to broadcast them if counterparty don't close channel with his higher commitment transaction after a substantial amount of time (a month or even a year) to get back funds. Best may be to contact out-of-band the other node operator to coordinate with him if option is available to you. In any-case, choice is up to the user.
-
block_connected
public TwoTuple<byte[],TwoTuple<Integer,TxOut>[]>[] block_connected(byte[] header, TwoTuple<Long,byte[]>[] txdata, int height, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Processes transactions in a newly connected block, which may result in any of the following: - update the monitor's state against resolved HTLCs - punish the counterparty in the case of seeing a revoked commitment transaction - force close the channel and claim/timeout incoming/outgoing HTLCs if near expiration - detect settled outputs for later spending - schedule and bump any in-flight claims Returns any new outputs to watch from `txdata`; after called, these are also included in [`get_outputs_to_watch`]. [`get_outputs_to_watch`]: #method.get_outputs_to_watch
-
block_disconnected
public void block_disconnected(byte[] header, int height, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Determines if the disconnected block contained any transactions of interest and updates appropriately.
-
transactions_confirmed
public TwoTuple<byte[],TwoTuple<Integer,TxOut>[]>[] transactions_confirmed(byte[] header, TwoTuple<Long,byte[]>[] txdata, int height, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Processes transactions confirmed in a block with the given header and height, returning new outputs to watch. See [`block_connected`] for details. Used instead of [`block_connected`] by clients that are notified of transactions rather than blocks. See [`chain::Confirm`] for calling expectations. [`block_connected`]: Self::block_connected
-
transaction_unconfirmed
public void transaction_unconfirmed(byte[] txid, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Processes a transaction that was reorganized out of the chain. Used instead of [`block_disconnected`] by clients that are notified of transactions rather than blocks. See [`chain::Confirm`] for calling expectations. [`block_disconnected`]: Self::block_disconnected
-
best_block_updated
public TwoTuple<byte[],TwoTuple<Integer,TxOut>[]>[] best_block_updated(byte[] header, int height, BroadcasterInterface broadcaster, FeeEstimator fee_estimator, Logger logger)
Updates the monitor with the current best chain tip, returning new outputs to watch. See [`block_connected`] for details. Used instead of [`block_connected`] by clients that are notified of transactions rather than blocks. See [`chain::Confirm`] for calling expectations. [`block_connected`]: Self::block_connected
-
get_relevant_txids
public byte[][] get_relevant_txids()
Returns the set of txids that should be monitored for re-organization out of the chain.
-
current_best_block
public BestBlock current_best_block()
Gets the latest best block which was connected either via the [`chain::Listen`] or [`chain::Confirm`] interfaces.
-
get_claimable_balances
public Balance[] get_claimable_balances()
Gets the balances in this channel which are either claimable by us if we were to force-close the channel now or which are claimable on-chain (possibly awaiting confirmation). Any balances in the channel which are available on-chain (excluding on-chain fees) are included here until an [`Event::SpendableOutputs`] event has been generated for the balance, or until our counterparty has claimed the balance and accrued several confirmations on the claim transaction. Note that the balances available when you or your counterparty have broadcasted revoked state(s) may not be fully captured here. See [`Balance`] for additional details on the types of claimable balances which may be returned here and their meanings.
-
-