_ Git - ldk-java/blob - src/main/java/org/ldk/structs/BumpTransactionEvent.java

   1 package org.ldk.structs;
   2
   3 import org.ldk.impl.bindings;
   4 import org.ldk.enums.*;
   5 import org.ldk.util.*;
   6 import java.util.Arrays;
   7 import java.lang.ref.Reference;
   8 import javax.annotation.Nullable;
   9
  10
  11 /**
  12  * Represents the different types of transactions, originating from LDK, to be bumped.
  13  */
  14 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  15 public class BumpTransactionEvent extends CommonBase {
  16         private BumpTransactionEvent(Object _dummy, long ptr) { super(ptr); }
  17         @Override @SuppressWarnings("deprecation")
  18         protected void finalize() throws Throwable {
  19                 super.finalize();
  20                 if (ptr != 0) { bindings.BumpTransactionEvent_free(ptr); }
  21         }
  22         static BumpTransactionEvent constr_from_ptr(long ptr) {
  23                 bindings.LDKBumpTransactionEvent raw_val = bindings.LDKBumpTransactionEvent_ref_from_ptr(ptr);
  24                 if (raw_val.getClass() == bindings.LDKBumpTransactionEvent.ChannelClose.class) {
  25                         return new ChannelClose(ptr, (bindings.LDKBumpTransactionEvent.ChannelClose)raw_val);
  26                 }
  27                 if (raw_val.getClass() == bindings.LDKBumpTransactionEvent.HTLCResolution.class) {
  28                         return new HTLCResolution(ptr, (bindings.LDKBumpTransactionEvent.HTLCResolution)raw_val);
  29                 }
  30                 assert false; return null; // Unreachable without extending the (internal) bindings interface
  31         }
  32
  33         /**
  34          * Indicates that a channel featuring anchor outputs is to be closed by broadcasting the local
  35          * commitment transaction. Since commitment transactions have a static feerate pre-agreed upon,
  36          * they may need additional fees to be attached through a child transaction using the popular
  37          * [Child-Pays-For-Parent](https://bitcoinops.org/en/topics/cpfp) fee bumping technique. This
  38          * child transaction must include the anchor input described within `anchor_descriptor` along
  39          * with additional inputs to meet the target feerate. Failure to meet the target feerate
  40          * decreases the confirmation odds of the transaction package (which includes the commitment
  41          * and child anchor transactions), possibly resulting in a loss of funds. Once the transaction
  42          * is constructed, it must be fully signed for and broadcast by the consumer of the event
  43          * along with the `commitment_tx` enclosed. Note that the `commitment_tx` must always be
  44          * broadcast first, as the child anchor transaction depends on it.
  45          *
  46          * The consumer should be able to sign for any of the additional inputs included within the
  47          * child anchor transaction. To sign its anchor input, an [`EcdsaChannelSigner`] should be
  48          * re-derived through [`AnchorDescriptor::derive_channel_signer`]. The anchor input signature
  49          * can be computed with [`EcdsaChannelSigner::sign_holder_anchor_input`], which can then be
  50          * provided to [`build_anchor_input_witness`] along with the `funding_pubkey` to obtain the
  51          * full witness required to spend.
  52          *
  53          * It is possible to receive more than one instance of this event if a valid child anchor
  54          * transaction is never broadcast or is but not with a sufficient fee to be mined. Care should
  55          * be taken by the consumer of the event to ensure any future iterations of the child anchor
  56          * transaction adhere to the [Replace-By-Fee
  57          * rules](https://github.com/bitcoin/bitcoin/blob/master/doc/policy/mempool-replacements.md)
  58          * for fee bumps to be accepted into the mempool, and eventually the chain. As the frequency of
  59          * these events is not user-controlled, users may ignore/drop the event if they are no longer
  60          * able to commit external confirmed funds to the child anchor transaction.
  61          *
  62          * The set of `pending_htlcs` on the commitment transaction to be broadcast can be inspected to
  63          * determine whether a significant portion of the channel's funds are allocated to HTLCs,
  64          * enabling users to make their own decisions regarding the importance of the commitment
  65          * transaction's confirmation. Note that this is not required, but simply exists as an option
  66          * for users to override LDK's behavior. On commitments with no HTLCs (indicated by those with
  67          * an empty `pending_htlcs`), confirmation of the commitment transaction can be considered to
  68          * be not urgent.
  69          *
  70          * [`EcdsaChannelSigner`]: crate::sign::EcdsaChannelSigner
  71          * [`EcdsaChannelSigner::sign_holder_anchor_input`]: crate::sign::EcdsaChannelSigner::sign_holder_anchor_input
  72          * [`build_anchor_input_witness`]: crate::ln::chan_utils::build_anchor_input_witness
  73          */
  74         public final static class ChannelClose extends BumpTransactionEvent {
  75                 /**
  76                  * The unique identifier for the claim of the anchor output in the commitment transaction.
  77                  *
  78                  * The identifier must map to the set of external UTXOs assigned to the claim, such that
  79                  * they can be reused when a new claim with the same identifier needs to be made, resulting
  80                  * in a fee-bumping attempt.
  81                 */
  82                 public final byte[] claim_id;
  83                 /**
  84                  * The target feerate that the transaction package, which consists of the commitment
  85                  * transaction and the to-be-crafted child anchor transaction, must meet.
  86                 */
  87                 public final int package_target_feerate_sat_per_1000_weight;
  88                 /**
  89                  * The channel's commitment transaction to bump the fee of. This transaction should be
  90                  * broadcast along with the anchor transaction constructed as a result of consuming this
  91                  * event.
  92                 */
  93                 public final byte[] commitment_tx;
  94                 /**
  95                  * The absolute fee in satoshis of the commitment transaction. This can be used along the
  96                  * with weight of the commitment transaction to determine its feerate.
  97                 */
  98                 public final long commitment_tx_fee_satoshis;
  99                 /**
 100                  * The descriptor to sign the anchor input of the anchor transaction constructed as a
 101                  * result of consuming this event.
 102                 */
 103                 public final org.ldk.structs.AnchorDescriptor anchor_descriptor;
 104                 /**
 105                  * The set of pending HTLCs on the commitment transaction that need to be resolved once the
 106                  * commitment transaction confirms.
 107                 */
 108                 public final HTLCOutputInCommitment[] pending_htlcs;
 109                 private ChannelClose(long ptr, bindings.LDKBumpTransactionEvent.ChannelClose obj) {
 110                         super(null, ptr);
 111                         this.claim_id = obj.claim_id;
 112                         this.package_target_feerate_sat_per_1000_weight = obj.package_target_feerate_sat_per_1000_weight;
 113                         this.commitment_tx = obj.commitment_tx;
 114                         this.commitment_tx_fee_satoshis = obj.commitment_tx_fee_satoshis;
 115                         long anchor_descriptor = obj.anchor_descriptor;
 116                         org.ldk.structs.AnchorDescriptor anchor_descriptor_hu_conv = null; if (anchor_descriptor < 0 || anchor_descriptor > 4096) { anchor_descriptor_hu_conv = new org.ldk.structs.AnchorDescriptor(null, anchor_descriptor); }
 117                         if (anchor_descriptor_hu_conv != null) { anchor_descriptor_hu_conv.ptrs_to.add(this); };
 118                         this.anchor_descriptor = anchor_descriptor_hu_conv;
 119                         long[] pending_htlcs = obj.pending_htlcs;
 120                         int pending_htlcs_conv_24_len = pending_htlcs.length;
 121                         HTLCOutputInCommitment[] pending_htlcs_conv_24_arr = new HTLCOutputInCommitment[pending_htlcs_conv_24_len];
 122                         for (int y = 0; y < pending_htlcs_conv_24_len; y++) {
 123                                 long pending_htlcs_conv_24 = pending_htlcs[y];
 124                                 org.ldk.structs.HTLCOutputInCommitment pending_htlcs_conv_24_hu_conv = null; if (pending_htlcs_conv_24 < 0 || pending_htlcs_conv_24 > 4096) { pending_htlcs_conv_24_hu_conv = new org.ldk.structs.HTLCOutputInCommitment(null, pending_htlcs_conv_24); }
 125                                 if (pending_htlcs_conv_24_hu_conv != null) { pending_htlcs_conv_24_hu_conv.ptrs_to.add(this); };
 126                                 pending_htlcs_conv_24_arr[y] = pending_htlcs_conv_24_hu_conv;
 127                         }
 128                         this.pending_htlcs = pending_htlcs_conv_24_arr;
 129                 }
 130         }
 131         /**
 132          * Indicates that a channel featuring anchor outputs has unilaterally closed on-chain by a
 133          * holder commitment transaction and its HTLC(s) need to be resolved on-chain. With the
 134          * zero-HTLC-transaction-fee variant of anchor outputs, the pre-signed HTLC
 135          * transactions have a zero fee, thus requiring additional inputs and/or outputs to be attached
 136          * for a timely confirmation within the chain. These additional inputs and/or outputs must be
 137          * appended to the resulting HTLC transaction to meet the target feerate. Failure to meet the
 138          * target feerate decreases the confirmation odds of the transaction, possibly resulting in a
 139          * loss of funds. Once the transaction meets the target feerate, it must be signed for and
 140          * broadcast by the consumer of the event.
 141          *
 142          * The consumer should be able to sign for any of the non-HTLC inputs added to the resulting
 143          * HTLC transaction. To sign HTLC inputs, an [`EcdsaChannelSigner`] should be re-derived
 144          * through [`HTLCDescriptor::derive_channel_signer`]. Each HTLC input's signature can be
 145          * computed with [`EcdsaChannelSigner::sign_holder_htlc_transaction`], which can then be
 146          * provided to [`HTLCDescriptor::tx_input_witness`] to obtain the fully signed witness required
 147          * to spend.
 148          *
 149          * It is possible to receive more than one instance of this event if a valid HTLC transaction
 150          * is never broadcast or is but not with a sufficient fee to be mined. Care should be taken by
 151          * the consumer of the event to ensure any future iterations of the HTLC transaction adhere to
 152          * the [Replace-By-Fee
 153          * rules](https://github.com/bitcoin/bitcoin/blob/master/doc/policy/mempool-replacements.md)
 154          * for fee bumps to be accepted into the mempool, and eventually the chain. As the frequency of
 155          * these events is not user-controlled, users may ignore/drop the event if either they are no
 156          * longer able to commit external confirmed funds to the HTLC transaction or the fee committed
 157          * to the HTLC transaction is greater in value than the HTLCs being claimed.
 158          *
 159          * [`EcdsaChannelSigner`]: crate::sign::EcdsaChannelSigner
 160          * [`EcdsaChannelSigner::sign_holder_htlc_transaction`]: crate::sign::EcdsaChannelSigner::sign_holder_htlc_transaction
 161          * [`HTLCDescriptor::tx_input_witness`]: HTLCDescriptor::tx_input_witness
 162          */
 163         public final static class HTLCResolution extends BumpTransactionEvent {
 164                 /**
 165                  * The unique identifier for the claim of the HTLCs in the confirmed commitment
 166                  * transaction.
 167                  *
 168                  * The identifier must map to the set of external UTXOs assigned to the claim, such that
 169                  * they can be reused when a new claim with the same identifier needs to be made, resulting
 170                  * in a fee-bumping attempt.
 171                 */
 172                 public final byte[] claim_id;
 173                 /**
 174                  * The target feerate that the resulting HTLC transaction must meet.
 175                 */
 176                 public final int target_feerate_sat_per_1000_weight;
 177                 /**
 178                  * The set of pending HTLCs on the confirmed commitment that need to be claimed, preferably
 179                  * by the same transaction.
 180                 */
 181                 public final HTLCDescriptor[] htlc_descriptors;
 182                 /**
 183                  * The locktime required for the resulting HTLC transaction.
 184                 */
 185                 public final int tx_lock_time;
 186                 private HTLCResolution(long ptr, bindings.LDKBumpTransactionEvent.HTLCResolution obj) {
 187                         super(null, ptr);
 188                         this.claim_id = obj.claim_id;
 189                         this.target_feerate_sat_per_1000_weight = obj.target_feerate_sat_per_1000_weight;
 190                         long[] htlc_descriptors = obj.htlc_descriptors;
 191                         int htlc_descriptors_conv_16_len = htlc_descriptors.length;
 192                         HTLCDescriptor[] htlc_descriptors_conv_16_arr = new HTLCDescriptor[htlc_descriptors_conv_16_len];
 193                         for (int q = 0; q < htlc_descriptors_conv_16_len; q++) {
 194                                 long htlc_descriptors_conv_16 = htlc_descriptors[q];
 195                                 org.ldk.structs.HTLCDescriptor htlc_descriptors_conv_16_hu_conv = null; if (htlc_descriptors_conv_16 < 0 || htlc_descriptors_conv_16 > 4096) { htlc_descriptors_conv_16_hu_conv = new org.ldk.structs.HTLCDescriptor(null, htlc_descriptors_conv_16); }
 196                                 if (htlc_descriptors_conv_16_hu_conv != null) { htlc_descriptors_conv_16_hu_conv.ptrs_to.add(this); };
 197                                 htlc_descriptors_conv_16_arr[q] = htlc_descriptors_conv_16_hu_conv;
 198                         }
 199                         this.htlc_descriptors = htlc_descriptors_conv_16_arr;
 200                         this.tx_lock_time = obj.tx_lock_time;
 201                 }
 202         }
 203         long clone_ptr() {
 204                 long ret = bindings.BumpTransactionEvent_clone_ptr(this.ptr);
 205                 Reference.reachabilityFence(this);
 206                 return ret;
 207         }
 208
 209         /**
 210          * Creates a copy of the BumpTransactionEvent
 211          */
 212         public BumpTransactionEvent clone() {
 213                 long ret = bindings.BumpTransactionEvent_clone(this.ptr);
 214                 Reference.reachabilityFence(this);
 215                 if (ret >= 0 && ret <= 4096) { return null; }
 216                 org.ldk.structs.BumpTransactionEvent ret_hu_conv = org.ldk.structs.BumpTransactionEvent.constr_from_ptr(ret);
 217                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 218                 return ret_hu_conv;
 219         }
 220
 221         /**
 222          * Utility method to constructs a new ChannelClose-variant BumpTransactionEvent
 223          */
 224         public static BumpTransactionEvent channel_close(byte[] claim_id, int package_target_feerate_sat_per_1000_weight, byte[] commitment_tx, long commitment_tx_fee_satoshis, org.ldk.structs.AnchorDescriptor anchor_descriptor, HTLCOutputInCommitment[] pending_htlcs) {
 225                 long ret = bindings.BumpTransactionEvent_channel_close(InternalUtils.check_arr_len(claim_id, 32), package_target_feerate_sat_per_1000_weight, commitment_tx, commitment_tx_fee_satoshis, anchor_descriptor == null ? 0 : anchor_descriptor.ptr, pending_htlcs != null ? Arrays.stream(pending_htlcs).mapToLong(pending_htlcs_conv_24 -> pending_htlcs_conv_24 == null ? 0 : pending_htlcs_conv_24.ptr).toArray() : null);
 226                 Reference.reachabilityFence(claim_id);
 227                 Reference.reachabilityFence(package_target_feerate_sat_per_1000_weight);
 228                 Reference.reachabilityFence(commitment_tx);
 229                 Reference.reachabilityFence(commitment_tx_fee_satoshis);
 230                 Reference.reachabilityFence(anchor_descriptor);
 231                 Reference.reachabilityFence(pending_htlcs);
 232                 if (ret >= 0 && ret <= 4096) { return null; }
 233                 org.ldk.structs.BumpTransactionEvent ret_hu_conv = org.ldk.structs.BumpTransactionEvent.constr_from_ptr(ret);
 234                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 235                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(anchor_descriptor); };
 236                 for (HTLCOutputInCommitment pending_htlcs_conv_24: pending_htlcs) { if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(pending_htlcs_conv_24); }; };
 237                 return ret_hu_conv;
 238         }
 239
 240         /**
 241          * Utility method to constructs a new HTLCResolution-variant BumpTransactionEvent
 242          */
 243         public static BumpTransactionEvent htlcresolution(byte[] claim_id, int target_feerate_sat_per_1000_weight, HTLCDescriptor[] htlc_descriptors, int tx_lock_time) {
 244                 long ret = bindings.BumpTransactionEvent_htlcresolution(InternalUtils.check_arr_len(claim_id, 32), target_feerate_sat_per_1000_weight, htlc_descriptors != null ? Arrays.stream(htlc_descriptors).mapToLong(htlc_descriptors_conv_16 -> htlc_descriptors_conv_16 == null ? 0 : htlc_descriptors_conv_16.ptr).toArray() : null, tx_lock_time);
 245                 Reference.reachabilityFence(claim_id);
 246                 Reference.reachabilityFence(target_feerate_sat_per_1000_weight);
 247                 Reference.reachabilityFence(htlc_descriptors);
 248                 Reference.reachabilityFence(tx_lock_time);
 249                 if (ret >= 0 && ret <= 4096) { return null; }
 250                 org.ldk.structs.BumpTransactionEvent ret_hu_conv = org.ldk.structs.BumpTransactionEvent.constr_from_ptr(ret);
 251                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 252                 for (HTLCDescriptor htlc_descriptors_conv_16: htlc_descriptors) { if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(htlc_descriptors_conv_16); }; };
 253                 return ret_hu_conv;
 254         }
 255
 256         /**
 257          * Checks if two BumpTransactionEvents contain equal inner contents.
 258          * This ignores pointers and is_owned flags and looks at the values in fields.
 259          */
 260         public boolean eq(org.ldk.structs.BumpTransactionEvent b) {
 261                 boolean ret = bindings.BumpTransactionEvent_eq(this.ptr, b == null ? 0 : b.ptr);
 262                 Reference.reachabilityFence(this);
 263                 Reference.reachabilityFence(b);
 264                 return ret;
 265         }
 266
 267         @Override public boolean equals(Object o) {
 268                 if (!(o instanceof BumpTransactionEvent)) return false;
 269                 return this.eq((BumpTransactionEvent)o);
 270         }
 271 }