git.bitcoin.ninja 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::ecdsa::EcdsaChannelSigner
  71          * [`EcdsaChannelSigner::sign_holder_anchor_input`]: crate::sign::ecdsa::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 `channel_id` of the channel which has been closed.
  77                 */
  78                 public final org.ldk.structs.ChannelId channel_id;
  79                 /**
  80                  * Counterparty in the closed channel.
  81                 */
  82                 public final byte[] counterparty_node_id;
  83                 /**
  84                  * The unique identifier for the claim of the anchor output in the commitment transaction.
  85                  *
  86                  * The identifier must map to the set of external UTXOs assigned to the claim, such that
  87                  * they can be reused when a new claim with the same identifier needs to be made, resulting
  88                  * in a fee-bumping attempt.
  89                 */
  90                 public final byte[] claim_id;
  91                 /**
  92                  * The target feerate that the transaction package, which consists of the commitment
  93                  * transaction and the to-be-crafted child anchor transaction, must meet.
  94                 */
  95                 public final int package_target_feerate_sat_per_1000_weight;
  96                 /**
  97                  * The channel's commitment transaction to bump the fee of. This transaction should be
  98                  * broadcast along with the anchor transaction constructed as a result of consuming this
  99                  * event.
 100                 */
 101                 public final byte[] commitment_tx;
 102                 /**
 103                  * The absolute fee in satoshis of the commitment transaction. This can be used along the
 104                  * with weight of the commitment transaction to determine its feerate.
 105                 */
 106                 public final long commitment_tx_fee_satoshis;
 107                 /**
 108                  * The descriptor to sign the anchor input of the anchor transaction constructed as a
 109                  * result of consuming this event.
 110                 */
 111                 public final org.ldk.structs.AnchorDescriptor anchor_descriptor;
 112                 /**
 113                  * The set of pending HTLCs on the commitment transaction that need to be resolved once the
 114                  * commitment transaction confirms.
 115                 */
 116                 public final HTLCOutputInCommitment[] pending_htlcs;
 117                 private ChannelClose(long ptr, bindings.LDKBumpTransactionEvent.ChannelClose obj) {
 118                         super(null, ptr);
 119                         long channel_id = obj.channel_id;
 120                         org.ldk.structs.ChannelId channel_id_hu_conv = null; if (channel_id < 0 || channel_id > 4096) { channel_id_hu_conv = new org.ldk.structs.ChannelId(null, channel_id); }
 121                         if (channel_id_hu_conv != null) { channel_id_hu_conv.ptrs_to.add(this); };
 122                         this.channel_id = channel_id_hu_conv;
 123                         this.counterparty_node_id = obj.counterparty_node_id;
 124                         this.claim_id = obj.claim_id;
 125                         this.package_target_feerate_sat_per_1000_weight = obj.package_target_feerate_sat_per_1000_weight;
 126                         this.commitment_tx = obj.commitment_tx;
 127                         this.commitment_tx_fee_satoshis = obj.commitment_tx_fee_satoshis;
 128                         long anchor_descriptor = obj.anchor_descriptor;
 129                         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); }
 130                         if (anchor_descriptor_hu_conv != null) { anchor_descriptor_hu_conv.ptrs_to.add(this); };
 131                         this.anchor_descriptor = anchor_descriptor_hu_conv;
 132                         long[] pending_htlcs = obj.pending_htlcs;
 133                         int pending_htlcs_conv_24_len = pending_htlcs.length;
 134                         HTLCOutputInCommitment[] pending_htlcs_conv_24_arr = new HTLCOutputInCommitment[pending_htlcs_conv_24_len];
 135                         for (int y = 0; y < pending_htlcs_conv_24_len; y++) {
 136                                 long pending_htlcs_conv_24 = pending_htlcs[y];
 137                                 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); }
 138                                 if (pending_htlcs_conv_24_hu_conv != null) { pending_htlcs_conv_24_hu_conv.ptrs_to.add(this); };
 139                                 pending_htlcs_conv_24_arr[y] = pending_htlcs_conv_24_hu_conv;
 140                         }
 141                         this.pending_htlcs = pending_htlcs_conv_24_arr;
 142                 }
 143         }
 144         /**
 145          * Indicates that a channel featuring anchor outputs has unilaterally closed on-chain by a
 146          * holder commitment transaction and its HTLC(s) need to be resolved on-chain. With the
 147          * zero-HTLC-transaction-fee variant of anchor outputs, the pre-signed HTLC
 148          * transactions have a zero fee, thus requiring additional inputs and/or outputs to be attached
 149          * for a timely confirmation within the chain. These additional inputs and/or outputs must be
 150          * appended to the resulting HTLC transaction to meet the target feerate. Failure to meet the
 151          * target feerate decreases the confirmation odds of the transaction, possibly resulting in a
 152          * loss of funds. Once the transaction meets the target feerate, it must be signed for and
 153          * broadcast by the consumer of the event.
 154          *
 155          * The consumer should be able to sign for any of the non-HTLC inputs added to the resulting
 156          * HTLC transaction. To sign HTLC inputs, an [`EcdsaChannelSigner`] should be re-derived
 157          * through [`HTLCDescriptor::derive_channel_signer`]. Each HTLC input's signature can be
 158          * computed with [`EcdsaChannelSigner::sign_holder_htlc_transaction`], which can then be
 159          * provided to [`HTLCDescriptor::tx_input_witness`] to obtain the fully signed witness required
 160          * to spend.
 161          *
 162          * It is possible to receive more than one instance of this event if a valid HTLC transaction
 163          * is never broadcast or is but not with a sufficient fee to be mined. Care should be taken by
 164          * the consumer of the event to ensure any future iterations of the HTLC transaction adhere to
 165          * the [Replace-By-Fee
 166          * rules](https://github.com/bitcoin/bitcoin/blob/master/doc/policy/mempool-replacements.md)
 167          * for fee bumps to be accepted into the mempool, and eventually the chain. As the frequency of
 168          * these events is not user-controlled, users may ignore/drop the event if either they are no
 169          * longer able to commit external confirmed funds to the HTLC transaction or the fee committed
 170          * to the HTLC transaction is greater in value than the HTLCs being claimed.
 171          *
 172          * [`EcdsaChannelSigner`]: crate::sign::ecdsa::EcdsaChannelSigner
 173          * [`EcdsaChannelSigner::sign_holder_htlc_transaction`]: crate::sign::ecdsa::EcdsaChannelSigner::sign_holder_htlc_transaction
 174          */
 175         public final static class HTLCResolution extends BumpTransactionEvent {
 176                 /**
 177                  * The `channel_id` of the channel which has been closed.
 178                 */
 179                 public final org.ldk.structs.ChannelId channel_id;
 180                 /**
 181                  * Counterparty in the closed channel.
 182                 */
 183                 public final byte[] counterparty_node_id;
 184                 /**
 185                  * The unique identifier for the claim of the HTLCs in the confirmed commitment
 186                  * transaction.
 187                  *
 188                  * The identifier must map to the set of external UTXOs assigned to the claim, such that
 189                  * they can be reused when a new claim with the same identifier needs to be made, resulting
 190                  * in a fee-bumping attempt.
 191                 */
 192                 public final byte[] claim_id;
 193                 /**
 194                  * The target feerate that the resulting HTLC transaction must meet.
 195                 */
 196                 public final int target_feerate_sat_per_1000_weight;
 197                 /**
 198                  * The set of pending HTLCs on the confirmed commitment that need to be claimed, preferably
 199                  * by the same transaction.
 200                 */
 201                 public final HTLCDescriptor[] htlc_descriptors;
 202                 /**
 203                  * The locktime required for the resulting HTLC transaction.
 204                 */
 205                 public final int tx_lock_time;
 206                 private HTLCResolution(long ptr, bindings.LDKBumpTransactionEvent.HTLCResolution obj) {
 207                         super(null, ptr);
 208                         long channel_id = obj.channel_id;
 209                         org.ldk.structs.ChannelId channel_id_hu_conv = null; if (channel_id < 0 || channel_id > 4096) { channel_id_hu_conv = new org.ldk.structs.ChannelId(null, channel_id); }
 210                         if (channel_id_hu_conv != null) { channel_id_hu_conv.ptrs_to.add(this); };
 211                         this.channel_id = channel_id_hu_conv;
 212                         this.counterparty_node_id = obj.counterparty_node_id;
 213                         this.claim_id = obj.claim_id;
 214                         this.target_feerate_sat_per_1000_weight = obj.target_feerate_sat_per_1000_weight;
 215                         long[] htlc_descriptors = obj.htlc_descriptors;
 216                         int htlc_descriptors_conv_16_len = htlc_descriptors.length;
 217                         HTLCDescriptor[] htlc_descriptors_conv_16_arr = new HTLCDescriptor[htlc_descriptors_conv_16_len];
 218                         for (int q = 0; q < htlc_descriptors_conv_16_len; q++) {
 219                                 long htlc_descriptors_conv_16 = htlc_descriptors[q];
 220                                 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); }
 221                                 if (htlc_descriptors_conv_16_hu_conv != null) { htlc_descriptors_conv_16_hu_conv.ptrs_to.add(this); };
 222                                 htlc_descriptors_conv_16_arr[q] = htlc_descriptors_conv_16_hu_conv;
 223                         }
 224                         this.htlc_descriptors = htlc_descriptors_conv_16_arr;
 225                         this.tx_lock_time = obj.tx_lock_time;
 226                 }
 227         }
 228         long clone_ptr() {
 229                 long ret = bindings.BumpTransactionEvent_clone_ptr(this.ptr);
 230                 Reference.reachabilityFence(this);
 231                 return ret;
 232         }
 233
 234         /**
 235          * Creates a copy of the BumpTransactionEvent
 236          */
 237         public BumpTransactionEvent clone() {
 238                 long ret = bindings.BumpTransactionEvent_clone(this.ptr);
 239                 Reference.reachabilityFence(this);
 240                 if (ret >= 0 && ret <= 4096) { return null; }
 241                 org.ldk.structs.BumpTransactionEvent ret_hu_conv = org.ldk.structs.BumpTransactionEvent.constr_from_ptr(ret);
 242                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 243                 return ret_hu_conv;
 244         }
 245
 246         /**
 247          * Utility method to constructs a new ChannelClose-variant BumpTransactionEvent
 248          */
 249         public static BumpTransactionEvent channel_close(org.ldk.structs.ChannelId channel_id, byte[] counterparty_node_id, 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) {
 250                 long ret = bindings.BumpTransactionEvent_channel_close(channel_id.ptr, InternalUtils.check_arr_len(counterparty_node_id, 33), InternalUtils.check_arr_len(claim_id, 32), package_target_feerate_sat_per_1000_weight, commitment_tx, commitment_tx_fee_satoshis, anchor_descriptor.ptr, pending_htlcs != null ? Arrays.stream(pending_htlcs).mapToLong(pending_htlcs_conv_24 -> pending_htlcs_conv_24.ptr).toArray() : null);
 251                 Reference.reachabilityFence(channel_id);
 252                 Reference.reachabilityFence(counterparty_node_id);
 253                 Reference.reachabilityFence(claim_id);
 254                 Reference.reachabilityFence(package_target_feerate_sat_per_1000_weight);
 255                 Reference.reachabilityFence(commitment_tx);
 256                 Reference.reachabilityFence(commitment_tx_fee_satoshis);
 257                 Reference.reachabilityFence(anchor_descriptor);
 258                 Reference.reachabilityFence(pending_htlcs);
 259                 if (ret >= 0 && ret <= 4096) { return null; }
 260                 org.ldk.structs.BumpTransactionEvent ret_hu_conv = org.ldk.structs.BumpTransactionEvent.constr_from_ptr(ret);
 261                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 262                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(channel_id); };
 263                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(anchor_descriptor); };
 264                 for (HTLCOutputInCommitment pending_htlcs_conv_24: pending_htlcs) { if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(pending_htlcs_conv_24); }; };
 265                 return ret_hu_conv;
 266         }
 267
 268         /**
 269          * Utility method to constructs a new HTLCResolution-variant BumpTransactionEvent
 270          */
 271         public static BumpTransactionEvent htlcresolution(org.ldk.structs.ChannelId channel_id, byte[] counterparty_node_id, byte[] claim_id, int target_feerate_sat_per_1000_weight, HTLCDescriptor[] htlc_descriptors, int tx_lock_time) {
 272                 long ret = bindings.BumpTransactionEvent_htlcresolution(channel_id.ptr, InternalUtils.check_arr_len(counterparty_node_id, 33), 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.ptr).toArray() : null, tx_lock_time);
 273                 Reference.reachabilityFence(channel_id);
 274                 Reference.reachabilityFence(counterparty_node_id);
 275                 Reference.reachabilityFence(claim_id);
 276                 Reference.reachabilityFence(target_feerate_sat_per_1000_weight);
 277                 Reference.reachabilityFence(htlc_descriptors);
 278                 Reference.reachabilityFence(tx_lock_time);
 279                 if (ret >= 0 && ret <= 4096) { return null; }
 280                 org.ldk.structs.BumpTransactionEvent ret_hu_conv = org.ldk.structs.BumpTransactionEvent.constr_from_ptr(ret);
 281                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 282                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(channel_id); };
 283                 for (HTLCDescriptor htlc_descriptors_conv_16: htlc_descriptors) { if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(htlc_descriptors_conv_16); }; };
 284                 return ret_hu_conv;
 285         }
 286
 287         /**
 288          * Checks if two BumpTransactionEvents contain equal inner contents.
 289          * This ignores pointers and is_owned flags and looks at the values in fields.
 290          */
 291         public boolean eq(org.ldk.structs.BumpTransactionEvent b) {
 292                 boolean ret = bindings.BumpTransactionEvent_eq(this.ptr, b.ptr);
 293                 Reference.reachabilityFence(this);
 294                 Reference.reachabilityFence(b);
 295                 return ret;
 296         }
 297
 298         @Override public boolean equals(Object o) {
 299                 if (!(o instanceof BumpTransactionEvent)) return false;
 300                 return this.eq((BumpTransactionEvent)o);
 301         }
 302 }