pub enum Event {
FundingGenerationReady {
temporary_channel_id: [u8; 32],
channel_value_satoshis: u64,
output_script: Script,
user_channel_id: u64,
},
PaymentReceived {
payment_hash: PaymentHash,
amt: u64,
purpose: PaymentPurpose,
},
PaymentSent {
payment_id: Option<PaymentId>,
payment_preimage: PaymentPreimage,
payment_hash: PaymentHash,
fee_paid_msat: Option<u64>,
},
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>,
},
PaymentFailed {
payment_id: PaymentId,
payment_hash: PaymentHash,
},
PendingHTLCsForwardable {
time_forwardable: Duration,
},
SpendableOutputs {
outputs: Vec<SpendableOutputDescriptor>,
},
PaymentForwarded {
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,
},
PaymentPathSuccessful {
payment_id: PaymentId,
payment_hash: Option<PaymentHash>,
path: Vec<RouteHop>,
},
OpenChannelRequest {
temporary_channel_id: [u8; 32],
counterparty_node_id: PublicKey,
funding_satoshis: u64,
push_msat: u64,
},
}
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.
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.
amt: 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 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.
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.
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. NetGraphMsgHandler
is capable of doing this.
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.
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
.
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.
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
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
, or 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 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.
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.
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 with ChannelManager::accept_inbound_channel
to accept,
or to ChannelManager::force_close_channel
to reject.
counterparty_node_id: PublicKey
The node_id of the counterparty requesting to open the channel.
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.
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 encode_with_len(&self) -> Vec<u8>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
fn encode_with_len(&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 · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcepub fn to_owned(&self) -> T
pub fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
sourcepub fn clone_into(&self, target: &mut T)
pub fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more