Enum BumpTransactionEvent

pub enum BumpTransactionEvent {
    ChannelClose {
        channel_id: ChannelId,
        counterparty_node_id: PublicKey,
        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 {
        channel_id: ChannelId,
        counterparty_node_id: PublicKey,
        claim_id: ClaimId,
        target_feerate_sat_per_1000_weight: u32,
        htlc_descriptors: Vec<HTLCDescriptor>,
        tx_lock_time: LockTime,
    },
}

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. It is also possible that the feerate of the commitment transaction is already sufficient, in which case the child anchor transaction is not needed and only the commitment transaction should be broadcast.

In zero-fee commitment channels, the commitment transaction and the anchor transaction form a 1-parent-1-child package that conforms to BIP 431 (known as TRUC transactions). The anchor transaction must be version 3, and its size must be no more than 1000 vB. The anchor transaction is usually needed to bump the fee of the commitment transaction as the commitment transaction is not explicitly assigned any fees. In those cases the anchor transaction must be broadcast together with the commitment transaction as a child-with-parents package (usually using the Bitcoin Core submitpackage RPC).

The consumer should be able to sign for any of the additional inputs included within the child anchor transaction. To sign its keyed-anchor input, an EcdsaChannelSigner should be re-derived through SignerProvider::derive_channel_signer. The anchor input signature can be computed with EcdsaChannelSigner::sign_holder_keyed_anchor_input, which can then be provided to build_keyed_anchor_input_witness along with the funding_pubkey to obtain the full witness required to spend. Note that no signature or witness data is required to spend the keyless anchor used in zero-fee commitment channels.

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

channel_id: ChannelId

The channel_id of the channel which has been closed.

counterparty_node_id: PublicKey

Counterparty in the closed channel.

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. In all such channels, 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.

In zero-fee commitment channels, you must set the version of the HTLC claim transaction to version 3 as the counterparty’s signature commits to the version of the transaction. You must also make sure that this claim transaction does not grow bigger than 10,000 vB, the maximum vsize of any TRUC transaction as specified in BIP 431. It is possible for htlc_descriptors to be long enough such that claiming all the HTLCs therein in a single transaction would exceed this limit. In this case, you must claim all the HTLCs in htlc_descriptors using multiple transactions. Finally, note that while HTLCs in zero-fee commitment channels no longer have the 1 CSV lock, LDK will still emit this event only after the commitment transaction has 1 confirmation.

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

channel_id: ChannelId

The channel_id of the channel which has been closed.

counterparty_node_id: PublicKey

Counterparty in the closed channel.

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

The locktime required for the resulting HTLC transaction.

Trait Implementations

impl Clone for BumpTransactionEvent

fn clone(&self) -> BumpTransactionEvent

Returns a duplicate 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

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