Package org.ldk.structs
Class ChannelManager
- java.lang.Object
-
- org.ldk.structs.ChannelManager
-
public class ChannelManager extends Object
Manager which keeps track of a number of channels and sends messages to the appropriate channel, also tracking HTLC preimages and forwarding onion packets appropriately. Implements ChannelMessageHandler, handling the multi-channel parts and passing things through to individual Channels. Implements Writeable to write out all channel state to disk. Implies peer_disconnected() for all peers during write/read (though does not modify this instance, only the instance being serialized). This will result in any channels which have not yet exchanged funding_created (ie called funding_transaction_generated for outbound channels). Note that you can be a bit lazier about writing out ChannelManager than you can be with ChannelMonitors. With ChannelMonitors you MUST write each monitor update out to disk before returning from chain::Watch::watch_/update_channel, with ChannelManagers, writing updates happens out-of-band (and will prevent any other ChannelManager operations from occurring during the serialization process). If the deserialized version is out-of-date compared to the ChannelMonitors passed by reference to read(), those channels will be force-closed based on the ChannelMonitor state and no funds will be lost (mod on-chain transaction fees). Note that the deserializer is only implemented for (BlockHash, ChannelManager), which tells you the last block hash which was block_connect()ed. You MUST rescan any blocks along the \"reorg path\" (ie call block_disconnected() until you get to a common block and then call block_connected() to step towards your best block) upon deserialization before using the object! Note that ChannelManager is responsible for tracking liveness of its channels and generating ChannelUpdate messages informing peers that the channel is temporarily disabled. To avoid spam due to quick disconnection/reconnection, updates are not sent until the channel has been offline for a full minute. In order to track this, you must call timer_tick_occurred roughly once per minute, though it doesn't have to be perfect. Rather than using a plain ChannelManager, it is preferable to use either a SimpleArcChannelManager a SimpleRefChannelManager, for conciseness. See their documentation for more details, but essentially you should default to using a SimpleRefChannelManager, and use a SimpleArcChannelManager when you require a ChannelManager with a static lifetime, such as when you're using lightning-net-tokio.
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description ChannelMessageHandler
as_ChannelMessageHandler()
Constructs a new ChannelMessageHandler which calls the relevant methods on this_arg.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.MessageSendEventsProvider
as_MessageSendEventsProvider()
Constructs a new MessageSendEventsProvider which calls the relevant methods on this_arg.void
await_persistable_update()
Blocks until ChannelManager needs to be persisted.boolean
await_persistable_update_timeout(long max_wait)
Blocks until ChannelManager needs to be persisted or a timeout is reached.void
broadcast_node_announcement(byte[] rgb, byte[] alias, NetAddress[] addresses)
Regenerates channel_announcements and generates a signed node_announcement from the given arguments, providing them in corresponding events via [`get_and_clear_pending_msg_events`], if at least one public channel has been confirmed on-chain.void
channel_monitor_updated(OutPoint funding_txo, long highest_applied_update_id)
Restores a single, given channel to normal operation after a ChannelMonitorUpdateErr::TemporaryFailure was returned from a channel monitor update operation.boolean
claim_funds(byte[] payment_preimage)
Provides a payment preimage in response to a PaymentReceived event, returning true and generating message events for the net layer to claim the payment, if possible.Result_NoneAPIErrorZ
close_channel(byte[] channel_id)
Begins the process of closing a channel.Result_NoneAPIErrorZ
close_channel_with_target_feerate(byte[] channel_id, int target_feerate_sats_per_1000_weight)
Begins the process of closing a channel.Result_NoneAPIErrorZ
create_channel(byte[] their_network_key, long channel_value_satoshis, long push_msat, long user_id, UserConfig override_config)
Creates a new outbound channel to the given remote node and with the given value.TwoTuple_PaymentHashPaymentSecretZ
create_inbound_payment(Option_u64Z min_value_msat, int invoice_expiry_delta_secs, long user_payment_id)
Gets a payment secret and payment hash for use in an invoice given to a third party wishing to pay us.Result_PaymentSecretAPIErrorZ
create_inbound_payment_for_hash(byte[] payment_hash, Option_u64Z min_value_msat, int invoice_expiry_delta_secs, long user_payment_id)
Gets a [`PaymentSecret`] for a given [`PaymentHash`], for which the payment preimage is stored external to LDK.BestBlock
current_best_block()
Gets the latest best block which was connected either via the [`chain::Listen`] or [`chain::Confirm`] interfaces.boolean
fail_htlc_backwards(byte[] payment_hash)
Indicates that the preimage for payment_hash is unknown or the received amount is incorrect after a PaymentReceived event, failing the HTLC back to its origin and freeing resources along the path (including in our own channel on which we received it).protected void
finalize()
void
force_close_all_channels()
Force close all channels, immediately broadcasting the latest local commitment transaction for each to the chain and rejecting new HTLCs on each.Result_NoneAPIErrorZ
force_close_channel(byte[] channel_id)
Force closes a channel, immediately broadcasting the latest local commitment transaction to the chain and rejecting new HTLCs on the given channel.Result_NoneAPIErrorZ
funding_transaction_generated(byte[] temporary_channel_id, byte[] funding_transaction)
Call this upon creation of a funding transaction for the given channel.UserConfig
get_current_default_configuration()
Gets the current configuration applied to all new channels, asbyte[]
get_our_node_id()
Gets the node_id held by this ChannelManagerChannelDetails[]
list_channels()
Gets the list of open channels, in random order.ChannelDetails[]
list_usable_channels()
Gets the list of usable channels, in random order.static ChannelManager
of(FeeEstimator fee_est, Watch chain_monitor, BroadcasterInterface tx_broadcaster, Logger logger, KeysInterface keys_manager, UserConfig config, ChainParameters params)
Constructs a new ChannelManager to hold several channels and route between them.void
process_pending_htlc_forwards()
Processes HTLCs which are pending waiting on random forward delay.Result_NonePaymentSendFailureZ
send_payment(Route route, byte[] payment_hash, byte[] payment_secret)
Sends a payment along a given route.Result_PaymentHashPaymentSendFailureZ
send_spontaneous_payment(Route route, byte[] payment_preimage)
Send a spontaneous payment, which is a payment that does not require the recipient to have generated an invoice.void
timer_tick_occurred()
Performs actions which should happen on startup and roughly once per minute thereafter.byte[]
write()
Serialize the ChannelManager object into a byte array which can be read by ChannelManager_read
-
-
-
Method Detail
-
finalize
protected void finalize() throws Throwable
-
of
public static ChannelManager of(FeeEstimator fee_est, Watch chain_monitor, BroadcasterInterface tx_broadcaster, Logger logger, KeysInterface keys_manager, UserConfig config, ChainParameters params)
Constructs a new ChannelManager to hold several channels and route between them. This is the main \"logic hub\" for all channel-related actions, and implements ChannelMessageHandler. Non-proportional fees are fixed according to our risk using the provided fee estimator. panics if channel_value_satoshis is >= `MAX_FUNDING_SATOSHIS`! Users need to notify the new ChannelManager when a new block is connected or disconnected using its `block_connected` and `block_disconnected` methods, starting from after `params.latest_hash`.
-
get_current_default_configuration
public UserConfig get_current_default_configuration()
Gets the current configuration applied to all new channels, as
-
create_channel
public Result_NoneAPIErrorZ create_channel(byte[] their_network_key, long channel_value_satoshis, long push_msat, long user_id, @Nullable UserConfig override_config)
Creates a new outbound channel to the given remote node and with the given value. user_id will be provided back as user_channel_id in FundingGenerationReady events to allow tracking of which events correspond with which create_channel call. Note that the user_channel_id defaults to 0 for inbound channels, so you may wish to avoid using 0 for user_id here. user_id has no meaning inside of LDK, it is simply copied to events and otherwise ignored. If successful, will generate a SendOpenChannel message event, so you should probably poll PeerManager::process_events afterwards. Raises APIError::APIMisuseError when channel_value_satoshis > 2**24 or push_msat is greater than channel_value_satoshis * 1k or channel_value_satoshis is < 1000. Note that we do not check if you are currently connected to the given peer. If no connection is available, the outbound `open_channel` message may fail to send, resulting in the channel eventually being silently forgotten. Note that override_config (or a relevant inner pointer) may be NULL or all-0s to represent None
-
list_channels
public ChannelDetails[] list_channels()
Gets the list of open channels, in random order. See ChannelDetail field documentation for more information.
-
list_usable_channels
public ChannelDetails[] list_usable_channels()
Gets the list of usable channels, in random order. Useful as an argument to get_route to ensure non-announced channels are used. These are guaranteed to have their [`ChannelDetails::is_usable`] value set to true, see the documentation for [`ChannelDetails::is_usable`] for more info on exactly what the criteria are.
-
close_channel
public Result_NoneAPIErrorZ close_channel(byte[] channel_id)
Begins the process of closing a channel. After this call (plus some timeout), no new HTLCs will be accepted on the given channel, and after additional timeout/the closing of all pending HTLCs, the channel will be closed on chain. If we are the channel initiator, we will pay between our [`Background`] and [`ChannelConfig::force_close_avoidance_max_fee_satoshis`] plus our [`Normal`] fee estimate. If our counterparty is the channel initiator, we will require a channel closing transaction feerate of at least our [`Background`] feerate or the feerate which would appear on a force-closure transaction, whichever is lower. We will allow our counterparty to pay as much fee as they'd like, however. May generate a SendShutdown message event on success, which should be relayed. [`ChannelConfig::force_close_avoidance_max_fee_satoshis`]: crate::util::config::ChannelConfig::force_close_avoidance_max_fee_satoshis [`Background`]: crate::chain::chaininterface::ConfirmationTarget::Background [`Normal`]: crate::chain::chaininterface::ConfirmationTarget::Normal
-
close_channel_with_target_feerate
public Result_NoneAPIErrorZ close_channel_with_target_feerate(byte[] channel_id, int target_feerate_sats_per_1000_weight)
Begins the process of closing a channel. After this call (plus some timeout), no new HTLCs will be accepted on the given channel, and after additional timeout/the closing of all pending HTLCs, the channel will be closed on chain. `target_feerate_sat_per_1000_weight` has different meanings depending on if we initiated the channel being closed or not: If we are the channel initiator, we will pay at least this feerate on the closing transaction. The upper-bound is set by [`ChannelConfig::force_close_avoidance_max_fee_satoshis`] plus our [`Normal`] fee estimate (or `target_feerate_sat_per_1000_weight`, if it is greater). If our counterparty is the channel initiator, we will refuse to accept a channel closure transaction feerate below `target_feerate_sat_per_1000_weight` (or the feerate which will appear on a force-closure transaction, whichever is lower). May generate a SendShutdown message event on success, which should be relayed. [`ChannelConfig::force_close_avoidance_max_fee_satoshis`]: crate::util::config::ChannelConfig::force_close_avoidance_max_fee_satoshis [`Background`]: crate::chain::chaininterface::ConfirmationTarget::Background [`Normal`]: crate::chain::chaininterface::ConfirmationTarget::Normal
-
force_close_channel
public Result_NoneAPIErrorZ force_close_channel(byte[] channel_id)
Force closes a channel, immediately broadcasting the latest local commitment transaction to the chain and rejecting new HTLCs on the given channel. Fails if channel_id is unknown to the manager.
-
force_close_all_channels
public void force_close_all_channels()
Force close all channels, immediately broadcasting the latest local commitment transaction for each to the chain and rejecting new HTLCs on each.
-
send_payment
public Result_NonePaymentSendFailureZ send_payment(Route route, byte[] payment_hash, @Nullable byte[] payment_secret)
Sends a payment along a given route. Value parameters are provided via the last hop in route, see documentation for RouteHop fields for more info. Note that if the payment_hash already exists elsewhere (eg you're sending a duplicative payment), we don't do anything to stop you! We always try to ensure that if the provided next hop knows the preimage to payment_hash they can claim an additional amount as specified in the last hop in the route! Thus, you should probably do your own payment_preimage tracking (which you should already be doing as they represent \"proof of payment\") and prevent double-sends yourself. May generate SendHTLCs message(s) event on success, which should be relayed. Each path may have a different return value, and PaymentSendValue may return a Vec with each entry matching the corresponding-index entry in the route paths, see PaymentSendFailure for more info. In general, a path may raise: APIError::RouteError when an invalid route or forwarding parameter (cltv_delta, fee, node public key) is specified. APIError::ChannelUnavailable if the next-hop channel is not available for updates (including due to previous monitor update failure or new permanent monitor update failure). APIError::MonitorUpdateFailed if a new monitor update failure prevented sending the relevant updates. Note that depending on the type of the PaymentSendFailure the HTLC may have been irrevocably committed to on our end. In such a case, do NOT retry the payment with a different route unless you intend to pay twice! payment_secret is unrelated to payment_hash (or PaymentPreimage) and exists to authenticate the sender to the recipient and prevent payment-probing (deanonymization) attacks. For newer nodes, it will be provided to you in the invoice. If you do not have one, the Route must not contain multiple paths as multi-path payments require a recipient-provided payment_secret. If a payment_secret *is* provided, we assume that the invoice had the payment_secret feature bit set (either as required or as available). If multiple paths are present in the Route, we assume the invoice had the basic_mpp feature set. Note that payment_secret (or a relevant inner pointer) may be NULL or all-0s to represent None
-
send_spontaneous_payment
public Result_PaymentHashPaymentSendFailureZ send_spontaneous_payment(Route route, @Nullable byte[] payment_preimage)
Send a spontaneous payment, which is a payment that does not require the recipient to have generated an invoice. Optionally, you may specify the preimage. If you do choose to specify the preimage, it must be a cryptographically secure random value that no intermediate node would be able to guess -- otherwise, an intermediate node may claim the payment and it will never reach the recipient. See [`send_payment`] documentation for more details on the return value of this function. Similar to regular payments, you MUST NOT reuse a `payment_preimage` value. See [`send_payment`] for more information about the risks of duplicate preimage usage. Note that `route` must have exactly one path. [`send_payment`]: Self::send_payment Note that payment_preimage (or a relevant inner pointer) may be NULL or all-0s to represent None
-
funding_transaction_generated
public Result_NoneAPIErrorZ funding_transaction_generated(byte[] temporary_channel_id, byte[] funding_transaction)
Call this upon creation of a funding transaction for the given channel. Returns an [`APIError::APIMisuseError`] if the funding_transaction spent non-SegWit outputs or if no output was found which matches the parameters in [`Event::FundingGenerationReady`]. Panics if a funding transaction has already been provided for this channel. May panic if the output found in the funding transaction is duplicative with some other channel (note that this should be trivially prevented by using unique funding transaction keys per-channel). Do NOT broadcast the funding transaction yourself. When we have safely received our counterparty's signature the funding transaction will automatically be broadcast via the [`BroadcasterInterface`] provided when this `ChannelManager` was constructed. Note that this includes RBF or similar transaction replacement strategies - lightning does not currently support replacing a funding transaction on an existing channel. Instead, create a new channel with a conflicting funding transaction. [`Event::FundingGenerationReady`]: crate::util::events::Event::FundingGenerationReady
-
broadcast_node_announcement
public void broadcast_node_announcement(byte[] rgb, byte[] alias, NetAddress[] addresses)
Regenerates channel_announcements and generates a signed node_announcement from the given arguments, providing them in corresponding events via [`get_and_clear_pending_msg_events`], if at least one public channel has been confirmed on-chain. This effectively re-broadcasts all channel announcements and sends our node announcement to ensure that the lightning P2P network is aware of the channels we have and our network addresses. `rgb` is a node \"color\" and `alias` is a printable human-readable string to describe this node to humans. They carry no in-protocol meaning. `addresses` represent the set (possibly empty) of socket addresses on which this node accepts incoming connections. These will be included in the node_announcement, publicly tying these addresses together and to this node. If you wish to preserve user privacy, addresses should likely contain only Tor Onion addresses. Panics if `addresses` is absurdly large (more than 500). [`get_and_clear_pending_msg_events`]: MessageSendEventsProvider::get_and_clear_pending_msg_events
-
process_pending_htlc_forwards
public void process_pending_htlc_forwards()
Processes HTLCs which are pending waiting on random forward delay. Should only really ever be called in response to a PendingHTLCsForwardable event. Will likely generate further events.
-
timer_tick_occurred
public void timer_tick_occurred()
Performs actions which should happen on startup and roughly once per minute thereafter. This currently includes: Increasing or decreasing the on-chain feerate estimates for our outbound channels, Broadcasting `ChannelUpdate` messages if we've been disconnected from our peer for more than a minute, informing the network that they should no longer attempt to route over the channel. Note that this may cause reentrancy through `chain::Watch::update_channel` calls or feerate estimate fetches.
-
fail_htlc_backwards
public boolean fail_htlc_backwards(byte[] payment_hash)
Indicates that the preimage for payment_hash is unknown or the received amount is incorrect after a PaymentReceived event, failing the HTLC back to its origin and freeing resources along the path (including in our own channel on which we received it). Returns false if no payment was found to fail backwards, true if the process of failing the HTLC backwards has been started.
-
claim_funds
public boolean claim_funds(byte[] payment_preimage)
Provides a payment preimage in response to a PaymentReceived event, returning true and generating message events for the net layer to claim the payment, if possible. Thus, you should probably kick the net layer to go send messages if this returns true! Note that if you did not set an `amount_msat` when calling [`create_inbound_payment`] or [`create_inbound_payment_for_hash`] you must check that the amount in the `PaymentReceived` event matches your expectation. If you fail to do so and call this method, you may provide the sender \"proof-of-payment\" when they did not fulfill the full expected payment. May panic if called except in response to a PaymentReceived event. [`create_inbound_payment`]: Self::create_inbound_payment [`create_inbound_payment_for_hash`]: Self::create_inbound_payment_for_hash
-
get_our_node_id
public byte[] get_our_node_id()
Gets the node_id held by this ChannelManager
-
channel_monitor_updated
public void channel_monitor_updated(OutPoint funding_txo, long highest_applied_update_id)
Restores a single, given channel to normal operation after a ChannelMonitorUpdateErr::TemporaryFailure was returned from a channel monitor update operation. All ChannelMonitor updates up to and including highest_applied_update_id must have been fully committed in every copy of the given channels' ChannelMonitors. Note that there is no effect to calling with a highest_applied_update_id other than the current latest ChannelMonitorUpdate and one call to this function after multiple ChannelMonitorUpdateErr::TemporaryFailures is fine. The highest_applied_update_id field exists largely only to prevent races between this and concurrent update_monitor calls. Thus, the anticipated use is, at a high level: 1) You register a chain::Watch with this ChannelManager, 2) it stores each update to disk, and begins updating any remote (eg watchtower) copies of said ChannelMonitors as it can, returning ChannelMonitorUpdateErr::TemporaryFailures any time it cannot do so instantly, 3) update(s) are applied to each remote copy of a ChannelMonitor, 4) once all remote copies are updated, you call this function with the update_id that completed, and once it is the latest the Channel will be re-enabled.
-
create_inbound_payment
public TwoTuple_PaymentHashPaymentSecretZ create_inbound_payment(Option_u64Z min_value_msat, int invoice_expiry_delta_secs, long user_payment_id)
Gets a payment secret and payment hash for use in an invoice given to a third party wishing to pay us. This differs from [`create_inbound_payment_for_hash`] only in that it generates the [`PaymentHash`] and [`PaymentPreimage`] for you, returning the first and storing the second. The [`PaymentPreimage`] will ultimately be returned to you in the [`PaymentReceived`], which will have the [`PaymentReceived::payment_preimage`] field filled in. That should then be passed directly to [`claim_funds`]. See [`create_inbound_payment_for_hash`] for detailed documentation on behavior and requirements. [`claim_funds`]: Self::claim_funds [`PaymentReceived`]: events::Event::PaymentReceived [`PaymentReceived::payment_preimage`]: events::Event::PaymentReceived::payment_preimage [`create_inbound_payment_for_hash`]: Self::create_inbound_payment_for_hash
-
create_inbound_payment_for_hash
public Result_PaymentSecretAPIErrorZ create_inbound_payment_for_hash(byte[] payment_hash, Option_u64Z min_value_msat, int invoice_expiry_delta_secs, long user_payment_id)
Gets a [`PaymentSecret`] for a given [`PaymentHash`], for which the payment preimage is stored external to LDK. A [`PaymentReceived`] event will only be generated if the [`PaymentSecret`] matches a payment secret fetched via this method or [`create_inbound_payment`], and which is at least the `min_value_msat` provided here, if one is provided. The [`PaymentHash`] (and corresponding [`PaymentPreimage`]) must be globally unique. This method may return an Err if another payment with the same payment_hash is still pending. `user_payment_id` will be provided back in [`PaymentPurpose::InvoicePayment::user_payment_id`] events to allow tracking of which events correspond with which calls to this and [`create_inbound_payment`]. `user_payment_id` has no meaning inside of LDK, it is simply copied to events and otherwise ignored. It may be used to correlate PaymentReceived events with invoice metadata stored elsewhere. `min_value_msat` should be set if the invoice being generated contains a value. Any payment received for the returned [`PaymentHash`] will be required to be at least `min_value_msat` before a [`PaymentReceived`] event will be generated, ensuring that we do not provide the sender \"proof-of-payment\" unless they have paid the required amount. `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for in excess of the current time. This should roughly match the expiry time set in the invoice. After this many seconds, we will remove the inbound payment, resulting in any attempts to pay the invoice failing. The BOLT spec suggests 3,600 secs as a default validity time for invoices when no timeout is set. Note that we use block header time to time-out pending inbound payments (with some margin to compensate for the inaccuracy of block header timestamps). Thus, in practice we will accept a payment and generate a [`PaymentReceived`] event for some time after the expiry. If you need exact expiry semantics, you should enforce them upon receipt of [`PaymentReceived`]. Pending inbound payments are stored in memory and in serialized versions of this [`ChannelManager`]. If potentially unbounded numbers of inbound payments may exist and space is limited, you may wish to rate-limit inbound payment creation. May panic if `invoice_expiry_delta_secs` is greater than one year. Note that invoices generated for inbound payments should have their `min_final_cltv_expiry` set to at least [`MIN_FINAL_CLTV_EXPIRY`]. [`create_inbound_payment`]: Self::create_inbound_payment [`PaymentReceived`]: events::Event::PaymentReceived [`PaymentPurpose::InvoicePayment::user_payment_id`]: events::PaymentPurpose::InvoicePayment::user_payment_id
-
as_MessageSendEventsProvider
public MessageSendEventsProvider as_MessageSendEventsProvider()
Constructs a new MessageSendEventsProvider which calls the relevant methods on this_arg. This copies the `inner` pointer in this_arg and thus the returned MessageSendEventsProvider 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
-
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
-
await_persistable_update_timeout
public boolean await_persistable_update_timeout(long max_wait)
Blocks until ChannelManager needs to be persisted or a timeout is reached. It returns a bool indicating whether persistence is necessary. Only one listener on `await_persistable_update` or `await_persistable_update_timeout` is guaranteed to be woken up. Note that the feature `allow_wallclock_use` must be enabled to use this function.
-
await_persistable_update
public void await_persistable_update()
Blocks until ChannelManager needs to be persisted. Only one listener on `await_persistable_update` or `await_persistable_update_timeout` is guaranteed to be woken up.
-
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.
-
as_ChannelMessageHandler
public ChannelMessageHandler as_ChannelMessageHandler()
Constructs a new ChannelMessageHandler which calls the relevant methods on this_arg. This copies the `inner` pointer in this_arg and thus the returned ChannelMessageHandler must be freed before this_arg is
-
write
public byte[] write()
Serialize the ChannelManager object into a byte array which can be read by ChannelManager_read
-
-