pub enum Event {
Show 13 variants
FundingGenerationReady {
temporary_channel_id: [u8; 32],
counterparty_node_id: PublicKey,
channel_value_satoshis: u64,
output_script: Script,
user_channel_id: u64,
},
PaymentReceived {
payment_hash: PaymentHash,
amount_msat: u64,
purpose: PaymentPurpose,
},
PaymentClaimed {
payment_hash: PaymentHash,
amount_msat: u64,
purpose: PaymentPurpose,
},
PaymentSent {
payment_id: Option<PaymentId>,
payment_preimage: PaymentPreimage,
payment_hash: PaymentHash,
fee_paid_msat: Option<u64>,
},
PaymentFailed {
payment_id: PaymentId,
payment_hash: PaymentHash,
},
PaymentPathSuccessful {
payment_id: PaymentId,
payment_hash: Option<PaymentHash>,
path: Vec<RouteHop>,
},
PaymentPathFailed {
payment_id: Option<PaymentId>,
payment_hash: PaymentHash,
rejected_by_dest: bool,
network_update: Option<NetworkUpdate>,
all_paths_failed: bool,
path: Vec<RouteHop>,
short_channel_id: Option<u64>,
retry: Option<RouteParameters>,
},
PendingHTLCsForwardable {
time_forwardable: Duration,
},
SpendableOutputs {
outputs: Vec<SpendableOutputDescriptor>,
},
PaymentForwarded {
prev_channel_id: Option<[u8; 32]>,
next_channel_id: Option<[u8; 32]>,
fee_earned_msat: Option<u64>,
claim_from_onchain_tx: bool,
},
ChannelClosed {
channel_id: [u8; 32],
user_channel_id: u64,
reason: ClosureReason,
},
DiscardFunding {
channel_id: [u8; 32],
transaction: Transaction,
},
OpenChannelRequest {
temporary_channel_id: [u8; 32],
counterparty_node_id: PublicKey,
funding_satoshis: u64,
push_msat: u64,
channel_type: ChannelTypeFeatures,
},
}
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
Fields
temporary_channel_id: [u8; 32]
The random channel_id we picked which you’ll need to pass into
ChannelManager::funding_transaction_generated
.
counterparty_node_id: PublicKey
The counterparty’s node_id, which you’ll need to pass back into
ChannelManager::funding_transaction_generated
.
channel_value_satoshis: u64
The value, in satoshis, that the output should have.
output_script: Script
The script which should be used in the transaction output.
user_channel_id: u64
The user_channel_id
value passed in to ChannelManager::create_channel
, or 0 for
an inbound channel.
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!
PaymentReceived
Fields
payment_hash: PaymentHash
The 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.
amount_msat: u64
The value, in thousandths of a satoshi, that this payment is for.
purpose: PaymentPurpose
Information for claiming this received payment, based on whether the purpose of the payment is to pay an invoice or to send a spontaneous payment.
Indicates we’ve received (an offer of) money! Just gotta dig out that payment preimage and
feed it to ChannelManager::claim_funds
to get it….
Note that if the preimage is not known, you should call
ChannelManager::fail_htlc_backwards
to free up resources for this HTLC and avoid
network congestion.
If you fail to call either ChannelManager::claim_funds
or
ChannelManager::fail_htlc_backwards
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
PaymentReceived
events may be generated for the same payment.
PaymentClaimed
Fields
payment_hash: PaymentHash
The payment hash of the claimed payment. Note that LDK will not stop you from registering duplicate payment hashes for inbound payments.
amount_msat: u64
The value, in thousandths of a satoshi, that this payment is for.
purpose: PaymentPurpose
The purpose of this claimed payment, i.e. whether the payment was for an invoice or a spontaneous payment.
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::PaymentReceived
. However, if we previously crashed during a
ChannelManager::claim_funds
call you may see this event without a corresponding
Event::PaymentReceived
event.
Note
LDK will not stop an inbound payment from being paid multiple times, so multiple
PaymentReceived
events may be generated for the same payment. If you then call
ChannelManager::claim_funds
twice for the same Event::PaymentReceived
you may get
multiple PaymentClaimed
events.
PaymentSent
Fields
payment_id: Option<PaymentId>
The id returned by ChannelManager::send_payment
and used with
ChannelManager::retry_payment
.
payment_preimage: PaymentPreimage
The 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: PaymentHash
The 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.
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.
PaymentFailed
Fields
payment_id: PaymentId
The id returned by ChannelManager::send_payment
and used with
ChannelManager::retry_payment
and ChannelManager::abandon_payment
.
payment_hash: PaymentHash
The hash that was given to ChannelManager::send_payment
.
Indicates an outbound payment failed. Individual Event::PaymentPathFailed
events
provide failure information for each MPP part in the payment.
This event is provided once there are no further pending HTLCs for the payment and the
payment is no longer retryable, either due to a several-block timeout or because
ChannelManager::abandon_payment
was previously called for the corresponding payment.
PaymentPathSuccessful
Fields
payment_id: PaymentId
The id returned by ChannelManager::send_payment
and used with
ChannelManager::retry_payment
.
payment_hash: Option<PaymentHash>
The hash that was given to ChannelManager::send_payment
.
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.
PaymentPathFailed
Fields
payment_id: Option<PaymentId>
The id returned by ChannelManager::send_payment
and used with
ChannelManager::retry_payment
and ChannelManager::abandon_payment
.
payment_hash: PaymentHash
The hash that was given to ChannelManager::send_payment
.
rejected_by_dest: bool
Indicates 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, you may retry the payment via a different route.
network_update: Option<NetworkUpdate>
Any failure information conveyed via the Onion return packet by a node along the failed payment route.
Should be applied to the NetworkGraph
so that routing decisions can take into
account the update.
all_paths_failed: bool
For both single-path and multi-path payments, this is set if all paths of the payment have failed. This will be set to false if (1) this is an MPP payment and (2) other parts of the larger MPP payment were still in flight when this event was generated.
Note that if you are retrying individual MPP parts, using this value to determine if a
payment has fully failed is race-y. Because multiple failures can happen prior to events
being processed, you may retry in response to a first failure, with a second failure
(with all_paths_failed
set) still pending. Then, when the second failure is processed
you will see all_paths_failed
set even though the retry of the first failure still
has an associated in-flight HTLC. See (1) for an example of such a failure.
If you wish to retry individual MPP parts and learn when a payment has failed, you must
call ChannelManager::abandon_payment
and wait for a Event::PaymentFailed
event.
(1) https://github.com/lightningdevkit/rust-lightning/issues/1164
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.
retry: Option<RouteParameters>
Parameters needed to compute a new Route
when retrying the failed payment path.
See find_route
for details.
Indicates an outbound HTLC we sent failed. Probably some intermediary node dropped something. You may wish to retry with a different route.
Note that this does not indicate that all paths for an MPP payment have failed, see
Event::PaymentFailed
and all_paths_failed
.
PendingHTLCsForwardable
Fields
time_forwardable: Duration
The minimum amount of time that should be waited prior to calling process_pending_htlc_forwards. To increase the effort required to correlate payments, you should wait a random amount of time in roughly the range (now + time_forwardable, now + 5*time_forwardable).
Used to indicate that ChannelManager::process_pending_htlc_forwards
should be called at
a time in the future.
SpendableOutputs
Fields
outputs: Vec<SpendableOutputDescriptor>
The outputs which you should store as spendable by you.
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 not ever be spent by rust-lightning, 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.
PaymentForwarded
Fields
prev_channel_id: Option<[u8; 32]>
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<[u8; 32]>
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.
fee_earned_msat: Option<u64>
The 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 fee_earned_msat
is
None
.
claim_from_onchain_tx: bool
If this is true
, the forwarded HTLC was claimed by our counterparty via an on-chain
transaction.
This event is generated when a payment has been successfully forwarded through us and a forwarding fee earned.
ChannelClosed
Fields
channel_id: [u8; 32]
The 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: u64
The 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 0 for an inbound channel.
This will always be zero for objects serialized with LDK versions prior to 0.0.102.
reason: ClosureReason
The reason the channel was closed.
Used to indicate that a previously opened channel with the given channel_id
is in the
process of closure.
DiscardFunding
Fields
transaction: Transaction
The full transaction received from the user
Used to indicate to the user that they can abandon the funding transaction and recycle the inputs for another purpose.
OpenChannelRequest
Fields
temporary_channel_id: [u8; 32]
The 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_channel
to reject.
counterparty_node_id: PublicKey
The 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_channel
to reject the
request.
funding_satoshis: u64
The channel value of the requested channel.
push_msat: u64
Our starting balance in the channel if the request is accepted, in milli-satoshi.
channel_type: ChannelTypeFeatures
The 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.
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_channel
.
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.
Trait Implementations
sourceimpl MaybeReadable for Event
impl MaybeReadable for Event
sourceimpl Writeable for Event
impl Writeable for Event
sourcefn write<W: Writer>(&self, writer: &mut W) -> Result<(), Error>
fn write<W: Writer>(&self, writer: &mut W) -> Result<(), Error>
Writes self out to the given Writer
sourcefn encode(&self) -> Vec<u8>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
fn encode(&self) -> Vec<u8>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
A: Allocator,
Writes self out to a Vec
sourcefn serialized_length(&self) -> usize
fn serialized_length(&self) -> usize
Gets the length of this object after it has been serialized. This can be overridden to optimize cases where we prepend an object with its length. Read more
Auto Trait Implementations
impl RefUnwindSafe for Event
impl Send for Event
impl Sync for Event
impl Unpin for Event
impl UnwindSafe for Event
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more