Enum breez_sdk_core::lightning::events::Event

pub enum Event {
Show 21 variants    FundingGenerationReady {
        temporary_channel_id: ChannelId,
        counterparty_node_id: PublicKey,
        channel_value_satoshis: u64,
        output_script: Script,
        user_channel_id: u128,
    },
    PaymentClaimable {
        receiver_node_id: Option<PublicKey>,
        payment_hash: PaymentHash,
        onion_fields: Option<RecipientOnionFields>,
        amount_msat: u64,
        counterparty_skimmed_fee_msat: u64,
        purpose: PaymentPurpose,
        via_channel_id: Option<ChannelId>,
        via_user_channel_id: Option<u128>,
        claim_deadline: Option<u32>,
    },
    PaymentClaimed {
        receiver_node_id: Option<PublicKey>,
        payment_hash: PaymentHash,
        amount_msat: u64,
        purpose: PaymentPurpose,
        htlcs: Vec<ClaimedHTLC>,
        sender_intended_total_msat: Option<u64>,
    },
    InvoiceRequestFailed {
        payment_id: PaymentId,
    },
    PaymentSent {
        payment_id: Option<PaymentId>,
        payment_preimage: PaymentPreimage,
        payment_hash: PaymentHash,
        fee_paid_msat: Option<u64>,
    },
    PaymentFailed {
        payment_id: PaymentId,
        payment_hash: PaymentHash,
        reason: Option<PaymentFailureReason>,
    },
    PaymentPathSuccessful {
        payment_id: PaymentId,
        payment_hash: Option<PaymentHash>,
        path: Path,
    },
    PaymentPathFailed {
        payment_id: Option<PaymentId>,
        payment_hash: PaymentHash,
        payment_failed_permanently: bool,
        failure: PathFailure,
        path: Path,
        short_channel_id: Option<u64>,
    },
    ProbeSuccessful {
        payment_id: PaymentId,
        payment_hash: PaymentHash,
        path: Path,
    },
    ProbeFailed {
        payment_id: PaymentId,
        payment_hash: PaymentHash,
        path: Path,
        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>,
        channel_id: Option<ChannelId>,
    },
    PaymentForwarded {
        prev_channel_id: Option<ChannelId>,
        next_channel_id: Option<ChannelId>,
        fee_earned_msat: Option<u64>,
        claim_from_onchain_tx: bool,
        outbound_amount_forwarded_msat: Option<u64>,
    },
    ChannelPending {
        channel_id: ChannelId,
        user_channel_id: u128,
        former_temporary_channel_id: Option<ChannelId>,
        counterparty_node_id: PublicKey,
        funding_txo: OutPoint,
    },
    ChannelReady {
        channel_id: ChannelId,
        user_channel_id: u128,
        counterparty_node_id: PublicKey,
        channel_type: Features<ChannelTypeContext>,
    },
    ChannelClosed {
        channel_id: ChannelId,
        user_channel_id: u128,
        reason: ClosureReason,
        counterparty_node_id: Option<PublicKey>,
        channel_capacity_sats: Option<u64>,
    },
    DiscardFunding {
        channel_id: ChannelId,
        transaction: Transaction,
    },
    OpenChannelRequest {
        temporary_channel_id: ChannelId,
        counterparty_node_id: PublicKey,
        funding_satoshis: u64,
        push_msat: u64,
        channel_type: Features<ChannelTypeContext>,
    },
    HTLCHandlingFailed {
        prev_channel_id: ChannelId,
        failed_next_destination: HTLCDestination,
    },
    BumpTransaction(BumpTransactionEvent),
}

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!

Fields

§temporary_channel_id: ChannelId

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 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. This may be zero for objects serialized with LDK versions prior to 0.0.113.

§

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.

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.

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

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

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

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.

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

§

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.

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. May be greater than the invoice amount.

§purpose: PaymentPurpose

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

§

InvoiceRequestFailed

Indicates a request for an invoice failed to yield a response in a reasonable amount of time or was explicitly abandoned by ChannelManager::abandon_payment. This may be for an InvoiceRequest sent for an Offer or for a Refund that hasn’t been redeemed.

Fields

§payment_id: PaymentId

The payment_id to have been associated with payment for the requested invoice.

§

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.

Fields

§payment_id: Option<PaymentId>

The payment_id passed to 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.

§

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.

Fields

§payment_id: PaymentId

The payment_id passed to ChannelManager::send_payment.

§payment_hash: PaymentHash

The hash that was given to ChannelManager::send_payment.

§reason: Option<PaymentFailureReason>

The reason the payment failed. This is only None for events generated or serialized by versions prior to 0.0.115.

§

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.

Fields

§payment_id: PaymentId

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

The payment path that was successful.

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

§

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.

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

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.

§

ProbeSuccessful

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

Fields

§payment_id: PaymentId

The id returned by ChannelManager::send_probe.

§payment_hash: PaymentHash

The hash generated by ChannelManager::send_probe.

§path: Path

The payment path that was successful.

§

ProbeFailed

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

Fields

§payment_id: PaymentId

The id returned by ChannelManager::send_probe.

§payment_hash: PaymentHash

The hash generated by ChannelManager::send_probe.

§path: Path

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.

§

PendingHTLCsForwardable

Used to indicate that ChannelManager::process_pending_htlc_forwards should be called at a time in the future.

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

§

HTLCIntercepted

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.

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. 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 or subtract it as required. Further, LDK will not stop you from forwarding more than you received.

§

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

Fields

§outputs: Vec<SpendableOutputDescriptor>

The outputs which you should store as spendable by you.

§channel_id: Option<ChannelId>

The channel_id indicating which channel the spendable outputs belong to.

This will always be Some for events generated by LDK versions 0.0.117 and above.

§

PaymentForwarded

This event is generated when a payment has been successfully forwarded through us and a forwarding fee earned.

Fields

§prev_channel_id: Option<ChannelId>

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

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.

§outbound_amount_forwarded_msat: Option<u64>

The final amount forwarded, in milli-satoshis, after the fee is deducted.

The caveat described above the 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.

Fields

§channel_id: ChannelId

The channel_id of the channel that is pending 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 an inbound channel.

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

§counterparty_node_id: PublicKey

The node_id of the channel counterparty.

§funding_txo: OutPoint

The outpoint of the channel’s funding transaction.

§

ChannelReady

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.

Fields

§channel_id: ChannelId

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

The features that this channel will operate with.

§

ChannelClosed

Used to indicate that a previously opened channel with the given channel_id is in the process of closure.

Note that this event is only triggered for accepted channels: if the UserConfig::manually_accept_inbound_channels config flag is set to true and the channel is rejected, no ChannelClosed event will be sent.

Fields

§channel_id: ChannelId

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.

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

§

DiscardFunding

Used to indicate to the user that they can abandon the funding transaction and recycle the inputs for another purpose.

This event is not guaranteed to be generated for channels that are closed due to a restart.

Fields

§channel_id: ChannelId

The channel_id of the channel which has been closed.

§transaction: Transaction

The full transaction received from the user

§

OpenChannelRequest

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. Note that a [’ChannelClosed`] event will not be triggered if the channel is rejected.

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.

Fields

§temporary_channel_id: ChannelId

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

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.

§

HTLCHandlingFailed

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.
Expected MPP amount has already been reached
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).

Fields

§prev_channel_id: ChannelId

The channel over which the HTLC was received.

§failed_next_destination: HTLCDestination

Destination of the HTLC that failed to be processed.

§

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 the ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx config flag is set to true. It is limited to the scope of channels with anchor outputs.