pub enum Event {
Show 22 variants
FundingGenerationReady {
temporary_channel_id: ChannelId,
counterparty_node_id: PublicKey,
channel_value_satoshis: u64,
output_script: ScriptBuf,
user_channel_id: u128,
},
PaymentClaimable {
receiver_node_id: Option<PublicKey>,
payment_hash: PaymentHash,
onion_fields: Option<RecipientOnionFields>,
amount_msat: u64,
counterparty_skimmed_fee_msat: u64,
purpose: PaymentPurpose,
via_channel_id: Option<ChannelId>,
via_user_channel_id: Option<u128>,
claim_deadline: Option<u32>,
},
PaymentClaimed {
receiver_node_id: Option<PublicKey>,
payment_hash: PaymentHash,
amount_msat: u64,
purpose: PaymentPurpose,
htlcs: Vec<ClaimedHTLC>,
sender_intended_total_msat: Option<u64>,
},
ConnectionNeeded {
node_id: PublicKey,
addresses: Vec<SocketAddress>,
},
InvoiceRequestFailed {
payment_id: PaymentId,
},
PaymentSent {
payment_id: Option<PaymentId>,
payment_preimage: PaymentPreimage,
payment_hash: PaymentHash,
fee_paid_msat: Option<u64>,
},
PaymentFailed {
payment_id: PaymentId,
payment_hash: PaymentHash,
reason: Option<PaymentFailureReason>,
},
PaymentPathSuccessful {
payment_id: PaymentId,
payment_hash: Option<PaymentHash>,
path: Path,
},
PaymentPathFailed {
payment_id: Option<PaymentId>,
payment_hash: PaymentHash,
payment_failed_permanently: bool,
failure: PathFailure,
path: Path,
short_channel_id: Option<u64>,
},
ProbeSuccessful {
payment_id: PaymentId,
payment_hash: PaymentHash,
path: Path,
},
ProbeFailed {
payment_id: PaymentId,
payment_hash: PaymentHash,
path: Path,
short_channel_id: Option<u64>,
},
PendingHTLCsForwardable {
time_forwardable: Duration,
},
HTLCIntercepted {
intercept_id: InterceptId,
requested_next_hop_scid: u64,
payment_hash: PaymentHash,
inbound_amount_msat: u64,
expected_outbound_amount_msat: u64,
},
SpendableOutputs {
outputs: Vec<SpendableOutputDescriptor>,
channel_id: Option<ChannelId>,
},
PaymentForwarded {
prev_channel_id: Option<ChannelId>,
next_channel_id: Option<ChannelId>,
prev_user_channel_id: Option<u128>,
next_user_channel_id: Option<u128>,
total_fee_earned_msat: Option<u64>,
skimmed_fee_msat: Option<u64>,
claim_from_onchain_tx: bool,
outbound_amount_forwarded_msat: Option<u64>,
},
ChannelPending {
channel_id: ChannelId,
user_channel_id: u128,
former_temporary_channel_id: Option<ChannelId>,
counterparty_node_id: PublicKey,
funding_txo: OutPoint,
channel_type: Option<ChannelTypeFeatures>,
},
ChannelReady {
channel_id: ChannelId,
user_channel_id: u128,
counterparty_node_id: PublicKey,
channel_type: ChannelTypeFeatures,
},
ChannelClosed {
channel_id: ChannelId,
user_channel_id: u128,
reason: ClosureReason,
counterparty_node_id: Option<PublicKey>,
channel_capacity_sats: Option<u64>,
channel_funding_txo: Option<OutPoint>,
},
DiscardFunding {
channel_id: ChannelId,
transaction: Transaction,
},
OpenChannelRequest {
temporary_channel_id: ChannelId,
counterparty_node_id: PublicKey,
funding_satoshis: u64,
push_msat: u64,
channel_type: ChannelTypeFeatures,
},
HTLCHandlingFailed {
prev_channel_id: ChannelId,
failed_next_destination: HTLCDestination,
},
BumpTransaction(BumpTransactionEvent),
}Expand description
An Event which you should probably take some action in response to.
Note that while Writeable and Readable are implemented for Event, you probably shouldn’t use them directly as they don’t round-trip exactly (for example FundingGenerationReady is never written as it makes no sense to respond to it after reconnecting to peers).
Variants§
FundingGenerationReady
Used to indicate that the client should generate a funding transaction with the given
parameters and then call ChannelManager::funding_transaction_generated.
Generated in ChannelManager message handling.
Note that all inputs in the funding transaction must spend SegWit outputs or your
counterparty can steal your funds!
Fields
temporary_channel_id: ChannelIdThe random channel_id we picked which you’ll need to pass into
ChannelManager::funding_transaction_generated.
counterparty_node_id: PublicKeyThe counterparty’s node_id, which you’ll need to pass back into
ChannelManager::funding_transaction_generated.
user_channel_id: u128The user_channel_id value passed in to ChannelManager::create_channel for outbound
channels, or to ChannelManager::accept_inbound_channel for inbound channels if
UserConfig::manually_accept_inbound_channels config flag is set to true. Otherwise
user_channel_id will be randomized for an inbound channel. This may be zero for objects
serialized with LDK versions prior to 0.0.113.
PaymentClaimable
Indicates that we’ve been offered a payment and it needs to be claimed via calling
ChannelManager::claim_funds with the preimage given in PaymentPurpose.
Note that if the preimage is not known, you should call
ChannelManager::fail_htlc_backwards or ChannelManager::fail_htlc_backwards_with_reason
to free up resources for this HTLC and avoid network congestion.
If Event::PaymentClaimable::onion_fields is Some, and includes custom TLVs with even type
numbers, you should use ChannelManager::fail_htlc_backwards_with_reason with
FailureCode::InvalidOnionPayload if you fail to understand and handle the contents, or
ChannelManager::claim_funds_with_known_custom_tlvs upon successful handling.
If you don’t intend to check for custom TLVs, you can simply use
ChannelManager::claim_funds, which will automatically fail back even custom TLVs.
If you fail to call ChannelManager::claim_funds,
ChannelManager::claim_funds_with_known_custom_tlvs,
ChannelManager::fail_htlc_backwards, or
ChannelManager::fail_htlc_backwards_with_reason within the HTLC’s timeout, the HTLC will
be automatically failed.
§Note
LDK will not stop an inbound payment from being paid multiple times, so multiple
PaymentClaimable events may be generated for the same payment. In such a case it is
polite (and required in the lightning specification) to fail the payment the second time
and give the sender their money back rather than accepting double payment.
§Note
This event used to be called PaymentReceived in LDK versions 0.0.112 and earlier.
Fields
receiver_node_id: Option<PublicKey>The node that will receive the payment after it has been claimed. This is useful to identify payments received via phantom nodes. This field will always be filled in when the event was generated by LDK versions 0.0.113 and above.
payment_hash: PaymentHashThe hash for which the preimage should be handed to the ChannelManager. Note that LDK will not stop you from registering duplicate payment hashes for inbound payments.
onion_fields: Option<RecipientOnionFields>The fields in the onion which were received with each HTLC. Only fields which were identical in each HTLC involved in the payment will be included here.
Payments received on LDK versions prior to 0.0.115 will have this field unset.
amount_msat: u64The value, in thousandths of a satoshi, that this payment is claimable for. May be greater than the invoice amount.
May be less than the invoice amount if ChannelConfig::accept_underpaying_htlcs is set
and the previous hop took an extra fee.
§Note
If ChannelConfig::accept_underpaying_htlcs is set and you claim without verifying this
field, you may lose money!
counterparty_skimmed_fee_msat: u64The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee taken by our channel counterparty.
Will always be 0 unless ChannelConfig::accept_underpaying_htlcs is set.
purpose: PaymentPurposeInformation for claiming this received payment, based on whether the purpose of the payment is to pay an invoice or to send a spontaneous payment.
via_channel_id: Option<ChannelId>The channel_id indicating over which channel we received the payment.
via_user_channel_id: Option<u128>The user_channel_id indicating over which channel we received the payment.
claim_deadline: Option<u32>The block height at which this payment will be failed back and will no longer be eligible for claiming.
Prior to this height, a call to ChannelManager::claim_funds is guaranteed to
succeed, however you should wait for Event::PaymentClaimed to be sure.
PaymentClaimed
Indicates a payment has been claimed and we’ve received money!
This most likely occurs when ChannelManager::claim_funds has been called in response
to an Event::PaymentClaimable. However, if we previously crashed during a
ChannelManager::claim_funds call you may see this event without a corresponding
Event::PaymentClaimable event.
§Note
LDK will not stop an inbound payment from being paid multiple times, so multiple
PaymentClaimable events may be generated for the same payment. If you then call
ChannelManager::claim_funds twice for the same Event::PaymentClaimable you may get
multiple PaymentClaimed events.
Fields
receiver_node_id: Option<PublicKey>The node that received the payment. This is useful to identify payments which were received via phantom nodes. This field will always be filled in when the event was generated by LDK versions 0.0.113 and above.
payment_hash: PaymentHashThe payment hash of the claimed payment. Note that LDK will not stop you from registering duplicate payment hashes for inbound payments.
amount_msat: u64The value, in thousandths of a satoshi, that this payment is for. May be greater than the invoice amount.
purpose: PaymentPurposeThe purpose of the claimed payment, i.e. whether the payment was for an invoice or a spontaneous payment.
htlcs: Vec<ClaimedHTLC>The HTLCs that comprise the claimed payment. This will be empty for events serialized prior to LDK version 0.0.117.
ConnectionNeeded
Indicates that a peer connection with a node is needed in order to send an OnionMessage.
Typically, this happens when a MessageRouter is unable to find a complete path to a
Destination. Once a connection is established, any messages buffered by an
OnionMessageHandler may be sent.
This event will not be generated for onion message forwards; only for sends including replies. Handlers should connect to the node otherwise any buffered messages may be lost.
Fields
addresses: Vec<SocketAddress>Sockets for connecting to the node.
InvoiceRequestFailed
Indicates a request for an invoice failed to yield a response in a reasonable amount of time
or was explicitly abandoned by ChannelManager::abandon_payment. This may be for an
InvoiceRequest sent for an Offer or for a Refund that hasn’t been redeemed.
Fields
PaymentSent
Indicates an outbound payment we made succeeded (i.e. it made it all the way to its target and we got back the payment preimage for it).
Note for MPP payments: in rare cases, this event may be preceded by a PaymentPathFailed
event. In this situation, you SHOULD treat this payment as having succeeded.
Fields
payment_id: Option<PaymentId>The payment_id passed to ChannelManager::send_payment.
payment_preimage: PaymentPreimageThe preimage to the hash given to ChannelManager::send_payment. Note that this serves as a payment receipt, if you wish to have such a thing, you must store it somehow!
payment_hash: PaymentHashThe hash that was given to ChannelManager::send_payment.
fee_paid_msat: Option<u64>The total fee which was spent at intermediate hops in this payment, across all paths.
Note that, like Route::get_total_fees this does not include any potential
overpayment to the recipient node.
If the recipient or an intermediate node misbehaves and gives us free money, this may overstate the amount paid, though this is unlikely.
PaymentFailed
Indicates an outbound payment failed. Individual Event::PaymentPathFailed events
provide failure information for each path attempt in the payment, including retries.
This event is provided once there are no further pending HTLCs for the payment and the
payment is no longer retryable, due either to the Retry provided or
ChannelManager::abandon_payment having been called for the corresponding payment.
In exceedingly rare cases, it is possible that an Event::PaymentFailed is generated for
a payment after an Event::PaymentSent event for this same payment has already been
received and processed. In this case, the Event::PaymentFailed event MUST be ignored,
and the payment MUST be treated as having succeeded.
Fields
payment_id: PaymentIdThe payment_id passed to ChannelManager::send_payment.
payment_hash: PaymentHashThe hash that was given to ChannelManager::send_payment.
reason: Option<PaymentFailureReason>The reason the payment failed. This is only None for events generated or serialized
by versions prior to 0.0.115.
PaymentPathSuccessful
Indicates that a path for an outbound payment was successful.
Always generated after Event::PaymentSent and thus useful for scoring channels. See
Event::PaymentSent for obtaining the payment preimage.
Fields
payment_id: PaymentIdThe payment_id passed to ChannelManager::send_payment.
payment_hash: Option<PaymentHash>The hash that was given to ChannelManager::send_payment.
This will be Some for all payments which completed on LDK 0.0.104 or later.
PaymentPathFailed
Indicates an outbound HTLC we sent failed, likely due to an intermediary node being unable to handle the HTLC.
Note that this does not indicate that all paths for an MPP payment have failed, see
Event::PaymentFailed.
See ChannelManager::abandon_payment for giving up on this payment before its retries have
been exhausted.
Fields
payment_id: Option<PaymentId>The payment_id passed to ChannelManager::send_payment.
This will be Some for all payment paths which failed on LDK 0.0.103 or later.
payment_hash: PaymentHashThe hash that was given to ChannelManager::send_payment.
payment_failed_permanently: boolIndicates the payment was rejected for some reason by the recipient. This implies that the payment has failed, not just the route in question. If this is not set, the payment may be retried via a different route.
failure: PathFailureExtra error details based on the failure type. May contain an update that needs to be
applied to the NetworkGraph.
short_channel_id: Option<u64>The channel responsible for the failed payment path.
Note that for route hints or for the first hop in a path this may be an SCID alias and may not refer to a channel in the public network graph. These aliases may also collide with channels in the public network graph.
If this is Some, then the corresponding channel should be avoided when the payment is
retried. May be None for older Event serializations.
ProbeSuccessful
Indicates that a probe payment we sent returned successful, i.e., only failed at the destination.
Fields
payment_id: PaymentIdThe id returned by ChannelManager::send_probe.
payment_hash: PaymentHashThe hash generated by ChannelManager::send_probe.
ProbeFailed
Indicates that a probe payment we sent failed at an intermediary node on the path.
Fields
payment_id: PaymentIdThe id returned by ChannelManager::send_probe.
payment_hash: PaymentHashThe hash generated by ChannelManager::send_probe.
PendingHTLCsForwardable
Used to indicate that ChannelManager::process_pending_htlc_forwards should be called at
a time in the future.
Fields
HTLCIntercepted
Used to indicate that we’ve intercepted an HTLC forward. This event will only be generated if
you’ve encoded an intercept scid in the receiver’s invoice route hints using
ChannelManager::get_intercept_scid and have set UserConfig::accept_intercept_htlcs.
ChannelManager::forward_intercepted_htlc or
ChannelManager::fail_intercepted_htlc MUST be called in response to this event. See
their docs for more information.
Fields
intercept_id: InterceptIdAn id to help LDK identify which HTLC is being forwarded or failed.
requested_next_hop_scid: u64The fake scid that was programmed as the next hop’s scid, generated using
ChannelManager::get_intercept_scid.
payment_hash: PaymentHashThe payment hash used for this HTLC.
expected_outbound_amount_msat: u64How many msats the payer intended to route to the next node. Depending on the reason you are intercepting this payment, you might take a fee by forwarding less than this amount. Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116.
Note that LDK will NOT check that expected fees were factored into this value. You MUST check that whatever fee you want has been included here or subtract it as required. Further, LDK will not stop you from forwarding more than you received.
SpendableOutputs
Used to indicate that an output which you should know how to spend was confirmed on chain and is now spendable.
Such an output will never be spent directly by LDK, and are not at risk of your counterparty spending them due to some kind of timeout. Thus, you need to store them somewhere and spend them when you create on-chain transactions.
You may hand them to the OutputSweeper utility which will store and (re-)generate spending
transactions for you.
Fields
outputs: Vec<SpendableOutputDescriptor>The outputs which you should store as spendable by you.
PaymentForwarded
This event is generated when a payment has been successfully forwarded through us and a forwarding fee earned.
Fields
prev_channel_id: Option<ChannelId>The channel id of the incoming channel between the previous node and us.
This is only None for events generated or serialized by versions prior to 0.0.107.
next_channel_id: Option<ChannelId>The channel id of the outgoing channel between the next node and us.
This is only None for events generated or serialized by versions prior to 0.0.107.
prev_user_channel_id: Option<u128>The user_channel_id of the incoming channel between the previous node and us.
This is only None for events generated or serialized by versions prior to 0.0.122.
next_user_channel_id: Option<u128>The user_channel_id of the outgoing channel between the next node and us.
This will be None if the payment was settled via an on-chain transaction. See the
caveat described for the total_fee_earned_msat field. Moreover it will be None for
events generated or serialized by versions prior to 0.0.122.
total_fee_earned_msat: Option<u64>The total fee, in milli-satoshis, which was earned as a result of the payment.
Note that if we force-closed the channel over which we forwarded an HTLC while the HTLC
was pending, the amount the next hop claimed will have been rounded down to the nearest
whole satoshi. Thus, the fee calculated here may be higher than expected as we still
claimed the full value in millisatoshis from the source. In this case,
claim_from_onchain_tx will be set.
If the channel which sent us the payment has been force-closed, we will claim the funds
via an on-chain transaction. In that case we do not yet know the on-chain transaction
fees which we will spend and will instead set this to None. It is possible duplicate
PaymentForwarded events are generated for the same payment iff total_fee_earned_msat is
None.
skimmed_fee_msat: Option<u64>The share of the total fee, in milli-satoshis, which was withheld in addition to the forwarding fee.
This will only be Some if we forwarded an intercepted HTLC with less than the
expected amount. This means our counterparty accepted to receive less than the invoice
amount, e.g., by claiming the payment featuring a corresponding
PaymentClaimable::counterparty_skimmed_fee_msat.
Will also always be None for events serialized with LDK prior to version 0.0.122.
The caveat described above the total_fee_earned_msat field applies here as well.
ChannelPending
Used to indicate that a channel with the given channel_id is being opened and pending
confirmation on-chain.
This event is emitted when the funding transaction has been signed and is broadcast to the
network. For 0conf channels it will be immediately followed by the corresponding
Event::ChannelReady event.
Fields
user_channel_id: u128The user_channel_id value passed in to ChannelManager::create_channel for outbound
channels, or to ChannelManager::accept_inbound_channel for inbound channels if
UserConfig::manually_accept_inbound_channels config flag is set to true. Otherwise
user_channel_id will be randomized for an inbound channel.
former_temporary_channel_id: Option<ChannelId>The temporary_channel_id this channel used to be known by during channel establishment.
Will be None for channels created prior to LDK version 0.0.115.
channel_type: Option<ChannelTypeFeatures>The features that this channel will operate with.
Will be None for channels created prior to LDK version 0.0.122.
ChannelReady
Used to indicate that a channel with the given channel_id is ready to
be used. This event is emitted either when the funding transaction has been confirmed
on-chain, or, in case of a 0conf channel, when both parties have confirmed the channel
establishment.
Fields
user_channel_id: u128The user_channel_id value passed in to ChannelManager::create_channel for outbound
channels, or to ChannelManager::accept_inbound_channel for inbound channels if
UserConfig::manually_accept_inbound_channels config flag is set to true. Otherwise
user_channel_id will be randomized for an inbound channel.
channel_type: ChannelTypeFeaturesThe features that this channel will operate with.
ChannelClosed
Used to indicate that a channel that got past the initial handshake with the given channel_id is in the
process of closure. This includes previously opened channels, and channels that time out from not being funded.
Note that this event is only triggered for accepted channels: if the
UserConfig::manually_accept_inbound_channels config flag is set to true and the channel is
rejected, no ChannelClosed event will be sent.
Fields
channel_id: ChannelIdThe channel_id of the channel which has been closed. Note that on-chain transactions
resolving the channel are likely still awaiting confirmation.
user_channel_id: u128The user_channel_id value passed in to ChannelManager::create_channel for outbound
channels, or to ChannelManager::accept_inbound_channel for inbound channels if
UserConfig::manually_accept_inbound_channels config flag is set to true. Otherwise
user_channel_id will be randomized for inbound channels.
This may be zero for inbound channels serialized prior to 0.0.113 and will always be
zero for objects serialized with LDK versions prior to 0.0.102.
reason: ClosureReasonThe reason the channel was closed.
counterparty_node_id: Option<PublicKey>Counterparty in the closed channel.
This field will be None for objects serialized prior to LDK 0.0.117.
DiscardFunding
Used to indicate to the user that they can abandon the funding transaction and recycle the inputs for another purpose.
This event is not guaranteed to be generated for channels that are closed due to a restart.
Fields
transaction: TransactionThe full transaction received from the user
OpenChannelRequest
Indicates a request to open a new channel by a peer.
To accept the request, call ChannelManager::accept_inbound_channel. To reject the request,
call ChannelManager::force_close_without_broadcasting_txn. Note that a [’ChannelClosed`]
event will not be triggered if the channel is rejected.
The event is only triggered when a new open channel request is received and the
UserConfig::manually_accept_inbound_channels config flag is set to true.
Fields
temporary_channel_id: ChannelIdThe temporary channel ID of the channel requested to be opened.
When responding to the request, the temporary_channel_id should be passed
back to the ChannelManager through ChannelManager::accept_inbound_channel to accept,
or through ChannelManager::force_close_without_broadcasting_txn to reject.
counterparty_node_id: PublicKeyThe node_id of the counterparty requesting to open the channel.
When responding to the request, the counterparty_node_id should be passed
back to the ChannelManager through ChannelManager::accept_inbound_channel to
accept the request, or through ChannelManager::force_close_without_broadcasting_txn to reject the
request.
channel_type: ChannelTypeFeaturesThe features that this channel will operate with. If you reject the channel, a well-behaved counterparty may automatically re-attempt the channel with a new set of feature flags.
Note that if ChannelTypeFeatures::supports_scid_privacy returns true on this type,
the resulting ChannelManager will not be readable by versions of LDK prior to
0.0.106.
Furthermore, note that if ChannelTypeFeatures::supports_zero_conf returns true on this type,
the resulting ChannelManager will not be readable by versions of LDK prior to
0.0.107. Channels setting this type also need to get manually accepted via
crate::ln::channelmanager::ChannelManager::accept_inbound_channel_from_trusted_peer_0conf,
or will be rejected otherwise.
HTLCHandlingFailed
Indicates that the HTLC was accepted, but could not be processed when or after attempting to forward it.
Some scenarios where this event may be sent include:
- Insufficient capacity in the outbound channel
- While waiting to forward the HTLC, the channel it is meant to be forwarded through closes
- When an unknown SCID is requested for forwarding a payment.
- Expected MPP amount has already been reached
- The HTLC has timed out
This event, however, does not get generated if an HTLC fails to meet the forwarding requirements (i.e. insufficient fees paid, or a CLTV that is too soon).
Fields
failed_next_destination: HTLCDestinationDestination of the HTLC that failed to be processed.
BumpTransaction(BumpTransactionEvent)
Indicates that a transaction originating from LDK needs to have its fee bumped. This event requires confirmed external funds to be readily available to spend.
LDK does not currently generate this event unless the
ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx config flag is set to true.
It is limited to the scope of channels with anchor outputs.