pub enum Event {
Show 29 variants
FundingGenerationReady {
temporary_channel_id: ChannelId,
counterparty_node_id: PublicKey,
channel_value_satoshis: u64,
output_script: ScriptBuf,
user_channel_id: u128,
},
FundingTxBroadcastSafe {
channel_id: ChannelId,
user_channel_id: u128,
funding_txo: OutPoint,
counterparty_node_id: PublicKey,
former_temporary_channel_id: ChannelId,
},
PaymentClaimable {
receiver_node_id: Option<PublicKey>,
payment_hash: PaymentHash,
onion_fields: Option<RecipientOnionFields>,
amount_msat: u64,
counterparty_skimmed_fee_msat: u64,
purpose: PaymentPurpose,
receiving_channel_ids: Vec<(ChannelId, Option<u128>)>,
claim_deadline: Option<u32>,
payment_id: Option<PaymentId>,
},
PaymentClaimed {
receiver_node_id: Option<PublicKey>,
payment_hash: PaymentHash,
amount_msat: u64,
purpose: PaymentPurpose,
htlcs: Vec<ClaimedHTLC>,
sender_intended_total_msat: Option<u64>,
onion_fields: Option<RecipientOnionFields>,
payment_id: Option<PaymentId>,
},
ConnectionNeeded {
node_id: PublicKey,
addresses: Vec<SocketAddress>,
},
InvoiceReceived {
payment_id: PaymentId,
invoice: Bolt12Invoice,
context: Option<OffersContext>,
responder: Option<Responder>,
},
PaymentSent {
payment_id: Option<PaymentId>,
payment_preimage: PaymentPreimage,
payment_hash: PaymentHash,
amount_msat: Option<u64>,
fee_paid_msat: Option<u64>,
bolt12_invoice: Option<PaidBolt12Invoice>,
},
PaymentFailed {
payment_id: PaymentId,
payment_hash: Option<PaymentHash>,
reason: Option<PaymentFailureReason>,
},
PaymentPathSuccessful {
payment_id: PaymentId,
payment_hash: Option<PaymentHash>,
path: Path,
hold_times: Vec<u32>,
},
PaymentPathFailed {
payment_id: Option<PaymentId>,
payment_hash: PaymentHash,
payment_failed_permanently: bool,
failure: PathFailure,
path: Path,
short_channel_id: Option<u64>,
hold_times: Vec<u32>,
},
ProbeSuccessful {
payment_id: PaymentId,
payment_hash: PaymentHash,
path: Path,
},
ProbeFailed {
payment_id: PaymentId,
payment_hash: PaymentHash,
path: Path,
short_channel_id: Option<u64>,
},
HTLCIntercepted {
intercept_id: InterceptId,
requested_next_hop_scid: u64,
payment_hash: PaymentHash,
inbound_amount_msat: u64,
expected_outbound_amount_msat: u64,
outgoing_htlc_expiry_block_height: Option<u32>,
},
SpendableOutputs {
outputs: Vec<SpendableOutputDescriptor>,
channel_id: Option<ChannelId>,
counterparty_node_id: Option<PublicKey>,
},
PaymentForwarded {
prev_htlcs: Vec<HTLCLocator>,
next_htlcs: Vec<HTLCLocator>,
total_fee_earned_msat: Option<u64>,
skimmed_fee_msat: Option<u64>,
claim_from_onchain_tx: bool,
outbound_amount_forwarded_msat: 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>,
funding_redeem_script: Option<ScriptBuf>,
},
ChannelReady {
channel_id: ChannelId,
user_channel_id: u128,
counterparty_node_id: PublicKey,
funding_txo: Option<OutPoint>,
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>,
last_local_balance_msat: Option<u64>,
},
SpliceNegotiated {
channel_id: ChannelId,
user_channel_id: u128,
counterparty_node_id: PublicKey,
new_funding_txo: OutPoint,
channel_type: ChannelTypeFeatures,
new_funding_redeem_script: ScriptBuf,
},
SpliceNegotiationFailed {
channel_id: ChannelId,
user_channel_id: u128,
counterparty_node_id: PublicKey,
reason: NegotiationFailureReason,
contribution: Option<FundingContribution>,
},
DiscardFunding {
channel_id: ChannelId,
funding_info: FundingInfo,
},
OpenChannelRequest {
temporary_channel_id: ChannelId,
counterparty_node_id: PublicKey,
funding_satoshis: u64,
channel_negotiation_type: InboundChannelFunds,
channel_type: ChannelTypeFeatures,
is_announced: bool,
params: ChannelParameters,
},
HTLCHandlingFailed {
prev_channel_ids: Vec<ChannelId>,
failure_type: HTLCHandlingFailureType,
failure_reason: Option<HTLCHandlingFailureReason>,
},
BumpTransaction(BumpTransactionEvent),
OnionMessageIntercepted {
prev_hop: Option<PublicKey>,
next_hop: NextMessageHop,
message: OnionMessage,
},
OnionMessagePeerConnected {
peer_node_id: PublicKey,
},
PersistStaticInvoice {
invoice: StaticInvoice,
invoice_request_path: BlindedMessagePath,
invoice_slot: u16,
recipient_id: Vec<u8>,
invoice_persisted_path: Responder,
},
StaticInvoiceRequested {
recipient_id: Vec<u8>,
invoice_slot: u16,
reply_path: Responder,
invoice_request: InvoiceRequest,
},
FundingTransactionReadyForSigning {
channel_id: ChannelId,
counterparty_node_id: PublicKey,
user_channel_id: u128,
unsigned_transaction: Transaction,
},
}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!
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())), but won’t be persisted across restarts.
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.
This may be zero for objects serialized with LDK versions prior to 0.0.113.
FundingTxBroadcastSafe
Used to indicate that the counterparty node has provided the signature(s) required to recover our funds in case they go offline.
It is safe (and your responsibility) to broadcast the funding transaction upon receiving this event.
This event is only emitted if you called
ChannelManager::unsafe_manual_funding_transaction_generated instead of
ChannelManager::funding_transaction_generated.
Fields
user_channel_id: u128The user_channel_id value passed in to ChannelManager::create_channel.
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.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
receiving_channel_ids: Vec<(ChannelId, Option<u128>)>The (channel_id, user_channel_id) pairs over which the payment was received.
This will be an incomplete vector for MPP payment events created/serialized using LDK version 0.1.0 and prior.
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.
payment_id: Option<PaymentId>A unique ID describing this payment (derived from the list of HTLCs in the payment).
Payers may pay for the same PaymentHash multiple times (though this is unsafe and
an intermediary node may steal the funds). Thus, in order to accurately track when
payments are received and claimed, you should use this identifier.
Only filled in for payments received on LDK versions 0.1 and higher.
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.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
sender_intended_total_msat: Option<u64>The sender-intended sum total of all the MPP parts. This will be None for events
serialized prior to LDK version 0.0.117.
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.124 will have this field unset.
payment_id: Option<PaymentId>A unique ID describing this payment (derived from the list of HTLCs in the payment).
Payers may pay for the same PaymentHash multiple times (though this is unsafe and
an intermediary node may steal the funds). Thus, in order to accurately track when
payments are received and claimed, you should use this identifier.
Only filled in for payments received on LDK versions 0.1 and higher.
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.
§Failure Behavior and Persistence
This event won’t be replayed after failures-to-handle
(i.e., the event handler returning Err(ReplayEvent ())), and also won’t be persisted
across restarts.
Fields
addresses: Vec<SocketAddress>Sockets for connecting to the node, if available. We don’t require these addresses to be present in case the node id corresponds to a known peer that is offline and can be awoken, such as via the LSPS5 protocol.
InvoiceReceived
Indicates a Bolt12Invoice in response to an InvoiceRequest or a Refund was
received.
This event will only be generated if UserConfig::manually_handle_bolt12_invoices is set.
Use ChannelManager::send_payment_for_bolt12_invoice to pay the invoice or
ChannelManager::abandon_payment to abandon the associated payment. See those docs for
further details.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
Fields
invoice: Bolt12InvoiceThe invoice to pay.
context: Option<OffersContext>The context of the BlindedMessagePath used to send the invoice.
responder: Option<Responder>A responder for replying with an InvoiceError if needed.
None if the invoice wasn’t sent with a reply path.
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.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
amount_msat: Option<u64>The total amount that was paid, across all paths.
Note that, like Route::get_total_amount, this does not include the paid fees.
This is only None for payments initiated on LDK versions prior to 0.2.
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.
This is only None for payments abandoned but ultimately claimed when using LDK versions
prior to 0.3, 0.2.3, or 0.1.10.
bolt12_invoice: Option<PaidBolt12Invoice>The paid BOLT 12 invoice bundled with the data needed to construct a
PayerProof, which selectively discloses invoice fields to prove payment to a
third party.
None for non-BOLT 12 payments.
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.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
Fields
payment_id: PaymentIdThe payment_id passed to ChannelManager::send_payment.
payment_hash: Option<PaymentHash>The hash that was given to ChannelManager::send_payment. None if the payment failed
before receiving an invoice when paying a BOLT12 Offer.
reason: Option<PaymentFailureReason>The reason the payment failed. This is only None for events generated or serialized
by versions prior to 0.0.115, or when downgrading to a version with a reason that was
added after.
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.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
path: PathThe payment path that was successful.
May contain a closed channel if the HTLC sent along the path was fulfilled on chain.
hold_times: Vec<u32>The time that each hop indicated it held the HTLC.
The unit in which the hold times are expressed are 100’s of milliseconds. So a hop reporting 2 is a hold time that corresponds to between 200 and 299 milliseconds.
We expect that at each hop the actual hold time will be strictly greater than the hold time of the following hops, as a node along the path shouldn’t have completed the HTLC until the next node has completed it. Note that because hold times are in 100’s of ms, hold times as reported are likely to often be equal across hops.
If our peer didn’t provide attribution data or the HTLC resolved on chain, the list will be empty.
Each entry will correspond with one entry in Path::hops, or, thereafter, the
BlindedTail::trampoline_hops in Path::blinded_tail. Because not all nodes
support hold times, the list may be shorter than the number of hops in the path.
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.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
hold_times: Vec<u32>The time that each hop indicated it held the HTLC.
The unit in which the hold times are expressed are 100’s of milliseconds. So a hop reporting 2 is a hold time that corresponds to between 200 and 299 milliseconds.
We expect that at each hop the actual hold time will be strictly greater than the hold time of the following hops, as a node along the path shouldn’t have completed the HTLC until the next node has completed it. Note that because hold times are in 100’s of ms, hold times as reported are likely to often be equal across hops.
If our peer didn’t provide attribution data or the HTLC resolved on chain, the list will be empty.
Each entry will correspond with one entry in Path::hops, or, thereafter, the
BlindedTail::trampoline_hops in Path::blinded_tail. Because not all nodes
support hold times, the list may be shorter than the number of hops in the path.
ProbeSuccessful
Indicates that a probe payment we sent returned successful, i.e., only failed at the destination.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
Fields
payment_id: PaymentIdThe id returned by ChannelManager::send_probe.
payment_hash: PaymentHashThe hash generated by ChannelManager::send_probe.
HTLCIntercepted
Used to indicate that we’ve intercepted an HTLC forward. This event will only be generated if
you’ve set some flags on UserConfig::htlc_interception_flags.
ChannelManager::forward_intercepted_htlc or
ChannelManager::fail_intercepted_htlc MUST be called in response to this event in a
timely manner (i.e. within some number of seconds, not minutes). See their docs for more
information.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
Fields
intercept_id: InterceptIdAn id to help LDK identify which HTLC is being forwarded or failed.
requested_next_hop_scid: u64The SCID which was selected by the sender as the next hop. It may point to one of our
channels, an intercept SCID generated with ChannelManager::get_intercept_scid, or
an unknown SCID if HTLCInterceptionFlags::ToUnknownSCIDs was selected.
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 (by comparing with
Self::HTLCIntercepted::inbound_amount_msat) or subtract it as required. Further,
LDK will not stop you from forwarding more than you received.
outgoing_htlc_expiry_block_height: Option<u32>The block height at which the forwarded HTLC sent to our peer will time out. In practice, LDK will refuse to forward an HTLC several blocks before this height (as if we attempted to forward an HTLC at this height we’d run some risk that our peer force-closes the channel immediately).
This will only be None for events generated or serialized by LDK 0.2 or prior.
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.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
Note that downgrading from 0.3 and above with pending trampoline forwards that use multipart payments will produce an event that only provides information about the first htlc that was received/dispatched.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
Fields
prev_htlcs: Vec<HTLCLocator>The set of HTLCs forwarded to our node that will be claimed by this forward. Contains a single HTLC for source-routed payments, and may contain multiple HTLCs when we acted as a trampoline router, responsible for pathfinding within the route.
next_htlcs: Vec<HTLCLocator>The set of HTLCs forwarded by our node that have been claimed by this forward. Contains a single HTLC for regular source-routed payments, and may contain multiple HTLCs when we acted as a trampoline router, responsible for pathfinding within the route.
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.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
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 when
- the initial funding transaction has been confirmed on-chain to an acceptable depth
according to both parties (i.e.,
channel_readymessages were exchanged), - a splice funding transaction has been confirmed on-chain to an acceptable depth according
to both parties (i.e.,
splice_lockedmessages were exchanged), or, - in case of a 0conf channel, when both parties have confirmed the channel establishment.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
funding_txo: Option<OutPoint>The outpoint of the channel’s funding transaction.
Will be None if the channel’s funding transaction reached an acceptable depth prior to
version 0.2.
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
Event::OpenChannelRequest was rejected, no ChannelClosed event will be sent.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
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.
channel_capacity_sats: Option<u64>Channel capacity of the closing channel (sats).
This field will be None for objects serialized prior to LDK 0.0.117.
channel_funding_txo: Option<OutPoint>The original channel funding TXO; this helps checking for the existence and confirmation status of the closing tx. Note that for instances serialized in v0.0.119 or prior this will be missing (None).
last_local_balance_msat: Option<u64>An upper bound on the our last local balance in msats before the channel was closed.
Will overstate our balance as it ignores pending outbound HTLCs and transaction fees.
For more accurate balances including fee information see
ChainMonitor::get_claimable_balances.
This field will be None only for objects serialized prior to LDK 0.1.
SpliceNegotiated
Used to indicate that a splice for the given channel_id has been negotiated, its
funding transaction has been broadcast, and local inputs or outputs were contributed to
it.
This event is not emitted if the counterparty negotiated a splice without using a local contribution.
The splice is then considered pending until both parties have seen enough confirmations to
consider the funding locked. Once this occurs, an Event::ChannelReady will be emitted.
Any UTXOs spent by the splice cannot be reused except by an RBF attempt for the same channel.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
channel_type: ChannelTypeFeaturesThe features that this channel will operate with. Currently, these will be the same features that the channel was opened with, but in the future splices may change them.
SpliceNegotiationFailed
Used to indicate that a splice negotiation round for the given channel_id has failed.
Each splice attempt (initial or RBF) resolves to this event on failure. On success,
Event::SpliceNegotiated is emitted if the negotiated transaction includes local
inputs or outputs. Prior successfully negotiated splice transactions are unaffected.
Any UTXOs contributed to the failed round that are not committed to a prior negotiated
splice transaction will be returned via a preceding Event::DiscardFunding.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
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.
reason: NegotiationFailureReasonThe reason the splice negotiation failed.
contribution: Option<FundingContribution>The funding contribution from the failed negotiation round, if available. This can be
fed back to ChannelManager::funding_contributed to retry with the same parameters.
Alternatively, call ChannelManager::splice_channel to obtain a fresh
FundingTemplate and build a new contribution.
The contribution preserves the full set of inputs and outputs from the failed round,
including any that were also committed to a prior negotiated (but not yet locked)
splice transaction. Those overlapping inputs and outputs are intentionally omitted
from the preceding Event::DiscardFunding, since they remain committed to that
prior splice.
DiscardFunding
Used to indicate to the user that they can abandon the funding transaction and recycle the inputs for another purpose.
When splicing, users can expect to receive an event for each negotiated splice transaction
that did not become locked. The negotiated splice transaction that became locked can be
obtained via Event::ChannelReady::funding_txo.
This event is not guaranteed to be generated for channels that are closed due to a restart.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
Fields
funding_info: FundingInfoThe full transaction received from the user
OpenChannelRequest
Indicates a request to open a new channel by a peer.
This event is triggered for all inbound requests to open a new channel.
To accept the request (and in the case of a dual-funded channel, not contribute funds),
call ChannelManager::accept_inbound_channel.
To reject the request, call ChannelManager::force_close_broadcasting_latest_txn.
Note that a ChannelClosed event will not be triggered if the channel is rejected.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and won’t be persisted across restarts.
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_broadcasting_latest_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_broadcasting_latest_txn
to reject the request.
channel_negotiation_type: InboundChannelFundsIf channel_negotiation_type is InboundChannelFunds::DualFunded, this indicates that the peer wishes to
open a dual-funded channel. Otherwise, this field will be InboundChannelFunds::PushMsats,
indicating the push_msats value our peer is pushing to us for a non-dual-funded channel.
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,
or will be rejected otherwise.
params: ChannelParametersChannel parameters given by the counterparty.
HTLCHandlingFailed
Indicates that the HTLC was accepted, but could not be processed when or after attempting to forward it.
Note that downgrading from 0.3 with pending trampoline forwards that have incoming multipart payments will produce an event that only provides information about the first htlc that was received/dispatched.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())) and will be persisted across restarts.
Fields
prev_channel_ids: Vec<ChannelId>The channel(s) over which the HTLC(s) was received. May contain multiple entries for trampoline forwards.
failure_type: HTLCHandlingFailureTypeThe type of HTLC handling that failed.
failure_reason: Option<HTLCHandlingFailureReason>The reason that the HTLC failed.
This field will be None only for objects serialized prior to LDK 0.2.0.
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 either the
ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx or the
ChannelHandshakeConfig::negotiate_anchor_zero_fee_commitments config flags are set to
true.
It is limited to the scope of channels with anchor outputs.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())), but will only be regenerated as needed after restarts.
OnionMessageIntercepted
We received an onion message that is intended to be forwarded to a peer that is currently offline or that is intended to be forwarded along a channel with an SCID unknown to us.
This event will only be generated if the OnionMessenger was initialized with
OnionMessenger::new_with_offline_peer_interception, see its docs. The
NextMessageHop::ShortChannelId variant is only generated if intercept_for_unknown_scids
was set when constructing the OnionMessenger.
The offline peer should be awoken if possible on receipt of this event, such as via the LSPS5 protocol.
Once they connect, you should handle the generated Event::OnionMessagePeerConnected and
provide the stored message.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())), but won’t be persisted across restarts.
Fields
prev_hop: Option<PublicKey>The node id of the peer that sent the message, if known.
This is None when the message is sent with
MessageSendInstructions::ForwardedMessage (e.g., when calling
OffersMessageFlow::enqueue_invoice_request_to_forward) rather than forwarded
internally by the OnionMessenger, as well as for events serialized prior to LDK 0.3.
Otherwise it is the node we received the message from.
next_hop: NextMessageHopThe next hop (offline peer or unknown SCID).
message: OnionMessageThe onion message intended to be forwarded to the offline peer or via the unknown channel once established.
OnionMessagePeerConnected
Indicates that an onion message supporting peer has come online and any messages previously
stored for them (from Event::OnionMessageIntercepteds) should be forwarded to them by
calling OnionMessenger::forward_onion_message.
This event will only be generated if the OnionMessenger was initialized with
OnionMessenger::new_with_offline_peer_interception, see its docs.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())), but won’t be persisted across restarts.
Fields
PersistStaticInvoice
As a static invoice server, we received a StaticInvoice from an async recipient that wants
us to serve the invoice to payers on their behalf when they are offline. This event will only
be generated if we previously created paths using
ChannelManager::blinded_paths_for_async_recipient and the recipient was configured with
them via ChannelManager::set_paths_to_static_invoice_server.
Fields
invoice: StaticInvoiceThe invoice that should be persisted and later provided to payers when handling a future
Event::StaticInvoiceRequested.
invoice_request_path: BlindedMessagePathThe path to where invoice requests will be forwarded. If we receive an invoice
request, we’ll forward it to the async recipient over this path in case the
recipient is online to provide a new invoice. This path should be persisted and
later provided to ChannelManager::respond_to_static_invoice_request.
This path’s BlindedMessagePath::introduction_node MUST be set to our node or one of our
peers. This is because, for DoS protection, invoice requests forwarded over this path are
treated by our node like any other onion message forward and will not generate
Event::ConnectionNeeded if the first hop in the path is not our peer.
If the next-hop peer in the path is offline, if configured to do so we will generate an
Event::OnionMessageIntercepted for the invoice request.
invoice_slot: u16Useful for the recipient to replace a specific invoice stored by us as the static invoice server.
When this invoice and its metadata are persisted, this slot number should be included so if
we receive another Event::PersistStaticInvoice containing the same slot number we can
swap the existing invoice out for the new one.
recipient_id: Vec<u8>An identifier for the recipient, originally provided to
ChannelManager::blinded_paths_for_async_recipient.
When an Event::StaticInvoiceRequested comes in for the invoice, this id will be surfaced
and can be used alongside the invoice_slot to retrieve the invoice from the database.
invoice_persisted_path: ResponderOnce the StaticInvoice and invoice_slot are persisted,
ChannelManager::static_invoice_persisted should be called with this responder to confirm
to the recipient that their Offer is ready to be used for async payments.
StaticInvoiceRequested
As a static invoice server, we received an InvoiceRequest on behalf of an often-offline
recipient for whom we are serving StaticInvoices.
This event will only be generated if we previously created paths using
ChannelManager::blinded_paths_for_async_recipient and the recipient was configured with
them via ChannelManager::set_paths_to_static_invoice_server.
If we previously persisted a StaticInvoice from an Event::PersistStaticInvoice that
matches the below recipient_id and invoice_slot, that invoice should be retrieved now
and forwarded to the payer via ChannelManager::respond_to_static_invoice_request.
The invoice request path previously persisted from Event::PersistStaticInvoice should
also be provided in ChannelManager::respond_to_static_invoice_request.
Fields
recipient_id: Vec<u8>An identifier for the recipient previously surfaced in
Event::PersistStaticInvoice::recipient_id. Useful when paired with the invoice_slot to
retrieve the StaticInvoice requested by the payer.
invoice_slot: u16The slot number for the invoice being requested, previously surfaced in
Event::PersistStaticInvoice::invoice_slot. Useful when paired with the recipient_id to
retrieve the StaticInvoice requested by the payer.
reply_path: ResponderThe path over which the StaticInvoice will be sent to the payer, which should be
provided to ChannelManager::respond_to_static_invoice_request along with the invoice.
invoice_request: InvoiceRequestThe invoice request that will be forwarded to the async recipient to give the
recipient a chance to provide an invoice in case it is online. It should be
provided to ChannelManager::respond_to_static_invoice_request.
FundingTransactionReadyForSigning
Indicates that a channel funding transaction constructed interactively is ready to be signed. This event will only be triggered if a contribution was made to the transaction.
The transaction contains all inputs and outputs provided by both parties including the channel’s funding output and a change output if applicable.
No part of the transaction should be changed before signing as the content of the transaction has already been negotiated with the counterparty.
Each signature MUST use the SIGHASH_ALL flag to avoid invalidation of the initial commitment and
hence possible loss of funds.
After signing, call ChannelManager::funding_transaction_signed with the (partially)
signed funding transaction. For splices where you contributed inputs or outputs, call
ChannelManager::cancel_funding_contributed instead if you no longer wish to proceed.
Generated in ChannelManager message handling.
§Failure Behavior and Persistence
This event will eventually be replayed after failures-to-handle (i.e., the event handler
returning Err(ReplayEvent ())), but will only be regenerated as needed after restarts.
Fields
channel_id: ChannelIdThe channel_id of the channel which you’ll need to pass back into
ChannelManager::funding_transaction_signed.
counterparty_node_id: PublicKeyThe counterparty’s node_id, which you’ll need to pass back into
ChannelManager::funding_transaction_signed.
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.
unsigned_transaction: TransactionThe unsigned transaction to be signed and passed back to
ChannelManager::funding_transaction_signed.