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

path: Vec<RouteHop>

The payment path that failed.

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

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.

PaymentPathSuccessful

Fields

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

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Reads a Self in from the given Read

Writes self out to the given Writer

Writes self out to a Vec

Writes self out to a Vec

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

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.