Package org.ldk.structs

Class Event.PaymentClaimable

  • Enclosing class:
    Event
    public static final class Event.PaymentClaimable
extends Event
    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. [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds [`ChannelManager::claim_funds_with_known_custom_tlvs`]: crate::ln::channelmanager::ChannelManager::claim_funds_with_known_custom_tlvs [`FailureCode::InvalidOnionPayload`]: crate::ln::channelmanager::FailureCode::InvalidOnionPayload [`ChannelManager::fail_htlc_backwards`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards [`ChannelManager::fail_htlc_backwards_with_reason`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards_with_reason

    • Field Detail

      • receiver_node_id

        @Nullable
public final byte[] receiver_node_id
        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. [phantom nodes]: crate::sign::PhantomKeysManager Note that this (or a relevant inner pointer) may be NULL or all-0s to represent None

      • payment_hash

        public final byte[] payment_hash
        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

        @Nullable
public final RecipientOnionFields onion_fields
        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. Note that this (or a relevant inner pointer) may be NULL or all-0s to represent None

      • amount_msat

        public final long amount_msat
        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! [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs

      • counterparty_skimmed_fee_msat

        public final long counterparty_skimmed_fee_msat
        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. [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs

      • purpose

        public final PaymentPurpose purpose
        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

        public final Option_ThirtyTwoBytesZ via_channel_id
        The `channel_id` indicating over which channel we received the payment.

      • via_user_channel_id

        public final Option_U128Z via_user_channel_id
        The `user_channel_id` indicating over which channel we received the payment.

      • claim_deadline

        public final Option_u32Z claim_deadline
        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. [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds