1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
7 import java.lang.ref.Reference;
8 import javax.annotation.Nullable;
12 * Represents the different types of transactions, originating from LDK, to be bumped.
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 {
20 if (ptr != 0) { bindings.BumpTransactionEvent_free(ptr); }
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);
27 if (raw_val.getClass() == bindings.LDKBumpTransactionEvent.HTLCResolution.class) {
28 return new HTLCResolution(ptr, (bindings.LDKBumpTransactionEvent.HTLCResolution)raw_val);
30 assert false; return null; // Unreachable without extending the (internal) bindings interface
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.
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.
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.
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
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
74 public final static class ChannelClose extends BumpTransactionEvent {
76 * The unique identifier for the claim of the anchor output in the commitment transaction.
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.
82 public final byte[] claim_id;
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.
87 public final int package_target_feerate_sat_per_1000_weight;
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
93 public final byte[] commitment_tx;
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.
98 public final long commitment_tx_fee_satoshis;
100 * The descriptor to sign the anchor input of the anchor transaction constructed as a
101 * result of consuming this event.
103 public final org.ldk.structs.AnchorDescriptor anchor_descriptor;
105 * The set of pending HTLCs on the commitment transaction that need to be resolved once the
106 * commitment transaction confirms.
108 public final HTLCOutputInCommitment[] pending_htlcs;
109 private ChannelClose(long ptr, bindings.LDKBumpTransactionEvent.ChannelClose obj) {
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;
128 this.pending_htlcs = pending_htlcs_conv_24_arr;
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.
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
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.
159 * [`EcdsaChannelSigner`]: crate::sign::ecdsa::EcdsaChannelSigner
160 * [`EcdsaChannelSigner::sign_holder_htlc_transaction`]: crate::sign::ecdsa::EcdsaChannelSigner::sign_holder_htlc_transaction
162 public final static class HTLCResolution extends BumpTransactionEvent {
164 * The unique identifier for the claim of the HTLCs in the confirmed commitment
167 * The identifier must map to the set of external UTXOs assigned to the claim, such that
168 * they can be reused when a new claim with the same identifier needs to be made, resulting
169 * in a fee-bumping attempt.
171 public final byte[] claim_id;
173 * The target feerate that the resulting HTLC transaction must meet.
175 public final int target_feerate_sat_per_1000_weight;
177 * The set of pending HTLCs on the confirmed commitment that need to be claimed, preferably
178 * by the same transaction.
180 public final HTLCDescriptor[] htlc_descriptors;
182 * The locktime required for the resulting HTLC transaction.
184 public final int tx_lock_time;
185 private HTLCResolution(long ptr, bindings.LDKBumpTransactionEvent.HTLCResolution obj) {
187 this.claim_id = obj.claim_id;
188 this.target_feerate_sat_per_1000_weight = obj.target_feerate_sat_per_1000_weight;
189 long[] htlc_descriptors = obj.htlc_descriptors;
190 int htlc_descriptors_conv_16_len = htlc_descriptors.length;
191 HTLCDescriptor[] htlc_descriptors_conv_16_arr = new HTLCDescriptor[htlc_descriptors_conv_16_len];
192 for (int q = 0; q < htlc_descriptors_conv_16_len; q++) {
193 long htlc_descriptors_conv_16 = htlc_descriptors[q];
194 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); }
195 if (htlc_descriptors_conv_16_hu_conv != null) { htlc_descriptors_conv_16_hu_conv.ptrs_to.add(this); };
196 htlc_descriptors_conv_16_arr[q] = htlc_descriptors_conv_16_hu_conv;
198 this.htlc_descriptors = htlc_descriptors_conv_16_arr;
199 this.tx_lock_time = obj.tx_lock_time;
203 long ret = bindings.BumpTransactionEvent_clone_ptr(this.ptr);
204 Reference.reachabilityFence(this);
209 * Creates a copy of the BumpTransactionEvent
211 public BumpTransactionEvent clone() {
212 long ret = bindings.BumpTransactionEvent_clone(this.ptr);
213 Reference.reachabilityFence(this);
214 if (ret >= 0 && ret <= 4096) { return null; }
215 org.ldk.structs.BumpTransactionEvent ret_hu_conv = org.ldk.structs.BumpTransactionEvent.constr_from_ptr(ret);
216 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
221 * Utility method to constructs a new ChannelClose-variant BumpTransactionEvent
223 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) {
224 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);
225 Reference.reachabilityFence(claim_id);
226 Reference.reachabilityFence(package_target_feerate_sat_per_1000_weight);
227 Reference.reachabilityFence(commitment_tx);
228 Reference.reachabilityFence(commitment_tx_fee_satoshis);
229 Reference.reachabilityFence(anchor_descriptor);
230 Reference.reachabilityFence(pending_htlcs);
231 if (ret >= 0 && ret <= 4096) { return null; }
232 org.ldk.structs.BumpTransactionEvent ret_hu_conv = org.ldk.structs.BumpTransactionEvent.constr_from_ptr(ret);
233 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
234 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(anchor_descriptor); };
235 for (HTLCOutputInCommitment pending_htlcs_conv_24: pending_htlcs) { if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(pending_htlcs_conv_24); }; };
240 * Utility method to constructs a new HTLCResolution-variant BumpTransactionEvent
242 public static BumpTransactionEvent htlcresolution(byte[] claim_id, int target_feerate_sat_per_1000_weight, HTLCDescriptor[] htlc_descriptors, int tx_lock_time) {
243 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);
244 Reference.reachabilityFence(claim_id);
245 Reference.reachabilityFence(target_feerate_sat_per_1000_weight);
246 Reference.reachabilityFence(htlc_descriptors);
247 Reference.reachabilityFence(tx_lock_time);
248 if (ret >= 0 && ret <= 4096) { return null; }
249 org.ldk.structs.BumpTransactionEvent ret_hu_conv = org.ldk.structs.BumpTransactionEvent.constr_from_ptr(ret);
250 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
251 for (HTLCDescriptor htlc_descriptors_conv_16: htlc_descriptors) { if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(htlc_descriptors_conv_16); }; };
256 * Checks if two BumpTransactionEvents contain equal inner contents.
257 * This ignores pointers and is_owned flags and looks at the values in fields.
259 public boolean eq(org.ldk.structs.BumpTransactionEvent b) {
260 boolean ret = bindings.BumpTransactionEvent_eq(this.ptr, b == null ? 0 : b.ptr);
261 Reference.reachabilityFence(this);
262 Reference.reachabilityFence(b);
266 @Override public boolean equals(Object o) {
267 if (!(o instanceof BumpTransactionEvent)) return false;
268 return this.eq((BumpTransactionEvent)o);