Enum BumpTransactionEvent

pub enum BumpTransactionEvent {
    ChannelClose {
        claim_id: ClaimId,
        package_target_feerate_sat_per_1000_weight: u32,
        commitment_tx: Transaction,
        commitment_tx_fee_satoshis: u64,
        anchor_descriptor: AnchorDescriptor,
        pending_htlcs: Vec<HTLCOutputInCommitment>,
    },
    HTLCResolution {
        claim_id: ClaimId,
        target_feerate_sat_per_1000_weight: u32,
        htlc_descriptors: Vec<HTLCDescriptor>,
        tx_lock_time: PackedLockTime,
    },
}

Represents the different types of transactions, originating from LDK, to be bumped.

Variants

ChannelClose

Indicates that a channel featuring anchor outputs is to be closed by broadcasting the local commitment transaction. Since commitment transactions have a static feerate pre-agreed upon, they may need additional fees to be attached through a child transaction using the popular Child-Pays-For-Parent fee bumping technique. This child transaction must include the anchor input described within anchor_descriptor along with additional inputs to meet the target feerate. Failure to meet the target feerate decreases the confirmation odds of the transaction package (which includes the commitment and child anchor transactions), possibly resulting in a loss of funds. Once the transaction is constructed, it must be fully signed for and broadcast by the consumer of the event along with the commitment_tx enclosed. Note that the commitment_tx must always be broadcast first, as the child anchor transaction depends on it.

The consumer should be able to sign for any of the additional inputs included within the child anchor transaction. To sign its anchor input, an EcdsaChannelSigner should be re-derived through AnchorDescriptor::derive_channel_signer. The anchor input signature can be computed with EcdsaChannelSigner::sign_holder_anchor_input, which can then be provided to build_anchor_input_witness along with the funding_pubkey to obtain the full witness required to spend.

It is possible to receive more than one instance of this event if a valid child anchor transaction is never broadcast or is but not with a sufficient fee to be mined. Care should be taken by the consumer of the event to ensure any future iterations of the child anchor transaction adhere to the Replace-By-Fee rules for fee bumps to be accepted into the mempool, and eventually the chain. As the frequency of these events is not user-controlled, users may ignore/drop the event if they are no longer able to commit external confirmed funds to the child anchor transaction.

The set of pending_htlcs on the commitment transaction to be broadcast can be inspected to determine whether a significant portion of the channel’s funds are allocated to HTLCs, enabling users to make their own decisions regarding the importance of the commitment transaction’s confirmation. Note that this is not required, but simply exists as an option for users to override LDK’s behavior. On commitments with no HTLCs (indicated by those with an empty pending_htlcs), confirmation of the commitment transaction can be considered to be not urgent.

Fields

claim_id: ClaimId

The unique identifier for the claim of the anchor output in the commitment transaction.

The identifier must map to the set of external UTXOs assigned to the claim, such that they can be reused when a new claim with the same identifier needs to be made, resulting in a fee-bumping attempt.

package_target_feerate_sat_per_1000_weight: u32

The target feerate that the transaction package, which consists of the commitment transaction and the to-be-crafted child anchor transaction, must meet.

commitment_tx: Transaction

The channel’s commitment transaction to bump the fee of. This transaction should be broadcast along with the anchor transaction constructed as a result of consuming this event.

commitment_tx_fee_satoshis: u64

The absolute fee in satoshis of the commitment transaction. This can be used along the with weight of the commitment transaction to determine its feerate.

anchor_descriptor: AnchorDescriptor

The descriptor to sign the anchor input of the anchor transaction constructed as a result of consuming this event.

pending_htlcs: Vec<HTLCOutputInCommitment>

The set of pending HTLCs on the commitment transaction that need to be resolved once the commitment transaction confirms.

HTLCResolution

Indicates that a channel featuring anchor outputs has unilaterally closed on-chain by a holder commitment transaction and its HTLC(s) need to be resolved on-chain. With the zero-HTLC-transaction-fee variant of anchor outputs, the pre-signed HTLC transactions have a zero fee, thus requiring additional inputs and/or outputs to be attached for a timely confirmation within the chain. These additional inputs and/or outputs must be appended to the resulting HTLC transaction to meet the target feerate. Failure to meet the target feerate decreases the confirmation odds of the transaction, possibly resulting in a loss of funds. Once the transaction meets the target feerate, it must be signed for and broadcast by the consumer of the event.

The consumer should be able to sign for any of the non-HTLC inputs added to the resulting HTLC transaction. To sign HTLC inputs, an EcdsaChannelSigner should be re-derived through HTLCDescriptor::derive_channel_signer. Each HTLC input’s signature can be computed with EcdsaChannelSigner::sign_holder_htlc_transaction, which can then be provided to HTLCDescriptor::tx_input_witness to obtain the fully signed witness required to spend.

It is possible to receive more than one instance of this event if a valid HTLC transaction is never broadcast or is but not with a sufficient fee to be mined. Care should be taken by the consumer of the event to ensure any future iterations of the HTLC transaction adhere to the Replace-By-Fee rules for fee bumps to be accepted into the mempool, and eventually the chain. As the frequency of these events is not user-controlled, users may ignore/drop the event if either they are no longer able to commit external confirmed funds to the HTLC transaction or the fee committed to the HTLC transaction is greater in value than the HTLCs being claimed.

Fields

claim_id: ClaimId

The unique identifier for the claim of the HTLCs in the confirmed commitment transaction.

The identifier must map to the set of external UTXOs assigned to the claim, such that they can be reused when a new claim with the same identifier needs to be made, resulting in a fee-bumping attempt.

target_feerate_sat_per_1000_weight: u32

The target feerate that the resulting HTLC transaction must meet.

htlc_descriptors: Vec<HTLCDescriptor>

The set of pending HTLCs on the confirmed commitment that need to be claimed, preferably by the same transaction.

tx_lock_time: PackedLockTime

The locktime required for the resulting HTLC transaction.

Trait Implementations

impl Clone for BumpTransactionEvent

fn clone(&self) -> BumpTransactionEvent

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for BumpTransactionEvent

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

Formats the value using the given formatter.

impl PartialEq for BumpTransactionEvent

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl Eq for BumpTransactionEvent

impl StructuralPartialEq for BumpTransactionEvent