Enum lightning::util::events::Event

pub enum Event {
    FundingGenerationReady {
        temporary_channel_id: [u8; 32],
        counterparty_node_id: PublicKey,
        channel_value_satoshis: u64,
        output_script: Script,
        user_channel_id: u128,
    },
    PaymentClaimable {
        receiver_node_id: Option<PublicKey>,
        payment_hash: PaymentHash,
        amount_msat: u64,
        purpose: PaymentPurpose,
        via_channel_id: Option<[u8; 32]>,
        via_user_channel_id: Option<u128>,
    },
    PaymentClaimed {
        receiver_node_id: Option<PublicKey>,
        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,
        payment_failed_permanently: bool,
        failure: PathFailure,
        path: Vec<RouteHop>,
        short_channel_id: Option<u64>,
        retry: Option<RouteParameters>,
    },
    ProbeSuccessful {
        payment_id: PaymentId,
        payment_hash: PaymentHash,
        path: Vec<RouteHop>,
    },
    ProbeFailed {
        payment_id: PaymentId,
        payment_hash: PaymentHash,
        path: Vec<RouteHop>,
        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>,
    },
    PaymentForwarded {
        prev_channel_id: Option<[u8; 32]>,
        next_channel_id: Option<[u8; 32]>,
        fee_earned_msat: Option<u64>,
        claim_from_onchain_tx: bool,
    },
    ChannelReady {
        channel_id: [u8; 32],
        user_channel_id: u128,
        counterparty_node_id: PublicKey,
        channel_type: ChannelTypeFeatures,
    },
    ChannelClosed {
        channel_id: [u8; 32],
        user_channel_id: u128,
        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,
    },
    HTLCHandlingFailed {
        prev_channel_id: [u8; 32],
        failed_next_destination: HTLCDestination,
    },
}

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: u128

The user_channel_id value passed in to ChannelManager::create_channel, or a random value for an inbound channel. This may be zero for objects serialized with LDK versions prior to 0.0.113.

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!

PaymentClaimable

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: 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.

via_channel_id: Option<[u8; 32]>

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.

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 you fail to call either ChannelManager::claim_funds, 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.

Note

This event used to be called PaymentReceived in LDK versions 0.0.112 and earlier.

PaymentClaimed

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: 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 the 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::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.

PaymentSent

Fields

payment_id: Option<PaymentId>

The id returned by ChannelManager::send_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::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 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.

PaymentPathSuccessful

Fields

payment_id: PaymentId

The id returned by ChannelManager::send_payment.

payment_hash: Option<PaymentHash>

The hash that was given to ChannelManager::send_payment.

path: Vec<RouteHop>

The payment path that was successful.

May contain a closed channel if the HTLC sent along the path was fulfilled on chain.

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::abandon_payment.

payment_hash: PaymentHash

The hash that was given to ChannelManager::send_payment.

payment_failed_permanently: 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, the payment may be retried via a different route.

failure: PathFailure

Extra error details based on the failure type. May contain an update that needs to be applied to the NetworkGraph.

path: Vec<RouteHop>

The payment path that failed.

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 used by LDK to compute a new Route when retrying the failed payment path.

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.

ProbeSuccessful

Fields

payment_id: PaymentId

The id returned by ChannelManager::send_probe.

payment_hash: PaymentHash

The hash generated by ChannelManager::send_probe.

path: Vec<RouteHop>

The payment path that was successful.

Indicates that a probe payment we sent returned successful, i.e., only failed at the destination.

ProbeFailed

Fields

payment_id: PaymentId

The id returned by ChannelManager::send_probe.

payment_hash: PaymentHash

The hash generated by ChannelManager::send_probe.

path: Vec<RouteHop>

The payment path that failed.

short_channel_id: Option<u64>

The channel responsible for the failed probe.

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.

Indicates that a probe payment we sent failed at an intermediary node on the path.

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.

HTLCIntercepted

Fields

intercept_id: InterceptId

An id to help LDK identify which HTLC is being forwarded or failed.

requested_next_hop_scid: u64

The fake scid that was programmed as the next hop’s scid, generated using ChannelManager::get_intercept_scid.

payment_hash: PaymentHash

The payment hash used for this HTLC.

inbound_amount_msat: u64

How many msats were received on the inbound edge of this HTLC.

expected_outbound_amount_msat: u64

How 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.

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.

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.

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.

ChannelReady

Fields

channel_id: [u8; 32]

The channel_id of the channel that is ready.

user_channel_id: u128

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 randomized for an inbound channel.

counterparty_node_id: PublicKey

The node_id of the channel counterparty.

channel_type: ChannelTypeFeatures

The features that this channel will operate with.

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.

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: u128

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 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: 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

channel_id: [u8; 32]

The channel_id of the channel which has been closed.

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_without_broadcasting_txn 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_without_broadcasting_txn 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_without_broadcasting_txn.

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.

HTLCHandlingFailed

Fields

prev_channel_id: [u8; 32]

The channel over which the HTLC was received.

failed_next_destination: HTLCDestination

Destination of the HTLC that failed to be processed.

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.
• Claiming an amount for an MPP payment that exceeds the HTLC total
• 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).

Trait Implementations

impl Clone for Event

fn clone(&self) -> Event

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Event

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl MaybeReadable for Event

fn read<R: Read>(reader: &mut R) -> Result<Option<Self>, DecodeError>

Reads a Self in from the given Read.

impl PartialEq<Event> for Event

fn eq(&self, other: &Event) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Writeable for Event

fn write<W: Writer>(&self, writer: &mut W) -> Result<(), Error>

Writes self out to the given Writer.

fn encode(&self) -> Vec<u8>

Writes self out to a Vec<u8>.

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.

impl Eq for Event

impl StructuralEq for Event

impl StructuralPartialEq for Event