Package org.ldk.structs

Class BumpTransactionEvent.ChannelClose

  • Enclosing class:
    BumpTransactionEvent
    public static final class BumpTransactionEvent.ChannelClose
extends BumpTransactionEvent
    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](https://bitcoinops.org/en/topics/cpfp) 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](https://github.com/bitcoin/bitcoin/blob/master/doc/policy/mempool-replacements.md) 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. [`EcdsaChannelSigner`]: crate::sign::EcdsaChannelSigner [`EcdsaChannelSigner::sign_holder_anchor_input`]: crate::sign::EcdsaChannelSigner::sign_holder_anchor_input [`build_anchor_input_witness`]: crate::ln::chan_utils::build_anchor_input_witness

    • Field Detail

      • claim_id

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

        public final int package_target_feerate_sat_per_1000_weight
        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

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

        public final long commitment_tx_fee_satoshis
        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

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

      • pending_htlcs

        public final HTLCOutputInCommitment[] pending_htlcs
        The set of pending HTLCs on the commitment transaction that need to be resolved once the commitment transaction confirms.